ものしり

第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 との構造比較はありません)。

公式ドキュメントは、コンテンツがサイトに届く流れを次のように説明しています。

  1. 編集者が管理画面でエントリを作成・更新する
  2. EmDash が設定済みのデータベースに保存する
  3. Astro がページを描画するとき、ページが EmDash のクエリ関数を呼び、公開済みのエントリを受け取る

この 3 のしくみは Astro の「ライブコンテンツコレクション (Live Content Collections)」に接続されています。ライブコレクションはビルド時だけでなくリクエスト時にコンテンツを読み込めるため、サーバーレンダリングするページなら、公開した編集が次のリクエストで反映されます。

図 1-1 に示すように、編集の保存から公開ページへの反映は 3 段階で進み、どの描画方式かによって最後の段階の実行タイミングが変わります。

図 1-1: 編集者の更新がデータベースに保存され、Astro がページを描画するときに取得される流れと、サーバーレンダリングとプリレンダリングでの反映の違い

注意: プリレンダリング (事前生成) したページは、再ビルドするまで静的なままです。「公開したのに反映されない」ときは、まずそのページがプリレンダリングされていないかを疑ってください。

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 ランタイムを通ってデータベースとメディアストレージを使います。

図 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-1: ダッシュボード(下書き・メディア・ユーザーの件数と、最近の更新)

画面 1-2 は、コンテンツの一覧(Posts)です。ステータスで絞り込み、検索、並べ替えができ、ゴミ箱のタブもあります。

画面 1-2: Posts の一覧(ステータス・日付・操作)
領域 用途
Dashboard サイトやプラグインのウィジェットを置く起点画面
コレクション名 (例: Posts) エントリの一覧・作成・編集・公開・ゴミ箱への移動
コレクショングループ 同じグループのコレクションをまとめる折りたたみフォルダ
Media ファイルのアップロード・検索・確認・差し替え・削除
Taxonomies / Bylines コンテンツの分類と、クレジット表示する著者の管理
Menus / Widget Areas サイトが描画するナビゲーションと編集可能な領域
Comments コレクションでコメントを有効にした場合のモデレーション
Content Types コレクションとフィールドの作成・設定変更
Plugins プラグインのインストール・設定・プラグイン提供ページ
Settings サイト、認証、バックアップ、サイト転送、メール、検索などの設定

注意: 管理画面で扱うのはデータと設定だけです。公開側のレイアウトは Astro のコンポーネントが決めます。管理画面でメニュー項目やウィジェットを足しても、Astro 側のコンポーネントがそのメニューやウィジェットエリアを問い合わせて描画していなければ、公開サイトには何も変わりません。

コンテンツエディタ

エディタのフォームは選択したコレクションから自動生成されます。短いテキストはテキスト入力、portableText フィールドはリッチテキストエディタ、メディアフィールドはメディアピッカー、参照フィールドは別エントリの選択、といった具合です。リッチテキストは見出し、リスト、引用、コード、リンク、画像、登録済みのカスタムブロックに対応します。インポートされたコンテンツにエディタが表示できないブロックがあっても、次回の保存で消さずに保持されます。

画面 1-3 は、公開済みの記事の編集画面です。中央にタイトル、アイキャッチ画像、本文のエディタがあり、右側のパネルに公開の状態、URL(スラッグ)、言語、執筆者があります。

画面 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 など)が表示されます。

画面 1-4: コンテンツタイプの一覧(コレクションと、有効な機能)
{
  "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 テンプレートを選びます。

手順

  1. Node.js 22.23.4 以降と npm を用意する (node --version で確認)
  2. スキャフォールダーを起動する
npm create emdash@latest
  1. プロンプトでは、プロジェクト名 my-emdash-site、デプロイ先 Node.js、テンプレート Starter、検出されたパッケージマネージャー、依存関係インストール Yes を選ぶ。Posts と Pages を持つ汎用の Node.js サイトができ、生成された EMDASH_ENCRYPTION_KEY が gitignore 済みの .env に書かれる
  2. cd my-emdash-site して npm run dev で開発サーバーを起動する (通常 http://localhost:4321/)
  3. http://localhost:4321/_emdash/admin/ を開き、セットアップウィザードで Site Title、メールアドレスを入力し、パスキー (passkey) を登録して Open the dashboard を選ぶ
  4. 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)。

画面 1-5: セットアップ画面(サイトのタイトルと、開始方法の選択)
画面 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 ガイド)。作業前にプロジェクトをコミットなどで保存します。

手順

  1. パッケージを入れる
npm install emdash @astrojs/node @astrojs/react react react-dom

公開サイトに React コンポーネントがなくても、管理画面が React を使うため必要です。

  1. astro.config.mjs に、アダプター、react()、emdash({...}) を登録する (1.2 節の例と同じ)。既存の設定は残し、必要な項目だけ足します。SQLite の data.db と uploads/ は .gitignore に追加します。
  2. src/live.config.ts に _emdash エントリを作る。既にあるファイルは置き換えずに collections へ追加します。ファイルベースの src/content.config.ts は併存できます。
  3. npx emdash secrets generate --write .env で暗号化キーを生成する。キーを失う/置き換えると暗号化済みの値が読めなくなるため、デプロイ前に保護されたバックアップを取ります。
  4. npm run dev で起動し、/_emdash/admin/ のウィザードでサイト情報、管理者アカウント、パスキーを設定する。シードファイルがないプロジェクトでは、EmDash の組み込み開始モデル (Posts と Pages のコレクション、Title と content のフィールド、Category と Tag のタクソノミー) が適用され、サンプルエントリは作られません。
  5. Posts で新規エントリを作り、Save、Publish。
  6. 確認用ページ (例: 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/mcp

AGENTS.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/skills

Codex や 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 (調べる) とエージェントスキル (作業の手順) がある

理解度チェック

  1. 公開済みの編集が反映されないとき、まず確認すべき Astro 側の設定やページの性質は何ですか。
  2. 管理画面で、コレクションのスラッグとフィールドのスラッグについて、作成後にできないことは何ですか。それはなぜですか。
  3. フィールドを削除する操作と、エントリをゴミ箱へ移動する操作の違いを説明してください。
  4. 既存の Astro プロジェクトに EmDash を追加する際、管理画面が「Loading EmDash...」のまま止まる原因として公式が挙げているものは何ですか。
  5. 1.0 で emdash dev が削除されました。代わりに何を使いますか。
  6. Docs MCP とサイト MCP の違いを述べてください。

答え

  1. ページがプリレンダリングされていないか(サーバーレンダリングされているか)、デプロイ先がサーバー出力か。プリレンダリング済みのページは再ビルドまで更新されない。
  2. 管理画面では、どちらのスラッグも後から変更(リネーム)できません。既存のクエリや保存済みカラムが依存するためです。
  3. フィールド削除はデータベースのカラムを落として全エントリのその値を消す破壊的なスキーマ変更。エントリのゴミ箱への移動は削除日時を設定するだけで、管理者が復元できる。
  4. @astrojs/react をインストールしても react() を integrations に登録していないこと。
  5. サイト自身の dev スクリプト (pnpm dev など) か astro dev。サイトの設定にあるデータベースアダプターが使われる。
  6. 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.)