Changesets
Overview
Changesets is a versioning and changelog management tool for JavaScript/TypeScript monorepos. Developers add changeset files describing their changes, then CI consumes them to bump package versions, generate changelogs, and publish to npm with coordinated releases across interdependent packages.
Instructions
- When adding a change, run
npx changeset, select affected packages, choose the semver bump type (patch, minor, major), write a user-facing description, and commit the generated .changeset/xxx.md file with the PR.
- When releasing versions, run
npx changeset version to consume pending changesets, bump package.json versions, update CHANGELOG.md per package, and handle dependency bumps automatically.
- When publishing, run
npx changeset publish to publish changed packages to npm, create git tags, and skip unchanged packages.
- When automating with CI, use
changesets/action in GitHub Actions to automatically create a "Version Packages" PR and publish on merge.
- When coordinating packages, use
linked for packages that must share the same version (CLI + SDK) and fixed for monorepo-wide versioning.
- When testing pre-releases, use snapshot releases (
--snapshot preview) for CI testing or pre-release mode (changeset pre enter next) for -next.0 versions.
Examples
Example 1: Set up automated releases for a monorepo
User request: "Configure Changesets for automated versioning and publishing in my Turborepo monorepo"
Actions:
- Install
@changesets/cli and run npx changeset init to create .changeset/config.json
- Configure
@changesets/changelog-github for PR links and author attribution
- Add
changesets/action to GitHub Actions for automatic "Version Packages" PR creation
- Set up CI check that requires a changeset file on PRs affecting published packages
Output: A monorepo with automated versioning, changelog generation, and npm publishing triggered by merging the version PR.
Example 2: Coordinate a breaking change across multiple packages
User request: "Release a major version bump for our core package and patch bumps for all dependents"
Actions:
- Run
npx changeset and select the core package with major bump
- Write a description of the breaking change for the changelog
- Run
npx changeset version which bumps the core package and patches all dependents
- Review the generated changelogs and version bumps, then merge
Output: A coordinated release with a major bump on the core package and automatic patch bumps on all dependent packages.
Guidelines
- Require changesets on every PR that affects published packages and enforce with a CI check.
- Write changeset descriptions for users, not developers: "Fixed button hover state" not "Refactored CSS modules."
- Use
linked for packages that must stay in sync, such as CLI and SDK pairs.
- Use snapshot releases for testing PRs since they publish
0.0.0-timestamp versions for CI testing.
- Use
@changesets/changelog-github for open-source projects to include PR links and author attribution.
- Keep
.changeset/config.json in the repo root as project configuration.
1---2name: changesets3description: Assists with managing versioning and changelogs in JavaScript/TypeScript monorepos using Changesets. Use when automating semantic versioning, generating changelogs from PRs, coordinating multi-package releases, or publishing to npm. Trigger words: changesets, versioning, changelog, npm publish, monorepo release, semver.4license: Apache-2.05---67# Changesets89## Overview1011Changesets is a versioning and changelog management tool for JavaScript/TypeScript monorepos. Developers add changeset files describing their changes, then CI consumes them to bump package versions, generate changelogs, and publish to npm with coordinated releases across interdependent packages.1213## Instructions1415- When adding a change, run `npx changeset`, select affected packages, choose the semver bump type (patch, minor, major), write a user-facing description, and commit the generated `.changeset/xxx.md` file with the PR.16- When releasing versions, run `npx changeset version` to consume pending changesets, bump `package.json` versions, update `CHANGELOG.md` per package, and handle dependency bumps automatically.17- When publishing, run `npx changeset publish` to publish changed packages to npm, create git tags, and skip unchanged packages.18- When automating with CI, use `changesets/action` in GitHub Actions to automatically create a "Version Packages" PR and publish on merge.19- When coordinating packages, use `linked` for packages that must share the same version (CLI + SDK) and `fixed` for monorepo-wide versioning.20- When testing pre-releases, use snapshot releases (`--snapshot preview`) for CI testing or pre-release mode (`changeset pre enter next`) for `-next.0` versions.2122## Examples2324### Example 1: Set up automated releases for a monorepo2526**User request:** "Configure Changesets for automated versioning and publishing in my Turborepo monorepo"2728**Actions:**291. Install `@changesets/cli` and run `npx changeset init` to create `.changeset/config.json`302. Configure `@changesets/changelog-github` for PR links and author attribution313. Add `changesets/action` to GitHub Actions for automatic "Version Packages" PR creation324. Set up CI check that requires a changeset file on PRs affecting published packages3334**Output:** A monorepo with automated versioning, changelog generation, and npm publishing triggered by merging the version PR.3536### Example 2: Coordinate a breaking change across multiple packages3738**User request:** "Release a major version bump for our core package and patch bumps for all dependents"3940**Actions:**411. Run `npx changeset` and select the core package with `major` bump422. Write a description of the breaking change for the changelog433. Run `npx changeset version` which bumps the core package and patches all dependents444. Review the generated changelogs and version bumps, then merge4546**Output:** A coordinated release with a major bump on the core package and automatic patch bumps on all dependent packages.4748## Guidelines4950- Require changesets on every PR that affects published packages and enforce with a CI check.51- Write changeset descriptions for users, not developers: "Fixed button hover state" not "Refactored CSS modules."52- Use `linked` for packages that must stay in sync, such as CLI and SDK pairs.53- Use snapshot releases for testing PRs since they publish `0.0.0-timestamp` versions for CI testing.54- Use `@changesets/changelog-github` for open-source projects to include PR links and author attribution.55- Keep `.changeset/config.json` in the repo root as project configuration.
eliferjunior