Implementing Changeset Version Management with Claude Code

Systematic Version Management With Changesets

Changesets is a tool that automates package version management and CHANGELOG generation. It really shines in monorepo environments, letting you build a consistent release flow that takes inter-package dependencies into account. Claude Code can help with everything from configuration to CI integration.

Initial Setup

Let’s ask Claude Code to handle the setup.

> Introduce Changesets into a monorepo project.
> Include automated releases via GitHub Actions and CHANGELOG generation.

# Install
npm install -D @changesets/cli @changesets/changelog-github

# Initialize
npx changeset init

// .changeset/config.json
{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": [
    "@changesets/changelog-github",
    { "repo": "your-org/your-repo" }
  ],
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": [],
  "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
    "onlyUpdatePeerDependentsWhenOutOfRange": true
  }
}

Creating a Changeset

Here’s how to create a changeset file that describes what changed.

# Create a changeset interactively
npx changeset

<!-- .changeset/happy-dogs-fly.md -->
---
"@myapp/ui": minor
"@myapp/utils": patch
---

Added an "outline" variant to the Button component.
Improved type definitions for utility functions.

Example prompt for asking Claude Code to create a changeset.

> Create a changeset for the current changes.
> Apply a minor version bump to @myapp/ui and write the description.

Configuring npm Scripts

// package.json
{
  "scripts": {
    "changeset": "changeset",
    "changeset:status": "changeset status",
    "version": "changeset version",
    "release": "changeset publish",
    "prerelease": "npm run build"
  }
}

Automating Releases With GitHub Actions

A workflow that opens a version bump PR automatically on PR merge and publishes to npm once that PR is merged.

# .github/workflows/release.yml
name: Release

on:
  push:
    branches: [main]

concurrency: ${{ github.workflow }}-${{ github.ref }}

permissions:
  contents: write
  pull-requests: write
  packages: write

jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: "https://registry.npmjs.org"

      - run: npm ci
      - run: npm run build

      - name: Create Release Pull Request or Publish
        id: changesets
        uses: changesets/action@v1
        with:
          version: npm run version
          publish: npm run release
          title: "chore: version packages"
          commit: "chore: version packages"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Advanced Settings for Monorepos

Configuration patterns that manage coordination between packages.

// .changeset/config.json
{
  "changelog": [
    "@changesets/changelog-github",
    { "repo": "your-org/your-repo" }
  ],
  "commit": false,
  "fixed": [
    ["@myapp/core", "@myapp/cli"]
  ],
  "linked": [
    ["@myapp/ui", "@myapp/theme"]
  ],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch"
}

• fixed - Groups of packages that always share the same version
• linked - Groups of packages whose versions are bumped together

Managing Pre-Releases

Release flow for beta or RC versions.

# Enter pre-release mode
npx changeset pre enter beta

# Add a changeset
npx changeset

# Apply the pre-release version
npx changeset version
# => 1.0.0 -> 1.1.0-beta.0

# Publish
npx changeset publish

# Exit pre-release mode
npx changeset pre exit

Validating Changesets

A workflow that checks in CI whether a PR includes a changeset.

# .github/workflows/changeset-check.yml
name: Changeset Check

on:
  pull_request:
    branches: [main]

jobs:
  changeset-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - name: Check for changeset
        run: npx changeset status --since=origin/main

Custom CHANGELOG Format

A pattern for customizing the CHANGELOG output.

// .changeset/changelog-config.ts
import type { ChangelogFunctions } from "@changesets/types";

const changelogFunctions: ChangelogFunctions = {
  getDependencyReleaseLine: async () => "",
  getReleaseLine: async (changeset, type) => {
    const [firstLine, ...rest] = changeset.summary
      .split("\n")
      .map((l) => l.trimEnd());

    const date = new Date().toISOString().slice(0, 10);

    let returnVal = `- ${firstLine}`;

    if (rest.length > 0) {
      returnVal += `\n${rest.map((l) => `  ${l}`).join("\n")}`;
    }

    return returnVal;
  },
};

export default changelogFunctions;

Summary

Changesets is a powerful tool for automating systematic version management and release flows. With Claude Code, you can efficiently build everything from initial setup to CI integration and monorepo support.

For monorepo management techniques, see the monorepo management guide, and for CI/CD pipeline design, see the CI/CD setup guide. You should also check out the official Changesets documentation.