API reference#

Every public export of @sigx/ssr-islands v0.4.2. The main entry re-exports the server and client surfaces; /server, /client and /jsx are the split entry points.

Server plugin#

islandsPlugin#

Create the islands SSRPlugin. Register it on an SSR instance with .use(). Server-side it intercepts client:* components, tracks signal state, manages async streaming, and injects __SIGX_ISLANDS__; client-side it schedules deferred hydration.

function islandsPlugin(options?: IslandsPluginOptions): SSRPlugin

• Exported from the main entry.

IslandsPluginOptions#

interface IslandsPluginOptions {
  strategies?: Record<string, (el: Element, hydrate: () => void) => void>;
  manifest?: Record<string, { chunkUrl: string; exportName: string }>;
}

• strategies — custom client-side hydration strategies, keyed by name.
• manifest — component → chunk-URL map (generated by @sigx/vite's sigxIslandsPlugin()); enables on-demand chunk loading without eager registration.
• Exported as a type from the main entry.

Client hydration#

hydrateIslands#

Hydrate the page's islands according to their client:* strategies (selective hydration). Call once after registering components.

function hydrateIslands(): void

scheduleComponentHydration#

Schedule one component's hydration for the given strategy; returns the next DOM node after the component's content. Used internally by the plugin's hydration walk.

function scheduleComponentHydration(
  vnode: VNode, dom: Node | null, parent: Node,
  strategy: { strategy: 'load' | 'idle' | 'visible' | 'media' | 'only'; media?: string },
): Node | null

initIslandHydration#

Initialize island hydration with context accessors from the server renderer (getCurrentAppContext / setCurrentAppContext / setPendingServerState). Called by the plugin during setup.

function initIslandHydration(fns: {
  getCurrentAppContext: () => any;
  setCurrentAppContext: (ctx: any) => void;
  setPendingServerState: (state: Record<string, any> | null) => void;
}): void

cleanupPendingHydrations#

Tear down all pending deferred-hydration observers/listeners. Call on SPA navigation to prevent IntersectionObserver / matchMedia leaks for islands that have not triggered yet.

function cleanupPendingHydrations(): void

invalidateMarkerIndex#

Invalidate the cached island-marker index — call when the DOM changes (e.g. after async component streaming) so the next hydration re-scans.

function invalidateMarkerIndex(): void

hydrateLeftoverAsyncComponents#

Hydrate async island components that streamed in after the initial walk.

function hydrateLeftoverAsyncComponents(): void

Component registry#

registerComponent / registerComponents#

Register island components eagerly by name, before hydrateIslands().

function registerComponent(name: string, component: ComponentFactory): void
function registerComponents(components: Record<string, ComponentFactory>): void

__registerIslandChunk#

Register a lazy island loader for code-split hydration; the loader's import() runs only when the island's strategy triggers. Normally emitted automatically by the sigxIslandsPlugin Vite transform.

function __registerIslandChunk(name: string, loader: LazyComponentLoader): void

resolveComponent / getComponent / hasComponent#

Resolve a component by name — resolveComponent checks eager then lazy (async, cached, deduped); getComponent is sync (eager only); hasComponent reports availability in either registry.

function resolveComponent(name: string): Promise<ComponentFactory | undefined>
function getComponent(name: string): ComponentFactory | undefined
function hasComponent(name: string): boolean

HydrationRegistry#

The class behind the module-level helpers, for isolated registry instances.

class HydrationRegistry {
  register(name: string, component: ComponentFactory): this;
  registerLazy(name: string, loader: LazyComponentLoader): this;
  registerAll(components: Record<string, ComponentFactory>): this;
  get(name: string): ComponentFactory | undefined;
  has(name: string): boolean;
  resolve(name: string): Promise<ComponentFactory | undefined>;
}

ComponentFactory / LazyComponentLoader#

interface ComponentFactory {
  __setup: Function;
  __name?: string;
  __islandId?: string;   // stable file-path identity (injected by the Vite plugin)
  __async?: boolean;
}
type LazyComponentLoader =
  () => Promise<ComponentFactory | { default: ComponentFactory; [key: string]: any }>;

• Exported as types from the main entry and /client.

Chunk loading#

loadIslandComponent#

Resolve an island's component across all paths (eager registry → lazy registry → direct chunk URL from the manifest), with in-flight dedup.

function loadIslandComponent(info: IslandInfo): Promise<ComponentFactory | undefined>

prefetchIslandChunks#

Warm the browser cache with <link rel="modulepreload"> for deferred islands.

function prefetchIslandChunks(islands: Record<string, IslandInfo>, strategies?: string[]): void

Island data (client)#

getIslandData / getIslandServerState / invalidateIslandCache#

Read the parsed __SIGX_ISLANDS__ data, look up a rendered component's captured server state by its numeric render id, or invalidate the cached island data.

function getIslandData(): Record<string, IslandInfo>
function getIslandServerState(componentId: number): Record<string, any> | undefined
function invalidateIslandCache(): void

The componentId parameter here is the numeric id assigned to a component during render — not IslandInfo.componentId, which is a separate string identifier (path- or name-based) used to resolve the component on the client.

Server utilities#

createTrackingSignal / serializeSignalState#

Capture signal names + values during async setup, then serialize them for client hydration. Exported from the main entry and /server.

function createTrackingSignal(signalMap: Map<string, any>): SSRSignalFn
function serializeSignalState(signalMap: Map<string, any>): Record<string, any> | undefined

generateIslandDataScript#

Generate the __SIGX_ISLANDS__ hydration-data script for a set of islands.

function generateIslandDataScript(islandData: Record<number, IslandInfo>): string

Types#

IslandInfo#

The per-island record serialized from server to client.

interface IslandInfo {
  strategy: HydrationStrategy;
  media?: string;
  props?: Record<string, any>;
  componentId?: string;
  state?: Record<string, any>;   // captured signal state
  placeholder?: string;          // streaming async placeholder HTML
  chunkUrl?: string;             // for lazy loading
  exportName?: string;
}

HydrationStrategy#

type HydrationStrategy = 'load' | 'idle' | 'visible' | 'media' | 'only';

ClientDirectives#

The JSX attributes (also available type-only via @sigx/ssr-islands/jsx).

interface ClientDirectives {
  'client:load'?: boolean;
  'client:idle'?: boolean;
  'client:visible'?: boolean;
  'client:media'?: string;
  'client:only'?: boolean;
}

PendingAsyncComponent / HydrationOptions#

PendingAsyncComponent describes an in-flight async island (id, HTML promise, captured signalMap, islandInfo); HydrationOptions carries recover and an onMismatch callback. Both exported as types.

Re-exports#

For convenience the package re-exports, from @sigx/server-renderer:

• generateSignalKey — the shared server/client serialization-key function.
• types SSRSignalFn and SSRHelper.

JSX subpath#

@sigx/ssr-islands/jsx is a types-only entry. Importing it augments JSX so the client:* attributes type-check:

import '@sigx/ssr-islands/jsx';

<Counter client:visible />;