What is nx migrate and how does it work?
nx migrate is a two-phase upgrade tool for Nx workspaces. In the first phase, you point it at a target version. It works out which Nx packages and related dependencies need new versions, updates package.json, and writes a migrations.json file listing the code transformations that the new versions provide. At this stage it has not changed any of your source or configuration files.
The second phase, nx migrate --run-migrations, reads migrations.json and runs each listed migration against your workspace. These migrations rewrite configuration, rename options, move files and update imports to match the new versions.
Neither phase is useful on its own. If you bump versions without running the migrations, the new packages can't read your old configuration. Running migrations without the bump has nothing to apply. The pause between the two phases is deliberate, because that is when you review the planned changes and can remove some of them:
version bump -> install -> review migrations.json -> run migrations -> verify
The work belongs to the platform and backend engineers who maintain the monorepo. They know which plugins, executors and custom generators the workspace depends on, and they will fix the build if an upgrade goes wrong.
Teams use nx migrate instead of editing package.json by hand because version numbers are the smallest part of an upgrade. The breaking changes in a major release are in configuration formats and APIs. The plugin authors know about those changes and have encoded them as migrations. Bumping versions by hand skips all of that work, and you end up rediscovering each change through build failures.
# Phase one: plan the upgrade.
# Updates package.json and writes migrations.json.
# No source or config files are changed yet.
npx nx migrate latest
# Install the new versions so the migration code itself is available locally.
npm install
# Review point: inspect what will run before anything touches the workspace.
# Each entry names a package, a version and a description of the change.
# Remove entries you want to skip or handle separately.
git diff package.json
cat migrations.json
# Phase two: apply the code transformations listed in migrations.json.
npx nx migrate --run-migrations
# Verify: see what the migrations rewrote, then build and test.
git status
git diff
npx nx run-many -t build test lint
# Once verified, migrations.json is no longer needed.
rm migrations.json
The full two-phase nx migrate flow from the command line: bump versions, install, review migrations.json, run the migrations, then verify the result with git diff and a full build, test and lint pass.
Why should you upgrade one major version at a time?
nx migrate can take you from an old major straight to latest in one command, but that makes failures hard to diagnose. When you skip several majors, the generated migrations.json holds every migration written across all of them. They were each written against the workspace state their author expected at that release. Running them together produces one large diff, and when the build breaks you can't easily tell which release's breaking changes caused it.
Passing an explicit target version for each major avoids this. You migrate to the next major, install, run the migrations, verify, and commit. Then you repeat for the following major. Each diff stays small enough to review. Migrations run in the sequence their authors intended. When something fails, you only need to check the changelog for one release.
This approach fits teams that are one or more majors behind. If you are on the current major and only picking up minors, the extra ceremony adds little value.
The cost is repetition. Every step needs its own install, migrate and verify round. If the upgrade happens on a long-lived branch, that branch collects merge conflicts from ongoing feature work. Keep each step short and merge it to the main branch before you start the next one.
| Approach | Safety | Effort | Diagnosing failures |
|---|---|---|---|
| One major at a time | High: migrations run in intended order | High: one install/migrate/verify round per major | Easy: failure maps to one release |
| Multi-major jump | Lower: interacting migrations, large diff | Low upfront, often high cleanup | Hard: failure could come from any skipped release |
| Stay on old major | Degrades over time as plugins and tooling move on | Deferred and growing | Not applicable until you upgrade, then worse |
#!/usr/bin/env bash
# One major upgrade per run, e.g. from Nx 16 to Nx 17. Run again for 18, 19, ...
# Usage: ./nx-step.sh 17.3.2 (pick the latest patch of the next major)
set -euo pipefail
TARGET="$1"
# Start each step from an up-to-date main so the branch stays short-lived.
git switch main && git pull
git switch -c "chore/nx-${TARGET}"
# 1. Update package.json and generate migrations.json for this major only.
npx nx migrate "nx@${TARGET}"
# 2. Install the new versions before running any migrations.
npm install
git add -A && git commit -m "chore: bump nx to ${TARGET}"
# 3. Run only the migrations written for this release, in their intended order.
npx nx migrate --run-migrations
git add -A && git commit -m "chore: run nx ${TARGET} migrations"
# 4. Verify. A failure here maps to this one release's changelog.
npx nx reset
npx nx run-many -t lint test build
# 5. Clean up the migration file and open a PR. Merge before the next major.
git rm migrations.json
git commit -m "chore: remove nx ${TARGET} migrations.json"
A script for a single upgrade step. It migrates to one explicit major version, installs, runs that release's migrations, verifies the workspace and commits each stage separately, so the branch can merge before the next major starts.
How do you read migrations.json before running it?
Running nx migrate with a target version does two things. It updates package.json with the new package versions, and it writes a migrations.json file listing code transformations that have not been applied yet. Nothing in that file runs until you run nx migrate --run-migrations. Use that gap to review the plan before any of your source files change.
Each entry in the migrations array has four fields worth reading:
package: the plugin that owns the migration.version: the release that introduced it.name: a stable identifier.description: a short summary of what it changes.
Group the entries by package. Then you can see which first-party plugins and which community plugins will touch your code. Community plugins deserve closer attention, because their migrations are written and tested to whatever standard their maintainers set.
Next, read the descriptions for words like "remove," "rename," or "replace." These usually point to breaking changes. Also look for descriptions that say the migration only warns, or asks you to update something by hand. Those entries may finish successfully but still leave work for you. Write them down before you run anything.
You can delete or hand-edit entries, and sometimes you need to. For example, one migration may crash on an unusual project layout and block everything after it. The cost is that migrations are ordered and assume the earlier ones ran. If you skip one, a later migration may find config in a shape it doesn't recognize. When that happens it may fail loudly, or it may quietly leave things half-converted. If you skip an entry, record why. Make the equivalent change by hand before you continue.
# 1. Generate the plan. This updates package.json and writes migrations.json.
# No source files change yet.
npx nx migrate latest
# 2. Count migrations per package to see which plugins will touch the code.
jq -r '.migrations | group_by(.package)[] | "\(length)\t\(.[0].package)"' migrations.json
# 3. List community-plugin entries (anything not "nx" or "@nx/*") for closer review.
jq -r '.migrations[]
| select(.package != "nx" and (.package | startswith("@nx/") | not))
| "\(.package)@\(.version) \(.name)\n \(.description)"' migrations.json
# 4. Flag likely breaking changes: removals, renames, replacements.
jq -r '.migrations[]
| select((.description // "") | test("remove|rename|replace"; "i"))
| "BREAKING? \(.package) \(.name)"' migrations.json
# 5. Flag entries that may only warn or leave manual work. Note these before running.
jq -r '.migrations[]
| select((.description // "") | test("manual|warn|by hand|you (will|may) need"; "i"))
| "FOLLOW-UP \(.package) \(.name): \(.description)"' migrations.json
# 6. If you must skip an entry, keep the original and drop it by name.
# Record why, then make the equivalent change by hand before continuing.
cp migrations.json migrations.orig.json
jq '.migrations |= map(select(.name != "example-migration-name"))' \
migrations.orig.json > migrations.json
# 7. Apply the reviewed plan.
npx nx migrate --run-migrations
Using jq to group migrations.json entries by package, isolate community plugins, flag descriptions that suggest breaking changes or manual follow-up, and remove a single entry while keeping a backup of the original plan.
A step-by-step procedure for a safe Nx version upgrade
Before touching anything, run git status and make sure the working tree is clean. Uncommitted edits mixed into an upgrade diff are hard to separate later. Then create a dedicated branch for this one major version.
- Bump to an explicit target. Run
nx migratewith a specific version, notlatest. A pinned target makes the step reproducible, and it stops a release published mid-upgrade from changing what you get. This step updatespackage.jsonand writesmigrations.json. It does not change any source yet. - Reinstall dependencies with your package manager so the lockfile matches the new versions.
- Commit. This commit contains only the version bump and the lockfile changes.
- Run the migrations with
nx migrate --run-migrations. - Commit again. This commit holds only the code changes the migrations produced.
Keeping the bump and the migrations in separate commits pays off in three ways:
- Review: reviewers can tell which changes come from dependency resolution and which are code rewrites.
- Bisecting: a bisect can tell you whether the new packages or the transformed code caused a regression.
- Reverting: you can back out a bad migration without undoing the version bump.
Large mechanical diffs tend to get skimmed, and a real problem can slip through that way. To keep review meaningful:
- Put manual fixes in their own commit, after the migrations commit.
- In the PR description, list which files were edited by hand.
- Point reviewers at those files, and at any configuration where a migration may have only partly converted the shape. They can sample the purely mechanical changes instead of reading every line.
Once the migrations are applied, delete migrations.json. If you leave it in the repo, someone may re-run it against code that has already been transformed. Instead, keep a short upgrade log in the PR or the repository that records:
- the target version
- each manual fix
- each skipped migration and the reason it was skipped
#!/usr/bin/env bash
# Upgrade Nx by one major version with separate, reviewable commits.
# Usage: ./upgrade-nx.sh <target-version> (an exact version, never 'latest')
set -euo pipefail
TARGET="${1:?usage: upgrade-nx.sh <target-version>}"
# 0. Refuse to start if there are uncommitted edits that would mix into the diff.
if [ -n "$(git status --porcelain)" ]; then
echo "Working tree is not clean; commit or stash first." >&2
exit 1
fi
# Dedicated branch for this one major version.
git switch -c "chore/nx-upgrade-${TARGET}"
# 1. Bump to a pinned target. This updates package.json and writes
# migrations.json; it does not rewrite any source yet.
npx nx migrate "nx@${TARGET}"
# 2. Reinstall so the lockfile matches the new versions.
npm install
# 3. Commit only the version bump, lockfile and migrations.json.
git add -A
git commit -m "chore(nx): bump to ${TARGET}"
# 4. Apply the code migrations listed in migrations.json.
npx nx migrate --run-migrations
# 5. Commit only the changes the migrations produced.
git add -A
git commit -m "chore(nx): run migrations for ${TARGET}"
# Manual fixes go in their own commit after this point, done by hand.
# Finally: remove migrations.json so nobody re-runs it later.
git rm migrations.json
git commit -m "chore(nx): remove applied migrations.json"
# Afterwards, record the target version, manual fixes and skipped
# migrations in a short upgrade log committed alongside the code.
A shell script that upgrades Nx to an explicit target version from a clean tree on a dedicated branch, keeping the version bump, the migrations, and the removal of migrations.json in separate commits.
How do you verify an Nx upgrade didn't break anything?
Once the migrations have run, resist the instinct to verify with nx affected. Affected detection compares the current state against a base commit and maps changed files to projects. Migrations, however, mostly touch shared configuration: nx.json, root TypeScript and ESLint configs, executor options in project.json files, and plugin settings. Depending on how your named inputs are defined, a change to a root file may mark everything as affected or almost nothing. In either case, the result shows how your inputs are configured, not what the migration actually broke. Run build, lint and test across every project with nx run-many so each target executes against the new configuration.
Before that full run, clear the local cache with nx reset. This removes cached task outputs and stops the Nx daemon, so the run doesn't start with a project graph or results computed under the old version. The remote cache needs the same attention. Upgrades often change task hashes, but don't assume they always do. If your hash inputs don't capture a changed executor or plugin, a remote hit can replay a green result from before the upgrade. For the verification run, bypass the cache entirely with --skip-nx-cache, or confirm that the runs actually executed and were not restored from cache.
In a large monorepo, a full uncached run can take hours of CI time. That cost is real, but it's bounded and you pay it once per upgrade. The alternative is config-level breakage that goes unnoticed until someone touches an untested project weeks later. At that point, the cause is much harder to trace back to the upgrade.
How should you handle framework, peer and community plugin dependencies?
When nx migrate rewrites package.json, it bumps more than Nx. Packages such as TypeScript, Jest, and your frontend framework may move too, because the Nx plugins declare the versions they support. Read that diff line by line. A TypeScript bump can introduce new type errors in code Nx never touches. A Jest bump can change defaults that your config relied on implicitly. A framework major comes with its own set of breaking changes.
Choose on purpose whether to take a framework bump in the same step. Bundling means fewer upgrade cycles and fewer lockfile churns. It also means that when a test fails, you can't tell whether Nx, the framework, or the TypeScript change caused it. Isolating takes longer, but every failure maps to one cause. If the Nx plugin requires the new framework version, you can't defer it. If the plugin only allows the new version, defer it and upgrade the framework in its own pass.
Before you start, check every community plugin's peer dependency range against the target Nx version. Plugins often lag behind Nx majors or ship without migrations. In-house generators and executors carry the same risk: they compile against devkit APIs that can be deprecated or removed. Run their tests against the new version first.
| Option for a lagging plugin | Upfront effort | Ongoing cost |
|---|---|---|
| Wait for upstream | None | Blocks your upgrade indefinitely |
| Fork and patch | Moderate | You own every future Nx upgrade for it |
| Replace | High | Low if the replacement is maintained |
When should you avoid relying on nx migrate alone, and what are the alternatives?
Migrations encode changes the Nx team could express as code transforms: renamed options, moved imports, restructured config. They cannot capture a target that now resolves inputs differently, an option that is deprecated but still accepted, or a change in how caching or task scheduling behaves in CI. These changes produce no diff, so migrations.json won't surface them. Someone has to read the release notes for every major you cross and turn each behavioral note into a check or a ticket.
When the migration path is unreliable, you have three other options:
| Approach | When it fits | Main cost |
|---|---|---|
| Manual package bumps | Small workspace, few generators run | You apply every config change by hand |
| Fresh workspace, port code across | Config is heavily customized or long neglected | Rebuilding project config and CI wiring |
| Defer the upgrade | A hard deadline outweighs the risk | Drift compounds as each skipped major adds migrations and conflicts |
CI hygiene and engineering cost
Keep every @nx/* package pinned to the same exact version. Mixed versions cause failures that are hard to trace back to their source. Update CI images and Node versions in the same change when the new major requires it, so local and CI results stay comparable. Land the whole upgrade in a single merge. A long-lived upgrade branch collects conflicts with every feature merge, and you end up re-running migrations over code that has moved.
Frequent small upgrades cost less engineering time than rare large ones. Each one carries fewer release notes to read and fewer interacting changes. When something breaks, the cause is easy to bisect. A multi-major jump turns a routine maintenance task into a project of its own.
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 migrate upgrade, 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.
- Changing a shared variable is one edit and one review instead of editing every service's
.envby hand.
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.
- A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
- 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.