Plugin System

The runtime’s extensibility mechanism. Plugins are isolated units that can intercept requests, register routes, provide services to other plugins, and expose UI in the shell. The system supports hot reload, declarative dependencies, and two execution modes (persistent vs serverless).

For the request pipeline that involves plugins, see Runtime. For the pool that runs serverless plugins, see Worker Pool.

Architecture

pluginDirs (RUNTIME_PLUGIN_DIRS)
        │
        ▼
PluginLoader   — scan + parse manifest.yaml + topological sort + lazy import
        │
        ▼
PluginRegistry — stores plugins, runs hooks, resolves routes, shares services
        │
        ▼
Hooks:  onInit · onRequest · onResponse · onShutdown
        onServerStart · onWorkerSpawn · onWorkerTerminate

Component	Role
PluginLoader	Auto-discovery in pluginDirs, manifest.yaml parsing, topological sort, lazy import
PluginRegistry	Stores plugins, runs hooks, manages service sharing, resolves routes

Plugin structure

plugins/plugin-example/
├── manifest.yaml      # Metadata + config
├── plugin.ts          # Middleware (persistent mode, main process)
├── index.ts           # Worker entrypoint (serverless mode, worker pool)
├── server/api.ts      # Shared API code
├── client/            # SPA (React/Solid/Vue/etc.)
└── dist/              # Build output
    ├── plugin.js
    ├── index.js
    └── client/index.html

API modes — persistent vs serverless

A central decision. Choose one — do not duplicate the API between plugin.ts and index.ts.

Mode	When to use	plugin.ts has routes?	index.ts has routes?	entrypoint
Persistent	DB connections, WebSocket/SSE, in-memory cache, cron, shared state	Yes	No (SPA only)	dist/client/index.html
Serverless	Stateless CRUD, file ops, isolation, horizontal scaling	No	Yes	dist/index.js

Persistent

Runs in the main process. The API lives on plugin.ts; index.ts only serves the SPA.

// plugin.ts — runs in the main process (persistent)
export default function databasePlugin(config): PluginImpl {
  let db: DatabasePool;
  return {
    routes: api, // API here (a Hono app)
    onInit(ctx) {
      db = new DatabasePool(config.url); // persistent connection
    },
  };
}

// index.ts — SPA only
export default { fetch: createStaticHandler(clientDir) };

Current persistent plugins: gateway, keyval, logs, metrics, proxy, turso, vhosts.

Serverless

Runs in the worker pool, per request. The API lives on index.ts; plugin.ts has no routes.

// plugin.ts — no routes
export default (config): PluginImpl => ({
  onInit(ctx) { /* optional */ },
});

// index.ts — API in the worker pool
export default {
  routes: { "/api/*": api.fetch },
  fetch: createStaticHandler(clientDir),
};

Entrypoint modes

Extension	Mode	Behavior
.html	SPA	serveStatic only; index.ts is NOT executed
.js / .ts	Service	Imports the module; expects export default { fetch?, routes? }

Common mistake

API code in index.ts while entrypoint points to an .html file. The API is silently ignored — the wrapper only serves static files. Pick one mode.

Manifest schema

name: "@buntime/plugin-example"  # Unique identifier
base: "/example"                 # /[a-zA-Z0-9_-]+; omit for hook-only plugins
enabled: true                    # default: true

# Worker / plugin entrypoints
entrypoint: dist/index.js        # service mode (or .html for SPA)
pluginEntry: dist/plugin.js      # middleware in the main process

# Dependencies (topological sort)
dependencies:
  - "@buntime/plugin-turso"      # required — fails if absent
optionalDependencies:
  - "@buntime/plugin-keyval"     # ignored if absent

# Auth bypass via onRequest
publicRoutes:
  ALL: ["/health"]
  GET: ["/api/public/**"]
  POST: ["/api/webhook"]

# Shell menus (cpanel)
menus:
  - { icon: lucide:box, path: /example, title: Example }

# Env vars for workers
env:
  MY_VAR: "value"

# Config schema for Helm/Rancher UI
config:
  apiKey:
    type: password
    label: API Key
    env: EXAMPLE_API_KEY         # maps to ConfigMap

Key fields

