Astro完全実践ガイド〜Islands Architecture・Content Collections・SSR/SSG・View Transitions【2026年版】〜

Webサイトを作るとき、Reactのような豪華なフレームワークを使うと「JSバンドルが重い」「初回表示が遅い」「SEOで不利」と感じたことはないでしょうか。逆にHugoや素のHTMLでは「動的なUIが書きにくい」「コンポーネント分割が面倒」「TypeScriptが効かない」といった不満が出ます。Astroはこの両極端を綺麗に橋渡しするフレームワークで、「必要な場所にだけJSを送る」というIslands Architectureを採用し、デフォルトでJSゼロ、必要に応じてReact/Vue/Svelte/Solidなど好きなUIライブラリのコンポーネントをそのまま使えるという独特の立ち位置を築いています。本記事では Astro 5.x を前提に、プロジェクト作成からIslands、Content Collections、SSR/SSG、View Transitions、Image最適化、デプロイまでをすべてコピペで動くコード付きで一気通貫に解説します。Next.jsやRemixと迷っているフロントエンドエンジニアにとって、判断材料として役立てば幸いです。

1. Astroのインストールとプロジェクト初期化
2. プロジェクト構造と .astro ファイルの基本
3. コンポーネント・Props・Slot・Layout
4. Islands Architectureとclientディレクティブ
5. Content Collections と型安全なMarkdown管理
6. ファイルベースルーティングと動的ルート
7. SSG / SSR / ハイブリッドモードの切り替え
8. Middleware と View Transitions
1. 8.1 src/middleware.ts
2. 8.2 ViewTransitions でSPA風遷移
9. Markdown / MDX サポート
10. Image最適化・Sitemap・RSS
11. Tailwind連携とAstro DB
1. 11.1 Tailwind v4 を入れる
2. 11.2 Astro DB(SQLiteベース)
12. デプロイ(Vercel / Netlify / Cloudflare)
13. Astro vs Next.js vs Hugo の使い分け
14. 実務で効くチューニングとベストプラクティス
15. FAQ:よくある詰まりどころ
まとめ:Astroは「軽さ」と「自由度」を両立できる選択肢

1. Astroのインストールとプロジェクト初期化

Astroのインストールは公式CLIを使うのが最速です。Node.js 18.20.8以上、もしくは20.3以上、22以上が必要なので、最初に node -v でバージョンを確認しておきましょう。

1.1 create astro でプロジェクトを生成する

# 公式CLIで対話形式に作成
npm create astro@latest my-astro-site

# 非対話モード(CIや自動化向け)
npm create astro@latest my-astro-site -- --template minimal --typescript strict --install --git

cd my-astro-site
npm run dev

テンプレートは minimal / basics / blog / portfolio などが用意されています。blog はContent Collectionsの実例が最初から組み込まれているので、勉強用には特におすすめです。

1.2 package.json の基本スクリプト

{
  "name": "my-astro-site",
  "type": "module",
  "version": "0.0.1",
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro",
    "check": "astro check"
  },
  "dependencies": {
    "astro": "^5.4.0"
  }
}

1.3 生成された tsconfig.json

{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"],
  "compilerOptions": {
    "jsx": "preserve",
    "baseUrl": ".",
    "paths": {
      "~/*": ["src/*"]
    }
  }
}

2. プロジェクト構造と .astro ファイルの基本

2.1 標準のディレクトリ構成

my-astro-site/
├── public/             # そのまま配信される静的ファイル
│   └── favicon.svg
├── src/
│   ├── components/     # 再利用するUIコンポーネント
│   ├── content/        # Content Collections のMarkdown/MDX
│   │   └── config.ts
│   ├── layouts/        # ページ全体のレイアウト
│   ├── pages/          # ファイルベースルーティング
│   │   └── index.astro
│   ├── styles/         # グローバルCSS
│   └── env.d.ts        # 型定義
├── astro.config.mjs    # Astro本体の設定
├── tsconfig.json
└── package.json

2.2 最小の .astro ファイル

AstroコンポーネントはFrontmatter Script(2本のダッシュで囲まれたJS/TSブロック)とHTMLテンプレートの2層構造で、見た目はSvelteや昔のPHPに近い感覚です。Frontmatter Scriptはビルド時(またはSSRリクエスト時)に1回だけ実行され、出力にJSが残らないのが特徴です。

