What is nx release and how does its three-stage pipeline work?
nx release is Nx's built-in release tool. It runs as a pipeline of three stages, version, changelog and publish, and each stage is also available as its own subcommand: nx release version, nx release changelog and nx release publish.
Version works out the next version for each project. It reads git history and existing release tags, or takes an explicit specifier such as minor. It then writes the new version into each project's package.json and updates dependents inside the workspace that reference the bumped packages.
Changelog reads the commits since the last release and writes changelog files. These can be per-project, workspace-wide or both. It can also create GitHub releases. In the combined flow, this is typically where the release commit and git tags are created.
Publish runs the publish step for each released package and pushes the built artifacts to the npm registry.
Because the stages have distinct inputs and outputs, you can run them separately and see where a release went wrong. A wrong version number is a version-stage problem, usually caused by commit history or tag matching. A missing package on the registry is a publish-stage problem, usually caused by authentication or build output. Separate stages also let CI split responsibilities. One job can version, tag and push. A later job, holding the registry token, only publishes.
The tool suits platform and backend engineers who ship several npm packages from one Nx workspace and want versioning to follow commit history. Configuration options and defaults have changed between Nx versions. Check the documentation for your installed version and pin Nx so that releases behave the same way on every run.
INPUTS (reads) STAGE OUTPUTS (writes)
+------------------+ +------------------+ +----------------------+
| git history |---->| 1. VERSION |---->| package.json files |
| release tags | | nx release | | + dependents in the |
| or specifier | | version | | workspace |
+------------------+ +--------+---------+ +----------------------+
|
v
+------------------+ +------------------+ +----------------------+
| commits since |---->| 2. CHANGELOG |---->| CHANGELOG files |
| last release | | nx release | | release commit, tags |
| | | changelog | | GitHub releases (opt)|
+------------------+ +--------+---------+ +----------------------+
|
v
+------------------+ +------------------+ +----------------------+
| build output |---->| 3. PUBLISH |---->| npm registry |
| registry token | | nx release | | |
| | | publish | | |
+------------------+ +------------------+ +----------------------+
CI job A (no npm token): version + changelog, push release commit and tags
CI job B (holds npm token): publish only
The three nx release stages, showing what each one reads and writes and how CI can split the version/changelog jobs from the token-holding publish job.
Who should use nx release?
nx release is a good fit if all of the following are true:
- You already run an Nx workspace. The tool relies on the Nx project graph to know which projects exist, where their roots are and which projects depend on which. If you already maintain that graph for builds and tests, releases come at little extra configuration cost.
- You publish more than one package from the repository. The tool earns its keep by coordinating many packages: bumping each one, updating internal dependency ranges, and tagging and publishing them in the right order. With a single package, most of that coordination does not exist.
- Your team can enforce conventional commits, or is willing to pass explicit version specifiers. Automated bumps are only as accurate as the commit messages they read.
- You want releases to run from CI rather than from a developer's machine, with the same steps every time.
In practice, this usually means platform teams that maintain shared libraries, SDK and client-library maintainers, design-system teams that ship component packages, and backend teams that publish internal packages to a private registry.
It is a weaker fit for teams that are not on Nx, teams whose releases need heavy human curation, and repositories with a single package. The section on when to avoid nx release covers those cases and the alternatives.
How does nx release work in a single run?
When you run the combined nx release command, the stages execute in sequence and share state. Each stage consumes what the previous one produced:
- Resolve the project set. Nx reads the
releaseblock innx.jsonand selects the configured projects and groups. It uses the project graph to learn each project's root directory and its dependencies on other workspace projects. - Find the baseline. For each project or group, Nx finds the most recent git tag that matches the configured
releaseTagPattern. That tag marks the last release, and the commits after it are the candidates for this one. - Calculate versions. Nx either uses the specifier you passed (for example
minor) or, with conventional commits enabled, classifies the commits that touched each project's files and picks the highest bump. Fixed groups receive one shared version. Independent projects each receive their own. - Update manifests. Nx writes the new versions into each
package.json. It then follows the project graph and rewrites dependency ranges in workspace packages that depend on a bumped project. Under independent versioning, this can also produce a bump for a dependent that has no direct commits of its own. - Render changelogs. Using the same commit set, Nx writes the workspace and per-project changelog entries and, if configured, creates GitHub releases.
- Commit and tag. If the
gitsettings allow it, Nx stages the changed manifests, lockfile and changelogs, creates a release commit and one or more tags in the configured pattern, and can push them. - Publish. Nx runs the publish step for each released project, in dependency order, against the configured registry and dist-tag. Pass
--skip-publishto stop after step 6 and publish in a separate job.
Every step from 3 onward is deterministic given the same commits, tags and configuration. That is why pinning the Nx version, fetching full git history in CI and running a dry run first make releases predictable.
How should you configure the release block in nx.json?
Everything lives under a single release key in nx.json. Build it in three passes.
Select projects and groups
Start with projects. It accepts project names, globs or tags and limits releases to publishable libraries, so internal apps and tooling are never versioned by accident. If parts of the repository need different policies, use groups instead. Each group has its own project list and its own settings, and a project can belong to only one group.
Choose the relationship
projectsRelationship is either fixed or independent. You can set it at the top level or per group.
| Concern | Fixed (lockstep) | Independent |
|---|---|---|
| Git tags | One tag per release, shared by all projects | One tag per project, typically including the project name |
| Changelogs | Usually one workspace-level changelog | Usually one changelog per project |
| Dependent packages | Always compatible, because they move together | Nx updates dependents' ranges, but you must reason about compatibility |
| Unchanged packages | Bumped anyway | Left alone unless a dependency changed |
Choose fixed when consumers install your packages as a set. Choose independent when the packages ship on their own schedules.
Version, changelog and git settings
The nested version, changelog and git objects control how versions are resolved, which changelogs are written, and whether Nx commits, tags and pushes. Keep the git settings explicit so CI behaviour is predictable.
Bootstrap an existing repository
Nx compares against previous tags to work out what changed. A repository with no matching tags has no baseline. You have two options:
- Run the first release with
--first-release, which tolerates missing tags and unpublished packages. - Create tags that match your tag pattern at the commit representing each package's currently published version.
{
"release": {
"git": {
"commit": true,
"tag": true
},
"version": {
"conventionalCommits": true
},
"changelog": {
"workspaceChangelog": true
},
"groups": {
"core": {
"projects": ["core-*"],
"projectsRelationship": "fixed",
"releaseTagPattern": "v{version}"
},
"plugins": {
"projects": ["plugin-*"],
"projectsRelationship": "independent",
"releaseTagPattern": "{projectName}@{version}",
"changelog": {
"projectChangelogs": true
}
}
}
}
}
A release block in nx.json with a fixed 'core' group that shares one v{version} tag, an independent 'plugins' group with per-project tags and changelogs, and top-level git, version and changelog settings that both groups inherit.
How do conventional commits determine version bumps?
With conventional commits enabled, nx release derives the bump from commit types instead of asking you for one. It reads the commits since each project's last release tag and applies the highest bump it finds:
| Commit message | Bump | Example result |
|---|---|---|
fix(api): handle empty payload |
Patch | 1.4.2 → 1.4.3 |
feat(api): add pagination |
Minor | 1.4.2 → 1.5.0 |
feat(api)!: drop v1 routes or a BREAKING CHANGE: footer |
Major | 1.4.2 → 2.0.0 |
chore:, docs:, test: |
None by default | unchanged |
Commits are assigned to projects by the files they touch, not by the scope in the message. A fix(api) that only edits files in libs/auth bumps auth. This causes two common errors. A change to a root tsconfig, a shared lint config, or a lockfile may fall outside every project's root, so no package is bumped even though its build output changed. A broad refactor that touches forty libraries produces forty releases, each with a changelog entry that has nothing to do with that library.
The version depends on commit messages, so enforce their format before merge. Run a commit linter in a commit hook for local feedback, and add a CI check that validates the pull request title. With squash merges, the PR title becomes the commit message on the main branch, and the individual branch commits are discarded. That makes the title check the gate that matters.
Weigh this before you enable it: one mislabeled merge produces a wrong version. npm restricts unpublishing, and it never lets you reuse a published version number. In practice you fix a mistake by publishing a new version, not by retracting the bad one.
name: PR title
on:
pull_request:
# 'edited' re-runs the check when someone renames the PR
types: [opened, edited, synchronize, reopened]
jobs:
commitlint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
# Assumes @commitlint/cli and @commitlint/config-conventional are
# devDependencies, and commitlint.config.js contains:
# module.exports = { extends: ['@commitlint/config-conventional'] };
- run: npm ci
# Pass the title through an env var rather than interpolating it
# into the script, so a crafted title cannot inject shell commands.
# commitlint reads the message from stdin and exits non-zero if
# the type, scope or format is invalid.
- name: Lint PR title
env:
PR_TITLE: ${{ github.event.pull_request.title }}
run: printf '%s\n' "$PR_TITLE" | npx commitlint --verbose
A GitHub Actions workflow that runs commitlint against the pull request title, which is the message that reaches main and drives the version bump when you squash merge.
How do you generate changelogs and GitHub releases with nx release?
Changelog generation runs from the same commit history that drove the version bump. Nx offers two layouts. A workspace changelog is a single file at the repository root that covers every released project. It suits fixed-versioning setups where all packages ship together. Per-project changelogs write a CHANGELOG.md into each package directory. That fits independent versioning, because a consumer of one library only reads entries relevant to that library. You can enable either layout or both under release.changelog in nx.json.
Each entry groups commits by type, with features and fixes in separate headings. It shows the scope when the commit has one and lists breaking changes in their own section, so upgraders see them first. It can also credit commit authors. If you set createRelease to github, Nx creates a GitHub release from the same rendered content. This requires a token with permission to create releases in CI.
The generator writes what the commits say. A subject like "fix stuff" becomes a changelog line that reads "fix stuff." Hand-editing the generated file is not a durable fix. The next release regenerates or prepends content, and your edits drift from the history that produced them. Fix the input instead:
- Write commit subjects for consumers, not reviewers. Describe the observable change.
- Put migration steps in the
BREAKING CHANGE:footer, since that text appears in the entry. - Use squash merges so the PR title becomes the commit, and lint PR titles in CI.
- Use types such as
choreorcifor internal changes so they stay out of user-facing sections.
{
"release": {
"projects": ["packages/*"],
"projectsRelationship": "independent",
"changelog": {
"workspaceChangelog": false,
"projectChangelogs": {
"createRelease": "github",
"renderOptions": {
"authors": true,
"commitReferences": true,
"versionTitleDate": true
}
}
},
"conventionalCommits": {
"types": {
"chore": { "changelog": false },
"ci": { "changelog": false }
}
}
}
}
An nx.json release block for independent versioning that writes a CHANGELOG.md per package, credits authors, creates GitHub releases from the same content, and keeps chore and ci commits out of the changelog.
How do you preview a release safely with dry-run mode?
Every nx release command accepts --dry-run (short form -d). In dry-run mode Nx runs the full logic of each stage, then prints what it would change instead of applying it. It writes no files, creates no commits or tags, and pushes nothing. The output shows the resolved version for each project, file diffs for each package.json and changelog, and the packages the publish stage would send to the registry. Read the diffs before you trust them, because a bad version cannot be taken back once it reaches npm.
Run stages in isolation
Running nx release --dry-run tells you the end result. It does not tell you which stage caused a problem. When the result looks wrong, run each subcommand on its own:
nx release version --dry-runshows the bump that Nx calculated for each project. A release that does nothing usually comes from one of two causes. Either no commits since the last matching git tag have a releasable type, or Nx cannot find a previous tag and is comparing against the wrong reference. Add--verboseto see which commits Nx considered and how it classified each one.nx release changelog <version> --dry-runrenders the changelog entries for a given version. If a bump is bigger than you expected, check here for a commit marked as breaking, either with!or with aBREAKING CHANGEfooter, that slipped through review.nx release publish --dry-runpasses dry-run through to the package manager. You can confirm which packages would publish and which registry and dist-tag each would use.
Add --projects to narrow the output when you are debugging a single package.
How do you publish npm packages from a monorepo in CI?
Nx can publish either from the source project root or from a build output directory such as dist/libs/my-lib. Publishing from build output gives you a clean tarball of compiled files, but the copied package.json must carry the new version and the updated internal dependency ranges. Run versioning before the build, or configure versioning to update the manifest in the output directory as well. When a library's version changes, Nx rewrites the range in every dependent package's manifest. A consumer installing api-client@2.1.0 then resolves the matching shared-types release, not a stale one.
Publish to the latest dist-tag only from main. Prereleases should go to a separate tag such as next through --tag, so a default npm install never picks them up. Store the registry token as a CI secret and write it into .npmrc at runtime. Never commit it.
In CI:
- Check out with full history and tags (
fetch-depth: 0). A shallow clone hides the previous tag. Nx then either finds no commits to analyze and releases nothing, or measures from the wrong baseline. - Gate the job on
main. - Commit and push as a bot identity that holds a narrowly scoped token and has been granted an exception in branch protection.
- Run
nx release --skip-publishto version, commit, tag and push. Then runnx release publish. The tags record intent before any irreversible registry write.
Publishing is not atomic across packages. If it fails partway, do not re-version and do not unpublish. Read the log to see which packages reached the registry. Fix the cause, then rerun nx release publish --projects=<failed ones> against the existing tags.
How can nx release save engineering time?
The time savings come from replacing a manual, error-prone checklist with one repeatable CI job. Without automation, each release in a multi-package repository means someone has to:
- Work out which packages changed since their last release and pick a bump for each.
- Find every workspace package that depends on a bumped package and update its dependency range.
- Write changelog entries by reading through merged pull requests.
- Create the release commit and tags with consistent names.
- Publish packages in dependency order, then check that each one reached the registry.
- Recover by hand when one of those steps was missed.
nx release turns those steps into configuration that runs the same way every time. The engineering time saved falls into three areas:
- Less release work. Bump calculation, dependent range updates, changelog drafting, tagging and publishing run without a person driving them. A release becomes a merge to
mainplus a review of the dry-run output. - Fewer release mistakes to clean up. Forgetting to bump a dependent, tagging the wrong commit or publishing out of order are coordination errors, and the tool removes them. Since npm does not let you reuse a version number, each avoided mistake also avoids a corrective release.
- No single release owner. When the process is encoded in
nx.jsonand a CI workflow, releases no longer depend on one person who remembers the steps, and they can happen as often as the team merges.
As an illustrative estimate, with all inputs assumed rather than measured: a workspace has 12 publishable packages and releases twice a week. A manual release is assumed to take 45 minutes of engineer time for bump decisions, range updates, changelog writing, tagging and publishing. That is about 90 minutes per week, or roughly 75 hours a year. If the automated flow is assumed to need 10 minutes per release for reviewing dry-run output and merging, the remaining cost is about 17 hours a year. Against that, set the assumed one-time setup cost (say, one to two days of configuration and CI work) and the recurring cost of commit discipline described in the next section. Replace these assumptions with your own numbers. The savings grow with package count and release frequency and shrink toward zero for a single package released rarely.
When should you avoid nx release, and what are the alternatives?
Automation pays off only when its inputs are reliable. nx release infers intent from commit messages, so it fits poorly when a team cannot enforce conventional commits. Free-form squash-merge titles or contributors who skip the format produce wrong or missing bumps, and the tool has no way to tell. It also assumes an Nx workspace. Adopting Nx only for releases means maintaining a project graph and configuration you would not otherwise need. Finally, if releases need human curation, such as hand-written notes or holding a breaking change for a coordinated launch, deriving everything from history works against you.
| Approach | Where release intent lives | Fits when | Main trade-off |
|---|---|---|---|
| nx release | Commit messages | Nx workspace with enforced commit linting | Bump accuracy depends on commit discipline |
| Changeset-based workflow | Small intent files committed with each PR | Reviewers want to see and edit the bump before merge | Authors must remember to add the file |
| semantic-release-style tool | Commit messages, released on every merge | Single package or simple repos | Little room for curation; monorepo support varies |
| Manual versioning, scripted publish | A person at release time | Few packages, infrequent releases | Coordination errors grow with package count |
Count the ongoing costs along with the setup. Configuration is a one-time cost. Commit discipline is a recurring one: lint hooks, PR-title checks and review friction. A CI job that holds a registry token and repository write access also widens your attack surface. Scope the token narrowly and restrict which branches can trigger a release.
The savings come from removing manual coordination. You no longer hand-compute bumps across dependent packages, write changelogs from memory, or run publishes that differ from one release to the next. The more packages you have and the more often you release, the more that coordination would otherwise cost.
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, 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.