Hooks

Hooks are how you change what Justflows does without changing Justflows. Write the plugin in plugins/<name>/ (copy plugins/hello-world) and register hooks in activate(). Names autocomplete from @justflows/sdk.

Actions#

Observe only. Cannot cancel. If your handler throws, Justflows logs it against your plugin and continues — a broken analytics plugin must not block publishing. Treat payloads as read-only. Async handlers are awaited in order.

Gates#

Run before commit. Call event.cancel("Human-readable reason") to abort. Fail closed: if your gate throws, the operation is aborted and attributed to your plugin. Priority order; first cancellation wins.

• content.beforeCreate / beforeUpdate / beforeDelete / beforePublish
• media.beforeUpload / media.beforeDelete
• workspace.beforeCreate / beforeSuspend / beforeReactivate / beforeDelete / beforePurge, site.beforeCreate
• domain.beforeAdd (refuse a custom domain before it is added)

ctx.hooks.gate("media.beforeUpload", (event) => {
  if (event.sizeBytes > 10_000_000) {
    event.cancel("Files must be under 10 MB.");
  }
});

Filters#

You must return a value. On core hooks TypeScript enforces it. If a custom filter returns undefined, the previous value is kept and a warning is logged. Throws skip your filter and keep the last good value.

SYNC_FILTERS: http.responseHeaders and site.underConstruction.render — handlers must not be async. html.head, html.title, html.canonical, and site.identity are awaited. content.blocks, content.render, and theme.css may be async.

Options and ownership#

• priority — lower runs earlier (default 100).
• once — auto-dispose after first dispatch.
• id — stable label in diagnostics.
• network: true — run this handler on every site while the plugin is active on the main site, also on sites that never activated it (needs platform:network; see Network-wide handlers).
• Plugins may emit only hooks under their own manifest id (justflows.acme-seo.scoreCalculated).
• Declaration merging on ActionEventMap / GateEventMap / FilterValueMap types your own names.

Network-wide handlers

On a multisite installation a handler normally runs only on the sites that activated the plugin. Register it with { network: true } to run it on every site while the plugin is active on the main site. That needs the sensitive platform:network permission; without it, registering throws. Only the handlers you mark run network-wide: routes, jobs, and every other handler stay on the sites that activated the plugin. Inside a network handler, ctx.settings and ctx.data still belong to the request's site; read the main site's choices with ctx.network.mainSiteSettings.get(key) and its secrets with ctx.network.mainSiteSecrets, and link to a site with ctx.network.site(siteId?), which returns its public url. Files the handler's markup loads from /ext/<plugin id>/ are served on every site.

ctx.hooks.filter("admin.body", async (html) => {
  const tag = await ctx.network?.mainSiteSettings.get<string>("adminTag");
  if (!tag || !/^[A-Z0-9-]+$/.test(tag)) return html;
  return `${html}<script src="/ext/acme.tags/tag.js" data-tag="${tag}"></script>`;
}, { network: true });

Header and comment hooks#

header.templates contributes named headers that appear in the per-page picker, build()-rendered at request time. header.resolve lets a plugin own a page's header per request; header.config adjusts the resolved header before render. comments.render restyles or replaces the rendered comments block. New SDK types: HeaderConfig, HeaderTemplate, HeaderBuildContext, HeaderResolveContext, CommentsBlockRenderContext, PublicComment. Outgoing webhooks add two filters — webhook.eventTypes to register event names and webhook.payload to reshape a body — plus the webhook.delivery action after every attempt; see Webhooks. Access-policy changes emit access-change hooks; a plugin registers a runtime capability with ctx.capabilities.register() and declares cookies with ctx.cookies.declare() (reading the resolved site registry with ctx.cookies.list()). The synchronous analytics.head filter lets Cookie consent defer third-party tags until consent is granted. For menus, menu.design.presets contributes one-click layout presets to the designer's design panel and menu.visibility.evaluate resolves a plugin-defined item condition — an unrecognized or deactivated condition id hides the item. See docs/HOOKS.md → Contributing a menu design preset in the Community Edition repository.