Creating EmDash Plugins

EmDash plugins extend the CMS with hooks, storage, settings, admin UI, API routes, and custom Portable Text block types. All plugins are TypeScript packages.

Plugin Types

EmDash has two plugin formats:

definePlugin({ hooks, routes })

createPlugin()

definePlugin()

id

version

Standard is the default. Most plugins should use it. Standard plugins can be published to the marketplace and work in both trusted and sandboxed modes.

Native is an escape hatch for plugins that need React admin components, direct DB access, or custom Astro components. Native plugins can only run in

plugins: []

Plugin Anatomy

Every plugin has two parts that run in different contexts:

1. Plugin descriptor (

   PluginDescriptor

   ) — returned by the factory function in

   index.ts

   . Declares metadata (id, version, capabilities, storage). Runs at build time in Vite (imported in

   astro.config.mjs

   ). Must be side-effect-free.
2. Plugin definition (

   definePlugin()

   ) — contains the runtime logic (hooks, routes). Runs at request time on the deployed server. Has access to the full plugin context (

   ctx

   ). Lives in a separate file (typically

   sandbox-entry.ts

   ).

These must be in separate entrypoints because they execute in completely different environments:

my-plugin/
├── src/
│   ├── index.ts            # Descriptor factory (runs in Vite at build time)
│   ├── sandbox-entry.ts    # Plugin definition with definePlugin() (runs at deploy time)
│   ├── admin.tsx            # Admin UI exports (React) — optional, native only
│   └── astro/               # Site-side rendering components — optional, native only
│       └── index.ts         # Must export `blockComponents`
├── package.json
└── tsconfig.json

Minimal Plugin (Standard Format)

The simplest possible plugin -- just hooks:

// src/index.ts — descriptor factory, runs in Vite at build time
import type { PluginDescriptor } from "emdash";

export function myPlugin(): PluginDescriptor {
	return {
		id: "my-plugin",
		version: "1.0.0",
		format: "standard",
		entrypoint: "@my-org/my-plugin/sandbox",
		options: {},
	};
}

// src/sandbox-entry.ts — plugin definition, runs at request time
import { definePlugin } from "emdash";
import type { PluginContext } from "emdash";

export default definePlugin({
	hooks: {
		"content:afterSave": {
			handler: async (event: any, ctx: PluginContext) => {
				ctx.log.info(`Saved ${event.collection}/${event.content.id}`);
			},
		},
	},
});

The descriptor is what gets imported in

astro.config.mjs

entrypoint

definePlugin()

./sandbox

package.json

Key differences from native format:

• No

  id

  ,

  version

  , or

  capabilities

  in

  definePlugin()

  -- those live in the descriptor

• definePlugin()

  is an identity function providing type inference
• Hook handlers use

  (event, ctx)

  two-arg pattern
• Route handlers use

  (routeCtx, ctx)

  two-arg pattern
• Exported as

  default

  (not a factory function)

Plugin ID Rules

• Lowercase alphanumeric + hyphens only
• Simple (

  my-plugin

  ) or scoped (

  @my-org/my-plugin

  )
• Unique across all installed plugins

Registration

The descriptor is imported in

astro.config.mjs

import { myPlugin } from "@my-org/my-plugin";

export default defineConfig({
	integrations: [
		emdash({
			plugins: [myPlugin()], // runs in-process
			// OR
			sandboxed: [myPlugin()], // runs in isolate on Cloudflare
		}),
	],
});

Standard plugins work in either array. Native plugins only work in

plugins: []

Trusted vs Sandboxed Plugins

EmDash has two execution modes. Plugin code is identical in both — only the enforcement changes.

astro.config.mjs

ctx.http

allowedHosts

Trusted Mode

Trusted plugins are npm packages or local files added in

astro.config.mjs

• Capabilities are documentation only. Declaring

  ["read:content"]

  documents intent but isn't enforced — the plugin has full process access.
• Only install from sources you trust. A malicious trusted plugin has the same access as your application code.

Sandboxed Mode

Sandboxed plugins run in isolated V8 isolates on Cloudflare Workers via Dynamic Worker Loader. Each plugin gets its own isolate.

• Capabilities are enforced. If a plugin declares

  ["read:content"]

  , it can only call

  ctx.content.get()

  and

  ctx.content.list()

  . Attempting

  ctx.content.create()

  throws a permission error.
• Network is blocked by default. Direct

  fetch()

  calls fail. Plugins must use

  ctx.http.fetch()

  , which validates against

  allowedHosts

  .
• Storage is scoped. A plugin can only access its own KV and storage collections.
• Admin UI uses Block Kit. Sandboxed plugins describe their UI as JSON blocks -- no plugin JavaScript runs in the browser. See Block Kit reference.
• No Portable Text block types. PT blocks require Astro components for site-side rendering (

  componentsEntry

  ), which are loaded at build time from npm. Sandboxed plugins are installed at runtime and can't ship components. PT blocks are a native-plugin-only feature.
