What is the Nx single version policy?

The Nx single version policy means a workspace has one root package.json and one lockfile, and together they set the version of every third-party dependency for every project in the repository. Applications and libraries do not declare their own versions of React, Express, TypeScript, or a testing framework. When any project imports a package, it gets the version pinned at the root. Projects may still have their own manifests for publishing or metadata, but the root decides what is installed.

This removes three kinds of version conflict that are common in multi-version monorepos:

  • Duplicate framework copies. Two copies of React or a DI container in one bundle break singletons, context, and instanceof checks, often with no build error.
  • Incompatible peer dependencies between shared libraries. If library A expects one major version of a peer and library B expects another, any app that consumes both has no valid install. With one version, that combination cannot be expressed.
  • "Works in lib A, breaks in app B" drift. A shared library tested against one version of a dependency and shipped into an app running a different one fails only in that app, usually late in the process.

The policy does not make these conflicts go away. It moves them from runtime to upgrade time. Every incompatibility shows up when someone bumps a version at the root, and it blocks the whole repository until it is fixed. Platform teams choose this trade because a failing upgrade pull request is cheaper to diagnose than a production incident. The trade only pays off if the upgrade machinery is built to match: automated update pull requests, affected-project testing, and clear ownership. The rest of this guide covers that machinery.

How does Nx rely on a single version of each dependency?

In an Nx workspace, a shared library is usually not built, versioned, and published before an app uses it. The app imports the library's TypeScript source through a path alias, and the bundler compiles both together. The library has no separate dependency tree. When libs/auth imports a JWT package, it gets whatever version the root package.json resolves, and so does every app that imports libs/auth. If two consumers needed different versions, there would be no published artifact to pin; the conflict would surface in the compiled output.

          root package.json + lockfile
           (upgrade: http-client 2 -> 3)
                        │
         ┌──────────────┼──────────────┐
         ▼              ▼              ▼
     libs/http      libs/auth      libs/ui
     (direct)    (imports http)   (unaffected)
         │              │              │
    ┌────┴────┐         │              │
    ▼         ▼         ▼              ▼
 api-gw   billing-svc  admin-app    web-app
 affected  affected    affected     not affected

The project graph keeps this manageable. Nx records which projects import which npm packages and which other projects. When a dependency changes, it walks the graph from that package to every project that depends on it, directly or transitively. CI then builds and tests only that set rather than the whole repository.

That precision weakens at the lockfile. A single upgrade can rewrite dozens of transitive entries, and widely shared packages such as a framework core, a test runner, or TypeScript are reachable from almost every project. Workspaces that treat the lockfile itself as a global input go further and invalidate every project's cached results. In practice, a routine dependency bump often marks most of the graph as affected. The upgrade process has to be designed to handle that case.

┌──────────────────────────────────────────────────────────────────────┐
│ root package.json + lockfile   upgrade: http-client 2 -> 3           │
│ one resolved version per package, shared by every lib and app        │
└─────────┬────────────────────────────────────────────────────────────┘
          │ imports http-client directly
          ▼
┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐
│ libs/http        │◄─────│ libs/auth        │      │ libs/ui          │
│ AFFECTED (direct)│      │ AFFECTED (via    │      │ not affected     │
│                  │      │ libs/http)       │      │ (no http import) │
└─────────┬────────┘      └──┬────────────┬──┘      └─────────┬────────┘
          │                  │            │                   │
          ▼                  ▼            ▼                   ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ api-gw       │  │ billing-svc  │  │ admin-app    │  │ web-app      │
│ AFFECTED     │  │ AFFECTED     │  │ AFFECTED     │  │ not affected │
└──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘

  ◄── project import edge (libs/auth imports libs/http source)
  Affected set = graph walk from http-client: libs/http, libs/auth,
                 api-gw, billing-svc, admin-app. Only these run in CI.
  If the lockfile is treated as a global input, every project above is
  invalidated, including libs/ui and web-app.

