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/assemble-release-plan

6.0.6

Patch Changes

• Updated dependencies [84a4a1b]:
  • @changesets/types@6.1.0
  • @changesets/get-dependents-graph@2.1.3
  • @changesets/should-skip-package@0.1.2

6.0.5

Patch Changes

• #1508 26c8ba9 Thanks @stevethedev! - Add error-reporting for when a changeset references a non-existent package

6.0.4

Patch Changes

• #1445 52c302a Thanks @bluwy! - Remove unused @babel/runtime dependency

• Updated dependencies [bc75c1a, 52c302a]:

  • @changesets/get-dependents-graph@2.1.2
  • @changesets/should-skip-package@0.1.1

6.0.3

Patch Changes

• Updated dependencies [dd6e5bb]:
  • @changesets/get-dependents-graph@2.1.1

6.0.2

Patch Changes

• Updated dependencies [5e9d33a]:
  • @changesets/get-dependents-graph@2.1.0

6.0.1

Patch Changes

• #1361 954a16a Thanks @jakebailey! - Version 2.25.0 introduced the privatePackage configuration option with default { version: false, tag: false }; due to a bug, these options were not respected in all commands, leading to commands like changeset tag still tagging private packages. This has been fixed, and all packages now respect this option.

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.

Patch Changes

• Updated dependencies [a971652]:
  • @changesets/get-dependents-graph@2.0.0
  • @changesets/errors@0.2.0
  • @changesets/types@6.0.0

5.2.4

Patch Changes

• #1176 41988ce Thanks @joshwooding! - Bump semver dependency to v7.5.3

• Updated dependencies [41988ce]:

  • @changesets/get-dependents-graph@1.3.6

5.2.3

Patch Changes

• Updated dependencies [521205d]:
  • @changesets/types@5.2.1
  • @changesets/get-dependents-graph@1.3.5

5.2.2

Patch Changes

• #949 64585ea Thanks @Andarist, @BPScott! - Fixed the issue that caused transitive dependents of dev dependents to be bumped when a package got bumped and when using ___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH.updateInternalDependents: "always". To illustrate this with an example:

  pkg-a - version: 1.0.0
  pkg-b - devDependencies['pkg-a']: 1.0.0
  pkg-c - dependencies['pkg-b']: 1.0.0

  With a changeset for pkg-a the pkg-c could have been sometimes incorrectly released.

• Updated dependencies [8c08469]:

  • @changesets/types@5.2.0
  • @changesets/get-dependents-graph@1.3.4

5.2.1

Patch Changes

• #914 b023e4b Thanks @Andarist! - Fixed an issue with the assembleReleasePlan's signature not being compatible with the old shape of the config and snapshot parameters. This could have caused runtime errors during snapshot releases when only some of the Changesets transitive dependencies were updated without other ones.

5.2.0

Minor Changes

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

Patch Changes

• Updated dependencies [dd9b76f]:
  • @changesets/types@5.1.0
  • @changesets/get-dependents-graph@1.3.3

5.1.3

Patch Changes

• #767 d6bfcc5 Thanks @Andarist! - Improve the error message when a package referenced in a changeset can't be found. The message will now also include the changeset's ID.

5.1.2

Patch Changes

• Updated dependencies [c87eba6]:
  • @changesets/types@5.0.0
  • @changesets/get-dependents-graph@1.3.2

5.1.1

Patch Changes

• #769 3e8e672 Thanks @Andarist! - Fixed an infinite loop involving a fixed group of packages and a package within that group that was both ignored and dependent on another package from that group.

5.1.0

Minor Changes

• #690 27a5a82 Thanks @Andarist! - Added handling of the fixed config option. This adds all the packages from the fixed group to the assembled release and added releases end up having the same version.

Patch Changes

• #706 0812858 Thanks @Andarist! - Fixed an issue with "none" releases causing package versions being bumped during snapshot releases. In addition to when you create "none" release types explicitly Changesets might create them implicitly in some situations, for example under some circumstances this issue caused snapshot releases to be created sometimes for ignored packages.

• #751 59c7ebc Thanks @Rugvip! - Fixed an issue where dependent packages would sometimes not get bumped properly when exiting prerelease mode.

