add-integration

Astro インテグレーションの追加

UI フレームワーク、スタイリングツール、アダプター、コンテンツツール、ユーティリティなど、Astro プロジェクトに公式またはコミュニティ製のインテグレーションを追加する際に、このスキルを使用します。

astro-best-practices が利用できる場合は、パフォーマンス、アクセシビリティ、ハイドレーションのデフォルト設定に関して、このスキルと併せて適用してください。

ワークフロー

1. インテグレーションを分類する

変更を加える前に、追加するものを特定します。

• UI フレームワーク：React、Vue、Svelte、Preact、Solid
• スタイリング：Tailwind、UnoCSS、Sass、CSS ツール
• デプロイアダプター：Netlify、Vercel、Cloudflare、Node
• コンテンツツール：MDX、Markdoc、CMS インテグレーション
• ユーティリティ：サイトマップ、Partytown、アナリティクス、データベースヘルパー

これにより、変更がレンダリングモード、ハイドレーション、設定の構成、またはビルド出力に影響するかどうかが決まります。

2. Astro 公式の方法を優先する

公式インテグレーションで対応している場合は、astro add を使用します。

npx astro add react
npx astro add tailwind
npx astro add netlify

コミュニティがメンテナンスするインテグレーションの場合は、プロジェクトのパッケージマネージャーでインストールし、astro.config.* に手動で組み込みます。

仕上げる前に、Astro やインテグレーションのバージョンが最近変更されている場合は特に、Astro の公式ドキュメントまたはインテグレーションの README で現在の設定を確認してください。

プロジェクトで Astro 自体もアップグレードする場合は、Astro と公式インテグレーションをまとめてアップグレードしてください。Astro 6 の場合は、インテグレーションの問題をアプリケーションのバグとして扱う前に、環境で Node 22.12.0 以降が実行されていることを確認してください。

3. Astro の設定を意図的に行う

astro.config.* を編集する際は、次の点に注意してください。

• インテグレーションを明示的に追加し、配列を読みやすく保つ
• アダプターまたはランタイムが必要とする場合にのみ output を設定する
• リクエスト時の処理が実際に必要な機能でない限り、サーバー出力を有効にしない
• インテグレーションのドキュメントで特定の順序が求められていない限り、既存の設定順序を維持する

例：

import { defineConfig } from 'astro/config'
import react from '@astrojs/react'

export default defineConfig({
  integrations: [react()],
})

4. フレームワークコンポーネントは必要な範囲で使用する

React、Vue、その他の UI フレームワークを追加する場合は、次の点に注意してください。

• 静的コンテンツには .astro を優先する
• インタラクティブアイランドにはフレームワークコンポーネントを使用する
• UX の要件を満たす範囲で最も軽いクライアントディレクティブを選ぶ

ハイドレーションの指針：

• ファーストビューより下にある UI や遅延させる UI には client:visible
• 重要ではない拡張機能には client:idle
• すぐに操作可能な UI に限り client:load
• サーバーレンダリングを意図的に省略する場合に限り client:only

5. 周辺設定も仕上げる

パッケージをインストールしただけで終わらせないでください。次の項目を確認します。

• スタイルシートのインポートまたはエントリーポイント
• 環境変数
• tailwind.config.* などの設定ファイル
• アダプター固有の出力要件
• プラットフォームのデプロイ設定

Tailwind v4 では、最小限の設定は多くの場合、次だけです。

@import "tailwindcss";

さらに、そのスタイルシートを共有レイアウトまたはエントリーポイントからインポートします。

6. 結果を検証する

設定後は、次の点を確認します。

• インテグレーションが astro.config.* に登録されていることを確認する
• astro check、astro build、既存のテストスイートなど、リポジトリに適したチェックを実行する
• Astro のメジャーアップグレード後も、デプロイ先／ランタイム環境がアダプターの要件に適合していることを確認する
• ハイドレーションの不整合、スタイルの欠落、アダプターとランタイムの不整合がないか調べる

よくある失敗例

• パッケージをインストールしたものの、integrations に追加していない
• output を合わせずにアダプターを追加している
• スタイルが用意されているものの、インポートされていない
• 単純な .astro コンポーネントで済む箇所に、フレームワークコンポーネントを追加している
• client:load を使いすぎて、JavaScript のコストが増えている