Plugin-System Übersicht

Das Plugin-System von EmDash ermöglicht es Ihnen, das CMS zu erweitern, ohne den Kerncode zu ändern. Plugins können sich in Content-Lifecycle-Events einhaken, eigene Daten speichern, Einstellungen für Administratoren bereitstellen und benutzerdefinierte UI zum Admin-Panel hinzufügen.

Designphilosophie

EmDash-Plugins gibt es in zwei Varianten: sandboxed und nativ. Sandboxed Plugins laufen in isolierten V8-Workern und können mit einem Klick vom Marketplace installiert werden. Native Plugins laufen im Prozess und werden im Code konfiguriert.

Bevorzugen Sie sandboxed Plugins. Sie können über die Admin-UI installiert, aktualisiert und entfernt werden, ohne Code anzufassen oder neu zu deployen. Verwenden Sie native Plugins nur, wenn Sie Funktionen benötigen, die Build-Zeit-Integration erfordern (React-Admin-Seiten, Portable Text-Rendering-Komponenten oder Page-Fragment-Injection).

Kernprinzipien:

• Sandbox-First — Entwerfen Sie für die Sandbox; verwenden Sie den nativen Modus nur bei Bedarf
• Deklarativ — Hooks, Speicher und Routen werden zur Definitionszeit deklariert, nicht dynamisch registriert
• Typsicher — Vollständige TypeScript-Unterstützung mit typisierten Kontextobjekten
• Capability-basiert — Plugins deklarieren, was sie benötigen; die Sandbox setzt es durch

Was Plugins tun können

Plugin-Architektur

Jedes Plugin wird mit definePlugin() erstellt:

import { definePlugin } from "emdash";

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

	// APIs, auf die das Plugin zugreifen muss
	capabilities: ["read:content", "network:fetch"],

	// Hosts, an die das Plugin HTTP-Anfragen stellen kann
	allowedHosts: ["api.example.com"],

	// Persistente Speichersammlungen
	storage: {
		entries: {
			indexes: ["userId", "createdAt"],
		},
	},

	// Event-Handler
	hooks: {
		"content:afterSave": async (event, ctx) => {
			ctx.log.info("Content saved", { id: event.content.id });
		},
	},

	// REST-API-Endpoints
	routes: {
		status: {
			handler: async (ctx) => ({ ok: true }),
		},
	},

	// Admin-UI-Konfiguration
	admin: {
		settingsSchema: {
			apiKey: { type: "secret", label: "API Key" },
		},
		pages: [{ path: "/dashboard", label: "Dashboard" }],
		widgets: [{ id: "status", size: "half" }],
	},
});

Plugin-Kontext

Jeder Hook und Route-Handler erhält ein PluginContext-Objekt mit Zugriff auf:

Die Kontextform ist bei allen Hooks und Routen identisch. Capability-geschützte Eigenschaften sind nur vorhanden, wenn das Plugin die erforderliche Capability deklariert.

Capabilities

Capabilities bestimmen, welche APIs im Plugin-Kontext verfügbar sind:

Registrierung

Registrieren Sie Plugins in Ihrer Astro-Konfiguration:

import { defineConfig } from "astro/config";
import { emdash } from "emdash/astro";
import seoPlugin from "@emdash-cms/plugin-seo";
import auditLogPlugin from "@emdash-cms/plugin-audit-log";

export default defineConfig({
	integrations: [
		emdash({
			plugins: [seoPlugin({ generateSitemap: true }), auditLogPlugin({ retentionDays: 90 })],
		}),
	],
});

Plugins werden zur Build-Zeit aufgelöst. Die Reihenfolge ist wichtig für Hooks mit gleicher Priorität — frühere Plugins im Array laufen zuerst.

Ausführungsmodi

EmDash unterstützt zwei Plugin-Ausführungsmodi:

Im Sandbox-Modus werden Capabilities auf Runtime-Ebene durchgesetzt — Plugins können nur auf das zugreifen, was sie deklarieren. Im nativen Modus sind Capabilities beratend und Plugins haben vollen Prozesszugriff.

Nächste Schritte