spicetify modules

V3 modules for the spicetify modular runtime.

Building (stitch)

Modules are built with stitch (scripts/stitch.ts), a thin builder on top of rolldown. Node 24 only; no Deno required, and TypeScript runs natively.

pnpm install
pnpm stitch modules/stdlib        # one module, auto-detects the classmap
pnpm stitch                       # all modules
pnpm stitch --classmap 1020092    # explicit classmap key
pnpm stitch -c path/to/classmap.json
pnpm stitch --help

Classmap resolution order (no env vars needed):

1. --classmap <key|path>: a key resolves to the newest classmap-*.json in that folder of a classmaps checkout; a path is used directly.
2. stitch.config.json (repo-level defaults, gitignored).
3. Auto-detection: the newest key folder in ../classmaps (sibling clone) or ./classmaps (in-repo, used by CI).
4. ./classmap.json as a fallback.

What stitch does:

• bundles TS/TSX with rolldown (lazy dynamic-import chunks preserved, /hooks/* and https:// imports kept external),
• compiles index.scss to index.css (sass-embedded),
• writes dist/<name>@<version>/ with metadata.json and the spicetify-module.json sidecar (classmap_base, installed_version, allow_stale),
• generates classmap.d.ts per module from the resolved classmap (typed MAP for authors).

Modules ship MAP-intact: class references stay as MAP.* in the built output and are remapped by the spicetify CLI at apply time against the exact installed classmap. One build serves every supported Spotify version; there are no per-version prebuilds.

Verifying one module

From the repository root, run a module's automated checks with Node 24 and the shared dependencies installed:

pnpm verify auto-skip-explicit
pnpm verify modules/lyrics-plus
pnpm verify themes/text

The command builds the selected module, checks its TypeScript and imported dependencies, lints, checks formatting and stdlib boundaries, validates repository dependency ranges, and runs its colocated *.test.mts files. It reports explicitly when a module has no automated tests. It doesn't install the build into Spotify.

To verify your changes and modules that depend on them, run:

pnpm verify --changed
pnpm verify --changed --base origin/main

Changed mode compares against the merge base with origin/main by default, including committed, staged, unstaged, and untracked files. It checks affected modules and their reverse dependencies. Shared tooling changes run all module builds and the full repository checks. CI continues to run the full suite. Fetch your target branch first when you need its latest state. Live Spotify verification remains a separate step.

Strict checking is the default for modules, stdlib, scripts, and generated TypeScript projects, including Lyrics Plus. File-level type-checking exemptions are rejected by lint. The module standard explains the checks and the separate client and test environments.

Docs

• docs/updating-modules.md — updating and repairing modules from the Spotify UI
• docs/authoring-guide.md — building a module
• docs/module-standard.md — the module contract
• docs/publishing.md — submitting a module to the store
• docs/npm-publishing.md — releasing the developer kit and scaffold launcher to npm
• docs/theming-the-client.md — theming the client's own colors
• docs/pr-flow.md — release and tag recovery

Why Node and not Deno

The 2024 prototype was Deno-first (TS-native execution, JSR, web-standard APIs). Everything the current pipeline needs, Node 24 does natively: type stripping, rolldown (Rust bundler with TS support), and the package ecosystem the rest of spicetify already uses (the CLI wrapper builds with esbuild on Node). The Deno/tailor tooling was removed; stitch is the only build path.

License

GPLv3. See COPYING.