Hooks

Hooks let plugins run code in response to events. All hooks receive an event object and the plugin context, and they’re declared at plugin definition time — there’s no dynamic registration at runtime.

This page covers sandboxed plugins. Native plugins use the same hook names and event types, but they use the in-process hook pipeline and can additionally register page:fragments. Sandboxed save rejection and isolated-runner failure behavior are described below.

Hook signature

Every hook handler takes two arguments:

async (event, ctx) => ReturnType;

event — data about what just happened (content being saved, media uploaded, lifecycle transition, etc.)
ctx — the PluginContext with storage, KV, logging, and capability-gated APIs

Assigning the definition to a SandboxedPlugin-typed constant infers event from the hook name (the full canonical event type) and ctx as PluginContext, so handlers need no parameter annotations. Export that constant as default. To reference an event type by name in a helper, import it from emdash/plugin.

Hook configuration

A hook can be declared as a bare handler or wrapped in a config object. Prefer the bare form unless the plugin also supports deliberate in-process execution and needs the metadata described below.

Simple
Full config

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

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

Configuration options

Option	Type	Default	Description
`priority`	`number`	`100`	Execution order. Lower numbers run first.
`timeout`	`number`	`5000`	Maximum execution time in milliseconds.
`exclusive`	`boolean`	`false`	Only one plugin can be the active provider. Used for `email:deliver` and `comment:moderate`.
`handler`	`function`	—	The hook handler function. Required.

Required capabilities

Several hooks expose protected data or can change an operation. EmDash registers them only when the manifest declares the matching capability:

Hooks	Capability	Reason
`content:beforeSave`	`content:write`	The hook can replace submitted content.
`content:beforePublish`, `content:beforeSchedule`, `content:beforeUnpublish`	`hooks.content-policy:register`	The hooks can reject publication state changes.
Other `content:*` hooks	`content:read`	Their events expose content or identify an entry.
`media:beforeUpload`	`media:write`	The hook can replace upload metadata or stop the upload.
`media:afterUpload`	`media:read`	Its event exposes the stored media item.
`email:beforeSend`, `email:afterSend`	`hooks.email-events:register`	The hooks inspect email lifecycle events.
`email:deliver`	`hooks.email-transport:register`	The hook becomes an email transport provider.
All `comment:*` hooks	`users:read`	Comment events can contain author contact information and request metadata.
`page:fragments`	`hooks.page-fragments:register`	The hook injects first-party page content and is native-only.

Lifecycle hooks, cron, and page:metadata have no registration capability. Declare the listed capability even when a hook only reads its event and does not call the matching ctx API. The declaration gives the operator an accurate consent prompt, gates the ctx API, and is required when the plugin runs in process. Capabilities and security explains the runtime effect.

Lifecycle hooks

Run during plugin installation, activation, deactivation, and removal.

`plugin:install`

Runs once when the plugin is first added to a site.

This example assumes the manifest declares an items storage collection:

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

Event: {} — Returns: Promise<void>

`plugin:activate`

Runs when the plugin is enabled (after install or when re-enabled).

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

Event: {} — Returns: Promise<void>

`plugin:deactivate`

Runs when the plugin is disabled (but not removed).

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

Event: {} — Returns: Promise<void>

`plugin:uninstall`

Runs when the plugin is removed from a site.

"plugin:uninstall": async (event, ctx) => {
  ctx.log.info("Uninstalling plugin...");
  if (event.deleteData) {
    while (true) {
      const result = await ctx.storage.items.query({ limit: 100 });
      if (result.items.length === 0) break;
      await ctx.storage.items.deleteMany(result.items.map((item) => item.id));
    }
  }
},

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

Content hooks

Run during create, update, and delete operations on site content.

`content:beforeSave`

Runs before content is saved. Return modified content, a sandbox hook error result, or void to leave it unchanged.

To reject a save from the sandbox, return a versioned hook result with a SAVE_REJECTED error. Set reason to plain text between 1 and 500 characters. EmDash identifies the plugin and shows the reason to the editor. Empty, overlong, malformed, and unknown error results fail the save with a generic hook error.

"content:beforeSave": async (event, ctx) => {
  const { content } = event;
  if (typeof content.title !== "string" || content.title.trim() === "") {
    return {
      __emdashSandboxHookResult: true,
      version: 1,
      error: {
        code: "SAVE_REJECTED",
        reason: "Add a title before saving.",
      },
    };
  }

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

  return content;
},

Do not put HTML in reason. The admin renders the value as text.

From the host process, throw ContentSaveRejectedError (exported from emdash) instead. The API returns SAVE_REJECTED with your message. Any other exception from either execution mode fails the save with a generic CONTENT_HOOK_ERROR response.

Event: { content, collection, isNew, id, actor } — Returns: modified content, a sandbox hook error result, or void. On an update, id is the ID of the existing item and content holds only the submitted field values; load the stored item with ctx.content.get(event.collection, event.id). Authenticated REST, visual editing, and MCP saves include actor.id and the numeric actor.role. Internal writes without an authenticated user omit actor.

`content:afterSave`

Runs after content is successfully saved. Use for side effects like notifications, logging, or external syncs.

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

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

Event: { content, collection, isNew, actor } — Returns: Promise<void>. Authenticated saves include the same optional actor snapshot as content:beforeSave.

`content:beforeDelete`

Runs before content is deleted. Return false to cancel; true or void allows it.

"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, permanent: false } — Returns: boolean | void

This hook runs before an entry is moved to trash. Removing an entry permanently from trash does not run content:beforeDelete again.

`content:afterDelete`

Runs after content is successfully deleted.

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

Event: { id, collection, permanent } — Returns: Promise<void>. permanent is false when the entry was moved to trash and true when the entry was removed permanently.

Declare hooks.content-policy:register to inspect and reject publication, scheduling, or unpublication without receiving content read, write, or publication-action access.

Return void to allow the action or { cancel: true, reason } to reject it. The reason must contain 1–500 plain-text characters. Invalid decisions and unexpected errors abort by default without exposing the exception. Explicit rejections return PUBLISH_REJECTED, SCHEDULE_REJECTED, or UNPUBLISH_REJECTED.

All three events contain { content, collection, origin, actor? }. origin.source is api, mcp, visual-editor, plugin, scheduler, or system; plugin origins also contain pluginId. Authenticated human actions include actor.id, numeric actor.role, and the matching actor.source. EmDash accepts the visual-editor origin only from the signed, short-lived action token embedded in an authenticated toolbar render; ordinary API requests cannot select their origin.

Publish and schedule events expose the effective draft in content.data and the staged slug in content.slug. Unpublish events expose the currently live content that the action would remove.

`content:beforePublish`

The following hook requires an approval marker before content can become live:

"content:beforePublish": async (event) => {
  const data = event.content.data;
  const approvalStatus =
    typeof data === "object" && data !== null && "approval_status" in data
      ? data.approval_status
      : undefined;
  if (approvalStatus !== "approved") {
    return { cancel: true, reason: "Approve this entry before publishing." };
  }
},

This hook runs before manual, MCP, plugin, system, and scheduled publication. Scheduled content is checked again when its publication time arrives. A scheduler rejection unschedules the entry, stores the public-safe reason, and lists the affected entry on the dashboard instead of retrying the same permanent rejection on every scheduler tick. A successful schedule, publish, or delete clears the record. An administrator can dismiss a stale record when the entry or policy plugin is no longer available.

`content:beforeSchedule`

Runs before an entry receives a publication time. The event also contains scheduledAt.

There is no content:beforeUnschedule hook. An administrator can always cancel a future publication.