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

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, html.head, site.underConstruction.render — handlers must not be async. 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.
• Plugins may emit only hooks under their own manifest id (acme.seo.scoreCalculated).
• Declaration merging on ActionEventMap / GateEventMap / FilterValueMap types your own names.

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.