E EmDash CMS Everything Guides, use cases, plugins, templates
日本語

最初のネイティブプラグイン

このページ

このガイドでは、ネイティブプラグインをゼロから構築する方法を説明します。ネイティブプラグインは Astro サイトと同じプロセスで実行されます——サンドボックスの境界がなく、ランタイムへの完全なアクセス、およびサンドボックスが提供できない機能（React 管理ページ、Portable Text コンポーネント、ページフラグメント）へのアクセスが可能です。

ネイティブプラグインとサンドボックスプラグインのどちらを使用するかまだ決めていない場合は、まずプラグイン形式の選択をお読みください。ネイティブパスは、サンドボックスでは本当に実現できないことがある場合に適しています。

2つの部分、1つまたは2つのファイルに

サンドボックスプラグインと同様に、ネイティブプラグインは2つの部分で構成されます：

  1. ディスクリプタファクトリ — format: "native" と管理関連のエントリーポイントを含む PluginDescriptor を返します。ビルド時に astro.config.mjs によってインポートされます。
  2. createPlugin(options) 関数 — ランタイム側。definePlugin({ id, version, capabilities, hooks, routes, admin }) の結果を返します。

サンドボックスプラグインとは異なり、両方の部分は同じファイルに存在できます。これは、異なる環境で実行されないためです——プラグイン全体がプロセス内で実行されます。パッケージの "." エクスポートは、ディスクリプタファクトリと createPlugin（または default）関数の両方をエクスポートするファイルを指します：

my-native-plugin/
├── src/
│   ├── index.ts          # ディスクリプタファクトリ + createPlugin
│   ├── admin.tsx         # React 管理コンポーネント（オプション）
│   └── astro/            # PT ブロックレンダリング用の Astro コンポーネント（オプション）
│       └── index.ts
├── package.json
└── tsconfig.json

パッケージのセットアップ

{
	"name": "@my-org/plugin-analytics",
	"version": "0.1.0",
	"type": "module",
	"main": "dist/index.js",
	"exports": {
		".": {
			"types": "./dist/index.d.ts",
			"import": "./dist/index.js"
		},
		"./admin": {
			"types": "./dist/admin.d.ts",
			"import": "./dist/admin.js"
		}
	},
	"files": ["dist"],
	"peerDependencies": {
		"emdash": "*",
		"react": "^18.0.0"
	}
}

emdash と react を peerDependencies として保持し、ホストサイトが実際のバージョンを提供し、重複を避けるようにします。

ディスクリプタとランタイムの記述

import { definePlugin } from "emdash";
import type { PluginDescriptor } from "emdash";

export interface AnalyticsOptions {
	enabled?: boolean;
	maxEvents?: number;
}

export function analyticsPlugin(options: AnalyticsOptions = {}): PluginDescriptor {
	return {
		id: "analytics",
		version: "0.1.0",
		format: "native",
		entrypoint: "@my-org/plugin-analytics",
		options,
		adminEntry: "@my-org/plugin-analytics/admin",
		adminPages: [{ path: "/dashboard", label: "Dashboard", icon: "chart" }],
		adminWidgets: [{ id: "events-today", title: "Events Today", size: "third" }],
	};
}

export function createPlugin(options: AnalyticsOptions = {}) {
	const maxEvents = options.maxEvents ?? 100;

	return definePlugin({
		id: "analytics",
		version: "0.1.0",

		capabilities: ["network:request"],
		allowedHosts: ["api.analytics.example.com"],

		storage: {
			events: { indexes: ["type", "createdAt"] },
		},

		admin: {
			entry: "@my-org/plugin-analytics/admin",
			settingsSchema: {
				trackingId: { type: "string", label: "トラッキング ID" },
				enabled: { type: "boolean", label: "有効", default: options.enabled ?? true },
			},
			pages: [{ path: "/dashboard", label: "ダッシュボード", icon: "chart" }],
			widgets: [{ id: "events-today", title: "今日のイベント", size: "third" }],
		},

		hooks: {
			"plugin:install": async (_event, ctx) => {
				ctx.log.info("分析プラグインがインストールされました", { maxEvents });
			},

			"content:afterSave": async (event, ctx) => {
				const enabled = await ctx.kv.get<boolean>("settings:enabled");
				if (enabled === false) return;

				await ctx.storage.events.put(`evt_${Date.now()}`, {
					type: "content:save",
					contentId: event.content.id,
					createdAt: new Date().toISOString(),
				});
			},
		},

		routes: {
			stats: {
				handler: async (ctx) => {
					const today = new Date().toISOString().split("T")[0];
					const count = await ctx.storage.events.count({
						createdAt: { gte: today },
					});
					return { today: count };
				},
			},
		},
	});
}

export default createPlugin;

知っておくべきいくつかの詳細：

  • format: "native" は必須です。 デフォルトも "native" になりますが、すべてのディスクリプタで明示的に指定すると、作業している形式を簡単に特定できます。
  • entrypoint はパッケージのメインエクスポートです。 EmDash はランタイムでそれをインポートし、デフォルトエクスポートを呼び出して解決されたプラグインを構築します。
  • options はディスクリプタから createPlugin に流れます。 ユーザーがプラグインを登録する際に渡すもの（analyticsPlugin({ enabled: false })）は、ディスクリプタに保持され、createPlugin に転送されます。サンドボックスプラグインにはこのサーフェスがありません——代わりに KV から設定を読み取ります。
  • id、version、capabilities は2回出現します。 一度はディスクリプタに、もう一度は definePlugin() に。これらは一致する必要があります。ディスクリプタのコピーは、ビルド時に astro.config.mjs が参照するもので、definePlugin() のコピーはリクエスト時に実行されるものです。
  • ネイティブルートハンドラは単一の引数を取ります — (ctx: RouteContext)。ここで、ctx.input、ctx.request、ctx.requestMeta は通常の PluginContext プロパティとマージされます。これは標準形式の2引数形式とは逆です。完全なサーフェスについては、API ルートを参照してください（その他はすべて同じです）。

