Using Changesets

Changesets are designed to make your workflows easier, by allowing the person making contributions to make key decisions when they are making their contribution. Changesets hold two key bits of information: a version type (following semver), and change information to be added to a changelog.

In addition, changesets were originally designed for implementation in bolt monorepos. As such, in a monorepo context, changesets will handle bumping dependencies of changed packages, if that is required.

This guide is aimed at package maintainers adding changesets as a tool. For the information relevant to contributors, see adding a changeset.

The overall tool after initialization should lead to a loop that looks like:

1. Changesets added along with each change
2. The version command is run when a release is ready, and the changes are verified
3. The publish command is run afterwards.

The second two steps can be made part of a CI process.

Add the changeset tool

npm

npm install @changesets/cli
npm run changeset init

pnpm

pnpm add @changesets/cli
pnpm changeset init

yarn

yarn add @changesets/cli
yarn changeset init

bun

bun add @changesets/cli
bun changeset init

Adding changesets

npm

npm run changeset

pnpm

pnpm changeset

yarn

yarn changeset

bun

bun changeset

Note: You can run changeset add to add a changeset if you want to, but running Changesets without any command works as well.

Versioning and publishing

Once you decide you want to do a release, you can run

npm

npm run changeset version

pnpm

pnpm changeset version

yarn

yarn changeset version

bun

bun changeset version

This consumes all changesets, and updates to the most appropriate semver version based on those changesets. It also writes changelog entries for each consumed changeset.

We recommend at this step reviewing both the changelog entries and the version changes for packages. Once you are confident that these are correct, and have made any necessary tweaks to changelogs, you can publish your packages:

npm

npm run changeset publish

pnpm

pnpm changeset publish

yarn

yarn changeset publish

bun

bun changeset publish

This will run npm publish in each package that is of a later version than the one currently listed on npm.

Some handy advice

Not every change requires a changeset

Since changesets are focused on releases and changelogs, changes to your repository that don't require these won't need a changeset. As such, we recommend not adding a blocking element to contributions in the absence of a changeset.