Changesets
Changesets is a release tool that captures release intent in markdown files at PR time rather than parsing it from commit messages. It's the monorepo-friendly alternative to semantic-release.
Pick one — Changesets or semantic-release — per repo. The doctor check flags repos configured for both.
Setup
The wizard offers Changesets as a peer to semantic-release for library projects:
? 🚀 Automated release tool?
📦 semantic-release (commit-message-driven)
> 📝 Changesets (changeset-file-driven, monorepo-friendly)
❌ None
If you pick Changesets, the wizard drops .changeset/config.json at the project root.
Adding to an existing project
npx @rtorcato/repo-tooling copy changesets
Install Changesets and the GitHub Action:
pnpm add -D @changesets/cli
Authoring changesets
For every change that should ship in a release, the author runs:
pnpm changeset
This is an interactive prompt that writes a markdown file under .changeset/, like:
---
'@rtorcato/my-pkg': minor
---
Add the new sparkle widget.
Commit the changeset file alongside the change. The release process consumes it later.
The scaffolded ci.yml has a changeset job that fails a PR changing src/ (or packages/<name>/src/) with no new .changeset/*.md. It skips the Version Packages PR and any PR whose title type releases nothing (docs, chore, ci, test, build, style, refactor). For a change that ships nothing under another type, commit an empty changeset with pnpm changeset --empty.
Releasing
For the whole flow, from a PR's changeset to npm, see Releasing.
pnpm changeset version # consume changesets, bump versions, write CHANGELOG.md
pnpm changeset publish # publish to npm
In CI, the generated release.yml runs the Changesets action in two jobs. Shipping is merge the Version Packages PR, then one approval:
- Every push to
mainruns the ungatedversionjob. With changesets pending, it opens or updates the "Version Packages" PR and publishes nothing. - Merging that PR is the release. Its push runs the
publishjob, which waits for one approval on thereleaseenvironment, then publishes every package whose version is not on npm yet and creates its GitHub release.
An ordinary merge skips publish, so it never queues an approval request. Dispatch the workflow (gh workflow run release.yml) to retry a failed publish. With changesets pending, a dispatch updates the Version Packages PR instead, so a hotfix ships the normal way: merge it, then merge the Version Packages PR. In pre mode (pnpm changeset pre enter beta) the same flow publishes x.y.z-beta.N under the beta tag. See GitHub Actions for the details.
Choosing between Changesets and semantic-release
Pick Changesets when you have:
- A monorepo with multiple publishable packages.
- A team that finds commit-message conventions hard to enforce.
- A workflow that benefits from
--snapshotreleases orpre enter <tag>prerelease modes.
Pick semantic-release when you have:
- A single-package repo.
- A team already disciplined on conventional commits.
- An existing CI built around
pnpm run release.
Both tools share the same shape: CI consumes intent, bumps versions, writes a changelog, and publishes to npm. The difference is where the intent lives.
Migrating from semantic-release
doctor lists a public package still on semantic-release as Release tool (optional-missing, so it never fails the exit code). fix changesets-migrate moves it:
- deletes
release.config.*/.releaserc*, thereleasefield, thereleasescript and thesemantic-release/@semantic-release/*dependencies; - adds
.changeset/config.json,@changesets/cliand achangesetscript, and lists.inpnpm-workspace.yamlwhen it has apackages:list without it; - sets
package.jsonversionto the latest on npm, so Changesets bumps from what is published (a package not on npm yet keeps its version); - rewrites
release.ymlas the two-job Version Packages flow, keeping itsenvironment:and dropping themilestone: closedtrigger. Re-add any custom steps afterwards; - records
semanticRelease: falseandchangesets: truein.repo-tooling.json.
It runs only when named, refuses while ci.yml still holds a semantic-release job (run fix github-actions first), and writes nothing when npm cannot be reached. Run pnpm install afterwards to refresh the lockfile.
Doctor behaviour
- If only
.changeset/config.jsonexists,doctorreportssemantic-releaseas ok with "using Changesets instead". - If both exist,
doctorflags drift — you have two release tools fighting for the same job. Remove one. doctorflags aci.ymlwith nochangesetjob;fix github-actionsregeneratesci.ymlwith it (see--difffirst if yours is customized).doctorflags a single-jobrelease.ymlthat opens the Version Packages PR and publishes behind one approval (two approvals per release).fix github-actionsrewrites it as the two-job shape and leavesci.ymlalone.- "Publishes on merge" means nothing stands between a merge and npm. The Release gate check flags a
changesets/actionjob with no protectedenvironment:. That holds in a monorepo with a private root too, as long as a workspace package isn't private.fix release-environmentadds the gate.