Server-Rendered Hydration
Hydration attaches event listeners and framework state to server-rendered HTML so the page becomes interactive without re-rendering, requiring client and server markup to match exactly.
Definition
Hydration is the process of bringing server-rendered static HTML to life: the client framework walks the existing DOM, attaches event handlers, links component state, and adopts the tree as its own. It avoids re-creating nodes already shipped in HTML. Mismatches between server and client render output cause warnings, discarded nodes, or full client re-render.
Context and scope
Every SSR framework on interactive pages: initial HTML for fast paint, hydration for interactivity. Islands architecture and streaming hydration reduce the cost by hydrating only what needs interactivity.
Common misconceptions
- Hydration is free because HTML already exists — walking and binding a large tree costs main-thread time proportional to page size
- A hydration mismatch always repairs itself — it discards server nodes and re-renders, erasing the SSR benefit for that subtree
- Hydration makes the page interactive — it makes it eventually interactive; the bound tree is interactive only when hydration completes
Anti-patterns
- Rendering timestamps, locale formats, or random values differently on server and client and triggering mismatch cascades
- Shipping a full framework runtime to hydrate a mostly-static marketing page
- Blocking on the entire bundle before any hydration instead of streaming or island-scoping interactive regions
Related concepts
Related examples
Authoritative source
What it is
Server rendering produces pixels fast; interactivity needs listeners and state attached to that DOM. Hydration is the attach step: the framework re-executes components against existing nodes rather than creating them. The user sees content before JavaScript finishes, and can interact after.
How it works
The client walks the DOM in the same order the server rendered it, asserting node-by-node equality with what it would have produced. Valid attributes and content adopt existing nodes; discrepancies re-render client-side. Selective and progressive hydration prioritize visible or interactive regions first; islands skip the rest entirely.
When to care
Any site needing both fast first paint and interactivity. Static-heavy pages benefit from islands or zero-JS; app-like pages accept full hydration because most of the tree is interactive anyway. Time-to-interactive and interaction latency are the metrics that move.
Pitfalls
Date formatting, browser-only APIs, and feature flags differing per environment are the classic mismatch sources. Double-rendering during hydration wastes the server work. Third-party scripts that mutate the DOM before hydration complete can invalidate assumptions the framework holds about its own tree.