Using Changesets for Monorepo Version Management: Workflow, Commands, and Limitations

Changesets is a popular open‑source tool for version and changelog management in monorepo projects, used by repositories such as pnpm and mobx, with roughly 2k stars on GitHub.

The author’s team replaced Lerna with a customized Changesets‑based solution because Lerna suffered from issues like unreliable ignoreChanges , incorrect version bumps via lerna version , incomplete changelog generation, lifecycle script conflicts, high CI customization cost, and lack of workspace protocol support.

The Changesets workflow focuses on three aspects: identifying packages to publish, determining the semver level of the version bump, and providing changelog information. Developers add a markdown changeset file after completing work, and maintainers later consume these files to update package versions and generate changelogs before publishing.

Key CLI commands include:

init : runs changeset init to create a .changeset folder with default configuration.

add : runs changeset add to generate a changeset file; it uses getPackages() from @manypkg/get-packages to list sub‑packages and git diff to suggest changed packages.

version : runs changeset version to consume all pending changeset files, bump package versions (using @changesets/assemble-release-plan and @changesets/apply-release-plan ), and update changelogs.

Other commands such as changeset pre , changeset status , and changeset publish support prerelease handling, status inspection, and a wrapped npm publish process.

Current limitations of the upstream Changesets project include random changeset file names (generated by the human-id library), lack of package‑level filtering for commands like add and version , cumbersome prerelease workflows, and limited maintenance activity and documentation.

The author’s fork addresses some of these issues by customizing the filename format (branch‑name+user‑id) via @changesets/write and integrating pnpm’s filter mechanism to allow selective operation on specific packages.

Overall, Changesets provides a flexible and powerful solution for monorepo release management, giving developers fine‑grained control over version bumps and changelog content, though some workflow friction and tooling gaps remain.