ものしり

第1部 基礎

第3章 Astro 基礎知識

EmDash を理解するために必要な Astro の基礎を学ぶ。

読了の目安 約 34 分 ・ EmDash 1.3.1 / Astro 7 系(確認日 2026-10-29)

この章で学ぶこと

EmDash は「Astro のサイトの中で動く CMS」です。公開ページも管理画面も、1つの Astro アプリケーションとしてデプロイされます。そのため、EmDash のテーマを読み書きするには、Astro の知識が一定量必要です。一方で、Astro 全体を網羅する必要はありません。この章では、EmDash を理解するために必要な範囲に絞って、次の内容を順に学びます。

  • プロジェクト構成と .astro コンポーネント(フロントマター、テンプレート、props、slot)
  • ルーティング(静的、動的、rest パラメータ、getStaticPaths()、優先順位)
  • 出力モード(static / server)、アダプター、ページ単位の prerender
  • ミドルウェア、i18n ルーティング、リダイレクト、環境変数
  • Astro の Content Collections と EmDash 独自のコレクションの違い
  • 画像、View Transitions(ごく簡潔に)、統合(integrations)、ビルドとデプロイ

基準は Astro 7 系です(EmDash 本体の package.json が要求する astro の範囲は、手元の資料からは確認できませんでした。なお、資料にあるプラグインの peer 依存は >=6.0.0-beta.0 です)。確認日は 2026-10-29 です。各節の末尾に、EmDash がその機能のどこに依存しているかを「EmDash との接点」として示します。


1. プロジェクト構成

なぜ構成を知る必要があるか

WordPress のテーマは、functions.php や index.php、header.php が1つのフォルダに並び、どのファイルがどの URL に対応するかは「テンプレート階層」というルールで決まります。Astro では、URL に対応するファイルを置く場所が明示されています。EmDash のテーマ(テンプレート)もこの構成に従っているので、最初に地図を持っておくと迷いません。

構成の要点

Astro の公式ドキュメントでは、次の項目がプロジェクトの基本要素として説明されています。

場所 役割
src/ ソースコード。ページ、レイアウト、コンポーネント、スタイル、画像など。Astro が処理してバンドルする
src/pages/ 唯一 Astro が予約しているディレクトリ。ここのファイルがルート(URL)になる
public/ 加工せずそのままコピーされる静的ファイル(robots.txt、フォントなど)
astro.config.mjs 統合(integrations)、ビルド、サーバーの設定。.js / .ts も可
package.json 依存関係とスクリプト
tsconfig.json TypeScript 設定(推奨だが必須ではない)

src/components/、src/layouts/、src/styles/ は「慣習」であり、名前を変えても動きます。必須なのは src/pages/ だけです。

EmDash のドキュメントでは、WordPress の概念との対応を次のように整理しています。

WordPress Astro(EmDash テンプレート) 目的
index.php, single.php, page.php src/pages/ URL ごとのルート
template-parts/ src/components/ 再利用できるマークアップ
header.php と footer.php src/layouts/ ページ全体の外枠
style.css src/styles/ サイトのスタイル
プラグインや DB の設定 astro.config.mjs 統合とサーバーアダプター
テーマのセットアップデータ seed/seed.json コレクション、メニュー、サンプルコンテンツ

ブログテンプレートの src/ は次のような形です。

src/
├── components/
│   └── PostCard.astro
├── layouts/
│   └── Base.astro
├── pages/
│   ├── index.astro
│   ├── pages/
│   │   └── [slug].astro
│   └── posts/
│       ├── index.astro
│       └── [slug].astro
└── live.config.ts

落とし穴

public/ に置いた CSS や JavaScript は最適化もバンドルもされません。自分で書くコードは src/ に置き、public/ は「そのままの URL で配りたいもの」に限ります。

EmDash との接点: seed/seed.json と src/live.config.ts は EmDash 固有のファイルです。前者はコレクションや初期データの定義、後者は EmDash を Astro に接続する登録ファイルです(第6節で扱います)。それ以外は普通の Astro プロジェクトです。


2. .astro コンポーネント

なぜ重要か

