Skip to main content

​
What are managers?

plugins and themes are the two addon managers. Each one runs every addon of its kind through the same lifecycle: load the bundle, run it, persist whether it’s enabled, and tear it down. Both extend the same base addon manager and behave the same way, except in one step: how a raw bundle becomes a running instance. They’re available as unbound.plugins and unbound.themes, and you can import them from @unbound-app/api.

​
The addon lifecycle

Every addon goes through the same stages. The key distinction is between two kinds of state:
  • Runtime: starting and stopping control whether the addon is running right now.
  • Intent: enabling and disabling control whether it should run. This is a persisted preference, restored on the next launch.

Load

The manager takes in the bundle and manifest. If the addon’s persisted state is enabled, it starts right away.

Start / Stop

Runtime state. start turns the bundle into an instance and runs it. stop tears that instance down. This isn’t persisted; it only tracks whether the addon is running in this session.

Enable / Disable / Toggle

Intent state. enable saves the addon as on and starts it. disable saves it as off and stops it. toggle switches between the two. This is the state that survives a reload.

Unload

The addon is removed from the manager. If it’s running, it stops first.
Because enabled-state is persisted, the manager restores it on launch: an enabled addon starts automatically during Load. This is the reason intent and runtime are kept separate.

​
Manifests & validation

Every addon ships a manifest that describes it. The manager validates the manifest before loading and rejects the addon if any required field is missing or undefined. The shared schema covers id, name, description, authors, version, and main, plus the optional icon, updates, and url. It’s documented on one page:

The manifest

The shared addon manifest schema and validation rules.

​
Events & state

Managers are event emitters. Subscribe to lifecycle events to react when addons change:
  • loaded, unloaded
  • started, stopped
  • enabled, disabled, toggled
  • reloaded
Enabled-state is persisted through storage, which is how it’s restored on the next launch.

​
Plugins vs themes

Plugins and themes share the lifecycle. The only difference is what handleBundle does with a bundle:
  • Plugins eval their bundle into a running instance with start/stop hooks.
  • Themes parse their bundle as JSON and drive the theme store, which applies the selected theme’s colors.
Everything else is shared: loading, validation, enable/disable, persistence, and events.