What is nx release and how do its version, changelog and publish phases work?

nx release is the release tooling built into Nx. It splits a release into three phases that you can run together or one at a time: nx release version, nx release changelog and nx release publish. Each phase reads different inputs and writes different outputs.

Version

The version phase works out the next version for each project. It can take an explicit specifier such as minor, or it can derive the bump from conventional commits since the last matching git tag. It reads the project graph to find which projects depend on the ones being bumped. It then writes new versions into the package manifests and updates the dependency ranges in dependent packages.

Changelog

The changelog phase reads the commits between the previous release tag and HEAD and groups them by type and project. It writes changelog files. By default it also creates the release commit and the git tags.

Publish

The publish phase runs each project's publish target and uploads artifacts to the registry. It does not modify git.

Run the phases separately during adoption

Run each phase on its own with --dry-run before you rely on the combined command in CI. A dry run shows the version decisions, the changelog text and the tags each phase would produce, without writing anything. If you start with a single all-in-one command, a misconfigured tag pattern or project filter can publish wrong versions, and you only find out after they reach the registry.

Commit messages are the release API

When versions are derived from commits, a commit's type and scope decide whether consumers get a patch, a minor or a major release, and which changelog the entry lands in. For internal packages, the commit history is the only release interface consuming teams see.

npx nx release version --dry-run --verbose

npx nx release version minor --dry-run

npx nx release changelog 1.4.0 --dry-run

npx nx release publish --dry-run

npx nx release --dry-run

Running nx release version, changelog and publish separately with --dry-run, followed by the combined command, with comments showing how conventional commit messages map to version bumps.

How does nx release work end to end?

A commit-driven release follows the same sequence every time:

  1. Select releasable projects. Nx reads the release block in nx.json to decide which projects take part and how they are grouped. Projects outside that configuration are ignored.
  2. Build the project graph. Nx already knows each project's files and its dependencies on other workspace projects. Release reuses that graph for commit attribution and for dependent updates.
  3. Find the current version. For each project or group, Nx establishes a starting point. That is usually the latest git tag that matches the configured tag pattern. It can also be the version in the package manifest on disk or the version in the registry.
  4. Read and classify commits. Nx collects the commits between that starting point and HEAD. It parses each header as a conventional commit, then maps the files each commit changed to projects. The highest-ranked type touching a project decides its bump. A breaking change outranks feat, and feat outranks fix.
  5. Apply versions. Nx writes the new version into each bumped project's manifest. It then updates dependency references in workspace projects that depend on it.
  6. Write changelogs, commit and tag. Nx renders entries from the same parsed commits, creates a release commit and adds tags using the configured pattern.
  7. Publish. Nx runs each released project's publish target against the configured registry.

All of the release decisions come from data that is already in the repository: the configuration, the project graph, the tags and the commit history. That is why the rest of this article focuses on keeping those inputs correct. The tool does what the tags and commit messages tell it to.

Should internal packages use fixed or independent versioning?

The release block in nx.json decides which projects take part. release.projects accepts project names, globs or tags. Filtering by a tag such as type:publishable keeps apps and test utilities out of the release, so nobody publishes an e2e helper by accident. release.groups splits releasable projects into named sets, and each group sets its own projectsRelationship: fixed or independent.

Concern Fixed (lockstep) Independent
Version accuracy Every package gets the highest bump in the group Each package's semver reflects its own commits
What consumers track One number for the whole group A matrix of versions per package
Unchanged packages Republished with a new version Left alone
Compatibility questions "Are we on the same version?" Needs a compatibility table or ranges
Upgrade noise Higher, because renovation PRs touch everything Lower, but spread over more PRs

With fixed versioning, a breaking change in auth-client forces a major bump on logging, even if logging did not change. That is the cost of the simpler mental model. Independent versioning makes semver honest. The cost moves to consuming services, which must work out which http-client works with which auth-client.

