AstroとReact Islandsのセットアップ

Astro プロジェクトの初期セットアップには npx create astro@latest を使用します。このコマンドを実行すると、テンプレート、TypeScript の設定、パッケージマネージャーを選択する対話型ウィザードが起動します。Astro では、空のテンプレート、ブログテンプレート、ドキュメントテンプレートなど、複数のスターターを利用できます。

Astro のインテグレーションを使うと、プロジェクトにフレームワークのサポートを追加できます。npx astro add react を実行すると、@astrojs/react、react、react-dom が自動的にインストールされ、React インテグレーションを含めるように astro.config.mjs も更新されます。セットアップ全体が1つのコマンドで完了します。

.astro ファイルは Astro のコンポーネント形式です。フロントマターセクション（--- で囲まれた JavaScript）とテンプレートセクションで構成されます。デフォルトでは、Astro ファイルは静的 HTML を出力します。クライアントディレクティブを明示的に追加しない限り、ブラウザに JavaScript は送信されません。

Astro ファイルに React コンポーネントをインポートするには、標準の ES モジュール構文を使用します：import Counter from './Counter.jsx'。クライアントディレクティブがない場合、Astro は React コンポーネントを静的 HTML としてサーバーレンダリングし、その HTML をブラウザに送信します。このコンポーネント用の JavaScript は一切配信されません。

Astro テンプレートのコンポーネントタグに client:visible を追加すると、そのコンポーネントがアイランドになります：<Counter client:visible />。これで Astro は Counter の JavaScript を配信し、コンポーネントが表示領域に入ったときにハイドレーションして、インタラクティブにします。ディレクティブがなければ、静的 HTML のままです。

Astro のアイランドとして使用する React コンポーネントは、標準の React で記述します。フック、state、エフェクト、任意の React ライブラリを使用できます。React コンポーネント自体には Astro 固有の API はありません。アイランドの境界はコンポーネントのコード内ではなく、Astro テンプレートで定義します。

各アイランドのインスタンスは独立した React ツリーです。同じページにある2つの Counter アイランドが状態を共有することはありません。状態を共有する必要がある場合は、1つのアイランドにまとめる、シリアライズ可能な状態に URL の検索パラメーターを使う、nanostores のような共有状態ライブラリを使う、という3つの方法があります。

@nanostores/react ライブラリは、どのアイランドからでも購読できる軽量な atom を提供します。あるアイランドが nano store の atom に書き込み、別のアイランドがそれを読み取ります。nano stores はフレームワークに依存しないため、このパターンは同じページ上の React アイランドと Vue アイランドの間でも機能します。

Astro のコンテンツコレクションは、Markdown ファイルと MDX ファイルを型安全に管理する方法を提供します。Zod でコレクションのスキーマを定義し、Markdown ファイルを src/content/ に配置すると、Astro が完全に型付けされたクエリ関数を生成します。これはブログ記事、ドキュメント、プロダクトページで標準的に使われるパターンです。

astro build を実行すると、静的 HTML ファイルが入った dist/ フォルダーが生成されます。Astro は各ページについて、サーバーレンダリングされたコンテンツを含む HTML ファイルと、そのページのアイランドに必要な JavaScript バンドルだけを出力します。アイランドのないページからは JavaScript が一切出力されません。

静的な出力は、サーバーなしで任意の CDN（Netlify、Vercel、Cloudflare Pages）にデプロイできます。サーバーサイドレンダリングが必要な場合（動的ルートや API エンドポイントなど）、Astro は Node.js、Vercel Edge、Cloudflare Workers、Deno 用の SSR アダプターをサポートしています。どちらのモードでもアイランドは同じように機能します。

インポートした React コンポーネントをクライアント側でインタラクティブにするには、Astro テンプレートでどのような最小限の変更が必要ですか？

npx astro add react を使って Astro に React をセットアップします。Astro ファイルはデフォルトで静的ですが、React コンポーネントのタグに client: ディレクティブを追加すると、ハイドレーションされるアイランドになります。React コンポーネントは標準の React であり、Astro 固有の API はありません。状態はアイランドごとに分離され、nanostores によってアイランド間の通信が可能になります。ビルドでは静的 HTML と、そのページのアイランドに必要な JavaScript だけが出力されます。