An http-client upgrade in the root package.json and lockfile flows through the project graph to every lib and app that imports it, while projects with no path to the package stay unaffected unless the lockfile is treated as a global input.

How do you upgrade Nx plugins versus ordinary dependencies?

That cost is why the two kinds of upgrade follow different paths.

Nx and @nx/* plugins Ordinary third-party packages
Tool nx migrate Package manager (npm install, pnpm add, yarn add)
What changes package.json, plus an optional migrations.json of code and config transforms package.json and the lockfile
Second step nx migrate --run-migrations applies the transforms None. You fix breaking changes by hand

Nx core and its plugins are released as a matched set. Plugins can also declare compatible versions of the tools they wrap. If you bump @nx/* packages directly with the package manager, you skip the generated migrations. The versions in package.json then move ahead while project configuration, executor options and generated files stay in their old shape. The reverse mistake causes the same kind of partial upgrade. If you hand-bump a wrapped tool, such as a test runner, while its Nx plugin stays behind, the plugin may no longer match the tool's new API.

Keep the two paths in separate commits:

  1. Run nx migrate latest, review the package.json diff, then install.
  2. Run nx migrate --run-migrations, commit the result, and delete migrations.json.
  3. In a separate commit, bump each ordinary dependency with the package manager.
  4. Run nx affected -t lint test build --base=origin/main to verify.

With split commits, a failure can be traced to the step that caused it.

Expect the affected set to be most of the repository, because these changes modify global inputs. A remote cache will not help the first CI run: every task hash is new, so every task misses. Plan for a full-graph CI run. Once one agent has computed results, the cache benefits retries and parallel agents.

# Path 1: Nx core and @nx/* plugins go through nx migrate
git switch -c chore/nx-upgrade

# Updates package.json and writes migrations.json if any apply
npx nx migrate latest
git diff package.json        # review the version changes before installing
npm install

# Apply the generated code and config transforms
npx nx migrate --run-migrations
rm -f migrations.json        # remove it once the transforms are applied
git add -A
git commit -m "chore: upgrade Nx and plugins via nx migrate"

# Path 2: ordinary third-party packages are bumped with the package manager
# (placeholder package; one commit per bump keeps failures traceable)
npm install date-fns@latest
git add package.json package-lock.json
git commit -m "chore: bump date-fns"

# Verify against the base branch. Expect most projects to be affected,
# because root package.json and lockfile changes are global inputs.
git fetch origin main
npx nx affected -t lint test build --base=origin/main

An Nx upgrade through nx migrate and a direct dependency bump, each in its own commit, followed by affected-based verification against origin/main.

How should you configure Renovate for an Nx monorepo?

Renovate's defaults assume each package can move on its own. Under a single version policy that assumption is wrong, so most of the configuration is about controlling how updates are grouped.

Group packages that must move together

Use packageRules with a groupName for each family that breaks when versions drift apart: a framework and its companion packages, nx with every @nx/* plugin, and @types/* alongside the runtime packages they describe. A mismatched pair is how a policy meant to prevent version conflicts ends up creating them. Keep major updates separate from minor and patch updates by matching on matchUpdateTypes. Majors need a human to read the changelog. Minors and patches mostly need green CI.

Schedule and automerge selectively

Put noisy categories, such as type definitions and lint tooling, on a weekly schedule. Allow automerge only for low-risk patch and dev-dependency groups. Grouping involves a trade-off. If you group too little, dozens of PRs accumulate and rebase on every merge. If you group too much, a red build hides which of fifteen bumps caused it.

Handle Nx itself differently

A plain version bump of nx or a plugin skips nx migrate, so code and config migrations never run. You have three options:

  1. Exclude Nx packages (enabled: false) and run nx migrate on a calendar.
  2. Use postUpgradeTasks on self-hosted Renovate. The commands must be listed in allowedPostUpgradeCommands in the bot's global config.
  3. Let Renovate open the PR, then have an engineer check out the branch and finish the migration by hand.
// renovate.json5 (JSON5, so comments are allowed)
{
  extends: ["config:recommended"],
  packageRules: [
    {
      // Framework family: core and companion packages move as one PR
      matchPackageNames: ["@angular/**"],
      matchUpdateTypes: ["minor", "patch"],
      groupName: "angular"
    },
    {
      // Majors get their own PR so a human reads the changelog first
      matchPackageNames: ["@angular/**"],
      matchUpdateTypes: ["major"],
      groupName: "angular (major)"
    },
    {
      // Noisy types and lint tooling: grouped, weekly, never mid-week churn
      matchPackageNames: ["@types/**", "eslint", "eslint-*", "@typescript-eslint/**"],
      groupName: "types and lint",
      schedule: ["before 6am on monday"]
    },
    {
      // Low risk: dev-dependency patches merge themselves on green CI
      matchDepTypes: ["devDependencies"],
      matchUpdateTypes: ["patch"],
      automerge: true
    },
    {
      // Option 1: a plain bump would skip `nx migrate`, so Renovate
      // leaves nx and @nx/* alone; a scheduled job runs the migration.
      // Last rule wins, so this overrides the rules above.
      matchPackageNames: ["nx", "@nx/**"],
      enabled: false
    }
  ]
}

A renovate.json5 that groups framework and type packages, splits majors from minor and patch updates, schedules noisy updates weekly, automerges dev-dependency patches, and excludes Nx packages so nx migrate handles them.

What do you do when one project cannot take an upgrade?

Start by fixing forward in the blocking project. Most upgrade failures come from a small surface: a removed API, a changed default, or a type that got stricter. Adapt the call sites, or add a thin compatibility shim, such as a wrapper module that keeps the old signature and delegates to the new one. The shim keeps the rest of the repo on the new version, and you can delete it in one later change because every caller goes through it.

If fixing forward fails, for example because a transitive dependency has no compatible release yet, grant a short-lived exception. There are two ways to do it, and they cost different amounts.

Option Scope Cost Removal effort
Package-manager overrides (npm overrides, Yarn resolutions, pnpm pnpm.overrides) Pins a version in the root lockfile Affects resolution repo-wide unless you scope it carefully, and it is easy to forget Delete one entry and reinstall
Isolated package.json for the project One project gets its own dependency tree Duplicate installs, a separate upgrade path, and the project-graph assumptions no longer hold Merge the dependencies back and fix the drift that built up

Exceptions erode the policy quietly. Once one exists, the next team asking for one has a precedent. Each upgrade also widens the gap the exception has to bridge, so removing it gets more expensive over time and it tends to become permanent.

Give every exception a named owner and an expiry date. JSON does not allow comments, so record both in a sibling metadata field or a linked tracking issue that the override entry references. The snippet below shows this convention. When the expiry passes, CI should fail and force someone to renew or remove the exception.

{
  "name": "acme-monorepo",
  "private": true,
  "dependencies": {
    "date-fns": "^3.6.0",
    "react-datepicker": "^4.25.0"
  },
  "overrides": {
    "react-datepicker": {
      "date-fns": "2.30.0"
    }
  },
  "dependencyExceptions": [
    {
      "override": "overrides.react-datepicker.date-fns",
      "pinnedVersion": "2.30.0",
      "policyVersion": "^3.6.0",
      "reason": "react-datepicker has no release compatible with date-fns 3 yet; fix-forward and shim attempts failed",
      "owner": "team-billing (jane.doe)",
      "issue": "PLAT-1234",
      "expires": "2027-01-31",
      "removal": "Delete the overrides entry, run npm install, close PLAT-1234"
    }
  ]
}

An npm override scoped to one parent package, paired with a dependencyExceptions entry recording owner, tracking issue, and expiry date, since JSON allows no comments; a CI check can fail once the expiry has passed.

Who owns cross-cutting upgrades, and how often should they happen?

Assign upgrade PRs to the platform team by default. They own the root package.json, the lockfile and the Nx workspace configuration, so a CODEOWNERS entry for those files should name them. Keep that entry narrow. The lockfile changes on almost every dependency PR. If it also pulls in every project team as a required reviewer, a routine patch bump waits on five approvals for code it never touched. Require project owners only when the upgrade PR edits files inside their projects.

This creates a predictable failure mode. The platform team merges the version bump, a downstream project breaks, and nobody fixes it because the platform team doesn't know that code and the project team didn't ask for the change. Upgrades then stall, or the platform team becomes the bottleneck for every migration. Make the rule explicit: platform raises the PR and runs the migration, and the affected team fixes failures in its own code within an agreed window.

Cadence matters more than ownership. Small, frequent upgrades isolate the cause of each breakage, and a single version policy couples everyone's release timing, so the slowest project sets the pace for the whole repo. Big-bang upgrades let that drag accumulate.

Illustrative estimate (assumed inputs): Weekly upgrade batches that each take about one engineer-hour add up to about 52 hours a year. An annual catch-up upgrade that needs three engineers for two weeks costs about 240 hours, and it also requires a merge freeze while it lands.

How do you keep the single version policy from eroding?

A single version policy rarely fails in one dramatic commit. It erodes through small, reasonable-looking changes: a nested package.json added so one service can pin a library, a stray lockfile left after someone ran npm install inside a project folder, or a new import that ties a stable service to a fast-moving UI package. Each one widens the set of projects that a future upgrade has to touch.

Fail CI on nested dependencies and lockfiles

The CI check below runs before the build and fails if two things are present. The first is any lockfile (package-lock.json, yarn.lock, pnpm-lock.yaml) outside the workspace root. The second is any project-level package.json that declares dependencies or devDependencies and is not on an explicit allowlist. Publishable libraries often need their own manifest, so the allowlist names them directly. Allowing them by default would let new exceptions in without review. Because the check fails the pull request, the person adding the exception has to justify it.

Constrain coupling with tags

Give each project a tag in its project.json, such as scope:payments or type:util. Then configure the @nx/enforce-module-boundaries lint rule with depConstraints. For example, a project tagged type:util can be limited by onlyDependOnLibsWithTags to other type:util projects. The upgrade benefit is that a shared utility cannot quietly start depending on a framework-heavy library. Without that link, a framework upgrade does not pull every consumer of the utility into its blast radius.

Review exceptions on a schedule

Record every allowlisted manifest and pinned override with an owner and an expiry date. Review the list monthly and either remove or renew each entry. An exception that has outlived its expiry date is the first sign the policy is slipping.

When should you avoid the single version policy, and what are the alternatives?

An exception that never expires usually means the project does not belong under the policy at all. Three cases justify that. A service bound by a hard external constraint, such as a vendor SDK certified against one major version of a framework, will block every upgrade that touches that framework. A deployed artifact pinned for compliance, where any dependency change triggers re-certification, pays that cost on every shared bump. A service that ships twice a year alongside apps that ship daily absorbs churn it gains nothing from.

Approach Conflict risk Upgrade cost CI cost Coordination overhead
Single version policy Low, and conflicts surface at upgrade time Paid once for all projects Root lockfile changes can mark most projects affected High during upgrades, low otherwise
Per-project package.json, independent versions High, with duplicate and mismatched copies in one install Paid separately per project Smaller affected sets per bump Low per change, but drift accumulates silently
Published internal packages Medium, because consumers pin ranges Producer effort plus consumer adoption lag Per-package builds plus a release pipeline Requires versioning and release discipline
Separate repositories Isolated, with conflicts deferred to integration Fully independent Duplicated pipelines and tooling Cross-repo changes need coordinated PRs

The policy fits teams that share a runtime and framework baseline, deploy from the main branch, and have a named owner with scheduled time for upgrades. Use it when nearly every project can absorb a given upgrade within one iteration. When the same few projects keep needing permanent overrides, move them out. Publish what they consume as versioned internal packages, or give them their own repository. That keeps the rest of the workspace on one version.

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 single version policy, 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.