Synapse Framework — Plugin system

Plugins are unsandboxed JavaScript modules that extend the desktop app: UI overlays, routes, editor hooks, bridge providers, filesystem access, and more. They load app-wide on the main webview only — undocked V3 tabs and Script Hub secondary webviews skip plugin bootstrap.

This guide covers the generic plugin API. Vendor-specific bridge plugins (Cosmic API, Velocity API, etc.) are not documented here.

What plugins are

flowchart TB
  ZIP["Install ZIP"] --> Disk["plugins/{id}/"]
  Disk --> Registry["localStorage registry"]
  Registry --> Bootstrap["pluginHost.bootstrap()"]
  Bootstrap --> Activate["activate(host)"]
  Activate --> UI["Overlays / routes / hooks"]
  Activate --> Bridge["Optional bridge provider"]

On-disk layout

Plugins live under the Tauri app data directory:

{app_data}/plugins/{plugin_id}/
  plugin.synapse-plugin    # Required — manifest + JS body
  bin/                     # Optional — exe, dll, assets
  ...

• Root path: resolved by plugins_root() in src-tauri/src/plugins.rs
• Plugin IDs: alphanumeric, -, _ only
• Multi-file packs: any relative path under the plugin folder (ZIP install extracts the full tree)
• Path traversal (..) is rejected by plugins_resolve_path

File format

Each plugin is a single .synapse-plugin file (or plugin.synapse-plugin in a pack):

1. Manifest block — JSON inside a comment header
2. JavaScript body — plugin code with activate / deactivate exports

/* @synapse-plugin-manifest
{
  "format": "synapse-plugin",
  "formatVersion": 1,
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "Optional description",
  "permissions": {
    "ui": true,
    "nav": true
  }
}
*/

function activate(host) {
  host.log("activated");
}

function deactivate(host) {
  host.log("deactivated");
}

exports.activate = activate;
exports.deactivate = deactivate;

Parsing and serialization: src/app/synapse-v3/plugins/pluginFileFormat.ts

Registry

Enabled plugins and load order are stored in localStorage:

Enable / disable in the Plugins UI (setPluginEnabled in v3PluginRegistry.ts). Disabling a plugin writes a tombstone on disk (plugins_tombstone) so it does not reload until re-enabled.

Structural changes (new permissions, new routes, pack file updates) require Save and Restart Framework (host.restartFramework() or the Plugins page button).

Lifecycle

1. Install — plugins_install_zip extracts to plugins/{id}/
2. Enable — add to enabledIds in registry
3. Save — persist registry; may prompt restart
4. Restart Framework — reload webview; pluginHost.bootstrap() runs activate() for each enabled plugin
5. Disable — deactivate(), tombstone, remove from enabledIds
6. Delete — plugins_delete removes folder and registry entry

Permissions

Declared in the manifest permissions object. Each key gates a group of host APIs. full: true grants everything.

Source: src/app/synapse-v3/plugins/v3PluginTypes.ts

Host API reference

The host object passed to activate(host) is built in PluginHost.createHostApi(). Grouped by concern:

Tauri commands

Plugin management (permissions.tauri)

Process and data

Bridge-related (allowlisted)

Framework

Full-power extras (permissions.full)

Full list: PLUGIN_TAURI_COMMANDS and PLUGIN_TAURI_FULL_EXTRA in src/app/synapse-v3/plugins/pluginHostConstants.ts

UI overlay slots

Register components with host.registerOverlay(slot, Component):

Source: PLUGIN_UI_SLOTS in pluginHostConstants.ts

Multi-file packs and subprocesses

Packs: Install a ZIP containing plugin.synapse-plugin plus binaries, DLLs, configs, etc. Use host.resolvePluginPath("bin/my-tool.exe") to get absolute paths.

Subprocesses: spawnPluginProcess starts a singleton host process per plugin (src-tauri/src/plugin_process_host.rs). Communicate via pluginProcessRequest with JSON payloads. The Rust side enforces one process per plugin ID and cleans up on kill.

Typical pattern:

const { handle } = await host.spawnPluginProcess("bin/helper.exe", ["--mode", "server"]);
const result = await host.pluginProcessRequest(handle, { action: "ping" }, 5000);

Troubleshooting

Key source files

Related documentation

• EXECUTOR_BRIDGE.md — Port, Stream, Compat legacy bridge
• PROJECT_OVERVIEW.md — App architecture and module map