nx migrate

Update Nx and its plugins, then apply the generated code migrations.

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

Migrate to latest Nx

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.