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 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:
Nx reads package.json files across the workspace to discover projects and their names. If project.json files are present, those take precedence.
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.
Nx creates default inputs (source files and package.json) and asks you to specify outputs (build directories) for each cacheable task during setup.
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 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.

​
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

FlagPurpose
nx migrate latest --interactivePrompt before applying optional package updates (e.g., skip a framework major version).
nx migrate --run-migrations --create-commitsCreate 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.jsonRun 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

Build docs developers (and LLMs) love

Get started for freeTalk to us