A tool to manage versioning and changelogs
with a focus on multi-package repositories

The changesets workflow is designed to help when people are making changes, all the way through to publishing. It lets contributors declare how their changes should be released, then we automate updating package versions, and changelogs, and publishing new versions of packages based on the provided information.

Changesets has a focus on solving these problems for multi-package repositories, and keeps packages that rely on each other within the multi-package repository up-to-date, as well as making it easy to make changes to groups of packages.

How do we do that?

A changeset is an intent to release a set of packages at particular semver bump types with a summary of the changes made.

The @changesets/cli package allows you to write changeset files as you make changes, then combine any number of changesets into a release, that flattens the bump-types into a single release per package, handles internal dependencies in a multi-package-repository, and updates changelogs, as well as release all updated packages from a mono-repository with one command.

How do I get started?

If you just want to jump in to using changesets, the Intro to using changesets and @changesets/cli docs are where you should head.

If you want a detailed explanation of the concepts behind changesets, or to understand how you would build on top of changesets, check out our detailed-explanation.

We also have a dictionary.

Integrating with CI

While changesets can be an entirely manual process, we recommend integrating it with how your CI works.

To check that PRs contain a changeset, we recommend using the changeset bot, or if you want to fail builds on a changesets failure, run yarn changeset status in CI.

To make releasing easier, you can use this changesets github action to automate creating versioning pull requests, and optionally publishing packages.

Documentation

• Intro to using changesets
• Detailed explanation
• Common questions
• Adding a changeset
• Automating changesets
• Checking for changesets
• Command line options
• Config file options
• Decisions
• Dictionary
• Fixed packages
• Linked packages
• Modifying changelog format
• Prereleases
• Problems publishing in monorepos
• Snapshot releases
• Versioning applications and other non-npm packages
• Experimental Options

Cool Projects already using Changesets for versioning and changelogs

• atlaskit
• emotion
• keystone
• react-select
• XState
• pnpm
• filbert-js
• tinyhttp
• Firebase Javascript SDK
• Formik
• MobX
• Nhost
• verdaccio
• Chakra UI
• Astro
• SvelteKit
• Hydrogen
• react-pdf
• GraphQL Code Generator
• GraphQL Yoga
• GraphQL-Mesh
• GraphiQL
• wagmi
• refine
• Modern Web
• Atomizer
• Medusa
• OpenZeppelin Contracts
• Block Protocol
• Remix
• Clerk
• Hey API
• neverthrow
• Apollo Client

Thanks/Inspiration

• bolt - Brought us a strong concept of how packages in a mono-repo should be able to interconnect, and provided the initial infrastructure to get inter-package information.
• Atlassian - The original idea/sponsor of the changesets code, and where many of the ideas and processes were fermented. It was originally implemented by the team behind atlaskit.
• lerna-semantic-release - put down many of the initial patterns around updating packages within a multi-package-repository, and started us thinking about how to manage dependent packages.
• Thinkmill - For sponsoring the focused open sourcing of this project, and the version two rearchitecture.

@changesets/types

6.1.0

Minor Changes

• #1453 84a4a1b Thanks @bennypowers! - Added a new config option to opt-out from formatting with Prettier using prettier: false.

6.0.0

Major Changes

• #1185 a971652 Thanks @Andarist! - package.json#exports have been added to limit what (and how) code might be imported from the package.

5.2.1

Patch Changes

• #1033 521205d Thanks @Andarist! - Added changedFilePatterns property to Config and WrittenConfig types.

5.2.0

Minor Changes

• #662 8c08469 Thanks @JakeGinnivan! - Added support for the privatePackages property in the config.

5.1.0

Minor Changes

• #858 dd9b76f Thanks @dotansimha! - Added a new config option: snapshot.prereleaseTemplate for customizing the way snapshot release numbers are being composed.

5.0.0

Major Changes

• #768 c87eba6 Thanks @rohit-gohri! - commit properties of config types were adjusted to account for this option potentially pointing to a module path.

4.1.0

Minor Changes

• #690 27a5a82 Thanks @Andarist! - Add the new fixed property to the Config type.

4.0.2

Patch Changes

• #668 9a993ba Thanks @marcodejongh! - Add resolutions to the PackageJSON type.

4.0.1

Patch Changes

