astro-dev

Astro Dev

プロジェクトにインストールされている Astro のバージョンとローカルの規約を、信頼できる情報源として使用してください。このスキルのリファレンスには、現在の Astro 7 のパターンとよくある移行時の落とし穴がまとめられていますが、ユーザーの依頼範囲を超える大規模なリファクタリングを正当化するものではありません。

クイックスタート

1. package.json、ロックファイル、astro.config.*、対象ファイルを確認します。
2. タスクに関連する Astro、Node、アダプター、インテグレーション、コンテンツの設定を確認します。
3. 下のルーターから、該当するリファレンスだけを読みます。
4. バージョンに依存する API や不慣れな API については、利用可能な公式ドキュメント機能を使って、公式の Astro ドキュメントで現在の正確な動作を確認します。この参照が必要な場合に限り、references/doc-endpoints.md を読みます。
5. リポジトリのコンポーネント、スタイル、デプロイの規約を維持しながら、依頼された結果を実現する最小限の変更を加えます。
6. 関連する型チェック、チェック、ビルド、テストのコマンドを実行します。表示上の動作については、対象ルートをレンダリングし、対象範囲の状態を確認します。

リファレンスのルーター

タスク	読むリファレンス
プロジェクトのセットアップ、コア API、ファイル構成、スクリプト、ミドルウェア、Astro 7 へのアップグレード、高度なルーティング	references/astro-core-patterns.md
ビルド時またはライブのコンテンツコレクション、ローダー、クエリ、Zod 4	references/content-collections.md
RSS、ページネーション、タグ、SEO、目次、Shiki、Markdown/MDX のカスタマイズ	references/blog-recipes.md
Tailwind CSS v4、テーマ、フォント	references/tailwind.md
アイランドと client:* ハイドレーション	references/islands-and-hydration.md
アクション、フォーム、検証、ミューテーション	references/actions-and-forms.md
<ClientRouter />、ライフサイクルイベント、状態の保持	references/view-transitions.md
プリレンダリング、セッション、環境変数、i18n、CSP、キャッシュ、Cloudflare	references/server-features.md
公式ドキュメントの検索と代替 URL	references/doc-endpoints.md

すべてのリファレンスを事前に読み込まないでください。タスクが 2 つの領域にまたがる場合は、その 2 つを読みます。このルーターはチェックリストではありません。

互換性ゲート

タスクで変更する行だけを確認してください。

領域	現在の基準
コンテンツ	src/content.config.ts を使用します。すべてのコレクションにローダーを設定し、astro/zod から z をインポートして、スタンドアロンの render(entry) を呼び出します
Tailwind	インストール済みの Tailwind v4 のセットアップを使用します。通常は @tailwindcss/vite と @import "tailwindcss" を使います。非推奨の @astrojs/tailwind を再導入しないでください
Markdown/MDX	Astro 7 のデフォルトは Sätteri です。markdown.processor を使用し、プロジェクトのプラグイン要件に応じて Sätteri または unified を選択します
ハイドレーション	すぐに操作可能な UI には client:load、遅延させるアイランドには client:idle または client:visible を使用します。静的マークアップはハイドレーションしないでください
ミューテーション	アプリのフォームには型付き Actions を優先します。Cookie、セッション、Actions、POST 処理、またはリクエストごとのデータが必要なページは、オンデマンドでレンダリングする必要があります
環境変数	アプリのコードではスキーマに基づく astro:env を優先します。ビルド時の import.meta.env と、文書化されたランタイム時／設定時の例外を区別します
ClientRouter	astro:page-load で初期化し、差し替えられる要素にはイベント委譲を使用します。描画前の状態は astro:before-swap で設定します
Astro 7	Node 22.12 以降、Vite 8、ESM 設定を使用します。HTML の解析は厳格化され、JSX の空白のデフォルトが変更されています。src/fetch.ts は予約済みで、キャッシュとルートルールはトップレベルにあります

