Hooks

Les hooks permettent aux plugins d’exécuter du code en réponse à des événements. Tous les hooks reçoivent un objet d’événement et le contexte du plugin, et ils sont déclarés au moment de la définition du plugin — il n’y a pas d’enregistrement dynamique à l’exécution.

Cette page couvre les plugins sandbox. Les hooks fonctionnent de manière identique dans les plugins natifs ; les plugins natifs peuvent en outre enregistrer page:fragments.

Signature du hook

Chaque gestionnaire de hook prend deux arguments :

async (event, ctx) => ReturnType;

• event — données sur ce qui vient de se produire (contenu en cours d’enregistrement, médias téléchargés, transition de cycle de vie, etc.)
• ctx — le PluginContext avec stockage, KV, journalisation et APIs contrôlées par capacités

satisfies SandboxedPlugin sur l’export par défaut infère event à partir du nom du hook (le type d’événement canonique complet) et ctx en tant que PluginContext, de sorte que les gestionnaires n’ont pas besoin d’annotations de paramètres. Pour référencer un type d’événement par nom dans un helper, importez-le depuis emdash/plugin.

Configuration des hooks

Un hook peut être déclaré comme un gestionnaire simple ou enveloppé dans un objet de configuration :

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

hooks: {
	"content:afterSave": {
		priority: 100,
		timeout: 5000,
		dependencies: ["audit-log"],
		errorPolicy: "continue",
		handler: async (event, ctx) => {
			ctx.log.info("Content saved");
		},
	},
},

Options de configuration

Hooks de cycle de vie

S’exécutent pendant l’installation, l’activation, la désactivation et la suppression du plugin.

plugin:install

S’exécute une fois lorsque le plugin est ajouté pour la première fois à un site.

"plugin:install": async (_event, ctx) => {
	ctx.log.info("Installing plugin...");
	await ctx.kv.set("settings:enabled", true);
	await ctx.storage.items.put("default", { name: "Default Item" });
},

Événement : {} — Retourne : Promise<void>

plugin:activate

S’exécute lorsque le plugin est activé (après l’installation ou lors de la réactivation).

"plugin:activate": async (_event, ctx) => {
	ctx.log.info("Plugin activated");
},

Événement : {} — Retourne : Promise<void>

plugin:deactivate

S’exécute lorsque le plugin est désactivé (mais pas supprimé).

"plugin:deactivate": async (_event, ctx) => {
	ctx.log.info("Plugin deactivated");
},

Événement : {} — Retourne : Promise<void>

plugin:uninstall

S’exécute lorsque le plugin est supprimé d’un site.

"plugin:uninstall": async (event, ctx) => {
	ctx.log.info("Uninstalling plugin...");
	if (event.deleteData) {
		const result = await ctx.storage.items.query({ limit: 1000 });
		await ctx.storage.items.deleteMany(result.items.map((i) => i.id));
	}
},

Événement : { deleteData: boolean } — Retourne : Promise<void>

Hooks de contenu

S’exécutent lors des opérations de création, de mise à jour et de suppression sur le contenu du site.

content:beforeSave

S’exécute avant l’enregistrement du contenu. Retournez le contenu modifié ou void pour le laisser inchangé. Levez une exception pour annuler.

"content:beforeSave": async (event, ctx) => {
	const { content, collection } = event;

	if (collection === "posts" && !content.title) {
		throw new Error("Posts require a title");
	}

	if (typeof content.slug === "string") {
		content.slug = content.slug.toLowerCase().replace(/\s+/g, "-");
	}

	return content;
},

Événement : { content, collection, isNew } — Retourne : contenu modifié ou void.

content:afterSave

S’exécute après l’enregistrement réussi du contenu. Utilisez pour les effets secondaires comme les notifications, la journalisation ou les synchronisations externes.

"content:afterSave": async (event, ctx) => {
	ctx.log.info(`${event.isNew ? "Created" : "Updated"} ${event.collection}/${event.content.id}`);

	if (ctx.http) {
		await ctx.http.fetch("https://api.example.com/webhook", {
			method: "POST",
			body: JSON.stringify({ event: "content:save", id: event.content.id }),
		});
	}
},

Événement : { content, collection, isNew } — Retourne : Promise<void>

content:beforeDelete

S’exécute avant la suppression du contenu. Retournez false pour annuler ; true ou void l’autorise.

"content:beforeDelete": async (event, ctx) => {
	if (event.collection === "pages" && event.id === "home") {
		ctx.log.warn("Cannot delete home page");
		return false;
	}
	return true;
},

Événement : { id, collection } — Retourne : boolean | void

content:afterDelete

S’exécute après la suppression réussie du contenu.

"content:afterDelete": async (event, ctx) => {
	await ctx.storage.cache.delete(`${event.collection}:${event.id}`);
},

