Build a third-party plugin

Start from the supported example

Copy plugins/hello-world in the CE repository. The runtime loads dist/index.js or index.js; it does not execute TypeScript from src, and it does not run npm install or a build step for you — compile before you package.

acme-plugin/
├── justflows.json
├── package.json
├── src/
│   ├── index.ts
│   └── styles/plugin.css
├── public/            # manifest.assets — bundled into /jf-plugins.<hash>.js
│   └── widget.js
├── admin/             # manifest.adminApp — framed admin screens
│   └── index.html
└── dist/
    ├── index.js
    └── styles/plugin.css

The two files below are one worked example, Acme Reviews — a plugin that adds a review content type, an admin inbox, a public star-rating widget, and an email notification setting. It uses every manifest field you are likely to need; copy it whole and delete what you don’t.

{
  "schemaVersion": 1,
  "type": "plugin",
  "id": "justflows.acme-reviews",
  "apiNamespace": "acme-reviews",
  "name": "Acme Reviews",
  "version": "1.2.0",
  "publisher": "Acme",
  "description": "Star ratings and moderated reviews for any content type, with a public widget and an admin inbox.",
  "homepage": "https://acme.example/reviews",
  "license": "GPL-2.0-or-later",
  "engines": { "justflows": ">=0.4.0 <0.5.0" },
  "permissions": ["content:create", "content:read", "content:delete", "admin:extend", "mail:send"],
  "entrypoints": { "server": "dist/index.js" },
  "setupPath": "setup",
  "contentTypes": ["review"],
  "adminMenu": [
    {
      "id": "reviews",
      "label": "Reviews",
      "labelKey": "nav.reviews",
      "labels": { "nl": "Beoordelingen" },
      "icon": "⭐",
      "domain": "extensions"
    }
  ],
  "adminApp": {
    "dir": "admin",
    "routes": [
      { "entry": "index.html", "title": "Reviews" },
      { "path": "setup", "entry": "setup.html", "title": "Reviews setup" }
    ]
  },
  "assets": {
    "dir": "public",
    "scripts": ["jf-reviews.js"],
    "styles": ["jf-reviews.css"]
  },
  "settingsSchema": {
    "minRatingToAutoPublish": {
      "type": "number",
      "label": "Minimum star rating to auto-publish",
      "default": 3
    },
    "notifyEmail": {
      "type": "string",
      "label": "Notify on new review (optional)",
      "description": "Sent through the configured outbound mail transport.",
      "default": ""
    },
    "showReviewerName": {
      "type": "boolean",
      "label": "Show reviewer name publicly",
      "default": true
    }
  },
  "registry": {
    "commercialMarketplace": false,
    "listed": true,
    "free": true,
    "comingSoon": false,
    "category": "Commerce",
    "tags": ["reviews", "ratings", "widget"],
    "screenshots": []
  }
}

import type { PluginModule } from "@justflows/sdk";
import { pluginShouldDeleteData } from "@justflows/sdk";

