Hydration Guardian
Overview
Ensures zero-mismatch integrity between server-rendered HTML and client-side React trees. Covers hydration error diagnosis, selective hydration via Suspense boundaries, deterministic data bridges with the React 19 use() hook, 'use cache' for eliminating data drift, two-pass rendering for client-only content, React 19's single-diff hydration error reporting for pinpointing exact mismatches, and automated validation of rendered DOM state.
When to use: Debugging hydration mismatch errors, fixing text content mismatches, handling browser extension DOM pollution, implementing deterministic data bridges, optimizing SSR/client hydration performance, setting up error monitoring with onRecoverableError.
When NOT to use: Client-only React applications without SSR, static sites without hydration, API-only backends.
Quick Reference
| Pattern |
Approach |
Key Points |
| Selective hydration |
<Suspense fallback={...}> boundary |
Hydrates independently; prioritizes user interaction |
| Deterministic bridge |
use(serverPromise) instead of useEffect |
Direct server-to-client data transition (React 19) |
| Cache directive |
'use cache' in data fetchers |
Share exact server result with client during hydration |
| Two-pass rendering |
useState + useEffect for client-only |
First render matches server; second adds client content |
| Client-only skip |
next/dynamic with ssr: false |
Exclude component from server render entirely |
| Error monitoring |
onRecoverableError on hydrateRoot |
Detect and report silent hydration recovery |
| Error reporting |
React 19 single-diff error format |
Pinpoints exact mismatch location with unified diff output |
| Error callbacks |
onUncaughtError, onCaughtError |
Granular error handling on createRoot/hydrateRoot |
| Date/time safety |
UTC normalization or server-synced context |
Prevent locale-dependent hydration mismatches |
| Extension resilience |
Test with common browser extensions active |
Detect DOM pollution from translators, dark-mode tools |
Hydration Error Diagnosis
| Error Message |
Likely Cause |
Corrective Action |
Text content did not match |
Non-deterministic render (dates, random values) |
Use two-pass rendering or suppressHydrationWarning |
Expected server HTML to contain |
Client renders content server did not |
Move client-only code to useEffect or dynamic import |
Hydration failed |
Invalid HTML nesting (<p> inside <p>) |
Fix HTML structure; browsers auto-correct causing drift |
Extra attributes from server |
Server-only attributes not on client |
Ensure attribute parity or use suppressHydrationWarning |
There was an error while hydrating |
Extension-modified DOM or major mismatch |
Check for browser extensions; verify HTML validity |
Common Mistakes
| Mistake |
Correct Pattern |
Using suppressHydrationWarning on container elements |
Fix the root cause; suppress only on leaf elements with unavoidable differences |
Accessing window or document in the render body |
Wrap client-only code in useEffect or use next/dynamic with ssr: false |
Using Math.random() or new Date() without stable seeds |
Use UTC normalization, server-cached values, or two-pass rendering |
| Ignoring silent hydration recovery in production |
Configure onRecoverableError on hydrateRoot to log and monitor |
Using dangerouslySetInnerHTML with server/client mismatch |
Ensure identical content or use a dedicated key change to force remount |
Checking typeof window !== 'undefined' in render |
Use two-pass rendering; the check runs on server too (it returns false) |
Nesting <p> inside <p> or <div> inside <p> |
Fix invalid HTML nesting; browsers correct it causing server/client drift |
Delegation
- Scan rendered pages for hidden hydration warnings: Use
Explore agent with Chrome DevTools to run the hydration audit script
- Fix hydration mismatches across multiple routes: Use
Task agent to isolate, correct, and verify each affected component
- Design hydration-safe architecture for new features: Use
Plan agent to select between Suspense boundaries, two-pass rendering, and cache patterns
References
- Common Mismatches -- causes, diagnosis, and fixes for hydration mismatch errors including dates, locales, HTML nesting, and browser extensions
- Selective Hydration -- Suspense-based selective hydration, streaming SSR, two-pass rendering, and client-only components
- Use Cache Patterns -- data drift prevention, Next.js use cache directive, React 19 use() hook, deterministic data bridges
- Validation Techniques -- automated DOM verification, mutation monitoring, onRecoverableError, and production hydration monitoring
1---
2name: hydration-guardian
3description: >
4 Ensures zero-mismatch integrity between server-rendered HTML and client-side
5 React trees. Use when debugging hydration errors, fixing text content
6 mismatches, handling browser extension DOM pollution, implementing selective
7 hydration with Suspense, using the React 19 use() hook for deterministic
8 server-to-client data bridges, or applying Next.js use cache for data drift
9 prevention. Use for hydration mismatch, SSR, hydrateRoot, suppressHydrationWarning,
10 onRecoverableError, two-pass rendering.
11license: MIT
12metadata:
13 author: oakoss
14 version: '1.0'
15 source: 'https://react.dev/reference/react-dom/client/hydrateRoot'
16---
17
18# Hydration Guardian
19
20## Overview
21
22Ensures zero-mismatch integrity between server-rendered HTML and client-side React trees. Covers hydration error diagnosis, selective hydration via Suspense boundaries, deterministic data bridges with the React 19 `use()` hook, `'use cache'` for eliminating data drift, two-pass rendering for client-only content, React 19's single-diff hydration error reporting for pinpointing exact mismatches, and automated validation of rendered DOM state.
23
24**When to use:** Debugging hydration mismatch errors, fixing text content mismatches, handling browser extension DOM pollution, implementing deterministic data bridges, optimizing SSR/client hydration performance, setting up error monitoring with `onRecoverableError`.
25
26**When NOT to use:** Client-only React applications without SSR, static sites without hydration, API-only backends.
27
28## Quick Reference
29
30| Pattern | Approach | Key Points |
31| -------------------- | ------------------------------------------ | ---------------------------------------------------------- |
32| Selective hydration | `<Suspense fallback={...}>` boundary | Hydrates independently; prioritizes user interaction |
33| Deterministic bridge | `use(serverPromise)` instead of useEffect | Direct server-to-client data transition (React 19) |
34| Cache directive | `'use cache'` in data fetchers | Share exact server result with client during hydration |
35| Two-pass rendering | `useState` + `useEffect` for client-only | First render matches server; second adds client content |
36| Client-only skip | `next/dynamic` with `ssr: false` | Exclude component from server render entirely |
37| Error monitoring | `onRecoverableError` on `hydrateRoot` | Detect and report silent hydration recovery |
38| Error reporting | React 19 single-diff error format | Pinpoints exact mismatch location with unified diff output |
39| Error callbacks | `onUncaughtError`, `onCaughtError` | Granular error handling on `createRoot`/`hydrateRoot` |
40| Date/time safety | UTC normalization or server-synced context | Prevent locale-dependent hydration mismatches |
41| Extension resilience | Test with common browser extensions active | Detect DOM pollution from translators, dark-mode tools |
42
43## Hydration Error Diagnosis
44
45| Error Message | Likely Cause | Corrective Action |
46| ------------------------------------ | ----------------------------------------------- | --------------------------------------------------------- |
47| `Text content did not match` | Non-deterministic render (dates, random values) | Use two-pass rendering or `suppressHydrationWarning` |
48| `Expected server HTML to contain` | Client renders content server did not | Move client-only code to `useEffect` or dynamic import |
49| `Hydration failed` | Invalid HTML nesting (`<p>` inside `<p>`) | Fix HTML structure; browsers auto-correct causing drift |
50| `Extra attributes from server` | Server-only attributes not on client | Ensure attribute parity or use `suppressHydrationWarning` |
51| `There was an error while hydrating` | Extension-modified DOM or major mismatch | Check for browser extensions; verify HTML validity |
52
53## Common Mistakes
54
55| Mistake | Correct Pattern |
56| ----------------------------------------------------------- | ------------------------------------------------------------------------------- |
57| Using `suppressHydrationWarning` on container elements | Fix the root cause; suppress only on leaf elements with unavoidable differences |
58| Accessing `window` or `document` in the render body | Wrap client-only code in `useEffect` or use `next/dynamic` with `ssr: false` |
59| Using `Math.random()` or `new Date()` without stable seeds | Use UTC normalization, server-cached values, or two-pass rendering |
60| Ignoring silent hydration recovery in production | Configure `onRecoverableError` on `hydrateRoot` to log and monitor |
61| Using `dangerouslySetInnerHTML` with server/client mismatch | Ensure identical content or use a dedicated `key` change to force remount |
62| Checking `typeof window !== 'undefined'` in render | Use two-pass rendering; the check runs on server too (it returns false) |
63| Nesting `<p>` inside `<p>` or `<div>` inside `<p>` | Fix invalid HTML nesting; browsers correct it causing server/client drift |
64
65## Delegation
66
67- **Scan rendered pages for hidden hydration warnings**: Use `Explore` agent with Chrome DevTools to run the hydration audit script
68- **Fix hydration mismatches across multiple routes**: Use `Task` agent to isolate, correct, and verify each affected component
69- **Design hydration-safe architecture for new features**: Use `Plan` agent to select between Suspense boundaries, two-pass rendering, and cache patterns
70
71## References
72
73- [Common Mismatches](references/common-mismatches.md) -- causes, diagnosis, and fixes for hydration mismatch errors including dates, locales, HTML nesting, and browser extensions
74- [Selective Hydration](references/selective-hydration.md) -- Suspense-based selective hydration, streaming SSR, two-pass rendering, and client-only components
75- [Use Cache Patterns](references/use-cache-patterns.md) -- data drift prevention, Next.js use cache directive, React 19 use() hook, deterministic data bridges
76- [Validation Techniques](references/validation-techniques.md) -- automated DOM verification, mutation monitoring, onRecoverableError, and production hydration monitoring
oakoss