Guide · Open source
How to use Changesets: install, add changesets and release
Updated · written with AI from the project's own documentation and checked against our catalogue data
Changesets is an open-source tool, written in TypeScript and released under the MIT licence, that manages versioning and changelogs with a focus on monorepos. This guide is for maintainers and contributors who publish packages to a registry and want releases handled consistently. After reading it, you will know how to install the CLI, how contributors describe their changes, and what the tool does during a release.
Changesetschangesets/changesets · ★ 12.6k · MIT Install options & downloads Quick start
- 1Check Node.js is installed. Changesets requires Node.js, so confirm it is available in your environment before you install the CLI.
- 2Install the CLI as a dev dependency. Run npm install -D @changesets/cli in your project to add the CLI as a development dependency.
- 3Add a changeset for a change. When you make a change that should be released, add a short changeset file that declares how it should be released.
- 4Let the tool update versions. Changesets uses the changeset files to update package versions for the packages you changed.
- 5Let the tool write changelogs. The changelogs are generated from the descriptions contributors wrote in each changeset.
- 6Publish the packages. Changesets handles publishing based on the provided changesets, as described in the docs at changesets.dev.
What Changesets does
Changesets is designed to help manage and describe changes all the way through to publishing. Contributors declare how their change should be released, and the tool then updates package versions, changelogs and publishing based on those declarations.
It focuses on monorepos, where packages rely on each other, so that packages that depend on one another stay up to date and groups of packages can be changed together. The README says the workflow can also benefit single-package repos.
Install the Changesets CLI
Changesets is installed through a package manager. The README installs the CLI as a dev dependency, and the prerequisite is Node.js.
npm install -D @changesets/cliAdd a changeset for each change
Contributors add a short changeset file with each change. The file states how the change should be released, and the release tooling reads these files later. Because the description is written by the contributor, the changelog entries reflect what the change means to users rather than a raw commit message.
The README describes this as an explicit declaration by the contributor, so the flow depends on people adding the file for each change.
- Write one short changeset per change.
- Describe the change in plain language, since it is used for the changelog.
- Declare the release impact for each package the change touches.
Let Changesets handle the release work
Based on the changeset files, the tool updates package versions, writes changelogs and handles publishing. Your job is to keep adding changesets as work lands, rather than editing versions and changelogs by hand.
Packages that depend on each other are kept in step by the same process, which is the main reason the tool is built for monorepos.
Know when Changesets is not the right fit
Changesets is built around releases, so it is a poor match for projects that do not publish packages and do not need versioning. It is also not a fully automatic commit-message-based flow, because contributors declare changes explicitly.
This guide does not cover the stable v2 code. The README says the branch it links to is the v3 development branch, and that the v2 code lives on the maintenance/v2 branch.
What people use it for
- Keeping several interdependent packages in one monorepo at consistent versions.
- Generating release notes from descriptions that contributors write for each change.
- Publishing packages to a registry with versioning handled the same way every release.
- Applying the same release workflow to a single-package repository.
Frequently asked questions
How do I install Changesets?
Install the CLI as a dev dependency with npm install -D @changesets/cli. The README lists Node.js as the prerequisite. The full documentation is at changesets.dev.
Is Changesets free to use?
Changesets is released under the MIT licence, as stated in the project's details. Check the LICENSE file in the repository for the full terms.
What language is Changesets written in?
Changesets is written in TypeScript. You install it through a package manager and need Node.js to run it.
Is Changesets only for monorepos?
No. It has a focus on monorepos, but the README says the workflow can also benefit single-package repos.
Does Changesets generate releases from commit messages?
No. Contributors declare how each change should be released by adding a changeset file, so the flow is explicit rather than automatic from commit messages.
How does Changesets compare to semantic-release, release-please and lerna?
These are comparable projects. Changesets relies on contributor-written changeset files, while the others are often chosen for different release flows. Compare them against your team's release process before choosing.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Changesets suits teams that maintain a monorepo of interdependent packages, or that publish to a registry and want release notes written from contributor descriptions. Projects that do not publish packages, or that want releases driven entirely by commit messages, should look at other tools such as semantic-release, release-please or lerna.
Install options & downloads