For libraries that many services consume, keep the two approaches apart by using groups:

  • Fixed groups for tightly coupled sets. Use lockstep for packages that share types or are always upgraded together, such as an SDK and its generated models.
  • Independent groups for standalone utilities. Use independent versioning for libraries with no shared contract.

Service owners then track a few group versions instead of dozens of packages, and unrelated libraries do not churn.

// nx.json (Nx parses this file as JSON with comments)
{
  "release": {
    // Top-level "projects" and "groups" are mutually exclusive.
    // With groups, each group lists its own releasable projects,
    // so apps and e2e helpers are excluded by never being listed.
    "groups": {
      // Lockstep: the SDK and its generated models share types and are
      // always upgraded together, so consumers track one number.
      "sdk": {
        "projects": ["sdk", "sdk-models"],
        "projectsRelationship": "fixed",
        // One tag per group release, not per package
        "releaseTagPattern": "sdk-v{version}"
      },
      // Independent: standalone utilities with no shared contract.
      // Each package bumps only from its own commits.
      "utilities": {
        "projects": ["tag:type:utility"],
        "projectsRelationship": "independent",
        // Per-package tags, e.g. logging@2.3.0
        "releaseTagPattern": "{projectName}@{version}"
      }
    },
    "version": {
      // Derive bump type (patch/minor/major) from Conventional Commits
      "conventionalCommits": true
    },
    "changelog": {
      // One changelog file per project, generated from the same commits
      "projectChangelogs": true
    }
  }
}

An nx.json release block that versions a tightly coupled SDK group in lockstep and standalone utilities independently, with bumps derived from Conventional Commits.

How do conventional commits determine semver bumps and project attribution?

Commit header or footer Bump Why
fix: ... patch Corrects behavior without changing the contract
feat: ... minor Adds capability; existing callers keep working
feat!: ... or a BREAKING CHANGE: footer major Consumers must change code to upgrade
chore, docs, test, etc. none by default No consumer-visible change

Nx does not trust the scope in fix(billing): ... to decide which package the commit belongs to. It looks at the files the commit touched and maps them to projects in the workspace graph. The scope is useful to readers, but a commit labeled billing that also edits libs/auth bumps both packages.

File-based attribution has a cost. A commit that edits root configuration, such as the base TypeScript config, a lockfile or shared lint rules, can count as touching every project that depends on that file. A fix: that tweaks a compiler option then gives a dozen packages a patch release, with changelog entries their consumers can't act on. Keep tooling changes in chore: commits, and split mixed changes into separate commits.

Bumps also cascade through the dependency graph. If libs/http-client gets a minor bump, Nx can bump the packages that depend on it so that they reference the new version. Before you turn this on, check how deep your graph is. A heavily shared library at the bottom of the graph will release most of the workspace on every change. Decide whether dependents need a new version or only an updated dependency range.

Nothing checks the commit type against the change itself. A breaking change labeled fix: ships as a patch, so reviewers have to check the label just as they check the code.

#!/usr/bin/env bash
set -euo pipefail

git log --format='%h %s' v1.4.0..HEAD

git log --name-only --format='--- %h %s' v1.4.0..HEAD

npx nx show projects --affected --base=a1b2c3d~1 --head=a1b2c3d

npx nx release version --dry-run --verbose

npx nx release changelog --dry-run

A dry-run workflow that shows which files each commit touched, which projects Nx attributes those commits to, and which bumps and changelog entries a release would produce, including cascaded bumps to dependents, before you publish.

How do you generate changelogs that consuming teams will actually read?

Nx release can write two kinds of changelog, and they serve different readers. A workspace changelog is a single file at the repository root. It collects every release entry across all projects and suits people who follow the monorepo as a whole, such as the platform team. Per-project changelogs live in each project's directory and contain only the commits attributed to that project. Consuming teams usually want the per-project file because they depend on one package and not the whole repository. With independent versioning, per-project files are the more natural fit, since each package has its own version history.

