Changesets
Overview
Changesets is a versioning and changelog management tool focused on multi-package repositories. Contributors declare the semver impact of each change (major/minor/patch) via changeset files, then Changesets aggregates them to bump versions, update changelogs, and publish packages in a single coordinated release.
When to use: Monorepo versioning, automated changelog generation, coordinated multi-package releases, CI-driven publishing, prerelease/snapshot workflows.
When NOT to use: Single-file projects with no npm publishing, projects using commit-message-based versioning (semantic-release), manual version management without an npm registry, projects where a single maintainer controls all releases without PR collaboration.
How It Works
- A contributor adds a changeset file declaring affected packages, bump types, and a summary
- The changeset file is committed alongside the code change in the PR
- When ready to release,
changeset versionconsumes all pending changesets and updates versions and changelogs changeset publishpublishes the updated packages to npm and creates git tags- In CI, the official GitHub Action automates steps 3-4 via an auto-maintained "Version Packages" PR
Key Concepts
- Changeset file — A markdown file in
.changeset/declaring which packages are affected, their bump type (major/minor/patch), and a human-readable summary that appears in the changelog - Version command — Consumes all pending changeset files, calculates final version bumps, updates
package.jsonversions, generatesCHANGELOG.mdentries, and bumps internal dependency ranges - Publish command — Publishes updated packages to npm and creates git tags; must run immediately after
versionwith no commits in between - Linked packages — Packages that share the highest bump type within a release but maintain independent version numbers
- Fixed packages — Packages that always share the exact same version number across the group
- Prerelease mode — A mode where
versionproduces prerelease versions (e.g.,1.0.0-beta.0) for testing before stable release - Snapshot releases — Temporary
0.0.0-timestampversions for ad-hoc testing without affecting the main release line
Configuration Quick Reference
| Option | Default | Description |
|---|---|---|
changelog | "@changesets/cli/changelog" | Changelog generator package or false to disable |
commit | false | Auto-commit on version and add commands |
access | "restricted" | npm publish access; set "public" for public scoped packages |
baseBranch | "main" | Branch used for change detection |
linked | [] | Groups of packages that share highest bump type |
fixed | [] | Groups of packages that share exact version |
ignore | [] | Packages excluded from changeset versioning |
updateInternalDependencies | "patch" | When to bump dependents: "patch" or "minor" |
privatePackages | {version: true, tag: false} | Version/tag behavior for "private": true packages |
Quick Reference
| Pattern | Command / Config | Key Points |
|---|---|---|
| Initialize | npx @changesets/cli init | Creates .changeset/ folder with config |
| Add changeset | npx @changesets/cli add | Interactive prompt for packages and bump type |
| Add empty changeset | npx @changesets/cli add --empty | Declares no packages need versioning (satisfies CI) |
| Version packages | npx @changesets/cli version | Consumes changesets, bumps versions, updates changelogs |
| Publish packages | npx @changesets/cli publish | Publishes to npm, creates git tags |
| Check status | npx @changesets/cli status | Lists pending changesets; exits 1 if changes lack changesets |
| Status since branch | npx @changesets/cli status --since=main | Only checks changes since diverging from main |
| Enter prerelease | npx @changesets/cli pre enter <tag> | Enables prerelease mode (beta, alpha, rc, next) |
| Exit prerelease | npx @changesets/cli pre exit | Returns to normal versioning mode |
| Snapshot version | npx @changesets/cli version --snapshot | Creates 0.0.0-timestamp versions for testing |
| Snapshot publish | npx @changesets/cli publish --tag canary --no-git-tag | Publishes snapshot without overwriting latest dist-tag |
| Link packages | "linked": [["pkg-a", "pkg-b"]] in config | Packages share the highest version bump type |
| Fix packages | "fixed": [["pkg-*"]] in config | Packages share the exact same version number |
| Ignore packages | "ignore": ["pkg-internal"] in config | Excludes packages from changeset versioning |
| Public access | "access": "public" in config | Required for publishing public scoped packages |
| GitHub changelog | "changelog": ["@changesets/changelog-github",...] | Adds PR links and contributor attribution |
| Auto-commit | "commit": true in config | Version and add commands auto-commit changes |
| Internal deps | "updateInternalDependencies": "patch" in config | Controls when internal dependents get bumped |
Common Mistakes
| Mistake | Correct Pattern |
|---|---|
Committing between version and publish | Run publish immediately after version with no commits in between |
Forgetting --empty for PRs with no package changes | Use npx @changesets/cli add --empty to satisfy CI checks |
Using linked when packages must share exact versions | Use fixed for identical versions; linked only shares bump magnitude |
Setting access: "restricted" for public packages | Set access: "public" in config for public npm packages |
Not including fetch-depth: 0 in CI checkout | Full git history is needed for changeset detection |
Running publish without building first | Always run build step before changeset publish |
| Entering prerelease mode on main branch | Use a dedicated branch for prereleases to avoid blocking normal releases |
| Ignoring packages that others depend on | Ignored packages skip bumps, breaking dependents — use sparingly |
| Publishing snapshots with default tag | Always use --tag flag to avoid overwriting latest dist-tag |
Not setting NPM_TOKEN in CI environment | Both GITHUB_TOKEN and NPM_TOKEN are required for automated publishing |
Using changeset publish in CI without the action | The official changesets/action handles the two-mode workflow correctly |
Manually editing generated CHANGELOG.md | Edit changeset files instead; changelogs are regenerated on version |
Delegation
- CI pipeline debugging: Use
Exploreagent for repository-specific workflow discovery - npm publishing issues: Use
Taskagent for debugging publish and registry authentication failures
If theturboreposkill is available, delegate build orchestration, task caching, and CI optimization to it. If thepnpm-workspaceskill is available, delegate workspace setup, dependency linking, catalogs, and Docker deployment to it. See its monorepo integration reference for the end-to-end release pipeline.