Merge pull request #2042 from nukeop/feat/plugin-auto-update

Feat/plugin auto update

Author: nukeop

packages/docs/plugins/getting-started.md

@@ -29,7 +29,7 @@ Run `npm init` inside.
   "main": "index.ts",
   "nuclear": {
     "displayName": "Hello Plugin",
-    "category": "Examples"
+    "categories": ["other"]
   }
 }
 ```
@@ -96,5 +96,5 @@ type Plugin = {
 * `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.categories` (shown in the Plugins list)
 * `nuclear.icon` and `nuclear.permissions` (optional; unknown permissions get a warning)

packages/docs/plugins/plugin-store.md

@@ -24,7 +24,7 @@ After installation, the plugin appears in the Installed tab. Toggle it on to ena
 
 You can also install plugins from a local folder. In the Installed tab, click "Add Plugin" and select a folder containing a plugin (a directory with a `package.json` and an entry file).
 
-Manually installed plugins have one extra feature: a reload button. Click it to re-read the plugin source from the original folder, recompile, and reload. This is useful during development. Store-installed plugins don't support reload; remove and reinstall to get a new version. Auto-update is planned for the future.
+Manually installed plugins have one extra feature: a reload button. Click it to re-read the plugin source from the original folder, recompile, and reload. This is useful during development. Store-installed plugins don't support reload; remove and reinstall to get a new version. Store plugins are updated automatically on startup (see Plugin updates below).
 
 ## Managing plugins
 
@@ -44,7 +44,11 @@ Dev plugins show a reload button that re-reads the source from the original fold
 
 ## Plugin updates
 
-There's no automatic update mechanism yet, but it's planned for the future. To update a store-installed plugin, remove it and reinstall from the store. Nuclear always fetches the latest GitHub release, so reinstalling picks up any new version the developer has published.
+Nuclear checks for updates when it starts. If a newer version is available in the registry and auto-update is enabled (the default), the update is downloaded and installed automatically. The old version's files remain on disk but the new version takes over.
+
+To disable auto-update, go to Settings and turn off "Auto-update plugins" under the Plugins section.
+
+Dev plugins are never auto-updated. To update a dev plugin, edit the source and click reload.
 
 ## Where plugins are stored
 

packages/docs/plugins/publishing.md

@@ -30,7 +30,7 @@ The `nuclear` field holds Nuclear-specific config:
 {
   "nuclear": {
     "displayName": "My Plugin",
-    "category": "metadata",
+    "categories": ["metadata"],
     "icon": {
       "type": "link",
       "link": "https://example.com/icon.png"
@@ -43,12 +43,12 @@ The `nuclear` field holds Nuclear-specific config:
 | Property | Required | Description |
 |----------|----------|-------------|
 | `displayName` | no | Human-readable name shown in the UI. Falls back to `name`. |
-| `category` | no | One of: `streaming`, `metadata`, `lyrics`, `scrobbling`, `dashboard`, `other`. Required for registry submission. |
+| `categories` | no | Array of categories. Valid values: `streaming`, `metadata`, `lyrics`, `scrobbling`, `dashboard`, `playlists`, `discovery`, `other`. Required for registry submission. |
 | `icon` | no | Plugin icon. Only `{"type": "link", "link": "url"}` is supported. |
 | `permissions` | no | Informational list. No permissions are enforced yet; this is for future use. |
 
 {% hint style="info" %}
-Categories are convenience tags for filtering in the store. Pick the one that best describes your plugin's primary function.
+A plugin can belong to multiple categories. Pick all that apply based on the provider types your plugin registers.
 {% endhint %}
 
 ### Full example
@@ -63,7 +63,7 @@ Categories are convenience tags for filtering in the store. Pick the one that be
   "main": "dist/index.js",
   "nuclear": {
     "displayName": "Discogs",
-    "category": "metadata"
+    "categories": ["metadata"]
   }
 }
 ```
@@ -113,7 +113,10 @@ Set up CI to build and create the release automatically. Manual zip creation is
   "author": "nukeop",
   "repo": "NuclearPlayer/nuclear-plugin-discogs",
   "category": "metadata",
+  "categories": ["metadata"],
   "tags": ["discogs", "metadata"],
