Migrate to Nx

Add Nx to an existing project or monorepo, migrate from Lerna or Turborepo, and keep your workspace up to date with nx migrate.

Nx is designed for incremental adoption. You can add it to any existing codebase with a single command and start with just task caching, then gradually add plugins, CI integrations, and distribution.

Add Nx to an existing project

Run the following command in the root of any existing project or monorepo:

npx nx@latest init

The init command walks you through an interactive setup that:

• Detects your package manager and workspace structure
• Identifies existing scripts in package.json files
• Asks which scripts to cache and what their output directories are
• Creates nx.json with sensible defaults
• Optionally connects to Nx Cloud for remote caching

After initialisation, try these commands:

nx build <project-name>        # Run a task
nx build <project-name>        # Run again — instant cache hit
nx run-many -t build test      # Run tasks across all projects
nx graph                       # Visualise project dependencies

What Nx detects and configures automatically

When you run nx init, Nx inspects your repository and configures:

Project discovery

Nx reads package.json files across the workspace to discover projects and their names. If project.json files are present, those take precedence.

Task configuration

Scripts defined in each package.json become Nx tasks. Nx infers dependsOn relationships (for example, build depends on upstream build) from common patterns and from Nx plugin inference rules.

Caching inputs and outputs

Nx creates default inputs (source files and package.json) and asks you to specify outputs (build directories) for each cacheable task during setup.

Plugin inference

If your projects use supported tools (Vite, Jest, ESLint, Playwright, etc.), the corresponding Nx plugin can be added to infer task configuration automatically — removing manual config duplication.

Migrating from specific tools

Lerna

Lerna workspaces are npm/yarn workspaces underneath. Run:

npx nx@latest init

Nx detects the workspaces field in the root package.json and discovers all packages. Lerna’s lerna.json is not removed; Nx and Lerna can coexist, letting you migrate incrementally.

To replace Lerna’s task orchestration with Nx:

# Instead of: lerna run build
nx run-many -t build

# Instead of: lerna run build --since=main
nx affected -t build

Nx affected is more accurate than Lerna’s --since flag because it uses the full project dependency graph rather than file ownership alone.

Turborepo

Turborepo workspaces are also npm/yarn/pnpm workspaces. Run:

npx nx@latest init

Nx reads your existing turbo.json pipeline configuration and maps it to equivalent task dependencies in nx.json. After init you can remove turbo.json and turbo from your dependencies.

Key differences to be aware of:

• Nx uses dependsOn in targetDefaults instead of Turborepo’s pipeline
• Nx inputs use glob patterns; Turborepo uses inputs arrays
• nx affected uses the project graph; Turborepo’s --filter uses globs

npm/pnpm/yarn workspaces

Plain workspaces with no build orchestration tool are the simplest case:

npx nx@latest init

Nx asks which scripts to make cacheable and creates a minimal nx.json. No existing configuration is removed.

Incremental migration strategy

You don’t need to adopt every Nx feature at once.

1. Start with caching only

   Run npx nx@latest init and answer the setup questions. You immediately get local task caching with no other changes to your workflow.

2. Add remote caching

   Run npx nx@latest connect to link your workspace to Nx Cloud. Cache hits are now shared across your team and CI pipeline.

   npx nx@latest connect
   
3. Add plugins for your tech stack

   Nx plugins for React, Angular, Node, Vite, Jest, and others can infer task configuration from existing tool config files — reducing the amount of configuration you manage manually.

   nx add @nx/react    # React
   nx add @nx/vite     # Vite
   nx add @nx/eslint   # ESLint
   
4. Set up CI with affected commands

   Update your CI pipeline to use nx affected so only changed projects are tested and built on each pull request.

   npx nx affected -t lint test build
   
5. Enable distributed task execution

   Add Nx Agents to your CI configuration to parallelize tasks across multiple machines.

   npx nx-cloud start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"
   

Keeping Nx updated with nx migrate

Use nx migrate to update Nx and all @nx/* packages together. Never update them manually — version mismatches cause subtle errors.

Standard update process

1. Generate the migration plan

   nx migrate latest
   

   This updates package.json and generates a migrations.json file listing the code migrations to apply. No files other than package.json are changed at this point.

2. Install updated dependencies

   npm install   # or pnpm install / yarn
   
3. Apply code migrations

   nx migrate --run-migrations
   

   This runs the scripts in migrations.json, updating configuration files and source code to match the new versions. All changes are left unstaged for you to review.

4. Clean up

   Review and commit the changes, then delete migrations.json.

   git add .
   git commit -m "chore: migrate to nx@latest"
   rm migrations.json
   

Update one major version at a time. Jumping multiple major versions in a single nx migrate may skip intermediate migrations and leave your workspace in an inconsistent state. This is especially important for Angular workspaces, where it is a hard requirement.

Updating community plugins

Community plugins are updated separately:

nx migrate my-plugin

To list all installed plugins:

nx report

Advanced migration options

Flag	Purpose
nx migrate latest --interactive	Prompt before applying optional package updates (e.g., skip a framework major version).
nx migrate --run-migrations --create-commits	Create a separate git commit per migration for easier review.
nx migrate latest --to="jest@29.0.0"	Override the version Nx would install for a specific package.
nx migrate --run-migrations=migrations.json	Run migrations from a custom file path.

Reverting a failed migration

Run migrations on a clean git branch so you can revert easily:

git reset --hard   # Discard all changes
git clean -fd      # Remove newly created files