Askr
Rendering

Hydration

Use hydration with the current published Askr packages.

  • @askrjs/askr0.0.59

How to use hydration

Keep the route tree shared and change the delivery adapter—not the component contract—when moving between client, server, and static rendering.

  1. Import the published @askrjs/askr entrypoint.
  2. Keep hydration configuration next to the component, route, or server composition root that owns it.
  3. Handle pending, unavailable, cancellation, and failure states, then verify the production path.
import { createSPA, hydrateSPA } from '@askrjs/askr/boot';

const root = document.getElementById('app')!;
if (root.childNodes.length) {
  await hydrateSPA({ root, registry });
} else {
  await createSPA({ root, registry });
}

Adopt server markup

`hydrateSPA` (from `@askrjs/askr/boot`) attaches the client runtime to HTML that a server already rendered, given the same `root`, `manifest`/`registry`/`routes` route source used elsewhere, plus an optional `dataRuntime` for reusing server-fetched data on the client. It's the counterpart to `createSPA`: `createSPA` builds the DOM from scratch, `hydrateSPA` claims DOM that's already there.

Deterministic first render

SSR and hydration share a numeric `seed` (see `createRenderContext(seed, ...)` and `renderToStringSync`'s `seed` option) so that keys and internal ordering generated during server render can be reproduced exactly on the client. Without matching seeds, the client's first pass could generate different keys than the server did, and hydration would treat identical markup as mismatched.

Event attachment

Hydration walks the existing DOM tree and attaches event listeners to the elements the component tree expects, rather than replacing nodes outright. `hydrate.deferUntilIdle` and `hydrate.deferBelowFold` (with `foldThreshold`) on `HydrateSPAConfig` let you push that listener attachment to idle time or until an element scrolls into view, trading immediate interactivity for less main-thread work at load.

Mismatch diagnostics

Set `hydrate: { verifyMarkup: true }` on `hydrateSPA` to have it check server-rendered markup against what the client would produce before attaching to it, surfacing a mismatch instead of silently adopting the wrong structure. `hydrate.skipSelectors` lets you exclude known-divergent regions (third-party widgets, ads) from that check so they don't produce false positives.