hydration-guardian
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.
- Installs
- 135
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/oakoss/agent-skills --skill hydration-guardian- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads hydration-guardian automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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
FAQ
What does the hydration-guardian skill do?
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.
How do I install hydration-guardian?
Run npx skills add https://github.com/oakoss/agent-skills --skill hydration-guardian in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/hydration-guardian/ (personal) or .claude/skills/hydration-guardian/ (project).
Which AI agents can use hydration-guardian?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is hydration-guardian safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains hydration-guardian?
It is published by oakoss in oakoss/agent-skills. It has 135 recorded installs.
More from oakoss/agent-skills
ui-ux-polish
oakoss/agent-skills
Iterative UI/UX polishing workflow for web applications. Use when improving visual polish, refining desktop and mobile UX separately, running iterative enhancement cycles, applying design patterns like glassmorphism or bento grids, or auditing accessibility and WCAG compliance. Use for Stripe-level visual quality, responsive optimization, and design system alignment.
playwright
oakoss/agent-skills
Playwright browser automation API, web scraping, and tooling. Covers locator strategies, assertions, API testing, stealth mode, anti-bot bypass, authenticated sessions, screenshots/PDFs, Docker deployment, configuration, debugging, and MCP integration with AI agents. Prevents documented errors including CI timeout hangs, extension testing failures, and navigation issues. Use when automating browsers, scraping protected sites, bypassing bot detection, generating screenshots/PDFs, configuring Playwright Test, troubleshooting Playwright errors, or learning Playwright API patterns. For E2E test architecture, Page Object Models, CI sharding strategies, or test organization patterns, use the e2e-testing skill instead.
coolify
oakoss/agent-skills
Coolify self-hosted PaaS for deploying applications, databases, and services via REST API and Git integration. Covers API authentication, deployment triggers, build packs (Nixpacks, Dockerfile, Compose), CI/CD with GitHub Actions webhooks, environment management, and Traefik proxy configuration. Use when deploying apps to Coolify, triggering deployments via API, configuring build packs, setting up GitHub Actions CI/CD pipelines, managing environment variables, or troubleshooting deployment failures.
application-security
oakoss/agent-skills
Application security covering threat modeling (STRIDE), OWASP Top 10 (2025), OWASP API Security Top 10 (2023), secure coding review, authentication/authorization patterns, input validation, encryption, security headers, supply chain security, compliance (GDPR/HIPAA/SOC2/PCI-DSS), and security monitoring. Use when reviewing code for vulnerabilities, implementing auth patterns, securing APIs, configuring security headers, hardening supply chain, preventing injection attacks, or preparing for compliance audits.
find-skills
oakoss/agent-skills
Discovers and installs agent skills from the open ecosystem. Enriches search results with descriptions fetched from skills.sh. Use when a user asks "how do I do X", "find a skill for X", "is there a skill that can...", or wants to extend agent capabilities. Use for skill discovery, skill search, skill install, finding tools.
drizzle-orm
oakoss/agent-skills
Drizzle ORM for type-safe SQL with PostgreSQL, MySQL, and SQLite. Use when defining schemas, writing queries, managing relations, running migrations, or using drizzle-kit. Use for drizzle, orm, schema, query, migration, pgTable, relations, drizzle-kit, drizzle-zod.
Popular frontend & design skills
setup-matt-pocock-skills
mattpocock/skills
Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
frontend-design
anthropics/skills
Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.
hyperframes-animation
heygen-com/hyperframes
All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.
prototype
mattpocock/skills
Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
hyperframes-core
heygen-com/hyperframes
The HyperFrames composition contract — build one renderable project. Use for composition structure, the data- timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.
vercel-react-best-practices
vercel-labs/agent-skills
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.