プラグイン id ルール

id フィールドは /^[a-z][a-z0-9_-]*$/ に一致する必要があります——小文字で始まり、その後に文字、数字、ハイフン、またはアンダースコアが続きます。id はプラグインルート URL の単一パスセグメントとして使用され、プラグインストレージインデックス用に生成される SQL 識別子の一部として使用されるため、そのパターンの外側のものはランタイムで失敗します。

// 有効
"seo";
"audit-log";
"audit_log";
"plugin-forms";

// 無効
"@my-org/plugin-forms";  // ランタイムでスコープ形式は許可されません
"MyPlugin";              // 大文字は不可
"42-plugin";             // 数字で始めることはできません
"my.plugin";             // ドットは不可

スコープなしの id を entrypoint のスコープ付き npm パッケージ名とペアにします——パッケージ名とプラグイン id は別の概念です。

バージョン形式

セマンティックバージョニングを使用します：

version: "1.0.0";       // 有効
version: "1.2.3-beta";  // 有効（プレリリース）
version: "1.0";         // 無効（パッチが欠落）

プラグインの登録

サイトの astro.config.mjs で、ディスクリプタファクトリをインポートし、それを plugins: [] 配列に渡します——ネイティブプラグインは常にプロセス内で実行され、sandboxed: [] では実行されません：

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { analyticsPlugin } from "@my-org/plugin-analytics";

export default defineConfig({
	integrations: [
		emdash({
			plugins: [
				analyticsPlugin({ enabled: true, maxEvents: 500 }),
			],
		}),
	],
});

設定 UI

ネイティブプラグインは admin.settingsSchema を使用して自動生成された設定フォームを利用でき、これが最も簡単な方法です：

admin: {
	settingsSchema: {
		apiKey: { type: "secret", label: "API キー" },
		enabled: { type: "boolean", label: "有効", default: true },
		maxItems: { type: "number", label: "最大アイテム数", min: 1, max: 1000, default: 100 },
	},
},

フィールドタイプ：string、number、boolean、select、secret、url、email。それぞれが label、description、default、および min/max/options などのタイプ固有の追加機能を受け入れます。設定は、サンドボックスプラグインが使用するのと同じプラグインごとの KV ストアに永続化されます——どこからでも ctx.kv.get<T>("settings:<key>") で読み取ります。

settingsSchema が提供するよりも豊富な設定 UI が必要な場合は、カスタム React ページを提供してください——React 管理ページとウィジェットを参照してください。

完全な例：監査ログプラグイン

import { definePlugin } from "emdash";
import type { PluginDescriptor } from "emdash";

interface AuditEntry {
	timestamp: string;
	action: "create" | "update" | "delete";
	collection: string;
	resourceId: string;
	userId?: string;
}

export function auditLogPlugin(): PluginDescriptor {
	return {
		id: "audit-log",
		version: "0.1.0",
		format: "native",
		entrypoint: "@emdash-cms/plugin-audit-log",
	};
}

export function createPlugin() {
	return definePlugin({
		id: "audit-log",
		version: "0.1.0",

		storage: {
			entries: {
				indexes: [
					"timestamp",
					"action",
					"collection",
					["collection", "timestamp"],
					["action", "timestamp"],
				],
			},
		},

		admin: {
			settingsSchema: {
				retentionDays: {
					type: "number",
					label: "保持期間（日数）",
					description: "エントリを保持する日数。0 = 永久。",
					default: 90,
					min: 0,
					max: 365,
				},
			},
			pages: [{ path: "/history", label: "監査履歴", icon: "history" }],
			widgets: [{ id: "recent-activity", title: "最近のアクティビティ", size: "half" }],
		},

		hooks: {
			"content:afterSave": {
				priority: 200,
				handler: async (event, ctx) => {
					const entry: AuditEntry = {
						timestamp: new Date().toISOString(),
						action: event.isNew ? "create" : "update",
						collection: event.collection,
						resourceId: event.content.id as string,
					};
					await ctx.storage.entries.put(`${Date.now()}-${event.content.id}`, entry);
				},
			},

			"content:afterDelete": {
				priority: 200,
				handler: async (event, ctx) => {
					await ctx.storage.entries.put(`${Date.now()}-${event.id}`, {
						timestamp: new Date().toISOString(),
						action: "delete",
						collection: event.collection,
						resourceId: event.id,
					});
				},
			},
		},

		routes: {
			recent: {
				handler: async (ctx) => {
					const result = await ctx.storage.entries.query({
						orderBy: { timestamp: "desc" },
						limit: 10,
					});
					return {
						entries: result.items.map((item) => ({
							id: item.id,
							...(item.data as AuditEntry),
						})),
					};
				},
			},
		},
	});
}

export default createPlugin;

テスト

プラグインが登録された最小限の Astro サイトを作成して、ネイティブプラグインをテストします：

  1. EmDash がインストールされたテストサイトを作成します。
  2. astro.config.mjs でプラグインを登録し、ローカルのソースパスから直接インポートします。
  3. 開発サーバーを実行し、コンテンツの作成、更新、または削除によってフックをトリガーします。
  4. コンソールで ctx.log 出力を確認し、API ルートを介してストレージを検証します。

ユニットテストの場合は、PluginContext インターフェースをモックし、フックハンドラを直接呼び出します。

次のステップ