Changesets: monorepo versioning with contributor-written change files

The monorepo problem Changesets targets

In a repository with several published packages, a change to one package often forces a release of the packages that depend on it. Doing that by hand means reading the diff, deciding whether each bump is major, minor or patch, editing several package.json files, and writing changelog entries that a human can read. Changesets moves the decision to the person making the change and the mechanical work to a command. The README describes the intent plainly: contributors declare how their changes should be released, and the tool handles updating package versions, changelogs and publishing from the changesets provided. It also states the focus directly, keeping packages that rely on each other up to date and making it easy to change groups of packages. The README adds that the workflow is conceptually useful for single-package repositories too, though the tooling is built around the monorepo case. The audience is therefore maintainers of JavaScript and TypeScript workspaces, especially ones publishing many packages under one repository.

How a changeset becomes a version bump

The unit of work is a markdown file in the .changeset directory, which is present at the top level of the repository. A contributor adds one alongside their code change, naming the packages affected and the bump type for each, plus a short prose summary. That file is committed with the change. Later, a version command consumes the accumulated files, applies the bumps, updates dependents whose ranges no longer match, writes changelog entries, and removes the consumed files. A separate publish step then pushes the packages to the registry. Nothing here inspects commit messages, so the release note text comes from the contributor rather than from a parser. The repository is a pnpm workspace, with pnpm-workspace.yaml and pnpm-lock.yaml at the top level, and the packages live under packages/. The published pieces are split into separate packages rather than one monolith: the CLI, a config package that validates the configuration, and a release-plan package that computes what a release would contain. The repository's own version-packages script chains changeset version with a formatter, which is a fair picture of how the tool is meant to sit inside a release workflow.

Installing the Changesets CLI and writing a first changeset

The README does not carry install instructions; it points to https://changesets.dev for the documentation, and the CLI is published on npm as @changesets/cli. A typical setup installs that package as a dev dependency and runs the init command, which writes the .changeset directory and a config file. Exact prompts and flags are documented on the site rather than in the README, so check there before scripting it. The commands below use the package name and the binary name as they appear in the repository metadata.

pnpm add -D @changesets/cli
pnpm changeset init

After init, the .changeset directory exists with a config file inside it. A contributor then records a change, which prompts for the packages and bump types and writes a markdown file into that directory.

pnpm changeset

The generated file is meant to be committed with the code change. When the release is prepared, the version command applies the pending files, updates dependent packages and writes changelog entries.

pnpm changeset version

Publishing is a separate step, so a CI job can run it with a registry token rather than on a laptop. The README does not document rollback of a version or publish step, so treat the version command as the point of no easy return and review the diff before committing it.

Where Changesets stops being the right tool

The design puts a manual artifact in every pull request. If your contributors will not write a change file, the version step has nothing to consume and the release either stalls or ships with an empty changelog. Teams that want release notes derived automatically from commit history are working against the grain of this tool. The second constraint is the dependency graph. The README's stated value is keeping interdependent packages up to date, which means the tool needs to understand how your workspace packages reference each other. If packages are versioned in ways the config does not model, or if releases are coordinated across repositories rather than inside one, the mechanism has less to work with. Third, the repository README opens with a notice that the default branch is the development branch for Changesets v3 and that v2 code lives on a maintenance/v2 branch. Anyone reading documentation should confirm which major line their installed CLI belongs to, because behaviour described for one line may not match the other. That is a real cost of adopting a project mid-major-version.

Changesets compared with semantic-release and release-please

The clearest contrast is where the release description comes from. Changesets takes it from a file a human wrote at change time. semantic-release and release-please derive it from commit messages or pull request titles, which means the release note is a byproduct of a convention the team already follows. That difference decides most adoptions. If your history is already conventional and you want zero extra files in the diff, a commit-driven tool fits better. If your commits are messy, or if a single change spans several packages and needs one explanation covering all of them, a changeset file expresses that directly. Changesets also handles the monorepo dependency bump as part of the same step, which is the specific problem the README names. A commit-message tool can be configured to do similar work, but the configuration is where the effort goes rather than into the change file.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-21. Recent releases in the same period include @changesets/[email protected], @changesets/[email protected] and @changesets/[email protected], all dated 2026-09-14. Those are versioned independently, so an upgrade is not a single version number: the CLI, the config schema and the release-plan package move on their own schedules, and a config package major can change what your .changeset/config.json is allowed to contain. The repository ships a script named generate-json-schema under packages/config, which indicates the config has a published schema you can validate against rather than infer from examples. The licence is MIT, declared in both the repository package.json and the LICENSE file at the top level. MIT permits commercial use and modification; it also means the project offers no warranty. That is a statement about the licence text, not legal advice, and anyone embedding the tool in a product should read the LICENSE file themselves. The practical upgrade cost is the split versioning: pin the CLI, watch the config package separately, and expect the v2-to-v3 transition to be the largest jump you will make, since v2 now lives on a maintenance branch.

Editorial conclusion

Adopt Changesets if your repository is a monorepo whose packages depend on each other and you want contributors to describe their own changes at pull request time. Skip it if you cannot ask contributors to write a change file, or if you want version numbers derived from commit messages with no extra artifact in the diff. Verify first that the packages you publish are wired into the workspace the way the config expects, because version bumps and dependent-package updates all flow from that graph. The v3 branch is the development branch, so confirm which major line your install resolves to before you rely on any behaviour you read about.

Frequently asked questions

Official sources

1. changesets/changesets on GitHub
2. License: MIT
3. Project website
4. README
5. Releases