Hydration
Hydration is the process by which client-side JavaScript attaches event listeners and application state to server-rendered HTML, turning static markup into a fully interactive application without re-rendering it from scratch.
Definition
Hydration is the process by which client-side JavaScript attaches event listeners and application state to server-rendered HTML, turning static markup into a fully interactive application without re-rendering it from scratch.
Overview
When a page uses Server-Side Rendering (SSR) or Static Site Generation (SSG), the browser first receives complete, already-rendered HTML — useful for fast first paint and SEO — but that HTML isn't yet interactive: buttons don't respond to clicks, and component state doesn't exist in the browser. Hydration is the step where the framework's JavaScript runtime runs on the client, walks the existing DOM, and attaches the event handlers and reactive state that make the page behave like a normal client-rendered app, ideally without discarding and re-building the DOM it just received. Frameworks like React and Vue.js implement hydration by matching the component tree they would have rendered against the DOM structure already present, reusing existing nodes where they match. A common failure mode, called a 'hydration mismatch,' occurs when the server-rendered HTML and the client's expected output diverge (for example, due to date formatting or environment-specific data), which frameworks typically detect and warn about, sometimes causing a visible re-render. Because naive hydration blocks interactivity until the entire page's JavaScript has loaded and hydrated, newer techniques — partial hydration, islands architecture (used by Astro), and React's streaming/selective hydration — aim to make only the interactive parts of a page hydrate early, improving time-to-interactive on content-heavy pages.
Key Concepts
- Attaches event listeners and state to already-rendered server HTML
- Reuses existing DOM nodes rather than re-rendering the page from scratch
- Required for interactivity in SSR and SSG-rendered applications
- Hydration mismatches occur when server and client output diverge
- Newer patterns (partial/selective hydration, islands architecture) hydrate only what's needed
- Directly affects time-to-interactive, a key web performance metric