Getting started with plugins

Create and load your first Nuclear plugin and verify the SDK works end-to-end.

Spin up a bare plugin, load it in Nuclear, and poke the Plugin SDK to make sure everything is wired.

Plugins are folders on disk with a package.json and an entry file. The app loads them at runtime and provides @nuclearplayer/plugin-sdk to your code.

Usage

Create a folder anywhere on your machine, e.g. ~/nuclear-plugins/hello-plugin.

Run npm init inside.

{
  "name": "hello-plugin",
  "version": "0.1.0",
  "description": "Minimal Nuclear plugin",
  "author": "Your Name",
  "main": "index.ts",
  "nuclear": {
    "displayName": "Hello Plugin",
    "categories": ["other"]
  }
}

const CATEGORY = "Examples";

module.exports = {
  async onLoad(api) {
    await api.Settings.register([
      {
        id: "hello",
        title: "Hello world",
        category: CATEGORY,
        kind: "boolean",
        default: true
      }
    ]);

    const v = await api.Settings.get("hello");
    await api.Settings.set("hello", !v);
  },

  async onEnable(api) {
  api.Settings.subscribe("hello", () => {});
  }
};

The app compiles TS on the fly. No additional setup is needed.

Load it in the app

Open Nuclear → Preference → Plugins (from the left sidebar).
Click Add Plugin and select your plugin folder.
Toggle it on. onLoad runs at import time; onEnable runs when you enable.

Verify the SDK

Open Settings and find the "Examples" section. You should see "Hello world" with a toggle.
Flip it. The value persists to disk and updates subscribers.

Setting IDs are auto-namespaced. Use bare IDs like hello; the app stores them as plugin.<pluginId>.hello.

Plugin shape

type Plugin = {
  onLoad?(api: NuclearPluginAPI): void | Promise<void>;
  onEnable?(api: NuclearPluginAPI): void | Promise<void>;
  onDisable?(api: NuclearPluginAPI): void | Promise<void>;
  onUnload?(api: NuclearPluginAPI): void | Promise<void>;
};

package.json keys used by the loader:

name, version, description, author
main (optional). If missing, the app tries index.js, index.ts, index.tsx, then dist/index.*.
nuclear.displayName (optional UI name)
nuclear.categories (shown in the Plugins list)
nuclear.icon and nuclear.permissions (optional; unknown permissions get a warning)

PreviousMusic discovery NextPlugin system

Last updated 1 month ago