> ## 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.

# 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:

```shell theme={null}
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:

```shell theme={null}
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:

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Migrating from specific tools

<Tabs>
  <Tab title="Lerna">
    Lerna workspaces are npm/yarn workspaces underneath. Run:

    ```shell theme={null}
    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:

    ```shell theme={null}
    # 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.
  </Tab>

  <Tab title="Turborepo">
    Turborepo workspaces are also npm/yarn/pnpm workspaces. Run:

    ```shell theme={null}
    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
  </Tab>

  <Tab title="npm/pnpm/yarn workspaces">
    Plain workspaces with no build orchestration tool are the simplest case:

    ```shell theme={null}
    npx nx@latest init
    ```

    Nx asks which scripts to make cacheable and creates a minimal `nx.json`. No existing configuration is removed.
  </Tab>
</Tabs>

## Incremental migration strategy

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.

    ```shell theme={null}
    npx nx@latest connect
    ```
  </Step>

  <Step title="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.

    ```shell theme={null}
    nx add @nx/react    # React
    nx add @nx/vite     # Vite
    nx add @nx/eslint   # ESLint
    ```
  </Step>

  <Step title="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.

    ```shell theme={null}
    npx nx affected -t lint test build
    ```
  </Step>

  <Step title="Enable distributed task execution">
    Add Nx Agents to your CI configuration to parallelize tasks across multiple machines.

    ```shell theme={null}
    npx nx-cloud start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"
    ```
  </Step>
</Steps>

## 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

<Steps>
  <Step title="Generate the migration plan">
    ```shell theme={null}
    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.
  </Step>

  <Step title="Install updated dependencies">
    ```shell theme={null}
    npm install   # or pnpm install / yarn
    ```
  </Step>

  <Step title="Apply code migrations">
    ```shell theme={null}
    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.
  </Step>

  <Step title="Clean up">
    Review and commit the changes, then delete `migrations.json`.

    ```shell theme={null}
    git add .
    git commit -m "chore: migrate to nx@latest"
    rm migrations.json
    ```
  </Step>
</Steps>

<Warning>
  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.
</Warning>

### Updating community plugins

Community plugins are updated separately:

```shell theme={null}
nx migrate my-plugin
```

To list all installed plugins:

```shell theme={null}
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:

```shell theme={null}
git reset --hard   # Discard all changes
git clean -fd      # Remove newly created files
```