Descripción general del sistema de plugins

El sistema de plugins de EmDash te permite extender el CMS sin modificar el código principal. Los plugins pueden engancharse a eventos del ciclo de vida del contenido, almacenar sus propios datos, exponer configuraciones a los administradores y añadir interfaz de usuario personalizada al panel de administración.

Filosofía de diseño

Los plugins de EmDash vienen en dos sabores: sandboxed y nativos. Los plugins sandboxed se ejecutan en workers V8 aislados y pueden instalarse desde el mercado con un clic. Los plugins nativos se ejecutan en proceso y se configuran en código.

Prefiere plugins sandboxed. Pueden ser instalados, actualizados y eliminados desde la interfaz de administración sin tocar código o redesplegar. Usa plugins nativos solo cuando necesites características que requieran integración en tiempo de compilación (páginas admin de React, componentes de renderizado Portable Text o inyección de fragmentos de página).

Principios clave:

• Sandbox-first — Diseña para el sandbox; usa el modo nativo solo cuando lo necesites
• Declarativo — Los hooks, el almacenamiento y las rutas se declaran en el momento de la definición, no se registran dinámicamente
• Type-safe — Soporte completo de TypeScript con objetos de contexto tipados
• Basado en capacidades — Los plugins declaran lo que necesitan; el sandbox lo aplica

Lo que los plugins pueden hacer

Arquitectura de plugin

Cada plugin se crea con definePlugin():

import { definePlugin } from "emdash";

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

	// APIs a las que el plugin necesita acceder
	capabilities: ["read:content", "network:fetch"],

	// Hosts a los que el plugin puede hacer solicitudes HTTP
	allowedHosts: ["api.example.com"],

	// Colecciones de almacenamiento persistente
	storage: {
		entries: {
			indexes: ["userId", "createdAt"],
		},
	},

	// Manejadores de eventos
	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 }),
		},
	},

	// Configuración de interfaz admin
	admin: {
		settingsSchema: {
			apiKey: { type: "secret", label: "API Key" },
		},
		pages: [{ path: "/dashboard", label: "Dashboard" }],
		widgets: [{ id: "status", size: "half" }],
	},
});

Contexto del plugin

Cada hook y manejador de ruta recibe un objeto PluginContext con acceso a:

La forma del contexto es idéntica en todos los hooks y rutas. Las propiedades protegidas por capacidad solo están presentes cuando el plugin declara la capacidad requerida.

Capacidades

Las capacidades determinan qué APIs están disponibles en el contexto del plugin:

Registro

Registra plugins en tu configuración 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 })],
		}),
	],
});

Los plugins se resuelven en tiempo de compilación. El orden importa para hooks con la misma prioridad — los plugins anteriores en el array se ejecutan primero.

Modos de ejecución

EmDash soporta dos modos de ejecución de plugins:

En modo sandboxed, las capacidades se aplican a nivel de runtime — los plugins solo pueden acceder a lo que declaran. En modo nativo, las capacidades son consultivas y los plugins tienen acceso completo al proceso.

Próximos pasos