サンドボックスで動くプラグインを作る

分離した実行環境を用意し、記事保存のログと動作確認用のAPIを持つプラグインを登録します。

目次

サイト本体から分離して動かす

サンドボックス方式では、サイト本体と分離した環境でプラグインを動かし、許可された窓口を通してEmDashを操作します。ここでは記事保存のログと、動作確認用のhealthというAPIを作ります。APIは、プログラムから情報や操作を受け渡す入口です。

必要なのは、起動できるNode.js用EmDashサイト、Node.js 22.23.4以上、プラグイン用のpnpm、公開者(publisher)として指定するAtmosphereのアカウントです。pnpmはnpmと同じくパッケージを管理する道具で、このガイドでは公式の生成手順に合わせてプラグイン側だけで使います。既存サイトの管理方式を途中で入れ替える必要はありません。

対象はEmDash 1.4.0です。サイト側とプラグイン側で使う道具と作業フォルダーが変わるので、手順ごとに確認します。

1. サイトに実行環境を入れる

コマンドはVS Codeのターミナルで入力します。Windowsではコマンドプロンプトを選びます。入力画面の開き方

npmで管理しているweekend-noteフォルダーで実行します。

npm install @emdash-cms/sandbox-workerd workerd

サイトのastro.config.mjsにある既存のemdash({ ... })へ、次の項目を加えます。

sandboxRunner: "@emdash-cms/sandbox-workerd/sandbox",

既存のデータベースなどの設定は残します。これはNode.js用です。Cloudflare用サイトには同じ設定を貼らず、公開構成のrunnerを使ってください。

workerdは実行するOS向けの部品を含みます。別のOSで作ったnode_modulesをそのままコピーせず、実際に動かす環境で依存関係を入れます。

2. ひな形を作る

VS Codeで新しいコマンド入力画面を開き、現在地が weekend-note なら cd .. で一つ上の親フォルダーへ移動します。.. は親フォルダーを表します。

pnpm --version で番号が表示されることを確認してから、次を実行します。まだ使えない場合は、pnpmの公式導入案内(別タブで開く)で対応する導入方法を選び、準備してください。

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

publisher、作者、連絡先、ソースの保管先などを聞かれます。自分の実際の情報を設定し、生成された内容を確認します。例に書かれた第三者の識別子や連絡先を、自分の情報として使わないでください。

emdash-plugin.jsoncが登録情報、src/plugin.tsが処理です。生成されたpackage.jsonのパッケージ名も確認します。以下ではsave-logとして説明します。

3. 使う権限を宣言する

emdash-plugin.jsoncの既存の本人情報を残して、capabilitiesとallowedHostsを次の状態にします。これはファイル全体ではなく、変更する2項目です。

"capabilities": ["content:read"],
"allowedHosts": []

今回、外部サーバーへ通信する処理はありません。保存後の情報を受け取るためにcontent:readを使います。

4. ログと確認用APIを書く

src/plugin.tsの内容を次にします。

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

const plugin: SandboxedPlugin = {
  hooks: {
    "content:afterSave": async (event, ctx) => {
      ctx.log.info("記事の保存を検出しました", {
        collection: event.collection,
        contentId: String(event.content.id),
      });
    },
  },
  routes: {
    health: {
      public: true,
      handler: async (_routeCtx, ctx) => ({
        ok: true,
        plugin: ctx.plugin.id,
      }),
    },
  },
};

export default plugin;

public: trueなので、この確認用APIはログインせず呼べます。返す情報は動作状態とプラグインIDだけです。記事の下書きや設定値を返すAPIへ広げる場合は、認証・権限の設計が必要です。

5. テストを変更し、ビルドする

生成されたテストは元のhelloというAPIを呼ぶため、tests/plugin.test.tsを以下に変更します。

import { afterEach, expect, it } from "vitest";
import { createPluginTestHost, type PluginTestHost } from "@emdash-cms/plugin-test";

let host: PluginTestHost | undefined;
afterEach(async () => { await host?.dispose(); host = undefined; });

it("動作確認APIがプラグインを識別する", async () => {
  host = await createPluginTestHost();
  expect(await host.invokeRoute("health")).toEqual({ ok: true, plugin: "save-log" });
});

save-logフォルダーで、順番に実行します。

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

失敗したら、その段階の出力を確認します。distは生成物なので、内容を直すときは登録情報のファイルemdash-plugin.jsoncやsrc内のコードを編集し、再ビルドします。

6. サイトへ取り込む

サイト側へ移動して導入します。

VS Codeの File → Open Folder(ファイル → フォルダーを開く)で weekend-note を開き、新しいコマンド入力画面を用意します。Windowsではコマンドプロンプトを使います。

npm install ../save-log

../save-log は、サイトと同じ親フォルダーに置いたプラグインの場所です。このnpmへの指定は、MacとWindowsのコマンドプロンプトで同じ書き方を使います。

サイトのastro.config.mjsでimport saveLog from "save-log";を加え、既存のemdash({ ... })に次を追加します。

sandboxed: [saveLog],

すでに配列があれば追記します。先ほどのsandboxRunnerも必要です。サイトを再起動し、実際のローカルURLで/_emdash/api/plugins/save-log/healthを開きます。

応答にはsuccess: trueがあり、dataの中にok: trueとプラグインIDが入る想定です。次に管理画面で記事を保存し、サイト側のコマンド入力画面にログが出ることを確認します。

動かないときと、終わり方

SANDBOX_NOT_AVAILABLEなら、プラグインを分離して動かす部品(runner)の起動を確認します。APIは動くのに保存ログが出ない場合は、権限宣言とサイト側のログを確認します。コードを変更した場合はプラグインを再ビルドし、必要に応じてサイトへ取り込み直します。

開発サーバーを終了するときはControl + Cです。次は、フックの発火条件と設定や記録の保存を確認します。

公式の参照元

関連ガイド

メニュー
ホーム公式ドキュメント (別タブで開く)

キーワードを入力すると、ガイドの内容から探せます。