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

Hydration Error Diagnosis

Common Mistakes

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