What is nx release and how does it work as three separate phases?
nx release is Nx's built-in command for versioning, changelog generation and publishing of workspace projects. It splits the release into three phases. Each phase can be run alone, so a failure is easier to locate and the release is easier to reason about.
- Version (
nx release version) reads commit history or an explicit specifier, plus the current version from its configured source. It writes new versions into each project'spackage.json, updates dependent projects' references, and can refresh the lockfile. - Changelog (
nx release changelog) reads commits since the last release and writesCHANGELOG.mdfiles or a hosted release. By default this is also where the git commit and tags are created. - Publish (
nx release publish) runs the package manager's publish against the built output and writes only to the registry.
Running nx release with no subcommand chains all three. The flow looks like this:
commits + version source → version →
package.json, lockfile → changelog →CHANGELOG.md, git commit, git tags → publish → registry
Start every phase with --dry-run. It prints planned version bumps, file diffs and tags without touching disk, git or the registry. This matters because the phases have different undo costs. You can revert a local file edit. You cannot cleanly take back a pushed tag or a published version.
Config keys, defaults (such as which phase commits) and CLI flags have changed across Nx releases. Check the documentation for the Nx version installed in your workspace.
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
npx nx release version minor
git diff --stat # inspect package.json and lockfile changes
npx nx release changelog 1.4.0
npx nx release publish
Runs the version, changelog and publish phases of nx release one at a time with --dry-run first, then for real. Rehearsal and inspection come before the steps that are harder to undo: pushed tags and published versions.
How does nx release work under the hood?
Each phase builds on information Nx already has about the workspace. Knowing what each phase reads and writes tells you where to look when its output surprises you.
Project graph. Nx maintains a graph of every project in the workspace and the dependencies between them. It builds the graph from project.json and package.json files and from the imports in source code. nx release uses this graph to decide which projects are in scope, and which projects depend on a project that is being bumped.
Project and group resolution. The release configuration in nx.json (release.projects, or release.groups) is resolved against the graph to produce the set of releasable projects. Each set is then treated as either fixed or independent. If you don't define groups, every releasable project falls into one implicit group.
Version resolution. Version resolution happens in two steps for each project or group:
- Nx reads the current version from the configured source: git tags, the
package.jsonon disk, or the registry. - Nx decides the bump. The bump can come from an explicit specifier on the command line, an interactive prompt, or conventional commits.
With conventional commits, Nx collects the commits since the previous release tag. It assigns each commit to projects by the files the commit touched, then takes the highest bump implied by that project's commits.
Nx then writes the new version into each package.json. It walks the graph to update the dependency ranges in local dependents that reference a bumped project.
Changelog rendering. The changelog phase takes the same commit range and groups the commits by type, such as features and fixes. It renders them as Markdown into a workspace-level changelog, per-project changelogs, or both. Then it creates the git commit and tags named by the tag pattern. These tags are also the markers Nx uses to find the previous release next time.
Publishing through the task runner. Publish is run as an Nx task for each project. For JavaScript projects, the task invokes the package manager's publish against the project's configured output. Because publishing goes through the task runner, it follows the usual task dependencies, so a build can be wired to run before it. A failure is also reported for the project where it happened.
Who should use nx release, and when should you avoid it?
nx release fits platform and backend teams that publish shared libraries, such as API clients, logging wrappers or config schemas, from an Nx monorepo to consumers outside it. Those consumers might be other repositories, separately built services, or partner teams. The benefit is that version, changelog and publish decisions come from the project graph Nx already maintains, so when a library changes, the packages that depend on it are bumped consistently.
It is the wrong tool in three situations:
- Every consumer lives inside the monorepo. Workspace imports already make changes atomic, so version numbers add ceremony that nobody reads.
- The team won't keep commit discipline. Bumps derived from commit messages are only as accurate as those messages.
- There is no private npm registry. Internal code then has nowhere sensible to go.
The real cost of publishing is the contract you take on. Inside the repo, a breaking change and every call-site fix can land in one commit. Once a package is published, a consumer can pin an old version and stay on it for a year. Removing a function then means a major bump, a deprecation period, and either maintaining the old line or chasing people to upgrade.
| Approach | Fits when | Main cost |
|---|---|---|
| Source-only consumption | All consumers are in the monorepo | Code can't be shared outside the repo |
Manual npm version / publish scripts |
One or two packages, rare releases | Dependents are forgotten, versions drift, changelogs are skipped |
| Changeset-style workflow | You want explicit, human-written release intent per change | An extra file per PR that contributors must remember to add |
nx release |
Many interdependent libraries with external consumers | Commit discipline, plus config that shifts across Nx versions |
What are the alternatives to nx release?
The table above summarizes the options. These are the trade-offs behind each one.
- Source-only consumption. You don't publish anything. Consumers import libraries directly through workspace paths, and a change and every call-site fix land in one commit. This is the cheapest option, and the right default, whenever every consumer lives in the repo.
- Manual
npm versionandnpm publish, or hand-written scripts. You bump and publish each package yourself. This is transparent and needs no extra configuration. It doesn't scale to interdependent packages, though: nothing reminds you to bump dependents, update their ranges, or write the changelog. - Changeset-style workflows. Contributors add a small file to each pull request that names the affected packages and the bump type, along with a human-written summary. A release step consumes those files. Release intent becomes explicit and reviewable, and it doesn't depend on commit message format. The cost is one more thing contributors must remember, and tooling that runs separately from the Nx project graph.
- Fully automated commit-driven release tools. Standalone tools that run in CI analyze conventional commits, then version and publish on every merge to the release branch. They remove the human trigger entirely, which suits single-package repositories well. Monorepo support varies, and none of them shares Nx's knowledge of which projects depend on which.
- Package-manager workspace commands. Some package managers can version or publish across workspace packages. They understand dependencies declared in
package.json, but not Nx-specific configuration such as tags or release groups.
Choose nx release when the workspace is already on Nx and there are enough interdependent publishable libraries that keeping dependents consistent by hand becomes a recurring problem. Choose a changeset-style workflow when you want release notes written deliberately rather than derived from commits.
How do you choose which projects are releasable?
Releasability belongs in nx.json, under the release.projects option, and nowhere else. Defining it in one place makes it reviewable: a pull request that widens the release set shows up as a diff to a single line rather than as a side effect of someone adding a package.json to an app folder.
The option accepts the same project specifiers that nx run-many --projects does. You can use three forms:
- Explicit names for a small, stable set. These are verbose but unambiguous.
- Glob patterns such as a
libs/*style path or name prefix. These suit workspaces that follow a strict naming convention. - Tags, written as
tag:publishableor similar. Tags usually hold up best over time, because opting in becomes a property of the project itself and is set in itsproject.json.
You can also exclude projects with a ! prefix, for example a pattern that matches everything under libs minus anything tagged scope:internal. Exclusions are worth writing even when a positive pattern seems sufficient. They record intent, and they protect you when a new project happens to match the glob.
Keep applications out entirely. They are deployed rather than consumed, and versioning them makes nx release bump and attempt to publish artifacts that nobody installs. Marking internal-only libraries "private": true in their package.json adds a second guard at the npm level.
Before trusting the config, run nx release --dry-run. The output lists every project it would version, along with the proposed new version. If an app or an internal library appears there, fix the specifier before anything is written or published.
cat > nx.json <<'EOF'
{
"release": {
"projects": ["tag:publishable", "!tag:scope:internal"]
}
}
EOF
nx release --dry-run
A tag-based release.projects configuration with an explicit exclusion, followed by a dry run to confirm that only the intended libraries would be versioned.
Should you use fixed or independent versioning?
Nx defaults to fixed versioning: every releasable project shares one version, and a release bumps all of them together. Independent versioning gives each project its own version line, bumped only when its own changes warrant it.
| Concern | Fixed | Independent |
|---|---|---|
| Semver signal | Coarse: a version bump may contain no changes | Precise: a bump means that package changed |
| Tags per release | One | One per released project |
| Changelogs | One shared, or one per project with identical versions | One per project, each with its own history |
| Consumer compatibility | "Use the same version of everything" | Consumers must track which versions work together |
| Noise | Unchanged packages get republished | Only changed packages are published |
Base the decision on how consumers adopt your packages. If services install a set of packages together, such as a client SDK and its types, fixed versioning is simpler. Nobody has to work out which combination of versions is compatible. If teams adopt packages one at a time on their own schedules, independent versioning lets them skip upgrades that do not affect them. The cost is that every combination of versions in the wild becomes something you might need to support.
You do not have to choose one model for the whole repository. Release groups, defined under release.groups in nx.json, partition projects so that each group has its own projectsRelationship, either fixed or independent. A typical setup puts tightly coupled SDK packages in a fixed group and standalone utility libraries in an independent group. In this layout the SDK moves as one unit and each utility evolves on its own.
{
"release": {
"groups": {
"sdk": {
"projects": ["sdk-client", "sdk-types"],
"projectsRelationship": "fixed",
"changelog": {
"projectChangelogs": true
}
},
"utils": {
"projects": ["string-utils", "date-utils", "retry-utils"],
"projectsRelationship": "independent",
"changelog": {
"projectChangelogs": true
}
}
}
}
}
An nx.json release configuration that puts the coupled SDK packages in a fixed group, so they always share one version, and the standalone utility libraries in an independent group, so each is versioned and gets its own changelog only when it changes.
How do conventional commits drive version bumps in nx release?
With conventional commits enabled, nx release reads commit messages since the last release and maps their types to a semver bump:
| Commit message | Bump | Notes |
|---|---|---|
fix(api): handle null cursor |
patch | |
feat(api): add retry option |
minor | |
feat(api)!: drop v1 endpoints |
major | ! marks a breaking change |
Any type with a BREAKING CHANGE: footer |
major | Footer must be in the commit body |
chore, docs, test |
none by default |
The scope in parentheses does not decide which package bumps. Nx attributes a commit to a project by the files it changes. A feat(auth) commit that only edits libs/billing bumps billing, not auth. A commit touching three libraries bumps all three, which is correct only if every change deserves that bump. Keep commits focused on one project.
Squash-merging makes the PR title the commit message, so an untyped title such as "Fix stuff" produces no bump at all. Merge commits keep each individual commit, so every one must be well formed. Whichever strategy you use, enforce the format with commit linting or a PR-title check. That check is part of what nx release costs you to run.
When a library bumps, nx release can update the dependency ranges in local dependents and may bump those dependents too, depending on configuration. Don't assume it does. Read the dry-run output and confirm which files changed and which projects are listed.
For changelogs, enable per-project changelogs in independent groups so each package's history only shows commits that touched it. Use a tag pattern that includes the project name, so tags stay unambiguous and Nx can find each project's previous version.
cat > nx.json <<'EOF'
{
"release": {
"projects": ["libs/*"],
"projectsRelationship": "independent",
"releaseTagPattern": "{projectName}@{version}",
"version": {
"conventionalCommits": true
},
"changelog": {
"workspaceChangelog": false,
"projectChangelogs": true
}
}
}
EOF
git add libs/billing/src/invoice.ts
git commit -m 'feat(billing): add proration option'
git add libs/auth/src/session.ts
git commit -m 'refactor(auth): replace session store' \
-m 'BREAKING CHANGE: SessionStore.get is now async'
npx nx release --dry-run --skip-publish --verbose
An independent nx release config with commit-driven bumps, per-project changelogs and name-prefixed tags, plus two commits scoped by file path and a dry run to check bumps and dependent range updates before releasing.
Where does version state come from, and how do you publish to a private npm registry?
Nx needs a current version for each project before it can compute the next one. There are three possible sources, and each fails differently.
- Git tags are the most portable, but CI checkouts are often shallow and skip tags. Nx then finds no prior release and falls back to an initial version, or bumps from the wrong baseline. Configure the CI checkout to fetch full history and tags. Also make sure tags created by a release are actually pushed. Otherwise the next run can't see them.
- package.json on disk is simple and works offline. It only works if the version commit lands on the branch CI builds from. An unmerged or reverted version commit leaves the file stale.
- The registry reflects what consumers can actually install. It also makes every release depend on registry uptime and read credentials, even for dry runs.
Use the same source locally and in CI. If a developer's dry run reads tags while CI reads the registry, the two can disagree about the next version. You only find out when the publish collides with an existing version.
For a private npm registry, route by scope. In the workspace .npmrc, map your scope (for example @acme) to the internal registry URL. Set publishConfig.registry in each publishable package as a second guard against publishing to the public registry. Reference the auth token as an environment variable in .npmrc and inject it from CI secrets. Never commit a literal token.
Before the first publish, check that every package name carries the scope your .npmrc routes. An unscoped name ignores the scope mapping and goes to the default registry.
How do you run nx release safely in CI and recover from partial failures?
Run releases from one protected branch only, and have the job check out full history with every tag. Nx finds each project's last release by its tag. A shallow clone hides those tags, so commits get counted twice or the version resolves from the wrong baseline. Build the releasable projects before the publish step so a compile error stops the run before anything reaches the registry.
Put a concurrency lock on the release job so that at most one run is active at a time. Push the version commit and tags with a credential that can write only to that repository. If another merge lands while the job runs, the push is rejected as non-fast-forward. Fail the job and let the next run handle the new commit. Do not rebase and force the push.
Releases are not atomic. Package A can publish while package B fails on a network error, which leaves tags and changelogs claiming versions the registry never received. To detect this, compare each project's latest tag with the version reported by npm view <name> version against your registry. Because the version and tags already exist, recover by re-running only nx release publish. Running a full release again would bump versions a second time.
Illustrative estimate. Assume 12 packages, 8 releases a month, 25 minutes per manual release, and 2 hours a month spent fixing mismatches. That comes to about 5.3 hours a month done by hand. A configured pipeline that takes 30 minutes a month to monitor saves roughly 4.8 hours.
How can nx release save engineering time?
The savings come from removing manual steps that are repeated on every release and are easy to get wrong:
- Deciding what to bump. Without automation, someone reads the merged pull requests and judges which packages changed and by how much. With conventional commits and file-based attribution, the version phase works this out from history, and the dry run shows the result for review.
- Keeping dependents consistent. When a shared library bumps, its local dependents need updated ranges and sometimes their own bump. Nx walks the project graph to do this. The alternative is a person remembering every consumer, which is where version drift usually starts.
- Writing changelogs. Changelogs are generated from the same commits, so they are produced on every release instead of being skipped when time is short.
- Avoiding cleanup work. Most of the expensive time is spent fixing releases that went wrong, not running them: a forgotten dependent, a tag without a matching published version, or a package sent to the wrong registry. The safeguards in this article reduce how often that happens. They are dry runs, a single source of version state, scoped registry routing, and a locked CI job with a publish-only recovery path.
The illustrative estimate in the previous section shows how to reason about the payoff. Take your own assumed release frequency, the time a manual release takes, and the time spent on mismatches. Compare the total against the one-off cost of configuration and enforcing commit format, plus ongoing monitoring. If you publish one or two packages a few times a year, those inputs may not justify the setup. The savings grow with the number of interdependent packages and the frequency of releases.
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.