Entries are built from commit subjects, so the writing quality of commits sets the quality of the changelog. Some conventions help:

  • Write subjects for consumers. "add retry option to HTTP client" tells a consumer something. "address review comments" does not.
  • Use scopes that match package names. The scope shows up in the entry, and readers can scan for the area they care about.
  • Hide noise. The commit type configuration controls which types show up. Leave chore, ci, test, and style out of changelogs so only feat, fix, and perf reach readers. You can still keep internal-only types visible in the workspace changelog for the platform team.

Generated entries describe what a commit did, not what a consumer must do about it. A feat! line saying "remove legacy auth middleware" tells a reader that something broke. It does not tell them how to fix it. For breaking changes, put a migration note in the commit body or the release notes. Write it by hand, and include before-and-after usage, so readers don't have to rebuild the upgrade path from a diff.

// nx.json (Nx accepts comments in this file)
{
  "release": {
    "projectsRelationship": "independent",
    "changelog": {
      // Per-project files are what consuming teams read: one package, one history
      "projectChangelogs": {
        "file": "{projectRoot}/CHANGELOG.md",
        "renderOptions": {
          "authors": false
        }
      },
      // No root file here; with independent versioning each package keeps its own history
      "workspaceChangelog": false
    },
    "conventionalCommits": {
      "types": {
        // Keep internal housekeeping out of consumer-facing entries
        "chore": { "changelog": false },
        "ci": { "changelog": false },
        "test": { "changelog": false },
        "style": { "changelog": false }
        // feat, fix and perf use their defaults and stay visible
      }
    }
  }
}

An nx.json release configuration that writes a CHANGELOG.md in each project for independently versioned packages and hides chore, ci, test and style commits, so feat, fix and perf entries reach consumers.

How do you enforce commit message format with commit linting and PR titles?

Changelog quality depends on the messages Nx parses, so enforce the format before a commit reaches the main branch. Use two checks. A commit linter in a local commit-msg Git hook (commitlint is the usual choice) catches mistakes while the author still has context. A CI check on the pull request is the gate that counts, because local hooks are easy to skip with --no-verify or never install.

The merge strategy decides which messages Nx reads. With squash merging, the PR title becomes the single commit on the main branch, so the PR title is the only message you need to validate. Contributors can write "wip" and "fix typo" commits on their branch without affecting the release. With merge commits, every commit on the branch lands in history, and Nx reads each one, so each one must pass the linter.

Strategy What Nx reads Hygiene burden Trade-off
Squash merge PR title (one commit) Validate one title per PR A mixed PR collapses to one type and one bump
Merge commit Every branch commit Every contributor writes compliant messages Keeps per-change detail and attribution

Squash merging is the easier default for most internal monorepos. Its weakness is mixed PRs. If a PR contains a feat for one package and a fix for another, the squash commit gets one title, so one change is labelled wrong or left out of the changelog. Split these into separate PRs. Smaller, single-purpose PRs also make review and reverts easier.

How do you run nx release safely in CI?

Nx computes the next version by finding the latest release tag for each project (or group) and reading the commits since that tag. The CI job therefore needs several things in place:

  • Full history and tags. Many CI checkouts are shallow by default. A shallow clone may not include the last release tag, or may cut off commits after it. Nx then either fails to find a starting point or reads too few commits, and the bump comes out wrong. Configure the checkout to fetch full depth and all tags.
  • Registry authentication. Inject a token scoped to publish to your private registry, and confirm the publish step uses it rather than a developer's cached credentials.
  • A concurrency guard. Two overlapping release jobs can calculate the same version, and the second will then fail to push its tag or publish its package. Serialize releases with a single concurrency group or lock per branch.
  • Loop prevention. The release step pushes a commit and tags. If that push triggers the pipeline again, the job must recognize its own release commit message or author and exit.

Rewritten history causes quieter failures. A force-push can leave tags pointing at commits that are no longer on the branch, and a deleted tag moves the baseline back to an older release. In both cases, commits that were already released get counted again.

For an existing repo, reconcile before the first real release. Make sure every project's current published version has a matching tag, or tell Nx to read the current version from the registry or from disk. Then run nx release --dry-run and check each proposed bump. A dry run often catches a project that would jump a major version because Nx found no prior tag for it.

