Registry & Versioning

Registry & Versioning

registry.json

The app reads exactly one auto-generated index — [registry.json](https://github.com/Psysonic/psysonic-themes/blob/main/registry.json) — over the [jsDelivr](https://www.jsdelivr.com/) CDN, then pulls each theme's CSS and thumbnail on demand. Nothing in this repo is bundled into the app itself.

registry.json is generated from every theme's manifest.json. A GitHub Actions workflow regenerates it automatically on every push to main. Locally, you can mirror that with:

npm run registry

Never edit registry.json by hand — your changes will be overwritten on the next merge, and a hand-edited registry that drifts from the manifests is exactly the kind of thing the auto-generation exists to prevent.

Each entry in registry.json carries the manifest fields plus resolved paths and an updatedAt timestamp, e.g.:

{
  "id": "your-theme-id",
  "name": "Your Theme Name",
  "author": "your-github-handle",
  "version": "1.0.0",
  "description": "Short description of the theme's look and inspiration.",
  "mode": "dark",
  "changelog": { "1.0.0": ["Initial release."] },
  "css": "themes/your-theme-id/theme.css",
  "thumbnail": "themes/your-theme-id/thumbnail.webp",
  "updatedAt": "2026-01-01T00:00:00+00:00"
}

Versioning

Bump manifest.version (X.Y.Z, no pre-release suffix) on every change to a theme that's already published — including CSS tweaks, bug fixes, and asset changes. The in-app Theme Store detects updates by comparing this version number, so a change shipped under the same version silently never reaches users who already installed the theme.

CI enforces this: a PR that edits an existing theme without raising its version fails the validate check. See Validator & CI.

Changelog

The optional changelog object in manifest.json is keyed by version, with an array of short bullet strings:

"changelog": {
  "1.3.1": [
    "Fix: row controls inside track rows can be clicked reliably again.",
    "The press animation was scaling the whole row on :active, which shifted controls out from under the cursor mid-click."
  ]
}

This is what powers the store's What's new panel — it's optional, but worth adding.

Branch hygiene for updates

See Making-a-Theme#updating-a-theme-thats-already-published for the rebase-not-merge workflow that keeps update PRs from colliding when two changes to the same theme are in flight at once.