What Is Hydration? Making Server HTML Interactive
Hydration is the step where client-side JavaScript attaches to already-rendered HTML, turning a static server-rendered page into an interactive app.
With SSR or SSG, the browser first receives finished HTML it can display immediately. But that HTML has no behavior yet. Hydration is the process where the JavaScript framework walks the existing DOM, reconnects its component tree to it, and wires up event handlers. Get it wrong and you get the dreaded hydration mismatch.
Why hydration is needed
Server-rendered HTML shows content but has no event listeners. Hydration lets the framework adopt the existing markup instead of rebuilding it, attaching interactivity so buttons, forms, and navigation start working.
Hydration mismatches
If the HTML the server produced differs from what the client would render, hydration breaks. Common causes are using random values, timestamps, or browser-only APIs during render. The fix is to make server and client render the same output.
The cost of hydration
- The full component tree must run again in the browser.
- Large apps can feel slow to become interactive even though they look ready.
- Shipping more JavaScript means more hydration work.
Newer approaches
Partial and progressive hydration only hydrate the interactive parts, and islands architecture hydrates isolated components rather than the whole page. These reduce the JavaScript that must run before the page is usable.
Hydration and CI/CD
Hydration is a runtime browser behavior, but it depends on the build producing matching server and client bundles. CI can guard against mismatches by running the production build and an end-to-end test that loads a rendered page and confirms it becomes interactive without console hydration errors.
Key takeaways
- Hydration attaches JavaScript behavior to server-rendered HTML.
- Mismatches between server and client output break hydration; keep render output identical.
- CI can catch hydration errors with an end-to-end test against the production build.