How to author, build, and load a plugin. Architecture (sandbox, IPC, quarantine) lives in architecture/plugin-host.md. Manifest schema lives in architecture/plugin-manifest.md. Method signatures live on StudioPluginApi in @elraptorus/bfw_studio_sdk.
- Node.js >= 24.20.0
- npm >= 12.0.0
- A Working BFW Studio instance
You can use the Plugin generator to quickly create a scaffold for a new plugin.
# Interactive mode
node tools/create-bfw-plugin/src/cli.js my-plugin
# Non-interactive — minimal (no webview)
node tools/create-bfw-plugin/src/cli.js my-plugin --minimal
# Non-interactive — with webview support
node tools/create-bfw-plugin/src/cli.js my-plugin --webviewmy-plugin/
├── package.json # Plugin metadata + bifrostStudio manifest
├── tsconfig.json
├── src/
│ └── index.ts # activate / deactivate
└── dist/
└── index.js # CommonJS output
my-plugin/
├── package.json
├── tsconfig.json
├── src/
│ └── index.ts
├── dist/
│ └── index.js
└── webview/
├── package.json
├── build.mjs
├── tsconfig.json
├── src/
│ ├── index.html
│ ├── main.tsx
│ ├── App.tsx
│ └── styles.css
└── dist/
├── index.html
├── main.js
└── styles.css
cd my-plugin
npm install
npm run build
# For webview plugins:
cd webview && npm install && cd ..
npm run buildInstall it from the Plugins pane with Install Plugin (plugins.installPlugin). Link a development folder when you want the Studio to use that directory in place, or copy a built plugin folder into the plugins directory. The destination is package.json name (plugins/<name> or plugins/@scope/<name>). Uninstall removes a link and leaves the development folder in place; a copied folder is moved to the trash.
You can still point discovery at another directory:
BFW_PLUGINS_DIR=/path/to/my-plugins-folder npm startEvery plugin must export two functions from its main entry:
import type { StudioPluginApi } from '@elraptorus/bfw_studio_sdk';
export async function activate(api: StudioPluginApi): Promise<void> {
// Register commands, panes, editors, settings, …
}
export async function deactivate(): Promise<void> {
// Timers, event listeners, save delegates
}When activation happens: activate() runs when an activationEvents entry fires. onStartup / * run after the window is ready. onCommand: / onDocumentType: / onUri: stay dormant until the trigger. Manifest contributes.editorDocumentTypes is itself a lazy trigger — a matching file open activates the plugin.
The api object: All methods return Promise because they cross IPC. Closures cannot be nested in option objects; register callbacks with onMessage / onDidOpen / events.on.
api.env (frozen):
| Property | Description |
|---|---|
pluginPath |
Absolute path to the plugin root |
pluginName |
Identifier-safe name (scoped npm names are flattened at discovery) |
storagePath |
Persistent plugin-specific directory |
apiVersion |
Studio Plugin API version this load uses |
Your code runs in a Worker Thread inside a SES Compartment. There is no DOM, no Electron, no fetch / http / net, and no eval. File I/O goes through api.workspace (or fs if you declared filesystem). Settings writes are only plugin.<name>.*. Crash 3 times in 60 seconds and the plugin is quarantined until Trust & Re-enable. Users see a permission dialog on every activation path unless they trust the current permission set.
Declare the minimum permissions in bifrostStudio. Vocabulary: filesystem, commands.std / commands.bpmn / commands.dmn, bpmn / bpmn.modelling / bpmn.renderer (same for dmn and landscape), native, system-info. renderer-modules is a legacy alias of bpmn.renderer. network is rejected.
Full tables, ModuleGate, and quarantine mechanics: architecture/plugin-host.md and architecture/plugin-manifest.md.
Example:
{
"name": "my-plugin",
"main": "dist/index.js",
"bifrostStudio": {
"apiVersion": "1.0.0",
"displayName": "My Plugin",
"activationEvents": ["onStartup"],
"permissions": ["filesystem", "commands.std"],
"contributes": { "commands": [] }
}
}CI can skip the dialog with BFW_SKIP_PERMISSION_DIALOG=1.
package.json → bifrostStudio lists contributions before any plugin code runs. That is how the Studio can show commands, panes, and file types for a dormant plugin.
Command IDs in the manifest are local (hello); the public ID is plugin.<name>.hello. The manifest registers a stub that only triggers activation. Your real handler exists only after api.commands.register in activate().
contributes.editorDocumentTypes is a placeholder. You must call api.editors.registerWebviewDocumentType({ id: <same id>, … }) in activate() or the tab stays on “Plugin activated but did not register an editor”.
contributes.pages (or api.workbench.registerPage) adds a page to an existing category, for example discover/insights. The ID must be unused, the page disappears when the plugin unloads, and it is not restored after a restart.
Schema, contribution keys, and cleanup: architecture/plugin-manifest.md.
activate(api) gives you namespaces that mirror the corresponding Bifrost mediators, with serializable POJOs instead of closures. Import types from @elraptorus/bfw_studio_sdk.
| Namespace | Typical use |
|---|---|
commands |
register / executeCommand / tryToExecuteCommand |
notifications |
open / close / onResponse |
settings |
Read any key; write only plugin.<name>.* |
editors |
registerWebviewDocumentType, dirty/save delegates |
panes |
registerWebviewPane |
webviews |
postMessage / onMessage (register before the iframe loads) |
statusBar / menuBar / menus |
Chrome contributions |
workbench |
registerPage / unregisterPage |
events |
Studio events |
diagnostics |
Problems for a URI |
dialogs |
open / file pickers |
workspace |
Project folders, read/write, watch |
views |
Push-only tree views |
themes |
--theme-* token maps |
bpmn / dmn / landscape |
Editor enrichment (permissions required) |
env |
Frozen paths |
enabledWhen on plugin commands is not supported (sync predicate vs async IPC). api.webviews.createPanel is a stub — use an editor document or a pane.
Host-side wiring and denylist: architecture/plugin-host.md.
You will subscribe to selection, place overlays, and (with modelling permission) mutate the diagram. Overlays are non-interactive unless they declare onClickCommand. Context-pad visibility is an elementIds allowlist you push, not a sync visibleWhen. Renderer modules must not touch window.bifrost; they talk through postToRendererModule / onRendererModuleMessage. Do not share the DI name pluginChannel across renderer-module plugins.
DMN APIs target the DRD only. Modeling throws when the user is in a decision table; queries return empty. Re-subscribe on api.dmn.onViewChanged after drill-down.
Permissions, overlay types, palette/context pad, modeling, renderer injection: architecture/plugin-bpmn-enrichment.md, architecture/plugin-dmn-enrichment.md and architecture/plugin-landscape-enrichment.md.
Landscape maps (.bfwmap): api.landscape offers the same overlay, event, palette, context pad and modeling surface as the other editors. Overlays and factories cover the plane on screen; queries return every saved shape and user-drawn connector on the map. Request landscape for reading, landscape.modelling for edits and entries, landscape.renderer for diagram-js modules.
UI runs in a sandboxed <iframe> at bifrostfw-webview://<pluginName>/. Inside the iframe, acquireStudioApi() gives postMessage / onMessage / theme helpers. Register onMessage in activate() before the iframe mounts. Collapsed panes unmount the iframe. Ctrl+S inside the iframe does not reach the Studio — use onSaveRequest / a plugin command. Cross-plugin postMessage is blocked.
Protocol, CSP, and surfaces: architecture/webviews.md.
Theme tokens in CSS: var(--theme-*). Feel editors and PaneProperty from the SDK are webview-safe; host Icon / Table / Checkbox are not.
BFW_PLUGINS_DIR=/path/to/my-plugins npm startPlugins pane (left sidebar) → wrench → Enable / Disable / Uninstall. Disabled names live in plugins.disabledPlugins. Quarantine is not cleared by Disable — use Trust & Re-enable.
View > Console or plugins.showConsole. Timestamped stdout/stderr from the host child. Filter by plugin name and free text.
Refresh Plugin List restarts the host and re-discovers. Toggle a single plugin to reload only that one.
DevTools (Ctrl+Shift+I) inspects the renderer. Host output also appears under [PluginHost:stdout] / [PluginHost:stderr].
- Output: CommonJS (
format: 'cjs'), Node (platform: 'node') mainmust exportactivateanddeactivate
esbuild for the host bundle:
esbuild src/index.ts --bundle --platform=node --format=cjs --outfile=dist/index.js --external:cryptoWebview bundle is IIFE for the browser:
await build({
entryPoints: ['src/main.tsx'],
outfile: 'dist/main.js',
bundle: true,
format: 'iife',
target: 'es2020',
jsx: 'automatic',
});TypeScript:
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "bundler",
"strict": true,
"outDir": "dist",
"esModuleInterop": true
},
"include": ["src"]
}@elraptorus/bfw_studio_sdk is a devDependency for types (and optional webview-safe components). The StudioPluginApi instance is injected at runtime. Internal Studio modules type Bifrost from #bifrost/Bifrost, not Studio from the SDK.
You can find a number of example plugins in the Studio's Test Fixtures.