ハンズオン：AIとプラグインを作る

本サイトの補足

注意

生成AIを使う前に知っておくこと

AIの回答が、古い仕様に基づくことがあります。EmDashは2026年4月に公開され、更新が速いためです。たとえば、廃止方向の Marketplace、旧形式の権限名 read:content（現在は content:read）、旧パッケージ名 @emdash-cms/registry-cli（現在は @emdash-cms/plugin-cli）をAIが案内することがあります。プラグイン開発では特に、この3つに注意してください。
AIツールに公式のDocs MCP（https://docs.emdashcms.com/mcp）を接続すると、最新の公式ドキュメントを参照させられます。接続方法は「生成AIと一緒に進める準備」と「AIツール向けDocs MCP」で説明しています。
公式テンプレートには、AI向けの指示ファイル AGENTS.md と、Docs MCPの設定ファイルが最初から入っています。このハンズオンも、テンプレートから作ったEmDashサイトを使います。プラグインの作成ツールも、AGENTS.md とプラグイン作成用のスキル（skills/creating-plugins/SKILL.md）を含むプロジェクトを作ります。

完成するもの

save-log という名前のサンドボックス型プラグイン。次の2つの機能を持ちます
- フック：コンテンツが保存されるたびに、保存イベントをプラグインのストレージに記録する
- APIルート：health という公開ルートで、プラグインが動いていることを返す
このプラグインを登録し、両方の機能が動くことを確認したローカルのEmDashサイト

（公式「はじめてのサンドボックス型プラグイン」）

所要時間

目安：45分

AIエージェントによる実測のあとに、この時間を更新します。

必要なもの

種類	必要なもの	補足
ツール	Node.jsとpnpm	プラグインの作成ツールはpnpmで動かします
EmDashのサイト	サンドボックスランナーを設定したサイト	このハンズオンでは、公式「はじめてのEmDashサイト作成」で作るNode.jsのサイト（`my-emdash-site`）を使い、ステップ1でランナーを設定します
アカウント	Atmosphereアカウントのハンドル、またはDID	マニフェストの `publisher` に使います。Blueskyのアカウントは、Atmosphereアカウントの1つです（公式「バンドルと公開」）
ツール	生成AIツール	ターミナルでコマンドを実行できるAIツール（Claude Code、Cursor、Codexなど）、またはチャット型のAI（ChatGPT、Claudeのチャットなど）。使い方の違いは「依頼文の使い方」で説明します

プラグインの形式をまだ決めていない場合は、先に「プラグイン形式の選び方」を読みます。公式ドキュメントは、ネイティブ型だけが持つ連携が必要な場合を除き、サンドボックス型を選ぶよう説明しています。

手順の全体像

図のテキストを読む

flowchart TD
    S1["1. サイトにサンドボックスランナーを設定"] --> S2["2. プラグインの雛形を作る"]
    S2 --> S3["3. マニフェストに権限とストレージを書く"]
    S3 --> S4["4. フックとルートを書く"]
    S4 --> S5["5. テストを書き換える"]
    S5 --> S6["6. 検証してビルド"]
    S6 --> S7["7. サイトに登録"]
    S7 --> S8["8. 動かして確認"]

ディレクトリは、サイト（my-emdash-site）とプラグイン（save-log）を同じ階層に並べます。公式の登録コマンドは、この並びを前提にしています。

依頼文の使い方

依頼文は、そのままコピーしてAIに貼り付けられる形にしています。
AIツールによって、コマンドを実行する人が違います。依頼文はどちらの種類でも同じ文面で使えます。
- ターミナルでコマンドを実行できるAIツール（Claude Code、Cursor、Codexなど）：依頼文を渡すと、AIがファイルの書き換えとコマンドの実行をします。
- チャット型のAI（ChatGPT、Claudeのチャットなど）：AIが示したコードとコマンドを、自分でファイルとターミナルに貼って実行します。
コードは公式ドキュメントに載っているものをそのまま使うよう、依頼文で指定しています。AIが独自のコードに書き換えた場合は、公式ページのコードと見比べます。

ステップ

ステップ1：サイトにサンドボックスランナーを設定する

サンドボックス型プラグインを動かすには、プラグインの登録に加えて、実行環境ごとのランナーが必要です。ランナーが使えないとき、EmDashは sandboxed に登録したプラグインを読み込みません。Node.jsでは、ランナーと workerd をインストールし、emdash() の sandboxRunner でランナーを指定します。（公式「プラグインサンドボックス」）

本サイトの補足 · AIへの依頼文