Who should use nx release?

nx release fits teams that meet most of these conditions:

  • You already use an Nx workspace. Release relies on the Nx project graph. Adopting Nx only to get release tooling means taking on a build system as well, and that is a much larger decision.
  • You publish several internal packages that depend on each other. File-based attribution and dependent updates are what separate nx release from simpler tools. With one package, a standalone conventional-commit tool does the same job.
  • Consumers outside the monorepo pin versions. Services in other repositories, or teams that roll out upgrades on their own schedule, need real version numbers and readable changelogs.
  • You can enforce commit conventions. A team that already squash-merges with validated PR titles, or is willing to add that check, gets reliable bumps. A team that cannot enforce the format will get wrong versions.
  • A platform or developer-experience team owns the release pipeline. Someone has to maintain the nx.json release configuration, the tag patterns and the CI job, and handle problems such as a missing tag.

It is a poor fit if all consumers live inside the monorepo and build from source, if you release one or two packages rarely, or if commit messages are written casually and nobody plans to change that. The last section covers alternatives for those cases.

How can nx release save engineering time?

Manual releases of interdependent packages repeat the same steps every time. Someone reads the history since the last release, decides on the bump, edits the manifests, updates dependents, writes changelog entries, commits, tags and publishes. nx release removes or shortens each of these steps:

  • Bump decisions come from commits. Nobody has to read through history to judge whether a change was a patch or a minor. The judgment happens once, when the author writes the commit, and the reviewer checks it during code review.
  • Dependent updates are automatic. Nx walks the project graph and updates the dependency references in dependent packages. When people do this by hand, they forget a package and consumers resolve mismatched versions.
  • Changelogs are a by-product. Entries come from the same commits used for versioning. Authors only write prose by hand for breaking-change migration notes.
  • Releases stop waiting for a specific person. When the release runs in CI from merged commits, the engineer who used to know the release steps no longer holds up a release. Releases can then happen more often and in smaller batches, which makes each upgrade easier for consumers.
  • Failures surface before publishing. --dry-run shows versions, changelog text and tags in advance. Fixing a wrong bump before publishing is cheaper than publishing a corrective release and telling consumers to skip the bad one.

These savings depend on the inputs staying correct. Time spent on commit linting, PR title checks and the CI concurrency and history settings is what keeps the automated output trustworthy. Count that time against the savings. The next section works through that trade-off with an illustrative estimate.

When is nx release worth it, and what are the alternatives?

The cost case comes down to arithmetic. Here is an illustrative estimate with assumed inputs, not measured data:

  • Assumed: 12 internal packages, each released 3 times a month (36 releases), at 10 minutes per manual bump and changelog entry. That is 6 hours a month.
  • Assumed: 2 days (16 hours) to set up nx release, commit linting and the CI job, plus about 1 hour a month of maintenance.

Under these assumptions, setup pays for itself in roughly three months. Change the inputs to 3 packages released once a month and manual work drops to 30 minutes a month, so payback takes years.

The time estimate also understates the benefit. Manual bumps fail in ways that cost more than the minutes saved, such as a missed dependent bump or a changelog that omits a breaking change.

Avoid nx release when you have a few rarely changing libraries. Also avoid it when your team will not maintain commit discipline. If commit messages are unreliable, generated bumps and changelogs will be wrong, and they will look authoritative.

Approach Version source Fits when Main cost
Manual versioning Human judgment Few packages, rare releases Toil and missed bumps
Changeset files Files committed with each PR Commits are messy but PRs are reviewed Authors must remember to add a file
Standalone conventional-commit tool Commit messages Single package or no Nx Weak monorepo project attribution
nx release Commits plus project graph Many interdependent Nx projects Setup and commit enforcement
No versioning, consume source Monorepo HEAD All consumers live in the repo No independent rollout or pinning

Consuming source directly is often the right default for internal code. Add versioning only when consumers outside the monorepo need to pin a release.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to nx release versioning, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.