In today’s coding landscape, monorepos are all the rage. They offer a centralized, streamlined approach to managing multiple packages within a single repository.

But here’s the kicker: we often want independent versioning for these packages. If we were to do this manually, it would be a real hassle. That’s where 🦋 Changesets come into play.

By offering a clear and efficient way to manage independent versioning for packages within a single repository, Changesets has become a crucial addition to the toolkit of many developers and organizations.

Let’s dive into the magic of this technology and see how they simplify the complex world of monorepo versioning.

Project Structure

Following is the project structure of our sample monorepo. This repository contains five packages, four of which are private and one that is public. The private packages are marked with “private”: true in their package.json files, indicating that they’re not meant to be published to npm.

├── apps
│ ├── docs (Private)
│ └── web (Private)
├── packages
│ ├── eslint-config-custom (Private)
│ ├── tsconfig (Private)
│ └── ui (Public)

Changesets Process

Let’s take a high-level look at what really happens with Changesets. In a nutshell, a developer can open a pull request (PR) with or without a changeset. By default, a changeset is not mandatory for a PR because not all changes require a release. However, when they do want to release one or multiple packages, they can include a changeset in the PR. Then Changesets will automate the versioning and release process.

Changesets Process💡 If you want to delve deeper into the design decisions of Changesets, you can find a detailed explanation in the official documentation.

Lets get started 🚀

Step 01: Install the Changesets CLI

To get started, we need to install the Changesets CLI package at the root of the mono repo. If you’re using pnpm, you can use the -w flag to bypass any warnings related to adding dependencies to the workspace root.

pnpm add @changesets/cli -w💡 For npm users, a simple npm install @changesets/cli will suffice.

Step 02: Initialize Changesets

Initializing Changesets in your project is straightforward. Run the following command, and it will create a .changeset folder containing a config.json file and a file.

pnpm changeset initTerminal output after initializing Changesets

Step 03: Customizing the Changeset Config

By default, Changesets only publishes and versions npm-publishable public packages in the repository. However, you might want to version and tag private packages too.

To achieve this, update the .changeset/config.json file with the following configuration:

“privatePackages”: {
“version”: true,
“tag”: true
…// rest

Feel free to tailor the config.json to match your specific requirements.

Step 04: Enhancing the Workflow with Scripts

To streamline the release process, let’s add some helpful scripts to your package.json.

“scripts”: {
“changeset”: “changeset”,
“publish:packages”: “changeset publish”,
“version:packages”: “changeset version”
}“changeset”: “changeset” : Execute the Changeset CLI using npm. This lets you use npm run changeset to invoke the CLI instead of using npx.“publish:packages”: “changeset publish” : This publishes any unpublished packages to npm, and creates git tags.“version:packages”: “changeset version” : Takes Changesets that have been made, updates versions and dependencies of packages, and writes changelogs. This command handles all file changes related to versions before publishing to npm.

Step 05: Add Changeset Bot to the repository

When a pull request (PR) is submitted, the Changeset bot evaluates the diff and comments on the PR if a changest is available or not.

Changeset bot in action

The bot is extremely useful to remind you of any pending Changesets that you might forget to add to your PR.

Step 06: Create your first Changeset

Once you are happy with your code in the PR, you can generate a changeset if you wish to release certain packages. To do this execute the folliwing command.

pnpm changeset

After the above is executed, you’ll see a set of prompts.

First, select the package or packages you want to include in the changeset (💡 Use the up/down arrows to navigate and the space bar to select).Prompt 01: Terminal output of generating a changeset

2. Next, choose the type of release you want to perform, whether it’s Major, Minor, or Patch.

3. Finally, provide a meaningful message. Keep in mind that this message will appear in the CHANGELOG of the respective package(s). Always write a message with context and meaning.

Prompt 02: Terminal output of generating a changeset

A sample changeset generated from the flow mentioned in the screenshots would appear like the following. The file name would be random.

“docs”: patch
“web”: patch
“@brionmario-experimental/eslint-config-changesets-mono-repo”: patch
“@brionmario-experimental/changesets-mono-repo-tsconfig”: patch
“@brionmario-experimental/changesets-mono-repo-ui”: patch

Initial release 🚀

Step 07: Configure GitHub action

Now, let’s set up the GitHub Actions workflow to automate the release process. Here’s how you can do it:

# This workflow will release the packages with Changesets

name: 🚀 Release

– main

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

GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

name: 🚀 Release
os: [ubuntu-latest] node-version: [lts/*] pnpm-version: [latest] runs-on: ${{ matrix.os }}
– name: ⬇️ Checkout
id: checkout
uses: actions/checkout@v2.3.3
token: ${{ env.GITHUB_TOKEN }}
fetch-depth: 0

– name: 🟢 Setup node
id: setup-node
uses: actions/setup-node@v2
node-version: ${{ matrix.node-version }}

– name: 🥡 Setup pnpm
id: setup-pnpm
uses: pnpm/action-setup@v2.1.0
version: ${{ matrix.pnpm-version }}
run_install: false

– name: 🎈 Get pnpm store directory
id: get-pnpm-cache-dir
run: |
echo “::set-output name=pnpm_cache_dir::$(pnpm store path)”

– name: 🔆 Cache pnpm modules
uses: actions/cache@v3
id: pnpm-cache
path: ${{ steps.get-pnpm-cache-dir.outputs.pnpm_cache_dir }}
key: ${{ runner.os }}-pnpm-store-${{ hashFiles(‘**/pnpm-lock.yaml’) }}
restore-keys: |
${{ runner.os }}-pnpm-store-