• #582 e89e28a Thanks @Andarist! - Add support for publishConfig.registry

4.0.0

Major Changes

• #542 de2b4a5 Thanks @Andarist! - A new updateInternalDependents experimental option has been added. It can be used to add dependent packages to the release (if they are not already a part of it) with patch bumps. To use it you can add this to your config:

  {
    "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
      "updateInternalDependents": "always"
    }
  }

  This option accepts two values - "always" and "out-of-range" (the latter matches the current default behavior).

3.3.0

Minor Changes

• 12f9a43 #507 Thanks @zkochan! - New setting added: bumpVersionsWithWorkspaceProtocolOnly. When it is set to true, versions are bumped in dependencies, only if those versions are prefixed by the workspace protocol. For instance, "foo": "workspace:^1.0.0".

3.2.0

Minor Changes

• f4973a2 #467 Thanks @Andarist! - Exported a new Linked type for convenience - it's an alias for ReadonlyArray<ReadonlyArray<string>>.`

3.1.1

Patch Changes

• a57d163 #428 Thanks @dotansimha! - Updated signature of PackageJSON['publishConfig'] to include directory?: string.

3.1.0

Minor Changes

• 9dcc364 #371 Thanks @Feiyang1! - Add ignore config option to configure ignored packages. The versions of ignored packages will not be bumped during a release, but their dependencies will still be bumped normally.

Patch Changes

• addd725 #383 Thanks @Feiyang1! - Added an experimental flag onlyUpdatePeerDependentsWhenOutOfRange. When set to true, we only bump peer dependents when peerDependencies are leaving range.

3.0.0

Major Changes

• 2b49d66 #358 Thanks @Blasz! - Add new updateInternalDependencies config option to disable auto bumping of internal dependencies in the same release if the dependency was only patch bumped

2.0.1

Patch Changes

• 1706fb7 #321 Thanks @mitchellhamilton! - Fix TypeScript declarations

2.0.0

Major Changes

• 011d57f #313 Thanks @zkochan! - Add in none as a potential option for bumpType in release plans. Note that this is experimental and is internal, not a possible user option

1.0.1

Patch Changes

• 04ddfd7 #305 Thanks @Noviny! - Add link to changelog in readme

• e56928b #298 Thanks @eps1lon! - In changelog-github, throw more descriptive error when no options are provided.

1.0.0

Major Changes

• cc8c921 #290 Thanks @mitchellhamilton! - Rename ModCompWithWorkspace to ModCompWithPackage and change config key with packageJson

• cc8c921 #290 Thanks @mitchellhamilton! - Remove Workspace type. You should use the Package type from @manypkg/get-packages instead.

Minor Changes

• 41e2e3d #292 Thanks @acheronfail! - Add new Changeset type

Patch Changes

• 2363366 #291 Thanks @acheronfail! - Add baseBranch to Config type

0.4.0

Minor Changes

• 8f0a1ef #183 Thanks @mitchellhamilton! - Add PreState type and preState property to ReleasePlan

0.3.1

Patch Changes

• a679b1d #204 Thanks @Andarist! - Correctly handle the 'access' flag for packages

  Previously, we had access as "public" or "private", access "private" isn't valid. This was a confusing because there are three states for publishing a package:

  • private: true - the package will not be published to npm (worked)
  • access: public - the package will be publicly published to npm (even if it uses a scope) (worked)
  • access: restricted - the package will be published to npm, but only visible/accessible by those who are part of the scope. This technically worked, but we were passing the wrong bit of information in.

  Now, we pass the correct access options public or restricted.

0.3.0

Minor Changes

• 1ff73b7 #156 Thanks @mitchellhamilton! - Remove Changeset type because it isn't used and make commit optional on NewChangesetWithCommit because the commit won't always exist

Patch Changes

• 8c43fa0 #155 Thanks @Noviny! - Add Readme

0.2.0

Minor Changes

• 296a6731 - Safety bump: Towards the end of preparing changesets v2, there was a lot of chaos - this bump is to ensure every package on npm matches what is found in the repository.

0.1.2

Patch Changes

• a15abbf9 - Previous release shipped unbuilt code - fixing that

0.1.0

Minor Changes

• 6d119893 - Initial Release
• 519b4218 - Add WrittenConfig type and include all properties in Config type