Nuclear Plugin SDK

Build plugins for Nuclear music player.

Plugins are JavaScript/TypeScript modules that extend Nuclear's functionality. Write lifecycle hooks, register providers, and ship it as an npm package or local bundle.

Quick Start

mkdir my-plugin && cd my-plugin
pnpm init -y
pnpm add @nuclearplayer/plugin-sdk

Create src/index.ts:

import { NuclearPluginAPI } from '@nuclearplayer/plugin-sdk';

export default {
  async onLoad(api: NuclearPluginAPI) {
    console.log('Plugin loaded');
  },
  async onEnable(api: NuclearPluginAPI) {
    console.log('Plugin enabled');
  },
  async onDisable() {
    console.log('Plugin disabled');
  },
  async onUnload() {
    console.log('Plugin unloaded');
  },
};

Build it to dist/index.js as a CommonJS bundle.

Manifest (package.json)

Required fields

• name - Unique plugin ID (scoped names allowed)
• version - Semver version
• description - One-line summary
• author - Your name

Optional fields

• main - Entry file path (defaults to index.js or dist/index.js)

Nuclear-specific config

Add a nuclear object for extra metadata:

• displayName - Friendly name (defaults to name)
• category - Arbitrary grouping (e.g., source, integration, lyrics)
• icon - See below
• permissions - Capabilities your plugin uses (informational only for now)

{
  "name": "@nuclear-plugin/lastfm",
  "version": "0.1.0",
  "description": "Scrobble tracks to Last.fm",
  "author": "Nuclear Team",
  "main": "dist/index.js",
  "nuclear": {
    "displayName": "Last.fm Scrobbler",
    "category": "integration",
    "icon": { "type": "link", "link": "https://example.com/icon.png" },
    "permissions": ["scrobble", "network"]
  }
}

Icons

type PluginIcon = { type: 'link'; link: string };

Link icons should point to a local file path or remote URL; keep them small (<= 64x64, optimized).

Lifecycle Hooks

All hooks are optional. Export a default object with any of:

• onLoad(api) - Runs after plugin code loads and manifest is parsed
• onEnable(api) - Runs when user enables the plugin
• onDisable() - Runs when user disables it
• onUnload() - Runs before plugin is removed from memory

export default {
  async onLoad(api) {
  },
  async onEnable(api) {
  },
  async onDisable() {
  },
  async onUnload() {
  },
};

Permissions

Declare what your plugin does in the permissions array. Permissions are currently informational. Future versions might show UI for this.

Examples: network, scrobble, playback-control, lyrics, search, storage

File Structure

my-plugin/
  package.json
  src/
    index.ts
  dist/
    index.js

Building

You can use any bundler that outputs a single JS file. Your bundle needs to work in a CommonJS environment (module.exports or exports.default).

Example with tsup:

{
  "devDependencies": { "tsup": "^8" },
  "scripts": { "build": "tsup src/index.ts --dts --format cjs --minify --out-dir dist" }
}

Run pnpm build and you'll get dist/index.js.

Development

1. Create your plugin folder
2. Build to produce the entry file
3. Load it in Nuclear
4. Rebuild after changes; you'll need to reload the plugin

Tips

• Keep startup fast, defer heavy work to onEnable
• Validate network responses
• Minimize dependencies, smaller = faster

Troubleshooting

| Problem | Solution | |---------|----------| | Can't find entry file | Check main in package.json or make sure index.js or dist/index.js exists | | Missing fields error | Add all required fields: name, version, description, author | | Hooks don't fire | Export a default object, not a function or class |

Types

import type {
  NuclearPlugin,
  PluginManifest,
  PluginIcon,
  // Model types (re-exported from @nuclearplayer/model)
  Artist,
  Album,
  Track,
  // ... and many more
} from '@nuclearplayer/plugin-sdk';

License

AGPL-3.0-only