---
title: "Hydration"
description: "How Radiant and JSX hydration work, including the explicit client hydrator contract for SSR pages."
order: 2
---

# Hydration

Hydration is the client attach step for HTML that was already rendered on the server.

The important distinction is:

- SSR produces HTML.
- hydration attaches behavior to that existing HTML.
- a normal client render replaces that HTML with a fresh DOM tree.

Radiant makes that boundary explicit for render-owning `RadiantElement` hosts.

## Two Hydration Models

There are two related but different hydration flows in this ecosystem.

### Plain JSX hydration

Use the `@ecopages/jsx` client APIs when you are hydrating a normal container element.

```tsx
/** @jsxImportSource @ecopages/jsx */

import { createRoot } from '@ecopages/jsx';
import { renderToString } from '@ecopages/jsx/server';

function App() {
	return <button on:click={() => console.log('clicked')}>Ship</button>;
}

const html = renderToString(<App />, { mode: 'hydrate' });

const container = document.querySelector('#app');

if (container instanceof HTMLElement) {
	createRoot(container).hydrate(<App />);
}
```

That flow only cares about JSX hydration markers inside a normal target element.

### Radiant host hydration

Use the explicit Radiant hydrator when the server rendered a custom-element host such as `<my-card>...</my-card>` through a render-owning `RadiantElement`.

That flow has one extra rule: the component hydrates in place only when both of these are true on first connect:

1. the host was server-rendered in hydrate mode, or already contains hydration markers
2. the explicit Radiant hydrator has been installed on the client

If either condition is missing, the host falls back to a fresh client render.

A render-owning host inside another host's view hydrates with its parent: the parent keeps the nested host's server node, binds its attributes and properties, and hands it the JSX children from its view, and the nested host then hydrates its own view. Its state, focus and typed input survive, and `isServerRendered` is `true`. Define the parent host on the client too, since the nested host gets its children only from the parent's view and waits for them to hydrate. Until then it is inert server markup: it has no event bindings, and `onConnected()` and `updated()` run only once it hydrates, never if its parent does not render on the client. The order in which the two tags are defined does not matter. A custom element that is not a render-owning `RadiantElement`, or whose tag is defined only after the parent hydrated, is rendered again by the parent instead.

## The Radiant Contract

For a hydratable render-owning `RadiantElement` page today, you need three pieces.

### 1. Server-side Radiant SSR runtime

The server render path must import an explicit server entrypoint so the shared SSR runtime is registered.

For adapters, import `@ecopages/radiant/server/install-ssr-runtime` once at server boot (or import `@ecopages/radiant/server/render-component`, which installs it as a side effect). When bundler order is uncertain, prefer the explicit `install-ssr-runtime` import first:

```ts
import '@ecopages/radiant/server/install-ssr-runtime';
```

In application code, the higher-level server helpers under `@ecopages/radiant/server/render-component` are the preferred API.

### 2. Hydrated server markup

The server render must emit hydration markers.

For JSX this means:

```ts
renderToString(view, { mode: 'hydrate' });
```

For render-owning `RadiantElement` hosts this usually means one of:

- `renderComponent(...)` / `renderComponentToString(...)` from `@ecopages/radiant/server/render-component`
- `renderRadiantElementHostToString(...)` from `@ecopages/radiant/server/radiant-element-ssr` when you need the host string directly
- `renderRadiantElementViewToString(element, { mode: 'hydrate' })` from `@ecopages/radiant/server/radiant-element-ssr` when you need the prepared view fragment without the host tag

### 3. Explicit client hydrator install

Install the client hydrator before component modules load:

```ts
import '@ecopages/radiant/client/install-hydrator';
```

Or, if you want explicit bootstrap control:

```ts
import { installRadiantHydrator } from '@ecopages/radiant/client/hydrator';

installRadiantHydrator();
```

This sets the global hydration gate that Radiant checks on first connect for render-owning hosts.

## What Happens On First Connect

When the browser upgrades a server-rendered render-owning `RadiantElement` host, the runtime does this:

1. wait one microtask after `connectedCallback()`
2. check whether the host was server-rendered or contains hydration markers
3. check whether the explicit hydrator is installed
4. if both are true, call `hydrate()` and reconnect listeners and bindings in place
5. otherwise call `update()` and mount a fresh client render

```mermaid
flowchart TD
  Upgrade[Browser upgrades the host] --> Wait[Wait one microtask after connectedCallback]
  Wait --> Server{Server-rendered or hydration markers?}
  Server -- no --> Update[update: mount a fresh client render]
  Server -- yes --> Installed{Hydrator installed?}
  Installed -- no --> Update
  Installed -- yes --> Hydrate[hydrate: reconnect listeners and bindings in place]
```

That last fallback is intentional. It means a page can still work without the hydrator import, but it will stop preserving the exact SSR DOM tree.

## When You Need The Hydrator

Install the explicit hydrator when:

- the server emitted render-owning `RadiantElement` markup with `mode: 'hydrate'`
- you want to preserve the SSR DOM in place on first connect
- you want server-emitted event and property bindings to reconnect without replacing nodes

You do not need it for:

- client-only pages
- plain `@ecopages/jsx` containers that hydrate through `createRoot(...).hydrate(...)`
- pages where a fresh client rerender is acceptable

## What If You Omit It

If you omit the Radiant hydrator import:

- the page can still become interactive
- render-owning hosts fall back to a fresh client render
- SSR nodes may be replaced instead of being hydrated in place

So this is not usually a catastrophic failure. It is a hydration-semantics regression, not necessarily a visible blank-page failure.

## Context And Signal Hydration

Hydration scripts for providers and signals still depend on server-rendered markup being present under the host.

That means the safest path for SSR pages is:

- use the Radiant server helpers to emit host markup
- install the explicit client hydrator before component modules load

This keeps host HTML, hydration markers, context payloads, and signal payloads on one coherent path.

## Recommended Mental Model

Use this rule of thumb:

- `@ecopages/jsx` owns container-level hydration.
- `@ecopages/radiant` owns host-level hydration for render-owning `RadiantElement` custom elements.
- Radiant host hydration is explicit on the client.

## Related Guides

- [RadiantElement](/docs/components/radiant-element) for the component-host lifecycle
- [JSX Client Rendering](/docs/jsx/rendering) for container-level client rendering and hydration
- [JSX SSR](/docs/ssr/jsx-ssr) for server-side HTML generation and marker emission
- [Provide Context](/docs/context/provide-context) for provider hydration payloads inside SSR hosts