EmDash のテーマはほぼすべて .astro ファイルで書かれています。ページもレイアウトも部品も同じ形式です。この形式を読めれば、テーマの大半は読めます。

構造: フロントマターとテンプレート

.astro ファイルは、--- のフェンス(柵)で区切られた2つの部分からなります。

---
// フロントマター(コンポーネントスクリプト): サーバー側で実行される
interface Props {
  title: string;
  excerpt?: string;
  href: string;
}
const { title, excerpt, href } = Astro.props;
---
<!-- テンプレート: ここが HTML になる -->
<article>
  <h2><a href={href}>{title}</a></h2>
  {excerpt && <p>{excerpt}</p>}
</article>
  • フェンスの内側(フロントマター)は、ビルド時またはリクエスト時に実行され、ブラウザに送られる HTML には含まれません。import、データ取得、変数の準備はここで行います。
  • フェンスの下(テンプレート)は HTML に JavaScript 式を { } で埋め込める形式です。{value} は自動でエスケープされます(筆者の理解。参照した公式ページでは明示的な記述を確認できませんでした)。

WordPress で言えば、PHP の <?php ... ?> 部分がフロントマターに集まり、出力部分がテンプレートに残るイメージです。PHP のように、HTML の途中でロジックが何度も行き来することはありません。

テンプレート式のよくある型は次の4つです。

目的 書き方
値の出力 {post.data.title}
あるときだけ表示 {excerpt && <p>{excerpt}</p>}
二択 {posts.length === 0 ? <p>なし</p> : <List />}
繰り返し {posts.map((p) => <PostCard ... />)}

props

親から子へ渡す値が props です。子は Astro.props から取り出します。interface Props を宣言すると TypeScript で型を確認でき、分割代入のときに既定値も書けます(const { greeting = 'Hello' } = Astro.props;)。get_template_part() に $args を渡す操作に近いものですが、入力が明示され型付けされる点が違います。

slot

slot は、親が子に「中身のマークアップ」を渡す仕組みです。

---
// Card.astro
const { title } = Astro.props;
---
<article>
  <h2>{title}</h2>
  <slot />                         <!-- 既定の slot -->
  <footer><slot name="footer" /></footer>  <!-- 名前付き slot -->
</article>
<Card title="最新記事">
  <p>カードの本文です。</p>
  <a slot="footer" href="/posts/latest">続きを読む</a>
</Card>
  • 名前付き slot へは、直接の子要素に slot="名前" を付けて渡します。ラッパー要素を増やしたくない場合は <Fragment slot="名前"> を使います。
  • <slot> の中に書いた内容は、親が何も渡さなかったときのフォールバックです。

レイアウトは「slot を持つコンポーネント」

header.php と footer.php に分かれていた共通部分は、レイアウトコンポーネント1つにまとまります。<html>、<head>、<body> を持ち、本文の位置に <slot /> を置きます。ページ側は <Base title="Home">...</Base> のようにレイアウトで包みます。

落とし穴

slot は呼び出しごとに閉じており、WordPress のアクションフックのように離れた場所から差し込めません。また Astro 7 では .astro のコンパイラが Rust 製になり、閉じていないタグがエラーになります。compressHTML の既定が 'jsx' になり、インライン要素間の空白が消えることもあります(Astro 7 アップグレードガイドの記述)。

EmDash との接点: <PortableText /> や <WidgetArea /> は emdash/ui から import する普通のコンポーネントです。リッチテキストは HTML 文字列ではなく構造化データとして渡します。


3. ルーティング

なぜ重要か

WordPress ではパーマリンク設定とテンプレート階層が URL とテンプレートを結びます。Astro では src/pages/ の中のファイル名がそのまま URL になります。EmDash は「コンテンツの種類ごとの URL」を作らず、これをテーマ側が決めます。つまり、URL 設計は Astro の流儀で行います。

静的ルート

src/pages/ の .astro(.md、.mdx も)が1ページになります。

ファイル URL
src/pages/index.astro /
src/pages/about.astro または about/index.astro /about
src/pages/about/me.astro /about/me

動的ルートと getStaticPaths()