+  "version": "1.0.0",
+  "downloadUrl": "https://github.com/NuclearPlayer/nuclear-plugin-discogs/releases/download/v1.0.0/plugin.zip",
   "addedAt": "2026-01-25T00:00:00Z"
 }
 ```
@@ -130,7 +133,10 @@ Set up CI to build and create the release automatically. Manual zip creation is
 | `author` | yes | 1-64 chars. |
 | `repo` | yes | `owner/repo-name` format. |
 | `category` | yes | Must match your `package.json` `nuclear.category`. |
+| `categories` | yes | Array of categories matching your plugin's provider types. Same valid values as `nuclear.categories` in package.json. |
 | `tags` | no | Up to 10 tags, lowercase with hyphens, unique. |
+| `version` | no | Latest released semver version. Populated automatically by CI. |
+| `downloadUrl` | no | Direct URL to the latest `plugin.zip`. Populated automatically by CI. |
 | `addedAt` | yes | ISO 8601 datetime (e.g., `2026-01-25T00:00:00Z`). |
 
 ---
@@ -142,7 +148,7 @@ You don't need to update the registry to release new versions. Create a new GitH
 Only submit a registry PR if you need to change the plugin's metadata (description, category, tags, etc.).
 
 {% hint style="info" %}
-There is no automatic update push to users who already have your plugin installed. They need to remove and reinstall to get the latest version.
+Nuclear checks for plugin updates on startup. If auto-update is enabled (it is by default), installed store plugins are automatically updated to the latest version. Users can disable this in Settings under Plugins.
 {% endhint %}
 
 ## Examples

packages/i18n/src/locales/en_US.json

@@ -219,7 +219,9 @@
     "installed": {
       "empty-state": "No plugins installed",
       "empty-state-description": "Browse the plugin store to find streaming, metadata, and other plugins.",
-      "empty-state-action": "Go to store"
+      "empty-state-action": "Go to store",
+      "update-available": "Update available",
+      "by": "by"
     },
     "store": {
       "searchPlaceholder": "Search plugins...",
@@ -233,6 +235,9 @@
         "metadata": "Metadata",
         "lyrics": "Lyrics",
         "scrobbling": "Scrobbling",
+        "dashboard": "Dashboard",
+        "playlists": "Playlists",
+        "discovery": "Discovery",
         "other": "Other"
       },
       "error": {
@@ -270,7 +275,11 @@
       }
     },
     "plugins": {
-      "title": "Plugins"
+      "title": "Plugins",
+      "auto-update": {
+        "title": "Auto-update plugins",
+        "description": "Automatically download and install new versions of store plugins on startup"
+      }
     },
     "themes": {
       "title": "Themes"

packages/player/package.json

@@ -53,6 +53,7 @@
     "react-i18next": "^16.0.0",
     "react-icons": "^5.6.0",
     "react-inspector": "9.0.0",
+    "semver": "^7.7.4",
     "sonner": "^2.0.7",
     "uuid": "^13.0.0",
     "zod": "^4.0.0",
@@ -69,6 +70,7 @@
     "@types/lodash-es": "^4.17.12",
     "@types/react": "^18.3.23",
     "@types/react-dom": "^18.3.7",
+    "@types/semver": "^7.7.1",
     "@types/uuid": "^11.0.0",
     "@typescript-eslint/eslint-plugin": "^8.57.0",
     "@typescript-eslint/parser": "^8.57.0",

packages/player/src/App.hydration.test.tsx

@@ -5,7 +5,7 @@ import { usePluginStore } from './stores/pluginStore';
 import { useStartupStore } from './stores/startupStore';
 import { PluginFsMock } from './test/mocks/plugin-fs';
 import { resetInMemoryTauriStore } from './test/utils/inMemoryTauriStore';
-import { seedRegistryEntry } from './test/utils/seedPluginRegistry';
+import { seedRegistryEntry } from './test/utils/seedPlugins';
 import { createPluginFolder } from './test/utils/testPluginFolder';
 import { PluginsWrapper } from './views/Plugins/Plugins.test-wrapper';
 

packages/player/src/apis/pluginMarketplaceApi.ts

@@ -2,22 +2,30 @@ import { z } from 'zod';
 
 import { ApiClient } from './ApiClient';
 
+const PluginCategorySchema = z.enum([
+  'streaming',
+  'metadata',
+  'lyrics',
+  'scrobbling',
+  'dashboard',
+  'playlists',
+  'discovery',
+  'other',
+]);
+
 const MarketplacePluginSchema = z.object({
   id: z.string().min(1),
   name: z.string().min(1),
   description: z.string(),
   author: z.string().min(1),
   repo: z.string().regex(/^[^/]+\/[^/]+$/),
-  category: z.enum([
-    'streaming',
-    'metadata',
-    'lyrics',
-    'scrobbling',
-    'dashboard',
-    'other',
-  ]),
+  // TODO: Remove category after registry migration to categories
+  category: PluginCategorySchema.optional(),
+  categories: z.array(PluginCategorySchema).optional(),
   tags: z.array(z.string()).optional(),
-  addedAt: z.string().datetime(),
+  version: z.string().min(1).optional(),
+  downloadUrl: z.url().optional(),
+  addedAt: z.iso.datetime(),
 });
 
 const RegistrySchema = z.object({

packages/player/src/services/coreSettings.ts

@@ -208,6 +208,15 @@ export const CORE_SETTINGS: SettingDefinition[] = [
     default: false,
     widget: { type: 'toggle' },
   },
+  {
+    id: 'plugins.autoUpdate',
+    title: 'preferences.plugins.auto-update.title',
+    description: 'preferences.plugins.auto-update.description',
+    category: 'plugins',
+    kind: 'boolean',
+    default: true,
+    widget: { type: 'toggle' },
+  },
   {
     id: 'integrations.mcp.enabled',
     title: 'preferences.integrations.mcp.enabled.title',

packages/player/src/services/plugins/PluginLoader.ts

@@ -59,6 +59,7 @@ export class PluginLoader {
       description: manifest.description,
       author: manifest.author,
       category: manifest.nuclear?.category,
+      categories: manifest.nuclear?.categories ?? [],
       icon: manifest.nuclear?.icon,
       permissions: manifest.nuclear?.permissions || [],
     };