AIに聞いてみよう

目的：Node.jsのEmDashサイトで、サンドボックス型プラグインを動かせるようにする

依頼文

公式ドキュメント「Create your first EmDash site」
（https://docs.emdashcms.com/getting-started/）で作ったNode.jsのサイト my-emdash-site に、
サンドボックス型プラグイン用のランナーを設定したいです。
公式ドキュメント「Configure the plugin sandbox」
（https://docs.emdashcms.com/deployment/plugin-sandbox/）の「Node.js」の手順に従ってください。

条件：
・公式ドキュメントに書かれているインストールコマンドを使う
・astro.config.mjs は、既存の database と storage の設定を残したまま、sandboxRunner だけを追加する
・変更する前に、変更前と変更後の差分を見せる

回答する前に、必ず公式ドキュメントの現在の内容を確認してください。
EmDash Docs MCP（https://docs.emdashcms.com/mcp）が使える場合は、それで確認してください。

AIが出す結果の例

公式ドキュメントに書かれているインストールコマンドと設定は次のとおりです。

npm install @emdash-cms/sandbox-workerd workerd

astro.config.mjs

import { sqlite } from "emdash/db";

emdash({
	database: sqlite({ url: "file:./data/emdash.db" }),
	sandboxRunner: "@emdash-cms/sandbox-workerd/sandbox",
});

公式の設定例はデータベースのパスが file:./data/emdash.db ですが、自分のサイトでは既存の database の設定を変えずに、sandboxRunner だけを追加します。

自分で確認すること

astro.config.mjs の emdash() の中に sandboxRunner: "@emdash-cms/sandbox-workerd/sandbox" がある
既存の database と storage の設定が消えていない

対応する公式ページ：プラグインサンドボックス（Node.js）

ステップ2：プラグインの雛形を作る

新しいプロジェクトを置くディレクトリで、プラグインの作成ツールを実行します。作成ツールは、公開者（publisher）、作者、セキュリティの連絡先、ソースリポジトリを質問し、プロジェクトの概要を表示してからファイルを作ります。

本サイトの補足 · AIへの依頼文

AIに聞いてみよう

目的：プラグインの作成ツールで、save-log の雛形を作る

依頼文

EmDashの公式ドキュメント「Your first sandboxed plugin」
（https://docs.emdashcms.com/plugins/creating-plugins/your-first-plugin/）の
「Scaffold the plugin」に沿って、save-log という名前のプラグインの雛形を作りたいです。

条件：
・my-emdash-site と同じ階層のディレクトリで実行する
・公式ドキュメントに書かれているコマンドをそのまま使う
・作成ツールが質問する項目（publisher、author、security contact、source repository）について、
　それぞれ何を入力するものかを先に説明する
・publisher には自分のAtmosphereアカウントのハンドルかDIDを使う

回答する前に、必ず公式ドキュメントの現在の内容を確認してください。
EmDash Docs MCP（https://docs.emdashcms.com/mcp）が使える場合は、それで確認してください。

AIが出す結果の例

公式ドキュメントに書かれているコマンドは次のとおりです。

pnpm dlx @emdash-cms/plugin-cli init save-log

cd save-log
pnpm install

作られるファイルの構成は次のとおりです。

save-log/
├── .agents/
│   └── skills -> ../skills
├── .claude/
│   ├── CLAUDE.md -> ../AGENTS.md
│   └── skills -> ../skills
├── AGENTS.md
├── emdash-plugin.jsonc
├── package.json
├── pnpm-workspace.yaml
├── README.md
├── skills/
│   └── creating-plugins/SKILL.md
├── src/
│   └── plugin.ts
├── tests/
│   └── plugin.test.ts
├── tsconfig.json
├── vitest.config.ts
└── .gitignore

自分で確認すること

save-log ディレクトリに emdash-plugin.jsonc と src/plugin.ts がある
pnpm install がエラーで終わっていない

対応する公式ページ：はじめてのサンドボックス型プラグイン（プラグインの雛形を作る）

ステップ3：マニフェストに権限とストレージを書く

emdash-plugin.jsonc は、プラグインの識別情報、レジストリ用の情報、信頼に関する約束事を持つマニフェストです。content:afterSave フックは保存されたコンテンツをプラグインに渡すため、権限（Capability）content:read を追加します。保存イベントを検索できる形で残すため、events というストレージのコレクションを宣言します。作成ツールが書き込んだ publisher、author、security の値は、そのまま残します。（公式「はじめてのサンドボックス型プラグイン」）

