@seithr/islands

Selective hydration island architecture, cross-island communication bus, and client directives for Seithr.

Overview

@seithr/islands enables partial and progressive hydration for server-rendered Seithr applications. By isolating interactive components into self-contained "islands", the majority of the page remains pure static HTML, significantly decreasing JavaScript payload size and Total Blocking Time (TBT).

Installation

bun add seithr
# or using npm
npm install seithr

Features

• Selective Hydration Directives:
  • client:load: Hydrates the island component immediately upon page arrival.
  • client:idle: Defers island hydration until the browser main thread is idle (requestIdleCallback).
  • client:visible: Uses IntersectionObserver to hydrate the island only when scrolled into the active viewport.
  • client:media: Hydrates when a specific CSS media query evaluates to true.
  • client:interaction: Hydrates upon first user interaction (pointerdown, focusin, keydown, etc.).
• Cross-Island Message Bus:
  • islandBus: Decoupled pub/sub event bus enabling isolated client islands to communicate seamlessly without requiring a shared global client-side framework root.

Usage

import { createIsland, hydrateIslands, islandBus } from "seithr/islands"

// Define an interactive island component
const InteractiveCart = createIsland(
  (props: { initialCount: number }) => {
    return (
      <div>
        <span>Items in cart: {props.initialCount}</span>
        <button onClick={() => islandBus.publish("checkout:requested", { count: props.initialCount })}>
          Checkout
        </button>
      </div>
    )
  },
  { id: "CartWidget", name: "CartWidget", strategy: "visible" },
)

// Hydrate all declared islands on the client
if (typeof window !== "undefined") {
  hydrateIslands()
}