Changesets: PR Receipts for Monorepo Releases

Why it exists

In monorepos with many interdependent packages, manual versioning is a coordination trap. Developers forget to bump package.json files, changelogs rot, and determining whether a change is a patch or minor becomes a guessing game at release time. Changesets were invented to separate the human work of describing impact from the mechanical work of applying version bumps and generating logs.

The mental model

Treat a changeset like a receipt you staple to a pull request. It states which packages are affected, the semver level of each change, and a human-readable description. The tool collects these receipts at release time, groups them by package, applies the highest bump per package, and writes the changelog entries automatically. You are not editing versions during development; you are leaving instructions for a robot to do it later.

How it works

When opening a pull request, a developer runs a CLI command that creates a markdown file in a .changeset directory. The file contains YAML frontmatter listing affected packages and bump types, followed by a description. On merge, the file persists in the repository. A maintainer or CI job later runs the version command, which consumes all unreleased changeset files, updates each package's version according to the aggregated bumps, appends the descriptions to each package's CHANGELOG.md, and deletes the consumed files. A subsequent publish command then ships to the registry.

When to use it

Changesets excel in multi-package monorepos where several teams contribute and packages have internal dependencies. They are ideal when you want batched releases rather than continuous deployment on every merge, and when you need changelogs that are actually readable because they are written by humans at the moment of change, not reconstructed from commit hashes later.

When not to use it

Avoid changesets for single-package repositories or teams that release on every merge; tools like semantic-release that derive versions from conventional commits are lighter. They also fail if your team lacks the discipline to generate the files, because missing changesets mean merged features never get published. The overhead of managing changeset files is not worth it for small projects with infrequent releases.

One canonical example

Imagine a design system monorepo with a button package and an icon package. A developer adds a new size prop to Button, which requires a minor alignment adjustment in Icon. They run pnpm changeset, select button for a minor bump and icon for a patch bump, and write "Added size prop to Button; fixed Icon alignment for new scale." Two more PRs accumulate over the week. At release time, the changeset tool reads all three files, bumps Button to 2.1.0 and Icon to 1.0.1, updates both changelogs with the human-written summaries, and publishes the packages.