既存の Astro プロジェクトに EmDash を追加する

npm create emdash@latest は事前設定されたプロジェクトを提供しますが、EmDash は既存の Astro サイトにも組み込めます。このガイドでは、スターターテンプレートが通常処理する各要件を説明します — それぞれが欠けていると混乱するエラーを引き起こすので、チェックリストを順番に進めてください。

前提条件

Astro 6 以降 — 古いメジャーバージョンの場合は先にアップグレード（npx @astrojs/upgrade）
Node.js v22.16.0 以上（奇数バージョンはサポートされていません）
サーバー出力 — EmDash はランタイムでコンテンツを提供するため、プロジェクトには output: "server" とアダプター（Node、Cloudflare など）が必要です

パッケージのインストール

EmDash を必要なピア依存関係とともにインストールします。React は /_emdash/admin の管理 UI を動かします。サイト自体が React を使用していなくても必要です。

npm

npm install emdash @astrojs/react react react-dom

pnpm

pnpm add emdash @astrojs/react react react-dom

yarn

yarn add emdash @astrojs/react react react-dom

Cloudflare にデプロイしますか？Cloudflare パッケージも追加してください — Cloudflare にデプロイガイドで詳しく説明しています：

npm install @astrojs/cloudflare @emdash-cms/cloudflare

インテグレーションの登録

react() と emdash() の両方を integrations 配列に追加します。@astrojs/react の登録は省略できません：パッケージをインストールするだけでは不十分で、インテグレーションがないとアドミンはビルドされますがハイドレーションされません — ページは「Loading EmDash…」のまま永遠に止まります。

import { defineConfig } from "astro/config";
import node from "@astrojs/node";
import react from "@astrojs/react";
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",
			}),
		}),
	],
});

Live Collections ローダーの追加

src/live.config.ts を作成して、Astro のコンテンツレイヤーが EmDash コンテンツを解決できるようにします。これがないと、getEmDashCollection / getEmDashEntry にはルーティング先の Live Collection がありません。

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

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

既存の src/content.config.ts（ファイルベースのコレクション）はそのまま動作します — 両者の共存方法については Astro 開発者向け EmDash を参照してください。

インストールの検証

開発サーバーを起動：
```
npm run dev
```
http://localhost:4321/_emdash/admin を開き、セットアップウィザードを完了します。

投稿を作成して公開し、ページからクエリします：

---
import { getEmDashCollection } from "emdash";

const { entries: posts } = await getEmDashCollection("posts", {
	status: "published",
});
---

<ul>{posts.map((post) => <li>{post.data.title}</li>)}</ul>

Cloudflare にデプロイ

完全なセットアップ（D1 データベース、R2 メディアバケット、cron トリガー）については Cloudflare にデプロイに従ってください。特に既存プロジェクトでつまずく2つのポイント：

Cloudflare Workers を使用してください、Pages ではありません。 @astrojs/cloudflare アダプターは Pages が受け付けない wrangler.json を出力します。サイトが現在 Pages にデプロイしている場合、先に Workers に移行してください。
バインディングが wrangler.jsonc に存在する必要があります。 最低でもデータベース用の D1 バインディングとメディア用の R2 バインディングが必要で、astro.config.mjs のバインディング名と一致させます。

トラブルシューティング

症状	原因	修正
アドミンが「Loading EmDash…」で停止	`@astrojs/react` が未登録	`react()` を `integrations` に追加
`live.config.ts` で `Could not resolve "astro:content"`	Astro 6 より古い	Astro をアップグレード
`getEmDashCollection` がエラーを返す	`src/live.config.ts` がない	Live Collections ローダーを追加
未解決パッケージのビルドエラー	ピア依存関係がインストールされていない	`@astrojs/react`、`react`、`react-dom` を明示的にインストール
コンテンツの変更が表示されない	ページがプリレンダリングされている	動的ページに `export const prerender = false` を設定

次のステップ

Astro 開発者向け EmDash — EmDash の概念が既知の知識にどうマッピングされるか
コンテンツの操作 — コンテンツのクエリとレンダリング
Cloudflare にデプロイ — サイトを本番環境へ