Versions and changesets

Every Void app built with Flare versions itself the same way: SemVer, with changesets (@changesets/cli) recording each change when it’s made. The Flare repository does this too (see decision 17).

Set it up

pnpm add -D @changesets/cli

Then add .changeset/config.json:

{
  "$schema": "https://unpkg.com/@changesets/config@4.0.1/schema.json",
  "baseBranch": "main",
  "access": "restricted",
  "fixed": [],
  "linked": [],
  "ignore": [],
  "updateInternalDependencies": "patch",
  "privatePackages": { "version": true, "tag": true },
  "changelog": "@changesets/cli/changelog",
  "format": false,
  "commit": false
}

An app’s package.json has "private": true, so it is never published. privatePackages with version and tag set to true still lets changesets bump its version, write its CHANGELOG.md and tag it.

Add these scripts:

{
  "scripts": {
    "changeset": "changeset",
    "version-packages": "changeset version && pnpm install --lockfile-only",
    "tag": "changeset git-tag"
  }
}

With every change

A change someone can notice gets a changeset in the same commit or pull request:

pnpm changeset

Pick the bump and write a sentence or two, in the present tense, about what changed for the people using the app. Start with the area in bold:

---
"my-app": minor
---

**Deals**: The pipeline board can be filtered by owner.

No changeset for refactors, tests, tooling or docs that change nothing anyone can see.

Which bump

An app’s users are people, and API, MCP or webhook clients.

• major: a client has to change: a removed or renamed route, field, MCP tool or webhook, or a data migration someone has to act on.
• minor: something new: a page, a route, a field, an MCP tool, an option.
• patch: a fix that changes nothing anyone relies on.

Release

pnpm version-packages
git commit -am "chore(release): version packages"
pnpm tag
git push --follow-tags

version-packages bumps package.json, writes CHANGELOG.md and deletes the consumed changesets, so .changeset/ always shows what hasn’t shipped. tag tags the new version. Deploy that tag (pnpm deploy).

To automate it, run changesets/action on pushes to main with version: pnpm version-packages and publish: pnpm tag. It keeps a “Version Packages” pull request open and tags the release when it merges. The Flare repository’s release.yml is an example; it publishes to npm, which an app doesn’t.

Several packages

A repository with more than one published package, like Flare’s @recranet/flare and @recranet/flare-cli, puts packages that always ship together in a fixed group, so they share one version:

{ "fixed": [["@recranet/flare", "@recranet/flare-cli"]] }