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