К основному содержанию
скилл CX Codex

hydration-guardian — скилл для Claude Code

Скилл hydration-guardian ловит расхождение серверной разметки и клиентского React-дерева: по тексту ошибки находит причину и подсказывает, какой приём гидратации применить.

MIT 144 установок ★ 29 обновлён 2026-08-17

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add oakoss/agent-skills --skill hydration-guardian -a claude-code
Открыть на GitHub

Что делает hydration-guardian

Скилл разбирает расхождение между HTML, который отдал сервер, и деревом, которое собрал React в браузере. Ошибки вида Text content did not match или Hydration failed он сопоставляет с причиной и говорит агенту, что править: структуру HTML, рендер даты или клиентский код, уехавший в useEffect.

Внутри SKILL.md — таблица приёмов: границы <Suspense>, use(serverPromise) вместо эффекта для передачи данных с сервера, директива 'use cache' в Next.js против дрейфа данных, двухпроходный рендер для клиентского контента и onRecoverableError на hydrateRoot. Отдельно лежат четыре справочника: частые расхождения, выборочная гидратация, паттерны кеша и проверка DOM.

Часть таких ошибок приходит не из кода: переводчики страниц и тёмные темы правят DOM до гидратации. Скилл советует проверять страницу с включёнными расширениями.

Какие задачи решает

  • найти компонент, из-за которого серверная разметка расходится с клиентской
  • убрать расхождение даты и локали между сервером и браузером
  • разложить тяжёлую страницу на Suspense-границы, чтобы каждая гидратировалась отдельно
  • настроить onRecoverableError, чтобы тихие сбои гидратации попадали в лог
  • отличить порчу DOM расширением браузера от ошибки в компоненте

Примеры запросов агенту

  • Найди, из-за чего в app/layout.tsx появляется Text content did not match, и почини рендер даты.
  • Оберни виджеты дашборда в <Suspense>, чтобы каждый гидрировался сам по себе.
  • Проверь, не ломает ли DOM расширение тёмной темы, прежде чем переписывать хедер.

Как установить hydration-guardian

1Через Skills CLI (Vercel)

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

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/hydration-guardian/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о hydration-guardian

Как установить hydration-guardian в Claude Code?

Выполните npx skills add oakoss/agent-skills --skill hydration-guardian -a claude-code. Скилл окажется по пути ~/.claude/skills/hydration-guardian/SKILL.md.

Что делает hydration-guardian?

Помогает агенту найти причину ошибки гидратации React и выбрать исправление: выборочная гидратация, мост с сервера через use(), кеш в Next.js или двухпроходный рендер.

Когда скилл не нужен?

В клиентском React без SSR, на статическом сайте без гидратации и в бэкенде без разметки. Там серверной и клиентской версий страницы просто нет.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Фронтенд и UI» →
react-selective-hydration patterns.dev Скилл react-selective-hydration для Claude Code учит агента настраивать выборочную гидратацию и потоковый SSR в React 18+. Ускоряет интерактивность страниц с тяжёлыми компонентами и запросами данных. CX Codex +1 1 000установок progressive-hydration patterns.dev Скилл progressive-hydration для Claude Code помогает распределить клиентскую гидратацию по приоритету. Он подключается при работе с SSR-страницами, где части интерфейса могут ждать JavaScript. CX Codex +1 1 000установок rendering-hydration-suppress-warning tech-leads-club Правило rendering-hydration-suppress-warning гасит предупреждения гидратации там, где сервер и клиент намеренно показывают разное: даты, случайные ID, форматирование по локали. CX Codex +1 ★ 7 191звёзд репо rendering-hydration-no-flicker tech-leads-club Правило rendering-hydration-no-flicker учит агента читать локальное хранилище без ошибок серверного рендеринга и без мигания интерфейса до гидратации. CX Codex +1 ★ 7 191звёзд репо execution-model TanStack Скилл execution-model помогает агенту правильно разделять серверный и клиентский код в TanStack Start и учитывать SSR, гидрацию и переменные окружения. CX Codex +1 214установок nextjs-use-search-params-suspense wsimmonds Скилл nextjs-use-search-params-suspense объясняет, как правильно читать параметры URL в клиентских компонентах Next.js: директива 'use client' плюс обёртка Suspense. CX Codex +1 313установок

Из того же набора106

Весь набор →
tanstack-virtual Скилл учит агента виртуализировать длинные списки, таблицы и сетки на TanStack Virtual: в DOM остаются только видимые строки. CX Codex +1 148установок de-slopify Скилл de-slopify для Claude Code находит шаблонные обороты, лишние тире и следы ИИ в комментариях при правке текста и кода после языковой модели. CX Codex +1 146установок docker Скилл для сборки Docker-образов, настройки Compose-стеков и подготовки контейнеров к продакшену. CX Codex +1 145установок chrome-devtools Скилл chrome-devtools управляет настоящим Chrome через расширение или DevTools MCP: заполняет формы, читает страницы и помогает отлаживать веб-приложения. Работает с активной сессией браузера. CX Codex +1 145установок e2e-testing Скилл e2e-testing помогает ИИ-агенту проектировать архитектуру E2E-тестов на Playwright: от Page Object Model и шардинга в CI до моков сети и проверок доступности. CX Codex +1 142установок valkey Скилл помогает настраивать Valkey и Redis-совместимое хранилище: от кэша и лимитов запросов до очередей и миграции с Redis. Пригодится при проектировании схемы данных и Docker Compose. CX Codex +1 142установок remotion Скилл для Remotion: агент собирает видео из React-компонентов и держит анимацию в таймлайне, а не в CSS. CX Codex +1 141установок vite Описывает конфиг Vite, плагины, dev-сервер, сборку, SSR и переменные окружения. Задачи: правка vite.config.ts и сборка библиотек. CX Codex +1 138установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой