astro-sites-manager

Astro Framework — v7

MCP ドキュメントへのアクセス

このスキルはAstro Docs MCP serverと連携して動作します。Astro に関する質問に回答する前に、astro-docs MCP ツールが利用可能か確認し、最新のドキュメントを照会してください。MCP サーバーは docs.astro.build にリアルタイムでアクセスでき、最新の API に関する唯一の信頼できる情報源です。

MCP Server: astro-docs
Tool: search_astro_docs

MCP サーバーが利用できない場合は、このスキルの参考資料と https://docs.astro.build を参照してください。

---

ベストプラクティス

コンポーネント設計

• ファイルごとに .astro コンポーネントを 1 つ作成します。コンポーネントは小さく、役割を絞ってください。
• データ取得とロジックにはフロントマター（---）を使い、その下のテンプレートにはマークアップのみを記述します。
• クライアント側のインタラクティブ性が必要な場合を除き、フレームワークコンポーネントより Astro コンポーネントを優先します。
• client:* ディレクティブは控えめに使います。それぞれバンドルに JavaScript が追加されます。
• ディレクティブの優先順位：client:idle > client:visible > client:load（遅延読み込みを優先）。

ルーティングとページ

• src/pages/ のファイルベースルーティングを使います。動的ルート：[slug].astro、[...path].astro。
• プリレンダリングする動的ルートでは、必ず getStaticPaths() をエクスポートします。
• SSR ページでは、先頭に export const prerender = false を記述します。
• ミドルウェアより高度な制御が必要な場合に限り src/fetch.ts（v7）を使います。単純な認証には使わないでください。

コンテンツコレクション

• content.config.ts で Zod を使ってスキーマを定義します。型付けされていないコンテンツを決して信頼しないでください。
• リストには getCollection()、単一の項目には getEntry() を使います。
• ローカルファイルには glob() ローダーを優先し、CMS データにはカスタムローダーを使います。

パフォーマンス

• デフォルトでは静的（prerender = true）にします。SSR はパーソナライズされたコンテンツや動的コンテンツに限って使います。
• astro:assets の <Image /> を使います。ローカル画像に生の <img> を使わないでください。
• Markdown には unified より Sätteri（v7 のデフォルト）を優先します。大幅に高速です。
• 静的なシェルと動的なフラグメントを組み合わせるには、Server Islands（server:defer）を使います。

スタイリング

• .astro ファイル内のスコープ付き <style> がデフォルトであり、推奨されます。
• 本当に必要な場合（サードパーティコンポーネントのスタイリングなど）に限り、is:global を使います。
• Tailwind は astro add tailwind でインストールし、手動で設定しないでください。

TypeScript

• コンテンツスキーマまたは環境変数を変更した後は、astro sync を実行します。
• コミット前に astro check を実行します。他のツールでは検出できないテンプレートの型エラーを見つけられます。
• 型付けされた環境変数には astro:env/server と astro:env/client を使います（process.env を直接使わないでください）。

開発ワークフロー

• HMR には astro dev を使います。python -m http.server やその他の静的サーバーは決して使わないでください。
• 公式インテグレーションには astro add を使い、設定を手動で編集しないでください。
• 本番環境での動作をローカルでテストするには、astro build && astro preview を使います。
• AI エージェントのワークフローでは、astro dev --background を使い、/_astro/status で検証します。

---

CLI コマンド

npx astro dev              # Dev server (foreground)
npx astro dev --background # Dev server (detached, for AI agents)
npx astro dev --json       # Dev server with JSON structured logs
npx astro build            # Production build
npx astro preview          # Serve production build locally
npx astro check            # Type checking and diagnostics
npx astro sync             # Generate TypeScript types
npx astro add <integration># Install and configure integration

バックグラウンド開発サーバー（AI エージェント）

AI エージェントとして作業する場合は、バックグラウンドモードを使います。

# Start (blocks until ready, then detaches)
astro dev --background
# → Dev server running at http://localhost:4321 (pid 12345)

# Check status
astro dev status

# Read logs
astro dev logs

# Stop
astro dev stop

# Health check endpoint (JSON)
curl http://localhost:4321/_astro/status
# → {"ok": true}

主な動作：

