Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nrwl/nx/llms.txt

Use this file to discover all available pages before exploring further.

nx migrate [packageAndVersion] [options]
nx migrate is a two-step process:
  1. Update packages — resolves the new versions of Nx packages and their plugins, updates package.json, and generates a migrations.json file listing the code transformations to apply.
  2. Apply migrations — runs the transformations listed in migrations.json against your source files.
Run npm install (or your package manager’s install command) after step 1 and before step 2 to install the updated packages.

​
Migration workflow

1

Generate migrations.json

Target the version you want to migrate to. Using latest resolves the latest stable release:
nx migrate latest
# or target a specific version
nx migrate @nx/workspace@20.0.0
# or update a specific plugin
nx migrate @nx/react@latest
This updates package.json and creates migrations.json.
2

Install updated packages

npm install
3

Apply the migrations

nx migrate --run-migrations
This runs every migration listed in migrations.json against your workspace files.
4

Review and commit the changes

Inspect the file changes produced by the migrations, run your tests, and commit the result.

​
Arguments

​
packageAndVersion
string
The target package and version to migrate to (e.g., @nx/workspace@20.0.0, latest, @nx/react@latest).

​
Options

​
--run-migrations
string
Execute code migrations from a file. When no file path is provided, reads from migrations.json in the current directory.
nx migrate --run-migrations
nx migrate --run-migrations=custom-migrations.json
​
--if-exists
boolean
default:"false"
When using --run-migrations, continue successfully even if the migrations file does not exist.
​
--from
string
Override the currently installed versions of packages when computing which migrations to run. Useful when the installed versions are not accurate. Accepts a comma-separated list.
nx migrate latest --from="@nx/react@18.0.0,@nx/js@18.0.0"
​
--to
string
Override the target versions that the migrator would otherwise calculate. Accepts a comma-separated list.
nx migrate @nx/workspace@20.0.0 --to="@nx/react@20.0.0,@nx/js@20.0.0"
​
--create-commits
boolean
default:"false"
Automatically create a git commit after each migration runs. Alias: -C.
​
--commit-prefix
string
default:"\"chore: [nx migration] \""
Custom prefix for commit messages when --create-commits is enabled. Requires --create-commits.
​
--interactive
boolean
default:"false"
Enable interactive prompts to confirm whether to collect optional package updates and migrations.
​
--exclude-applied-migrations
boolean
default:"false"
Exclude migrations that should have already been applied in earlier updates. Must be used with --from.
​
--verbose
boolean
Print additional information about the migration process.

​
Examples

nx migrate latest

​
How migrations.json works

After running nx migrate <version>, Nx creates (or updates) a migrations.json file: 
{
  "migrations": [
    {
      "package": "@nx/react",
      "version": "20.0.0",
      "name": "update-react-config",
      "description": "Updates React configuration to new format",
      "cli": "nx",
      "implementation": "./src/migrations/update-20-0-0/update-react-config"
    }
  ]
}
You can review, reorder, or remove entries in migrations.json before running --run-migrations. Each migration is a code transform (similar to a generator) that modifies workspace files.
Do not modify the generated migrations.json unless you understand the implications. Skipping migrations can leave the workspace in an inconsistent state.

Build docs developers (and LLMs) love

Get started for freeTalk to us