Askr
Renderinglimited

Selective Hydration

Use selective hydration with the current published Askr packages.

  • @askrjs/askr0.0.59

How to use selective hydration

The published runtime does not expose a separate selective-hydration boundary. Hydrate the deterministic application tree with hydrateSPA; split independently loaded behavior with routes and lazy modules instead of inventing a boundary API.

  1. Import the published @askrjs/askr entrypoint.
  2. Keep selective 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 { hydrateSPA } from '@askrjs/askr/boot';

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

Boundary selection

Selective hydration is driven by the same `hydrate` options on `HydrateSPAConfig` as ordinary hydration — there's no separate boundary-marking API. `deferBelowFold` is the closest thing to boundary selection: it treats anything below `foldThreshold` as deferrable, so what counts as a "boundary" is a viewport position rather than an explicit annotation in your component code. Treat this as an early, limited feature rather than a full partial-hydration system.

Priority

`deferUntilIdle` schedules hydration work for the browser's idle time, giving above-the-fold interactivity implicit priority over everything scheduled later. There's no per-component priority level beyond idle-vs-not and fold-position — if you need finer-grained control today, you'll likely need to split the page into separate islands with `createIsland` instead of relying on this option set.

Interaction activation

Deferred regions still hydrate eagerly once idle time arrives or the fold threshold is crossed; nothing in the current API ties hydration to a user interaction like a click or hover. If you need hydrate-on-interaction behavior specifically, it isn't part of `hydrate` today — you'd have to build it on top with `createIsland` and your own trigger.

Fallback behavior

Because `verifyMarkup` and the defer options are independent settings, a deferred region can still fail markup verification once it does hydrate, and that failure is reported the same way as an immediate hydration mismatch. There's no separate fallback UI mechanism for selective hydration beyond what plain hydration already gives you — plan for the same mismatch diagnostics, just arriving later.