Changesets

Appearance

Command Line Interface ​

The Changesets CLI is the main way of interacting with changesets. It provides a set of commands that allow you to manage your changesets, version your packages, and publish them.

bash
Usage:
  $ changeset [command] [options]

Commands:
  init                    Initialize a new changesets setup
  add                     Add a new changeset (default)
  version                 Version packages and create changelogs
  publish                 Publish packages to npm and create git tags
  status                  Show the changesets that currently exist
  tag                     Create git tags for the current version of all packages
  pre <enter|exit> [tag]  Enter or exit prerelease mode (tag required for enter)

init ​

bash
Usage:
  $ changeset init

This command sets up the .changeset folder. It generates a readme and a config file with the default options. You should run this command once when setting up Changesets.

add ​

bash
Usage:
  $ changeset [options]
  $ changeset add [options]

Options:
  --empty               Add an empty changeset 
  --open                Open the changeset in the editor after creating it 
  --since <branch>      Detect changed packages since the provided git ref 
  -m, --message <text>  Directly provide a message to the changeset 

Examples:
  $ changeset -m 'Description'
  $ changeset --open --since main

This is the main command to interact with the changesets.

It will ask you a series of questions, first about what packages you want to release, then what semver bump type for each package, then it will ask for a summary of the changes. The final step will show the changeset it will generate and confirm that you want to add it.

Once confirmed, the changeset will be written in the .changeset folder. If the commit option is enabled, the changeset will be automatically committed to git.

Empty changesets ​

If you have CI that blocks merges without a changeset, pass --empty to create an empty changeset.

Changing the base branch ​

When prompting for packages to release, Changesets will detect and suggest the changed packages since the last commit on baseBranch. If you want to use a different base branch, tag, or git ref, you can change it with the --since [branch] option.

bash
$ changeset --since next

version ​

bash
Usage:
  $ changeset version

Options:
  --ignore <pkg>                             Packages to ignore 
  --snapshot [name]                          Create a snapshot prerelease 
  --snapshot-prerelease-template <template>  Template for snapshot prerelease 

Examples:
  $ changeset version
  $ changeset version --snapshot 'pr#123'

This is one of two commands responsible for releasing packages. The version command takes changesets that have been made and updates versions and dependencies of packages, as well as writing changelogs. It is responsible for all file changes before publishing to npm.

Commit the version changes

We recommend making sure changes made from this command are committed before you run publish:

bash
$ git add .
$ git commit -m "Version packages"

Ignoring packages ​

The --ignore flag allows you to skip packages from being published. This allows you to run partial publishes of the repository. This extends the ignore option with the same documented caveats.

bash
$ changeset version --ignore pkg-a --ignore pkg-b

Snapshot releases ​

You can use the --snapshot flag to create a snapshot release, meant for testing purposes only. The suffix for snapshot releases can be customized with --snapshot-prerelease-template <template>, which works the same way as the snapshot.prereleaseTemplate option.

It is highly recommended to read the Snapshot Releases guide before using this flag.

bash
$ changeset version --snapshot 'pr#123'

publish ​

bash
Usage:
  $ changeset publish

Options:
  --otp <code>  One time password for npm publish 
  --tag <name>  Publish with the given npm dist-tag 
  --git-tag     Create a git tag for the release (default: true)

Examples:
  $ changeset publish --otp 123456
  $ changeset publish --tag beta

This command publishes changes to npm and creates git tags. It works by going into each package, checking if the version it has in its package.json is published on npm, and if it's not, run npm publish (or pnpm publish etc if detected to be using a different package manager).

Because this command assumes that the last commit is the version commit, you should not commit any changes between calling version and publish. These commands are separate to enable you to check if the release changes are accurate.

Git tags for each package are also created by default. This allows users to easily find the code for a specific release. The tags created are in the format of pkg-name@X.X.X, or in single-package repos, it is vX.X.X. Pass --no-git-tag to disable this.

Make sure to push the tags to your git remote after creating them:

bash
$ git push --follow-tags

OTP ​

When publishing locally, you may be prompted for a one-time password (OTP) if your have two-factor authentication enabled on npm. You can provide this OTP directly with the --otp <code> flag to avoid the prompt.

bash
$ changeset publish --otp 123456

NPM dist-tags ​

Published versions are tagged on npm with latest by default. You may want to change the dist-tag when publishing snapshot releases to prevent them from being installed by default. Pass --tag <name> to publish with a different dist-tag.

bash
$ changeset publish --tag beta

status ​

The status command provides information about the changesets that currently exist. If there are no changesets present, it exits with exit code 1.

JSON output ​

Pass --output <file> write the status output as a JSON file so it can be consumed by other tools.

bash
$ changeset status --output status.json

Status since a specific branch ​

You can use --since <branch> with a different branch, tag, or git ref to only display the information about changesets since that point.

bash
$ changeset status --since next

WARNING

status will fail if you are in the middle of running version or publish. If you want to get changeset status at the time of a version increase and publish, you need to run it immediately before running version.

tag ​

bash
Usage:
  $ changeset tag

The tag command creates git tags for the current version of all packages. The tags created are equivalent to those created by the publish command, but the tag command does not publish anything to npm.

This is helpful in situations where a different tool is used to publish packages instead of Changesets. The tags created are in the format pkg-name@X.X.X, or in single-package repos, it is vX.X.X. It is expected to run the version command first so the created tags are up to date.

pre ​

bash
Usage:
  $ changeset pre <enter|exit> [tag]

The pre command is used to enter or exit prerelease mode. It does not do any versioning but prepares Changesets in a state for prereleases.

When you want to do a prerelease, run pre enter <tag> to enter prerelease mode with the given tag, then do the normal release process as usual. When you're ready for a stable release, run pre exit and do the normal release process again.

Prereleases are complicated

Many of the safety rails that Changesets helps you with are taken off in prerelease mode. You may also prefer using snapshot releases for a slightly less involved process. It is highly recommended to read through the prereleases documentation before using this command.