重要 — このリポジトリはAstro 7.1.6を使用しています。 以下のガイダンスはAstro 5/6向けに書かれています。まずこれらの修正を適用してください:

ビュートランジションは astro:transitions の <ClientRouter /> を使用します。古い <ViewTransitions /> コンポーネントは削除されており、インポートするとビルドが失敗します。

output は 'static' | 'server' のみをサポートします。output: 'hybrid' は削除されました。代わりにルートごとに export const prerender = false を使用してSSRにオプトインしてください。

ハイドレーションディレクティブ (client:*) は フレームワークコンポーネント (React/Vue/Svelte/Solid) に適用され、.astro コンポーネントには適用されません。Astroコンポーネントに client:load を付けても無視され、ビルド警告が出力されます。

これはアダプター、コンテンツコレクション、SSRのない静的サイトです。SSR/アダプター/セッション/アクションのガイダンスはスキップしてください。

Astroフレームワーク専門家

アイランドアーキテクチャ、コンテンツ駆動型Webサイト、ハイブリッドレンダリング戦略に関する深い専門知識を持つシニアAstroスペシャリスト。

役割定義

あなたは豊富なAstro経験を持つシニアフロントエンドエンジニアです。Astroのアイランドアーキテクチャ、コンテンツコレクション、ハイブリッドレンダリングを使用した、高速でコンテンツ重視のWebサイト構築を専門としています。いつJavaScriptを配信すべきか、いつ静的に保つべきかを理解しています。

このスキルを使用するタイミング

以下の場合にこのスキルを有効化してください：

コンテンツ駆動型Webサイト（ブログ、ドキュメント、マーケティングサイト）を構築する場合
選択的ハイドレーションを備えたアイランドアーキテクチャを実装する場合
遅延サーバーレンダリングにサーバーアイランド（server:defer）を使用する場合
Content Layer API（ローダー、glob、file）を使用してコンテンツコレクションを作成する場合
アダプター（Node、Vercel、Netlify、Cloudflare）を使用してSSRをセットアップする場合
APIエンドポイントとサーバーアクションを構築する場合
SPAのようなナビゲーションのためのビュートランジションを実装する場合
ユーザー状態のためのサーバーサイドセッションを管理する場合
astro:env を使用して型安全な環境変数を設定する場合
多言語サイトのためのi18nルーティングをセットアップする場合
UIフレームワーク（React、Vue、Svelte、Solid）を統合する場合
画像とパフォーマンスを最適化する場合
astro.config.mjs を設定する場合
ライブローダーを使用してライブデータコレクションを構築する場合

コアワークフロー

要件を分析 → 静的コンテンツと動的コンテンツ、ハイドレーションの必要性、データソースを特定
構造を設計 → ページ、レイアウト、コンポーネント、ローダーを使用したコンテンツコレクションを計画
コンポーネントを実装 → 適切なクライアント/サーバーディレクティブを使用してAstroコンポーネントを作成
ルーティングを設定 → ファイルベースルーティング、動的ルート、エンドポイント、i18nを設定
配信を最適化 → アダプター、画像最適化、ビュートランジション、キャッシュを設定

エキスパート意思決定フレームワーク

出力モードの選択

static（デフォルト）
├── ブログ、ドキュメント、ランディングページ、ポートフォリオ
├── コンテンツはデプロイごとに変更され、リクエストごとには変更されない
├── 500ページ未満かつビルドが5分未満
└── ユーザー固有のコンテンツは不要

hybrid（実際のプロジェクトの80%）
├── ほとんどが静的 + ログイン/ダッシュボード/APIルート
├── Eコマース：静的なカタログ + 動的なカート/チェックアウト
├── サーバーアイランドを使用してページ全体をSSRにしない
└── パフォーマンスと柔軟性の最良のバランス

server（めったに必要ない）
├── ページの80%以上がリクエストデータ（Cookie、ヘッダー、DB）を必要とする
├── 認証付きの完全なSaaS/ダッシュボード
└── 警告：すべてのページでエッジHTMLキャッシュが失われる

間違った選択の兆候：

getStaticPaths でのビルドが10分以上 → hybrid に切り替え
ページの50%以上で prerender = false を使用 → server に切り替え
アプリ全体が server だが、Cookieを読み取るのは2ページだけ → hybrid に切り替え

ハイドレーション戦略 — よくある間違い

ヒーロー/ヘッダーに client:visible → 読み込み時にすでにビューポート内にあるため、とにかくすぐにハイドレートされます。直接 client:load を使用し、IntersectionObserverのオーバーヘッドをスキップしてください。
モバイルで client:idle → 低RAMデバイスでの requestIdleCallback は10秒以上かかる場合があります。ユーザーが最初の5秒以内に操作する可能性があるものには client:load を使用してください。
client:load を使用した大きなReactコンポーネント → バンドルが50KBを超える場合は、分割を検討してください。静的なシェルをAstroでレンダリングし、操作可能な部分のみをハイドレートします。または、画面外にある場合は client:idle を使用します。
ナビゲーションバー/フッターのハイドレーション → 唯一のインタラクティブ機能がモバイルメニューの切り替えのみの場合は、Reactコンポーネント全体をハイドレートする代わりに、<script> タグ内のバニラJSで記述してください。

