astro-best-practices

Astro のベストプラクティス

Astro の作業を設計、実装、レビューする際の基本として、このスキルを使用してください。Astro 固有のアーキテクチャに関する指針を、さまざまなエージェントに適用できる汎用的な手順にまとめています。

基本原則

• リクエスト時のレンダリングが不要な場合は、静的生成を優先してください
• クライアント側の JavaScript は最小限に抑えてください
• 実際にインタラクティブな機能が必要な場合にのみ、フレームワークアイランドを使用してください
• 明確なプロジェクト構成と予測しやすいルーティングを維持してください
• 出力の同等性だけでなく、アクセシビリティと保守性を重視してください

アーキテクチャのデフォルト

まずは .astro を優先する

• 静的または大部分が静的な UI には、.astro コンポーネントを使用してください
• ローカルの状態やクライアント側の動作が本当に必要な場合にのみ、React、Vue、または他のフレームワークを使用してください
• インタラクティブアイランドは小さく、末端に配置してください

意図的にハイドレーションを使用する

• 遅延表示する UI には client:visible
• 優先度の低い拡張には client:idle
• 重要で即時のインタラクティブ性が必要な場合にのみ client:load
• サーバー側のレンダリングを省略する意図がある場合にのみ client:only

広範囲なレイアウト領域をハイドレーションすることは、デフォルトで避けてください。

予測しやすいプロジェクト構成を維持する

一般的な構成：

src/
  components/
  layouts/
  pages/
  content/
  styles/
  assets/
public/

プロジェクト固有の明確な理由がない限り、独自のフォルダー構成を作らないでください。

コンテンツとデータ

• 構造化コンテンツにはコンテンツコレクションを使用してください
• 制約のないフロントマターを受け入れるのではなく、スキーマを定義してください
• 明確な理由がない限り、Astro のフロントマターでサーバー側のデータを取得してください
• データフローを明確にし、そのデータを所有するコンポーネントまたはページの近くに配置してください

アクセシビリティ

• header、nav、main、article、footer などのセマンティックなランドマークを使用してください
• すべてのインタラクティブなコントロールをキーボードで操作できるようにしてください
• 意味のあるラベルとアクセシブルな名前を付けてください
• 見出しの階層を正しく保ってください
• 適切な画像の代替テキストを使用してください
• フォーカス状態を視覚的に表示してください
• 色のコントラストは必須の基準として扱ってください

パフォーマンス

• astro:assets またはプロジェクトで選択されている画像パイプラインを意図的に使用してください
• 画像の寸法や安定したコンテナーを指定して、レイアウトシフトを防いでください
• 不必要なクライアントハイドレーションを避けてください
• CSS と JavaScript は、それらを必要とする機能に限定してください
• クライアント側の複雑さより、シンプルなサーバーレンダリングのマークアップを優先してください

スタイル設定

• プロジェクトでスタイルシステムが定義されていない限り、スコープ付きのコンポーネントスタイルをデフォルトにしてください
• 再利用可能なトークンには CSS カスタムプロパティを使用してください
• プロジェクトですでにユーティリティファーストを採用していない場合は、場当たり的なユーティリティの乱用より、保守しやすいレイアウトパターンを優先してください
• レスポンシブな動作は意図を明確にし、テスト可能な状態にしてください

レビューチェックリスト

Astro の作業を完了する前に、次の点を確認してください。

• ハイドレーションされたコードに不要なものはありませんか
• HTML はセマンティックな状態を保っていますか
• ルートとレイアウトの構成は明確なままですか
• コンテンツスキーマは十分に厳密ですか
• キーボードや支援技術でアクセスできますか
• 実装は既存のプロジェクト規約に沿っていますか