Astro.glob()、entry.render()、旧形式のコレクションの配置場所／型、output: 'hybrid'、CJS 設定、<ViewTransitions /> など、削除されたパターンを新しいコードにコピーしないでください。移行でこれらに触れる場合は、完全な対応表として references/astro-core-patterns.md を参照してください。

実装ワークフロー

1. 変更範囲を定める

依頼された動作と、それを担当する可能性の高いファイルを明確にします。依頼で明示的に変更されない限り、公開ルート、コンテンツ ID、アダプターの動作、デザインシステムの規約を維持します。Astro が対応しているという理由だけで、インテグレーション、クライアントフレームワーク、新たな抽象化を追加しないでください。

2. API を選ぶ前に調査する

• パッケージマネージャーのスクリプトとインストール済みパッケージのバージョンを確認します。
• ルートが事前レンダリングされるか、リクエスト時にレンダリングされるかを確認します。
• Node API やサーバー機能を使う前に、アダプター／ランタイムを確認します。
• 既存のコンテンツローダー、Actions、ミドルウェア、スタイルのエントリーポイントを確認します。
• 新しい解決策を導入する前に、リポジトリ内で既存の実装を検索します。

3. 適切な境界で実装する

ルートファイルはルーティング、データ読み込み、組み立てに集中させます。既存の レイアウト／コンポーネント／ヘルパーを再利用します。依頼された変更によって 責務が混在したり、検証が難しくなったりする場合に限り、ファイルを分割します。 小さな修正をリポジトリ全体の再編成に発展させないでください。

デフォルトでは、サーバーレンダリングされた Astro マークアップを選択します。 ブラウザーで状態管理や即時のインタラクションが必要な場合に限り、クライアント アイランドを追加し、意図したインタラクションを維持できる最も遅延の少ない ディレクティブを選びます。

4. 動作を検証する

まず、プロジェクトのパッケージマネージャーと既存のスクリプトを使います。 変更内容に応じて、以下を検証します。

• Astro／型チェックと対象を絞ったテスト
• 設定、インテグレーション、ルーティング、デプロイに関する変更では本番ビルド
• サーバー動作について、対象ランタイムで影響を受けるルート
• 表示 UI の変更では、デスクトップ／モバイルでのレンダリングと主要なインタラクション
• 移行に固有のケース（無効な HTML、インラインの空白、コンテンツ ID、環境変数のタイミング、事前レンダリング／リクエスト時レンダリングの境界など）

静的な確認だけでアップグレードや UI の変更が完了したと主張しないでください。 環境上、関連するチェックを実行できない場合は、その不足点を具体的に報告します。

テンプレート

templates/ 配下のファイルは出発点であり、リポジトリを調査する代わりにはなりません。 インストール済みのインテグレーションとデプロイ先に適合する部分だけをコピーします。

出力契約

まず、完了した動作を述べます。次に、変更した対象範囲のファイルと、 実際に実行したチェックを要約します。該当する場合は、レンダリングした ルートやビューポートも含めます。未検証のランタイム、移行ケース、視覚的な状態が あれば明記します。チュートリアルは、ユーザーから求められた場合に限り追加します。

注意点

• 最新に見える API が、インストール済みの API とは限りません。編集前にバージョンを 確認し、バージョンに依存する正確な動作については公式ドキュメントを参照します。
• 静的な frontmatter はビルド時に実行されます。リクエストごとのロジックには、 リクエスト時レンダリングと適切なアダプターが必要です。
• class は Astro コンポーネントを自動的に通過せず、スコープ付きスタイルも スロットや Markdown のコンテンツには自動的に適用されません。
• 処理された <script> タグはバンドルされ、重複が除去されます。 define:vars はインライン動作を意味します。コンポーネントを複数回使用する場合は、 インスタンスごとに安全なパターンが必要です。
• ビルドに成功しても、ハイドレーションのタイミング、ClientRouter のライフサイクル、 レスポンシブレイアウトが正しいとは限りません。変更した動作を実際に確認します。
• ユーザーが依頼した成果の範囲外で、機会に乗じた移行、依存関係の追加、 ファイル分割を行わないでください。