@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