Changesets — Version and Changelog Management for Monorepos

Introduction

Changesets provides a structured workflow for versioning and publishing packages in JavaScript monorepos. Instead of deriving versions from commit messages, developers explicitly create small markdown files (changesets) that describe what changed and the semver impact. At release time, these changesets are consumed to calculate version bumps, update changelogs, and publish affected packages.

What Changesets Does

• Lets developers create changeset markdown files describing changes and their semver impact
• Calculates version bumps across interdependent packages in a monorepo at release time
• Generates per-package CHANGELOG.md files from accumulated changesets
• Publishes updated packages to npm with correct version numbers and dependency updates
• Provides a GitHub bot that comments on PRs to remind contributors to add changesets

Architecture Overview

Changesets stores pending changes as markdown files in a .changeset/ directory. Each file lists the affected packages and the bump type (major, minor, patch) plus a human-written summary. The changeset version command reads all pending files, resolves dependencies between packages, bumps version numbers in every affected package.json, writes CHANGELOG entries, and deletes the consumed changeset files. The changeset publish command then publishes packages with new versions to the registry.

Self-Hosting & Configuration

• Install with npm install --save-dev @changesets/cli and run npx changeset init
• Configure .changeset/config.json to set the changelog format, commit behavior, and access level
• Add the @changesets/changelog-github package for GitHub-linked changelog entries with PR references
• Set up the Changesets GitHub Action or bot to automate version PRs and publishing in CI
• Configure linked or fixed package groups for packages that should version together

Key Features

• Explicit change declarations give developers full control over version semantics
• Handles transitive dependency bumps across packages in complex monorepo dependency graphs
• Pre-release mode for publishing alpha and beta versions from feature branches
• Snapshot releases create temporary versions for testing unreleased changes
• Works with npm, yarn, and pnpm workspaces out of the box

Comparison with Similar Tools

• semantic-release — Fully automatic from commits; Changesets requires explicit developer intent per change
• Lerna — Includes versioning and publishing but uses commit-based version detection; Changesets adds changeset files
• release-please — Google's approach uses PR-based release proposals; Changesets uses file-based change declarations
• Turborepo — Handles build orchestration in monorepos but does not manage versioning or publishing
• Rush — Microsoft's monorepo tool with its own change file system; heavier setup than Changesets

FAQ

Q: When should I create a changeset? A: Create a changeset whenever you make a user-facing change to a package. Run npx changeset and follow the prompts to select packages and bump types.

Q: What happens if I forget to add a changeset? A: The Changesets GitHub bot will comment on your PR reminding you. The release process will not bump versions for undocumented changes.

Q: Can I use Changesets for a single-package repo? A: Yes. Changesets works for single packages too, providing the same structured changelog and versioning workflow.

Q: How do snapshot releases work? A: Run npx changeset version --snapshot preview to create a temporary version like 0.0.0-preview-20240101 for testing.

Sources

• https://github.com/changesets/changesets
• https://github.com/changesets/changesets/blob/main/docs/intro-to-using-changesets.md