Événement : { id, collection } — Retourne : Promise<void>

content:afterPublish

S’exécute après la promotion du contenu de brouillon à publié. Nécessite la capacité content:read.

Événement : { content, collection } — Retourne : Promise<void>

content:afterUnpublish

S’exécute après le retour du contenu de publié à brouillon. Nécessite la capacité content:read.

Événement : { content, collection } — Retourne : Promise<void>

Hooks de médias

media:beforeUpload

S’exécute avant le téléchargement d’un fichier. Retournez les métadonnées du fichier modifiées ou levez une exception pour annuler.

"media:beforeUpload": async (event, ctx) => {
	if (!event.file.type.startsWith("image/")) {
		throw new Error("Only images are allowed");
	}
	if (event.file.size > 10 * 1024 * 1024) {
		throw new Error("File too large");
	}
	return { ...event.file, name: `${Date.now()}-${event.file.name}` };
},

Événement : { file: { name, type, size } } — Retourne : fichier modifié ou void

media:afterUpload

S’exécute après le téléchargement réussi d’un fichier.

Événement : { media: { id, filename, mimeType, size, url, createdAt } } — Retourne : Promise<void>

Hooks de pages publiques

Ceux-ci permettent aux plugins de contribuer aux pages publiques rendues. Les templates optent en incluant les composants <EmDashHead>, <EmDashBodyStart> et <EmDashBodyEnd> depuis emdash/ui.

page:metadata

Contribue des métadonnées typées à <head> — balises meta, propriétés OpenGraph, rels <link> autorisés et JSON-LD. Disponible pour les plugins sandbox et natifs. Core valide, déduplique et rend les contributions ; les plugins retournent des données structurées, jamais du HTML brut.

"page:metadata": async (event, ctx) => {
	if (event.page.kind !== "content") return null;

	return {
		kind: "jsonld",
		id: `schema:${event.page.content?.collection}:${event.page.content?.id}`,
		graph: {
			"@context": "https://schema.org",
			"@type": "BlogPosting",
			headline: event.page.pageTitle ?? event.page.title,
			description: event.page.description,
		},
	};
},

Événement :

{
	page: {
		url: string;
		path: string;
		locale: string | null;
		kind: "content" | "custom";
		pageType: string;
		title: string | null;
		pageTitle?: string | null;
		description: string | null;
		canonical: string | null;
		image: string | null;
		content?: { collection: string; id: string; slug: string | null };
	}
}

Retourne : PageMetadataContribution | PageMetadataContribution[] | null

Types de contribution :

La première contribution gagne pour toute clé de déduplication. Le rel de link est restreint à une liste d’autorisation verrouillée par sécurité (canonical, alternate, author, license, nlweb, site.standard.document) ; href doit être HTTP ou HTTPS.

page:fragments

Contribue du HTML brut, des scripts ou des feuilles de style aux points d’insertion de page. Plugins natifs uniquement.

Les plugins sandbox ne peuvent pas utiliser ce hook car sa sortie s’exécute en tant que code first-party dans le navigateur du visiteur, en dehors de toute limite de sandbox. Pour les contributions de page sécurisées par sandbox, utilisez page:metadata. Voir Plugins natifs : fragments de page si vous avez besoin de cette surface.

Ordre d’exécution des hooks

Les hooks s’exécutent dans cet ordre :

1. Les hooks avec des valeurs de priority plus basses s’exécutent en premier.
2. Pour des priorités égales, les hooks s’exécutent dans l’ordre d’enregistrement du plugin.
3. Les hooks avec dependencies attendent que ces plugins se terminent.

// Plugin A
"content:afterSave": { priority: 50, handler: async () => {} }

// Plugin B
"content:afterSave": { priority: 100, handler: async () => {} }

// Plugin C
"content:afterSave": {
	priority: 200,
	dependencies: ["plugin-a"],   // waits for A even if its priority would normally be later
	handler: async () => {},
}

Gestion des erreurs

Lorsqu’un hook lève une exception ou expire :

• errorPolicy: "abort" — tout le pipeline s’arrête et l’opération d’origine peut échouer.
• errorPolicy: "continue" — l’erreur est journalisée et les hooks restants continuent de s’exécuter.

"content:afterSave": {
	timeout: 5000,
	errorPolicy: "continue",
	handler: async (event, ctx) => {
		await ctx.http!.fetch("https://unreliable-api.com/notify");
	},
},

Timeouts

Les hooks ont par défaut 5000ms. Augmentez le timeout pour les travaux plus lents :

"content:afterSave": {
	timeout: 30000,
	handler: async (event, ctx) => {
		// Long-running operation
	},
},

Référence des hooks

Voir la Référence des Hooks pour les types d’événements complets et les signatures des gestionnaires.