What is Nx Release and how does it split version, changelog and publish?
Nx Release is the release tooling built into Nx. It treats a release as three phases that run in a fixed order:
- Version: work out each project's next version, write it to
package.json, and update dependents that reference it. - Changelog: render Markdown entries from the commits since the last release and, if configured, create git commits, tags and provider releases.
- Publish: run
npm publishfor each released project.
nx release runs all three phases. nx release version, nx release changelog and nx release publish run each phase alone. The split matters in practice. You can version and tag on a developer machine or in a release PR, then publish from CI, where the npm token is stored. If a publish fails halfway, you can rerun only that phase instead of bumping again.
The full flow:
commits since last tag → project graph (which projects those files belong to, and who depends on them) → semver bump per project → updated
package.jsonfiles → changelog entries → git commit and tags → npm
The main beneficiaries are teams that ship several npm libraries from one workspace. Without this tooling, they hand-edit version fields, changelogs and tag scripts, and those manual steps tend to drift apart.
Make --dry-run your default. It prints the planned bumps, file diffs and changelog text without writing files or touching git or npm. That lets you catch a wrong bump before it becomes a published version, which npm does not let you reuse.
The automation only works under three conditions:
- Commit messages follow a consistent format.
- Project boundaries in the graph are accurate.
- Previous releases left tags Nx can find.
#!/usr/bin/env bash
set -euo pipefail
# --- On a developer machine or in a release PR ---
# 1. Preview first. Prints planned bumps, package.json diffs and
# changelog text without writing files or touching git or npm.
npx nx release --dry-run
# 2. Run the version and changelog phases for real, but skip npm.
# This writes versions, renders changelogs and, if configured,
# creates the release commit and tags.
npx nx release --skip-publish
# 3. Push the release commit and its tags so CI and later
# releases can find them.
git push --follow-tags
# --- In CI, where the npm token is stored ---
# 4. Preview the publish phase alone.
npx nx release publish --dry-run
# 5. Publish. If this fails halfway, rerun only this step.
# Do not bump versions again.
npx nx release publish
# Run each phase on its own when you need finer control:
# npx nx release version --dry-run
# npx nx release changelog --dry-run
# npx nx release publish --dry-run
A release split across two environments: preview with --dry-run, then version, changelog and tag locally with --skip-publish, and run only the publish phase in CI, where it can be retried without bumping again.
How do conventional commits map to semver bumps in Nx Release?
With conventional commits enabled, Nx Release reads each commit's type and footer since the last release tag and picks the highest bump that applies to each project.
| Commit header or footer | Default bump | Example |
|---|---|---|
fix: |
patch | 1.4.2 → 1.4.3 |
feat: |
minor | 1.4.2 → 1.5.0 |
feat!: or a BREAKING CHANGE: footer |
major | 1.4.2 → 2.0.0 |
chore:, docs:, test:, ci:, refactor: |
none | unchanged |
The last row produces no bump because those types describe changes that consumers can't observe through the published package. A test refactor or a README edit doesn't change the API surface or the runtime behaviour. If you publish a new version for it, every downstream lockfile churns for no benefit. You can remap types in configuration, but the defaults follow semver's intent.
Type alone doesn't decide which packages move. Nx looks at the files each commit touched and maps them to projects through the project graph. Two consequences follow:
- Multi-package commits bump more than you might expect. A
feat:that touches bothpackages/authandpackages/loggergives both packages a minor bump, even if the logger change was a one-line typo fix. - Shared and root files can bump more or less than you might expect. Lockfiles, root
tsconfig, lint config and build tooling may sit outside any project. Depending on your configuration and graph, edits to them can be attributed to every project or to none, and neither result reliably matches what consumers experience.
These details matter because npm never lets you reuse a published version number. If a breaking change is labelled fix:, it ships as a patch, and that patch stays in the registry permanently. Deprecating it only adds a warning. The cheapest fix is to correct the commit message before release, not after.
# Each commit header/footer drives the bump for the projects whose files it touches.
# patch: bug fix confined to packages/auth
git commit -m "fix(auth): handle expired refresh tokens"
# minor: new capability in packages/logger
git commit -m "feat(logger): add JSON output format"
# major via the ! marker in the header
git commit -m "feat(auth)!: drop support for Node 16"
# major via a footer: the type is refactor, but the
# BREAKING CHANGE footer (last paragraph) forces a major bump
git commit -m "refactor(auth): rename session helper" \
-m "BREAKING CHANGE: createSession() is now startSession()"
# no bump: docs/test/chore don't change what consumers install
git commit -m "docs(auth): clarify token refresh in README"
git commit -m "test(logger): cover JSON formatter edge cases"
# Risky: one feat commit touching two packages bumps BOTH to a minor,
# even though the logger change is only a typo fix
git add packages/auth packages/logger
git commit -m "feat(auth): add passwordless login"
# Always preview the computed versions before anything is tagged or
# published. Published npm versions can't be reused, so fix mislabeled
# commits now, before the release runs.
npx nx release version --dry-run
Example commit messages and the semver bump each one produces in Nx Release, followed by a dry run that previews the computed versions before any publish.
Should you use fixed or independent versioning?
Before the first release, decide whether packages share one version number or each keeps its own. The choice determines what a version number tells your consumers.
With fixed versioning, every package in the group moves to the same version on every release. A consumer who sees @acme/client@4.2.0 knows that @acme/server@4.2.0 was built and tested alongside it. The cost is noise: a package with no changes still gets a new version, and its changelog has an empty entry.
With independent versioning, each package bumps only when its own commits require it. The version number then carries real information. The cost is bookkeeping: you get one git tag per package per release, more changelogs to read, and consumers have to work out which combinations of versions are compatible.
| Concern | Fixed | Independent |
|---|---|---|
| Version signal | Coarse, shared | Precise, per package |
| Unchanged packages | Bumped anyway | Left alone |
| Git tags per release | One | One per changed package |
| Compatibility story | Same version works together | Needs peer ranges or docs |
Mixing both with release groups
You don't have to pick one approach for the whole workspace. Under release.groups in nx.json, you can define a group such as sdk that lists the tightly coupled packages and sets projectsRelationship to fixed. A second group, such as utils, can hold unrelated packages with projectsRelationship set to independent. Each group is versioned according to its own setting.
Release configuration has changed across Nx versions, so check the documentation for the exact Nx version pinned in your workspace before you copy any example.
{
"release": {
"groups": {
"sdk": {
"projects": ["client", "server", "types"],
"projectsRelationship": "fixed"
},
"utils": {
"projects": ["date-utils", "string-utils"],
"projectsRelationship": "independent"
}
},
"version": {
"conventionalCommits": true
},
"changelog": {
"projectChangelogs": true
}
}
}
An nx.json release config where the coupled sdk group shares one version and the utils group versions each package separately; confirm key names against the docs for your pinned Nx version.
How do you generate readable changelogs and handle internal dependencies?
Nx can write two kinds of changelog. A workspace changelog is a single CHANGELOG.md at the repo root that covers every project in the release. A per-project changelog sits beside each package and lists only the commits that touched it. The workspace file suits fixed versioning and internal readers. Independent npm packages usually need per-project files, because a consumer of one package should not have to read about the others. Both are controlled by workspaceChangelog and projectChangelogs in the release configuration.
The default renderer groups entries by commit type. feat commits go under a features heading and fix commits under fixes. Types such as chore or ci are usually omitted. Breaking changes are called out separately. Each line comes from the commit subject, so the quality of the changelog depends on how commits are written. Require scopes (fix(auth): …) so entries show which area changed. Write subjects for the person upgrading, such as "reject expired refresh tokens", rather than "refactor token util". Even with that discipline, generated changelogs for packages with outside consumers often need curating before release. Plan to add migration notes and to merge noisy entries.
Internal dependencies add a second effect. Suppose package A depends on B, and B gets a minor bump. A's package.json range for B then has to change, and depending on configuration, A may receive its own patch bump so the new range is actually published. Run nx release --dry-run and check three things in its output: B's new version, the diff to A's dependency field, and whether A appears in the list of projects being versioned. If A is missing when you expected it, fix the configuration before anything reaches npm.
# nx.json: independent versions, per-project changelogs, no root changelog
cat > nx.json <<'EOF'
{
"release": {
"projects": ["packages/*"],
"projectsRelationship": "independent",
"version": {
"conventionalCommits": true
},
"changelog": {
"workspaceChangelog": false,
"projectChangelogs": true
}
}
}
EOF
# Scoped subjects written for the person upgrading.
# These lines become changelog entries under Features / Fixes.
git commit -m "feat(b): accept a timeout option in createClient"
git commit -m "fix(auth): reject expired refresh tokens"
# Preview versions, file diffs and changelog text. Nothing is
# written, committed, tagged or published.
npx nx release --dry-run
# Check in the output before running for real:
# 1. B's new version (a feat commit should give a minor bump)
# 2. The diff to packages/a/package.json, where the dependency
# range for B should point at B's new version
# 3. Whether A appears among the projects being versioned.
# If A's range changes but A gets no bump of its own, the new
# range never reaches npm, so fix the config first.
A minimal nx.json for independent packages with per-project changelogs, scoped commits that become changelog entries, and a dry run used to confirm that a bump to B updates A's dependency range and, where expected, A's own version before anything is published.
How do you publish to npm from CI with Nx Release?
Store an npm automation token as a CI secret and expose it to the job as an environment variable. Have an .npmrc reference it through ${NPM_TOKEN} interpolation so the token never lands in the repository. The job also needs full git history and tags. Nx Release finds the last release by its tag and reads commits since then, so a shallow clone produces wrong bumps or empty changelogs.
Run the build before publishing, either as an explicit step or as a dependency of the publish target. Then point each package's release configuration at its build output directory, such as dist/packages/<name>, rather than the project root. Publishing from source ships untranspiled TypeScript and any files you did not mean to include, and a missing files field will not catch it.
Ordering matters. In the default flow, Nx Release creates the version commit and tags before it publishes. If the push succeeds and npm rejects the upload, git says a release exists that the registry never received. Recover in this order:
- Leave pushed tags in place. Deleting them causes more confusion for anyone who already fetched.
- Run
npm view <pkg> versionsfor each affected package to see what actually reached the registry. - Fix the cause, which is usually an expired token or a missing build artifact.
- Re-run only the publish step with
nx release publish. Packages whose version already exists on the registry will not be overwritten.
Write these steps into a runbook before the first incident. A partial release is a bad moment to work them out.
Teams that need an approval gate can split the flow. One job versions, writes changelogs, commits and tags on merge. A separate, manually triggered job builds and publishes.
How do you enforce commit format and adopt Nx Release in an existing repo?
Local enforcement catches mistakes early, and CI makes them impossible to merge. Run a commit-message linter from a commit-msg git hook, configured with the conventional commits rules and a list of allowed scopes. Hooks can be skipped, so add a CI check that validates the pull request title against the same rules.
Squash merges vs merge commits
The PR title matters because of how most teams merge. With squash merges, the PR title becomes the single commit that lands on the main branch, and that commit is what Nx Release parses. The result is one clean, reviewed message per change. The drawback shows up when a PR touches several packages. Each affected package gets the same changelog entry, even if the change was trivial for some of them.
Merge commits keep every individual commit, so per-package changelogs can be more precise. The cost is that every commit on the branch must be well-formed, including the "fix typo" commits. Reviewers have to check commit history, not just the diff.
Adopting Nx Release in an existing repo
Without a starting point, the first release scans the full history. It then produces a changelog full of old or malformed commits and may pick the wrong bump. To avoid this, create baseline tags on the current commit that match your configured release tag pattern. Use one tag per package for independent versioning, or one workspace tag for fixed versioning.
Plan for the cost. Initial setup takes time, and keeping commit messages clean adds ongoing review effort on every PR.
When should you avoid Nx Release, and what are the alternatives?
Nx Release infers versions from history, so it is only as reliable as that history. Avoid it, or delay adoption, in these cases:
- Weak commit discipline. If squash-merge titles are rarely reviewed, or contributors routinely write "fix stuff", a breaking change can ship as a patch. The tool cannot detect intent that was never recorded.
- Manual approval gates. Some teams need a release manager to sign off on each bump. Fully automated inference fights that workflow, and adding approval steps around it erodes the time savings.
- Coordinated releases across many repositories. Nx Release works inside one workspace. Cross-repo coordination needs separate orchestration.
- A single package with no workspace. Adopting a workspace tool only for versioning adds configuration you will rarely use.
Alternatives
| Approach | Setup cost | Ongoing maintenance | Risk of wrong bump | Time saved per release |
|---|---|---|---|---|
| Manual versioning, hand-written changelog | None | High: repeated every release | Depends on the person releasing | None |
| Intent files (contributors declare the bump in the PR) | Low to moderate | Reviewers check each declaration | Low, because the bump is explicit and reviewable | Moderate |
| Standalone conventional-commit tool | Low | Commit linting | Same as Nx Release | High for single-package repos |
| Nx Release | Moderate | Commit linting and config upkeep | Tied to commit quality | High for multi-package workspaces |
Intent files are worth a close look. They move the bump decision into code review, where a human sees the diff, rather than relying on a one-line commit prefix. For a small library that releases a few times a year, manual versioning is often the cheapest honest option.
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 conventional commits, 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.