const plugin: PluginModule = {
  // Every field here except "main" also lives in justflows.json and must say
  // the same thing — the installer reads that file before any code runs; the
  // loader reads this object only after your compiled module is imported.
  manifest: {
    id: "justflows.acme-reviews",
    apiNamespace: "acme-reviews",
    name: "Acme Reviews",
    version: "1.2.0",
    description: "Star ratings and moderated reviews, with a public widget and an admin inbox.",
    author: "Acme Team",
    license: "GPL-2.0-or-later",
    engines: { justflows: ">=0.4.0 <0.5.0" },
    permissions: ["content:create", "content:read", "content:delete", "admin:extend", "mail:send"],
    main: "index.js",
    setupPath: "setup",
    contentTypes: ["review"],
    adminMenu: [
      {
        id: "reviews",
        label: "Reviews",
        labelKey: "nav.reviews",
        labels: { nl: "Beoordelingen" },
        icon: "⭐",
        domain: "extensions",
      },
    ],
    adminApp: {
      dir: "admin",
      routes: [
        { entry: "index.html", title: "Reviews" },
        { path: "setup", entry: "setup.html", title: "Reviews setup" },
      ],
    },
    assets: {
      dir: "public",
      scripts: ["jf-reviews.js"],
      styles: ["jf-reviews.css"],
    },
    settingsSchema: {
      minRatingToAutoPublish: {
        type: "number",
        label: "Minimum star rating to auto-publish",
        default: 3,
      },
      notifyEmail: {
        type: "string",
        label: "Notify on new review (optional)",
        description: "Sent through the configured outbound mail transport.",
        default: "",
      },
      showReviewerName: { type: "boolean", label: "Show reviewer name publicly", default: true },
    },
  },

  async activate(ctx) {
    // Idempotent: safe to run on every activation, does nothing once the type exists.
    await ctx.content.ensureType({
      slug: "review",
      label: "Review",
      fields: [
        { key: "rating", label: "Rating", type: "number", required: true },
        { key: "body", label: "Review", type: "textarea", required: true },
      ],
    });

    ctx.capabilities.register({ id: "reviews:moderate", label: "Moderate reviews", group: "Reviews" });

    // Renders the hydration marker the "jf-reviews.js" asset below fills in.
    ctx.blocks.register({
      type: "justflows.acme-reviews.widget",
      version: 1,
      title: "Reviews",
      description: "Star rating and review list for the current page.",
      category: "content",
      schema: { targetId: { type: "text" } },
      validateProps: (raw) => ({ targetId: String((raw as { targetId?: string })?.targetId ?? "") }),
      render: (props) =>
        `<div class="jf-reviews" data-target="${String((props as { targetId: string }).targetId)}"></div>`,
    });

    // Public submit route the widget posts to: /api/acme-reviews/reviews.
    ctx.http.post("reviews", async (req) => {
      const body = req.body as { targetId?: string; rating?: number; body?: string };
      await ctx.data.put("reviews", `${Date.now()}`, body);
      const to = await ctx.settings.get<string>("notifyEmail");
      if (to) await ctx.mail.send({ to, subject: "New review", text: body.body ?? "" });
      return { status: 201, type: "application/json", body: { ok: true } };
    });

    ctx.logger.info("Acme Reviews activated");
  },

  async deleteData(ctx) {
    if (await pluginShouldDeleteData(ctx)) {
      await ctx.data.clear();
    }
  },
};

export default plugin;

entrypoints.server is optional — omit it and the installer tries dist/index.js, then index.js. The embedded manifest.main field is kept for compatibility only; nothing reads it.

justflows.json, field by field

schemaVersion / type

Fixed values that mark this as a plugin package manifest — always 1 and "plugin" today.

id

