Astro v6アーキテクチャルール（厳格モード）

# Astro v6 アーキテクチャルール（厳格モード） ## 1. 核心理念 - Astroの「HTML優先 / デフォルトでJavaScriptゼロ」の原則に従う： - インタラクティブ性が明示的に要求されない限り、すべては静的HTML。 - JavaScriptはコストであり、実際のユーザー価値を生み出す場合のみ追加する。 - 常に「アイランドアーキテクチャ」で考える： - ページは静的HTML - インタラクティブな部分は分離されたアイランド - ページ全体をアプリとして扱わない - JavaScriptを書く前に、常に自問する：「これはHTML + CSSまたはサーバーサイドロジックで解決できるか？」 ## 2. コンポーネントモデル - `.astro`コンポーネントを使用する対象： - レイアウト - 構成 - 静的UI - データ取得 - サーバーサイドロジック（フロントマター） - `.astro`コンポーネント： - ビルド時またはサーバーサイドで実行 - デフォルトではJavaScriptを配信しない - フレームワークに依存しない状態を維持する - `.astro`内でReact/Vue/Svelteのフックを絶対に使用しない ## 3. アイランド（インタラクティブコンポーネント） - インタラクティブ性にはフレームワークコンポーネント（React、Vue、Svelteなど）のみを使用する。 - すべてのインタラクティブコンポーネントを分離されたアイランドとして扱う： - 独立している - 自己完結型 - スコープを最小限に - 絶対にしないこと： - ページ全体やレイアウトをハイドレーションする - 大きなツリーを単一のアイランドでラップする - ループ内で不必要に多数の小さなアイランドを作成する - 優先する方法： - 静的なリストレンダリング - 最小限のインタラクティブユニットのみをハイドレーションする ## 4. ハイドレーション戦略（重要） - 常に`client:*`ディレクティブを使用してハイドレーションを明示的に定義する。 - 可能な限り**低い**優先度を選択する： - `client:load` -> ファーストビューの重要なインタラクティブ性にのみ使用 - `client:idle` -> ページ読み込み後の二次的なUIに使用 - `client:visible` -> ファーストビュー外または重いコンポーネントに使用 - `client:media` -> レスポンシブ/条件付きUIに使用 - `client:only` -> SSRが壊れる場合（window、localStorageなど）にのみ使用 - デフォルトルール： - 決して`client:load`をデフォルトにしない - `client:visible`または`client:idle`を優先する - ハイドレーションはパフォーマンス予算： - 各アイランドはJSを追加する - 総JS量を最小限に保つ ## 5. サーバー vs クライアントロジック - サーバーサイドロジック（`.astro`フロントマター内）を優先する対象： - データ取得 - 変換 - フィルタリング/ソート - 派生値 - クライアントサイドの状態は以下の場合のみ使用する： - ユーザーインタラクションが必要な場合 - リアルタイム更新が必要な場合 - 避けること： - クライアントでのロジックの重複 - サーバーロジックのアイランドへの移動 ## 6. 状態管理 - 厳密に必要な場合を除き、クライアント状態を避ける。 - 必要な場合： - 状態をアイランド内にのみスコープする - 必要な場合を除き、グローバルアプリ状態を作成しない - アイランド間の状態： - 軽量な共有ストア（例：nano stores）を使用する - デフォルトで重いグローバル状態システムを避ける ## 7. パフォーマンス制約（ハードルール） - クライアントに配信するJavaScriptを最小化する： - AstroはハイドレーションされたコンポーネントのJSのみを読み込む - 優先する方法： - 静的レンダリング - 部分的なハイドレーション - 遅延ハイドレーション - 避けること： - 大きなリストのハイドレーション - ループ内での繰り返しアイランド - `client:load`の過剰使用 - 各アイランド： - 独自のバンドルを持つ - 独立して読み込まれる - 小さく焦点を絞った状態を保つ ## 8. ファイルとプロジェクト構造 - `/pages` - エントリーポイント（SSG/SSR）、クライアントロジックなし - `/components` - 共有UI、アイランドはここに配置 - `/layouts` - 静的ラッパーのみ - `/content` - Markdown/CMSデータ - `.astro`ファイルは構成に焦点を当て、振る舞いには焦点を当てない ## 9. アンチパターン（厳格に禁止） - `.astro`でのフックの使用 - AstroをSPAアーキテクチャに変換すること - レイアウト/ページ全体のハイドレーション - あらゆる場所での`client:load`の使用 - リストのハイドレーションされたコンポーネントへのマッピング - 静的な問題に対するクライアントJSの使用 - サーバーロジックのクライアントロジックへの置き換え ## 10. 推奨パターン - 静的ファーストレンダリング - 最小限で分離されたアイランド - 遅延ハイドレーション（`visible`、`idle`） - サーバーサイド計算 - JSの前にHTML + CSS - プログレッシブエンハンスメント ## 11. 意思決定フレームワーク（非常に重要） すべての機能に対して： 1. これは静的HTMLで可能か？ -> YES -> `.astro`を使用 2. インタラクションが必要か？ -> NO -> 静的のまま 3. JSが必要か？ -> YES -> アイランドを作成 4. いつ読み込むべきか？ -> 最も低い優先度の`client:*`を選択 ## 12. メンタルモデル（譲れない） - Astroは以下ではない： - Next.js - SPAフレームワーク - Reactファーストシステム - Astroは以下である： - 静的ファーストレンダラー - 部分的なハイドレーションシステム - パフォーマンスファーストアーキテクチャ - 考え方：「HTMLを配信し、JSを振りかける」