SSR & Hydration
Dathra SSR renders registered Web Components to Declarative Shadow DOM and hydrates them after the browser has parsed that DSD into real shadow roots. The server and client both use the same component definitions.
For exact SSR and hydration signatures, see the Core SSR API Referenceand Core Hydration API Reference.
Server Entry
The server entry is a typed request handler. It receives request context, chooses the route state, and returns the HTML for a root component:
import { defineSsrEntry, render } from "@dathra/core/ssr";
import { AppRoot } from "./AppRoot";
const handler = defineSsrEntry(async ({ request }) => {
const routePath = new URL(request.url).pathname;
return {
html: render(AppRoot, { routePath }),
statusCode: routePath === "/missing" ? 404 : 200,
};
});
export default handler;Root Component
The root component receives server-provided props as signals. On the server, returning JSX produces HTML inside the DSD template. On the client, the same definition upgrades the custom element.
import { defineComponent } from "@dathra/components";
const AppRoot = defineComponent(
"app-root",
({ props }) => {
return <main>Route: {props.routePath.value}</main>;
},
{
props: {
routePath: { type: String, default: "/" },
},
},
);
export { AppRoot };Client Hydration
import { hydrate } from "@dathra/core/hydration";
void import("./AppRoot").then(() => {
queueMicrotask(() => {
hydrate(document);
});
});Hydration Behavior
Dathra treats server-rendered Declarative Shadow DOM as the source of truth during upgrade. Supported compiler-generated hydration plans connect bindings in place; unsupported DSD keeps its existing DOM instead of being replaced.
const AppRoot = defineComponent(
"app-root",
({ props }) => <main>{props.routePath.value}</main>,
{
props: {
routePath: { type: String, default: "/" },
},
},
);Usehydration.unsupported: "rerender"only when a component must discard SSR
DOM and rebuild itself on the client.
Islands Architecture
Components can be marked withclient:*directives for selective hydration.
Directives are written as JSX props on Dathra components:
<hero-banner />
<cart-summary client:visible />
<search-box client:interaction="input" />
<desktop-nav client:media="(min-width: 768px)" />client:visible— hydrate when visible (IntersectionObserver)client:idle— hydrate when the browser is idleclient:interaction— hydrate on user interactionclient:media="(min-width: 768px)"— hydrate when media matchesclient:load— hydrate immediately on load
Interaction Replay
When usingclient:interaction, user interactions before hydration are captured
and replayed after the component hydrates. Supported events includeonClick, onKeydown, andonPointerdown.
Hydration Plan
The hydration system usesplanFactoryto generate a hydration plan from the
server-rendered DOM. The plan describes which nodes to hydrate, what strategies to use, and
how to handle nested islands.
Most applications should usehydrate(document)from @dathra/core/hydration. Lower-level hydration APIs are for runtime integrations
and advanced testing.