@spicetify/kit 0.3.1 → 0.4.0

package/README.md

@@ -0,0 +1,82 @@
+# @spicetify/kit
+
+The developer kit for [Spicetify](https://spicetify.app) v3 modules. It scaffolds a module, builds it, and hot-pushes every save into a running Spotify client.
+
+## Requirements
+
+- Node 22.6 or newer.
+- Spotify with Spicetify v3 applied (`spicetify apply`). The kit pushes into the client the Spicetify CLI has patched, so a stock Spotify cannot load a pushed module.
+- The standalone Spotify install. The Microsoft Store build cannot be started with a debug port.
+
+## Start a module
+
+```sh
+npm create spicetify-module my-module
+cd my-module
+npm install
+npm run dev
+```
+
+`npm run dev` starts Spotify with a remote debugging port, or reuses a client already running with one. It then rebuilds on every save and pushes the build into the client in about a second, with no re-apply and no restart. Stop it with ctrl-c, which removes the pushed copy so Spotify goes back to whatever version of the module is installed.
+
+Pick a template with `--template`:
+
+| Template          | What you get                            |
+| ----------------- | --------------------------------------- |
+| `basic` (default) | a topbar button that opens a page       |
+| `extension`       | behaviour only, with no UI              |
+| `app`             | a sidebar entry and a full page         |
+| `theme`           | CSS and `color.ini` only, no TypeScript |
+
+## Scripts in a scaffolded project
+
+| Script           | What it does                                                                                                                         |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `npm run dev`    | start Spotify, then rebuild and hot-push on every save                                                                               |
+| `npm run build`  | build once into `dist/`                                                                                                              |
+| `npm run check`  | typecheck and audit the module against the [module standard](https://github.com/spicetify/modules/blob/main/docs/module-standard.md) |
+| `npm test`       | run the unit tests in `test/`                                                                                                        |
+| `npm run remove` | remove a pushed copy that is still installed in the client                                                                           |
+
+`dev` flags go after `--`, for example `npm run dev -- --keep`:
+
+| Flag          | Effect                                                                    |
+| ------------- | ------------------------------------------------------------------------- |
+| `--keep`      | leave the pushed copy installed when `dev` stops                          |
+| `--once`      | build and push once, then exit; the pushed copy stays                     |
+| `--no-launch` | do not start Spotify; wait for one started with `--remote-debugging-port` |
+| `--port <n>`  | use another debug port (default 9229, or `SPICETIFY_CDP_PORT`)            |
+
+## Troubleshooting
+
+**"port 9229 is already in use by ..., not Spotify"**: Node's inspector also defaults to 9229, so `node --inspect` or `wrangler dev` can hold it. Stop that process, or use another port with `npm run dev -- --port 9230`.
+
+**"the v3 loader is not staged in this client"**: Spotify is running without Spicetify v3. Run `spicetify apply`, then start `dev` again.
+
+**The UI still shows the old build**: a surface that was already on screen keeps the old code until it remounts. Navigate away from it and back.
+
+## Commands
+
+`spicetify-kit <command> --help` prints each command's flags.
+
+| Command                | What it does                                                   |
+| ---------------------- | -------------------------------------------------------------- |
+| `create <name>`        | scaffold a module project                                      |
+| `dev <module>`         | watch, rebuild, and hot-push into Spotify                      |
+| `build [module...]`    | bundle modules into `dist/`                                    |
+| `check [module]`       | audit a module against the module standard                     |
+| `remove <dir\|id>`     | remove a pushed copy from the running client                   |
+| `install <zip\|dir>`   | push a packed or built module into the running client once     |
+| `pack <dist-dir>`      | zip a built module and print its sha256                        |
+| `vault add <dist-dir>` | write the store registry entry for a release                   |
+| `from-theme <dir>`     | convert a classic `user.css` and `color.ini` theme to a module |
+
+## Learn more
+
+- [Building a module](https://github.com/spicetify/docs/blob/v3/src/content/docs/development/building-a-module.md)
+- [Authoring guide](https://github.com/spicetify/modules/blob/main/docs/authoring-guide.md)
+- [Publishing to the store](https://github.com/spicetify/modules/blob/main/docs/publishing.md)
+
+## License
+
+GPL-3.0-or-later

package/dist/args.js

@@ -0,0 +1,15 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+// flagValue returns the operand of --<name>, undefined when the flag is
+// absent, and throws when the flag is present without an operand.
+export function flagValue(argv, name) {
+    const i = argv.indexOf(`--${name}`);
+    if (i < 0)
+        return undefined;
+    const value = argv[i + 1];
+    if (value === undefined || value.startsWith("--"))
+        throw new Error(`--${name} needs a value`);
+    return value;
+}

package/dist/cli.js

@@ -10,10 +10,11 @@ usage: spicetify-kit <command> [args]
   check [module]     audit a module against the module standard (advisory)
   from-theme <dir>   migrate a classic theme (user.css + color.ini) to a module
   build [module...]  bundle modules (rolldown + scss) into dist/
-  dev <module>       watch, rebuild, and hot-push into a running client
+  dev <module>       watch, rebuild, and hot-push into Spotify (starts it if needed)
   pack <dist-dir>    zip a built module and print its sha256
   vault add <dir>    record a built module into a vault file (--artifact <url>)
   install <zip|dir>  sideload a packed module into a running client
+  remove <dir|id>    drop a hot-pushed override from a running client
 
 run a command with --help for its flags`;
 export async function main(argv) {
@@ -36,6 +37,8 @@ export async function main(argv) {
                 return await (await import("./vault.js")).runVault(rest);
             case "install":
                 return await (await import("./install.js")).runInstall(rest);
+            case "remove":
+                return await (await import("./remove.js")).runRemove(rest);
             case undefined:
             case "--help":
             case "-h":

package/dist/create.js

@@ -267,6 +267,7 @@ notification       = 1C1C30
             scripts: {
                 build: "spicetify-kit build .",
                 dev: "spicetify-kit dev .",
+                remove: "spicetify-kit remove .",
                 check: "spicetify-kit check .",
             },
             devDependencies: { "@spicetify/kit": KIT_DEPENDENCY_RANGE },
@@ -281,7 +282,7 @@ notification       = 1C1C30
     if (!bare) {
         console.log("next steps:");
         console.log(`  cd ${rel} && npm install`);
-        console.log("  npm run dev        # hot-push into a running client");
+        console.log("  npm run dev        # start Spotify, then rebuild and hot-push on every save");
     }
 }
 export async function runCreate(argv, cwd = process.cwd()) {
@@ -369,6 +370,7 @@ export async function load(ctx: ModuleRuntimeContext) {
             scripts: {
                 build: "spicetify-kit build .",
                 dev: "spicetify-kit dev .",
+                remove: "spicetify-kit remove .",
                 check: "tsc && spicetify-kit check .",
                 test: 'node --test "test/*.test.mts"',
             },
@@ -392,7 +394,7 @@ export async function load(ctx: ModuleRuntimeContext) {
                 noEmit: true,
                 jsx: "react-jsx",
                 lib: ["ES2024", "ESNext.Disposable", "DOM", "DOM.Iterable"],
-                strict: false,
+                strict: true,
                 skipLibCheck: true,
                 resolveJsonModule: true,
                 types: [],
@@ -417,12 +419,14 @@ export async function load(ctx: ModuleRuntimeContext) {
     console.log(`created ${rel}/`);
     console.log("next steps:");
     if (bare) {
-        console.log(`  node scripts/stitch.ts modules/${name}     # one-off build into dist/`);
-        console.log(`  node scripts/dev.ts modules/${name}        # watch + hot-push into a running client`);
+        console.log(`  pnpm stitch modules/${name}     # one-off build into dist/`);
+        console.log(`  pnpm dev modules/${name}        # start Spotify, then rebuild and hot-push on every save`);
     }
     else {
         console.log(`  cd ${rel} && npm install`);
-        console.log("  npm run dev        # watch + hot-push into a running client (Spotify started with --remote-debugging-port=9229)");
+        console.log("  npm run dev        # start Spotify, then rebuild and hot-push on every save");
         console.log("  npm run build      # one-off build into dist/");
+        console.log("stopping dev removes the pushed override; `npm run dev -- --keep` leaves it installed.");
+        console.log("Spotify needs Spicetify v3 applied (`spicetify apply`) for the push to land.");
     }
 }

package/dist/dev.js

@@ -9,32 +9,55 @@
  * fresh bundle over the Chrome DevTools Protocol as a local install
  * (Spicetify.Modules.installLocal), so nothing in the staged app bundle
  * is touched and the loop is sub-second. Spotify must be running with
- * --remote-debugging-port=<port>. Remove the override afterwards with
- * Spicetify.Modules.removeLocal("<name>") (or from the manager page) to
- * fall back to the staged copy.
+ * --remote-debugging-port=<port>; dev starts (or reuses) such a client unless
+ * --no-launch is passed. Stopping dev removes the override so the client falls
+ * back to the staged copy; --keep (and --once) leave it installed, and
+ * `spicetify-kit remove` drops it later.
  */
 import { watch } from "node:fs";
 import path from "node:path";
+import { flagValue } from "./args.js";
 import { buildModule, readMetadata, resolveModuleDir } from "./build.js";
 import { loadConfig, resolveClassmap } from "./classmap.js";
-import { launchSpotify } from "./launch.js";
-import { formatPushResult, push, record } from "./push.js";
+import { launchSpotify, waitForTarget } from "./launch.js";
+import { formatPushResult, formatRemoveOutcome, push, record, removeLocal, resolvePort } from "./push.js";
 // Re-exported for callers that imported it from here before the push extraction.
 export { formatPushResult } from "./push.js";
-const USAGE = "spicetify-kit dev <module> [--launch] [--port 9229] [--once] [--classmap <key|path>] [--out <dir>]\n" +
-    "  --launch   start (or reuse) Spotify with the remote-debugging port itself";
+const USAGE = `spicetify-kit dev <module> [--no-launch] [--keep] [--once] [--port 9229] [--classmap <key|path>] [--out <dir>]
+  --no-launch  do not start Spotify; wait for one already running with --remote-debugging-port
+  --keep       leave the pushed override installed when dev stops
+  --once       build and push once, then exit (the override stays)
+  --port       CDP port (default 9229, or SPICETIFY_CDP_PORT)`;
+// isSourceChange filters watcher events down to module sources. A standalone
+// project's module dir is the project root, so the build's own dist/ output,
+// node_modules, and dot-dirs all sit inside the watched tree.
+export function isSourceChange(file, moduleDir, outDir) {
+    const segments = file.split(/[\\/]/);
+    if (segments.some((s) => s.startsWith(".") || s === "node_modules"))
+        return false;
+    const rel = path.relative(outDir, path.resolve(moduleDir, file));
+    return rel.startsWith("..") || path.isAbsolute(rel);
+}
 export async function runDev(argv, cwd = process.cwd()) {
-    const moduleArg = argv.find((a) => !a.startsWith("--"));
-    const flag = (n) => {
-        const i = argv.indexOf(`--${n}`);
-        return i >= 0 ? argv[i + 1] : undefined;
-    };
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(USAGE);
+        return;
+    }
+    const valueFlags = new Set(["--port", "--classmap", "--out"]);
+    const moduleArg = argv.find((a, i) => !a.startsWith("--") && !valueFlags.has(argv[i - 1]));
+    const flag = (n) => flagValue(argv, n);
     if (!moduleArg)
         throw new Error(USAGE);
-    const port = flag("port") ?? "9229";
+    const port = resolvePort(flag("port"));
     const once = argv.includes("--once");
-    if (argv.includes("--launch"))
+    const keep = once || argv.includes("--keep");
+    if (argv.includes("--no-launch")) {
+        console.log(`[dev] waiting for Spotify on port ${port} (started with --remote-debugging-port=${port})`);
+        await waitForTarget(port, Number.POSITIVE_INFINITY);
+    }
+    else {
         await launchSpotify(port);
+    }
     const config = loadConfig(cwd);
     const modulesDir = config.modulesDir ? path.resolve(cwd, config.modulesDir) : path.join(cwd, "modules");
     const outDir = flag("out") ?? (config.outDir ? path.resolve(cwd, config.outDir) : path.join(cwd, "dist"));
@@ -48,7 +71,11 @@ export async function runDev(argv, cwd = process.cwd()) {
     });
     if (!resolved.path)
         throw new Error("no classmap found (pass --classmap <key|path>)");
+    let pushed = false;
+    let stopping = false;
     const cycle = async () => {
+        if (stopping)
+            return;
         const started = Date.now();
         let distDir;
         try {
@@ -59,8 +86,13 @@ export async function runDev(argv, cwd = process.cwd()) {
             console.error(`[dev] build failed: ${e.message}`);
             return;
         }
+        if (stopping)
+            return;
         try {
-            const raw = await push(record(distDir, id), id, port);
+            const pending = push(record(distDir, id), id, port);
+            // Set before the await: a ctrl-c mid-push must still remove what lands.
+            pushed = true;
+            const raw = await pending;
             const result = formatPushResult(raw);
             const line = `[dev] ${id} ${result.message} (${Date.now() - started}ms)`;
             if (result.ok)
@@ -72,13 +104,39 @@ export async function runDev(argv, cwd = process.cwd()) {
             console.error(`[dev] push failed: ${e.message}`);
         }
     };
-    await cycle();
-    if (once)
-        return;
-    console.log(`[dev] watching ${moduleDir} (ctrl-c to stop; removeLocal("${id}") drops the override)`);
+    let current = Promise.resolve();
     let timer;
+    const stop = async (code = 0) => {
+        if (stopping)
+            process.exit(130);
+        stopping = true;
+        clearTimeout(timer);
+        await current;
+        if (keep || !pushed)
+            process.exit(code);
+        try {
+            console.log(`[dev] ${formatRemoveOutcome(id, await removeLocal(id, port))}`);
+        }
+        catch (e) {
+            console.error(`[dev] could not remove the override: ${e.message}`);
+            console.error(`[dev] run \`spicetify-kit remove ${id}\` once Spotify is reachable`);
+        }
+        process.exit(code);
+    };
+    const onSignal = () => void stop();
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+    current = cycle();
+    await current;
+    if (once) {
+        process.off("SIGINT", onSignal);
+        process.off("SIGTERM", onSignal);
+        return;
+    }
+    const onExit = keep ? "the override stays installed" : "the override is removed";
+    console.log(`[dev] watching ${moduleDir} (ctrl-c to stop; ${onExit})`);
     let loggedDts = false;
-    watch(moduleDir, { recursive: true }, (_event, file) => {
+    const watcher = watch(moduleDir, { recursive: true }, (_event, file) => {
         if (!file)
             return;
         // The build regenerates classmap.d.ts into the source dir on every run;
@@ -90,10 +148,16 @@ export async function runDev(argv, cwd = process.cwd()) {
             }
             return;
         }
-        if (file.startsWith("."))
+        if (!isSourceChange(file, moduleDir, outDir))
             return;
         clearTimeout(timer);
-        timer = setTimeout(() => void cycle(), 200);
+        timer = setTimeout(() => {
+            current = current.then(cycle);
+        }, 200);
+    });
+    watcher.on("error", (e) => {
+        console.error(`[dev] watcher failed: ${e.message}`);
+        void stop(1);
     });
     // Keep the process alive while the watcher runs.
     await new Promise(() => { });

package/dist/install.js

@@ -12,7 +12,8 @@ import { execFileSync } from "node:child_process";
 import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import { formatPushResult, push, record } from "./push.js";
+import { flagValue } from "./args.js";
+import { formatPushResult, push, record, resolvePort } from "./push.js";
 const USAGE = "spicetify-kit install <zip|dist-dir> [--port 9229]\n  (requires `unzip` on PATH for a .zip)";
 function unzipTo(zipPath, dest) {
     try {
@@ -24,11 +25,8 @@ function unzipTo(zipPath, dest) {
 }
 export async function runInstall(argv, cwd = process.cwd()) {
     const target = argv.find((a) => !a.startsWith("--"));
-    const flag = (n) => {
-        const i = argv.indexOf(`--${n}`);
-        return i >= 0 ? argv[i + 1] : undefined;
-    };
-    const port = flag("port") ?? "9229";
+    const flag = (n) => flagValue(argv, n);
+    const port = resolvePort(flag("port"));
     if (!target)
         throw new Error(USAGE);
     const abs = path.resolve(cwd, target);

package/dist/launch.js

@@ -16,9 +16,10 @@
 import { execFileSync, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import path from "node:path";
+import { portInUseMessage, probePort } from "./push.js";
 const APPX_MESSAGE = "Spotify is a Microsoft Store (AppX) install, which the kit cannot launch with a debug port: " +
     "it needs the spicetify-staged --app-directory, which only the CLI knows. " +
-    "Start Spotify yourself with --remote-debugging-port, or run `spicetify-kit dev` without --launch.";
+    "Start Spotify yourself with --remote-debugging-port, then run `spicetify-kit dev --no-launch`.";
 // which returns the resolved path of a command on PATH, or null.
 function defaultWhich(cmd) {
     try {
@@ -38,7 +39,7 @@ export function discoverSpotify(platform = process.platform, env = process.env,
         const app = "/Applications/Spotify.app";
         if (exists(app))
             return { kind: "macos", app };
-        throw new Error(`Spotify not found at ${app}. Install Spotify, or start it yourself with --remote-debugging-port and run dev without --launch.`);
+        throw new Error(`Spotify not found at ${app}. Install Spotify, or start it yourself with --remote-debugging-port and run dev with --no-launch.`);
     }
     if (platform === "win32") {
         // win32.join so paths use backslashes on any host (matters for tests).
@@ -53,30 +54,18 @@ export function discoverSpotify(platform = process.platform, env = process.env,
     const onPath = which("spotify");
     if (onPath)
         return { kind: "linux", exe: onPath };
-    throw new Error("'spotify' not found on PATH. Install Spotify, or start it yourself with --remote-debugging-port and run dev without --launch.");
-}
-// hasXpuiTarget reports whether a debuggable xpui page is already listening
-// on the port, so an already-good client is reused rather than killed.
-export async function hasXpuiTarget(port) {
-    try {
-        const res = await fetch(`http://localhost:${port}/json/list`);
-        if (!res.ok)
-            return false;
-        const targets = (await res.json());
-        return targets.some((t) => t.url?.includes("xpui"));
-    }
-    catch {
-        return false;
-    }
+    throw new Error("'spotify' not found on PATH. Install Spotify, or start it yourself with --remote-debugging-port and run dev with --no-launch.");
 }
 // waitForTarget polls until an xpui debug target appears or the timeout
-// fires; the timeout error names the port and the flag so the remedy is
-// obvious.
-export async function waitForTarget(port, timeoutMs = 30_000) {
+// fires. A foreign listener fails fast instead of burning the whole timeout.
+export async function waitForTarget(port, timeoutMs = 30_000, probe = probePort) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-        if (await hasXpuiTarget(port))
+        const state = await probe(port);
+        if (state.state === "xpui")
             return;
+        if (state.state === "other")
+            throw new Error(portInUseMessage(port, state.what));
         await new Promise((r) => setTimeout(r, 500));
     }
     throw new Error(`timed out waiting for a Spotify xpui debug target on port ${port}. ` +
@@ -101,11 +90,22 @@ function spawnDetached(cmd, args) {
 }
 // launchSpotify reuses a good client, otherwise (re)starts one with the
 // debug port and waits for its xpui target. Returns "reused" or "launched".
-export async function launchSpotify(port, log = console.log, platform = process.platform) {
-    if (await hasXpuiTarget(port)) {
+export async function launchSpotify(port, log = console.log, platform = process.platform, probe = probePort) {
+    const state = await probe(port);
+    if (state.state === "xpui") {
         log(`[dev] reusing the Spotify client already debuggable on port ${port}`);
         return "reused";
     }
+    // Killing Spotify would not free the port, so the relaunch could never bind it.
+    if (state.state === "other")
+        throw new Error(portInUseMessage(port, state.what));
+    if (state.state === "unknown")
+        throw new Error(portInUseMessage(port, "a process that is not a DevTools endpoint"));
+    if (state.state === "spotify") {
+        log(`[dev] Spotify is starting on port ${port}, waiting for it`);
+        await waitForTarget(port, 30_000, probe);
+        return "reused";
+    }
     const target = discoverSpotify(platform);
     if (target.kind === "appx")
         throw new Error(APPX_MESSAGE);
@@ -117,6 +117,6 @@ export async function launchSpotify(port, log = console.log, platform = process.
         spawnDetached("open", ["-a", target.app, "--args", portFlag]);
     else
         spawnDetached(target.exe, [portFlag]);
-    await waitForTarget(port);
+    await waitForTarget(port, 30_000, probe);
     return "launched";
 }