E EmDash CMS Everything Guides, use cases, plugins, templates
Deutsch

Plugins erstellen

Auf dieser Seite

Diese Anleitung führt durch den Aufbau eines vollständigen EmDash-Plugins. Sie lernen, wie Sie den Code strukturieren, Hooks und Storage definieren und Admin-UI-Komponenten exportieren.

Plugin-Struktur

Jedes Plugin hat zwei Teile, die in unterschiedlichen Kontexten laufen:

  1. Plugin-Deskriptor (PluginDescriptor) — wird von der Factory-Funktion zurückgegeben und sagt EmDash, wie das Plugin geladen wird. Läuft zur Build-Zeit in Vite (importiert in astro.config.mjs). Muss frei von Seiteneffekten sein und darf keine Runtime-APIs nutzen.
  2. Plugin-Definition (definePlugin()) — enthält die Runtime-Logik (Hooks, Routes, Storage). Läuft zur Request-Zeit auf dem deployten Server. Hat Zugriff auf den vollen Plugin-Kontext (ctx).

Diese müssen in getrennten Entrypoints liegen, weil sie in völlig unterschiedlichen Umgebungen ausgeführt werden:

my-plugin/
├── src/
│   ├── descriptor.ts     # Plugin descriptor (runs in Vite at build time)
│   ├── index.ts           # Plugin definition with definePlugin() (runs at deploy time)
│   ├── admin.tsx          # Admin UI exports (React components) — optional
│   └── astro/             # Optional: Astro components for site-side rendering
│       └── index.ts       # Must export `blockComponents`
├── package.json
└── tsconfig.json

Plugin anlegen

Deskriptor (Build-Zeit)

Der Deskriptor sagt EmDash, wo das Plugin liegt und welche Admin-UI es bereitstellt. Diese Datei wird in astro.config.mjs importiert und läuft in Vite.

import type { PluginDescriptor } from "emdash";

// Options your plugin accepts at registration time
export interface MyPluginOptions {
	enabled?: boolean;
	maxItems?: number;
}

export function myPlugin(options: MyPluginOptions = {}): PluginDescriptor {
	return {
		id: "my-plugin",
		version: "1.0.0",
		entrypoint: "@my-org/plugin-example",
		options,
		adminEntry: "@my-org/plugin-example/admin",
		componentsEntry: "@my-org/plugin-example/astro",
		adminPages: [{ path: "/settings", label: "Settings", icon: "settings" }],
		adminWidgets: [{ id: "status", title: "Status", size: "half" }],
	};
}

Definition (Runtime)

Die Definition enthält die Runtime-Logik — Hooks, Routes, Storage und Admin-Konfiguration. Diese Datei wird zur Request-Zeit auf dem deployten Server geladen.

import { definePlugin } from "emdash";
import type { MyPluginOptions } from "./descriptor.js";

export function createPlugin(options: MyPluginOptions = {}) {
	const maxItems = options.maxItems ?? 100;

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

		// Declare required capabilities
		capabilities: ["read:content"],

		// Plugin storage (document collections)
		storage: {
			items: {
				indexes: ["status", "createdAt", ["status", "createdAt"]],
			},
		},

		// Admin UI configuration
		admin: {
			entry: "@my-org/plugin-example/admin",
			settingsSchema: {
				maxItems: {
					type: "number",
					label: "Maximum Items",
					description: "Limit stored items",
					default: maxItems,
					min: 1,
					max: 1000,
				},
				enabled: {
					type: "boolean",
					label: "Enabled",
					default: options.enabled ?? true,
				},
			},
			pages: [{ path: "/settings", label: "Settings", icon: "settings" }],
			widgets: [{ id: "status", title: "Status", size: "half" }],
		},

		// Hook handlers
		hooks: {
			"plugin:install": async (_event, ctx) => {
				ctx.log.info("Plugin installed");
			},

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

				ctx.log.info("Content saved", {
					collection: event.collection,
					id: event.content.id,
				});
			},
		},

		// API routes (trusted only — not available in sandboxed plugins)
		routes: {
			status: {
				handler: async (ctx) => {
					const count = await ctx.storage.items!.count();
					return { count, maxItems };
				},
			},
		},
	});
}

export default createPlugin;

Regeln für die Plugin-ID

Das Feld id muss diesen Regeln folgen:

  • Nur Kleinbuchstaben, Ziffern und Bindestriche
  • Entweder einfach (my-plugin) oder scoped (@my-org/my-plugin)
  • Eindeutig unter allen installierten Plugins
// Valid IDs
"seo";
"audit-log";
"@emdash-cms/plugin-forms";

// Invalid IDs
"MyPlugin"; // No uppercase
"my_plugin"; // No underscores
"my.plugin"; // No dots

Versionsformat

Semantic Versioning verwenden:

version: "1.0.0"; // Valid
version: "1.2.3-beta"; // Valid (prerelease)
version: "1.0"; // Invalid (missing patch)

Package-Exports

Konfigurieren Sie package.json-exports, damit EmDash jeden Entrypoint laden kann. Deskriptor und Definition sind getrennte Exports, weil sie in unterschiedlichen Umgebungen laufen:

