プラグインシステム概要

EmDash のプラグインシステムを使用すると、コアコードを変更することなく CMS を拡張できます。プラグインは、コンテンツライフサイクルイベントにフックし、独自のデータを保存し、管理者に設定を公開し、管理パネルにカスタム UI を追加できます。

設計哲学

EmDash プラグインには、サンドボックス化とネイティブの 2 つのタイプがあります。サンドボックス化されたプラグインは分離された V8 ワーカーで実行され、マーケットプレイスからワンクリックでインストールできます。ネイティブプラグインはインプロセスで実行され、コードで設定されます。

サンドボックス化されたプラグインを優先してください。 管理 UI からコードに触れることなく、または再デプロイすることなくインストール、更新、削除できます。ビルド時統合が必要な機能（React 管理ページ、Portable Text レンダリングコンポーネント、またはページフラグメント注入）が必要な場合にのみ、ネイティブプラグインを使用してください。

主要な原則：

• サンドボックス優先 — サンドボックス用に設計し、必要な場合にのみネイティブモードを使用
• 宣言的 — フック、ストレージ、およびルートは定義時に宣言され、動的に登録されない
• 型安全 — 型付きコンテキストオブジェクトを使用した完全な TypeScript サポート
• 能力ベース — プラグインは必要なものを宣言し、サンドボックスがそれを強制する

プラグインができること

プラグインアーキテクチャ

すべてのプラグインは definePlugin() で作成されます：

import { definePlugin } from "emdash";

export default definePlugin({
	id: "my-plugin",
	version: "1.0.0",

	// プラグインがアクセスする必要がある API
	capabilities: ["read:content", "network:fetch"],

	// プラグインが HTTP リクエストを行うことができるホスト
	allowedHosts: ["api.example.com"],

	// 永続ストレージコレクション
	storage: {
		entries: {
			indexes: ["userId", "createdAt"],
		},
	},

	// イベントハンドラー
	hooks: {
		"content:afterSave": async (event, ctx) => {
			ctx.log.info("Content saved", { id: event.content.id });
		},
	},

	// REST API エンドポイント
	routes: {
		status: {
			handler: async (ctx) => ({ ok: true }),
		},
	},

	// 管理 UI 設定
	admin: {
		settingsSchema: {
			apiKey: { type: "secret", label: "API Key" },
		},
		pages: [{ path: "/dashboard", label: "Dashboard" }],
		widgets: [{ id: "status", size: "half" }],
	},
});

プラグインコンテキスト

すべてのフックとルートハンドラーは、アクセスできる PluginContext オブジェクトを受け取ります：

コンテキストの形状は、すべてのフックとルートで同じです。能力でゲートされたプロパティは、プラグインが必要な能力を宣言した場合にのみ存在します。

能力

能力は、プラグインコンテキストで使用可能な API を決定します：

登録

Astro 設定でプラグインを登録します：

import { defineConfig } from "astro/config";
import { emdash } from "emdash/astro";
import seoPlugin from "@emdash-cms/plugin-seo";
import auditLogPlugin from "@emdash-cms/plugin-audit-log";

export default defineConfig({
	integrations: [
		emdash({
			plugins: [seoPlugin({ generateSitemap: true }), auditLogPlugin({ retentionDays: 90 })],
		}),
	],
});

プラグインはビルド時に解決されます。同じ優先度のフックの場合、順序が重要です — 配列内の早いプラグインが最初に実行されます。

実行モード

EmDash は 2 つのプラグイン実行モードをサポートしています：

サンドボックスモードでは、能力はランタイムレベルで強制されます — プラグインは宣言したもののみにアクセスできます。ネイティブモードでは、能力はアドバイザリであり、プラグインは完全なプロセスアクセス権を持ちます。

次のステップ