Astroアイランドアーキテクチャ：clientディレクティブの使い分け

---
// Astro公式仕様：アイランドアーキテクチャの記述例
import HeaderNav from '../components/HeaderNav.jsx';
import FooterForm from '../components/FooterForm.jsx';
import ClientOnlyWidget from '../components/ClientOnlyWidget.jsx';
---

<!-- 1. 即時対話が必要なヘッダー: ページロード直後にハイドレーション -->
<HeaderNav client:load />

<!-- 2. ファーストビュー外のフッター: スクリーン内に入った時に遅延ハイドレーション -->
<FooterForm client:visible />

<!-- 3. localStorage依存コンポーネント: サーバーレンダリング自体をスキップ -->
<ClientOnlyWidget client:only="react" />

Astro公式仕様：4つの client:* ディレクティブの使い分け

ディレクティブ	ハイドレーションの実行タイミング	推奨ユースケース
client:load	ページロード直後（最優先）	モバイルメニュー、ドロップダウン、即時対話UI
client:idle	メインスレッドが空いた時 (requestIdleCallback)	検索フィルター、いいねボタン、非優先UI
client:visible	要素が画面内に入った時 (IntersectionObserver)	コメント欄、フッターフォーム、下部カルーセル
client:only="react"	サーバー描画をスキップしクライアントでのみ描画	window / localStorage 依存コンポーネント

---

実際に起こる障害：ハイドレーション・ミスマッチ (Hydration Mismatch)

client:load や client:visible を指定したUIコンポーネント内部で、サーバーレンダリング（SSR）時とクライアントハイドレーション時で異なるデータ（localStorage, window.innerWidth, Date.now()）を参照すると、サーバーが生成したHTML構造とクライアントが生成したDOM構造にズレ（Hydration Mismatch）が生じ、画面表示が一瞬崩れたり状態が破棄される障害が発生します。

---

障害回避手順

1. window や localStorage に依存するコンポーネントは、ブラウザ専用を示す client:only="react" (または vue/svelte) を指定する
2. client:load 等を使用する場合は、ブラウザ固有オブジェクトの参照を React の useEffect / Vue の onMounted の中に閉じる
3. 不要なコンポーネントには client:* を一切付けず、Astroのデフォルトである「純粋な静的HTML」として出力させる