Getting started

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.

Quick start

1) Folder

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

Run npm init inside.

2) package.json

3) index.ts

Load it in the app

1. Open Nuclear → Preference → Plugins (from the left sidebar).

2. Click Add Plugin and select your plugin folder.

3. 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?(): void | Promise<void>;
  onUnload?(): 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.category (shown in the Plugins list)

• nuclear.icon and nuclear.permissions (optional; unknown permissions get a warning)

Common checks

Symptom	Cause	Fix
Plugin not listed after Add	Missing/invalid package.json	Ensure required fields and a resolvable entry file
"Plugin must export a default object"	Entry doesn’t default-export an object	Export module.exports = { ... } or export default { ... }
"Module X not found"	Importing unsupported dependency	Only @nuclearplayer/plugin-sdk is provided; bundle or avoid other deps
Setting doesn’t appear	Not registered	Call api.Settings.register([...]) in onLoad

Next steps

• Use the Settings guide to define richer options.

• Add a real feature under onEnable, and store user prefs with the Settings API.