• #703 15c461d Thanks @Andarist! - Fixed an issue with dependant packages being always bumped when their * dependency was bumped.

• Updated dependencies [27a5a82]:

  • @changesets/types@4.1.0
  • @changesets/get-dependents-graph@1.3.1

5.0.5

Patch Changes

• #693 1be201f Thanks @luciaquirke! - Fixed an issue with none release type sometimes overriding other release types and thus preventing a release from happening.

• Updated dependencies [6f9c9d6]:

  • @changesets/get-dependents-graph@1.3.0

5.0.4

Patch Changes

• #692 e4c4b29 Thanks @jakubmazanec! - Fix snapshot timestamp so its date part contains the correct date and the timestamp can be used for collation.

5.0.3

Patch Changes

• #667 fe8db75 Thanks @fz6m! - Upgraded @manypkg/get-packages dependency to fix getting correct packages in pnpm workspaces with exclude rules.

• Updated dependencies [fe8db75, 9a993ba]:

  • @changesets/get-dependents-graph@1.2.4
  • @changesets/types@4.0.2

5.0.2

Patch Changes

• Updated dependencies [74dda8c]:
  • @changesets/get-dependents-graph@1.2.3

5.0.1

Patch Changes

• Updated dependencies [e89e28a]:
  • @changesets/types@4.0.1
  • @changesets/get-dependents-graph@1.2.2

5.0.0

Major Changes

• #542 de2b4a5 Thanks @Andarist! - The accepted Config type has been changed - a new experimental option (updateInternalDependents) was added to it.

Patch Changes

• Updated dependencies [de2b4a5]:
  • @changesets/types@4.0.0
  • @changesets/get-dependents-graph@1.2.1

4.1.1

Patch Changes

• #441 8b9ac07 Thanks @joshlartz! - Fixed an issue with including dependents in the release plan for dependencies using workspace: protocol that had a none changeset for them.

4.1.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".

Patch Changes

• Updated dependencies [12f9a43]:
  • @changesets/get-dependents-graph@1.2.0
  • @changesets/types@3.3.0

4.0.1

Patch Changes

• e92cc01 #482 Thanks @jonathanmorley! - Fixed an issue with bumping a peer dependency using a "none" changeset type resulting in the dependent package being major bumped.

4.0.0

Major Changes

• ab98fe3 #454 Thanks @Andarist! - Returned releases in pre mode will have type of the highest bump type within the current release now, instead of having the highest bump type from among all changesets within this pre mode. So if you release a new prerelease including a major bump and later release the same package with a minor bump the assembled release will be of type minor - the final computed version will, of course, still be the next one for a major bump.

Patch Changes

• d1d987c #455 Thanks @Andarist! - Fixed an issue with linked package being assigned a non-none release type when another package from the linked set has been added to current releases and the package had just a none release type.

• 9d99bd1 #446 Thanks @Andarist! - Fixed an issue with dependent packages not being updated to their highest bump type in pre mode sometimes. This could happen when dependent packages were only versioned because of their dependencies being upgraded and not because of a dedicated changeset for those dependent packages.

  For the very same reason linked packages were also not always bumped correctly in pre mode to the highest bump type in a linked group.

3.0.1

Patch Changes

• d531dbd #412 Thanks @Feiyang1! - Fixed an issue with the same package specified as a different dependency type with different range types not being updated correctly for all of them.

3.0.0

Major Changes

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

Minor Changes

• 9dcc364 #371 Thanks @Feiyang1! - Added support for ignoring packages in the version command. The version of ignored packages will not be bumped, but their dependencies will still be bumped normally. This is useful when you have private packages, e.g. packages under development. It allows you to make releases for the public packages without changing the version of your private packages. To use the feature, you can define the ignore array in the config file with the name of the packages:

  {
    ...
    "ignore": ["pkg-a", "pkg-b"]
    ...
  }

  or you can pass the package names to the --ignore flag when using cli:

  yarn changeset version --ignore pkg-a --ignore --pkg-b

Patch Changes

• 00e768e #382 Thanks @Feiyang1! - Fix a bug where packages that shouldn't get released get patch releases when the pre mode is exit

