# Changesets — Version and Changelog Management for Monorepos

> Changesets is a tool for managing versioning and changelogs in JavaScript and TypeScript monorepos by letting developers declare their changes in small markdown files that get consumed at release time.

## Install

Save in your project root:

# Changesets — Version and Changelog Management for Monorepos

## Quick Use
```bash
npm install --save-dev @changesets/cli
npx changeset init
npx changeset        # create a changeset
npx changeset version # bump versions
npx changeset publish # publish to npm
```

## 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

---
Source: https://tokrepo.com/en/workflows/e866204c-3bec-11f1-9bc6-00163e2b0d79
Author: AI Open Source