Development setup
npm install
npm run rebuild
npm run binaries:prepare
npm run dev
The dev command starts Vite at http://127.0.0.1:5173/ and launches Electron. npm run rebuild prepares native SQLite bindings for Electron. npm run dev automatically runs binaries:prepare before Electron starts, downloading the pinned yt-dlp release and copying the ffmpeg-static binary into bin/<platform>-<arch>/. Run binaries:prepare manually if you only need to refresh media tools.
npm run binaries:prepare:win # Windows x64 media binaries, from any platform
npm run binaries:prepare:linux # Linux x64 media binaries, from any platform
npm run binaries:prepare:mac # Both macOS architectures, from any platform
For hardware-free watch detection checks, set COROS_WATCH_PATH=/path/to/mock-watch with a Music folder, or run:
npm run smoke:watch
Packaging
npm run dist:mac
npm run dist:win
npm run dist:linux
Run npm run binaries:prepare before packaging. The packaged app checks bundled binaries first, then falls back to PATH.
Native dependencies:
Because better-sqlite3 is native, build Windows installers on Windows or in CI where Electron native dependencies can be rebuilt for the Windows target. The same applies to Linux AppImages on Linux.
For a quick local packaging layout check without code signing:
CSC_IDENTITY_AUTO_DISCOVERY=false npm run dist -- --dir
Publishing a release (maintainers)
Prepare the version
Update package.json and package-lock.json so they match the tag you're about to create:
npm run release:prepare -- v0.1.17
git commit -am "chore: release v0.1.17"
git tag v0.1.17
git push origin main v0.1.17
CI builds and publishes
Pushing the tag triggers the Release installers workflow. CI syncs the tag into package.json before building, verifies the versions match, and uploads latest-mac.yml, latest-linux.yml, and latest.yml plus macOS/Windows blockmaps so packaged apps can auto-update via electron-updater (the Linux AppImage embeds its blockmap in the file). Each platform build runs scripts/verify-release-artifacts.mjs and fails if update metadata is missing.
You can also run the workflow manually from Actions → Release installers — it uses the current package.json version when no tag is pushed. Pushes to main run Build desktop installers and upload CI artifacts for testing before tagging.
Verify release artifacts locally
npm run dist:mac # or dist:win / dist:linux on the matching OS
npm run release:verify-artifacts -- macos
After building, confirm release/latest-mac.yml (or latest.yml / latest-linux.yml) exists and that the packaged app contains app-update.yml with the GitHub publish config.
Test auto-update end-to-end (maintainers)
- Tag and ship a baseline release that includes the updater (e.g. v0.1.8).
- Install that build from GitHub Releases on a test machine.
- Confirm the header shows a clickable version badge (not dev-only text).
- Tag and ship a newer release (e.g. v0.1.9).
- In the older app, wait ~5 seconds or click the version badge.
- Expect: checking → update available → downloading → Restart to update.
- Click restart; the app should relaunch on the new version.
Windows and signed macOS builds should complete this flow. Locally built unsigned macOS apps may still need a manual download from GitHub Releases.