• Updated dependencies [addd725, 9dcc364]:

  • @changesets/types@3.1.0

2.1.0

Minor Changes

• 6d0790a #359 Thanks @ajaymathur! - Add support for snapshot flag to version command. Usage: changeset version --snapshot [tag]. The updated version of the packages looks like 0.0.0[-tag]-YYYYMMDDHHMMSS where YYYY, MM, DD, HH, MM, and SS is the date and time of when the snapshot version is created. You can use this feature with the tag option in the publish command to publish packages under experimental tags from feature branches. To publish a snapshot version of a package under an experimental tag you can do:

  # Version packages to snapshot version
  changeset version --snapshot
  # Publish packages under experimental tag, keeping next and latest tag clean
  changeset publish --tag experimental

2.0.4

Patch Changes

• Updated dependencies [2b49d66]:
  • @changesets/types@3.0.0
  • @changesets/get-dependents-graph@1.1.3

2.0.3

Patch Changes

• 8469636 #344 Thanks @zkochan! - When both a dev dep and a prod dep of a dependent package are published, the version of the dependent package should be bumped. This fixes a regression introduced by #313.

2.0.2

Patch Changes

• d678da5 #324 Thanks @zkochan! - Dev dependencies that are installed via the link or file protocol are ignored.

• Updated dependencies [d678da5]:

  • @changesets/get-dependents-graph@1.1.2

2.0.1

Patch Changes

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

• Updated dependencies [1706fb7]:

  • @changesets/errors@0.1.4
  • @changesets/get-dependents-graph@1.1.1
  • @changesets/types@2.0.1

2.0.0

Major Changes

• 011d57f #313 Thanks @zkochan! - When the released package is only used as a dev dependency, the dependent package's version should not be bumped.

Patch Changes

• Updated dependencies [c3cc232, 011d57f]:
  • @changesets/get-dependents-graph@1.1.0
  • @changesets/types@2.0.0

1.0.1

Patch Changes

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

• b49e1cf #306 Thanks @Andarist! - Ignore node_modules when glob searching for packages. This fixes an issue with package cycles.

• Updated dependencies [04ddfd7, e56928b, b49e1cf]:

  • @changesets/config@1.0.1
  • @changesets/errors@0.1.3
  • @changesets/get-dependents-graph@1.0.1
  • @changesets/types@1.0.1

1.0.0

Major Changes

• cc8c921 #290 Thanks @mitchellhamilton! - Accept Packages object instead of Workspace[] and remove dependentsGraph argument

Patch Changes

• Updated dependencies [41e2e3d, cc8c921, cc8c921, 2363366, cc8c921, cc8c921]:
  • @changesets/types@1.0.0
  • @changesets/get-dependents-graph@1.0.0
  • @changesets/config@1.0.0

0.3.1

Patch Changes

• 1282ef6 #263 Thanks @mitchellhamilton! - Fixed a bug where only the unreleased pre-release changesets were taken into account when calculating the new version, not previously released changesets.

0.3.0

Minor Changes

• 8f0a1ef #183 Thanks @mitchellhamilton! - Add support for prereleases. For more information, see the docs on prereleases.

Patch Changes

• Updated dependencies [8f0a1ef, 8f0a1ef, 8f0a1ef]:
  • @changesets/types@0.4.0
  • @changesets/errors@0.1.2
  • @changesets/config@0.2.3

0.2.1

Patch Changes

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

• Updated dependencies [8c43fa0, 1ff73b7]:

  • @changesets/types@0.3.0
  • @changesets/config@0.2.1

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.

Patch Changes

• Updated dependencies [296a6731]:
  • @changesets/config@0.2.0
  • @changesets/types@0.2.0

0.1.2

Patch Changes

• a15abbf9 - Previous release shipped unbuilt code - fixing that

0.1.0

Minor Changes

• 84aeb37f - Initial release

Patch Changes

• 519b4218 - Use new Config type which makes linked required

• Updated dependencies [519b4218]:

• Updated dependencies [519b4218]:
  • @changesets/config@0.1.0
  • @changesets/types@0.1.0