Plugins
How the plugin kernel works: what a plugin is, the client and server slots it contributes to, how plugins are installed at build time and switched on and off at runtime.
The admin console and the workspace do not hard-code features. They read slots (the sidebar, the dashboard, the billing header and the agent workbench), and every installed plugin contributes entries to them. The foundation itself is a plugin, each module is one, and a feature you write for your own product can be one too. To write one, see Write a console plugin.
What a plugin is
A plugin is a manifest plus contributions to named slots, in one folder under src/plugins/<id>/.
| File | Holds | Loaded by |
|---|---|---|
manifest.ts | Pure data: id, version, kind, requires, routes | Anything |
plugin.ts | Browser-safe contributions: navigation with icons, blocks, workbench extensions | The web app |
plugin.server.ts | Server-only contributions: API routes, billing fulfilment, agent host extensions. Optional | The web app's server and the agent service |
The manifest's routes lists the path prefixes the plugin owns, without the locale prefix, such as /admin/cms or /app/image. requires lists plugin ids that must be installed and switched on.
| Kind | Meaning | Can be switched off |
|---|---|---|
builtin | The foundation: the console every installation has | No |
module | A module that ships in the repository, with a marker region and a module.json | Yes |
agent | An agent capability; requires agent-starter | Yes |
local | Belongs to your project. It has no marker region and no module.json | Yes |
Installed at build time, enabled at runtime
Plugins are not downloaded or loaded while the app runs. The template deploys to Cloudflare Workers, which cannot load remote code, file routes are fixed at build time, and a plugin has to pass type checking and the validators together with the host. A plugin therefore has two separate states.
Installed is a build-time fact. src/plugins/installed.ts is an explicit list, and what a deployment runs is readable there. A module's entry sits in its // @module:<key> region of that list. You add a local plugin by hand, outside any region. src/plugins/installed.server.ts is the matching list of server halves. The agent service imports it, so nothing reachable from it may import React, icons or @/ aliases.
Enabled is a runtime fact, stored in the admin config table under plugins.state.v1. Only the ids an operator switched off are stored, so a plugin installed later is on by default. The enabled set is resolved like this:
builtinplugins are always on.- A plugin in the disabled list is off.
- A plugin whose dependency is off is off too, transitively.
An administrator with config.write changes it in Settings → Plugins (/admin/plugins). The console rejects switching off a plugin that an enabled plugin still requires and names the dependents. It rejects switching on a plugin whose dependency is off and names the dependency.
Client slots and server slots
A slot is a typed, named list that the host reads and plugins contribute to. Client slots add UI: admin.nav and app.nav take sidebar entries, and app.dashboard.cards takes a card on the /app dashboard. A plugin contributes to them through contributes in plugin.ts, and the console shells read them through usePluginValues(slot). Server slots add behaviour: api.routes serves endpoints under /api/plugins/<pluginId>/…, and billing.fulfilment delivers what a paid order buys. A plugin contributes to them through contributes in plugin.server.ts.
Each slot declares the shape of one contribution and the field that keys it. The full list, with each contribution's type, is in src/plugins/slots.ts (client) and src/plugins/server-slots.ts (server). The agent slots exist only when the agent-starter template is installed; Agent plugins covers them.
The registry merges the installed plugins once, when it is built, and rejects every conflict with one of these errors:
| Error | Cause |
|---|---|
duplicate_plugin | Two plugins share an id |
duplicate_slot_key | Two contributions to one slot share a key |
duplicate_plugin_route | Two plugins claim one route prefix |
missing_plugin_dependency | A plugin requires one that is not installed |
plugin_dependency_cycle | Plugins require each other in a loop |
unknown_plugin_slot | A contribution names a slot that is not declared |
What switching a plugin off does
| Surface | Effect |
|---|---|
| Navigation and blocks | The shells read contributions of enabled plugins only, so its entries and cards disappear. |
Pages under /admin and /app | The console layouts call the route guard in beforeLoad; a path owned by a disabled plugin resolves to not found. The owner is the plugin with the longest matching route prefix. |
/api/plugins/<id>/… | The catch-all route returns 404. |
| Server functions | A module's own functions call requirePluginEnabled(<id>) after their auth guard and reject the call. |
| Billing | Only fulfillers of enabled plugins are called. |
| Agent | A disabled plugin's scenes, routes and skills are skipped, and a run on its scene is rejected with plugin_disabled. |
The route guard runs in the two console layouts. A public route prefix in a manifest, such as /blog, records ownership but is not blocked there.
Disabling a plugin does not uninstall it. Files, tables, data and migrations stay.
Deployment capabilities
Some entries depend on what the deployment has. An app.nav entry may carry requires: "agent", and it is hidden when the agent service is not available, even with its plugin enabled. The console layouts resolve the enabled ids and the capabilities together on the server and pass both to the shell. See Agent runtime.
How modules relate to plugins
A module is a feature whose boundary is recorded in modules/<key>/module.json: files, shared-file regions, migrations and packages. A plugin is how that module's console presence is wired in. The two must agree in three places, which pnpm validate:plugins checks:
- The plugin id equals the module key, and both carry the same version.
- The module's
filesincludesrc/plugins/<key>/**. - The module's
fragmentsincludesrc/plugins/installed.ts, where its marker region sits.
Schema, permission seeds and dictionary entries are not plugin contributions. They stay in // @module:<key> regions of the shared files. See Build a module.
Files
Next steps
Data access
How business code reaches the database: repositories only, one contract over SQLite, D1 and Postgres, what a transaction means on each, and why migrations are kept per dialect.
Write a console plugin
Add a feature of your own as a local plugin: a workspace sidebar entry, a page and a dashboard card that an administrator can switch on and off.