第1部 基礎
第1章 EmDash とは
EmDash の設計思想とアーキテクチャ、はじめ方をつかむ。
読了の目安 約 38 分 ・ EmDash 1.3.1 / Astro 7 系(確認日 2026-10-29)
この章で学ぶこと
- EmDash (エムダッシュ) が何を解決する CMS で、どんなプロジェクトに向き、どんなときは向かないか
- 管理画面・Astro のページ・データベース・メディアストレージがどう組み合わさっているか
- コレクション (collection)、フィールド (field)、エントリ (entry)、シード (seed) というコンテンツモデルの基本語彙
- ローカルで EmDash サイトを動かし、既存の Astro プロジェクトに EmDash を足す手順
- 0.x から 1.0 へ上げるときの破壊的変更
- AI コーディングアシスタントと EmDash を連携させる 2 つの仕組み (Docs MCP とエージェントスキル)
基準は EmDash 1.3.1 (確認日 2026-10-29) です。
1.1 EmDash の設計思想
なぜ「Astro の中に CMS がある」のか
EmDash は Astro 用のコンテンツ管理システム (CMS) です。最大の特徴は、編集者向けの管理画面 (admin panel) が、公開サイトと同じ Astro アプリケーションの中に入っていることです。
WordPress では、管理画面 (wp-admin) とテーマが同じ PHP アプリケーションに同居していました。一方、近年の「ヘッドレス CMS」は、管理画面を別のサービスとして運用し、API でコンテンツを配信します。EmDash も、管理画面と公開サイトが 1 つのアプリケーションに同居する点では WordPress と似ています。ただし、フロントエンドは PHP ではなく Astro で、管理画面は React、コンテンツモデルはデータベースに持つなど、違いも多くあります (この対比は筆者の見解で、公式ドキュメントに WordPress との構造比較はありません)。
公式ドキュメントは、コンテンツがサイトに届く流れを次のように説明しています。
- 編集者が管理画面でエントリを作成・更新する
- EmDash が設定済みのデータベースに保存する
- Astro がページを描画するとき、ページが EmDash のクエリ関数を呼び、公開済みのエントリを受け取る
この 3 のしくみは Astro の「ライブコンテンツコレクション (Live Content Collections)」に接続されています。ライブコレクションはビルド時だけでなくリクエスト時にコンテンツを読み込めるため、サーバーレンダリングするページなら、公開した編集が次のリクエストで反映されます。
図 1-1 に示すように、編集の保存から公開ページへの反映は 3 段階で進み、どの描画方式かによって最後の段階の実行タイミングが変わります。
注意: プリレンダリング (事前生成) したページは、再ビルドするまで静的なままです。「公開したのに反映されない」ときは、まずそのページがプリレンダリングされていないかを疑ってください。
EmDash がやらないこと
EmDash が管理するのは構造化されたコンテンツです。ビジュアルなページビルダーではありません。HTML とデザインは Astro のコンポーネントが決めます。また、PHP、WordPress のテーマ、WordPress のプラグインは動きません。WordPress のコンテンツはインポートできますが、サイトのデザインとプラグイン固有の挙動は、Astro と EmDash 向けに作り直す必要があります。
向いているプロジェクト
公式の整理では、次の 4 条件がすべて当てはまると相性が良いとされています。
- サイトが Astro で作られている
- 編集者がリポジトリのファイルを触らずにコンテンツを管理したい
- 開発者が CMS とサイトを 1 つのアプリケーション・1 回のデプロイにまとめたい
- 開発者がサイトと一緒にデータベースとメディアストレージを運用できる
典型例は、制作会社が作ってクライアントの編集者に引き渡すサイト、小規模チームが保守する Astro サイト、フロントエンドを Astro で作り直す WordPress 移行です。
他の選択肢との比較
Astro でコンテンツを扱う方法は他にもあります。公式の比較表を、判断の軸ごとに整理します。
| 判断軸 | EmDash | ファイルベースの Astro コレクション | 別立てのヘッドレス CMS |
|---|---|---|---|
| 編集者の作業場所 | Astro アプリが配信する管理画面 | リポジトリ内のファイルと開発ツール | CMS 提供元、または別運用の管理アプリ |
| コンテンツの読み込み時点 | サーバーレンダリングされるページのリクエスト時 | 開発時またはサイトのビルド時 | ビルド時またはリクエスト時 (ネットワーク API 経由) |
| モデルの定義場所 | EmDash のデータベース (管理画面または CLI) | リポジトリ内のソースコード | CMS の設定 |
| チームが運用するもの | Astro アプリ、データベース、メディアストレージ | Astro アプリとビルドパイプライン | Astro アプリと CMS のアカウント/サービス |
| リリースの分離 | 管理画面とフロントエンドが一緒にデプロイされる | 通常コンテンツとフロントエンドが一緒にビルドされる | CMS とフロントエンドが独立にデプロイされる |
公式の結論は次のとおりです。コンテンツをバージョン管理に置きたく、寄稿者が Git に慣れているならファイルベース。複数のアプリケーションが 1 つの独立したコンテンツサービスを必要とするなら別立てのヘッドレス CMS。編集者と Astro サイトが 1 つのアプリを共有する利点があり、デプロイを共有してよいなら EmDash です。
向かないケースと運用コスト
公式は、Astro 以外で作るサイト、すべてのコンテンツをソースリポジトリに残す必要があるサイト、複数の無関係なフロントエンドに独立デプロイ可能な CMS が必要な場合は向かないとしています。また、データベース、メディアストレージ、バックアップ、アップグレード、管理画面を配信するアプリの責任をチームが負う、という運用作業が増える点も明記されています。
ホスティングとデータ
デプロイの形は主に 2 つです。
- Cloudflare Workers: コンテンツは Cloudflare D1、メディアは R2 に保存
- Node.js: コンテンツは SQLite、libSQL、PostgreSQL のいずれか。メディアはローカルファイルシステムまたは S3 互換サービス
データベースにはエントリだけでなくコンテンツモデルも入っています。そのため、サイトの稼働中でも管理者がモデルを変更できます。この柔軟さの代償は 1.4 節で扱います。
プラグイン
プラグインは、コンテンツやメディアのイベントに反応し、設定、ルート、管理画面ページ、ダッシュボードウィジェット、編集用コントロールを追加できます。形式は 2 つで、信頼境界が異なります。
- ネイティブプラグイン: ホストアプリケーションの一部として動き、ホストと同じアクセス権を持つ
- 標準形式 (standard-format) のプラグイン: サンドボックスランナーを設定し、必要な権限 (capability) を与えれば、隔離されたランタイムで動かせる
1.2 アーキテクチャ
全体像
公開ページと管理画面は、EmDash ランタイム、データベース、メディアストレージを共有します。「フロントエンド」と「別の CMS サービス」ではなく、1 つのデプロイ単位です。
図 1-2 に示すように、編集者は管理画面、訪問者は Astro のページを入口にし、どちらも EmDash ランタイムを通ってデータベースとメディアストレージを使います。
データベースには、コンテンツモデル、エントリ、ユーザー、設定などの CMS のレコードが入ります。メディアフィールドはファイルの実体ではなく、保存済みメディアアイテムへの参照を持ちます。
Astro 側の設定
EmDash サイトでは Astro を output: "server" にし、デプロイ先に合ったアダプターを入れます。管理画面、API ルート、現在のコンテンツをランタイムで配信するためです。
また、integrations に React と EmDash の両方を登録します。管理画面は React アプリだからです。
// astro.config.mjs (Node.js の例・要点のみ)
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" }),
}),
],
});注意:
@astrojs/reactをインストールしても、react()を integrations 配列に入れ忘れると、管理画面は「Loading EmDash...」のまま止まります。
storage を省略するとローカルストレージが既定になりますが、本番ではリリースやインスタンスをまたいで永続するストレージが必要です。
ページがコンテンツを取得する仕組み
src/live.config.ts が EmDash のローダーを Astro のライブコレクションとして登録します。
import { defineLiveCollection } from "astro:content";
import { emdashLoader } from "emdash/runtime";
export const collections = {
_emdash: defineLiveCollection({ loader: emdashLoader() }),
};ページ側は、一覧なら getEmDashCollection()、1 件なら getEmDashEntry() を呼びます。サーバーレンダリングされたページはリクエストごとに (設定したキャッシュの範囲内で) クエリを実行し、プリレンダリングされたページはビルド時に一度だけ実行します。
モデルの変更
管理者は管理画面でコレクションとフィールドを作れます。すると EmDash がデータベースのスキーマを変更します。シードファイルは、別環境に出発点のモデルを再現するためのバージョン管理しやすい記述で、生成される TypeScript 宣言は、開発者が現在のモデルをコードで使うための補助です。これらは同じモデルを記述・変更する手段であり、並行する複数のコピーではありません。
1.3 管理画面
なぜ重要か
編集者が日々触るのは管理画面です。管理画面は Astro アプリが /_emdash/admin/ で配信し、公開ページと同じデータベース・メディアストレージ・コンテンツモデル・プラグインを使います。新規サイトで最初にここを開くと、セットアップウィザードに遷移します。
主な作業領域
ナビゲーションはサイトのコレクションとインストール済みプラグインに応じて変わります。
ヒント: 本書の「画面」は、EmDash 1.3.1 のブログテンプレート(サンプルコンテンツ)で作った検証用サイトを、日本語のブラウザで開いたときの管理画面です。記事や名前はすべて架空のサンプルです。表示言語はブラウザの言語設定に従うため、英語で表示される部分もあります。
画面 1-1 は、ログイン直後のダッシュボードです。左のサイドバーからコンテンツ、メディア、メニューなどの作業領域に移動します。
画面 1-2 は、コンテンツの一覧(Posts)です。ステータスで絞り込み、検索、並べ替えができ、ゴミ箱のタブもあります。
| 領域 | 用途 |
|---|---|
| Dashboard | サイトやプラグインのウィジェットを置く起点画面 |
| コレクション名 (例: Posts) | エントリの一覧・作成・編集・公開・ゴミ箱への移動 |
| コレクショングループ | 同じグループのコレクションをまとめる折りたたみフォルダ |
| Media | ファイルのアップロード・検索・確認・差し替え・削除 |
| Taxonomies / Bylines | コンテンツの分類と、クレジット表示する著者の管理 |
| Menus / Widget Areas | サイトが描画するナビゲーションと編集可能な領域 |
| Comments | コレクションでコメントを有効にした場合のモデレーション |
| Content Types | コレクションとフィールドの作成・設定変更 |
| Plugins | プラグインのインストール・設定・プラグイン提供ページ |
| Settings | サイト、認証、バックアップ、サイト転送、メール、検索などの設定 |
注意: 管理画面で扱うのはデータと設定だけです。公開側のレイアウトは Astro のコンポーネントが決めます。管理画面でメニュー項目やウィジェットを足しても、Astro 側のコンポーネントがそのメニューやウィジェットエリアを問い合わせて描画していなければ、公開サイトには何も変わりません。
コンテンツエディタ
エディタのフォームは選択したコレクションから自動生成されます。短いテキストはテキスト入力、portableText フィールドはリッチテキストエディタ、メディアフィールドはメディアピッカー、参照フィールドは別エントリの選択、といった具合です。リッチテキストは見出し、リスト、引用、コード、リンク、画像、登録済みのカスタムブロックに対応します。インポートされたコンテンツにエディタが表示できないブロックがあっても、次回の保存で消さずに保持されます。
画面 1-3 は、公開済みの記事の編集画面です。中央にタイトル、アイキャッチ画像、本文のエディタがあり、右側のパネルに公開の状態、URL(スラッグ)、言語、執筆者があります。
ドラフト対応のコレクションでは、保存と公開が別の状態です。Save は現在の作業をドラフトとして保存し、Publish (または Publish changes) が、その保存済みバージョンを公開クエリから見えるようにします。スケジューリングは、ドラフトや保留中の変更をいつ公開するかを記録します。
編集ロック (edit locking) を有効にしたコレクションでは、エントリを開いた編集者がロックを保持し、その間は他の書き手が拒否されます。ロックがなくても、読み込み後にエントリが更新されていれば古い内容での保存は拒否され、編集者は最新版を読み込み直すことになります。
ロールと権限
ロールは Subscriber、Contributor、Author、Editor、Admin の 5 つです。権限は上位ロールほど積み上がりますが、コンテンツとメディアの操作では所有者であるかどうかも効きます。たとえば Author は自分のエントリを編集・公開でき、Editor は任意のエントリでそれができます。
- Editor: タクソノミー、メニュー、バイライン、ウィジェット、セクション、他の著者のコンテンツを管理できる
- Admin: コンテンツモデル、ユーザー、プラグイン、リダイレクト、バックアップ、設定を変更でき、サイト全体のエクスポート/インポートや、ゴミ箱のコンテンツの完全削除ができる
セキュリティ: 権限チェックはサーバーが操作ごとに行います。ナビゲーション項目を隠すことはセキュリティ境界ではありません。プラグインが管理画面ページを足す場合も、保護すべき操作ではサーバー側で権限を確認する必要があります (リンクを特定ロールにだけ見せていても同じです)。
メディアとプラグイン UI
メディアライブラリはグリッド/リスト表示、検索、絞り込み、メタデータ表示、複数選択操作を備えます。アップロードの挙動はストレージアダプター次第で、署名付きアップロードに対応する場合、ブラウザが短命の署名 URL でストレージへ直接送り、完了を EmDash に確認します。メディアの削除は、それを参照するエントリに影響しうるため、使用状況の表示や差し替え機能を使ってから削除してください。
プラグインは、ダッシュボードウィジェット、設定セクション、編集用コントロール、完全な管理ページを追加できます。ただしプラグインのページは自身の管理ルート配下に置かれ、コア画面を置き換えることはできません。
1.4 コンテンツモデル、コレクション、フィールド
用語
- コレクション (collection): コンテンツの種類 (Posts、Products、Authors など)
- フィールド (field): その種類が持つ個々の情報 (タイトル、本文、価格など)
- エントリ (entry): コレクションに保存された 1 件
EmDash は、ID、公開スラッグ、公開状態、著者、作成/更新日時、ロケール、リビジョン参照のように、全エントリに必要な情報も管理します。クエリ結果にはこれらの標準情報が、コレクション固有のフィールドと並んで出てきます。
エントリを削除するとゴミ箱に入り (削除日時が設定される)、管理者は完全削除されるまで復元できます。これはフィールドやコレクションの削除とは別物です。後者はスキーマを変更し、保存されたデータを消します。
1 つのモデルを 2 通りで管理する
モデルは管理画面の Content Types で作成・編集できます。もう一つの方法がシードファイル (JSON) で、テンプレートはセットアップ時にこれでコレクションなどを作ります。チームがシードをバージョン管理し、別環境を作るときに適用することもできます。管理画面とシードが別々のモデルを持つわけではなく、どちらも対象データベースに保存されたモデルを変更します。
画面 1-4 は、管理画面の「コンテンツタイプ」の一覧です。コレクションごとに、有効になっている機能(drafts、revisions、preview、scheduling、search、seo など)が表示されます。
{
"version": "1",
"collections": [{
"slug": "posts", "label": "Posts", "labelSingular": "Post",
"fields": [
{ "slug": "title", "label": "Title", "type": "string", "required": true },
{ "slug": "content", "label": "Content", "type": "portableText" }
]
}]
}シードにはコレクションのほか、設定、タクソノミー、メニュー、ウィジェットエリア、リダイレクト、サンプルコンテンツも含められます (詳細は公式のシードファイルリファレンスを参照)。
コレクションの識別子と振る舞い
コレクションには複数形ラベル、任意の単数形ラベル、スラッグがあります。ラベルは管理画面の表示用で、スラッグがクエリ、API ルート、シード、データベースでの識別子です。
落とし穴: 管理画面ではコレクションのスラッグもフィールドのスラッグも後から変更できません。既存のクエリや保存済みカラムが依存するためです。作る前に決めてください。スラッグは小文字で始まり、小文字・数字・アンダースコアのみ、最大 63 文字です。EmDash 自身のルートやエントリデータで使う予約名は拒否されます。
コレクションの設定で、次の振る舞いを選べます。
| 設定 | 内容 |
|---|---|
| Routable | 公開にはスラッグが必須。URL パターンにスラッグや ID、公開日を組み込める |
| Drafts | 公開前に下書きを保存できる |
| Revisions | 内容履歴のスナップショットを保持 |
| Preview | 未公開コンテンツ向けの署名付きプレビュー URL |
| Search | 検索対象に指定したフィールドの全文検索 |
| SEO | タイトル・説明・画像のメタデータフィールドを追加し、サイトマップに含める |
| Edit locking | 作業中の編集者が保持し、他の書き手を拒否 |
| Comments | コレクション単位で有効化。モデレーションと自動クローズの設定あり |
| Icon / Hide from navigation / Group | サイドバーの見た目と整理に関する設定 |
URL パターンは、各プレースホルダーが専用のパスセグメントを持つ必要があります。/{year}/{month}/{slug}.html は有効ですが、/{year}{month}/{slug} や /{slug}-{id} は拒否されます。サイトで実際に使う振る舞いだけを有効にしてください。たとえば Preview をオンにしても、Astro のページがエントリとプレビュー状態を正しく描画しなければ意味がありません。
フィールドタイプ
フィールドタイプは 17 種類で、編集者が入力する値と、コードが受け取る形に対応します。
| 用途 | タイプ |
|---|---|
| 短い/長いテキスト | string, text, slug, url |
| 数値 | number, integer |
| 状態と時刻 | boolean, datetime |
| 固定の選択肢 | select, multiSelect |
| リッチ/構造化データ | portableText, json, repeater, blocks |
| メディア | image, file |
| 関連 | reference |
タイプは編集用コントロールであるだけでなく、保存形式と検証、生成される TypeScript 宣言にも影響します。
フィールドには、Required、Unique、Default value、Validation、Searchable、Indexed、Translatable といったルールを付けられます。Indexed は、ソートや絞り込みに使うカスタムフィールドにだけオンにします。ストレージを消費し、作成/更新のたびに作業が増えるため、「ページに表示するから」という理由でインデックスを付けないでください。対象は string、url、number、integer、boolean、datetime、select、reference、slug で、リッチテキスト、JSON、リピーター、複数選択は使えません。
reference フィールドは、コレクション自身のテーブルには何も保存せず、リンクを別に保持します。クエリ結果では data ではなく references に出てくるので、関連コンテンツを、コピーせずに読み込めます。
後からの変更とデータの安全性
追加は安全です。ラベル、検証、検索設定、インデックス、ウィジェットオプション、表示順は、フィールドを作り直さずに変更できます。フィールドを追加しても既存エントリは残りますが、新しいフィールドの値は、編集者かマイグレーションが与えるまで空です (既定値を設定すれば初期値を入れられます)。
注意: 破壊的な変更に注意してください。 - フィールドの削除は、データベースのカラムを落とし、全エントリのその値を消します。 - コレクションの削除は、コンテンツテーブルと全エントリを落とします。 - 管理画面では既存フィールドのタイプを変更できません。スキーマ API が許す in-place のタイプ変更は
string・text・slugの間だけです。他のタイプ変更、required/uniqueの変更、translatable から非 translatable への変更は、コンテンツのマイグレーションが必要です。本番データのバックアップを取り、代表的なコンテンツでマイグレーションを試し、変更するフィールドに依存するクエリとコンポーネントを更新してから実施してください。デプロイ中は旧コードと新コードの互換性も必要です。
TypeScript 宣言
EmDash は、データベースのモデルから TypeScript 宣言を生成できます。クエリ関数にコレクション名とフィールドの型が加わり、posts を問い合わせると data.title や data.content が型付きで得られます。ローカル開発中は Astro インテグレーションが emdash-env.d.ts を書き出し、スキーマ変更のたびに更新します。生成物なので手で編集せず、モデルのほうを編集してください。リモートのサイトに対しては emdash types で .emdash/types.ts を出力でき、モデルを変えたら再生成が必要です。
型はスキーマにコードを合わせる助けにはなりますが、保存済みコンテンツを移行はしません。モデルの変更と、必要なコンテンツのマイグレーションは別の作業です。
1.5 はじめ方 (新規サイト)
なぜこの手順か
公式のチュートリアルは、クラウドアカウント不要でひととおり体験できるよう、Node.js、SQLite、ローカルメディアストレージ、Starter テンプレートを選びます。
手順
- Node.js 22.23.4 以降と npm を用意する (
node --versionで確認) - スキャフォールダーを起動する
npm create emdash@latest- プロンプトでは、プロジェクト名
my-emdash-site、デプロイ先 Node.js、テンプレート Starter、検出されたパッケージマネージャー、依存関係インストール Yes を選ぶ。Posts と Pages を持つ汎用の Node.js サイトができ、生成されたEMDASH_ENCRYPTION_KEYが gitignore 済みの.envに書かれる cd my-emdash-siteしてnpm run devで開発サーバーを起動する (通常http://localhost:4321/)http://localhost:4321/_emdash/admin/を開き、セットアップウィザードで Site Title、メールアドレスを入力し、パスキー (passkey) を登録して Open the dashboard を選ぶ- Posts の Welcome を開いて題名を変更し、Save、次に Publish changes を実行する。トップページに新しい題名が出ることを確認する
トップページが公開済みの投稿を取得する部分は、次のコードと同等です。
---
import { getEmDashCollection } from "emdash";
const { entries: posts, cacheHint } = await getEmDashCollection("posts", {
orderBy: { published_at: "desc" },
});
if (Astro.cache?.enabled) Astro.cache.set(cacheHint);
---
<ul>{posts.map((post) => <li>{post.data.title}</li>)}</ul>
初回にサイトを開くと、セットアップ画面が表示されます(画面 1-5)。サイトのタイトルとキャッチフレーズを決め、サンプルコンテンツ、空のサイト、既存の EmDash サイトのインポートから開始方法を選びます。続いてアカウントを作成し、最後にパスキーを作成します(画面 1-6)。
生成物の見方
astro.config.mjs がサーバーレンダリング、Node.js アダプター、管理画面用の React、EmDash のデータベースとメディアディレクトリを設定します。src/live.config.ts がデータベースのコンテンツを Astro のライブコレクションにつなぎます。seed/seed.json が Posts と Pages のコレクション、フィールド、サンプルコンテンツを定義します。.env の暗号化キーは、モデルとコンテンツを持つ SQLite ファイルとは別に実行時に供給されます。
セキュリティ:
.envをコミットしないでください。デプロイ前にEMDASH_ENCRYPTION_KEYのバックアップを取ってください。このキーがないと、EmDash は保存済みのプラグインシークレットを復号できません。
次に読むもの
公式は、クエリのガイド (フィルタ、ページネーション、下書き、エラー処理)、メディアライブラリのガイド、Cloudflare Workers と Node.js へのデプロイを案内しています。
1.6 既存の Astro プロジェクトに追加する
なぜ
すでに Astro サイトがあるなら、スキャフォールドし直さずに EmDash を足せます。ここでも Node.js アダプター、SQLite、ローカルメディアで、一台のマシンで完結する経路を取ります。
前提
Astro 6 以降と Node.js 22.16 以降が必要です。Astro 7.4 以降を使うプロジェクトでは Node.js 22.23.4 以降を使ってください。
落とし穴: この手順はサイトを Astro の
server出力に変更し、Node.js アダプターを設定します。ビルドとデプロイの方法が変わります。すでに別のサーバーアダプターがあるなら 2 つ目を足さず、そのアダプターのまま進めてください (Cloudflare なら公式の Cloudflare Workers ガイド)。作業前にプロジェクトをコミットなどで保存します。
手順
- パッケージを入れる
npm install emdash @astrojs/node @astrojs/react react react-dom公開サイトに React コンポーネントがなくても、管理画面が React を使うため必要です。
astro.config.mjsに、アダプター、react()、emdash({...})を登録する (1.2 節の例と同じ)。既存の設定は残し、必要な項目だけ足します。SQLite のdata.dbとuploads/は.gitignoreに追加します。src/live.config.tsに_emdashエントリを作る。既にあるファイルは置き換えずにcollectionsへ追加します。ファイルベースのsrc/content.config.tsは併存できます。npx emdash secrets generate --write .envで暗号化キーを生成する。キーを失う/置き換えると暗号化済みの値が読めなくなるため、デプロイ前に保護されたバックアップを取ります。npm run devで起動し、/_emdash/admin/のウィザードでサイト情報、管理者アカウント、パスキーを設定する。シードファイルがないプロジェクトでは、EmDash の組み込み開始モデル (Posts と Pages のコレクション、Title と content のフィールド、Category と Tag のタクソノミー) が適用され、サンプルエントリは作られません。- Posts で新規エントリを作り、Save、Publish。
- 確認用ページ (例:
src/pages/emdash-test.astro) でgetEmDashCollection("posts")を呼んで表示する
うまくいかないとき
- 管理画面が Loading EmDash... のまま:
react()が integrations にあるか確認 - ライブコレクションに関するエラー:
src/live.config.tsがemdashLoader()を使った_emdashを export しているか確認 - 開発では動くがデプロイ後に編集が反映されない: ページがプリレンダリングされていないか、デプロイ先がサーバー出力か確認
- import が解決できない: 別のワークスペースディレクトリではなく、このプロジェクトに 5 つのパッケージが入っているか確認
1.7 EmDash 1.0 への移行
なぜ
1.0 では、0.x で非推奨だった API が削除され、EmDash 自身だけが読み込むエントリポイントが emdash/internal/ 配下に移されました。0.x のサイトは、更新後にビルドや起動でエラーになる可能性があります。
基本手順
emdash と使っている他の EmDash パッケージを最新に更新し、ビルドし直します (Cloudflare サイトの例: pnpm up --latest emdash @emdash-cms/cloudflare のあと pnpm build)。デプロイで emdash migrate を実行しているなら、アップグレード後のビルドで生成された .emdash/migrations.json に対して実行します。以前のバージョンが書いたマニフェストは拒否されます。更新だけで問題なく動く場合もあります。
破壊的変更の一覧
| 変更 | 影響 | 対処 |
|---|---|---|
cloudflareCache() 削除 |
import するサイトはビルド失敗 | Astro Cloudflare アダプターの cacheCloudflare() に置き換える。EmDash は cloudflare:workers の cache.purge() でタグ単位に purge するため、CF_ZONE_ID と CF_CACHE_PURGE_TOKEN のシークレットは削除できる。KV のオブジェクトキャッシュ (kvCache()) は変更なし |
emdash/ui からの Comments / CommentForm 削除 |
emdash/ui から import するとビルド失敗 |
emdash/ui/comments から import する。コンポーネント自体は同じ |
emdash dev と emdash auth secret 削除 |
実行すると Unknown command |
自サイトの dev スクリプト (pnpm dev) か astro dev を使う。package.json の emdash 配下の url キーは削除。リモートサイトから型を作るなら emdash types --url <site-url> か EMDASH_URL。EMDASH_AUTH_SECRET が設定済みなら残す (コメント投稿者 IP ハッシュを安定させるため読み込まれ続ける)。プラグインシークレットの暗号化には emdash secrets generate |
experimental.registry 削除 |
設定が残っていると起動時にエラー | 値をそのまま最上位の registry オプションへ移す。空の experimental: {} は削除 |
内部エントリポイントを emdash/internal/ へ移動 |
直接 import している場合に影響。emdash() 経由で設定するサイトは影響なし |
公開 API (sqlite() / libsql() / postgres()、memoryCache()、localMedia()、@emdash-cms/plugin-test、emdash() の middleware.outer) に置き換える |
emdash/internal/ 配下は公開 API ではなく、どのリリースでもエクスポートが変わりえます。
非推奨 (1.x の間は動作) の項目として、read:content、network:fetch、page:inject のような旧プラグイン capability 名があります。起動時に警告が出て、現在の名前 (例: read:content → content:read) が表示されます。使っているプラグインが警告を出すなら更新版を使うか作者に依頼し、自作ならマニフェストの名前を直します。
1.8 AI 連携: Docs MCP とエージェントスキル
2 つの仕組みの違い
AI コーディングアシスタントが古い知識で EmDash の API を書いてしまう問題に対し、EmDash は 2 つの手段を用意しています。
| Docs MCP | エージェントスキル | |
|---|---|---|
| 何か | 公式ドキュメントを検索する公開 MCP サーバー | 手順と参考資料をまとめたフォルダ (アシスタントが必要なときに読む) |
| 向き | API 名、フック名、設定項目を最新ドキュメントで調べる | 現在の EmDash のパターンに沿ってサイト構築・プラグイン作成・移植を行う |
Docs MCP
https://docs.emdashcms.com/mcp で公開されている Model Context Protocol サーバーです。認証や API キーは不要で、読み取り専用です。公開するツールは search_docs の 1 つで、Cloudflare AI Search で docs.emdashcms.com のインデックスを検索し、ソース URL と一致した箇所を返します。回答にどう使うかは AI クライアントが決めます。
これは、自サイトのコンテンツを管理する「サイト MCP」(AI Tools ガイド参照) とは別物です。Docs MCP はドキュメントしか知らず、コンテンツの読み書きはできません。
npm create emdash で作ったプロジェクトには、.mcp.json (Claude Code)、.cursor/mcp.json (Cursor)、.vscode/mcp.json (VS Code) があらかじめ入っており、ワークスペースの信頼確認を承認すれば自動で使われます。テンプレートを使わない場合は、たとえば Claude Code なら次のコマンドで追加できます。Codex、OpenCode、ChatGPT、Claude のカスタムコネクタ向けの手順も公式にあります。
claude mcp add --transport http emdash-docs https://docs.emdashcms.com/mcpAGENTS.md などに、「EmDash の API やフック、設定は emdash-docs MCP で確認し、学習データの推測より優先する」という趣旨の一節を書いておくと効果的です (スターターテンプレートには同梱済み)。
セキュリティ: Docs MCP は EmDash プロジェクトがホストし、クエリは
docs.emdashcms.comに送られて Cloudflare AI Search が処理します。非公開のコード、シークレット、ユーザーデータをクエリに含めないでください。
エージェントスキル
スキルは agentskills.io 形式の、指示と参考資料のフォルダです。EmDash は次のスキルを公開しています。
| スキル | 用途 |
|---|---|
building-emdash-site |
スキーマ/シード、クエリ、Portable Text、メニュー、タクソノミー、デプロイ |
creating-plugins |
サンドボックス/ネイティブプラグイン (フック、ルート、ストレージ、管理 UI) |
emdash-cli |
コマンドラインからのサイト管理 |
upgrading-emdash |
パッケージ、プロジェクトコード、スキル、コアのマイグレーションの更新 |
wordpress-theme-to-emdash |
WordPress テーマの移植 |
wordpress-plugin-to-emdash |
WordPress プラグインの挙動の移植 |
npm create emdash のプロジェクトには、building-emdash-site、creating-plugins、emdash-cli が .agents/skills/ に入っています (.claude/skills は同じファイルへの互換リンク)。これらは作成時のバージョンのままなので、更新や WordPress 移植スキルの追加には、リポジトリ (emdash-cms/skills) から入れます。
npx skills add emdash-cms/skillsCodex や Claude Code にはプラグインマーケットプレイス経由の導入方法もあります。更新は npx skills update (ユーザー単位なら -g)、Claude Code なら /plugin marketplace update emdash です。WordPress 移植のスキルは building-emdash-site と creating-plugins を参照するため、併せて入れてください。問題の報告は、EmDash 本体リポジトリの skills/ フォルダに対して行い、emdash-cms/skills では受け付けません。
ヒント: Docs MCP は文書検索、スキルは作業手順の資料、という役割の整理は筆者のものです (公式は両者を別々のページで説明しています)。Docs MCP とスキルの併用可否は公式ドキュメントに記載がありません。一方、Docs MCP とサイトの MCP サーバーについては、Docs MCP のページが「両方に接続してよい」と明記しています。
WordPress との違い
| 観点 | WordPress | EmDash |
|---|---|---|
| 実行基盤 | PHP + MySQL | Astro (サーバーレンダリング) + SQLite/D1/libSQL/PostgreSQL |
| 管理画面とテーマ | 同一アプリ内 (PHP) | 同一アプリ内 (管理画面は React、テーマは Astro) |
| コンテンツの定義 | 投稿タイプやメタ (コード/プラグインで定義) | 管理画面またはシードファイルでコレクションとフィールドを定義 |
| リッチテキスト | Gutenberg ブロック (HTML) | Portable Text |
| 拡張 | PHP プラグイン | ネイティブ/標準形式のプラグイン (サンドボックス可) |
| デプロイ | サーバーにファイルとデータベースを配置 | コードのデプロイとデータベースの内容が別 (モデルもデータベース側) |
詳細な対応は第2章で扱います。
セキュリティ上の注意
EMDASH_ENCRYPTION_KEYは.envに置き、コミットせず、バックアップを取る- 権限はサーバー側で検証される。プラグインを書くときも、サーバー側で権限を確認する
- ネイティブプラグインはホストと同じアクセス権で動く。信頼できないプラグインはサンドボックス形式を検討する
- Docs MCP のクエリに機密情報を含めない
まとめ
- EmDash は、管理画面と Astro サイトが 1 つのアプリケーションに同居する CMS で、コンテンツは Astro のライブコレクション経由でリクエスト時に取得される
- サーバーレンダリングが前提。プリレンダリングしたページは再ビルドまで更新されない
- モデルはコレクション、フィールド、エントリで構成され、データベースに保存される。管理画面とシードは同じモデルを操作する
- スラッグは後から変えられない。フィールド/コレクションの削除とタイプ変更はデータに影響するため、計画とバックアップが必要
- 新規は
npm create emdash@latest、既存の Astro にはemdashなどを入れ、astro.config.mjsとsrc/live.config.tsを設定する - 1.0 では、廃止 API と内部エントリポイントの移動に対応する必要がある
- AI 連携には Docs MCP (調べる) とエージェントスキル (作業の手順) がある
理解度チェック
- 公開済みの編集が反映されないとき、まず確認すべき Astro 側の設定やページの性質は何ですか。
- 管理画面で、コレクションのスラッグとフィールドのスラッグについて、作成後にできないことは何ですか。それはなぜですか。
- フィールドを削除する操作と、エントリをゴミ箱へ移動する操作の違いを説明してください。
- 既存の Astro プロジェクトに EmDash を追加する際、管理画面が「Loading EmDash...」のまま止まる原因として公式が挙げているものは何ですか。
- 1.0 で
emdash devが削除されました。代わりに何を使いますか。 - Docs MCP とサイト MCP の違いを述べてください。
答え
- ページがプリレンダリングされていないか(サーバーレンダリングされているか)、デプロイ先がサーバー出力か。プリレンダリング済みのページは再ビルドまで更新されない。
- 管理画面では、どちらのスラッグも後から変更(リネーム)できません。既存のクエリや保存済みカラムが依存するためです。
- フィールド削除はデータベースのカラムを落として全エントリのその値を消す破壊的なスキーマ変更。エントリのゴミ箱への移動は削除日時を設定するだけで、管理者が復元できる。
@astrojs/reactをインストールしてもreact()をintegrationsに登録していないこと。- サイト自身の dev スクリプト (
pnpm devなど) かastro dev。サイトの設定にあるデータベースアダプターが使われる。 - Docs MCP は公式ドキュメントを検索するだけの公開・読み取り専用サーバー。サイト MCP は自分のサイトのコンテンツを管理するためのもので、別のサーバー。
出典
- 1.1 設計思想: https://docs.emdashcms.com/why-emdash/
- 1.2 アーキテクチャ: https://docs.emdashcms.com/concepts/architecture/
- 1.3 管理画面: https://docs.emdashcms.com/concepts/admin-panel/
- 1.4 コンテンツモデル: https://docs.emdashcms.com/concepts/content-model/ , https://docs.emdashcms.com/concepts/collections/
- 1.5 はじめ方: https://docs.emdashcms.com/getting-started/
- 1.6 既存プロジェクト: https://docs.emdashcms.com/existing-project/
- 1.7 1.0 への移行: https://docs.emdashcms.com/upgrade-to-v1/ , https://github.com/emdash-cms/emdash/releases
- 1.8 Docs MCP: https://docs.emdashcms.com/docs-mcp/ ; エージェントスキル: https://docs.emdashcms.com/agent-skills/ , https://github.com/emdash-cms/skills
- 元資料:
sources/emdash-docs/(MIT, Copyright 2026 Cloudflare Inc.)