Skip to main content

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/js-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.

Releasing​

pnpm changeset version   # consume changesets, bump versions, write CHANGELOG.md
pnpm changeset publish   # publish to npm

In CI, the Changesets release bot opens a "Version Packages" PR whenever changesets are pending and publishes on merge.

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 --snapshot releases or pre 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.

Doctor behaviour​

  • If only .changeset/config.json exists, doctor reports semantic-release as ok with "using Changesets instead".
  • If both exist, doctor flags drift — you have two release tools fighting for the same job. Remove one.