您的第一个原生插件 | EmDash CMS Everything

本指南将引导您从头开始构建原生插件。原生插件与您的 Astro 站点在同一进程中运行,可完全访问运行时,包括 React 管理页面、Portable Text 组件和页面片段。

如果您还没有决定是使用原生插件还是沙盒插件,请先阅读选择插件格式。原生格式适用于需要 React 管理页面、Portable Text 渲染组件或页面片段的插件。

一个或两个文件中的两个部分

与沙盒插件类似,原生插件包含两个部分:

描述符工厂 — 返回带有 format: "native" 和管理相关入口点的 PluginDescriptor。在构建时由 astro.config.mjs 导入。
createPlugin(options) 函数 — 运行时部分。返回 definePlugin({ id, version, capabilities, hooks, routes, admin }) 结果。

与沙盒插件不同,这两个部分可以位于同一个文件中,因为它们不在不同的环境中运行 — 整个插件都在进程内运行。包的 "." 导出指向一个同时导出描述符工厂和 createPlugin(或 default)函数的文件:

my-native-plugin/
├── src/
│   ├── index.ts          # Descriptor factory + createPlugin
│   ├── admin.tsx         # React admin components (optional)
│   └── astro/            # Astro components for PT block rendering (optional)
│       └── index.ts
├── package.json
└── tsconfig.json

设置包

以下 package.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 保持为对等依赖,以便宿主站点提供实际版本,避免您发送重复的包。

编写描述符和运行时

以下 src/index.ts 在一个文件中定义了描述符工厂和 createPlugin 运行时:

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: "Tracking ID" },
				enabled: { type: "boolean", label: "Enabled", default: options.enabled ?? true },
			},
			pages: [{ path: "/dashboard", label: "Dashboard", icon: "chart" }],
			widgets: [{ id: "events-today", title: "Events Today", size: "third" }],
		},

		hooks: {
			"plugin:install": async (_event, ctx) => {
				ctx.log.info("Analytics plugin installed", { 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 出现两次。 一次在描述符上,一次在 definePlugin() 上。它们应该匹配。描述符的副本是 astro.config.mjs 在构建时看到的;definePlugin() 的副本是在请求时运行的。
原生路由处理程序接受单个参数 — (ctx: RouteContext),其中 ctx.input、ctx.request 和 ctx.requestMeta 与常规 PluginContext 属性合并。这与标准格式的双参数形式相反。完整表面请参见 API 路由(其他所有内容都相同)。

插件 ID 规则

id 字段必须匹配 /^[a-z][a-z0-9_-]*$/ — 以小写字母开头,然后是字母、数字、连字符或下划线。ID 在插件路由 URL 中用作单个路径段,并作为插件存储索引生成的 SQL 标识符的一部分,因此该模式之外的任何内容在运行时都会失败。以下值显示了哪些 ID 是可接受的:

// Valid
"seo";
"audit-log";
"audit_log";
"plugin-forms";

// Invalid
"@my-org/plugin-forms";  // scoped form not allowed at runtime
"MyPlugin";              // no uppercase
"42-plugin";             // can't start with a digit
"my.plugin";             // no dots

将无作用域的 id 与 entrypoint 中的有作用域的 npm 包名配对 — 包名和插件 ID 是独立的关注点。

版本格式

使用语义版本控制。以下值显示了哪些版本字符串是可接受的:

version: "1.0.0";       // valid
version: "1.2.3-beta";  // valid (prerelease)
version: "1.0";         // invalid (missing patch)

注册插件

在您站点的 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 Key" },
		enabled: { type: "boolean", label: "Enabled", default: true },
		maxItems: { type: "number", label: "Max items", 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: "Retention (days)",
					description: "Days to keep entries. 0 = forever.",
					default: 90,
					min: 0,
					max: 365,
				},
			},
			pages: [{ path: "/history", label: "Audit History", icon: "history" }],
			widgets: [{ id: "recent-activity", title: "Recent Activity", 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 站点来测试原生插件:

创建一个安装了 EmDash 的测试站点。
在 astro.config.mjs 中注册您的插件,直接从您的本地源路径导入。
运行开发服务器并通过创建、更新或删除内容来触发钩子。
检查控制台的 ctx.log 输出并通过 API 路由验证存储。

对于单元测试,模拟 PluginContext 接口并直接调用钩子处理程序。

下一步

React 管理页面和小部件 — 为管理面板发送自定义 React UI。
Portable Text 渲染组件 — 提供渲染插件定义的块类型的 Astro 组件。
页面片段 — 将脚本、样式表或 HTML 注入公共页面。
分发原生插件 — npm 打包和版本控制。