What is Nx Release and how does it work?
Nx Release is the release mechanism built into the Nx toolchain. It replaces the usual mix of separate versioning, changelog, and publish scripts with one command, nx release, that runs three phases in order: versioning, changelog generation, and publishing. Each phase is also available as its own subcommand: nx release version, nx release changelog, and nx release publish.
How it decides what to release
Nx already maintains a project graph of the workspace that records which files belong to which project and how projects depend on each other. Nx Release uses that graph to map commits since the last release tag onto specific projects. A commit that only touches libs/auth affects the auth library. Nx Release can also bump projects that depend on it, so their package.json dependency ranges stay correct. You don't maintain a hand-written list of what changed, because the graph supplies it.
commits since last tag
│
▼
version calculation (per project, via project graph)
│
▼
package.json updates (own version + dependent ranges)
│
▼
git commit + tag
│
▼
changelog generation
│
▼
publish to registry
Why run phases separately
A single nx release invocation is convenient, but a failure halfway through leaves you to work out which step broke. Running each subcommand with --dry-run first shows the computed versions, file diffs, and changelog text without writing anything. If a version looks wrong, you know the problem is in commit parsing or graph detection, not in registry authentication. After the dry run checks out, run each phase for real, one at a time. That way any error is tied to a single, known step.
#!/usr/bin/env bash
# Run Nx Release one phase at a time so a failure points to a single step.
set -euo pipefail
# Placeholder version for a fixed-version workspace. In independent mode,
# let the version phase compute per-project versions instead.
NEXT_VERSION="1.4.0"
# 1. Preview every phase. --dry-run prints computed versions, file diffs
# and changelog text without writing files, committing or publishing.
npx nx release version "$NEXT_VERSION" --dry-run --verbose
npx nx release changelog "$NEXT_VERSION" --dry-run
npx nx release publish --dry-run
# Stop here and review the output. Wrong versions or a missing project
# point to commit parsing or project graph detection, not publishing.
read -r -p "Dry run looks correct? Continue for real [y/N] " answer
[[ "$answer" == "y" ]] || exit 1
# 2. Versioning: update package.json versions and dependent ranges.
npx nx release version "$NEXT_VERSION"
# 3. Changelog: generate changelog entries for the new version.
npx nx release changelog "$NEXT_VERSION"
# 4. Publishing: push packages to the registry. Credentials come from
# the environment or .npmrc, never from this script.
npx nx release publish
A shell script that previews each Nx Release phase with --dry-run, then runs versioning, changelog generation, and publishing as separate steps so any failure is tied to one phase.
Who should use Nx Release, and when should you avoid it?
Nx Release fits best when Nx is already the source of truth for how your repository is structured. The typical case is a backend or platform team with a monorepo that publishes shared artifacts such as service SDKs, generated API clients, logging and tracing wrappers, or internal validation libraries. The project graph already knows that payments-client depends on http-core. Nx Release can use that knowledge to decide what needs a new version and in what order packages should be published, so you don't maintain a separate list of package relationships that drifts out of sync with the code.
It is a poor fit in three situations:
- You already have a standalone release tool that works. If releases are reliable and nobody is hand-editing changelogs, migrating means rewriting CI jobs, retraining the team, and accepting a period of uncertainty. Graph-aware releases help most when dependency chains are deep. With a handful of loosely coupled packages, the benefit may not cover that cost.
- You don't want releases tied to the Nx toolchain. Release behavior then follows your Nx upgrades. If your organization treats the build tool as replaceable, or upgrades it rarely, that coupling is a real constraint.
- Commit messages are inconsistent. Automated bumps are only as accurate as the history they parse. A repo full of "fix stuff" commits will produce wrong versions and empty changelogs.
Configuration options and defaults have changed between Nx releases. Check the documentation for your installed version rather than relying on examples written for another one.
Should you use fixed or independent versioning for backend libraries?
Nx Release lets you choose between these models per release group, so this does not have to be a single workspace-wide decision. In a fixed group, every package shares one version number. Any releasable change bumps all of them together. In an independent group, each package carries its own version and is bumped only when its own code, or a dependency it relies on, changes.
| Concern | Fixed group | Independent group |
|---|---|---|
| Consumer experience | One version to pin across all libraries | Consumers track a separate version per library |
| Tag naming | One tag per release, typically a plain version | One tag per package per release, typically scoped by project name |
| Changelog layout | A single workspace-level changelog is natural | Per-project changelogs, one per package |
| Tested-together sets | Implicit: same version number means same commit | Needs a lockfile, manifest or tag lookup to reconstruct |
| Publish noise | Unchanged packages get new versions | Only changed packages publish |
Fixed versioning suits libraries that are always deployed as a set, such as a shared logging, tracing and config stack used by every service. Consumers upgrade once, and 2.4.0 of one package is known to work with 2.4.0 of the others.
The cost is that unchanged packages are republished under new version numbers. That causes needless upgrades and can confuse anyone reading a diff. Independent versioning avoids this, which makes it a better fit for loosely related utilities. The price is more tags, more changelogs, and extra effort to answer which versions were tested together.
How do you configure the release block in nx.json?
The release block starts with which projects are releasable at all. The release.projects key accepts project names, glob patterns, and tag selectors, so a common approach is to tag every publishable backend library (for example tag:npm-public) and select by that tag instead of listing names. Tag-based selection makes the opt-in explicit. A new service or app does not enter the publish set just because a glob happened to match it. Applications, test harnesses and internal-only libraries should never carry the tag. As a second guard, mark their package.json as "private": true so the registry rejects them even if the config is misconfigured.
When different library families need different cadences, define release groups under release.groups. Each group has its own project selector and its own projectsRelationship (fixed or independent). For example, you might use a fixed group for a tightly coupled set of database client packages and an independent group for small utilities. A project should belong to only one group, so that it has a single source of truth for its version.
Dependent updates need deliberate handling. When a library is bumped, Nx rewrites the internal dependency range in the package.json of each releasable project that depends on it. Whether those dependents also get a new version is controlled by an updateDependents-style option under the version configuration. If a dependent is not re-released, it keeps referencing the old range on the registry. That is acceptable only when the change is backward compatible and the range still matches. For backend packages that pin internal libraries exactly, you should re-release the dependents.
Option names, accepted values and defaults have changed across Nx major versions. Check every key against the documentation for the version you run, and do a dry run before you commit any configuration.
{
"release": {
"groups": {
"db-clients": {
"projects": ["tag:npm-public-db"],
"projectsRelationship": "fixed"
},
"backend-utils": {
"projects": ["tag:npm-public-util"],
"projectsRelationship": "independent"
}
},
"version": {
"updateDependents": "auto"
}
}
}
Two tag-selected release groups, one fixed and one independent, with dependents of bumped libraries also released. Untagged apps stay out. Check every key and value against the Nx release docs for your version.
How do conventional commits drive version bumps and changelog generation?
With conventional commits enabled, Nx reads each commit's type to decide the bump. The mapping is deliberately small:
| Commit signal | Example header | Bump |
|---|---|---|
fix |
fix(auth): reject expired refresh tokens |
patch |
feat |
feat(queue): add dead-letter retry policy |
minor |
! after type, or BREAKING CHANGE: footer |
feat(db)!: drop legacy pool options |
major |
chore, docs, test, etc. |
chore: bump lint rules |
none by default |
The type determines the size of the bump. File paths determine which project gets it. Nx maps each changed file to its owning project through the project graph. A fix that only touches the root tsconfig, a shared ESLint config, or generated client code may bump nothing because no project owns those files. It may also bump every project, depending on how the inputs are wired. Run a dry run to check which projects get bumped, and don't assume it from the commit message.
Changelogs can be workspace-level (one root file for fixed groups) or per-project (one per library, suited to independent versioning). Entries come from commits since the project's last release tag, so a missing or mistyped tag pulls in far more history than you expect.
Commit messages describe the change from the author's point of view, not from a consumer's, so generated entries need editing. Generate them without committing, rewrite breaking-change notes into migration steps, and then commit. When commit history is unreliable, pass an explicit version specifier instead and make that the source of truth.
If you keep commit-driven bumps, a malformed header is a release bug: it can silently skip a major bump. Enforce commit linting in CI and treat failures as blocking, the same as test failures.
#!/usr/bin/env bash
# Pre-release checks for commit-driven versioning in an Nx workspace.
# Assumes nx.json sets release.version.conventionalCommits = true.
set -euo pipefail
# 1. Block the release if any commit header is malformed.
# A typo like 'feat(db) : drop pool' or a missing '!' can silently
# downgrade a major bump to minor, or to no bump at all.
npx commitlint --from origin/main --to HEAD --verbose
# 2. Preview which projects Nx will bump and what the changelog will say.
# Nx attributes commits to projects by the files they touch, so check
# this output rather than inferring bumps from commit messages.
# Look for unexpected entries caused by root tsconfig, shared lint
# config or generated code.
npx nx release --dry-run --skip-publish
# 3. If the preview pulls in far more history than expected, check that
# each project's last release tag exists and is spelled correctly.
git tag --list --sort=-creatordate | head -n 20
# 4. Alternative when commit history is unreliable: state the bump
# explicitly for the affected project and make that the source of truth.
npx nx release version major --projects=db-client --dry-run
A pre-release script that lints commit headers, previews per-project bumps and changelog entries with a dry run, checks release tags, and shows an explicit version specifier as the fallback.
How do you publish npm packages from an Nx monorepo safely?
Publish from the build output, not the source folder. For a backend library compiled from TypeScript, the source package.json usually points main and types at files that only exist after the build. Configure the publish step's package root to the output directory (for example dist/libs/<name>). Then confirm that the generated package.json there has the bumped version, resolved dependency versions instead of workspace references, and entry points that match the emitted files. If you publish the wrong directory, consumers can install the package and still fail at the first require.
Set the registry and access level explicitly with publishConfig in each package's package.json. npm treats scoped packages as restricted by default. A public @org/logger therefore fails on its first publish unless access is public. A private package pointed at the public registry by mistake is a data leak, which is worse. Stating both values for every package prevents either surprise.
Before the first real publish, run npm pack --dry-run in the output directory to list the files that would ship. You can also run npm pack and inspect the tarball with tar -tzf. Look for leaked .env files, test fixtures, missing type declarations, and source maps you didn't intend to ship.
In CI, run nx release --dry-run on pull requests. This surfaces versioning and changelog problems before merge. Run the real release only from the main branch. Fetch the full history and tags (fetch-depth: 0 in GitHub Actions checkout), because a shallow clone hides the previous release tag, and Nx may then miscalculate the bump or treat every commit as new. Inject the registry token as a CI secret. Reference it from .npmrc through an environment variable, and never commit the literal token.
# .github/workflows/release.yml
name: release
on:
pull_request:
push:
branches: [main]
permissions:
contents: write # the real release pushes the version commit and tags
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # full history and tags so Nx can find the last release tag
- uses: actions/setup-node@v4
with:
node-version: 20
# Generates an .npmrc that reads the token from NODE_AUTH_TOKEN; no token is committed
registry-url:
- run: npm ci
# Pull requests only preview the version bumps, changelogs and publish; nothing is written
- name: Release dry run
if: github.event_name == 'pull_request'
run: npx nx release --dry-run
# Only main does the real version, changelog and publish
- name: Release
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
run: |
git config user.name "release-bot"
git config user.email "release-bot@example.com"
npx nx release --yes
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} # stored as a repository secret
A GitHub Actions workflow that runs nx release --dry-run on pull requests and does the real release only on main, with full git history and tags fetched and the npm token supplied as a secret.
How do you recover from a partial release, and what are the alternatives to Nx Release?
…commit the token itself.
Recovering from a partial release
The awkward failure is when nx release bumps versions, commits, and tags, but npm publish fails partway through. For example, three of five libraries reach the registry and two do not. Git now describes a release that only partly exists. Publishing is not transactional across packages, so nothing rolls back the three that succeeded. npm also refuses to republish a version number, even after an unpublish.
Do not rerun the full release. That would compute a second bump and tag versions that never shipped. The tags and commit are already correct, so run only the publish phase with nx release publish, scoped with --projects to the libraries that failed. Use npm view <package>@<version> to confirm which packages are actually live. If a published package is broken, ship a patch version rather than trying to reuse its number.
Alternatives
| Approach | Setup effort | CI time | Commit discipline | Automates |
|---|---|---|---|---|
| Nx Release | Moderate | Low (graph-aware) | Conventional commits | Versions, tags, changelogs, publish |
| Changeset-based tools | Moderate | Low | Explicit change files per PR | Versions, changelogs, publish |
| Semantic-release-style tools | Higher in monorepos | Moderate | Strict conventional commits | Full pipeline, per package |
| Manual scripts | Low at first | Varies | None enforced | Whatever you write |
Illustrative estimate, using assumed inputs: 8 libraries, two releases a month, 45 minutes per manual release, and 5 minutes per automated release. That saves about 80 minutes a month. Two days of setup and commit-convention training pay back in roughly a year. The payback comes faster if you release more often or if missed changelog entries currently cause support work.
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.
- Changing a shared variable is one edit and one review instead of editing every service's
.envby hand.
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.
- A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
- 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.