Changesets
Last modified on Wed 25 Sep 2024

🦋 A way to manage your versioning and changelogs with a focus on monorepos

Features

changesets offer a solution to the problem of organizing package releases and grouping changes effectively. Here's why you should consider using changesets:

Find more information about changesets in the official documentation

Setup

Install

First, install the @changesets/cli package in the repository where you want to use changesets:

pnpm install -D -E @changesets/cli

Once installed, initialize the repository to use changesets:

pnpm changeset init

Github Actions

Although changesets can function without continuous integration (CI), it's recommended to use it with a CI system to automate versioning and publishing. You can utilize the Github Action provided by the changesets team.

To use the action, create a .github/workflows/release.yml file. Follow the instructions under the With Publishing section in the documentation, with minor adjustments. This flow updates the versions of changed packages and publishes them to npm registry.

name: Release

on:
  push:
    branches:
      # Make sure to check the branch name here; usual values are `main` and `master`
      - master

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

jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repo
        uses: actions/checkout@v4

      # Corepack makes sure to use correct Node.js version for your project, it requires having "engines" specified in package.json file
      # Read more about Corepack and advanced dependencies caching at: https://infinum.com/handbook/frontend/node/managing-node-npm-versions
      - name: 🗃️ Enable corepack
        run: corepack enable
        shell: bash

      - name: Setup Node.js
        uses: actions/setup-node@v4

      - name: Install Dependencies
        run: pnpm install --prod --frozen-lockfile

      - name: Create Release Pull Request or Publish to npm registry
        id: changesets
        uses: changesets/action@v1
        with:
          publish: pnpm ci:publish
          # if your repository is using conventional commits, you should use the following option (the message can be customized)
          # commit: 'ci: version packages'
        env:
          # GITHUB_TOKEN is required for creating a pull request and will be provided by the Github Action automatically
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # NPM_TOKEN is required for publishing to registry and needs to be provided manually
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

      # This step will push tags to the repository after the packages are published and will create a new release on Github
      - name: Push git tag after publish
        if: steps.changesets.outputs.published == 'true'
        run: git push --follow-tags

Before using the action, ensure the following checklist is complete:

Changeset Bot

Changeset bot is a GitHub bot that further automates package publishing. It's recommended to install it in the repository. Refer to the official documentation for more details. Ask your TL, TD, or PE to install it.

Usage

When you finish making changes, create a PR as usual. The bot will add a comment with a link to add a changeset file. This action should be performed by a repo maintainer or someone responsible for releases. The changeset file will look like this:

---
'@infinum/new-package': patch
---

This is a patch release because of a bug fix.

Once the PR is merged, the GitHub Action will create a new release, bump the version, and publish the package to registry. It removes the generated changesets, preparing for the next release.

When a release is ready, responsible person will merge the PR and the Github Action will publish the package to registry. It will also create a new tag and a Github release.

Pre-releases

Changesets can be used to create pre-releases. It is not as easy as regular releases, but it is well documented in the official documentation.

Please proceed with caution when creating pre-releases.

First thing you need to do is to enter the pre-release mode:

pnpm changeset pre <tag>

Most often for <tag> we will use beta but you can use any tag you want - e.g. alpha, rc, next, etc.

As a result, a new file will be created in the .changeset folder. Next thing to do is to update the version of the package you want to release. You can do that by using the changeset version command:

pnpm changeset version

Now, we need to commit the version change and the changeset file:

git add .
git commit -m "chore: release <tag>"

Once commited, we can publish the package:

pnpm changeset publish

IMPORTANT: Make sure to use changeset publish command instead of pnpm publish because pnpm does not know that we are in prerelease mode.

After publishing, we can push the tag to the origin and create a new release manually.

git push --follow-tags

Once you are done with the pre-release, you can exit the pre-release mode:

pnpm changeset exit pre

This will create changes in your code so make sure to also commit them.

git add .
git commit -m "chore: exit pre-release mode"

See it in action

Changesets are already implemented in a few repositories. Check them out to see how they work:

Resources