@exactjs/hydrate

Browser hydration and server-response patching for eXact applications.

Overview

The package adopts HTML produced by @exactjs/ssr, activates compiler-generated client islands, and coordinates authorized server operations and validated patches through one root-scoped client. It preserves the component and operation identities generated by the compiler without exposing the underlying transport or patch-authority machinery.

Usage

import { createExactClient } from '@exactjs/hydrate';

const client = createExactClient(document.getElementById('app')!, {
	islands
});

Eligible interaction-only islands remain inert until their first supported event. Set hydration: { strategy: 'eager' } when an application needs all eligible islands activated immediately.

Hydrate the same compiled application that produced the server output. Server endpoints remain responsible for authorization, CSRF policy, payload limits, and operation allowlists.

Generated enhancement modules register their bundle-local providers and hydration support automatically. Hydration adopts compatible authored DOM first, then activates those ordinary enhancement components against the adopted targets. A low-level integration that manually passes HydrateOptions.enhancementCatalog must import hydrate from @exactjs/hydrate/enhanced so the synchronous enhancement host is installed before adoption.

Applications with ordinary browser-owned service calls and no compiler-generated server operations, response patches, or client islands can select the hydration-only entry:

import { hydrate } from '@exactjs/hydrate/root';

const root = hydrate(app, document.getElementById('app')!);

When SSR uses publishRootProps: true, construct the client root from the same bounded bootstrap record instead of shipping a second application-data script:

const container = document.getElementById('app')!;
hydrateAfterNavigation(() => {
	const props = readPublishedRootProps<AppProps>(App, container);
	return <App {...props} />;
}, container);

Passing the compiled root binds any compiler-proven compact positional payload to the matching client artifact. Named payloads from older or structurally open roots remain supported. The later hydration call reuses the same decoded object graph.

hydrateAfterNavigation() accepts an element or the executing window's current document. After DOMContentLoaded, visible documents get one rendering opportunity before activation is scheduled; hidden documents use a task directly. An earlier pointer, keyboard, input, change, or submit event activates the root synchronously before target and bubble handlers. Failure removes pending hooks and rejects without retry. Hydrate embedded documents from their own window's runtime.

Because that static entry does not expose the optional capabilities, bundlers can remove their implementations completely. Use the main entry whenever the compiled application contains server operations, patch refreshes, or islands.

Use ExactClient.applyPatches() only for framework integrations that deliberately apply validated patches within that client's root. Direct transport invocation and unscoped patch application are package-private implementation details.

A synchronous factory passed to hydrateAfterNavigation() defers published-props decoding and root creation until activation. The factory runs once, including when an early interaction wins, and a thrown error rejects the hydration promise. Existing root values remain supported. This does not defer static module evaluation or guarantee that first contentful paint precedes activation.

See SSR and hydration and component registries.

Documentation | Source on GitHub