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
Exploreagent with Chrome DevTools to run the hydration audit script - Fix hydration mismatches across multiple routes: Use
Taskagent to isolate, correct, and verify each affected component - Design hydration-safe architecture for new features: Use
Planagent 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