changesets

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

1. A contributor adds a changeset file declaring affected packages, bump types, and a summary
2. The changeset file is committed alongside the code change in the PR
3. When ready to release, changeset version consumes all pending changesets and updates versions and changelogs
4. changeset publish publishes the updated packages to npm and creates git tags
5. 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.json versions, generates CHANGELOG.md entries, and bumps internal dependency ranges
• Publish command — Publishes updated packages to npm and creates git tags; must run immediately after version with 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 version produces prerelease versions (e.g., 1.0.0-beta.0) for testing before stable release
• Snapshot releases — Temporary 0.0.0-timestamp versions 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 Explore agent for repository-specific workflow discovery
• npm publishing issues: Use Task agent for debugging publish and registry authentication failures

If the turborepo skill is available, delegate build orchestration, task caching, and CI optimization to it. If the pnpm-workspace skill 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.

References

• Basic workflow: adding changesets, versioning, publishing, CI integration
• Monorepo setup: configuration, linked packages, fixed versioning, ignore patterns
• CI automation: GitHub Actions, automated PRs, snapshot releases, prerelease channels