Field	Type	Description
name	string	Unique identifier, format @scope/plugin-name
base	string	Base path for plugin routes
enabled	boolean	false to skip on load
entrypoint	string	Worker entrypoint (HTML for SPA, JS for service)
pluginEntry	string	Main-process middleware
dependencies	string[]	Required plugins (error if absent)
optionalDependencies	string[]	Optional plugins (ignored if absent)
publicRoutes	array | object	Bypass onRequest hooks
menus	MenuItem[]	Menu items for the shell
injectBase	boolean	Controls <base href> injection
visibility	enum	public | protected | internal
env	record	Vars for plugin workers
config	object	Config schema for Helm generation

Hook-only infrastructure plugins that don’t serve routes should omit base entirely — don’t set base: "", which can later be mistaken for a root plugin-app base during route resolution.

Auto-discovery

PluginLoader scans pluginDirs (PATH-style, :-separated). Supported structures:

1. Direct:       {pluginDir}/plugin.ts + manifest.yaml
2. Subdirectory: {pluginDir}/{name}/plugin.ts + manifest.yaml
3. Scoped:       {pluginDir}/@scope/{name}/plugin.ts + manifest.yaml

Entry-file priority: manifest.pluginEntry → plugin.{ts,js} → index.{ts,js}. Default for RUNTIME_PLUGIN_DIRS: /data/.plugins:/data/plugins (built-in first, external second).

Topological sort — Kahn’s algorithm

Plugins are sorted by dependency before loading, using Kahn’s algorithm (O(V + E)):

1. Compute the in-degree (number of dependencies) for each plugin.
2. Enqueue plugins with in-degree zero.
3. For each processed plugin, decrement the in-degree of its dependents; enqueue any that reach zero.
4. Any plugin left unprocessed → a dependency cycle, which is a hard error.

Example: with keyval depending on turso, the resulting order is always turso → keyval, regardless of filesystem order.

Lifecycle hooks

interface PluginImpl {
  routes?: Hono;
  middleware?: MiddlewareHandler;
  server?: { routes?; fetch? };
  websocket?: { open?; message?; close? };
  provides?: () => unknown | Promise<unknown>;

  onInit?(ctx: PluginContext): void | Promise<void>;
  onShutdown?(): void | Promise<void>;
  onServerStart?(server): void;
  onRequest?(req, app?): Request | Response | undefined;
  onResponse?(res, app): Response;
  onWorkerSpawn?(worker, app): void;
  onWorkerTerminate?(worker, app): void;
}

Hook	When	Return	Notes
onInit(ctx)	On plugin load	void/Promise	30s timeout — hard failure if exceeded
onShutdown()	On SIGINT	void/Promise	Reverse order (LIFO)
onServerStart(server)	After Bun.serve()	void	Access to the instance for WS upgrade
onRequest(req, app?)	Before each handler	Request (modified) | Response (short-circuit) | undefined	Topological order
onResponse(res, app)	After response generation	Response	Topological order
onWorkerSpawn(worker, app)	Worker created	void	—
onWorkerTerminate(worker, app)	Worker terminated	void	—

onInit — the context

interface PluginContext {
  config: Record<string, unknown>;   // from manifest.yaml
  globalConfig: GlobalPluginConfig;  // workerDirs, poolSize, pluginDirs
  logger: PluginLogger;              // scoped logger
  auth?: PluginAuthContext;          // API key store + master key
  pool?: WorkerPool;                 // worker pool, if needed
  getPlugin<T>(name: string): T | undefined; // another plugin's exports
  runtime: { api: string; version: string }; // same as /.well-known/buntime
}

The canonical config-reading pattern reads Bun.env first (ConfigMap/Helm), then the manifest config, then a default:

const apiKey = Bun.env.MY_API_KEY ?? pluginConfig.apiKey ?? "default";

Caution

Never write to Bun.env. Workers are isolated — they wouldn’t see the change even if it persisted.

onRequest — short-circuit

onRequest(req, app) {
  if (rateLimitExceeded) {
    return new Response("Too Many Requests", { status: 429 }); // short-circuit
  }
  return undefined; // continue the pipeline
}

Return	Behavior
undefined	Continue with the original request
Request	Continue with the modified request
Response	Short-circuit — the runtime returns immediately

Plugins run in topological order, e.g. Metrics → Proxy → Gateway → Worker.

Service sharing — provides / getPlugin