{
	"name": "@my-org/plugin-example",
	"version": "1.0.0",
	"type": "module",
	"exports": {
		".": {
			"types": "./dist/index.d.ts",
			"import": "./dist/index.js"
		},
		"./descriptor": {
			"types": "./dist/descriptor.d.ts",
			"import": "./dist/descriptor.js"
		},
		"./admin": {
			"types": "./dist/admin.d.ts",
			"import": "./dist/admin.js"
		},
		"./astro": {
			"types": "./dist/astro/index.d.ts",
			"import": "./dist/astro/index.js"
		}
	},
	"files": ["dist"],
	"peerDependencies": {
		"emdash": "^0.1.0",
		"react": "^18.0.0"
	}
}
ExportKontextZweck
"."Server (Runtime)createPlugin() / definePlugin() — wird zur Request-Zeit über entrypoint geladen
"./descriptor"Vite (Build-Zeit)PluginDescriptor-Factory — Import in astro.config.mjs
"./admin"BrowserReact-Komponenten für Admin-Seiten/Widgets
"./astro"Server (SSR)Astro-Komponenten für Site-seitiges Block-Rendering

Nur ./admin- und ./astro-Exports einbinden, wenn das Plugin sie nutzt.

Vollständiges Beispiel: Audit-Log-Plugin

Dieses Beispiel zeigt Storage, Lifecycle-Hooks, Content-Hooks und API-Routes:

import { definePlugin } from "emdash";

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

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: {
			"plugin:install": async (_event, ctx) => {
				ctx.log.info("Audit log plugin installed");
			},

			"content:afterSave": {
				priority: 200, // Run after other plugins
				timeout: 2000,
				handler: async (event, ctx) => {
					const { content, collection, isNew } = event;

					const entry: AuditEntry = {
						timestamp: new Date().toISOString(),
						action: isNew ? "create" : "update",
						collection,
						resourceId: content.id as string,
					};

					const entryId = `${Date.now()}-${content.id}`;
					await ctx.storage.entries!.put(entryId, entry);

					ctx.log.info(`Logged ${entry.action} on ${collection}/${content.id}`);
				},
			},

			"content:afterDelete": {
				priority: 200,
				timeout: 1000,
				handler: async (event, ctx) => {
					const { id, collection } = event;

					const entry: AuditEntry = {
						timestamp: new Date().toISOString(),
						action: "delete",
						collection,
						resourceId: id,
					};

					const entryId = `${Date.now()}-${id}`;
					await ctx.storage.entries!.put(entryId, entry);

					ctx.log.info(`Logged delete on ${collection}/${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),
						})),
					};
				},
			},

			history: {
				handler: async (ctx) => {
					const url = new URL(ctx.request.url);
					const limit = parseInt(url.searchParams.get("limit") || "50", 10);
					const cursor = url.searchParams.get("cursor") || undefined;

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

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

export default createPlugin;

Plugins testen

Testen Sie Plugins, indem Sie eine minimale Astro-Site mit registriertem Plugin anlegen:

  1. Test-Site mit installiertem EmDash erstellen.

  2. Plugin in astro.config.mjs registrieren:

    import myPlugin from "../path/to/my-plugin/src";

export default defineConfig({
	integrations: [
		emdash({
			plugins: [myPlugin()],
		}),
	],
});

  3. Dev-Server starten und Hooks durch Erstellen/Aktualisieren von Content auslösen.

  4. Konsole auf ctx.log-Ausgabe prüfen und Storage über API-Routes verifizieren.

Für Unit-Tests das Interface PluginContext mocken und Hook-Handler direkt aufrufen.

Portable-Text-Blocktypen

Plugins können dem Portable-Text-Editor eigene Blocktypen hinzufügen. Diese erscheinen im Slash-Menü des Editors und können in jedes portableText-Feld eingefügt werden.

Blocktypen deklarieren

In createPlugin() Blocks unter admin.portableTextBlocks deklarieren:

admin: {
	portableTextBlocks: [
		{
			type: "youtube",
			label: "YouTube Video",
			icon: "video",           // Named icon: video, code, link, link-external
			placeholder: "Paste YouTube URL...",
			fields: [                // Block Kit fields for the editing UI
				{ type: "text_input", action_id: "id", label: "YouTube URL" },
				{ type: "text_input", action_id: "title", label: "Title" },
				{ type: "text_input", action_id: "poster", label: "Poster Image URL" },
			],
		},
	],
}

Jeder Blocktyp definiert:

  • type — Blocktyp-Name (in Portable Text _type)
  • label — Anzeigename im Slash-Menü
  • icon — Icon-Key (video, code, link, link-external). Fallback: generischer Würfel.
  • placeholder — Platzhaltertext der Eingabe
  • fields — Block-Kit-Formularfelder für die Bearbeitung. Wenn weggelassen, wird eine einfache URL-Eingabe angezeigt.

Rendering auf der Site

Um Blocktypen auf der Site zu rendern, exportieren Sie Astro-Komponenten aus einem componentsEntry:

import YouTube from "./YouTube.astro";
import CodePen from "./CodePen.astro";

// This export name is required — the virtual module imports it
export const blockComponents = {
	youtube: YouTube,
	codepen: CodePen,
};

Setzen Sie componentsEntry im Plugin-Deskriptor:

export function myPlugin(options = {}): PluginDescriptor {
	return {
		id: "my-plugin",
		entrypoint: "@my-org/my-plugin",
		componentsEntry: "@my-org/my-plugin/astro",
		// ...
	};
}

Plugin-Block-Komponenten werden automatisch in <PortableText> gemerged — Site-Autoren müssen nichts importieren. Vom Nutzer bereitgestellte Komponenten haben Vorrang vor Plugin-Defaults.

Package-Exports

Fügen Sie den Export ./astro in package.json hinzu:

{
	"exports": {
		".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
		"./admin": { "types": "./dist/admin.d.ts", "import": "./dist/admin.js" },
		"./astro": { "types": "./dist/astro/index.d.ts", "import": "./dist/astro/index.js" }
	}
}

Nächste Schritte