api.registry

Low-level plugin registry access

Overview

api.registry provides low-level access to the plugin registry. Primarily used by the Plugin Manager.

Registry Methods

registry.getAll()

Returns a deep copy of the registry array.

const plugins = api.registry.getAll();
// → [{ id: 'hello', name: 'Hello Box', enabled: true, ... }, ...]

Returns: Array<PluginDefinition>

interface PluginDefinition {
  id: string;
  name: string;
  url: string;
  enabled: boolean;
  source?: 'system' | 'registry' | 'manual';  // How the plugin was installed
  icon?: string;                                // Emoji icon
  author?: string;                              // Plugin author
}

registry.get(id)

Returns a single plugin definition by ID (shallow copy), or null if not found.

const plugin = api.registry.get('my-plugin');
// → { id: 'my-plugin', name: 'My Plugin', enabled: true, ... }

Parameter	Type	Description
id	string	Plugin ID

Returns: PluginDefinition | null

registry.save(newRegistry)

Overwrites the entire registry and persists to localStorage.

const plugins = api.registry.getAll();
plugins.push({ id: 'new', name: 'New', url: './new.js', enabled: true });
api.registry.save(plugins);

Management Methods

These are attached directly to api (not api.registry):

api.installPlugin(id, url, name)

Install a plugin from URL. Validates the URL format and checks for duplicate IDs.

await api.installPlugin(
  'my-plugin',
  'https://raw.githubusercontent.com/user/repo/main/plugin.js',
  'My Plugin'
);

Parameter	Type	Description
id	string	Unique plugin ID
url	string	URL to the .js file (must end with .js, must be http(s)://)
name	string	Display name (defaults to id)

Returns: Promise<boolean> — true if installed, false if ID already exists

Plugins installed via installPlugin get source: 'manual'. The core will show a warning notification when loading manual plugins.

api.togglePlugin(id)

Enable or disable a plugin. Loads the plugin if disabled, unloads if enabled.

await api.togglePlugin('my-plugin');

Parameter	Type	Description
id	string	Plugin ID

Returns: Promise<boolean> — true if successful, false if not found

api.deletePlugin(id)

Permanently remove a plugin. Unloads it first, then removes from registry.

api.deletePlugin('my-plugin');

Parameter	Type	Description
id	string	Plugin ID

Returns: boolean — true if successful, false if not found

api.reloadPlugin(id)

Unload and reload a single plugin without restarting the whole board.

await api.reloadPlugin('my-plugin');

Parameter	Type	Description
id	string	Plugin ID

Returns: Promise<boolean> — true if successful, false if not found

Use reloadPlugin during plugin development to test changes without restarting the entire board.

api.restart()

Unload all plugins, then reload all enabled plugins from the registry.

await api.restart();
// All plugins are torn down and re-initialized

Emits: board:restarted event after completion.

restart() is useful after bulk registry changes or when you need a clean slate.

Plugin ID

api.getPluginId()

Returns the ID of the currently loading plugin. Only has a value while a plugin’s setup() is executing.

export function setup(api) {
  console.log(api.getPluginId());  // → 'my-plugin'
}

Returns: string | null