Plugins

A plugin is a definition that receives the app at .plug() time, adds capabilities, and returns it with accumulated types. Plugins are how OKE's own built-ins are built — auth, the Console, docker derivation, channels — so the extension API you get is the one we use ourselves.

Quick start

import { plugin, field, id, now } from "okengine";

export const audit = plugin("audit", { version: "1.0.0" })
  .table("audit_log", {
    id: field.text().primaryKey().defaultFn(id),
    flowId: field.text().notNull(),
    at: field.integer().notNull().defaultFn(now),
  })
  .hook("afterHandle", async (ctx, fxOrErr, fx) => {
    // observe every completed flow
  });

import { oke } from "okengine";
import { audit } from "./plugins/audit.ts";

export const app = oke({ name: "shop", env: "dev" }).plug(audit);

What a plugin may contribute

Every method below exists on both the fluent definition and the boot-time builder the registry records:

New infrastructure is a driver for an existing element, never a ninth element — plugins follow the same law.

Hooks run inside the pipeline

A hook intercepts every flow invocation at one stage, in documented order:

The handler itself is a pipeline slot, not a hook name — you cannot replace a flow's body from a plugin, only observe and short-circuit around it. A hook may return void, a Response (short-circuit), or a FlowFailure.

At onResponse, ctx.response holds the final serialized HTTP response — mutate it in place (rebuild with new headers) to stamp headers on every outcome, including failures. Non-HTTP triggers leave ctx.response undefined; middleware hooks must no-op then. The official plugins rely on exactly this contract.

Edge handlers answer unmatched requests

Hooks only ever see requests a flow owns — an OPTIONS preflight for a path bound to GET matches nothing and would 404 untouched. .edge(fn) closes that gap: handlers run in install order when the router finds no flow, the first returned Response answers, and undefined passes to the next handler, then the plain 404:

plugin("cors", { version: "1.0.0" }).edge((request, info) => {
  if (info.method === "OPTIONS" && request.headers.has("origin")) {
    return new Response(null, { status: 204, headers: preflightHeaders(request) });
  }
  return undefined; // not mine — let someone else answer, else 404
});

There is no flow context on the edge (no flow matched!), so handlers receive only (request, { method, path }) — no ctx, no fx. The official CORS plugin's preflight handling is built on exactly this.

Runtime configuration: code or DB

Plugin options are static by default — changing them means a redeploy. Every official plugin also accepts a configSource(), which keeps code as the floor and lets a database row override it live, with a KV binding as the automatic read-through cache:

import { every, oke, on, store } from "okengine";
import { configSource, maintenanceMode } from "okengine/plugins";

const db = store.sql("app");
const cache = store.kv("cache");

const maintenance = configSource({
  plugin: "maintenance-mode",
  code: { enabled: false }, // the floor — always safe
  db: { store: db }, // source of truth (optional)
  kv: cache, // read-through cache (optional)
});

on(every("30s"), maintenance.sync()); // one clock flow refreshes the box

export const app = oke({ name: "shop", env: "dev" }).plug(maintenanceMode(maintenance));

oke db push

INSERT INTO maintenance_mode_config ("key", "value")
VALUES ('config', '{"enabled": true, "retryAfter": 300}');

Plugin tables are whole tables

A plugin may declare its own tables with field.* columns, merged into the generated domain schema at oke db time — the CLI loads your live app entry, collects every plugged plugin's contributions, and emits them alongside app tables:

plugin("billing", { version: "2.1.0" }).table(
  "invoices",
  { id: field.text().primaryKey().defaultFn(id) },
  { plane: "user" },
);

Extending an existing app-owned table with plugin columns is not supported in v1 — contribute a separate table and reference the app's by key. The optional plane metadata ("operator" | "user" | "shared") keeps data-plane isolation intact for privacy tooling.

Identity, config, and dependencies

Troubleshooting

Learn more

• Security Headers · CORS · CSRF · Compression · Maintenance Mode · IP Allowlist — first-party plugins built on exactly this API
• Flow — what plugin flows and hooks plug into
• Store — field.* builders and schema sync
• Configuration — where plugin config is declared

Next