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 version consumes all pending changesets and updates versions and changelogs
changeset publish publishes 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.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
1---
2name: changesets
3description: 'Changesets for versioning and changelog management in monorepos. Use when managing package versions, generating changelogs, or publishing packages. Use for changesets, versioning, changelog, semver, monorepo-versioning, release, publish, bump.'
4license: MIT
5metadata:
6 author: oakoss
7 version: '1.2'
8 source: 'https://github.com/changesets/changesets'
9user-invocable: false
10---
11
12# Changesets
13
14## Overview
15
16Changesets 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.
17
18**When to use:** Monorepo versioning, automated changelog generation, coordinated multi-package releases, CI-driven publishing, prerelease/snapshot workflows.
19
20**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.
21
22### How It Works
23
241. A contributor adds a changeset file declaring affected packages, bump types, and a summary
252. The changeset file is committed alongside the code change in the PR
263. When ready to release, `changeset version` consumes all pending changesets and updates versions and changelogs
274. `changeset publish` publishes the updated packages to npm and creates git tags
285. In CI, the official GitHub Action automates steps 3-4 via an auto-maintained "Version Packages" PR
29
30## Key Concepts
31
32- **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
33- **Version command** — Consumes all pending changeset files, calculates final version bumps, updates `package.json` versions, generates `CHANGELOG.md` entries, and bumps internal dependency ranges
34- **Publish command** — Publishes updated packages to npm and creates git tags; must run immediately after `version` with no commits in between
35- **Linked packages** — Packages that share the highest bump type within a release but maintain independent version numbers
36- **Fixed packages** — Packages that always share the exact same version number across the group
37- **Prerelease mode** — A mode where `version` produces prerelease versions (e.g., `1.0.0-beta.0`) for testing before stable release
38- **Snapshot releases** — Temporary `0.0.0-timestamp` versions for ad-hoc testing without affecting the main release line
39
40## Configuration Quick Reference
41
42| Option | Default | Description |
43| ---------------------------- | ------------------------------- | ------------------------------------------------------------- |
44| `changelog` | `"@changesets/cli/changelog"` | Changelog generator package or `false` to disable |
45| `commit` | `false` | Auto-commit on `version` and `add` commands |
46| `access` | `"restricted"` | npm publish access; set `"public"` for public scoped packages |
47| `baseBranch` | `"main"` | Branch used for change detection |
48| `linked` | `[]` | Groups of packages that share highest bump type |
49| `fixed` | `[]` | Groups of packages that share exact version |
50| `ignore` | `[]` | Packages excluded from changeset versioning |
51| `updateInternalDependencies` | `"patch"` | When to bump dependents: `"patch"` or `"minor"` |
52| `privatePackages` | `{ version: true, tag: false }` | Version/tag behavior for `"private": true` packages |
53
54## Quick Reference
55
56| Pattern | Command / Config | Key Points |
57| ------------------- | ------------------------------------------------------- | ------------------------------------------------------------ |
58| Initialize | `npx @changesets/cli init` | Creates `.changeset/` folder with config |
59| Add changeset | `npx @changesets/cli add` | Interactive prompt for packages and bump type |
60| Add empty changeset | `npx @changesets/cli add --empty` | Declares no packages need versioning (satisfies CI) |
61| Version packages | `npx @changesets/cli version` | Consumes changesets, bumps versions, updates changelogs |
62| Publish packages | `npx @changesets/cli publish` | Publishes to npm, creates git tags |
63| Check status | `npx @changesets/cli status` | Lists pending changesets; exits 1 if changes lack changesets |
64| Status since branch | `npx @changesets/cli status --since=main` | Only checks changes since diverging from main |
65| Enter prerelease | `npx @changesets/cli pre enter <tag>` | Enables prerelease mode (beta, alpha, rc, next) |
66| Exit prerelease | `npx @changesets/cli pre exit` | Returns to normal versioning mode |
67| Snapshot version | `npx @changesets/cli version --snapshot` | Creates 0.0.0-timestamp versions for testing |
68| Snapshot publish | `npx @changesets/cli publish --tag canary --no-git-tag` | Publishes snapshot without overwriting latest dist-tag |
69| Link packages | `"linked": [["pkg-a", "pkg-b"]]` in config | Packages share the highest version bump type |
70| Fix packages | `"fixed": [["pkg-*"]]` in config | Packages share the exact same version number |
71| Ignore packages | `"ignore": ["pkg-internal"]` in config | Excludes packages from changeset versioning |
72| Public access | `"access": "public"` in config | Required for publishing public scoped packages |
73| GitHub changelog | `"changelog": ["@changesets/changelog-github", ...]` | Adds PR links and contributor attribution |
74| Auto-commit | `"commit": true` in config | Version and add commands auto-commit changes |
75| Internal deps | `"updateInternalDependencies": "patch"` in config | Controls when internal dependents get bumped |
76
77## Common Mistakes
78
79| Mistake | Correct Pattern |
80| ------------------------------------------------------ | ------------------------------------------------------------------------- |
81| Committing between `version` and `publish` | Run `publish` immediately after `version` with no commits in between |
82| Forgetting `--empty` for PRs with no package changes | Use `npx @changesets/cli add --empty` to satisfy CI checks |
83| Using `linked` when packages must share exact versions | Use `fixed` for identical versions; `linked` only shares bump magnitude |
84| Setting `access: "restricted"` for public packages | Set `access: "public"` in config for public npm packages |
85| Not including `fetch-depth: 0` in CI checkout | Full git history is needed for changeset detection |
86| Running `publish` without building first | Always run build step before `changeset publish` |
87| Entering prerelease mode on main branch | Use a dedicated branch for prereleases to avoid blocking normal releases |
88| Ignoring packages that others depend on | Ignored packages skip bumps, breaking dependents — use sparingly |
89| Publishing snapshots with default tag | Always use `--tag` flag to avoid overwriting `latest` dist-tag |
90| Not setting `NPM_TOKEN` in CI environment | Both `GITHUB_TOKEN` and `NPM_TOKEN` are required for automated publishing |
91| Using `changeset publish` in CI without the action | The official `changesets/action` handles the two-mode workflow correctly |
92| Manually editing generated `CHANGELOG.md` | Edit changeset files instead; changelogs are regenerated on `version` |
93
94## Delegation
95
96- **CI pipeline debugging**: Use `Explore` agent for repository-specific workflow discovery
97- **npm publishing issues**: Use `Task` agent for debugging publish and registry authentication failures
98
99> If the `turborepo` skill is available, delegate build orchestration, task caching, and CI optimization to it.
100> 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.
101
102## References
103
104- [Basic workflow: adding changesets, versioning, publishing, CI integration](references/basic-workflow.md)
105- [Monorepo setup: configuration, linked packages, fixed versioning, ignore patterns](references/monorepo-setup.md)
106- [CI automation: GitHub Actions, automated PRs, snapshot releases, prerelease channels](references/ci-automation.md)
oakoss