ファイル名の [ ] は動的セグメントで、値は Astro.params から読めます。

---
// src/pages/posts/[slug].astro
const { slug } = Astro.params;
---

ここで出力モードによって挙動が分かれます。

  • 静的(prerender)ページ: ビルド時に「どの値の組を生成するか」を知る必要があるので、getStaticPaths() をエクスポートし、{ params: { slug: "..." } } の配列を返します。props を添えて追加データも渡せます。params の値はデコードされないため、必要なら decodeURI() を使います。
  • オンデマンド(サーバー)ページ: リクエスト時に解決するので getStaticPaths() は不要です。どんな値でも受け付けるため、ページ内でデータを探し、なければ Astro.rewrite("/404") を返します。URL を保ったまま 404 ページを表示できます。Astro.redirect("/404") も公式のルーティング解説に例がありますが、ブラウザの URL が /404 に変わる点が違います。

rest パラメータ

[...path] は任意の深さのパスに一致します。値を undefined にすると親のパス(/sequences など)にも一致します。[org]/[repo]/tree/[branch]/[...file] のように名前付きパラメータと組み合わせられますが、オンデマンドレンダリングのルートでは、1つのファイル名に rest パラメータは1つだけです([locale]/[...slug].astro は可、[...locale]/[...slug].astro は不可)。

ルートの優先順位

同じ URL に複数のルートが一致するとき、Astro は次の順で決めます(公式ドキュメントの記載順)。

  1. Astro の予約ルート(_astro/、_server_islands/、_actions/)
  2. パスのセグメント数が多いルート
  3. 静的ルートが動的ルートより優先
  4. 名前付きパラメータが rest パラメータより優先
  5. prerender された動的ルートがサーバー動的ルートより優先
  6. エンドポイントがページより優先
  7. ファイルベースのルートがリダイレクトより優先
  8. 上記で決まらなければ、Node の既定ロケールでのアルファベット順

落とし穴

EmDash テンプレートの固定ページは /pages/about のように pages フォルダ配下の URL です。ルート直下(/about)で受けたい場合はキャッチオール [...slug].astro が候補になります。

EmDash との接点: EmDash のドキュメントは、テーマのルートに getStaticPaths() を足さないよう案内しています(サイトが EmDash を「ビルド時のデータソース」として意図的に扱う場合を除く)。理由は次節のとおり、EmDash が実行時にデータベースへ問い合わせる前提だからです。


4. 出力モードとアダプター

なぜ重要か

WordPress は常にサーバー(PHP)がリクエストごとにページを組み立てます。Astro は既定ではその逆で、ビルド時にすべてを HTML にします。EmDash は管理画面、API、最新コンテンツを実行時に配信するため、サーバーで動く必要があります。この選択が、EmDash の設定の中心です。

2つの出力モード

astro.config.mjs の output で既定の挙動を決めます。

値 意味
'static'(既定) すべてのページがビルド時に静的 HTML になる
'server' すべてのページがリクエストごとにレンダリングされる(オンデマンド)

Astro 公式は、ほとんどのページがオンデマンドになるまでは 'static' から始めることを勧めています。'server' は「すべてのページで prerender を無効にしたのと同じ」で、機能が増えるわけではなく既定値が変わるだけです。

なお、今回参照したドキュメントのオンデマンドレンダリングのページには 'hybrid' モードは登場しません。ページ単位で切り替える仕組みは次の prerender です。

ページ単位の prerender

モードの既定値を、ページごとに上書きできます。

---
export const prerender = false; // static モードで、このページだけサーバーレンダリング
---

逆に server モードで export const prerender = true; と書けば、そのページだけビルド時に HTML 化されます。ここで重要なのは、EmDash のコンテンツに問い合わせるページを prerender にすると、問い合わせはビルド時に1回だけ実行されることです。EmDash のドキュメントも、prerender されたページは「次のビルドまで後からの編集が反映されない」と説明しています。

図 3-1 に示すように、prerender したページとサーバーレンダリングのページでは、EmDash への問い合わせが行われる時点が異なります。