– name: 🧩 Install Dependencies
id: install-dependencies
run: pnpm install

– name: 🏗️ Build
id: build-the-mono-repo
run: |
pnpm build

– name: 📣 Create Release Pull Request or Publish to npm
id: changesets
uses: changesets/action@v1
title: “chore(release): version packages 🦋”
publish: pnpm publish:packages
version: pnpm version:packages
commit: “chore(release): version packages 🦋 [skip ci]”

The 📣 Create Release Pull Request or Publish to npm step is where the magic happens! It utilizes the Changesets GitHub Actions action to create release pull requests or publish to npm based on the Changesets detected in your monorepo. It’s the final and crucial step that automates the versioning and release process, making your life as a developer a whole lot easier. 🦋✨

Step 08: Review and Merge the PR

With the bulk of the work completed, it’s time to have your PR reviewed and subsequently merged.

Sample PR:

feat: introduce changesets 🦋 by brionmario · Pull Request #3 · brionmario/changesets-mono-repo

Step 09: Merge the version bump PR

After merging your changes from the previous steps, the Changesets action in the release workflow takes charge to ensure that your requested changes are properly released. It accomplishes this by checking if the PR you just merged contains a changeset. If it detects a changeset, it automatically increments the package versions and generates another PR for your review and final merge.

Once you complete this step, your packages will be accurately versioned, tagged, and released 🎉.

GitHub Releases: Release:

Below is an example of the version bump PR generated by the GitHub action for reference.

chore(release): version packages 🦋 by brionmario · Pull Request #2 · brionmario/changesets-mono-repo


By default, Changesets generates CHANGELOG files in the repository when a release occurs. However, there’s an optional package called @changesets/changelog-github that offers enhanced functionality for GitHub users. This package interacts with the GitHub API to provide richer CHANGELOG entries, including the commiters’ names and hyperlinks to the PRs, among other things.

The following diagrams illustrate the differences between a default CHANGELOG entry and one created with @changesets/changelog-github.

Comparison between different changelog formatters

To utilize this plugin, follow these steps:

Install the @changesets/changelog-github dependency.pnpm add @changesets/changelog-github -wUpdate the .changeset/config.json file.{
“changelog”: [“@changesets/changelog-github”, { “repo”: “brionmario/changesets-mono-repo” }],
…// rest

Sample PR:

chore: add `@changesets/changelog-github` by brionmario · Pull Request #5 · brionmario/changesets-mono-repo


As we’ve explored in this blog post, Changesets simplifies versioning in monorepos.

The code used in this article can be found at this GitHub repository. Feel free to explore and experiment with Changesets in your own projects.

However, one area where Changesets could improve is its documentation accessibility. As of now, the official documentation exists as Markdown files within the repository itself. While this is certainly useful, it can be more user-friendly to have a dedicated website with interactive features. Fortunately, a kind individual has already hosted the Markdown files, making it easier for developers to access and understand Changesets. You can find these hosted docs at

Finally, I encourage all of you to explore this innovative technology and consider implementing it in your work and personal projects.

Signing off… ✌️❤️

🦋 Changesets is a game changer was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.

​ Level Up Coding – Medium

about Infinite Loop Digital

We support businesses by identifying requirements and helping clients integrate AI seamlessly into their operations.

Gartner Digital Workplace Summit Generative Al

GenAI sessions:

  • 4 Use Cases for Generative AI and ChatGPT in the Digital Workplace
  • How the Power of Generative AI Will Transform Knowledge Management
  • The Perils and Promises of Microsoft 365 Copilot
  • How to Be the Generative AI Champion Your CIO and Organization Need
  • How to Shift Organizational Culture Today to Embrace Generative AI Tomorrow
  • Mitigate the Risks of Generative AI by Enhancing Your Information Governance
  • Cultivate Essential Skills for Collaborating With Artificial Intelligence
  • Ask the Expert: Microsoft 365 Copilot
  • Generative AI Across Digital Workplace Markets
10 – 11 June 2024

London, U.K.