Hooks

Hooks permitem que plugins executem código em resposta a eventos. Todos os hooks recebem um objeto de evento e o contexto do plugin, e são declarados no momento da definição do plugin — não há registro dinâmico em tempo de execução.

Esta página cobre plugins sandboxed (formato padrão). Hooks funcionam de forma idêntica em plugins nativos; a única diferença é que plugins nativos também podem registrar page:fragments, o que plugins sandboxed não podem.

Assinatura do Hook

Cada manipulador de hook recebe dois argumentos:

async (event: EventType, ctx: PluginContext) => ReturnType;

• event — dados sobre o que acabou de acontecer (conteúdo sendo salvo, mídia carregada, transição de ciclo de vida, etc.)
• ctx — o PluginContext com armazenamento, KV, logging e APIs controladas por capacidades

Configuração de Hooks

Um hook pode ser declarado como um manipulador simples ou envolvido em um objeto de configuração:

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

Opções de configuração

Hooks de ciclo de vida

Executam durante a instalação, ativação, desativação e remoção do plugin.

plugin:install

Executa uma vez quando o plugin é adicionado pela primeira vez a um 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" });
},

Event: {} — Returns: Promise<void>

plugin:activate

Executa quando o plugin é habilitado (após a instalação ou quando reabilitado).

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

Event: {} — Returns: Promise<void>

plugin:deactivate

Executa quando o plugin é desabilitado (mas não removido).

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

Event: {} — Returns: Promise<void>

plugin:uninstall

Executa quando o plugin é removido de um 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));
	}
},

Event: { deleteData: boolean } — Returns: Promise<void>

Hooks de conteúdo

Executam durante operações de criação, atualização e exclusão do conteúdo do site.

content:beforeSave

Executa antes de o conteúdo ser salvo. Retorne conteúdo modificado ou void para deixá-lo inalterado. Lance um erro para cancelar.

"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;
},

Event: { content, collection, isNew } — Returns: conteúdo modificado ou void.

content:afterSave

Executa após o conteúdo ser salvo com sucesso. Use para efeitos colaterais como notificações, logging ou sincronizações externas.

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

Event: { content, collection, isNew } — Returns: Promise<void>

content:beforeDelete

Executa antes de o conteúdo ser excluído. Retorne false para cancelar; true ou void permite.

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

Event: { id, collection } — Returns: boolean | void

content:afterDelete

Executa após o conteúdo ser excluído com sucesso.

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

Event: { id, collection } — Returns: Promise<void>

content:afterPublish

Executa após o conteúdo ser promovido de rascunho para publicado. Requer a capacidade content:read.

Event: { content, collection } — Returns: Promise<void>

content:afterUnpublish

Executa após o conteúdo ser revertido de publicado para rascunho. Requer a capacidade content:read.

Event: { content, collection } — Returns: Promise<void>

Hooks de mídia

media:beforeUpload

Executa antes de um arquivo ser carregado. Retorne metadados de arquivo modificados ou lance um erro para cancelar.

"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}` };
},

Event: { file: { name, type, size } } — Returns: arquivo modificado ou void

media:afterUpload

Executa após um arquivo ser carregado com sucesso.

Event: { media: { id, filename, mimeType, size, url, createdAt } } — Returns: Promise<void>

Hooks de página pública

Estes permitem que plugins contribuam para páginas públicas renderizadas. Templates devem aderir incluindo os componentes <EmDashHead>, <EmDashBodyStart> e <EmDashBodyEnd> de emdash/ui.

page:metadata

Contribui metadados tipados para <head> — tags meta, propriedades OpenGraph, <link> rels permitidos e JSON-LD. Disponível tanto para plugins sandboxed quanto nativos. O núcleo valida, deduplica e renderiza as contribuições; plugins retornam dados estruturados, nunca HTML bruto.

"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,
		},
	};
},

Event:

{
	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 };
	}
}

Returns: PageMetadataContribution | PageMetadataContribution[] | null

Tipos de contribuição:

A primeira contribuição ganha para qualquer chave de deduplicação. Link rel é restrito a uma lista de permitidos bloqueada por segurança (canonical, alternate, author, license, nlweb, site.standard.document); href deve ser HTTP ou HTTPS.

page:fragments

Contribui HTML bruto, scripts ou folhas de estilo para pontos de inserção de página. Apenas plugins nativos.

Plugins sandboxed não podem usar este hook porque sua saída executa como código de primeira parte no navegador do visitante, fora de qualquer limite de sandbox. Para contribuições de página seguras para sandbox, use page:metadata. Veja Plugins nativos: fragmentos de página se precisar dessa superfície.

Ordem de execução dos hooks

Hooks executam nesta ordem:

1. Hooks com valores de priority mais baixos executam primeiro.
2. Para prioridades iguais, hooks executam na ordem de registro do plugin.
3. Hooks com dependencies aguardam que esses plugins sejam concluídos.

// 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 () => {},
}

Tratamento de erros

Quando um hook lança um erro ou atinge o timeout:

• errorPolicy: "abort" — todo o pipeline para e a operação original pode falhar.
• errorPolicy: "continue" — o erro é registrado e os hooks restantes ainda executam.

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

Timeouts

Hooks têm padrão de 5000ms. Aumente o timeout para trabalhos mais lentos:

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

Referência de hooks

Veja a Referência de Hooks para tipos de eventos completos e assinaturas de manipuladores.