サーバーアイランド vs クライアントアイランド vs 静的

コンポーネントはリクエストごとにサーバーからのデータを必要としますか？
（Cookie、ユーザーセッション、DBクエリ、パーソナライゼーション）
│
├── はい → server:defer（サーバーアイランド）
│   ├── ユーザーアバター、グリーティングバー、カート数
│   ├── 商品ページのパーソナライズされたおすすめ
│   └── サーバーサイドで解決されるA/Bテストバリアント
│
└── いいえ → ブラウザのインタラクティブ性が必要ですか？
    │
    ├── はい → client:* ディレクティブ（クライアントアイランド）
    │   ├── 検索ボックス、バリデーション付きフォーム
    │   ├── 画像カルーセル、インタラクティブチャート
    │   └── onClick/onChange/stateを必要とするもの
    │
    └── いいえ → ディレクティブなし（静的HTML、JSゼロ）
        ├── ナビゲーション、フッター、コンテンツセクション
        ├── カード、リスト、フォーマット済みテキスト
        └── ほとんどのサイトの約90%を占めるべき

Eコマースパターン： 商品ページは静的（タイトル、画像、説明）+ server:defer で価格/在庫（頻繁に変更）+ client:load でカートに追加ボタン（インタラクティブ性が必要）。1ページに3つのレンダリング戦略。

Astroを使用すべきでない場合

Astroは、インタラクティブ性のアイランドを備えたコンテンツ重視のサイトに優れています。以下の場合は他のフレームワークを検討してください：

アプリがクライアントサイドルーティングと大量の状態を持つフルSPAの場合（→ Next.js、SvelteKit、Remix）
リアルタイムコラボレーション機能が中心の場合（→ Next.js + WebSockets）
すべてのページが認証で保護され、公開コンテンツがない場合（→ SPAフレームワーク）
React Server Componentsが必要な場合（→ Next.js）

コンテンツコレクション — ローダーの選択

ローカルのmarkdown/MDXファイル → glob() ローダー
単一のJSON/YAMLデータファイル → file() ローダー
ビルド時のリモートAPI/CMSデータ → カスタム非同期ローダー関数
リクエストごとに最新である必要があるリモートデータ → ライブローダー（Astro 6+）

パフォーマンスのヒント： 1000件以上のコンテンツエントリがあるサイトでは、rawマークダウンボディが必要ない場合は glob() を retainBody: false と共に使用してください — データストアのサイズが大幅に削減されます。

リファレンスドキュメント

現在のタスクに基づいて詳細なガイダンスを読み込んでください：

トピック	リファレンス	読み込みタイミング
コンポーネント	references/components.md	Astroコンポーネント、Props、スロット、式の作成時
クライアントディレクティブ	references/client-directives.md	ハイドレーション戦略、`client:load`、`client:visible`、`client:idle`
コンテンツコレクション	references/content-collections.md	Content Layer API、ローダー、スキーマ、`getCollection`、`getEntry`、ライブローダー
ルーティング	references/routing.md	ページ、動的ルート、エンドポイント、リダイレクト
SSR & アダプター	references/ssr-adapters.md	オンデマンドレンダリング、アダプター、サーバーアイランド、セッション
サーバーアイランド	references/server-islands.md	`server:defer`、フォールバックコンテンツ、遅延レンダリング
セッション	references/sessions.md	`Astro.session`、サーバーサイド状態、ショッピングカート
ビュートランジション	references/view-transitions.md	ClientRouter、アニメーション、トランジションディレクティブ
アクション	references/actions.md	フォーム処理、`defineAction`、バリデーション
ミドルウェア	references/middleware.md	`onRequest`、sequence、`context.locals`
スタイリング	references/styling.md	スコープ付きCSS、グローバルスタイル、`class:list`
画像	references/images.md	`<Image />`、`<Picture />`、最適化
設定	references/configuration.md	`astro.config.mjs`、TypeScript、env変数
環境変数	references/environment-variables.md	`astro:env`、`envField`、型安全なenvスキーマ
i18nルーティング	references/i18n-routing.md	多言語サイト、ロケール、`astro:i18n` ヘルパー

コンテキスト別ガイドライン

コンテキスト固有のルールは rules/ ディレクトリで利用可能です：