Plugins share functionality without importing each other. A provider returns its public surface from provides(); a consumer reaches it through ctx.getPlugin().

// Provider — plugin-turso/plugin.ts
export default (config): PluginImpl => {
  const service = new TursoService(config);
  return {
    provides: () => service, // exposed to other plugins
    onInit(ctx) { /* ... */ },
  };
};

// Consumer — must declare the dependency in its manifest
export default (config): PluginImpl => ({
  onInit(ctx) {
    const turso = ctx.getPlugin<TursoService>("@buntime/plugin-turso");
    if (!turso) throw new Error("Requires @buntime/plugin-turso");
  },
});

Rules:

• provides() may be sync or async; its return value is what getPlugin yields.
• Exports are available after the provider’s onInit — declare dependencies so the loader orders them correctly.

Hot reload

# Upload a tarball/zip (extracts to pluginDirs; does NOT load yet)
POST /api/plugins/upload

# Re-scan + reload all (loads newly uploaded plugins, no process restart)
POST /api/plugins/reload

# Enable / disable a single plugin at runtime (no restart)
POST /api/plugins/<url-encoded-name>/enable
POST /api/plugins/<url-encoded-name>/disable

reload clears the registry, re-scans directories, sorts topologically, re-runs onInit, and refreshes the live HTTP server’s native route table.

The runtime serves three kinds of plugin HTTP surface, each reaching the live server differently:

Surface	Declared as	How it dispatches	Hot-reloads?
Hono routes	PluginImpl.routes	app.fetch queries the registry per request	Yes — inherently dynamic
Fetch handler	PluginImpl.server.fetch	app.fetch iterates the registry per request	Yes — inherently dynamic
Native routes	PluginImpl.server.routes	Bun matches these before app.fetch; the table is fixed at Bun.serve() time	Yes — reload calls server.reload({ routes })

Important

Before native-route reloading was wired, server.routes plugins appeared “loaded” but their HTTP routes 404’d until a process restart, because Bun’s native route table is built once at boot. reload now calls server.reload() so native routes are rebuilt from the current registry.

enable/disable flip the plugin’s manifest enabled flag on disk (a surgical line edit that preserves comments), then rescan and refresh routes. Because the manifest is the source of truth for enabled state, the change survives restarts. Names are URL-encoded, so scoped names work: POST /api/plugins/%40acme%2Fplugin-x/disable.

Public routes

Bypass onRequest hooks (auth). Two formats:

# Array — all methods
publicRoutes:
  - "/health"
  - "/api/public/**"

# Object — per method
publicRoutes:
  ALL: ["/health"]
  GET: ["/api/users/**"]
  POST: ["/api/webhook"]

Wildcards: * (single segment), ** (multi-segment). Plugin public routes are absolute; worker public routes are relative and made absolute by the runtime (/api/health → /todos-kv/api/health).

Plugins with UI

Plugins with an HTML entrypoint are automatically exposed as micro-frontends in the shell via <z-frame>:

name: "@buntime/plugin-keyval"
base: "/keyval"
entrypoint: dist/client/index.html
pluginEntry: dist/plugin.js
menus:
  - { title: KeyVal, icon: lucide:database, path: /keyval }

Trailing slash

The shell loads the plugin base with a trailing slash — <z-frame> normalizes its src to /<base>/. Workers with an entrypoint get a 308 redirect from /<base> to /<base>/, so this is transparent. But a plugin that serves its own UI through server.routes must register both /<base> and /<base>/ (Bun native routes match exactly). Prefer an entrypoint for UI plugins.

Details in Micro-Frontend Architecture.

Best practices

• Single mode — don’t duplicate the API between plugin.ts and index.ts.
• Bun.env.X ?? config.x — read with a fallback, never write.
• : for multi-values — PATH-style, never commas.
• Declare dependencies — required in dependencies, optional in optionalDependencies.
• Fast init — there’s a 30s timeout in onInit. Lazy-load expensive connections.
• Graceful onShutdown — flush caches, close DB, clear timers.
• Lightweight hooks — onRequest/onResponse run per request.

Related

• Runtime — request pipeline, resolution order.
• Worker Pool — serverless plugin execution.
• Writing a plugin — a step-by-step guide.
• Plugins overview — the bundled core plugins.