Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 36 ยท Projects and Practice

Project: A Monorepo Release Pipeline

Model a monorepo release flow in Node.js. Collect change files, compute version bumps with dependents, write changelogs, rewrite workspace ranges and publish in dependency order.

Releasing one package is a checklist. Releasing twelve that depend on each other is a puzzle: which packages need a new version, how big should each bump be, in what order must they be published, and who writes the changelog? Teams solve it with a tool (Changesets is the most common; others are release-please, Lerna, Nx release and semantic-release variants) and a simple workflow. In this project you build the core of such a pipeline in plain Node.js so you understand what those tools do.

The real tools talk to git and the registry, which this site cannot do. Your pipeline therefore works on plain data, and the final steps show the commands you would run for real. Every code block runs here.

The workflow in one picture

flowchart LR
  A["Developer adds a change file<br/>with their pull request"] --> B["Changes merge to main"]
  B --> C["Release step collects change files"]
  C --> D["Compute bumps incl. dependents"]
  D --> E["Update versions, changelogs, ranges"]
  E --> F["Publish in dependency order"]

The key idea: humans declare intent per pull request; the tool does the arithmetic once, at release time.

A change file is a small file committed with the pull request that says which packages changed and how. In Changesets it is a Markdown file such as .changeset/quiet-lions-sing.md:

MARKDOWN
---
"@acme/ui": minor
"@acme/utils": patch
---

Add a `loading` prop to Button and fix rounding in `formatPrice`.

Step 1: read the change files

Node.js Parse change files

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Step 2: compute the bumps

If three change files mention @acme/utils (patch, minor, patch), the package gets one release, with the highest bump (minor). Then the dependents: if @acme/ui depends on @acme/utils and utils gets a new version, ui's manifest range must be updated, which is itself a change, so ui also needs a release, at least a patch.

Computing the next versions

Merge change files Highest bump wins
Add dependents Patch when a range moves
Write changelogs
Publish in order Libraries first
1 / 2
Node.js Merge bumps and add dependents

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check the result against the rules. utils received patch and minor, so one minor bump (0.1.0 to 0.2.0). ui asked for minor itself. web was not mentioned anywhere, but it depends on both, so it gets an automatic patch, and because it is private it will be versioned but not published. api asked for a major.

Step 3: changelogs

Each release's notes become a changelog entry, grouped by bump size. Generating it from the change files means nobody edits CHANGELOG.md by hand and merge conflicts disappear.

Node.js Generate changelog entries

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Step 4: update ranges and order the publish

Two mechanical jobs remain. First, rewrite dependency ranges in dependents so they accept the new versions (with workspace:^, pnpm and Yarn do this at pack time, but plain-npm monorepos need the tool to do it; see workspace protocol). Second, publish dependencies before dependents: if [email protected] reached the registry before [email protected], an install in that gap would fail to find the dependency version.

Node.js Publish in dependency order, skipping private packages

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Step 5: wire it to real tools

Here is how the same pipeline looks with the real ecosystem (read-only):

Terminal
# Developers, per pull request
npx changeset                 # asks which packages changed and how; writes .changeset/*.md

# Release, usually in CI on main
npx changeset version         # consumes change files: bumps versions, updates changelogs and ranges
npm install                   # refresh the lockfile after version changes
npx changeset publish         # publishes packages whose version is not yet on the registry, tags them

CI usually runs a GitHub Action that opens a "Version Packages" pull request collecting everything pending; merging that pull request triggers the publish. Add these safeguards from earlier lessons: trusted publishing or a granular token (scopes and registries), provenance (supply-chain security), a dry run (npm pack and publish) and a failing-fast check that every non-private package that changed has a change file.

Alternatives and when to prefer them: release-please derives versions from Conventional Commit messages (feat:, fix:, feat!:) instead of change files; Nx release and Lerna integrate with their task graphs; fixed versioning (all packages share one version, as in many framework monorepos) removes this whole computation at the cost of releasing unchanged packages.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Three change files bump @acme/utils as patch, minor and patch. What is released?

    All change files are merged per package, and the largest bump wins; the notes from all files go into one changelog entry.
  2. 2. @acme/web is not in any change file but depends on a package that is released. What happens?

    Dependents get a patch bump when their dependency ranges are updated, so they can ship the new range.
  3. 3. Why publish dependencies before dependents?

    Publishing in topological order guarantees every referenced version exists when consumers can first install the dependent.
  4. 4. What is the benefit of change files over editing CHANGELOG.md by hand?

    Each PR adds its own small file; the release step assembles them, avoiding shared-file conflicts and forgotten entries.

Summary

  • A release pipeline collects intent (change files or commit messages), computes bumps, updates versions, ranges and changelogs, then publishes.
  • Highest bump wins per package; dependents of released packages need at least a patch.
  • Publish in topological order and skip private packages.
  • Changesets, release-please, Nx release and Lerna implement these steps; fixed versioning avoids the computation.
  • Automate the safe parts (dry run, provenance, tokens) in CI.

Next: Practice: Exercises and Cheat Sheet