Changesets

Appearance

Getting Started ​

What is Changesets? ​

Changesets has several meanings that are sometimes used interchangeably:

  1. It is a tool to manage package versions and changelog generation in a project, designed to work in monorepos as well as single package repos.

  2. It is a workflow that allows contributors to describe what their changes are and how they should be released.

  3. It also represents a group of changeset files, which are Markdown files that each describe a change.

New to Changesets?

If you are contributing to a project that uses Changesets, check out the frequently asked questions for a quick introduction to working with changesets.

Why Changesets? ​

Changesets is designed to help manage and describe changes, all the way through to publishing. It lets contributors declare how their changes should be released, and it'll handle updating package versions, changelogs, and publishing based on the provided changesets.

Changesets has a focus on solving these problems for monorepos, keeping packages that rely on each other up to date, as well as making it easy to make changes to groups of packages. Conceptually, the workflow is also beneficial for single package repos.

Read more about the motivation in the Why Changesets page.

What is a changeset? ​

A changeset is a Markdown file with YAML frontmatter. The contents of the Markdown is the change summary which will be written to the changelog and the YAML frontmatter describes the packages that have changed and their respective semver bump types.

They typically look like this:

md
---
"pkg-a": minor
"pkg-b": patch
---

Summary of the change

The core idea of Changesets revolves around these files.

Setting Up ​

Selecting a package manager

We recommend using pnpm as it has safer security defaults and better monorepo support. However, we also support other package managers if you prefer them.

Install the Changesets CLI:

bash
$ pnpm add -D @changesets/cli
bash
$ npm install -D @changesets/cli
bash
$ yarn add -D @changesets/cli

And run init to set up the .changeset folder in your project:

bash
$ pnpm changeset init
bash
$ npx @changesets/cli init
bash
$ yarn changeset init

Your project is now using Changesets!

Usage ​

Whenever you make a change, e.g. via a git commit or a PR, create a changeset alongside with the CLI:

bash
$ pnpm changeset
bash
$ npx @changesets/cli
bash
$ yarn changeset

Not every change requires a changeset

Since a changeset describes how a change should be released, changes that don't require a release do not need a changeset. As such, we do not recommend blocking contributions in the absence of a changeset.

Once you have accumulated some changesets, check out the Versioning and Publishing guide to learn how to release your changes.

See also the CLI reference to learn more about the available CLI commands.