What is independent versioning in Nx Release, and how is it different from fixed?

Nx Release treats a monorepo as a set of release groups. A group is a named collection of projects that share release configuration, defined under release.groups in nx.json. Each group's projectsRelationship setting decides how its members are versioned. The value is either fixed or independent, and fixed is the default.

In fixed mode, every project in the group shares one version number. If any member changes, the whole group moves to the same new version, and a single tag marks that release. In independent mode, each project has its own version, its own changelog entries and its own git tag. A service is bumped only when commits affect it.

Aspect Fixed Independent
Version number One per group One per project
Bump trigger Any change in the group Changes affecting that project
Git tags One tag per group release One tag per project release
Typical fit API plus its dedicated worker Separately deployed services

This article is for backend and platform teams running a monorepo of deployable services. Use independent mode when services deploy on their own schedules. Version bumps in a service that did not change create misleading deploys and hide the real change history. Use fixed mode for components that must ship together, such as an API and the worker that consumes its queue messages. For those, a version mismatch is a bug.

Throughout this article, per-project git tags are the release contract. CI deploys a service when its tag appears. npm publishing is not part of that contract and is skipped entirely.

How do you configure release groups and tag patterns in nx.json?

The release configuration lives under the release key in nx.json. Inside it, groups maps a group name to a set of projects. You can list projects by name, use a glob such as *-api, or match project tags. Matching on a tag like type:app is the most durable option, because a new service joins the right group as soon as it is tagged and nobody has to edit nx.json.

One group per release contract

Put the deployable services in a group with projectsRelationship set to independent, so each service carries its own version line. Where shared libraries go depends on who consumes them:

  • External consumers exist. If another repository installs the libraries from a registry, give them their own group with its own relationship and tag pattern.
  • Only the repo consumes them. If nothing outside the repo uses them, leave them out of release entirely. They are build inputs, not releases, and versioning them only adds noise.

Tag patterns must include the project

Set the group's releaseTagPattern to {projectName}@{version}, which produces tags like orders-api@1.4.0.

A version-only pattern such as v{version} breaks under independent versioning. When orders-api and billing-api both reach 1.4.0, they compete for the same v1.4.0 tag. The second tag fails to create or points at the wrong commit, and CI cannot tell which service to deploy.

Version sources

By default, Nx reads each project's current version from its package.json. Every versioned app therefore needs one, even a backend service that is never published.

Non-JS services need a different source, such as resolving the current version from git tags or using a language-specific plugin. Option names and their placement, including the current-version resolver, have moved between Nx versions. Check them against the documentation for your pinned Nx version.

{
  "release": {
    "groups": {
      "services": {
        "projects": ["tag:type:app"],
        "projectsRelationship": "independent",
        "releaseTagPattern": "{projectName}@{version}"
      },
      "published-libs": {
        "projects": ["shared-contracts", "shared-client"],
        "projectsRelationship": "fixed",
        "releaseTagPattern": "libs@{version}"
      }
    }
  }
}

An nx.json release block with independently versioned services selected by tag and an optional fixed group for externally consumed libraries. Omit that group if only the repo uses them, and confirm option names against the docs for your pinned Nx version.

How does Nx decide which service gets bumped from conventional commits?

Nx parses each commit message since the project's last release tag and maps its type to a semver bump. A feat yields a minor, a fix yields a patch, and a breaking-change marker yields a major. The marker can be ! after the type or a BREAKING CHANGE: footer. Other types such as chore or docs produce no bump by default. When several commits apply to one project, the highest bump wins.

Nx does not use the commit scope to decide which project the bump applies to. It looks at the files the commit touched and maps them to projects through the project graph. The scope in feat(orders): ... is a human convention for readers and changelogs. A commit scoped orders that only edits apps/billing bumps billing.

Commit Files touched Projects bumped
fix(api): handle null currency apps/orders/..., apps/billing/... orders: patch, billing: patch
feat!: switch to ESM root tsconfig.base.json Depends on workspace inputs: possibly every project at major, possibly none

Root files are the ambiguous case. Whether Nx attributes a root config change to all projects depends on how your workspace treats that file. Run a dry-run to confirm what happens in yours.

This scheme has trade-offs:

  • Enforcement: It only works if messages follow the convention. Enforce it with commit linting or with PR-title checks.
  • Squash merges: With squash merges, the final message is what counts. The person editing it at merge time decides the bump.
  • Attribution errors: File-based attribution can over-attribute, for example a formatting sweep that patches twenty services. It can also miss changes, such as a behavioural change made through config outside any project root.
