Vue d'ensemble du système de plugins

Le système de plugins EmDash vous permet d’étendre le CMS sans modifier le code principal. Les plugins peuvent se brancher sur des événements de cycle de vie du contenu, stocker leurs propres données, exposer des paramètres aux administrateurs et ajouter une interface utilisateur personnalisée au panneau d’administration.

Philosophie de conception

Les plugins EmDash se déclinent en deux versions : sandboxés et natifs. Les plugins sandboxés s’exécutent dans des workers V8 isolés et peuvent être installés depuis le marché en un clic. Les plugins natifs s’exécutent en processus et sont configurés dans le code.

Préférez les plugins sandboxés. Ils peuvent être installés, mis à jour et supprimés depuis l’interface admin sans toucher au code ou redéployer. N’utilisez les plugins natifs que lorsque vous avez besoin de fonctionnalités nécessitant une intégration au moment du build (pages admin React, composants de rendu Portable Text ou injection de fragments de page).

Principes clés :

• Sandbox d’abord — Concevez pour le sandbox ; utilisez le mode natif uniquement si nécessaire
• Déclaratif — Les hooks, le stockage et les routes sont déclarés au moment de la définition, pas enregistrés dynamiquement
• Type-safe — Support complet de TypeScript avec des objets de contexte typés
• Basé sur les capacités — Les plugins déclarent ce dont ils ont besoin ; le sandbox l’applique

Ce que les plugins peuvent faire

Architecture des plugins

Chaque plugin est créé avec definePlugin() :

import { definePlugin } from "emdash";

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

	// APIs dont le plugin a besoin
	capabilities: ["read:content", "network:fetch"],

	// Hôtes vers lesquels le plugin peut faire des requêtes HTTP
	allowedHosts: ["api.example.com"],

	// Collections de stockage persistant
	storage: {
		entries: {
			indexes: ["userId", "createdAt"],
		},
	},

	// Gestionnaires d'événements
	hooks: {
		"content:afterSave": async (event, ctx) => {
			ctx.log.info("Content saved", { id: event.content.id });
		},
	},

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

	// Configuration de l'interface admin
	admin: {
		settingsSchema: {
			apiKey: { type: "secret", label: "API Key" },
		},
		pages: [{ path: "/dashboard", label: "Dashboard" }],
		widgets: [{ id: "status", size: "half" }],
	},
});

Contexte du plugin

Chaque hook et gestionnaire de route reçoit un objet PluginContext avec accès à :

La forme du contexte est identique pour tous les hooks et routes. Les propriétés protégées par capacité ne sont présentes que lorsque le plugin déclare la capacité requise.

Capacités

Les capacités déterminent quelles API sont disponibles dans le contexte du plugin :

Enregistrement

Enregistrez les plugins dans votre configuration Astro :

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 })],
		}),
	],
});

Les plugins sont résolus au moment du build. L’ordre compte pour les hooks avec la même priorité — les plugins plus tôt dans le tableau s’exécutent en premier.

Modes d’exécution

EmDash prend en charge deux modes d’exécution de plugins :

En mode sandboxé, les capacités sont appliquées au niveau du runtime — les plugins ne peuvent accéder qu’à ce qu’ils déclarent. En mode natif, les capacités sont consultatives et les plugins ont un accès complet au processus.

Prochaines étapes