---
// src/pages/index.astro
// ↑ここは「Frontmatter Script」。サーバ側でだけ実行される
const title = "Astro入門ページ";
const items = ["Islands", "Content Collections", "View Transitions"];
---
<html lang="ja">
  <head>
    <meta charset="utf-8" />
    <title>{title}</title>
  </head>
  <body>
    <h1>{title}</h1>
    <ul>
      {items.map((item) => <li>{item}</li>)}
    </ul>
  </body>
</html>

2.3 JSXとの違いに注意する

---
const isActive = true;
const tags = ["astro", "ssg"];
---
<!-- class はそのまま class でOK(React と違って className 不要) -->
<div class={isActive ? "active" : "inactive"}>
  <!-- スタイルもkebab-caseのまま -->
  <p style="font-size: 14px; color: tomato;">こんにちは</p>

  <!-- 配列の展開 -->
  <ul>
    {tags.map((t) => <li>#{t}</li>)}
  </ul>

  <!-- フラグメント -->
  <>
    <span>A</span>
    <span>B</span>
  </>
</div>

3. コンポーネント・Props・Slot・Layout

3.1 Props と Astro.props

---
// src/components/Card.astro
interface Props {
  title: string;
  href: string;
  badge?: string;
}
const { title, href, badge } = Astro.props;
---
<a class="card" href={href}>
  <h3>{title}</h3>
  {badge && <span class="badge">{badge}</span>}
</a>

<style>
  .card {
    display: block;
    padding: 1rem;
    border: 1px solid #ddd;
    border-radius: 8px;
    text-decoration: none;
    color: inherit;
  }
  .badge {
    background: #ffe58f;
    padding: 0.1rem 0.5rem;
    border-radius: 999px;
    font-size: 0.8rem;
  }
</style>

3.2 利用する側(子コンポーネントとして読み込む)

---
// src/pages/index.astro
import Card from "../components/Card.astro";
---
<main>
  <Card title="Astro公式" href="https://astro.build" badge="New" />
  <Card title="ドキュメント" href="https://docs.astro.build" />
</main>

3.3 slot による差し込み

---
// src/components/Panel.astro
const { heading } = Astro.props;
---
<section class="panel">
  <header>
    <slot name="header"><h2>{heading}</h2></slot>
  </header>
  <div class="body">
    <slot /> {/* デフォルトスロット */}
  </div>
  <footer>
    <slot name="footer" />
  </footer>
</section>

---
import Panel from "../components/Panel.astro";
---
<Panel heading="お知らせ">
  <h2 slot="header">カスタムヘッダー</h2>
  <p>ここが本文に差し込まれます。</p>
  <small slot="footer">2026-05-27 更新</small>
</Panel>

3.4 layout(共通レイアウト)

---
// src/layouts/BaseLayout.astro
interface Props {
  title: string;
  description?: string;
}
const { title, description = "Astro入門サンプル" } = Astro.props;
---
<!doctype html>
<html lang="ja">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    <meta name="description" content={description} />
    <title>{title}</title>
  </head>
  <body>
    <header><a href="/">Home</a></header>
    <main>
      <slot />
    </main>
    <footer>© 2026 my-astro-site</footer>
  </body>
</html>

---
// src/pages/about.astro
import BaseLayout from "../layouts/BaseLayout.astro";
---
<BaseLayout title="About | my-astro-site">
  <h1>このサイトについて</h1>
  <p>AstroとIslands Architectureの学習用サンプルです。</p>
</BaseLayout>

4. Islands Architectureとclientディレクティブ

Astroの核心は Islands Architectureです。ページ全体は静的HTMLとして出力し、動きが必要な「島」だけにJSをハイドレーションする発想で、Next.jsのデフォルトのような「ページまるごとJSハイドレート」とは正反対のアプローチを取ります。

4.1 React/Vue/Svelte 統合を追加する

# 公式CLIで追加(astro.config.mjsへの記述まで自動)
npx astro add react
npx astro add vue
npx astro add svelte
npx astro add solid

4.2 astro.config.mjs に integrations が入る

// astro.config.mjs
import { defineConfig } from "astro/config";
import react from "@astrojs/react";
import vue from "@astrojs/vue";
import svelte from "@astrojs/svelte";

export default defineConfig({
  site: "https://example.com",
  integrations: [react(), vue(), svelte()],
});

4.3 React コンポーネント例(Counter)

// src/components/Counter.tsx
import { useState } from "react";

interface Props {
  initial?: number;
  label?: string;
}

export default function Counter({ initial = 0, label = "Count" }: Props) {
  const [count, setCount] = useState(initial);
  return (
    <div className="counter">
      <span>{label}: {count}</span>
      <button onClick={() => setCount(count + 1)}>+1</button>
      <button onClick={() => setCount(count - 1)}>-1</button>
    </div>
  );
}

4.4 clientディレクティブで「島」を起動する

---
// src/pages/islands.astro
import Counter from "../components/Counter.tsx";
---
<h1>Islands Demo</h1>

<!-- 1. ハイドレートしない(JS不要・静的HTMLだけ) -->
<Counter initial={1} label="Static" />

<!-- 2. 即座にハイドレート -->
<Counter client:load initial={2} label="Load" />

<!-- 3. ブラウザがアイドルになってからハイドレート -->
<Counter client:idle initial={3} label="Idle" />

<!-- 4. 画面に入ったらハイドレート -->
<Counter client:visible initial={4} label="Visible" />

<!-- 5. メディアクエリ一致時のみハイドレート -->
<Counter client:media="(max-width: 600px)" initial={5} label="Media" />

<!-- 6. クライアントのみでレンダリング(SSRしない) -->
<Counter client:only="react" initial={6} label="OnlyClient" />

これらディレクティブの違いを覚えるだけで、不要なJSを積み込まないチューニング感覚が一気に身につきます。実務では大半が client:visible と client:idle で十分で、client:load はファーストビュー直下の操作可能要素(検索バーなど)に限定するのが定石です。逆に「動かないと意味がないUI(動画プレーヤーのコントロールバー、リアルタイムチャットの入力欄など)」では client:load 必須なので、各Islandの優先度を「ファーストビュー有無」「ユーザー操作の即応性」「画面外なら不要かどうか」の3軸で機械的に分類してから割り当てると、PageSpeedスコアが安定して伸びます。

Islandsの考え方が画期的なのは、「フレームワーク独立」である点です。同じページに React のSearchBoxと、Svelteで作ったCommentsと、Vueで作ったPollを共存させても問題なく動きます。これは各IslandがそれぞれにマイクロアプリとしてバンドルされるためでDOMを共有しません。ただし、Islands間でグローバル状態を共有したいときは localStorage・BroadcastChannel・postMessage・nanostores などフレームワーク外の手段で連携することになります。Reactひとつで全部書きたい設計思想の人にとっては最初少し不便に感じますが、「動かしたいUIだけ動かす」という制約こそが結果として軽量サイトを実現する近道だと割り切ると、納得して使えるようになります。

4.5 Islandsの結果をDevToolsで確認する

npm run build
npm run preview
# ブラウザDevToolsのNetworkを開き、JSファイルがコンポーネント単位で分割されていることを確認
# Performance > Coverageで「Unused JS」が極端に少ないことが分かる

5. Content Collections と型安全なMarkdown管理

ブログやドキュメントサイトで重宝するのが Content Collectionsです。Markdownのfrontmatterを zod でスキーマ定義することで、TypeScriptの型が完全に効くMarkdown CMSのような開発体験になります。frontmatterのキー名のミス、日付フォーマットのズレ、必須項目の抜けといった「Markdown運用あるある」のバグをコンパイル時に弾けるため、特に複数人で運用するブログや、企業のドキュメントサイトでは導入する価値が大きい機能です。GatsbyのGraphQLや、Nuxt Contentのスキーマレス取得と比較しても、シンプルでハマりにくいAPIに仕上がっています。

5.1 src/content/config.ts でスキーマを定義

// src/content/config.ts
import { defineCollection, z } from "astro:content";

const blog = defineCollection({
  type: "content", // Markdown/MDX
  schema: z.object({
    title: z.string(),
    description: z.string().max(160),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
    heroImage: z.string().optional(),
  }),
});

const authors = defineCollection({
  type: "data", // JSON/YAML
  schema: z.object({
    name: z.string(),
    twitter: z.string().optional(),
  }),
});

export const collections = { blog, authors };

5.2 Markdown 記事を置く

---
# src/content/blog/hello-astro.md
title: "Hello Astro"
description: "Astro入門記事"
pubDate: 2026-05-27
tags: ["astro", "tutorial"]
---

# はじめに

Astroで最初のブログを書きました。

5.3 getCollection / getEntry で取得する

---
// src/pages/blog/index.astro
import { getCollection } from "astro:content";

const posts = (await getCollection("blog", ({ data }) => !data.draft))
  .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
---
<h1>ブログ一覧</h1>
<ul>
  {posts.map((post) => (
    <li>
      <a href={`/blog/${post.slug}/`}>{post.data.title}</a>
      <time>{post.data.pubDate.toLocaleDateString("ja-JP")}</time>
    </li>
  ))}
</ul>

6. ファイルベースルーティングと動的ルート

6.1 src/pages の規約

src/pages/
├── index.astro            => /
├── about.astro            => /about/
├── blog/
│   ├── index.astro        => /blog/
│   └── [slug].astro       => /blog/:slug/
├── docs/
│   └── [...path].astro    => /docs/* (catch-all)
└── api/
    └── hello.json.ts      => /api/hello.json (Endpoint)

6.2 動的ルートとgetStaticPaths(SSGの場合)

---
// src/pages/blog/[slug].astro
import { getCollection, type CollectionEntry } from "astro:content";
import BaseLayout from "../../layouts/BaseLayout.astro";

export async function getStaticPaths() {
  const posts = await getCollection("blog");
  return posts.map((post) => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

interface Props {
  post: CollectionEntry<"blog">;
}
const { post } = Astro.props;
const { Content, headings } = await post.render();
---
<BaseLayout title={post.data.title} description={post.data.description}>
  <h1>{post.data.title}</h1>
  <time>{post.data.pubDate.toLocaleDateString("ja-JP")}</time>
  <nav>
    {headings.map((h) => <a href={`#${h.slug}`}>{h.text}</a>)}
  </nav>
  <article>
    <Content />
  </article>
</BaseLayout>

6.3 JSONエンドポイント

// src/pages/api/posts.json.ts
import type { APIRoute } from "astro";
import { getCollection } from "astro:content";

export const GET: APIRoute = async () => {
  const posts = await getCollection("blog");
  const body = posts.map((p) => ({
    slug: p.slug,
    title: p.data.title,
    pubDate: p.data.pubDate,
  }));
  return new Response(JSON.stringify(body), {
    headers: { "content-type": "application/json" },
  });
};

7. SSG / SSR / ハイブリッドモードの切り替え

7.1 output の3モード

// astro.config.mjs
import { defineConfig } from "astro/config";
import node from "@astrojs/node";

export default defineConfig({
  // "static"  : 全部ビルド時にHTML出力(デフォルト・SSG)
  // "server"  : リクエスト時にレンダリング(SSR)
  // "hybrid"  : 既定SSGで、ページ単位で server に切替可能
  output: "hybrid",
  adapter: node({ mode: "standalone" }),
});

7.2 ページ単位でprerenderを切り替える

---
// src/pages/dashboard.astro
// このページだけ SSR にする
export const prerender = false;

const user = await fetch("https://api.example.com/me", {
  headers: { authorization: Astro.request.headers.get("authorization") ?? "" },
}).then((r) => r.json());
---
<h1>こんにちは {user.name} さん</h1>

7.3 POSTを受けるサーバーアクション風エンドポイント

// src/pages/api/contact.ts
import type { APIRoute } from "astro";

export const POST: APIRoute = async ({ request }) => {
  const data = await request.formData();
  const name = data.get("name")?.toString() ?? "";
  const message = data.get("message")?.toString() ?? "";
  if (!name || !message) {
    return new Response("invalid", { status: 400 });
  }
  // 実際はDBやメール送信
  console.log("contact:", name, message);
  return new Response(JSON.stringify({ ok: true }), {
    headers: { "content-type": "application/json" },
  });
};

7.4 フォーム側

<form method="POST" action="/api/contact">
  <input name="name" required />
  <textarea name="message" required></textarea>
  <button type="submit">送信</button>
</form>

8. Middleware と View Transitions

8.1 src/middleware.ts

// src/middleware.ts
import { defineMiddleware } from "astro:middleware";

export const onRequest = defineMiddleware(async (context, next) => {
  // 認証チェック
  const isAuth = context.cookies.get("session")?.value;
  if (context.url.pathname.startsWith("/admin") && !isAuth) {
    return context.redirect("/login");
  }
  // contextへ値を共有
  context.locals.requestId = crypto.randomUUID();
  const res = await next();
  res.headers.set("x-request-id", context.locals.requestId);
  return res;
});

8.2 ViewTransitions でSPA風遷移

---
// src/layouts/BaseLayout.astro
import { ViewTransitions } from "astro:transitions";
---
<html>
  <head>
    <ViewTransitions />
  </head>
  <body><slot /></body>
</html>

<!-- 個別要素のtransition -->
<img src="/hero.webp" transition:name="hero" transition:animate="slide" />
<h1 transition:name="title">ページタイトル</h1>

9. Markdown / MDX サポート

9.1 MDX統合の追加

npx astro add mdx

9.2 MDX内でAstro/Reactコンポーネントを使う

---
title: "MDXサンプル"
pubDate: 2026-05-27
---
import Counter from "../../components/Counter.tsx";

# MDXからReactを呼ぶ

下のカウンターはMDXに埋め込まれたReact Islandです。

<Counter client:visible initial={10} />

9.3 シンタックスハイライトのカスタマイズ

// astro.config.mjs
import { defineConfig } from "astro/config";

export default defineConfig({
  markdown: {
    shikiConfig: {
      theme: "github-dark",
      langs: ["typescript", "tsx", "astro", "bash", "diff"],
      wrap: true,
    },
  },
});

10. Image最適化・Sitemap・RSS

10.1 astro:assets で画像最適化

---
// src/pages/photo.astro
import { Image, Picture } from "astro:assets";
import hero from "../assets/hero.jpg"; // 1600x900
---
<Image src={hero} alt="hero" widths={[400, 800, 1200]} sizes="100vw" />

<Picture
  src={hero}
  formats={["avif", "webp", "jpeg"]}
  widths={[400, 800, 1600]}
  sizes="(max-width: 600px) 100vw, 50vw"
  alt="hero"
/>

10.2 sitemap統合

npx astro add sitemap

// astro.config.mjs
import sitemap from "@astrojs/sitemap";
export default defineConfig({
  site: "https://example.com",
  integrations: [sitemap({ changefreq: "weekly" })],
});

10.3 RSS feed

# 依存追加
npm install @astrojs/rss

// src/pages/rss.xml.ts
import rss from "@astrojs/rss";
import { getCollection } from "astro:content";

export async function GET(context: { site: URL }) {
  const posts = await getCollection("blog");
  return rss({
    title: "my-astro-site",
    description: "Astro入門ブログ",
    site: context.site,
    items: posts.map((p) => ({
      title: p.data.title,
      description: p.data.description,
      pubDate: p.data.pubDate,
      link: `/blog/${p.slug}/`,
    })),
  });
}

11. Tailwind連携とAstro DB

11.1 Tailwind v4 を入れる

npx astro add tailwind

/* src/styles/global.css */
@import "tailwindcss";

---
// 任意のページ・コンポーネントで
import "../styles/global.css";
---
<div class="mx-auto max-w-3xl px-4 py-12">
  <h1 class="text-3xl font-bold tracking-tight">Tailwind on Astro</h1>
  <p class="mt-4 text-gray-600">ユーティリティが効いています</p>
</div>

11.2 Astro DB(SQLiteベース)

npx astro add db

// db/config.ts
import { defineDb, defineTable, column } from "astro:db";

const Comment = defineTable({
  columns: {
    id: column.number({ primaryKey: true }),
    postSlug: column.text(),
    author: column.text(),
    body: column.text(),
    createdAt: column.date({ default: new Date() }),
  },
});

export default defineDb({ tables: { Comment } });

// db/seed.ts
import { db, Comment } from "astro:db";
export default async function () {
  await db.insert(Comment).values([
    { id: 1, postSlug: "hello-astro", author: "alice", body: "first!" },
  ]);
}

---
// src/pages/blog/[slug].astro 抜粋
import { db, Comment, eq } from "astro:db";
const comments = await db
  .select()
  .from(Comment)
  .where(eq(Comment.postSlug, post.slug));
---
<ul>
  {comments.map((c) => <li><strong>{c.author}</strong>: {c.body}</li>)}
</ul>

12. デプロイ(Vercel / Netlify / Cloudflare)

12.1 Vercel

npx astro add vercel

// astro.config.mjs
import vercel from "@astrojs/vercel/serverless";
export default defineConfig({
  output: "server",
  adapter: vercel({ webAnalytics: { enabled: true } }),
});

12.2 Netlify

npx astro add netlify

# netlify.toml
[build]
  command = "npm run build"
  publish = "dist"

12.3 Cloudflare Pages

npx astro add cloudflare

// astro.config.mjs
import cloudflare from "@astrojs/cloudflare";
export default defineConfig({
  output: "server",
  adapter: cloudflare({ mode: "directory" }),
});

12.4 自前のNode.jsサーバー

npm install @astrojs/node

// astro.config.mjs
import node from "@astrojs/node";
export default defineConfig({
  output: "server",
  adapter: node({ mode: "standalone" }),
});

# ビルドして起動
npm run build
HOST=0.0.0.0 PORT=3000 node ./dist/server/entry.mjs

13. Astro vs Next.js vs Hugo の使い分け

13.1 まず役割を整理する

Next.jsはReactベースのフルスタックWebアプリ向け、Hugoは爆速ビルドの静的サイトジェネレーター、AstroはMPA志向で「コンテンツ駆動サイト+ピンポイントのインタラクション」の中間領域に強いという棲み分けです。SaaSのダッシュボードや認証必須のSPAはNext.js、技術ドキュメント・コーポレートサイト・ブログはAstro、Markdownだけで足りる超軽量サイトはHugo、というのが大まかな選び方です。

もうひとつ重要な違いは「ターゲットの利用者層」です。Next.jsはReactを深く理解した上でSSR/RSC/Server Actionsまでフル活用したいプロ向けで、エコシステムの強さは抜群ですがその分学習コストも高いです。Hugoは記事の書き手がエンジニアではない場合にすら手渡せるほど枯れていますが、動的UIを足すには独自テーマかJSを別途用意する必要があります。Astroはその中間で「コンテンツ管理は型安全Markdown、UIは必要箇所だけReact/Vue/Svelte」という独自ポジションを取っており、エンジニアと編集者が混在するチームに最も向いています。サイトの目的を「主に読ませる」「主に操作させる」「両方を1サイトで」と分けて考えると判断しやすいでしょう。

13.2 数値で比較

項目	Astro 5	Next.js 15	Hugo
主力ユースケース	コンテンツサイト	SaaS / アプリ	静的サイト
UIフレームワーク	独自+React/Vue/Svelte/Solid	React専用	テンプレート(Go HTML)
デフォルトのJS出力	0KB	あり(RSC+クライアント)	0KB
SSG/SSR	両対応(hybrid可)	両対応(App Router)	SSGのみ
学習コスト	低〜中	中〜高	低
TypeScript	標準	標準	不要

13.3 Reactコンポーネントだけ移植したい場合

// Next.jsの src/components/Counter.tsx をそのまま
// Astro側 src/components/Counter.tsx へコピーし、利用箇所で
// <Counter client:visible /> と書くだけで動くケースが多い
// useRouterなど Next 依存のフックは Astro.url / Astro.params に置換が必要

14. 実務で効くチューニングとベストプラクティス

14.1 不要なclient:loadを撲滅する

// NG例:静的なバナーをわざわざクライアントで動かしている
<Banner client:load />

// OK例:そもそも .astro として書き直し、JSを出さない
<Banner />

14.2 環境変数の使い方

# .env
PUBLIC_GA_ID=G-XXXX     # PUBLIC_ で始まるとクライアントからも参照可
DB_URL=postgres://...   # それ以外はサーバーのみ

---
const gaId = import.meta.env.PUBLIC_GA_ID;
const dbUrl = import.meta.env.DB_URL; // ビルド時 or SSR でのみ参照
---
<script>
  window.GA_ID = `{gaId}`;
</script>

14.3 検証用コマンドの定型

# 型チェック+ビルド+プレビューを一括
npm run check && npm run build && npm run preview

14.4 学習を効率化したい人へ

Astroだけ単独で深掘りするより、Reactの基礎+TypeScript+Web標準APIを同時に底上げしたほうが結局早く成果につながります。独学が頭打ちになってきたら、現役エンジニアからレビューを受けられるTechAcademyのフロントエンドコースや、最終的に転職まで伴走してくれる侍エンジニアのマンツーマン指導、未経験から短期間で実務水準を狙うDMM WEBCAMPあたりが現実的な選択肢です。すでに実務経験があり、Astro/React案件にピンポイントで関わりたい人は、フロントエンドの非公開案件を多く持つレバテックフリーランスの登録も並行しておくと、学習成果をそのまま単価アップに繋げやすくなります。

15. FAQ:よくある詰まりどころ

Q1. Reactのフックが「is not a function」と怒られる

そのコンポーネントを .astro 側で使うときに client:* ディレクティブを付け忘れている可能性が高いです。サーバーレンダリングだけならフック自体は呼ばれませんが、副作用フック(useEffect)は無視されてしまいます。インタラクションがあるなら client:visible を付けるのが基本です。

Q2. window/documentが undefined になる

// NG:Frontmatterはサーバーで動くのでwindowは無い
---
const w = window.innerWidth;
---

// OK:<script>でブラウザ側に書く、もしくはclient:onlyで切り出す
<script>
  console.log(window.innerWidth);
</script>

Q3. Content Collections が認識されない

# src/content/config.ts を作った後に必ず
npx astro sync
# 型が .astro/types.d.ts に再生成される

Q4. ビルド時に「No adapter installed」と出る

output: "server" または "hybrid" にしているのにアダプターを入れていないと出ます。Node/Vercel/Netlify/Cloudflareのうち、デプロイ先に応じた@astrojs/*アダプターを npx astro add で追加してください。

Q5. 既存サイトをAstroに段階移行できるか

可能です。src/pages/下にAstroの各ページを置き、まだ移行していないURLは vite.server.proxy や Nginx / Cloudflare 側のルーティングで既存サーバーへ流すパターンが鉄板です。ブログだけ先にAstro化する、ランディングだけAstro化するといった小さな移行から始めると安全に進められます。

まとめ:Astroは「軽さ」と「自由度」を両立できる選択肢

Astroは「JSをデフォルトで送らない」「必要な場所だけ任意のUIフレームワークを差し込める」というIslands Architectureを軸に、Content Collectionsで型安全なMarkdown管理、Astro DBで簡単なデータ永続化、View Transitionsで滑らかな遷移、Image最適化やSitemap/RSSのファーストパーティ統合まで一通り揃っており、コンテンツ駆動のWebサイトでは現時点でかなり強い選択肢です。SaaSダッシュボードのような重量級SPAはNext.jsに任せ、コーポレート・ブログ・ドキュメント・ポートフォリオなど「速度とSEOがそのまま売上に効くサイト」はAstroで組むという棲み分けが、2026年時点での現実解と言えます。本記事のコードはすべてコピペで動くように書いていますので、まずは npm create astro@latest で空のプロジェクトを作り、Counter Islandまで一気に動かしてみるところから始めてみてください。手を動かしてしまえば、Astroが「特別なフレームワーク」ではなく「素のHTMLにJSを後付けする昔のWeb開発の良さを取り戻した道具」だと体感できるはずです。

最後に学習ロードマップとしてのおすすめは、(1)まずbasicsテンプレートで Astroの構文に慣れる、(2)blogテンプレートでContent CollectionsとMarkdownの取り回しを身につける、(3)既存のReactコンポーネントをひとつだけIslandsとして組み込んでみる、(4)View Transitionsで遷移を磨く、(5)VercelかCloudflare PagesでSSRデプロイしてみる、という5段階です。1〜2日もあれば(1)〜(3)までは到達できるので、まずは小さく動かしてから本記事を再度ななめ読みするだけで、各セクションの意図が驚くほどクリアに見えてくるはずです。Astroは「学習コストの低さ」ではなく「学習投資の回収率の高さ」がいちばんの魅力なので、案件で導入する前にぜひ素振りしておくことをおすすめします。