Adopt Changesets

Goal

Set up @changesets/cli for proper semantic versioning, changelog generation, and npm publishing workflow.

Install

pnpm add -D @changesets/cli
pnpm changeset init

This creates a .changeset/ directory with a config.json.

Configure

Edit .changeset/config.json:

{
  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "master",
  "updateInternalDependencies": "patch",
  "ignore": []
}

Key settings:

• access: "public" for scoped packages (@scope/pkg), "restricted" for private
• baseBranch: match the project's main branch (master or main)
• commit: false: don't auto-commit version bumps (do it manually for review)

Workflow

For Contributors (per PR)

pnpm changeset
# Interactive: select packages, bump type (patch/minor/major), describe change

This creates a markdown file in .changeset/ that describes the change.

For Maintainers (release)

pnpm changeset version    # Updates package versions + CHANGELOG.md
git add . && git commit -m "chore: version packages"
pnpm changeset publish    # Publishes to npm
git push --follow-tags    # Push commits + version tags

Package.json Scripts

Add to root package.json:

{
  "scripts": {
    "changeset": "changeset",
    "version-packages": "changeset version",
    "release": "pnpm build && changeset publish"
  }
}

GitHub Actions (Optional)

Create .github/workflows/release.yml:

name: Release
on:
  push:
    branches: [master]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - name: Create Release PR or Publish
        uses: changesets/action@v1
        with:
          publish: pnpm release
          version: pnpm version-packages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

This creates a "Version Packages" PR that accumulates changesets, and publishes when merged.

prepublishOnly Script

Add to each publishable package's package.json:

{
  "scripts": {
    "prepublishOnly": "pnpm build && pnpm test && pnpm ts:check"
  }
}

npm Provenance

When publishing from GitHub Actions, add --provenance:

{
  "scripts": {
    "release": "pnpm build && changeset publish --provenance"
  }
}