図 3-1: prerender したページはビルド時に一度だけ、サーバーレンダリングのページはリクエストごとに EmDash のデータを取得する流れの比較

アダプター

オンデマンドレンダリングには、動かす環境に合わせたアダプターが必要です。公式アダプターは Cloudflare、Netlify、Node、Vercel です。npx astro add <name> で、インストールと設定ファイルの更新をまとめて行えます。

@astrojs/node

  • mode: 'standalone': ビルド結果が自分で待ち受けるサーバーになり、静的ファイルも配信します。node ./dist/server/entry.mjs で起動します。HOST と PORT の環境変数で待ち受け先を変えられます。
  • mode: 'middleware': handler を書き出し、Express などの自前のサーバーに組み込みます。静的ファイル(./dist/client/)は自分で配信します。

@astrojs/cloudflare

  • adapter: cloudflare() で使います。wrangler.jsonc は任意で、なければ自動生成されます。
  • 現行のアダプターでは Astro.locals.runtime は廃止され(廃止された版は、確認できた範囲の公式ページに記載がありませんでした)、環境変数やバインディングは cloudflare:workers の env、cf は Astro.request.cf、実行コンテキストは Astro.locals.cfContext から取得します。Cloudflare Pages は対象外で Workers へ移行する形です。
  • astro dev / astro preview は workerd 上で動き、本番に近い挙動になります。秘密情報は npx wrangler secret put <KEY>、ローカルは .dev.vars に置きます。

EmDash の設定例

EmDash のアーキテクチャ解説にある Node 構成の設定は次のとおりです。

import node from "@astrojs/node";
import react from "@astrojs/react";
import { defineConfig } from "astro/config";
import emdash, { local } from "emdash/astro";
import { sqlite } from "emdash/db";

export default defineConfig({
  output: "server",
  adapter: node({ mode: "standalone" }),
  integrations: [
    react(),
    emdash({
      database: sqlite({ url: "file:./data.db" }),
      storage: local({
        directory: "./uploads",
        baseUrl: "/_emdash/api/media/file",
      }),
    }),
  ],
});

読み解くポイントは3つです。

  1. output: "server" と adapter の組み合わせが、EmDash が要求する土台です。
  2. integrations に react() と emdash() の両方が必要です。React は管理画面のハイドレーション(ブラウザ側での動作化)に使われ、@astrojs/react を入れても react() を配列に書き忘れると、管理画面が「Loading EmDash...」のまま止まります(EmDash のドキュメントの記載)。
  3. データベースとメディアの保存先は emdash() の引数で与えます。Cloudflare 向けテンプレートは D1 と R2 を使う構成が別に用意されているので、デプロイ先に合ったテンプレートから始め、Node の設定を手で書き換えるのは避けます。

注意: storage を省略するとローカルストレージが既定になりますが、本番ではリリースやインスタンスをまたいで残る保存先が必要です(EmDash のドキュメントの記載)。


5. ミドルウェア、リダイレクト、環境変数

ミドルウェア

なぜ必要か

認証、ヘッダー追加、リクエスト単位のデータ共有など、全ページの前後に挟みたい処理を1か所に書くための仕組みです。WordPress では init や template_redirect などのアクションに近い役割です。

どうやる

src/middleware.ts(または src/middleware/index.ts)から、名前付きで onRequest をエクスポートします(default export は不可)。

import { defineMiddleware } from "astro:middleware";

export const onRequest = defineMiddleware((context, next) => {
  context.locals.title = "New title";
  return next();
});
  • next() は次のミドルウェアまたはルートを呼び、Response を返します。それを加工して返すこともできます。
  • context.locals(ページでは Astro.locals)は、1リクエストの間だけ有効なデータの置き場です。リクエストをまたいで残す用途には使えません。
  • sequence() で複数のミドルウェアを順番に実行できます。await next() より前のコードは指定順、後ろのコードは逆順で動きます。
  • context.rewrite(path) はリダイレクトなしに別の内容を同じ URL で返します。
  • 型は src/env.d.ts で App.Locals を宣言して付けます。
  • ミドルウェアは、prerender されたページではビルド時、オンデマンドのページでは各リクエスト時に動きます。

