Spicetify Skills

Spicetify Development

Learn how to create themes, extensions, and custom apps for Spicetify. This skill is a router: keep this file for orientation, then open the matching references/*.md file for full docs, signatures, and examples (copied from the official Spicetify docs).

Conventions

• Prefer TypeScript over JavaScript for all new extensions, custom apps, themes-with-JS, and @spicemod/creator projects (.ts / .tsx, spice.config.ts, --language ts).
• Use plain JavaScript only when maintaining an existing JS codebase or the user explicitly asks for JS.
• Prefer @spicemod/creator for multi-file / React / typed work instead of hand-rolled single .js files.

Four development paths

Build/watch tooling, React DevTools, and Spotify CLI flags: references/build-tooling.md.

API Wrapper (global Spicetify object): start at references/api-overview.md, then the method/class/function/property/type refs below.

Theme — project structure

~/.config/spicetify/Themes/       # Linux/macOS
%appdata%\spicetify\Themes\       # Windows
└── MyTheme/
    ├── color.ini                 # Required: color definitions
    ├── user.css                  # Required: custom CSS rules
    ├── theme.js                  # Optional: theme-specific JavaScript
    └── assets/                   # Optional: images, fonts, etc.

Required: color.ini (CSS variables) and user.css. Home-directory themes override executable-directory themes with the same name.

Read: references/themes.md for color formats (hex, decimal, env/xrdb), scheme sections, and CSS guidance.

Extension — project structure

~/.config/spicetify/Extensions/   # Linux/macOS
%appdata%\spicetify\Extensions\   # Windows
├── myExtension.js
└── ...

Minimal pattern: wait until Spicetify.Player / Spicetify.Platform exist, then run. Enable with:

spicetify config extensions myExtension.js
spicetify apply

Key namespaces: Spicetify.Player, Platform, CosmosAsync, URI, React / ReactDOM, Topbar, Playbar, ContextMenu.

For multi-file work, TypeScript, or npm packages, use @spicemod/creator with --language ts instead of a raw single .js file.

Read: references/extensions.md (includes JS/NPM modules).

Custom app — project structure

~/.config/spicetify/CustomApps/   # Linux/macOS
%appdata%\spicetify\CustomApps\   # Windows
└── my-app/
    ├── index.js                  # Required: main entry with render()
    ├── manifest.json             # Required: app metadata and icons
    ├── style.css                 # Optional
    └── src/                      # Optional subfiles

manifest.json keys: name, icon, active-icon, optional subfiles, optional subfiles_extension. Vanilla custom apps use Spicetify.React / createElement (no JSX unless using Creator).

Read: references/custom-apps.md.

@spicemod/creator — project structure

The old FlafyDev Spicetify Creator / create-spicetify-app is deprecated. Use the maintained toolchain:

npx @spicemod/creator create
# or: bunx @spicemod/creator create

Repo: sanoojes/spicetify-creator. Templates: extension, theme, custom-app. Default to TypeScript (--language ts) and React when UI is involved; use JS/vanilla only if requested.

Typical layout:

my-app/
  package.json
  spice.config.ts       # defineConfig from @spicemod/creator
  tsconfig.json         # when using TypeScript
  src/
    app.tsx             # extension/theme entry, or custom-app page
    extension/          # custom-app companion extension (when applicable)
    ...

• Extension: src/app.* runs on Spotify startup.
• Theme: JS+CSS entries via spice.config (see Creator reference).
• Custom app: src/app.* page component + src/extension/ + icons/SCSS modules.

Scripts: dev (HMR), build (use -a to apply to Spicetify), update-types, clean-spice.

Read: references/spicetify-creator.md.

Build tooling

Open references/build-tooling.md when you need:

• Compiling / watch workflows for extensions and apps
• React DevTools setup inside Spotify
• Spotify CLI flags useful for Spicetify development

API Wrapper — which reference to open

Access Spicetify in DevTools, extensions, or window.top.Spicetify from an iframe app.

Do not invent method signatures — copy from these reference files.

Agent workflow

1. Identify the path (theme / extension / custom app / @spicemod/creator) and open that reference.
2. Default to TypeScript (and @spicemod/creator when scaffolding); use JavaScript only if the project already is JS or the user asks for it.
3. For any Spicetify.* API use, open the matching API reference and use signatures/examples verbatim.
4. After Creator code changes, prefer build -a / npm run build -- -a (or dev while iterating); otherwise remind the user of spicetify apply.
5. When the user mentions Spicetify Creator, create-spicetify-app, or spcr-*, steer new work to @spicemod/creator — see references/spicetify-creator.md.