What is Nx Release and how does it split versioning, changelogs and publishing?
Nx Release is the built-in release tooling in Nx. It treats a release as three phases that you can run together with nx release or one at a time with nx release version, nx release changelog and nx release publish.
The three phases
- Version reads git history (conventional commits, if configured) or an explicit specifier and decides each project's next version. It writes new versions into
package.jsonand updates dependents that reference bumped packages. - Changelog reads the same commit range and writes
CHANGELOG.mdfiles, per project or for the whole workspace. It can also create git commits and tags, and optionally a release on your git host. - Publish reads the built packages and pushes them to the npm registry. It doesn't modify git.
Here is the flow:
conventional commits → version (package.json) → changelog (CHANGELOG.md, commit, tags) → publish (registry)
Why run phases separately
Each phase has different side effects, and some can't be undone. You can amend a bad version bump locally. You can't take back a pushed tag or a published version without cleanup. If you run each phase on its own with --dry-run first, you see the exact file diffs and the publish plan before anything is written. When something fails, you also know which phase and which inputs caused it, instead of untangling a partially completed all-in-one run.
Options and defaults have changed across Nx versions. This includes which phase creates commits and tags. Check the documentation for your installed version before relying on any default.
+---------------------------+
| git history |
| (conventional commits) |
+-------------+-------------+
|
v
+---------------------------+ writes +-----------------------+
| 1. nx release version |---------------->| package.json versions |
| --dry-run first | | + dependent refs |
+-------------+-------------+ +-----------------------+
|
v
+---------------------------+ writes +-----------------------+
| 2. nx release changelog |---------------->| CHANGELOG.md files |
| --dry-run first | | git commit + tags * |
+-------------+-------------+ | opt. git host release |
| +-----------------------+
v
+---------------------------+ pushes +-----------------------+
| 3. nx release publish |---------------->| npm registry |
| --dry-run first | | (git not modified) |
+---------------------------+ +-----------------------+
* which phase creates commits/tags varies by Nx version; check your docs
nx release = version -> changelog -> publish in a single run
Nx Release turns conventional commits into version bumps, changelogs with git commits and tags, and registry publishes, and each phase can be dry-run and executed on its own.
Who should use Nx Release, and when should you avoid it?
The clearest fit is a backend or platform team that already runs an Nx workspace and publishes shared libraries that services consume: logging wrappers, auth clients, generated API types, database helpers. These teams already have the project graph Nx Release relies on. They also have the pain it removes. Without a release tool, someone edits package.json versions by hand, forgets to bump a dependent package, writes a changelog from memory of the last few merges, and runs a publish script that only works on one person's laptop. Nx Release replaces all three steps with one repeatable process driven by commit history and workspace configuration. Each release takes minutes instead of an afternoon, and versions stop drifting between packages that depend on each other.
That saving only appears if the inputs are reliable. Avoid or delay adoption in these cases:
- No commit discipline. If commit messages don't follow a convention, the tool can't infer bump types, and the changelogs will be noise. Fix the commit habits first, ideally with a commit-message lint in CI.
- Nothing to publish. A repo of deployable services with no packages consumed elsewhere gains little. Its versioning concerns are image tags and deploy history, not registry releases.
- An established release tool already in place. Existing git tags, version history and changelog files must be reconciled with what Nx expects. Plan that migration explicitly, or it can produce skipped or duplicated versions.
Expect to spend some setup time on configuration, and to keep paying a small, ongoing cost in commit discipline.
Should you use fixed or independent versioning for backend packages?
The deciding question is how consumers take your packages. If every service installs the whole set together, as a platform SDK with a client, auth middleware, and shared types, use fixed versioning. One number then describes a known-good combination. If services pin individual shared libraries and upgrade them on their own schedules, use independent versioning. That lets a breaking change in the logging library ship as a major without forcing every other package to look like it broke too.
| Concern | Fixed | Independent |
|---|---|---|
| Compatibility story | One version means "these work together" | Consumers must work out compatible combinations |
| Unchanged packages | Republished with a new version anyway | Left alone |
| Upgrade noise for consumers | Bumps arrive even when nothing they use changed | Bumps reflect real changes |
| Support burden | One line to patch and backport | A version matrix across services |
| Changelog | One combined entry per release | Per-package entries |
Neither cost goes away. Independent versioning moves the burden onto you. When a security fix lands, you have to work out which services run which versions of which packages, and backport to several release lines. Fixed versioning moves the burden onto consumers. Dependency update tooling opens pull requests for packages with no code changes, and teams learn to ignore those bumps, which is risky when a real one arrives.
You don't have to pick one approach for the whole workspace. Nx Release supports release groups. Each group has its own projectsRelationship, either fixed or independent, and its own changelog settings. A common split is to version the SDK packages as a fixed group and the standalone utility libraries as an independent group, all from one workspace and one release process.
How do you configure the release block in nx.json?
Start with release.projects, which defines what Nx is allowed to touch. Use explicit names, globs or tag selectors such as tag:publishable rather than relying on a default. Tag selectors keep deployable services and internal-only libraries out of the release, because those projects simply never carry the tag. Also mark internal libraries "private": true in their package.json so a misconfigured filter still can't push them to the registry.
Inside release.groups, give each group its own projects list, projectsRelationship, and releaseTagPattern. Set conventionalCommits: true under the version settings so Nx derives bumps from commit history instead of prompting. For changelogs, projectChangelogs writes a CHANGELOG.md per package, which suits independent groups. workspaceChangelog produces one root file that reads better for fixed groups. Enabling both usually duplicates content.
When a dependency is bumped, Nx rewrites the version ranges in dependent packages' package.json files. Before publishing, check the following in the generated files:
- Each range actually includes the newly published version.
- No
workspace:*orfile:specifiers remain unless your package manager rewrites them on publish. - Range prefixes (
^vs exact) match what you intend consumers to resolve.
Option names and defaults have shifted between Nx releases, so verify each key against the docs for your installed version.
Adopting this in a repo that already has tags costs some migration work. Nx finds the previous version by matching releaseTagPattern. If your existing tags use a different format, either set the pattern to match them or create one baseline tag per package. Otherwise the first run computes bumps from the wrong starting point.
// nx.json (Nx parses this file as JSON with comments)
{
"release": {
// Only projects tagged publishable are releasable; services and internal libs never get the tag
"projects": ["tag:publishable"],
"groups": {
"sdk": {
// Client packages that always ship together at one version
"projects": ["api-client", "api-types"],
"projectsRelationship": "fixed",
// Set this to match your existing tags, or create one baseline tag before the first run
"releaseTagPattern": "sdk-v{version}"
},
"shared": {
// Utility packages that each version on their own
"projects": ["logger", "config-loader"],
"projectsRelationship": "independent",
"releaseTagPattern": "{projectName}@{version}"
}
},
"version": {
// Derive patch/minor/major from commit messages instead of prompting
"conventionalCommits": true
},
"changelog": {
// One CHANGELOG.md per package; leave the root changelog off to avoid duplicate entries
"projectChangelogs": true,
"workspaceChangelog": false
}
}
}
A representative nx.json release block with a fixed group, an independent group, conventional-commit versioning and per-project changelogs. Check every key against the docs for your installed Nx version.
How does Nx turn conventional commits into version bumps and changelogs?
Nx reads every commit since each package's last release tag and parses the message as a conventional commit. The highest-ranking change for a project determines its bump:
| Commit message | Bump | Changelog effect |
|---|---|---|
fix(orders-api): retry on deadlock |
patch | Listed under fixes |
feat(billing): add invoice webhooks |
minor | Listed under features |
feat(auth)!: drop session cookies |
major | Flagged as breaking |
refactor: ... with a BREAKING CHANGE: footer |
major | Footer text appears in the breaking section |
chore(ci): bump runner image |
none by default | Omitted |
The scope in parentheses is cosmetic. Nx attributes a commit to a project based on the files the commit touches, mapped through the project graph. Two problems follow from that.
- A commit that edits the root
tsconfig.base.jsonor a shared lint config can touch every project and bump all of them. - A change to a dependency declared only through
implicitDependencies, or to an asset outside a project's root, may not touch any of a package's own files. In that case the package gets no bump, even though its runtime behavior changed.
The generated entry for billing would show a features heading, then the line "billing: add invoice webhooks" with the short commit hash and author.
Nx can only work with the messages it receives, so enforce the format at the source. Run commit-message linting in a hook, or check PR titles if you squash-merge. With squash merges, a title like "updates" erases every type from the branch, and the release quietly ships as no bump.
Breaking changes deserve more than an auto-generated line. A consumer needs to know what to change and why. Edit the generated changelog before publishing, or write the migration steps in the commit body so they land in the breaking section.
# Install commitlint and the conventional-commits preset as dev dependencies
npm install --save-dev @commitlint/cli @commitlint/config-conventional
# Use the preset's rules: types like fix/feat, optional '!' and BREAKING CHANGE footer
echo "module.exports = { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js
# Reject malformed messages before they enter history (commit-msg hook)
mkdir -p .githooks
cat > .githooks/commit-msg <<'EOF'
#!/bin/sh
npx --no -- commitlint --edit "$1"
EOF
chmod +x .githooks/commit-msg
git config core.hooksPath .githooks
# Sanity checks: the first message passes, the second fails
echo "feat(billing): add invoice webhooks" | npx commitlint
echo "updates" | npx commitlint || echo "rejected: no type"
# If you squash-merge, the PR title becomes the commit message, so lint it in CI too
# (PR_TITLE is supplied by your CI system)
echo "$PR_TITLE" | npx commitlint
# Preview the bumps and changelog Nx would produce, without writing anything
npx nx release --dry-run
Enforcing conventional commits with commitlint in a local hook and on PR titles, then previewing the resulting Nx version bumps and changelog with a dry run.
How do you publish from build output and verify packages before they reach the registry?
Nx publishes whatever directory the nx-release-publish target points at. For a backend package this should be the build output, not the source folder. Publishing from source ships TypeScript files, test fixtures and a package.json whose entry points reference files that don't exist yet. Set the publish target's packageRoot option to the built directory, such as dist/{projectRoot}, so the tarball contains only compiled code and the manifest your build emits.
Pointing at dist only works if the build has run. It also has to run after versioning, so the bumped version reaches the copied package.json. Add build to the dependsOn list of nx-release-publish, through targetDefaults or per project. Nx then builds each package as part of the publish run instead of trusting a stale dist left over from an earlier job.
Before anything reaches the registry, run the full sequence with --dry-run: nx release version, then nx release changelog, then nx release publish. Each prints the file changes or publish actions it would perform without writing them. Then run npm pack inside one output directory and list the tarball contents. Missing type declarations, leaked .env files and a wrong main path all show up here, and they are cheap to fix before release.
For scoped or private packages, commit an .npmrc that maps your scope to the registry URL and reads the auth token from an environment variable, such as ${NPM_TOKEN}. npm expands the variable at runtime. The repository then holds only configuration, and CI injects the secret.
#!/usr/bin/env bash
# Rehearse a release locally, then inspect a built tarball before anything is published.
set -euo pipefail
# Committed .npmrc at the repo root (config only, no secrets):
# @acme:registry=
# //npm.internal.example.com/:_authToken=${NPM_TOKEN}
# npm expands ${NPM_TOKEN} at runtime. CI injects the real value as a secret.
# Locally, a placeholder is enough because dry runs never authenticate.
export NPM_TOKEN="${NPM_TOKEN:-placeholder-not-a-real-token}"
# 1. Preview version bumps. Nothing is written to package.json or git.
npx nx release version 1.4.0 --dry-run
# 2. Preview changelog entries for the same version. No files, commits or tags are created.
npx nx release changelog 1.4.0 --dry-run
# 3. Preview publishing. Because nx-release-publish dependsOn build, this also runs
# each package's build, so dist/ is fresh rather than left over from an earlier job.
npx nx release publish --dry-run
# 4. Inspect what one package's tarball would actually contain.
# Run this from the build output (packageRoot), not from the source folder.
cd dist/packages/orders-api
npm pack --dry-run
# Things to check in the file list:
# - compiled .js files and .d.ts declarations are present
# - no .ts sources, test fixtures or .env files
# - the main/types paths in package.json point at files listed above
A dry-run sequence covering nx release version, changelog and publish, then npm pack --dry-run in the build output directory, with a committed .npmrc that reads the registry token from NPM_TOKEN for a scoped private registry.
How do you run Nx Release in CI safely, and what are the alternatives?
That token should exist only in the release job. Trigger the job on pushes to the main branch and never on pull requests, so code from forks cannot reach the secret. Give it two narrowly scoped credentials: a registry token that can publish only your scope, and a repository token that can push commits and tags but cannot change repository settings. If the pipeline is compromised, an attacker gets those two abilities and nothing else.
Order the steps so failures leave a recoverable state. Let Nx Release create the version commit and tags, push them, and then publish. Published npm versions are immutable, so you cannot overwrite a bad or half-finished release. If publishing fails partway, the tags claim versions that the registry only partly holds. Recovery usually means fixing the cause and bumping again instead of reusing the number. To make re-runs safe, check each package with npm view <name>@<version> and skip any version that already exists. Also make sure a retry never creates a second version bump.
| Approach | Development cost | Maintenance effort | Fit for backend monorepos |
|---|---|---|---|
| Nx Release | Low if you already use Nx | Moves with Nx upgrades | Strong, because it reuses the project graph |
| Changeset-based tools | Moderate: contributors write change files | Low | Good when you want explicit, reviewed bumps |
| Commit-driven tools | Low | Moderate, with plugins per package | Weaker for many interdependent packages |
Scripted npm publish |
High | High, since you own every edge case | Only for a few rarely released packages |
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.