justflows.<name>, lowercase with hyphens. The installer rejects any other id. It becomes the /ext/{id}/** asset prefix, the /admin/plugins/{id} admin namespace, and the prefix of every hook and block the plugin owns.

apiNamespace

Optional. Also serves the plugin’s routes at /api/{apiNamespace}, such as /api/acme-reviews/reviews.

name / description / homepage

Display metadata for the Marketplace and Admin → Plugins. The runtime never reads these.

publisher

The registry account this listing belongs to — distinct from the optional author on the index.ts manifest.

version / license / engines

SemVer version, a GPL-compatible license (required), and the justflows host-version range this build supports.

permissions

The exact ctx APIs this plugin may use. The host highlights the sensitive ones during install and rejects any call outside this list — declaring contentTypes below is what required adding content:delete here.

entrypoints.server

The compiled file the host imports. Optional — defaults to dist/index.js, then index.js.

setupPath

Admin page the host opens right after activation for first-run setup, relative to /admin/plugins/{id}. Requires admin:extend.

contentTypes

CMS type slugs this plugin owns. The host offers to delete them and every entry when the plugin is uninstalled. Requires content:delete.

adminMenu

Up to 20 sidebar entries, gone the moment the plugin is uninstalled. Requires admin:extend. path is relative to /admin/plugins/{id} (omit it for the root). labelKey is looked up in your own adminApp.locales catalogs first, and labels gives per-locale text for a plugin without an admin app. roles names the roles that may open the page, such as one your plugin registers; without it, administrators and editors may. domain picks the sidebar group, and an unknown group falls back to extensions.

adminSection

Justflows 0.4.1 and later. Gives the plugin its own sidebar section, above Extensions, for menu items with domain: "plugin": a label, an optional labelKey or labels, and an icon that is an emoji or a .png, .svg, or .webp file in the admin app folder. Requires admin:extend.

editorPanels

Up to 5 content editor sections, next to Content, Discussion, and Advanced. A panel has up to 20 fields (text, textarea, url, image, or checkbox, saved in the entry’s fields), or, from Justflows 0.4.1, an app: an admin-app screen that receives the entry’s contentId. indexableOnly limits a panel to content types included in search engines. Requires admin:extend.

workspacePanels

Justflows 0.4.1 and later. Up to 5 cards on Platform → Workspace, each embedding an admin-app screen that receives the workspaceId. Requires admin:extend.

adminApp

The plugin’s own HTML admin screens, framed in an <iframe>: up to 40 routes, relative to /admin/plugins/{id}, and optional locales catalogs per admin language. Requires admin:extend.

assets

Public JS/CSS bundled into /jf-plugins.<hash>.js / .css and added to every public page.

settingsSchema

Small config fields rendered on Admin → Plugins → Settings. ctx.settings.get() / set() read and write them, and the plugin.settings.schema filter can drop fields or fill select options per site.

requires

Optional. Other plugin ids that must already be installed on the site, such as ["justflows.shop"]. Install is refused while one is missing, and activation is refused until each one is active.

registry

Marketplace-only listing data — category, tags, pricing, screenshots. The runtime never reads it.

src/index.ts, section by section

manifest

The same data as justflows.json, minus schemaVersion / type / publisher, with main in place of entrypoints.server. The loader validates this copy and builds ctx.permissions from it.

activate(ctx)

Runs once, when the plugin turns on. Everything registered inside — hooks, blocks, capabilities, HTTP routes — is torn down automatically on deactivate; you never write matching cleanup code for these.

ctx.content.ensureType(…)

Creates the review content type the first time this activates. Idempotent — a no-op on every activation after that.

ctx.capabilities.register(…)

Adds a reviews:moderate user capability while the plugin is active, so an operator can grant it per role.

ctx.blocks.register(…)

Registers the editor/public block that renders the hydration marker jf-reviews.js fills in.

ctx.http.post("reviews", …)

The public submit endpoint the widget script posts to, at /api/acme-reviews/reviews (and /ext/justflows.acme-reviews/reviews). A path that starts with / claims a site-root path instead. Stores the row with ctx.data.put() and, when notifyEmail is set, sends a notification with ctx.mail.send().

deleteData(ctx)

Runs when the plugin is deleted, before deactivation. Honors the operator’s delete-data choice through pluginShouldDeleteData(), then clears everything under ctx.data.

The plugin context

Permissions are least-privilege

Declare only what you use. The host uses the manifest to decide which context APIs are available and highlights sensitive access during installation.

What a route can answer

status / type / body

A normal JSON, HTML, or text response.

file

Stream one of the plugin’s private files (ctx.files) with Range support.

redirect

Send the browser to a same-site path, with a 303 unless status is already a redirect. Absolute and protocol-relative URLs are ignored.

renderPage

Answer with a published page of this site, by slug, in the active theme at the URL the visitor asked for. Never cached.

revalidate

true drops this site’s page caches after a config write. "network" drops every site’s, with platform:network on the main site.

cors

Allow a vouched-for origin, such as a static export host, to read the response.

Admin pages, asset bundles, and admin apps

Acme Reviews above already declares all three, so there is no separate manifest to copy — only the rule for each:

Publish a health check

Declare diagnostics:publish, then register a read-only check during activation. Check IDs are namespaced by plugin, execution is time-bounded, and returned details are recursively redacted before display or export.

const unregister = ctx.diagnostics.register({
  id: "provider",
  label: "Provider connection",
  async run() {
    return (await ctx.secrets.has("apiKey"))
      ? { status: "ok", summary: "Provider credentials are configured" }
      : { status: "warning", summary: "Provider credentials are not configured" };
  },
});

Styles that follow the active theme

Read and cache your built stylesheet during activation, then append it through the async theme.css filter. Namespace classes and use public theme variables such as --color-*, --space-*, and --radius-*.

ctx.hooks.filter("theme.css", (current) =>
  current.includes(MARKER)
    ? current
    : `${current}\n${MARKER}\n${stylesheet}`
);

Cleanup and packaging

Every plugin implements deleteData. Remove plugin data, owned tables, and optionally declared content types according to operator settings. Build before packaging, because the host will not install or compile anything.

Include every top-level file or folder your manifest points to — justflows.json and dist/ always; public/ when you declared assets; admin/ when you declared adminApp. Never include node_modules, src, or tsconfig.json — the host does not need them, and shipping src would let anyone read your unminified source.

pnpm build
COPYFILE_DISABLE=1 tar -czf ../../acme-reviews.jfpkg \
  justflows.json dist \
  $(test -d public && echo public) \
  $(test -d admin && echo admin)