EmDash との接点: EmDash のドキュメントは「公式テンプレートには、アダプター、シードのパス、ライブコレクション、ミドルウェア、パッケージのバージョンがまとめて入っている」と述べています。テンプレート由来のミドルウェアがある場合は、役割を確認せずに削除・上書きしないでください(この点は筆者の注意喚起で、資料に明記された内容ではありません)。

リダイレクト

設定で宣言する方法と、ページ内で返す方法があります。

export default defineConfig({
  redirects: {
    "/old-page": "/new-page",
    "/blog/[...slug]": "/articles/[...slug]",
    "/moved": { status: 302, destination: "/new-page" },
  },
});

既定のステータスは 301 です。静的 HTML 出力ではメタリフレッシュになりステータスは無視されます。同じパスにファイルがあればそちらが優先されます。ページ内では return Astro.redirect("/login") を使い、オンデマンドレンダリングでは HTML がストリーミングされるため、リダイレクトとヘッダー変更はコンポーネント内ではなくページ側で行います。

環境変数

  • import.meta.env が基本です。サーバーのコードからはすべて読めますが、クライアントに渡るのは PUBLIC_ 接頭辞の付いたものだけです。
  • astro.config.mjs の中では .env が読み込まれないので、process.env か Vite の loadEnv を使います。
  • 型安全にしたい場合は astro:env を使います。設定に env.schema を書き、envField.string({ context: "server", access: "secret" }) のように、context(client / server)と access(public / secret)を指定します。秘密の値は astro:env/server から import し、クライアントにはバンドルされません(secret のクライアント用は存在しません)。
  • Cloudflare では、バインディングや変数は cloudflare:workers の env から取得でき、astro:env とも併用できます。

セキュリティ: クライアントに出る変数は PUBLIC_ を付けたものだけ、という規則を逆用しないでください。API キーなどの秘密に PUBLIC_ を付けるとブラウザに配られます。Cloudflare では秘密情報を wrangler secret put で登録し、リポジトリの .env や wrangler.jsonc の vars に書かないことが基本です。


6. Content Collections と EmDash のコレクション

2種類の Astro コレクション

Astro には、構造化コンテンツを扱う仕組みが2つあります。

ビルド時コレクション ライブコレクション
設定ファイル src/content.config.ts src/live.config.ts
定義 defineCollection() defineLiveCollection()
ローダー 組み込み(glob()、file())または自作 組み込みなし。自作か第三者製
データ取得のタイミング ビルド時に取得して保存 リクエストごとに取得(キャッシュしない場合)
取得関数 getCollection()、getEntry() getLiveCollection()、getLiveEntry()
MDX・画像最適化 対応 非対応

公式は、可能な限りビルド時コレクションを使い、リアルタイム性が必要なときだけライブコレクションを選ぶよう勧めています。CMS のプレビュー用途もライブコレクションの想定用途として挙げられています。

EmDash のコレクションは別物

ここが混乱しやすい点です。EmDash の「コレクション」は、Astro の Content Collections そのものではありません。EmDash のドキュメントによる比較は次のとおりです。

Astro のコンテンツコレクション EmDash のコレクション
保存先 プロジェクト内のファイル SQL データベース
編集 リポジトリのワークフロー EmDash の管理画面
取得 getCollection() getEmDashCollection()
リッチテキスト Markdown / MDX Portable Text
配信 ビルド時、またはライブローダー 実行時のライブローダー

つまり、EmDash は Astro の「ライブコレクション」の枠に、自前のローダー(emdashLoader())を差し込んでいます。src/live.config.ts は次のとおりです。

import { defineLiveCollection } from "astro:content";
import { emdashLoader } from "emdash/runtime";

export const collections = {
  _emdash: defineLiveCollection({ loader: emdashLoader() }),
};

Astro から見えるコレクションは _emdash ひとつだけで、投稿やページなど「どの種類のコンテンツか」は getEmDashCollection("posts") や getEmDashEntry("posts", slug) の引数で選ばれます。

