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:

1. Install @changesets/cli and run npx changeset init to create .changeset/config.json
2. Configure @changesets/changelog-github for PR links and author attribution
3. Add changesets/action to GitHub Actions for automatic "Version Packages" PR creation
4. 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:

1. Run npx changeset and select the core package with major bump
2. Write a description of the breaking change for the changelog
3. Run npx changeset version which bumps the core package and patches all dependents
4. 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.