• Routes work. Standard plugin routes are available in both trusted and sandboxed modes via the sandbox runner's

  invokeRoute()

  RPC.

Sandboxing is not available on Node.js. All plugins run in trusted mode on non-Cloudflare platforms.

Developing for Both Modes

Write the same code. Develop locally in trusted mode (faster iteration, easier debugging). Deploy to sandboxed mode in production without code changes. With the standard format, the same entrypoint serves both modes -- no separate sandbox entry needed.

// src/sandbox-entry.ts -- works in both trusted and sandboxed modes
import { definePlugin } from "emdash";
import type { PluginContext } from "emdash";

export default definePlugin({
	hooks: {
		"content:afterSave": {
			handler: async (event: any, ctx: PluginContext) => {
				// Trusted: ctx.http present because descriptor declares network:fetch
				// Sandboxed: ctx.http present and enforced via RPC bridge
				if (!ctx.http) return;
				await ctx.http.fetch("https://api.analytics.example.com/track", {
					method: "POST",
					body: JSON.stringify({ contentId: event.content.id }),
				});
			},
		},
	},
});

Key constraint for sandbox compatibility: no Node.js built-ins (

fs

path

child_process

Capabilities

Capabilities control what APIs are available on

ctx

ctx

read:content

ctx.content.get()

ctx.content.list()

content

write:content

ctx.content.create()

ctx.content.update()

ctx.content.delete()

content

read:media

ctx.media.get()

ctx.media.list()

media

write:media

ctx.media.getUploadUrl()

ctx.media.delete()

media

network:fetch

ctx.http.fetch()

allowedHosts

http

read:users

ctx.users.get()

ctx.users.list()

ctx.users.getByEmail()

users

email:send

ctx.email.send()

email

email:provide

email:deliver

email:intercept

email:beforeSend

email:afterSend

Storage (

ctx.storage

ctx.kv

Email capabilities are distinct:

• email:send

  — for plugins that consume email (call

  ctx.email.send()

  )

• email:provide

  — for plugins that deliver email (implement the transport, e.g. Resend, SMTP)

• email:intercept

  — for plugins that observe or transform email (middleware hooks)

// In the descriptor (index.ts)
export function myPlugin(): PluginDescriptor {
	return {
		id: "my-plugin",
		version: "1.0.0",
		format: "standard",
		entrypoint: "@my-org/my-plugin/sandbox",
		options: {},
		capabilities: ["read:content", "network:fetch"],
		allowedHosts: ["api.example.com", "*.googleapis.com"], // Wildcards supported
	};
}

When a marketplace plugin is installed, the admin sees a capability consent dialog listing what the plugin can access. Users must approve before installation.

Publishing to the Marketplace

Standard plugins can be published to the EmDash Marketplace for one-click installation:

emdash plugin bundle --dir packages/plugins/my-plugin  # creates .tar.gz
emdash plugin login                                      # authenticate via GitHub
emdash plugin publish --tarball dist/my-plugin-1.0.0.tar.gz

See Publishing Reference for bundle format, validation, and security audit details.

Package Exports

Configure

package.json

{
	"name": "@my-org/my-plugin",
	"type": "module",
	"exports": {
		".": "./src/index.ts",
		"./sandbox": "./src/sandbox-entry.ts",
		"./admin": "./src/admin.tsx"
	},
	"peerDependencies": {
		"emdash": "^0.1.0"
	}
}

"."

astro.config.mjs

"./sandbox"

definePlugin({ hooks, routes })

entrypoint

"./admin"

"./astro"

The

"."

"./sandbox"

entrypoint

"./sandbox"

./admin

./astro

Plugin Features

Each feature is optional. Add only what your plugin needs:

definePlugin({ hooks })

storage

ctx.kv

definePlugin({ routes })

/_emdash/api/plugins/<id>/<route>

admin

admin

admin.entry

admin.portableTextBlocks

componentsEntry

See the reference files for detailed syntax:

• Hooks Reference — All hook types, signatures, configuration
• Storage & Settings — Collections, KV, settings schema
• Admin UI — Pages, widgets, entry point structure
• API Routes — Route handlers, validation, context
• Block Kit — Declarative UI for sandboxed plugins (similar to Slack Block Kit but not identical)
• Portable Text Blocks — Custom block types + frontend rendering
• Publishing — Bundle format, validation, marketplace publishing

Complete Example: Standard Plugin with Hooks, Routes, and Storage

// src/index.ts — descriptor factory, runs in Vite at build time
import type { PluginDescriptor } from "emdash";

export function submissionsPlugin(): PluginDescriptor {
	return {
		id: "submissions",
		version: "1.0.0",
		format: "standard",
		entrypoint: "@my-org/plugin-submissions/sandbox",
		options: {},
		capabilities: ["read:content"],
		storage: {
			submissions: {
				indexes: ["formId", "status", "createdAt"],
			},
		},
		adminPages: [{ path: "/submissions", label: "Submissions", icon: "list" }],
		adminWidgets: [{ id: "recent-submissions", title: "Recent Submissions", size: "half" }],
	};
}

// src/sandbox-entry.ts — plugin definition, runs at request time
import { definePlugin } from "emdash";
import type { PluginContext } from "emdash";

export default definePlugin({
	hooks: {
		"plugin:install": {
			handler: async (_event: any, ctx: PluginContext) => {
				ctx.log.info("Submissions plugin installed");
				await ctx.kv.set("settings:maxSubmissions", 1000);
			},
		},
	},

	routes: {
		submit: {
			public: true, // No auth required
			handler: async (routeCtx: any, ctx: PluginContext) => {
				const { formId, ...data } = routeCtx.input as Record<string, unknown>;

				const count = await ctx.storage.submissions.count({ formId });
				const max = (await ctx.kv.get<number>("settings:maxSubmissions")) ?? 1000;

				if (count >= max) {
					return { success: false, error: "Submission limit reached" };
				}

				const id = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
				await ctx.storage.submissions.put(id, {
					formId,
					data,
					status: "pending",
					createdAt: new Date().toISOString(),
				});

				return { success: true, id };
			},
		},

		list: {
			handler: async (routeCtx: any, ctx: PluginContext) => {
				const url = new URL(routeCtx.request.url);
				const limit = Math.max(
					1,
					Math.min(parseInt(url.searchParams.get("limit") || "50", 10) || 50, 100),
				);
				const cursor = url.searchParams.get("cursor") || undefined;

				const result = await ctx.storage.submissions.query({
					orderBy: { createdAt: "desc" },
					limit,
					cursor,
				});

				return {
					items: result.items.map((item: any) => ({ id: item.id, ...item.data })),
					cursor: result.cursor,
					hasMore: result.hasMore,
				};
			},
		},

		// Block Kit admin handler for pages and widgets
		admin: {
			handler: async (routeCtx: any, ctx: PluginContext) => {
				const interaction = routeCtx.input as { type: string; page?: string };

				if (interaction.type === "page_load" && interaction.page === "/submissions") {
					const result = await ctx.storage.submissions.query({
						orderBy: { createdAt: "desc" },
						limit: 50,
					});
					return {
						blocks: [
							{ type: "header", text: "Submissions" },
							{
								type: "table",
								blockId: "submissions-table",
								columns: [
									{ key: "formId", label: "Form", format: "text" },
									{ key: "status", label: "Status", format: "badge" },
									{ key: "createdAt", label: "Date", format: "relative_time" },
								],
								rows: result.items.map((item: any) => item.data),
							},
						],
					};
				}

				return { blocks: [] };
			},
		},
	},
});

Plugin Context

All hooks and routes receive

ctx

interface PluginContext {
	plugin: { id: string; version: string };
	storage: Record<string, StorageCollection>; // Declared collections
	kv: KVAccess; // Key-value store
	log: LogAccess; // Structured logger
	content?: ContentAccess; // If "read:content" capability
	media?: MediaAccess; // If "read:media" capability
	http?: HttpAccess; // If "network:fetch" capability
	users?: UserAccess; // If "read:users" capability
	cron?: CronAccess; // Always available — scoped to plugin
	email?: EmailAccess; // If "email:send" capability AND a provider is configured
}

Capabilities are declared in the descriptor (not in

definePlugin()

// In the descriptor
export function myPlugin(): PluginDescriptor {
	return {
		id: "my-plugin",
		version: "1.0.0",
		format: "standard",
		entrypoint: "@my-org/my-plugin/sandbox",
		options: {},
		capabilities: ["read:content", "network:fetch"],
		allowedHosts: ["api.example.com"],
		storage: { events: { indexes: ["timestamp"] } },
	};
}

Output Checklist

When creating a standard-format plugin, provide:

1. src/index.ts

   -- Descriptor factory (runs in Vite at build time)

2. src/sandbox-entry.ts

   --

   definePlugin({ hooks, routes })

   as default export (runs at request time)

3. package.json

   -- With exports

   "."

   (descriptor) and

   "./sandbox"

   (implementation)

4. tsconfig.json

   -- Standard TypeScript config

For native-format plugins (React admin, PT blocks, Astro components), also provide:

5. src/admin.tsx

   -- Admin entry point with React components

6. src/astro/index.ts

   -- Block components export (if PT blocks)