2つの仕組みは同じプロジェクトで共存できます。開発者がリポジトリで管理するリリースノートは Astro のコレクション、編集者が管理画面で書く記事は EmDash、という分担です。両者の結果は別々のままで、EmDash がファイルベースのエントリーをデータベースにコピーすることはありません。

図 3-2 に示すように、2 つの仕組みは呼び出す関数も設定ファイルも読み込み先も別の経路です。

図 3-2: Astro のビルド時コレクションがファイルを読む経路と、EmDash がライブコレクションとして登録したローダーでデータベースを読む経路の対比

読み方のポイント

  • getEmDashCollection() は { entries, error, cacheHint } を返し、getEmDashEntry() は { entry, error, cacheHint } を返します。エントリーが見つからないと entry は null です。
  • entry.id は Astro のルート識別子で、通常はスラッグです。データベース上のコンテンツ ID は entry.data.id です。ID を要求する API には data.id を渡します。
  • 動的ルートでは decodeSlug(Astro.params.slug) で URL のスラッグを復元してから問い合わせます。見つからなければ Astro.rewrite("/404") を返します。

落とし穴: ライブコレクションは MDX と画像最適化に対応していません。EmDash のリッチテキストが Markdown/MDX ではなく Portable Text であること、画像はメディアフィールドを通して扱うことは、この制約と整合しています(整合している、という点は筆者の読み取りです)。


7. i18n ルーティング

なぜ重要か

多言語サイトでは、URL 構造と「翻訳がないとき何を見せるか」を決める必要があります。WordPress では多言語プラグイン(Polylang、WPML など)がこの役を担いますが、Astro は URL のルーティング部分をフレームワーク側で持っています。EmDash のコンテンツ側にも、ロケールを指定して問い合わせる仕組みがあります。

設定項目

import { defineConfig } from "astro/config";

export default defineConfig({
  i18n: {
    locales: ["es", "en", { path: "french", codes: ["fr", "fr-BR", "fr-CA"] }],
    defaultLocale: "en",
    fallback: { fr: "es" },
    routing: {
      prefixDefaultLocale: true,
      redirectToDefaultLocale: true,
      fallbackType: "rewrite",
    },
  },
});
項目 内容
locales 対応する言語の一覧。文字列、または path と codes を持つオブジェクト(URL 上の接頭辞とブラウザの言語コードを対応づける)
defaultLocale 既定の言語。locales に含まれている必要がある
fallback ロケールごとの代替ロケール。例 { fr: "es" }
routing.prefixDefaultLocale 既定 false。true にすると既定言語の URL にも /en/ のような接頭辞が付く
routing.redirectToDefaultLocale prefixDefaultLocale: true と併用。/ を /{defaultLocale}/ にリダイレクト
routing.fallbackType "redirect"(既定)または "rewrite"
routing: "manual" Astro の i18n ミドルウェアを無効化し、astro:i18n のヘルパー関数で自前制御

Astro.currentLocale(現在の URL のロケール)、Astro.preferredLocale(ブラウザの言語設定に最も合うロケール)と、astro:i18n の getRelativeLocaleUrl() などが用意されています。domains でロケールごとにドメインを割り当てることもできますが、site、output: "server"、@astrojs/node または @astrojs/vercel が必要です。

落とし穴

注意: routing.fallbackType の既定値は "redirect" です。URL を変えずに代替言語の内容を見せたい場合は "rewrite" を明示します(Astro 公式ドキュメントの記載)。

EmDash との接点: Astro の i18n は URL ルーティングを扱い、翻訳対象のコンテンツそのものは EmDash 側が持ちます。両者の対応づけ(ロケール付きの問い合わせなど)は EmDash のクエリガイド(querying-content)で扱われます。


8. 画像、View Transitions、統合

画像

  • src/ の画像は import して最適化でき、public/ の画像はそのまま配られます。astro:assets の <Image /> / <Picture /> は最適化済みの出力を作り、alt が必須です。
  • リモート画像は image.domains / image.remotePatterns で許可したものだけが最適化されます。既定の画像サービスは Sharp で、Cloudflare アダプターには imageService オプション(既定 cloudflare-binding)があります。

