Skip to main content
skill CX Codex

hydration-guardian — Claude Code skill: what it does, how to install

hydration-guardian finds where server-rendered HTML and the client React tree disagree, then points to the pattern that fixes it.

MIT 144 installs ★ 29 updated 2026-08-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill hydration-guardian -a claude-code
Open on GitHub

What hydration-guardian does

Hydration breaks when the markup the server produced stops matching what React renders in the browser. This skill walks the agent through that failure: it pairs common error strings with the cause behind them and names the fix, whether that means repairing invalid nesting, moving client-only code into an effect, or stabilising a date render.

Inside SKILL.md sits a table of patterns. Suspense boundaries let parts of the page hydrate on their own. A promise passed to use() replaces the effect-based data handoff, and Next.js 'use cache' keeps a fetch identical on both sides so the trees stop drifting. Four reference files cover mismatch causes, streaming SSR, cache patterns and DOM checks.

Some of these errors never come from your code. Page translators and dark-mode add-ons edit the DOM before React reaches it, so the skill suggests testing with those extensions switched on. On a client-only app there is nothing to hydrate and the whole thing is dead weight.

What it helps with

  • trace a server/client markup mismatch back to the component that causes it
  • stop dates and locales from rendering differently on each side
  • split a heavy page into Suspense boundaries that hydrate on their own
  • log silent hydration recoveries through onRecoverableError
  • tell browser-extension DOM edits apart from a real component bug

Example prompts for the agent

  • Find out why app/layout.tsx throws Text content did not match and fix the date render.
  • Wrap the dashboard widgets in <Suspense> so each one hydrates separately.
  • Check whether the dark-mode extension is polluting the DOM before I rewrite the header.

How to install hydration-guardian

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill hydration-guardian -a claude-code

2Manually: put the files in place

~/.claude/skills/hydration-guardian/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/hydration-guardian/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about hydration-guardian

How do I install hydration-guardian in Claude Code?

Run npx skills add oakoss/agent-skills --skill hydration-guardian -a claude-code. The skill lands at ~/.claude/skills/hydration-guardian/SKILL.md.

What does hydration-guardian do?

It helps the agent diagnose a React hydration error and pick a fix: selective hydration, a server-to-client use() bridge, Next.js caching, or two-pass rendering.

When is it not needed?

Client-only React without SSR, static sites that never hydrate, and API-only backends. There is no server-rendered markup to compare against.

Source text

SKILL.md · MIT
---
name: hydration-guardian
description: >
  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.
license: MIT
metadata:
  author: oakoss
  version: '1.0'
  source: 'https://react.dev/reference/react-dom/client/hydrateRoot'
---

# 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](references/common-mismatches.md) -- causes, diagnosis, and fixes for hydration mismatch errors including dates, locales, HTML nesting, and browser extensions
- [Selective Hydration](references/selective-hydration.md) -- Suspense-based selective hydration, streaming SSR, two-pass rendering, and client-only components
- [Use Cache Patterns](references/use-cache-patterns.md) -- data drift prevention, Next.js use cache directive, React 19 use() hook, deterministic data bridges
- [Validation Techniques](references/validation-techniques.md) -- automated DOM verification, mutation monitoring, onRecoverableError, and production hydration monitoring

© oakoss · MIT · oakoss/agent-skills

Similar skills

All skills for Frontend and UI →

From the same set106

The whole set →

Project sponsors

Companies that keep this analytics open