DEV Community

Alex Spinov
Alex Spinov

Posted on

Changesets Has a Free Versioning Tool That Makes npm Publishing Painless

#changesets #npm #publishing #monorepo

Publishing npm packages is error-prone: forget to bump the version, write a changelog, or publish a dependency first. Changesets automates all of it.

The Problem

Manual publishing:

  1. Remember which packages changed
  2. Decide version bumps (patch? minor? major?)
  3. Write CHANGELOG entries
  4. Update package.json versions
  5. Publish in the right order (dependencies first)
  6. Create git tags

Miss one step → broken release.

How Changesets Works

1. Add a Changeset 

npx changeset
# Interactive prompt:
# Which packages changed? (select with space)
# Is it a major/minor/patch change?
# Write a summary of the change
Enter fullscreen mode Exit fullscreen mode

This creates a markdown file in .changeset/:

---
"@repo/ui": minor
"@repo/utils": patch
---

Added new Button variant and fixed utility type export.
Enter fullscreen mode Exit fullscreen mode

2. Version (Before Release) 

npx changeset version
Enter fullscreen mode Exit fullscreen mode

This:

  • Bumps versions in all affected package.json files
  • Generates/updates CHANGELOG.md for each package
  • Handles dependency version updates
  • Deletes consumed changeset files

3. Publish 

npx changeset publish
Enter fullscreen mode Exit fullscreen mode

Publishes all packages with new versions to npm, in the correct dependency order.

Setup 

npm install @changesets/cli
npx changeset init
Enter fullscreen mode Exit fullscreen mode 
// .changeset/config.json
{
  "$schema": "https://github.com/changesets/changesets/blob/main/packages/config/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch"
}
Enter fullscreen mode Exit fullscreen mode

GitHub Actions (Automated Releases) 

# .github/workflows/release.yml
name: Release
on:
  push:
    branches: [main]
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - name: Create Release PR or Publish
        uses: changesets/action@v1
        with:
          publish: npx changeset publish
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

This creates a "Version Packages" PR that:

  • Shows all pending changesets
  • Bumps versions when merged
  • Publishes to npm automatically

Linked Packages 

{
  "linked": [["@repo/react", "@repo/vue", "@repo/svelte"]]
}
Enter fullscreen mode Exit fullscreen mode

Linked packages always have the same version. Bump one → bump all.

Snapshot Releases (Pre-releases) 

npx changeset version --snapshot canary
npx changeset publish --tag canary
# Publishes: @repo/ui@0.0.0-canary-20260330
Enter fullscreen mode Exit fullscreen mode

Perfect for testing unreleased changes.

Who Uses Changesets

  • Vercel (Next.js, Turborepo, SWR)
  • Chakra UI
  • Radix UI
  • Mantine
  • Pnpm
  • Most major open-source monorepos

Need help with package publishing or monorepo setup? I build developer tools and infrastructure. Email spinov001@gmail.com or check my Apify tools.

Top comments (0)