astro について
Astro は、コンテンツ中心の高速なサイトを構築するための Web フレームワークを扱うスキルです。コンテンツコレクション、レンダリング方式、アイランド構成、各種 UI フレームワークとの連携を開発者に案内します。
主な機能
- 01コンテンツコレクションと型付きクエリ
- 02アイランド構成とハイドレーション方式
- 03静的・サーバー・ハイブリッドレンダリング
- 04React、Svelte、Vue、Solid、Preact との連携
- 05ミドルウェア、ルート、画面遷移
活用シーン
- 01ブログ、ドキュメント、マーケティングサイトの構築
- 02静的ページへのインタラクティブなコンポーネント追加
- 03静的・サーバー・ハイブリッド方式の選択
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/astroを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
references/astro-db.mdcontent-collections.mdframework-integration.mdisland-architecture.mdmiddleware.mdrendering-modes.mdview-transitions.md詳細
Astro
概要
Astro は、高速でコンテンツ重視のウェブサイトを構築するためのオールインワンのウェブフレームワークです。アイランドアーキテクチャを採用しており、デフォルトでは JavaScript を一切配信せず、インタラクティブなコンポーネントのみを必要に応じてハイドレーションします。React、Svelte、Vue、Solid、Preact のコンポーネントを1つのプロジェクト内で共存させることができます。
使用する場合： コンテンツ主導のサイト（ブログ、ドキュメント、マーケティングサイト）、ポートフォリオ、ECストアフロントなど、大部分のページが主に静的で、一部に独立したインタラクティブ領域があるサイト。
使用しない場合： 高度にインタラクティブなシングルページアプリケーション（ダッシュボード、リアルタイムコラボレーションツール）や、すべてのコンポーネントで共有されるグローバル状態を伴う、完全なクライアントサイドルーティングが必要なアプリ。
クイックリファレンス
| パターン | API／ディレクティブ | 主なポイント |
|---|---|---|
| コンテンツコレクション | defineCollection({ loader, schema }) | Zod スキーマ、glob／ファイルローダー、型安全なクエリ |
| コレクションのクエリ | getCollection('blog') | 型付き配列を返し、フィルターコールバックに対応 |
| 単一エントリー | getEntry('blog', 'my-post') | コレクション名とエントリー ID を指定して取得 |
| アイランド（読み込み） | <Component client:load /> | ページ読み込み時にすぐハイドレーション |
| アイランド（アイドル） | <Component client:idle /> | ブラウザーがアイドル状態のときにハイドレーション |
| アイランド（表示時） | <Component client:visible /> | コンポーネントがビューポートに入るとハイドレーション |
| アイランド（クライアントのみ） | <Component client:only="react" /> | SSR をスキップし、クライアントのみでレンダリング |
| ビュートランジション | <ClientRouter /> | <head> に追加すると、SPA のようなナビゲーションが可能 |
| 状態の維持 | transition:persist | ナビゲーションをまたいでアイランドの状態を維持 |
| プログラムからのナビゲーション | navigate(href) | スクリプトからクライアント側でナビゲーション |
| 静的出力 | output: 'static' | ビルド時にすべてのページを事前レンダリング（デフォルト） |
| サーバー出力 | output: 'server' | すべてのページをリクエストに応じてサーバーレンダリング |
| ハイブリッド（SSR をオプトイン） | output: 'static' + per-page prerender = false | デフォルトは静的、個別のページで SSR をオプトイン |
| ハイブリッド（静的出力をオプトイン） | output: 'server' + per-page prerender = true | デフォルトは SSR、個別のページで静的出力をオプトイン |
| サーバーアイランド | <Component server:defer /> | 静的コンテンツ内の動的コンテンツのサーバーレンダリングを遅延 |
| ミドルウェア | onRequest(context, next) | すべてのルートの前に実行され、sequence() でチェーン可能 |
| Astro DB テーブル | defineTable({ columns }) | カラム定義による型安全な SQL |
| フレームワークコンポーネント | .jsx／.svelte／.vue をインポート | ファイル拡張子から自動検出 |
| インテグレーション | astro add react | フレームワークアダプターとツールを追加する CLI |
| コンテンツのレンダリング | const { Content } = await entry.render() | Markdown／MDX をコンポーネントにコンパイル |
| 動的ルート | getStaticPaths() + コレクションクエリ | コレクションのエントリーからページを生成 |
| API エンドポイント | export const GET: APIRoute | サーバーレンダリングされる REST エンドポイント |
| アイランド間で共有する状態 | nanostores | フレームワークの境界を越えてリアクティブな状態を共有 |
| 環境変数 | import.meta.env.PUBLIC_* | クライアントからアクセス可能な変数には PUBLIC_ 接頭辞を使用 |
| トランジションアニメーション | transition:animate="slide" | initial、fade、slide、none |
| リンクのプリフェッチ | data-astro-prefetch | hover、viewport、load、または false |
| コレクション参照 | reference('authors') | 型安全なコレクション間リレーション |
| スクリプトの再実行 | data-astro-rerun | ビュートランジションによるナビゲーションのたびに <script> を再実行 |
| リダイレクト | context.redirect(url, status) | ミドルウェアまたはサーバーページからリダイレクト |
よくある間違い
| 間違い | 正しいパターン |
|---|---|
.astro コンポーネントに client: ディレクティブを追加する | client: を受け付けるのは UI フレームワークのコンポーネント（React、Svelte、Vue）のみです |
どこでも client:load を使う | デフォルトでは client:idle または client:visible を使い、client:load は必要な場合に限って使います |
client:only でフレームワーク文字列を忘れる | フレームワークの指定が必要です：client:only="react" |
| Astro 以外のファイルでフレームワークのコンポーネントを混在させる | 複数のフレームワークのコンポーネントを組み合わせられるのは .astro ファイルのみです |
ほとんどが静的なサイトで output: 'server' を使う | ハイブリッド構成では、ページごとに prerender = false を設定して output: 'static' を使います |
ビュー遷移で <ClientRouter /> を省略する | すべてのページの <head> 内に必要です（共有レイアウトを使います） |
コンテンツ設定が src/content.config.ts にない | ファイル名を content.config.ts とし、src/ のルートに配置する必要があります |
getCollection() の呼び出しを await しない | フロントマター内のコレクションクエリには必ず await を付けます |
クライアントスクリプトで astro:content からインポートする | コンテンツ API はサーバー専用です。データはクライアントコンポーネントに props として渡します |
ミドルウェアを src/middleware.ts の外に配置する | ミドルウェアは src/middleware.ts または src/middleware/index.ts に配置する必要があります |
| アイランドに関数を props として渡す | サーバー／クライアント間で受け渡せるのはシリアライズ可能なデータのみです |
対応するページがない状態で transition:persist を使う | コンポーネントは同じ persist 値で、新旧両方のページに表示される必要があります |
| サーバー／ハイブリッドモードでアダプターが不足している | アダプターをインストールします：npx astro add vercel（または node、netlify など） |
委任
- パターンの調査：
Exploreエージェントを使います - ビルド設定：
Taskエージェントを使います - コードレビュー：
code-reviewerエージェントに委任します
tailwindスキルが利用可能な場合は、スタイリングと Tailwind CSS の設定をそのスキルに委任します。vitestスキルが利用可能な場合は、ユニットテストのパターンをそのスキルに委任します。playwrightスキルが利用可能な場合は、エンドツーエンドテストのパターンをそのスキルに委任します。viteスキルが利用可能な場合は、ビルド設定と Vite プラグインのセットアップをそのスキルに委任します。drizzleスキルが利用可能な場合は、高度なデータベースクエリのパターンをそのスキルに委任します。sentryスキルが利用可能な場合は、エラー監視とオブザーバビリティの設定をそのスキルに委任します。pino-loggingスキルが利用可能な場合は、サーバーサイドのロギング設定をそのスキルに委任します。tanstack-queryスキルが利用可能な場合は、クライアントサイドのデータ取得とキャッシュをそのスキルに委任します。