# Assumes nx.json already enables independent releases driven by
# conventional commits, e.g. release.projectsRelationship = "independent"
# and release.version.conventionalCommits = true.

# Commit 1: scope says "api", but the files live in two projects.
# Nx ignores the scope and attributes the commit by file path.
echo "// null-currency guard" >> apps/orders/src/main.ts
echo "// null-currency guard" >> apps/billing/src/main.ts
git add apps/orders apps/billing
git commit -m "fix(api): handle null currency"
# Expected: orders -> patch, billing -> patch

# Commit 2: breaking change to a root file outside any project root.
# Attribution depends on how the workspace treats this file, so the
# result may be every project at major, or none.
echo "" >> tsconfig.base.json
git add tsconfig.base.json
git commit -m "feat!: switch to ESM"

# Commit 3: a scope that does not match the touched files.
# Only billing is touched, so only billing is considered.
echo "// retry tweak" >> apps/billing/src/main.ts
git add apps/billing
git commit -m "feat(orders): add retry on timeout"
# Expected: billing -> minor (highest bump wins over the patch)

# Preview what Nx would do without writing files, commits or tags.
# Read the per-project output to check how commit 2 was attributed.
npx nx release version --dry-run --verbose

Three commits show that Nx assigns bumps by the files each commit touched rather than by its scope, and a dry run confirms how a root config change is attributed in your workspace.

Should a shared library change bump every service that depends on it?

For deployable apps, the useful question is not "did a dependency change?" but "did the artifact we ship change?" A service that bundles a shared library at build time does change when that library changes. Whether that change deserves its own version and deploy is a separate decision.

How propagation works

In independent mode, when Nx bumps a library that is itself a release project, it can also give a patch bump to the projects that depend on it in the project graph. Each of those dependents gets a "dependency updated" changelog entry, even if none of its own files changed. This behaviour exists for publishable packages, where a consumer's manifest has to reference the new version. Apps are not installed by anyone, so that reason does not apply to them.

A decision framework

  • Bump dependents when the library carries runtime behaviour that matters to the service, such as auth, serialization or a client for another service, and you need every running build to map to a version.
  • Don't bump dependents when the libraries are internal types, lint config or test utilities. In that case, let the service pick up the change on its next real release.

The cost of churn

Illustrative estimate. Assume these inputs:

  • 12 services depend on one shared library.
  • The library receives 3 fixes a week.
  • Each deploy takes 20 minutes of pipeline time.

That adds up to 36 extra releases and about 12 hours of deploy queue each week. None of it comes from code the service teams wrote.

Configuration

Nx exposes a setting that controls whether dependents are updated, with options along the lines of automatic versus never. Its name and location in nx.json have changed between major versions, so check the release docs for the version you run. You can also avoid the problem entirely: keep shared libraries out of any release group, so that only apps are versioned.

// nx.json (Nx parses this file as JSONC, so comments are allowed)
// Version-dependent: in Nx 17-20 the option lives under
// release.version.generatorOptions.updateDependents.
// Newer majors moved it, so check the release docs for your version.
{
  "release": {
    // Each project gets its own version and its own changelog
    "projectsRelationship": "independent",
    "projects": ["apps/*", "libs/*"],
    "version": {
      "generatorOptions": {
        // "auto": a lib bump also patch-bumps every dependent in the
        //   project graph, adding "dependency updated" entries.
        // "never": only projects with their own changes are bumped.
        //   Deployable apps pick up the lib fix on their next real release.
        "updateDependents": "never"
      }
    },
    "changelog": {
      // Per-project changelogs, so a skipped bump leaves no noise entry
      "projectChangelogs": true
    }
  }
}

An nx.json release config for independent versioning that turns off automatic dependent bumps. This means a shared-library fix no longer creates patch releases for every service that depends on it. The option is shown under its Nx 17-20 location, which is version-dependent.

Running nx release step by step: dry-run, version, changelog, and skipping publish

Start every release with nx release --dry-run. It prints the version each project would get, the changelog entries it would write, and the tags it would create, without touching files or git. Read it as you would a diff. Look for services that were bumped unexpectedly, and for services you expected to be bumped that are missing. Either case usually points to a commit scope or a project graph edge you misjudged.

Once the plan looks right, run the phases separately. nx release version resolves the new versions and updates each project's manifest. nx release changelog then writes the changelogs and creates the commit and project-scoped tags. Running them as two steps gives you a checkpoint where you can inspect the version changes, or run a build against them, before anything is tagged.

