hydration-guardian

ハイドレーションガーディアン

概要

サーバーでレンダリングされた HTML とクライアント側の React ツリー間で、不一致が一切ない整合性を確保します。ハイドレーションエラーの診断、Suspense 境界を用いた選択的ハイドレーション、React 19 の use() フックによる決定論的なデータブリッジ、データのずれをなくすための 'use cache'、クライアント専用コンテンツ向けの 2 パスレンダリング、不一致箇所を正確に特定する React 19 の単一差分ハイドレーションエラー報告、レンダリング済み DOM の状態の自動検証を扱います。

使用する場面： ハイドレーションの不一致エラーのデバッグ、テキストコンテンツの不一致の修正、ブラウザー拡張機能による DOM の汚染への対処、決定論的なデータブリッジの実装、SSR／クライアントのハイドレーションパフォーマンスの最適化、onRecoverableError によるエラー監視の設定。

使用しない場面： SSR を使用しないクライアント専用の React アプリケーション、ハイドレーションを使用しない静的サイト、API 専用のバックエンド。

クイックリファレンス

パターン	アプローチ	要点
選択的ハイドレーション	<Suspense fallback={...}> 境界	独立してハイドレーションされ、ユーザーの操作が優先されます
決定論的なブリッジ	useEffect の代わりに use(serverPromise)	サーバーからクライアントへデータを直接移行します（React 19）
キャッシュディレクティブ	データフェッチャー内の 'use cache'	ハイドレーション中にサーバーの結果をクライアントと正確に共有します
2 パスレンダリング	クライアント専用コンテンツに useState + useEffect を使用	1 回目のレンダリングはサーバーと一致し、2 回目にクライアントのコンテンツを追加します
クライアント専用レンダリングのスキップ	ssr: false を指定した next/dynamic	コンポーネントをサーバーレンダリングから完全に除外します
エラー監視	hydrateRoot の onRecoverableError	表面化しないハイドレーションのリカバリーを検出して報告します
エラー報告	React 19 の単一差分エラー形式	統合された差分出力で不一致箇所を正確に特定します
エラーコールバック	onUncaughtError、onCaughtError	createRoot／hydrateRoot で詳細なエラー処理を行います
日付／時刻の安全性	UTC 正規化またはサーバー同期コンテキスト	ロケール依存のハイドレーション不一致を防ぎます
拡張機能への耐性	一般的なブラウザー拡張機能を有効にしてテスト	翻訳ツールやダークモードツールによる DOM の汚染を検出します

ハイドレーションエラーの診断

エラーメッセージ	考えられる原因	対応策
Text content did not match	決定性のないレンダリング（日付、ランダムな値）	2 パスレンダリングまたは suppressHydrationWarning を使用します
Expected server HTML to contain	クライアントが、サーバーにはないコンテンツをレンダリングしている	クライアント専用コードを useEffect または動的インポートに移します
Hydration failed	無効な HTML の入れ子（<p> 内の <p>）	HTML の構造を修正します。ブラウザーによる自動修正でずれが生じます
Extra attributes from server	クライアントにないサーバー専用の属性	属性を一致させるか、suppressHydrationWarning を使用します
There was an error while hydrating	拡張機能によって変更された DOM または重大な不一致	ブラウザー拡張機能を確認し、HTML が有効であることを検証します

よくある間違い

間違い	正しいパターン
コンテナ要素で suppressHydrationWarning を使う	根本原因を修正します。回避できない差異がある場合に限り、末端要素で抑制します
render 本文で window や document にアクセスする	クライアント専用のコードを useEffect で囲むか、ssr: false を指定して next/dynamic を使います
安定したシード値を使わずに Math.random() や new Date() を使う	UTC で正規化するか、サーバーでキャッシュした値、または 2 パスレンダリングを使います
本番環境でのサイレントなハイドレーション回復を無視する	hydrateRoot で onRecoverableError を設定し、ログを記録して監視します
サーバーとクライアントで不一致がある状態で dangerouslySetInnerHTML を使う	コンテンツを同一にするか、専用の key を変更して強制的に再マウントします
render 内で typeof window !== 'undefined' を確認する	2 パスレンダリングを使います。このチェックはサーバーでも実行されます（false が返ります）
<p> の中に <p>、または <p> の中に <div> をネストする	不正な HTML のネストを修正します。ブラウザーが修正するため、サーバーとクライアントにずれが生じます

委任

• レンダリングされたページをスキャンして、隠れたハイドレーション警告を探す：Explore エージェントと Chrome DevTools を使って、ハイドレーション監査スクリプトを実行します
• 複数のルートにわたるハイドレーションの不一致を修正する：Task エージェントを使って、影響を受ける各コンポーネントを切り分け、修正して検証します
• 新機能のハイドレーションに安全なアーキテクチャを設計する：Plan エージェントを使って、Suspense 境界、2 パスレンダリング、キャッシュパターンから選択します

参考資料

• よくある不一致 -- 日付、ロケール、HTML のネスト、ブラウザー拡張機能など、ハイドレーションの不一致エラーの原因、診断方法、修正方法
• 選択的ハイドレーション -- Suspense ベースの選択的ハイドレーション、ストリーミング SSR、2 パスレンダリング、クライアント専用コンポーネント
• キャッシュパターンの使用 -- データのずれの防止、Next.js の use cache ディレクティブ、React 19 の use() フック、決定論的なデータブリッジ
• 検証手法 -- DOM の自動検証、変更の監視、onRecoverableError、本番環境でのハイドレーション監視