Hydration

Why the step exists at all

Prerendered or server-rendered HTML looks finished but is inert: buttons do nothing, menus do not open, form validation is absent. The framework needs to rebuild its component tree in the browser and connect it to the DOM nodes that already exist. That connection is hydration.

It creates a window that is easy to miss in development and obvious on a mid-range phone: the page is visible but not usable. Text is readable, layout is correct, and taps are either ignored or queued until the bundle has downloaded, parsed and executed. The bigger the bundle, the longer the window — and it shows up directly in Interaction to Next Paint.

Hydration mismatch

If the HTML the browser received does not match what the framework renders on the client, you get a mismatch. React logs a warning and, in recent versions, re-renders the affected subtree; the visible symptom is content that flashes or shifts a moment after load.

The usual causes are predictable once you know them:

• new Date(), Math.random() or anything else that differs between build and run.
• Reading window, localStorage or user agent during the first render.
• Content that depends on locale or timezone resolved differently on the server than in the browser.

The fix is to render the same neutral output on both sides and move the browser-specific part into an effect that runs after hydration.

Ways around it

Frameworks have spent years reducing the cost. Partial hydration or islands architecture, used by Astro, hydrates only the components that genuinely need interactivity and leaves the rest as plain HTML. Progressive hydration defers components until they scroll into view. Server components in React push work back to the server so less code ships at all.

The misconception worth naming: hydration is not what makes a page appear. The page appears from the HTML; hydration only makes it respond. A site that renders instantly and reacts slowly has a hydration cost, not a rendering problem.