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