本サイトの補足 · AIへの依頼文

AIに聞いてみよう

目的：マニフェストに、フックが使う権限とストレージを追加する

依頼文

EmDashの公式ドキュメント「Your first sandboxed plugin」
（https://docs.emdashcms.com/plugins/creating-plugins/your-first-plugin/）の
「Define the plugin's access and storage」に沿って、save-log/emdash-plugin.jsonc を更新してください。

条件：
・capabilities に content:read を追加する（旧形式の read:content は使わない）
・storage に events コレクションを宣言し、indexes は ["savedAt"] にする
・作成ツールが書き込んだ publisher、author、security の値は変更しない
・変更する前に、変更前と変更後の差分を見せる
・content:read が必要な理由を1〜2文で説明する

回答する前に、必ず公式ドキュメントの現在の内容を確認してください。
EmDash Docs MCP（https://docs.emdashcms.com/mcp）が使える場合は、それで確認してください。

AIが出す結果の例

公式ドキュメントに書かれている、このチュートリアルで使う項目は次のとおりです。

	"capabilities": ["content:read"],
	"allowedHosts": [],
	"storage": {
		"events": { "indexes": ["savedAt"] },
	},

自分で確認すること

capabilities に content:read がある
storage に events がある
publisher が、自分のAtmosphereアカウントのハンドルかDIDになっている

対応する公式ページ：はじめてのサンドボックス型プラグイン（プラグインの権限とストレージを定義する）、マニフェスト

ステップ4：フックとルートを書く

生成された src/plugin.ts を、公式ドキュメントのコードに置き換えます。フックのハンドラーは (event, ctx)、ルートのハンドラーは (routeCtx, ctx) を受け取ります。health ルートは公開・読み取り専用のため、管理画面にログインしていなくても確認できます。公開ルートはインターネットから呼び出せるため、実際のデータや更新処理を公開する前に、公式「APIルート」の認証とブラウザのオリジンに関するルールを読みます。（公式「はじめてのサンドボックス型プラグイン」）

本サイトの補足 · AIへの依頼文

AIに聞いてみよう

目的：保存イベントを記録するフックと、動作確認用のルートを書く

依頼文

EmDashの公式ドキュメント「Your first sandboxed plugin」
（https://docs.emdashcms.com/plugins/creating-plugins/your-first-plugin/）の
「Add the hook and route」に沿って、save-log/src/plugin.ts を置き換えてください。

条件：
・公式ドキュメントに載っているコードをそのまま使い、独自に書き換えない
・書き換えたあと、コードの各部分（content:afterSave フック、ctx.storage.events.put、
　ctx.log.info、health ルート）が何をしているかを、1部分につき1〜2文で説明する

回答する前に、必ず公式ドキュメントの現在の内容を確認してください。
EmDash Docs MCP（https://docs.emdashcms.com/mcp）が使える場合は、それで確認してください。

AIが出す結果の例

公式ドキュメントに書かれているコードは次のとおりです。

src/plugin.ts

import type { SandboxedPlugin } from "emdash/plugin";

const plugin: SandboxedPlugin = {
	hooks: {
		"content:afterSave": {
			handler: async (event, ctx) => {
				const savedAt = new Date().toISOString();
				const contentId = String(event.content.id);
				await ctx.storage.events.put(`${savedAt}:${contentId}`, {
					savedAt,
					collection: event.collection,
					contentId,
				});

				ctx.log.info("Content save recorded", {
					collection: event.collection,
					contentId,
				});
			},
		},
	},

	routes: {
		health: {
			public: true,
			handler: async (_routeCtx, ctx) => {
				return { ok: true, plugin: ctx.plugin.id };
			},
		},
	},
};

export default plugin;

自分で確認すること

src/plugin.ts の内容が、公式ページのコードと一致している

対応する公式ページ：はじめてのサンドボックス型プラグイン（フックとルートを追加する）、APIルート

ステップ5：生成されたテストを書き換える

作成ツールが生成したテストは、元の hello ルートを呼び出します。これを health ルートのテストに置き換えます。

本サイトの補足 · AIへの依頼文

AIに聞いてみよう

目的：health ルートを確かめるテストに置き換える

依頼文

EmDashの公式ドキュメント「Your first sandboxed plugin」
（https://docs.emdashcms.com/plugins/creating-plugins/your-first-plugin/）の
「Update the generated test」に沿って、save-log/tests/plugin.test.ts を置き換えてください。