EmDash のメディアライブラリの画像は、データベースとメディアストレージに保存される「メディア項目」です。

View Transitions(ごく簡潔に)

astro:transitions の <ClientRouter /> を共通レイアウトの <head> に置くと、リンク遷移をブラウザ側で行い、ページを入れ替えながらアニメーションさせます。EmDash の理解に必須ではありません。使う場合の注意点は、バンドルされたスクリプトが遷移後に再実行されないこと(astro:page-load イベントで初期化する)と、遷移から外したいリンクには data-astro-reload を付けることです。

統合(integrations)

統合は、Astro に機能を足すための拡張単位です。UI フレームワーク(React など)、アダプター、MDX、サイトマップなどが該当し、astro.config.mjs の integrations 配列に並べます。npx astro add <name> で導入と設定追記を自動で行えます。偽値は無視されるため、条件付きで有効化することもできます。統合は、ビルドや開発サーバーのフックに参加できます(Integration API)。

EmDash との接点: EmDash 自身が Astro の統合(emdash/astro の emdash())です。WordPress でいうプラグインに近い位置づけですが、より正確には「Astro に CMS 機能を組み込む部品」です。EmDash のプラグインは、この Astro の統合とは別の仕組みです。


9. ビルドとデプロイの流れ

  1. 開発: astro dev で開発サーバーを起動します。
  2. ビルド: astro build(または npm run build)。出力先は既定で dist/ です(outDir で変更可)。
  3. 静的サイトの場合: dist/ をそのまま静的ホスティングに置きます。
  4. オンデマンドの場合: アダプターがサーバー用の成果物を作ります。Node なら ./dist/server/entry.mjs を node で起動、Cloudflare なら wrangler deploy などで Workers にデプロイします。Cloudflare の環境はビルド時に選ぶ形になり、環境ごとに別々にビルドします(CLOUDFLARE_ENV=some-env astro build && wrangler deploy)。
  5. 確認: Cloudflare アダプターでは astro preview が astro build の後に workerd 上で動きます。

ヒント: EmDash では、astro build のたびにデータベースの内容が「焼き込まれる」わけではありません。ページが server モードで描画される限り、データはリクエスト時に取得されます。ビルド時にデータが固定されるのは、そのページを prerender した場合だけです。


EmDash が Astro に依存している箇所の整理

EmDash の機能 依存している Astro の仕組み
公開ページとテーマ .astro、レイアウト、ファイルベースルーティング
実行時のコンテンツ取得 output: "server" とアダプター
getEmDashCollection() / getEmDashEntry() ライブコレクション(src/live.config.ts と emdashLoader())
管理画面 統合(react() と emdash())、/_emdash/admin などのルート
デプロイ先 @astrojs/node または @astrojs/cloudflare
404 などのエラー処理 Astro.rewrite()、Response の返却
キャッシュ Astro.cache(クエリが返す cacheHint を渡す)
テンプレートの一体配布 ミドルウェアを含むプロジェクト構成

WordPress との違い

  • WordPress は常にサーバーがページを組み立てます。Astro は既定ではビルド時に HTML を作り、サーバーが必要なら output: "server" とアダプターを明示します。
  • URL とテンプレートの対応は、テンプレート階層ではなく src/pages/ のファイル名で決まります。
  • 共通部分は header.php / footer.php ではなく、slot を持つレイアウトです。横断処理はフックではなくミドルウェアが担います。

セキュリティ上の注意

セキュリティ: 環境変数は PUBLIC_ を付けたものだけがブラウザに渡ります。秘密情報には付けないでください。ミドルウェアで認可を行う場合も、locals は1リクエスト限りのデータであることを前提にします。navigate()(View Transitions)は URL を検証しないので、ユーザー入力を直接渡さないでください(公式ドキュメントの注意)。

