migrate

Astro への移行

別のフレームワークからプロジェクトを Astro に移行する場合、静的サイトを Astro に変換する場合、または既存の Astro コードベースをアップグレードする場合に、このスキルを使用してください。

astro-best-practices が利用できる場合は、このスキルと併せて適用し、古いシステムを機械的に再現するのではなく、移行後の成果物が Astro の適切なデフォルトに従うようにしてください。

ワークフロー

1. 現在のシステムを調査する

コードを変更する前に、次の項目を特定してください。

• ルーティング構造
• レイアウトや共有シェルのパターン
• データソース
• スタイリングの方針
• インタラクティブなコンポーネント
• 画像の扱い
• デプロイとランタイムの要件

これにより、移行先を静的、ハイブリッド、サーバーレンダリングのどれにするか判断できます。

2. 移行の形を選ぶ

一般的なパターンは次のとおりです。

• 静的 HTML から Astro のページとレイアウトへの移行
• Next.js または Nuxt から Astro のページとフレームワークアイランドへの移行
• Gatsby のコンテンツ／データフローからコンテンツコレクションへの移行
• 公式のアップグレードガイドを使った Astro のメジャーバージョンアップグレード

既存アプリに重要なランタイム動作や広範なインタラクティブ機能がある場合は、段階的な移行計画を優先してください。

3. ファイルをむやみにコピーせず、概念を対応づける

一般的な対応関係は次のとおりです。

ソース	Astro の移行先
共有アプリシェル	レイアウト
ルートコンポーネント	ページまたは動的ルート
Markdown／コンテンツのパイプライン	コンテンツコレクション
フレームワーク専用ウィジェット	クライアントディレクティブを指定したアイランド
画像ヘルパー	astro:assets またはプロジェクトで現在使用している画像方針

価値がある場合に限り、フレームワークのコンポーネントを残してください。静的コンテンツは通常、.astro にしてください。

4. ルーティングとデータフローを再構築する

移行する各範囲について、次の作業を行ってください。

• src/pages/ にルートを再作成する
• 共有ラッパーを src/layouts/ に移動する
• 構造化コンテンツを src/content/ に移行する
• フレームワーク固有のデータ取得パターンを Astro のフロントマターまたはコンテンツ API に置き換える

以前のページが getStaticPaths 形式のルート生成を使用していた場合は、古いフレームワークのライフサイクルを再現するのではなく、Astro で明示的に再構築してください。

5. インタラクティブ機能をアイランドとして扱う

意図的な互換性ブリッジとして使用するのでない限り、フレームワークアプリ全体を変更せずに Astro に移植しないでください。

代わりに、次のようにしてください。

• 静的シェルを .astro にする
• インタラクティブなアイランドにはフレームワークのコンポーネントを残す
• クライアントディレクティブを意図的に選ぶ
• ハイドレーションの対象範囲を最小限にする

6. 動作とリグレッションを検証する

少なくとも次の項目を確認してください。

• ルートの同等性
• メタデータと head の出力
• 画像のレンダリング
• フォームの動作
• キーボードナビゲーション
• ビルドとプレビューの動作
• デプロイに関する前提条件

Astro のアップグレードに関するガイダンス

Astro から Astro へのアップグレードでは、次の点に従ってください。

• 公式のアップグレードガイドから始め、リポジトリに適している場合は npx @astrojs/upgrade を使用する
• 公式のインテグレーションとアダプターは、後回しにせず Astro と同時に更新する
• コードレベルの問題をデバッグする前に、ローカルとデプロイ先のランタイムが現在の Node 要件を満たしていることを確認する
• アップグレード後にコンテンツ、ルーティング、ビルドのチェックを再実行する

Astro 6 では、次の変更点を確認してください。

• Node ランタイム：Astro 6 には Node 22.12.0 以降が必要です
• コンテンツコレクション：src/content.config.* を使用し、すべてのコレクションに loader を定義し、type を削除し、astro/zod から z をインポートし、slug の代わりに entry.id を使用し、entry.render() を render(entry) に置き換える
• レガシーコレクションフラグ：legacy.collections の設定があれば削除する
• ファイルのクエリ：コンテンツコレクションでは Astro.glob() を import.meta.glob() または getCollection() に置き換える
• ビュートランジション：プロジェクトに <ViewTransitions /> が残っている場合は <ClientRouter /> に置き換える
• getStaticPaths()：Astro.generator を削除し、getStaticPaths() 内で Astro.site が使われている場合は import.meta.env.SITE に置き換える
• カスタムスキーマ：アップグレード後に検証が失敗する場合は、カスタム Zod の使用箇所を Zod 4 に照らして確認する

破壊的変更については、バージョン固有のドキュメントを参照してください。以前の移行ガイダンスが現在の Astro リリースにも適用されると想定しないでください。