creating-plugins

Creating EmDash plugins

Build against the API that reaches the intended execution mode. Source types and production-boundary tests take precedence over examples in this skill when they disagree.

Choose a format

Format	Runtime source	Admin UI	Distribution
Sandboxed	src/plugin.ts default-exports a SandboxedPlugin	Block Kit pages, widgets, saved-entry panels, and actions	Plugin CLI and registry
Native	definePlugin() / createPlugin()	React, Block Kit, and Astro components	Trusted site dependency only

Use a sandboxed plugin unless the feature needs host-process access, React admin code, Astro rendering components, raw page fragments, or custom Portable Text block definitions. Native plugins run with the site's authority and cannot be installed from the registry.

Scaffold a sandboxed plugin

pnpm dlx @emdash-cms/plugin-cli init my-plugin
cd my-plugin
pnpm install
pnpm run test

The manifest is the identity and trust contract. Runtime hooks and routes live in src/plugin.ts; the CLI generates descriptors, manifests, and bundles. Do not create a separate descriptor factory or sandbox-entry.ts.

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

const plugin: SandboxedPlugin = {
	hooks: {
		"content:afterSave": async (event, ctx) => {
			ctx.log.info("Content saved", { id: event.content.id });
		},
	},
};

export default plugin;

Import authoring types from emdash/plugin with import type. Value imports are limited to lightweight helpers such as pluginRoute() and pluginResponse(), which the CLI bundles. Sandboxed runtime code can use Web APIs but not Node.js built-ins.

Declare access

Declare every host API in emdash-plugin.jsonc. Adding authority, exposing a route publicly, or adding MCP tools requires renewed administrator approval.