Astro Islands Architect は何をしますか?
Astro は「デフォルトで HTML を配信し、JS が必要な部分だけをハイドレートする」フレームワークです。マーケティング、ドキュメント、コンテンツ重視のサイトでは、React/Next.js よりも劇的にバンドルサイズを削減できます。肝心なのは、どのコンポーネントを静的(static)にし、どのコンポーネントをアイランド(island)にするかです。
使用するケース
- マーケティングサイト、ブログ、ドキュメントポータル — コンテンツが製品そのもの。
- クライアント JS が過剰な Next.js マーケティングサイトからの移行。
- マルチフレームワーク — React コンポーネントライブラリを Vue や Svelte コンポーネントと併用。
- MDX と型安全なフロントマターによるヘビーなコンテンツ作成。
- SPA を使わずにページ間のビュートランジションを実現。
中核機能
ページ構造
---
// src/pages/blog/[slug].astro — フロントマターはビルド/SSR 時に実行されます
import { getCollection, getEntry } from 'astro:content';
import Layout from '../../layouts/Default.astro';
import Newsletter from '../../components/Newsletter.tsx';
export async function getStaticPaths() {
const posts = await getCollection('blog');
return posts.map((p) => ({ params: { slug: p.slug }, props: { post: p } }));
}
const { post } = Astro.props;
const { Content } = await post.render();
---
<Layout title={post.data.title}>
<h1>{post.data.title}</h1>
<article><Content /></article>
{/* アイランド — このコンポーネントだけが JS を配信します */}
<Newsletter client:visible />
</Layout>
--- で囲まれた部分はサーバーコードです。<...> 内では、デフォルトは静的 HTML です。client:* ディレクティブを持つコンポーネントがアイランドになります。
クライアントディレクティブ — 適切なものを選択する
| ディレクティブ | ハイドレートのタイミング | 使用例 |
|---|---|---|
client:load | ページ読み込み時 | ファーストビューのインタラクティブ要素(カート、検索)。 |
client:idle | ブラウザがアイドル状態になった時 | 重要でないインタラクティブ要素(チャットウィジェット)。 |
client:visible | ビューポートにスクロールされた時 | ファーストビューより下のコンテンツ(ニュースレター登録、コメント)。 |
client:media="(min-width: 768px)" | メディアクエリに一致した時 | デスクトップ専用ウィジェット。 |
client:only="react" | SSR をスキップし、クライアントのみでレンダリング | マウント時にブラウザ API が必要なコンポーネント。 |
client:idle は、ほとんどの重要でないアイランドの適切なデフォルトです。client:load は大きなハンマーのようなもので、控えめに使いましょう。
コンテンツコレクション
// src/content/config.ts
import { defineCollection, z } from 'astro:content';
const blog = defineCollection({
type: 'content', // markdown/MDX ファイル
schema: z.object({
title: z.string().max(120),
description: z.string().max(160),
date: z.coerce.date(),
tags: z.array(z.string()).default([]),
draft: z.boolean().default(false),
cover: z.object({ src: z.string(), alt: z.string() }).optional(),
}),
});
export const collections = { blog };
これで getCollection('blog') は完全に型付けされます。フロントマターのミスは本番環境ではなくビルド時に検出されます。
const posts = (await getCollection('blog'))
.filter((p) => !p.data.draft)
.sort((a, b) => +b.data.date - +a.data.date);
マルチフレームワーク
npx astro add react vue svelte
---
import ReactSearch from '../components/Search.tsx';
import VueChart from '../components/Chart.vue';
import SvelteToggle from '../components/Toggle.svelte';
---
<ReactSearch client:idle />
<VueChart client:visible />
<SvelteToggle client:load />
各フレームワークのランタイムは個別にバンドルされ、そのフレームワークを使用するページでのみ読み込まれます。ほとんどが静的であるドキュメントサイトの場合、ほとんどのページに React JS をまったく配信しないということも可能です。
サーバーアイランド(Astro 4+)
<Layout>
<Header />
<PersonalizedRecommendations server:defer>
<p slot="fallback">読み込み中...</p>
</PersonalizedRecommendations>
<Footer />
</Layout>
server:defer は、ページの残りの部分をすぐにレンダリングし、遅延コンポーネントの HTML を別のリクエストでストリーミング配信します。パーソナライズされたコンテンツなど、ページ全体を SSR にする必要がない場合に便利です。
画像最適化
---
import { Image } from 'astro:assets';
import cover from '../assets/cover.jpg';
---
<Image src={cover} alt="カバー写真" widths={[400, 800, 1200]} sizes="(max-width: 768px) 400px, 1200px" />
Astro は srcset を生成し、Sharp でリサイズを実行し、必要なものだけを配信します。画像は完全な最適化のために src/assets/ に配置してください。public/ は未処理のまま配信されます。
ビュートランジション
---
import { ViewTransitions } from 'astro:transitions';
---
<html>
<head>
<ViewTransitions />
</head>
...
</html>
<a href="/about" transition:name="hero">About</a>
SPA なしでページ間のトランジションを実現します。ブラウザがほとんどの処理を行い、Astro は要素のマッチングを調整します。
MDX とコンポーネント
---
title: 私の投稿
date: 2026-04-30
---
import Callout from '../../components/Callout.astro';
# {frontmatter.title}
<Callout type="warn">
これはサーバーサイドでレンダリングされる警告です。JS は不要です。
</Callout>
MDX 内でインポートされたコンポーネントは、アイランドでない限り、ビルド/SSR 時に実行されます。
ハイブリッド SSR
// astro.config.mjs
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({
output: 'hybrid',
adapter: cloudflare(),
});
---
// src/pages/api/search.ts — エッジで実行
export const prerender = false;
export async function GET({ request }) {
const url = new URL(request.url);
const q = url.searchParams.get('q') ?? '';
const results = await search(q);
return new Response(JSON.stringify(results), { headers: { 'content-type': 'application/json' } });
}
prerender = false はルートを SSR に設定し、サイトの残りの部分は静的のままです。
アンチパターン
あらゆる場所で client:load を使う
症状: Lighthouse の JS バンドルサイズが肥大化。Astro のハイドレーション戦略が無意味になる。
診断: 開発者が最も馴染み深い client:load をデフォルトで使ってしまっている。
修正: デフォルトは client:idle または client:visible にする。client:load はファーストビューのインタラクティブ要素に限定する。
クライアントコンポーネントでデータをフェッチする
症状: すべてのページにローディングスピナーが表示され、SEO に悪影響。
診断: データフェッチが Astro のフロントマターではなく React コンポーネントに移動している。
修正: --- のフェンス内でフェッチし、サーバーサイドでレンダリングし、データをプロパティとしてアイランドに渡す。
型付けされていないフロントマター
症状: ビルドは成功するが、本番環境でタイトルに undefined が表示される。
診断: コンテンツコレクションのスキーマがなく、フロントマターの typo に気づかなかった。
修正: zod スキーマで defineCollection を使用する。フロントマターのミスはビルド時に検出される。
public/ と src/assets/ を画像の格納場所として混在させる
症状: 一部の画像は最適化されるが、他の画像は元のサイズで配信される。
診断: public/ はそのまま配信され、src/assets/ のみが Sharp で処理される。
修正: 画像を src/assets/ に移動する。<Image> を常に使用する。public/ は OGP 画像やファビコンのみに使用する。
Astro を SPA として使おうとする
症状: ハイドレーションと常に戦うことになり、ページ全体がインタラクティブになるまでアイランドが肥大化する。 診断: 仕事に適したフレームワークではない。Astro はコンテンツに優れており、SPA には Next/Remix が必要。 修正: ほとんどのページがインタラクティブな場合は Next/Remix を使用する。マーケティングとドキュメントには Astro を使用する。
client:only の過剰使用
症状: ページ読み込みのたびにレイアウトシフト(CLS)が発生し、コンテンツが表示される前に「ちらつき」が生じる。
診断: SSR をスキップすると、ブラウザは JS が実行されるまで空のプレースホルダを表示する。
修正: client:only は、コンポーネントが本当にサーバーサイドでレンダリングできない場合にのみ使用する。最終的なサイズに近いプレースホルダを提供する。
品質ゲート
- デフォルトのクライアントディレクティブは
client:idleまたはclient:visibleであり、client:loadは用途ごとに正当性が説明されている。 - すべてのコンテンツが
defineCollectionを介して型付けされたスキーマを持っている。 - 画像は
src/assets/に配置され、<Image>コンポーネントを使用している。 - マルチフレームワーク統合(
@astrojs/reactなど)は、実際に存在するコンポーネントに対してのみ追加されている。 - 最も遅い代表的なページで LCP が 2 秒未満。
- ページごとに初回読み込み JS バジェットが設定されており、CI がリグレッションで失敗する。
- MDX では静的な部分に Astro コンポーネントを使用し、アイランドはインタラクティブな部分のみに使用している。
- ビュートランジションが主要なナビゲーションパス全体でテストされている。
対象外
- 完全な SPA — Next.js、Remix、TanStack Start の方が適している。
- Astro プラグイン/インテグレーションの作成 — 別のスキル(現時点では専用スキルなし)。
- Vite 側のビルドチューニング — Astro は内部で Vite を使用。チャンクサイズ、HMR、プラグインライフサイクルの問題は
vite-build-optimizerを参照。 - ヘビーなクライアントステートアプリ(ダッシュボード、リアルタイムツール) — アイランドが役立つ範囲を超えて JS が多すぎる。
- ネイティブモバイル — Astro はウェブのみ。