Server/Packages/Islands/Registry & code splitting
@sigx/ssr-islands · Stable

Registry & code splitting#

On the client, the islands runtime needs a way to find the component behind each client:* marker. The registry maps component names to factories — eagerly, or lazily for per-island code splitting.

Eager registration#

The simplest setup: import the components and register them by name before calling hydrateIslands().

TypeScript 
import { registerComponent, hydrateIslands } from '@sigx/ssr-islands';
import { Counter } from './components/Counter';

registerComponent('Counter', Counter);
hydrateIslands();

Register several at once with registerComponents — keys become the names:

TypeScript 
import { registerComponents } from '@sigx/ssr-islands';
import * as Components from './components';

registerComponents(Components); // { Counter, Chart, … }

The name you register must match the component name the server serialized into the island data.

Trade-off: eager registration imports every island's code up front, so it is all in the initial bundle — simple, but no code splitting.

Lazy registration & per-island chunks#

To download an island's code only when its strategy fires, register a loader instead of a component. The loader's import() runs on demand:

TypeScript 
import { registerComponentChunk } from '@sigx/ssr-islands/client';

registerComponentChunk('Counter', () => import('./Counter').then((m) => m.Counter));

A client:visible island registered this way downloads its chunk only when it scrolls into view.

You rarely write this by hand. The sigxIslandsPlugin Vite transform generates these registerComponentChunk calls automatically from your islands, keyed by a stable file-path id. Hand-write loaders only for components the transform doesn't cover.

Resolution order#

When an island needs its component, the runtime resolves it in order:

  1. Eager registry — already loaded via registerComponent.
  2. Lazy registry — registered via registerComponentChunk.
  3. Direct chunk URL — from the SSR manifest (IslandInfo.chunkUrl), see Plugin setup.

loadIslandComponent(info) runs this full resolution (with in-flight dedup); resolveComponent(name) checks the eager then lazy registries and caches the result for instant subsequent lookups.

Prefetching#

For deferred islands, warm the browser cache early with <link rel="modulepreload"> so the chunk is ready before the strategy fires:

TypeScript 
import { prefetchIslandChunks, getIslandData } from '@sigx/ssr-islands';

// On DOMContentLoaded — prefetch all deferred islands' chunks
prefetchIslandChunks(getIslandData());

Pass a list of strategies to limit which islands are prefetched (default: all deferred strategies).

The registry class#

For advanced cases, HydrationRegistry is the class behind the module-level helpers — useful when you want an isolated registry instance:

TypeScript 
import { HydrationRegistry } from '@sigx/ssr-islands';
import { Counter } from './components/Counter';

const registry = new HydrationRegistry()
    .register('Counter', Counter)
    .registerLazy('Chart', () => import('./Chart').then((m) => m.Chart));

await registry.resolve('Chart'); // ComponentFactory | undefined

Next steps#