@servlyadmin/runtime-vue

@servlyadmin/runtime-vue

Vue 3 wrapper for Servly runtime renderer. Render Servly components in your Vue applications with full slot support, state management, and reactive updates.

Installation

npm install @servlyadmin/runtime-vue
# or
yarn add @servlyadmin/runtime-vue
# or
pnpm add @servlyadmin/runtime-vue

Requirements

• Vue 3.0.0 or higher
• @servlyadmin/runtime-core (installed automatically)

Quick Start

<template>
  <!-- That's it! Components are fetched from Servly's registry automatically -->
  <ServlyComponent
    id="my-component-id"
    :props="{ title: 'Hello World' }"
  />
</template>

<script setup lang="ts">
import { ServlyComponent } from '@servlyadmin/runtime-vue';
</script>

Registry & Caching

Default Registry

Components are fetched from Servly's production registry by default:

• URL: https://core-api.servly.app/v1/views/registry

To use a custom registry:

import { setRegistryUrl } from '@servlyadmin/runtime-vue';

setRegistryUrl('https://your-api.com/v1/views/registry');

Cache Strategies

The runtime supports three caching strategies:

Strategy	Description	Persistence	Best For
localStorage	Persists across browser sessions	Yes	Production (default)
memory	In-memory cache, cleared on refresh	No	Development, SSR
none	No caching, always fetches fresh	No	Testing, debugging

<template>
  <!-- Default: localStorage caching -->
  <ServlyComponent id="my-component" />

  <!-- Explicit cache strategy -->
  <ServlyComponent id="my-component" cache-strategy="memory" />

  <!-- No caching -->
  <ServlyComponent id="my-component" cache-strategy="none" />
</template>

API Reference

ServlyComponent Props

Prop	Type	Default	Description
id	string	required	Component ID from the registry
version	string	'latest'	Version specifier (exact, range, or "latest")
props	object	{}	Props to pass to the component
cacheStrategy	'localStorage' | 'memory' | 'none'	'localStorage'	Caching strategy
retryConfig	object	undefined	Retry configuration for failed fetches
eventHandlers	object	undefined	Event handlers keyed by element ID
showSkeleton	boolean	true	Show loading skeleton
enableStateManager	boolean	false	Enable built-in state management
initialState	object	undefined	Initial state for state manager

Events

Event	Payload	Description
load	ComponentData	Emitted when component loads successfully
error	Error	Emitted when component fails to load
stateChange	StateChangeEvent	Emitted when state changes (if enabled)
ready	void	Emitted when component is fully rendered

Slots

<template>
  <ServlyComponent id="my-component">
    <!-- Custom loading state -->
    <template #fallback>
      <div>Loading...</div>
    </template>
    
    <!-- Custom error state -->
    <template #error="{ error, retry }">
      <div>
        <p>Error: {{ error.message }}</p>
        <button @click="retry">Retry</button>
      </div>
    </template>
    
    <!-- Named slots for component content -->
    <template #header>
      <h1>Custom Header</h1>
    </template>
    
    <template #footer>
      <p>Custom Footer</p>
    </template>
  </ServlyComponent>
</template>

Advanced Usage

With State Management

<template>
  <ServlyComponent
    id="counter-component"
    :props="{ count }"
    enable-state-manager
    :initial-state="{ count: 0 }"
    @state-change="onStateChange"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { ServlyComponent } from '@servlyadmin/runtime-vue';

const count = ref(0);

const onStateChange = (event) => {
  if (event.key === 'count') {
    count.value = event.value;
  }
};
</script>

With Event Handlers

<template>
  <ServlyComponent
    id="form-component"
    :event-handlers="handlers"
  />
</template>

<script setup lang="ts">
import { ServlyComponent } from '@servlyadmin/runtime-vue';

const handlers = {
  'submit-btn': {
    click: (event) => {
      console.log('Button clicked!', event);
    },
  },
  'email-input': {
    change: (event) => {
      console.log('Email changed:', event.target.value);
    },
  },
};
</script>

Accessing Component Instance

<template>
  <ServlyComponent
    ref="servlyRef"
    id="my-component"
  />
  <button @click="reload">Reload</button>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { ServlyComponent } from '@servlyadmin/runtime-vue';

const servlyRef = ref();

const reload = () => {
  servlyRef.value?.reload();
};

// Other exposed methods:
// servlyRef.value?.getSlotElement('header')
// servlyRef.value?.getSlotNames()
// servlyRef.value?.getStateManager()
// servlyRef.value?.update({ newProp: 'value' })
</script>

Version Specifiers

<template>
  <!-- Exact version -->
  <ServlyComponent id="my-component" version="1.2.3" />
  
  <!-- Caret range (compatible with) -->
  <ServlyComponent id="my-component" version="^1.0.0" />
  
  <!-- Tilde range (approximately) -->
  <ServlyComponent id="my-component" version="~1.2.0" />
  
  <!-- Latest version (default) -->
  <ServlyComponent id="my-component" />
</template>

TypeScript Support

Full TypeScript support is included:

import type {
  ServlyComponentProps,
  BindingContext,
  ComponentData,
  StateChangeEvent,
} from '@servlyadmin/runtime-vue';

Re-exported Utilities

For convenience, common utilities are re-exported:

import {
  // Fetching
  fetchComponent,
  prefetchComponents,
  setRegistryUrl,
  DEFAULT_REGISTRY_URL,
  
  // Caching
  invalidateCache,
  clearAllCaches,
  
  // State management
  StateManager,
  
  // Event system
  EventSystem,
  getEventSystem,
} from '@servlyadmin/runtime-vue';

License

MIT