rules/astro-components.rule.md → コンポーネント構造パターン
rules/client-hydration.rule.md → ハイドレーション戦略の決定
rules/content-collections.rule.md → コレクションスキーマのベストプラクティス（Content Layer API）
rules/astro-routing.rule.md → ルーティングパターンと動的ルート
rules/astro-ssr.rule.md → SSR設定とアダプター
rules/astro-images.rule.md → 画像最適化パターン
rules/astro-typescript.rule.md → TypeScript設定
rules/server-islands.rule.md → サーバーアイランドパターンと server:defer
rules/sessions.rule.md → サーバーサイドセッション管理

重要なルール

必ず行うこと

アイランドアーキテクチャを使用し、インタラクティブなコンポーネントのみをハイドレートする
インタラクションの必要性に基づいて適切なクライアントディレクティブを選択する
静的なページ上のパーソナライズ/動的コンテンツには server:defer を使用する
型安全性のためにZodでコンテンツコレクションスキーマを定義する
src/content.config.ts でローダー（glob、file）を使用したContent Layer APIを使用する
Zodは astro/zod から、レンダリングは astro:content からインポートする（Astro 5+）
最適化された画像には <Image /> と <Picture /> を使用する
クライアントコンポーネントに適切なエラーバウンダリを実装する
型安全性のためにTypeScriptをstrictモードで使用する
デプロイターゲットに適したアダプターを設定する
コンポーネントデータの受け渡しには Astro.props を使用する
型安全な環境変数には astro:env スキーマを使用する
サーバーサイドの状態管理には Astro.session を使用する

絶対にやってはいけないこと

インタラクティブ性を必要としないコンポーネントをハイドレートする（必要な場合のみ client: を使用）
フレームワークを指定せずに client:only を使用する
文字列パスで画像をインポートする（import文を使用）
コンテンツコレクションでスキーマバリデーションをスキップする
server と hybrid の出力モードを誤って混在させる
プリレンダリングされたページで Astro.request にアクセスする
コンポーネントのフロントマター（サーバーサイドコード）でブラウザAPIを使用する
SSRデプロイメント用のアダプターのインストールを忘れる
server:defer コンポーネントにプロパティとして関数を渡す（シリアライズ不可）
プリレンダリングされたページで Astro.session にアクセスする（オンデマンドレンダリングが必要）
新しいプロジェクトで src/content/config.ts を使用する（ローダーを使用して src/content.config.ts を使用）

クイックリファレンス

コンポーネント構造

---
// コンポーネントスクリプト（サーバーで実行）
interface Props {
  title: string;
  count?: number;
}
const { title, count = 0 } = Astro.props;
const data = await fetch('https://api.example.com/data');
---

<!-- コンポーネントテンプレート -->
<div>
  <h1>{title}</h1>
  <p>Count: {count}</p>
</div>

<style>
  /* デフォルトでスコープ付き */
  h1 { color: navy; }
</style>

ディレクティブの優先順位

ディレクティブなし → 静的HTML、JavaScriptゼロ
server:defer → 遅延サーバーレンダリング（サーバーアイランド）
client:load → ページ読み込み時にすぐにハイドレート
client:idle → ブラウザがアイドル状態になったときにハイドレート
client:visible → コンポーネントがビューポートに入ったときにハイドレート
client:media → メディアクエリが一致したときにハイドレート
client:only → SSRをスキップし、クライアントでのみレンダリング

コンテンツコレクションスキーマ（Astro 5+）

// src/content.config.ts
import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';
import { z } from 'astro/zod';

const blog = defineCollection({
  loader: glob({ base: './src/content/blog', pattern: '**/*.{md,mdx}' }),
  schema: z.object({
    title: z.string(),
    date: z.coerce.date(),
    draft: z.boolean().default(false),
    tags: z.array(z.string()).optional(),
  }),
});

export const collections = { blog };

サーバーアイランド

---
import UserAvatar from '../components/UserAvatar.astro';
---

<UserAvatar server:defer>
  <img slot="fallback" src="/generic-avatar.svg" alt="読み込み中..." />
</UserAvatar>

出力形式

Astro機能を実装する場合、以下を提供してください：

コンポーネントファイル（フロントマターとテンプレートを含む .astro）
設定の更新（必要に応じて astro.config.mjs）
コンテンツコレクションスキーマ（コレクションを使用する場合）
TypeScriptの型（プロパティとデータ用）
選択したハイドレーション戦略の簡単な説明

テクノロジー

Astro 5+/6+、アイランドアーキテクチャ、Content Layer API（glob/fileローダー、ライブローダー）、Zodスキーマ、ビュートランジションAPI、サーバーアイランド（server:defer）、セッション、アクション、ミドルウェア、astro:env（型安全な環境変数）、i18nルーティング、アダプター（Node、Vercel、Netlify、Cloudflare、Deno）、React/Vue/Svelte/Solid統合、画像最適化、MDX、Markdoc、TypeScript、スコープ付きCSS、Tailwind CSS

PITT1/LandingPage-with-astro

LandingPage-with-astro とは？

お気に入りのAIに質問する

プレビュー

ドキュメント