For changelogs, enable projectChangelogs in the release.changelog section of nx.json. Each service's changelog then lists only the commits that touched files in that project, which is what the team that owns the service will read. A workspace changelog combines entries from every service into one file. That file is rarely useful for independently deployed services, so set workspaceChangelog to false unless someone actually reads a combined feed.

Services that ship as container images have nothing to publish to a package registry. Pass --skip-publish to nx release, or do not invoke the publish phase at all. Image pushes belong to the deploy pipeline.

Finally, pin Nx to an exact version in package.json. Release behavior can change between versions, so re-run the dry-run after every Nx upgrade before you trust a real release.

#!/usr/bin/env bash
# Release flow for independently versioned services that ship as images.
# Assumes nx.json contains:
#   "release": {
#     "projectsRelationship": "independent",
#     "changelog": { "projectChangelogs": true, "workspaceChangelog": false }
#   }
set -euo pipefail

# 1. Preview the whole plan: versions, changelog entries, tags.
#    Nothing is written to disk or git. Review it like a diff.
npx nx release --dry-run --skip-publish

# 2. Resolve and write new versions to each project's manifest.
npx nx release version

# Checkpoint: inspect the bumps and build against them before tagging.
git diff --stat
npx nx affected -t build

# 3. Write per-project changelogs, then commit and create project-scoped tags.
npx nx release changelog

# No publish step: container images are pushed by the deploy pipeline.
# The one-shot equivalent of steps 2-3 is:
#   npx nx release --skip-publish

# After any Nx upgrade, pin it exactly (placeholder version) and dry-run again:
#   npm install --save-dev --save-exact nx@<x.y.z>
#   npx nx release --dry-run --skip-publish

Release sequence for independently versioned services: a full dry-run, then separate version and changelog phases with a review checkpoint between them, and no publish step for services shipped as container images.

How do project-scoped tags hand off to the deploy pipeline in CI?

The release job and the deploy job have separate responsibilities. The release job creates commits and tags. The deploy pipeline runs whenever a new tag matching your release tag pattern is pushed. With a pattern such as {projectName}@{version}, the deploy trigger splits the tag on its last @. The left side is the project name and the right side is the version. That last-@ rule also handles npm-style scoped names like @acme/orders. The pipeline builds only that project, tags the container image with the parsed version, and deploys that one service. If one release run produces three tags, three independent deploys start, and unchanged services are never touched.

Requirements for the release job

  • Full git history. Nx finds the previous tag for each project and reads the commits since that tag. A shallow clone hides both, so Nx may treat everything as new or find nothing to bump. Fetch all history and tags, for example with fetch-depth: 0 in GitHub Actions.
  • Push credentials. The job's token must be able to push commits and tags. Some CI platforms do not trigger new workflows from pushes made with their default token. In that case, use a dedicated bot token or deploy key so the tag push actually starts the deploy pipeline.
  • Branch protection. Add a scoped bypass rule for the release identity, or release from a branch that merges back through a pull request.
  • Serialization. Run release jobs one at a time using your CI's concurrency or lock feature. Two concurrent runs can compute the same next version, collide on tags, or overwrite each other's changelog edits.

This split removes manual version bookkeeping. Every running image maps to a git tag, and every tag maps to a changelog entry that explains what shipped.

When should you avoid Nx independent versioning, and what are the alternatives?

Independent versioning answers "what changed in this service?" It does not answer "what was running together on Tuesday at 14:00?" If incident review or audit needs a system-wide snapshot, per-service tags alone won't provide one. You still need a record that joins them. The approach also depends on commit discipline. Mis-scoped or untyped commits produce wrong bumps without any error, so a team that won't enforce conventional commits will get version numbers it can't trust. Finally, if most services are Go, Python, or JVM, there is no package.json to hold the version. You then have to configure an alternative version source, such as resolving from git tags or custom version handling, and that adds friction for little return.

Option Good fit when Main cost
Fixed release group Services always ship together Unchanged services get noise bumps
Deployment manifest / environment record You need "what ran together at time T" One more artifact to keep authoritative
Commit-SHA image tags, no semver Continuous deploy, no external consumers Versions carry no compatibility signal
Versioning outside Nx Polyglot repo with existing per-language tooling Duplicates affected-project logic

Weigh the development cost honestly. It includes the initial setup, ongoing upkeep of commit linting, CI tokens with permission to push tags and commits, and config churn when Nx upgrades change release behaviour. That cost pays off only if manual bookkeeping currently eats real time.

Whichever option you choose, a semver major does not coordinate API consumers. A major version tells callers that something broke, but it does not stop an old client from calling a new service. Contract testing and deploy ordering remain separate problems that you must solve explicitly.

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 independent 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.