条件：
・公式ドキュメントに載っているコードをそのまま使い、独自に書き換えない
・このテストが何を確かめているかを2〜3文で説明する

回答する前に、必ず公式ドキュメントの現在の内容を確認してください。
EmDash Docs MCP（https://docs.emdashcms.com/mcp）が使える場合は、それで確認してください。

AIが出す結果の例

公式ドキュメントに書かれているテストは、health ルートを呼び出し、結果が { ok: true, plugin: "save-log" } になることを確かめます。テストはプラグインをビルドし、Worker Loaderと PluginBridge を通してルートを呼び出します。

自分で確認すること

tests/plugin.test.ts の内容が、公式ページのコードと一致している

対応する公式ページ：はじめてのサンドボックス型プラグイン（生成されたテストを更新する）、サンドボックス型プラグインのテスト

ステップ6：検証してビルドする

テストを実行し、マニフェストを検証して、npm用の成果物をビルドします。

本サイトの補足 · AIへの依頼文

AIに聞いてみよう

目的：プラグインのテスト、検証、ビルドを通す

依頼文

EmDashの公式ドキュメント「Your first sandboxed plugin」
（https://docs.emdashcms.com/plugins/creating-plugins/your-first-plugin/）の
「Validate and build」に沿って、save-log のディレクトリで検証とビルドをしてください。

条件：
・公式ドキュメントに書かれている4つのコマンドを、書かれている順に1つずつ実行する
・どれかが失敗したら、次のコマンドに進まずに止まり、表示されたメッセージをそのまま見せる
・ビルドで作られるファイルと、それぞれの役割を説明する

回答する前に、必ず公式ドキュメントの現在の内容を確認してください。
EmDash Docs MCP（https://docs.emdashcms.com/mcp）が使える場合は、それで確認してください。

AIが出す結果の例

公式ドキュメントに書かれているコマンドは次のとおりです。

pnpm run validate
pnpm run typecheck
pnpm run test
pnpm run build

ビルドで作られるファイルは次の3つです。

dist/plugin.mjs：フックとルートのコード
dist/manifest.json：実行時のマニフェストと、検出されたフック名・ルート名
dist/index.mjs：サイトが読み込む、デフォルトエクスポートの記述子

自分で確認すること

4つのコマンドがすべてエラーで終わっていない
dist/ に plugin.mjs、manifest.json、index.mjs の3つがある

対応する公式ページ：はじめてのサンドボックス型プラグイン（検証とビルド）

ステップ7：サイトにプラグインを登録する

ローカルのパッケージをEmDashのサイトにインストールし、astro.config.mjs の sandboxed に追加します。コマンドはサイトのディレクトリで実行します。

本サイトの補足 · AIへの依頼文

AIに聞いてみよう

目的：作ったプラグインを、ローカルのEmDashサイトに登録する

依頼文

EmDashの公式ドキュメント「Your first sandboxed plugin」
（https://docs.emdashcms.com/plugins/creating-plugins/your-first-plugin/）の
「Register the plugin」に沿って、save-log を my-emdash-site に登録してください。

条件：
・my-emdash-site と save-log は同じ階層にある
・astro.config.mjs は、既存の database、storage、sandboxRunner の設定を残したまま、
　save-log の import と sandboxed への追加だけをする
・変更する前に、変更前と変更後の差分を見せる

回答する前に、必ず公式ドキュメントの現在の内容を確認してください。
EmDash Docs MCP（https://docs.emdashcms.com/mcp）が使える場合は、それで確認してください。

AIが出す結果の例

公式ドキュメントに書かれているコマンドと設定は次のとおりです。

pnpm add file:../save-log

astro.config.mjs

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import saveLog from "save-log";

export default defineConfig({
	integrations: [
		emdash({
			sandboxed: [saveLog],
			sandboxRunner: "@emdash-cms/sandbox-workerd/sandbox",
		}),
	],
});

自分で確認すること

astro.config.mjs に import saveLog from "save-log"; がある
emdash() の中に sandboxed: [saveLog] と sandboxRunner の両方がある
既存の database と storage の設定が消えていない

対応する公式ページ：はじめてのサンドボックス型プラグイン（プラグインを登録する）

ステップ8：動かして確認する

2つの開発プロセスを起動します。

プラグインのディレクトリで pnpm dev を実行します。プラグインのソースやマニフェストが変わると、CLIがプラグインをビルドし直します。
サイトのディレクトリで、サイトの開発用コマンドを実行します。my-emdash-site の場合は npm run dev です。（公式「はじめてのEmDashサイト作成」）

