React-Admin-Seiten und Widgets

Native Plugins können das Admin-Panel mit benutzerdefinierten React-Seiten und Dashboard-Widgets erweitern — Sandbox-Plugins beschreiben ihre UI stattdessen als Block Kit, da das Laden von Plugin-JavaScript in den Admin die Sandbox-Isolation brechen würde.

Wenn Ihr Plugin nur ein Einstellungsformular benötigt, deckt das automatisch generierte admin.settingsSchema-Formular (siehe Ihr erstes natives Plugin) die meisten Fälle ab, ohne React zu schreiben. Verwenden Sie benutzerdefinierte Komponenten nur, wenn Sie eine reichhaltigere UI benötigen, als settingsSchema bietet.

Admin-Einstiegspunkt

Plugins mit Admin-UI exportieren pages- und widgets-Objekte aus einem admin-Einstiegspunkt:

import { SEOSettingsPage } from "./components/SEOSettingsPage";
import { SEODashboardWidget } from "./components/SEODashboardWidget";

export const widgets = {
	"seo-overview": SEODashboardWidget,
};

export const pages = {
	"/settings": SEOSettingsPage,
};

Konfigurieren Sie den Einstiegspunkt in package.json:

{
	"exports": {
		".": "./dist/index.js",
		"./admin": "./dist/admin.js"
	}
}

Referenzieren Sie ihn von definePlugin():

definePlugin({
	id: "seo",
	version: "1.0.0",

	admin: {
		entry: "@my-org/plugin-seo/admin",
		pages: [{ path: "/settings", label: "SEO Settings", icon: "settings" }],
		widgets: [{ id: "seo-overview", title: "SEO Overview", size: "half" }],
	},
});

Der Deskriptor benötigt einen passenden adminEntry, damit EmDash weiß, wo die Komponenten zur Build-Zeit zu finden sind:

adminEntry: "@my-org/plugin-seo/admin",

Admin-Seiten

Admin-Seiten sind React-Komponenten, die unter /_emdash/admin/plugins/<plugin-id>/<path> eingebunden werden.

Seitendefinition

Deklarieren Sie jede Seite unter admin.pages mit einem Pfad, Label und Icon:

admin: {
	pages: [
		{
			path: "/settings",
			label: "Settings",
			icon: "settings",
		},
		{
			path: "/reports",
			label: "Reports",
			icon: "chart",
		},
	],
}

Deklarieren Sie Labels auf Englisch. Der Admin führt sie durch seine gemeinsame Lingui-Instanz, bevor er die Seitenleiste und die Befehlspalette rendert, sodass ein Plugin, das seinen eigenen Nachrichtenkatalog lädt — mit dem englischen Label als Nachrichten-ID — lokalisierte Navigation kostenlos erhält. Labels, die einer der eigenen Nachrichten des Admins entsprechen (Settings, Dashboard, …), übernehmen die Übersetzungen des Admins auch ohne Plugin-Katalog; Labels ohne Katalogeintrag werden wie deklariert gerendert.

import { i18n } from "@lingui/core";

// Den kompilierten Katalog des Plugins in die i18n-Instanz des Admins zusammenführen.
// "Reports" wird jetzt als "Berichte" gerendert, wenn die Admin-Locale Deutsch ist.
const catalogs: Record<string, Record<string, string>> = {
	de: { Reports: "Berichte", Settings: "Einstellungen" },
};

function mergeCatalog() {
	const messages = catalogs[i18n.locale];
	if (messages && !("Reports" in i18n.messages)) i18n.load(i18n.locale, messages);
}

mergeCatalog();
// Der Locale-Umschalter des Admins *ersetzt* den Katalog bei Änderung, also erneut zusammenführen.
// Die Sentinel-Prüfung oben verhindert Rekursion (load() löst "change" aus).
i18n.on("change", mergeCatalog);

Seitenkomponente

Die folgende Komponente liest und speichert Einstellungen über den Plugin-API-Hook:

import { useState, useEffect } from "react";
import { usePluginAPI } from "@emdash-cms/admin";

export function SettingsPage() {
	const api = usePluginAPI();
	const [settings, setSettings] = useState<Record<string, unknown>>({});
	const [saving, setSaving] = useState(false);

	useEffect(() => {
		api.get("settings").then(setSettings);
	}, []);

	const handleSave = async () => {
		setSaving(true);
		await api.post("settings/save", settings);
		setSaving(false);
	};

	return (
		<div>
			<h1>Plugin-Einstellungen</h1>

			<label>
				Website-Titel
				<input
					type="text"
					value={(settings.siteTitle as string) || ""}
					onChange={(e) => setSettings({ ...settings, siteTitle: e.target.value })}
				/>
			</label>

			<button onClick={handleSave} disabled={saving}>
				{saving ? "Speichert..." : "Einstellungen speichern"}
			</button>
		</div>
	);
}

Plugin-API-Hook

usePluginAPI() ruft die Routen Ihres Plugins mit dem Plugin-ID-Präfix und dem automatisch hinzugefügten X-EmDash-Request: 1 CSRF-Header auf:

import { usePluginAPI } from "@emdash-cms/admin";

function MyComponent() {
	const api = usePluginAPI();

	const data = await api.get("status");                       // GET /_emdash/api/plugins/<id>/status
	await api.post("settings/save", { enabled: true });          // POST mit JSON-Body
	const result = await api.get("history?limit=50");            // Query-Parameter unterstützt
}

Dashboard-Widgets

Widgets erscheinen auf dem Admin-Dashboard und bieten Informationen auf einen Blick.

Deklarieren Sie jedes Widget unter admin.widgets mit einer ID, einem Titel und einer Größe:

admin: {
	widgets: [
		{
			id: "seo-overview",
			title: "SEO Overview",
			size: "half",   // "full" | "half" | "third"
		},
	],
}

Die folgende Komponente ruft ihre Daten beim Laden ab und rendert eine kompakte Zusammenfassung:

import { useState, useEffect } from "react";
import { usePluginAPI } from "@emdash-cms/admin";

export function SEOWidget() {
	const api = usePluginAPI();
	const [data, setData] = useState({ score: 0, issues: [] });

	useEffect(() => {
		api.get("analyze").then(setData);
	}, []);

	return (
		<div className="widget-content">
			<div className="score">{data.score}%</div>
			<ul>
				{data.issues.map((issue, i) => (
					<li key={i}>{(issue as { message: string }).message}</li>
				))}
			</ul>
		</div>
	);
}

Größe	Beschreibung
`full`	Volle Dashboard-Breite
`half`	Halbe Dashboard-Breite
`third`	Ein Drittel Dashboard-Breite

Widgets werden automatisch basierend auf der Bildschirmbreite umbrochen.

Export-Struktur

Der Admin-Einstiegspunkt exportiert zwei Objekte:

import { SettingsPage } from "./components/SettingsPage";
import { ReportsPage } from "./components/ReportsPage";
import { StatusWidget } from "./components/StatusWidget";
import { OverviewWidget } from "./components/OverviewWidget";

export const pages = {
	"/settings": SettingsPage,
	"/reports": ReportsPage,
};

export const widgets = {
	status: StatusWidget,
	overview: OverviewWidget,
};

Admin-Komponenten verwenden

EmDash bietet vorgefertigte Komponenten für gängige Muster:

import {
	Card,
	Button,
	Input,
	Select,
	Toggle,
	Table,
	Pagination,
	Alert,
	Loading,
} from "@emdash-cms/admin";

function SettingsPage() {
	return (
		<Card title="Einstellungen">
			<Input label="API-Schlüssel" type="password" />
			<Toggle label="Aktiviert" defaultChecked />
			<Button variant="primary">Speichern</Button>
		</Card>
	);
}

Automatisch generierte Einstellungs-UI