• ロックファイルによってインスタンスの重複を防ぎます。再度起動すると、既存のインスタンスが返されます。
• すべてのコマンドはべき等です（実行中でない場合の停止は、メッセージを出さずに成功します）。
• AI エージェント内で実行されている場合は自動検出されます（フラグは不要です）。
• 無効にするには：ASTRO_DEV_BACKGROUND=0 astro dev

---

プロジェクト構成

src/
├── pages/          # File-based routing (.astro, .md, .mdx)
├── layouts/        # Reusable page layouts
├── components/     # Astro & framework components
├── content/        # Content collections (type-safe)
├── middleware.ts   # Request middleware
├── fetch.ts        # Advanced routing (v7, optional)
├── styles/         # Global CSS
├── assets/         # Optimized assets (images, fonts)
├── actions/        # Server actions
└── env.d.ts        # Environment type declarations
astro.config.mjs    # Main configuration
content.config.ts   # Content collection schemas
tsconfig.json       # TypeScript config

---

設定（v7）

import { defineConfig, memoryCache, logHandlers } from 'astro/config';

export default defineConfig({
  // Output mode
  output: 'static', // or configure per-page with server adapter

  // Route caching (stable in v7)
  cache: {
    provider: memoryCache(),
  },
  routeRules: {
    '/blog/[...path]': { maxAge: 300, swr: 60 },
  },

  // Logger (stable in v7)
  logger: logHandlers.json(), // or .console(), or .compose(...)

  // Markdown (Sätteri is default in v7)
  markdown: {
    // No config needed for defaults (GFM, smartypants, heading IDs)
    // For extra features:
    // processor: satteri({ features: { directive: true, math: true } })
  },

  // Advanced routing file (default: src/fetch.ts)
  // fetchFile: null, // disable if src/fetch.ts is used for other purposes

  // Whitespace (v7 default: 'jsx')
  compressHTML: 'jsx', // or true (v6 behavior), or false (preserve all)
});

---

Islands アーキテクチャ（client:* ディレクティブ）

<Counter client:load />


<Newsletter client:idle />


<Comments client:visible />


<MobileMenu client:media="(max-width: 768px)" />


<MapWidget client:only="react" />


<UserGreeting server:defer />

判断ガイド： ディレクティブなし（デフォルト）なら JavaScript はゼロで、静的 HTML になります。ユーザー操作が必要な場合に限り、ディレクティブを追加してください。

---

画像の最適化

---
import { Image } from 'astro:assets';
import heroImage from '../assets/hero.jpg';
---

<Image src={heroImage} alt="Hero" width={1200} />


<Image src="https://cdn.example.com/photo.jpg" alt="Photo" width={800} height={600} />

リモート画像の設定：

// astro.config.mjs
image: {
  domains: ['cdn.example.com'],
  remotePatterns: [{ protocol: 'https', hostname: '**.cloudinary.com' }],
}

---

詳細リファレンス

• MCP サーバーのインストール — あらゆる AI ツール（Kiro、Claude、Cursor、VS Code など）向けの Astro Docs MCP のセットアップ
• v6→v7 移行ガイド — 破壊的変更のチェックリストを含む、段階的なアップグレード計画
• 検証チェックリスト — インストールの確認、破壊的変更や非推奨のパターンの検出
• AI 開発サーバー — バックグラウンドモード、JSON ロギング、エージェント検出
• Astro v7 の機能 — Rust コンパイラー、Sätteri、高度なルーティング、ルートキャッシュ、CDN プロバイダー
• Astro v6 の機能 — Content Collections v2、Actions、Sessions、Server Islands、env モジュール
• 関連コンテンツ — 関連投稿向けのベクトル埋め込み、モデルを使わずに Coolify へ軽量デプロイ
• テスト — Vitest コンポーネント、Playwright E2E、リンクチェック、CI パイプライン
• SEO フルスタック — JSON-LD グラフ、エージェントの検出、IndexNow、OG 画像、ビルド時の検証、パフォーマンス
• Starlight とパターン — ドキュメントサイト、Pagefind 検索、i18n、ページネーション、RSS
• デプロイ — Cloudflare、Vercel、Netlify、Firebase、GitHub Pages、Docker/Coolify、Azure
• Coolify へのデプロイ — Coolify へのセルフホスト可能なデプロイ（Dockerfile、API、注意点、推奨スタック）