本サイトの補足 · AIへの依頼文

AIに聞いてみよう

目的：プラグインのルートとフックが動いていることを確かめる

依頼文

EmDashの公式ドキュメント「Your first sandboxed plugin」
（https://docs.emdashcms.com/plugins/creating-plugins/your-first-plugin/）の
「Run the plugin」に沿って、save-log が動いているか確認したいです。

条件：
・ターミナルを2つ使う。1つは save-log で pnpm dev、もう1つは my-emdash-site で npm run dev
・health ルートのURLと、返ってくるはずの内容を教える
・フックが動いたことを確かめる方法を、公式ドキュメントの記述の範囲で教える

回答する前に、必ず公式ドキュメントの現在の内容を確認してください。
EmDash Docs MCP（https://docs.emdashcms.com/mcp）が使える場合は、それで確認してください。

AIが出す結果の例

公式ドキュメントに書かれている確認先のURLは次のとおりです。

http://localhost:4321/_emdash/api/plugins/save-log/health

このURLは、標準のAPIの形式で、プラグインが返した値を返します。

{
	"success": true,
	"data": { "ok": true, "plugin": "save-log" },
}

管理画面でエントリーを保存すると、サイトのログに Content save recorded が出力され、フックがプラグインの events コレクションに1件書き込みます。

自分で確認すること

health のURLを開くと、"ok": true と "plugin": "save-log" を含む応答が表示される
管理画面でエントリーを保存したあと、サイトを起動したターミナルに Content save recorded が表示される

対応する公式ページ：はじめてのサンドボックス型プラグイン（プラグインを動かす）

うまくいかないときの確認点

症状	確認すること	公式ページ
プラグインが読み込まれない	ランナーが使えないとき、EmDashは `sandboxed` のプラグインを読み込みません。ステップ1のランナーの設定を確認します	はじめてのサンドボックス型プラグイン、プラグインサンドボックス
`Plugin sandbox is configured but not available on this platform` と表示される	コロンのあとの文が原因を示します。Node.jsで `workerd is missing or its binary does not run on this platform` と表示された場合は、`./node_modules/.bin/workerd --version` を実行します。失敗する場合は、動かす環境で、オプションの依存パッケージを有効にしてインストールし直します	プラグインサンドボックス（トラブルシューティング）
`workerd failed to start within 10 seconds` と表示される	このメッセージより前の、`[emdash:workerd]` で始まる行に、`workerd` 自身の出力（設定や起動時のエラー）があります	プラグインサンドボックス（トラブルシューティング）
`workerd crashed 5 times in 60 seconds, giving up` と表示される	このメッセージより前の `[emdash:workerd] workerd exited with <reason>` の行が、終了した理由を示します。原因を直してからサーバーを再起動します	プラグインサンドボックス（トラブルシューティング）
`ctx.storage.events` でエラーになる	マニフェストに `events` のストレージコレクションが宣言されていないと、`ctx.storage.events` へのアクセスはエラーになります。ステップ3を確認します	はじめてのサンドボックス型プラグイン
`ctx.content` がない	`content:read` を宣言していないプラグインには、`ctx.content` が渡されません	権限（Capabilities）とセキュリティ

このほかの症状は「つまずきやすいポイント」にまとめています。

根拠にした公式ページ

はじめてのサンドボックス型プラグイン：https://docs.emdashcms.com/plugins/creating-plugins/your-first-plugin/
プラグイン形式の選び方：https://docs.emdashcms.com/plugins/creating-plugins/choosing-a-format/
プラグインサンドボックス：https://docs.emdashcms.com/deployment/plugin-sandbox/
権限（Capabilities）とセキュリティ：https://docs.emdashcms.com/plugins/creating-plugins/capabilities/
バンドルと公開：https://docs.emdashcms.com/plugins/creating-plugins/publishing/
はじめてのEmDashサイト作成：https://docs.emdashcms.com/getting-started/
AIツール向けDocs MCP：https://docs.emdashcms.com/docs-mcp/

完成するもの

所要時間

必要なもの

手順の全体像

依頼文の使い方

ステップ

ステップ1：サイトにサンドボックスランナーを設定する

ステップ2：プラグインの雛形を作る

ステップ3：マニフェストに権限とストレージを書く

ステップ4：フックとルートを書く

ステップ5：生成されたテストを書き換える

ステップ6：検証してビルドする

ステップ7：サイトにプラグインを登録する

ステップ8：動かして確認する

うまくいかないときの確認点

根拠にした公式ページ

次に読むページ