Plugins

Every Zenbu.js application is itself a plugin. Your app is defined with definePlugin() the same way any third-party extension would be, and it has the same capabilities. The only thing that makes the main application special is the uiEntrypoint in defineConfig(), which tells the framework which plugin’s code to load in the renderer process first.

Defining a plugin

Plugins are declared with definePlugin() from @zenbujs/core/config:

zenbu.config.ts

import { defineConfig, definePlugin } from "@zenbujs/core/config"

export default defineConfig({
  db: "./.zenbu/db",
  uiEntrypoint: "./src/renderer",
  plugins: [
    definePlugin({
      name: "app",
      services: ["./src/main/services/*.ts"],
      schema: "./src/main/schema.ts",
      events: "./src/main/events.ts",
      migrations: "./migrations",
      icons: {
        "my-view": '<svg ...>...</svg>',
      },
    }),
  ],
})

Field	Required	Description
name	yes	Unique plugin identifier. Used as the top-level namespace for the plugin’s database section, RPC services, and events (e.g. db.<name>, rpc.<name>.<service>, events.<name>.<event>). Reserved value: core belongs to the framework.
services	yes	Glob patterns for main process service files.
schema	no	Path to the database schema definition.
events	no	Path to event type definitions.
migrations	no	Directory of generated migration files.
preload	no	Path to a renderer preload module.
icons	no	Map of inline SVG strings keyed by injection name. When you call this.inject({ name }) and a matching key exists, the framework copies the SVG into meta.icon for you. Lookup is per-plugin (no cross-plugin fallback).
dependsOn	no	Declares which other plugins this plugin needs type definitions from. See Type dependencies.

Scaffolding a plugin

create-zenbu-app can scaffold a plugin folder from anywhere on disk:

pnpm create zenbu-app --plugin my-plugin

Flag	Description
--plugin	Use the plugin template instead of the app template. Skips app-only prompts (Tailwind, build config).
--no-add-to-host	Skip the interactive prompt that offers to add the new plugin to each upstream host’s plugins: array.
--no-git	Skip the git init prompt. Git init is auto-skipped when an ancestor already has a .git/.
--yes / -y	Auto-confirm every prompt with the default.

The command scaffolds the plugin folder and installs its dependencies.

Adding a plugin

Plugins can be inlined with definePlugin() or referenced by path to a zenbu.plugin.ts file:

plugins: [
  definePlugin({ name: "app", services: ["./src/main/services/*.ts"] }),
  "./plugins/devtools/zenbu.plugin.ts",
]

Adding or removing a plugin in zenbu.config.ts is a hot-reloadable change that takes effect without restarting the app.

Local-only plugins (localPlugins)

A zenbu.config.ts can opt into a per-developer overlay file that’s gitignored and loaded only if it exists. Use this when you want to wire a local plugin (e.g. one cloned into ~/.zenbu/plugins/...) into your app without committing the path:

export default defineConfig({
  uiEntrypoint: "./src/renderer",
  plugins: [
    "./plugins/app/zenbu.plugin.ts",
  ],
  localPlugins: "./zenbu.local.ts", // gitignored; optional
})

zenbu.local.ts

import type { LocalPluginsDefault } from "@zenbujs/core/config"

const plugins: LocalPluginsDefault = [
  "/Users/me/.zenbu/plugins/the-browser-plugin/zenbu.plugin.ts",
  // or an inline definePlugin({...})
]
export default plugins

Rules:

• The default export is a plugin entry, or an array of entries. Same shape as plugins.
• Relative paths inside the overlay anchor to the overlay file’s directory, not the project root.
• localPlugins accepts a single string or an array of strings (multiple overlays).
• If the overlay file doesn’t exist, the field is silently ignored.
• Editing the overlay file hot-reloads exactly like editing zenbu.config.ts.
• zen build:source / zen build:electron / zen publish:source skip localPlugins entirely, so a developer’s overlay can never ship in a build artefact.

Plugin capabilities

A plugin has the same capabilities as the host application:

• Services run in the main process and expose methods via RPC.
• Database schemas define sections of the shared database.
• Events can be emitted and listened to across plugins.
• Injections are the unified renderer-side surface. One primitive (this.inject(...) / useRegisterInjection(...)) covers React components other plugins can render via <View>, plain side-effect modules (the old “content script” pattern), plain functions/values, and advice (sugar for wrapping or replacing an existing export).

Type dependencies

If a plugin needs to call another plugin’s RPC methods, read its database, or subscribe to its events, it needs that plugin’s type definitions. You declare this with dependsOn:

zenbu.plugin.ts

import { definePlugin } from "@zenbujs/core/config"

export default definePlugin({
  name: "devtools",
  services: ["./src/main/services/*.ts"],
  dependsOn: [
    { name: "app", from: "../../zenbu.config.ts" },
  ],
})

name is the plugin you depend on, and from is the path to the file that defines it. With this in place, you get typed access to that plugin’s API:

// Read app's database
const count = useDb(root => root.app.count)

// Call app's RPC methods
const rpc = useRpc()
await rpc.app.counter.increment()

// Subscribe to app's events
events.app.notification.subscribe(data => { ... })

This is a type-only dependency. dependsOn tells zen link where to find the other plugin’s service, schema, and event definitions so it can generate TypeScript types under <plugin>/.zenbu/types/. The generated files are import type pointers to the actual source on disk, and the entire .zenbu/types/ directory is gitignored.

zen link runs automatically inside zen dev. Outside dev, run it manually before typechecking:

zen link