@magnet/hydrate

DOM adoption for Magnet hydration.

@magnet/hydrate provides a deterministic-order cursor and hydrating document/window facades that serve existing DOM nodes from a server-rendered tree instead of creating new ones. This enables DOM-adopting hydration: reusing server-rendered nodes instead of replacing them with a fresh render.

Install

JSR

deno add jsr:@magnet/hydrate

npm via JSR

npx jsr add @magnet/hydrate

npm

npm install @magnet-js/hydrate

Usage

import { hydrationWindow } from "@magnet/hydrate";
import { magnet } from "@magnet/ui";
import { tc39 } from "@magnet/signal";

const m = magnet({ window: hydrationWindow(window, islandElement), ...tc39 });

// The render pipeline now adopts existing nodes from the server tree
// instead of creating new ones.

While the cursor over the server tree has nodes, each node request is served from the tree; on any mismatch (wrong tag, missing node, wrong text) an "adoption mismatch" error is thrown and the caller should fall back to fresh render. Once the cursor is exhausted — hydration complete — the facades delegate to the real document, so reactive updates after hydration create fresh nodes as usual.

Public API

• hydrationDoc(window, element) — creates a document facade that adopts element's server tree, then delegates to the real document.
• hydrationWindow(window, element) — creates a minimal window facade whose document is the hydrating document. Only document is provided; Magnet's render pipeline needs nothing else.

License

MIT © 2026 Fernando G. Vilar.