Wenn Ihr Plugin nur ein Einstellungsformular benötigt, verwenden Sie admin.settingsSchema ohne benutzerdefinierte Komponenten:

admin: {
	settingsSchema: {
		apiKey: { type: "secret", label: "API Key" },
		enabled: { type: "boolean", label: "Enabled", default: true },
	},
},

EmDash generiert automatisch eine Einstellungsseite. Verwenden Sie benutzerdefinierte React-Seiten nur, wenn Sie Verhalten benötigen, das über ein einfaches Formular hinausgeht.

Plugin-Seiten erscheinen in der Admin-Seitenleiste unter dem Namen des Plugins. Die Reihenfolge entspricht dem admin.pages-Array, wie unten gezeigt:

admin: {
	pages: [
		{ path: "/settings", label: "Settings", icon: "settings" },  // erste
		{ path: "/history", label: "History", icon: "history" },     // zweite
		{ path: "/reports", label: "Reports", icon: "chart" },        // dritte
	],
}

Build-Konfiguration

Admin-Komponenten benötigen einen separaten Build-Einstiegspunkt. Die folgende Bundler-Konfiguration baut sowohl den Server- als auch den Admin-Einstiegspunkt:

tsdown

export default {
	entry: {
		index: "src/index.ts",
		admin: "src/admin.tsx",
	},
	format: "esm",
	dts: true,
	external: ["react", "react-dom", "emdash", "@emdash-cms/admin"],
};

tsup

export default {
	entry: ["src/index.ts", "src/admin.tsx"],
	format: "esm",
	dts: true,
	external: ["react", "react-dom", "emdash", "@emdash-cms/admin"],
};

Halten Sie React und EmDash Admin als externe Abhängigkeiten, um Duplikate im Bundle zu vermeiden.

Plugin aktivieren/deaktivieren

Wenn ein Plugin im Admin deaktiviert wird:

Seitenleisten-Links werden ausgeblendet.
Dashboard-Widgets werden nicht gerendert.
Admin-Seiten geben 404 zurück.
Backend-Hooks werden weiterhin ausgeführt (zur Datensicherheit).

Plugins können ihren Aktivierungsstatus prüfen:

const enabled = await ctx.kv.get<boolean>("_emdash:enabled");

Vollständiges Beispiel

Das folgende Plugin definiert eine Dashboard-Seite, eine Einstellungsseite und ein Widget, mit Runtime- und Admin-Einstiegspunkten in separaten Dateien. Die src/index.ts-Datei enthält den Deskriptor und die Runtime:

import { definePlugin } from "emdash";
import type { PluginDescriptor } from "emdash";

export function analyticsPlugin(): PluginDescriptor {
	return {
		id: "analytics",
		version: "1.0.0",
		format: "native",
		entrypoint: "@my-org/plugin-analytics",
		adminEntry: "@my-org/plugin-analytics/admin",
		adminPages: [
			{ path: "/dashboard", label: "Dashboard", icon: "chart" },
			{ path: "/settings", label: "Settings", icon: "settings" },
		],
		adminWidgets: [{ id: "events-today", title: "Events Today", size: "third" }],
	};
}

export function createPlugin() {
	return definePlugin({
		id: "analytics",
		version: "1.0.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: true },
			},
			pages: [
				{ path: "/dashboard", label: "Dashboard", icon: "chart" },
				{ path: "/settings", label: "Settings", icon: "settings" },
			],
			widgets: [{ id: "events-today", title: "Events Today", size: "third" }],
		},

		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;

Die src/admin.tsx-Datei ordnet Seitenpfade und Widget-IDs ihren React-Komponenten zu:

import { EventsWidget } from "./components/EventsWidget";
import { DashboardPage } from "./components/DashboardPage";
import { SettingsPage } from "./components/SettingsPage";

export const widgets = {
	"events-today": EventsWidget,
};

export const pages = {
	"/dashboard": DashboardPage,
	"/settings": SettingsPage,
};