まとめ

  • Astro で必須なのは src/pages/ だけで、その中のファイルが URL になります。
  • .astro はフロントマター(サーバー側)とテンプレート(HTML)からなり、props で値を、slot でマークアップを渡します。
  • 動的ルートは、静的ページなら getStaticPaths() が必要で、サーバーページでは不要です。優先順位は「具体的なものが先」が基本です。
  • EmDash は output: "server"、アダプター、react() と emdash() の統合、src/live.config.ts の emdashLoader() を前提とします。
  • EmDash のコレクションは DB 上のもので、Astro のコンテンツコレクションとは別物です。Astro のライブコレクションの枠を借りて配信されます。
  • i18n では fallbackType の既定が "redirect" であり、URL を保ったまま代替言語を見せるには "rewrite" を指定します。

理解度チェック

  1. src/pages/posts/[slug].astro が静的(prerender)ページのとき、必要な関数は何ですか。サーバーレンダリングのページではどうなりますか。
  2. /blog/[...slug] と /blog/about が両方存在するとき、/blog/about はどちらが処理しますか。理由も答えてください。
  3. EmDash の設定で @astrojs/react を入れたのに管理画面が「Loading EmDash...」のまま進まないとき、最初に確認する場所はどこですか。
  4. Astro のコンテンツコレクションと EmDash のコレクションを、保存先・編集方法・取得関数の観点で比較してください。
  5. i18n で未翻訳ページが 302 でリダイレクトされるとき、URL を変えずに代替言語の内容を表示するには何を設定しますか。
  6. 環境変数 PUBLIC_ 接頭辞の意味と、Cloudflare で秘密情報を扱う方法を説明してください。

答え

  1. getStaticPaths() が必要です。サーバーレンダリングのページでは不要で、リクエスト時に Astro.params からデータを探し、なければ Astro.rewrite("/404") などを返します。
  2. /blog/about を処理するのは静的ルート(blog/about.astro)です。優先順位で「静的ルートが動的ルートより優先」されるためです。
  3. astro.config.mjs の integrations 配列に react() が含まれているかを確認します(emdash() と両方が必要です)。
  4. Astro は保存先がプロジェクト内のファイル、編集はリポジトリのワークフロー、取得は getCollection()。EmDash は保存先が SQL データベース、編集は管理画面、取得は getEmDashCollection() です。
  5. i18n.routing.fallbackType: "rewrite" を設定します(既定は "redirect")。
  6. PUBLIC_ 付きの変数だけがクライアントのコードに渡ります。Cloudflare では秘密情報を npx wrangler secret put <KEY> で登録し、ローカルでは .dev.vars に置きます。

出典

実際に取得して読んだ URL です(確認日 2026-10-29)。

プロジェクト構成・コンポーネント - https://docs.astro.build/en/basics/project-structure/ - https://docs.astro.build/en/basics/astro-components/

ルーティング・リダイレクト - https://docs.astro.build/en/guides/routing/ - https://docs.astro.build/ja/guides/routing/ (日本語の用語確認)

出力モード・アダプター・ビルド - https://docs.astro.build/en/guides/on-demand-rendering/ - https://docs.astro.build/en/reference/configuration-reference/ (先頭約 100,000 文字まで) - https://docs.astro.build/en/guides/integrations-guide/node/ - https://docs.astro.build/en/guides/integrations-guide/cloudflare/ - https://docs.astro.build/en/guides/deploy/

ミドルウェア・i18n・環境変数 - https://docs.astro.build/en/guides/middleware/ - https://docs.astro.build/en/guides/internationalization/ - https://docs.astro.build/en/guides/environment-variables/

コンテンツ・画像・View Transitions・統合 - https://docs.astro.build/en/guides/content-collections/ - https://docs.astro.build/en/guides/images/ - https://docs.astro.build/en/guides/view-transitions/ - https://docs.astro.build/en/guides/integrations-guide/

Astro 7 の変更点 - https://docs.astro.build/en/guides/upgrade-to/v7/

EmDash 公式ドキュメント(sources/emdash-docs/、MIT, Copyright 2026 Cloudflare Inc.) - coming-from/astro.mdx (https://docs.emdashcms.com/coming-from/astro/) - coming-from/astro-for-wp-devs.mdx (https://docs.emdashcms.com/coming-from/astro-for-wp-devs/) - concepts/architecture.mdx (https://docs.emdashcms.com/concepts/architecture/)