Skip to main content

Island Architecture in Archibald

Archibald treats the page as a collection of Islands. The global application shell provides routing and global state while individual interactive blocks remain dormant until triggered.

What is an "Island"?​

In Archibald, an Island is any CMS component that is:

  • Registered: Added to the CMSRegistry with hydration metadata.
  • Wrapped: Automatically wrapped in the withHydration (or withComponentHydration) HOC during registration.

The Role of CMSRegistry​

The CMSRegistry in @archibald/storefront is the orchestrator. When a component is registered, the registry checks for a hydrate property. Its type discriminator ('default' | 'component') decides which HOC wraps the component: 'default' uses withHydration, 'component' uses withComponentHydration.

// Defining an Island
CMSRegistry.register('MyCarousel', CarouselComponent, {
    hydrate: {
        type: 'default', // 'default' -> withHydration, 'component' -> withComponentHydration
        options: {
            hydrationTrigger: 'visible',
            height: '400px'
        }
    }
});

If no metadata is given, the registry falls back to { type: 'default', options: { hydrationTrigger: 'visible' } }.

Rendering registered Islands​

When a page is rendered, the CMS rendering layer looks up each block's typeCode in the CMSRegistry. If the component has hydration metadata, the version already wrapped in the hydration HOC is rendered — the server emits the island's markup and container, and the client hydrates it when its trigger fires (see Decision Logic).