Nx Monorepo Toolkit

22.6.5 · active · verified Sat Apr 18

Nx is a powerful open-source build system for monorepos, enabling development teams to build, test, and deploy applications faster. It provides advanced features like a project graph, computation caching, and task orchestration, making it ideal for large-scale, multi-project environments. The current stable version is 22.6.5, with frequent updates and beta releases leading up to new minor/major versions, ensuring continuous improvement and support for the latest web technologies.

Common errors

```
NX The "nx" command failed. For more information, please see the errors above.
```
cause A general error occurred during an Nx command execution, often due to an underlying build, test, or lint failure.

fix Scroll up in your terminal to examine the detailed error messages preceding the 'NX command failed' output for the specific cause (e.g., TypeScript error, missing dependency, linter violation).
```
Cannot find module '@swc/core'
```
cause The `@swc/core` peer dependency, essential for many modern Nx workspaces using SWC for compilation, is not installed.

fix Install `@swc/core` as a development dependency: `npm install --save-dev @swc/core @swc-node/register` or `yarn add --dev @swc/core @swc-node/register`.
```
NX There is no project called 'my-app' in this workspace. Run 'nx project-graph' to see a list of all projects.
```
cause The specified project name in an `nx run`, `nx build`, or `nx serve` command does not exist or is misspelled in the workspace configuration (e.g., `project.json` or `workspace.json`).

fix Verify the correct project name by running `nx graph` or checking the relevant `project.json` file. Correct the command with the accurate project name.
```
The current Node.js version (14.x.x) is not supported by Nx. Please upgrade to Node.js 16 or higher.
```
cause Your Node.js version is older than what is required by the current Nx version.

fix Upgrade Node.js to the version recommended by Nx (e.g., using `nvm install 18` and `nvm use 18`) or adjust your project's `.nvmrc` file.
```
Computation caching is not enabled for the "build" target.
```
cause The specified target (e.g., 'build', 'test') has not been configured to use Nx's computation cache in `nx.json` or `project.json`.

fix In your `nx.json` or `project.json`, ensure the target's configuration includes `cache: true` and appropriate `inputs` and `outputs`. For example, `"targetDefaults": { "build": { "cache": true, "inputs": ["default", "^default"], "outputs": ["{projectRoot}/dist"] } }`.

Warnings

breaking Nx frequently introduces breaking changes between major and sometimes minor versions. Always consult the official migration guide for your specific upgrade path.
Fix: Run `nx migrate latest` and follow the prompts to automatically update dependencies and apply necessary code transformations. Review the migration guide for manual steps.
gotcha Nx has specific Node.js version requirements, and using an unsupported version can lead to build errors or unexpected behavior.
Fix: Check the official Nx documentation for the recommended Node.js version for your Nx release and upgrade using a tool like `nvm` (e.g., `nvm install 18 && nvm use 18`).
gotcha Stale computation cache can lead to unexpected build results or outdated artifacts. This often happens after manual file changes outside of standard build processes.
Fix: Clear the Nx computation cache by running `nx reset` or `nx clear-cache` to force a fresh recomputation of tasks.
gotcha Missing peer dependencies like `@swc/core` or `@swc-node/register` can cause compilation failures, especially when using modern Nx plugins.
Fix: Ensure all required peer dependencies are installed in your workspace. For `@swc/core` and `@swc-node/register`, run `npm install --save-dev @swc/core @swc-node/register` or `yarn add --dev @swc/core @swc-node/register`.
gotcha For complex monorepos, the default project graph might not accurately reflect all dependencies, leading to inefficient caching or incorrect task execution.
Fix: Carefully configure `implicitDependencies` and `namedInputs` in your `nx.json` or `project.json` files to ensure all relevant file changes trigger correct task re-execution and caching.

Install

npm install nx npm
yarn add nx yarn
pnpm add nx pnpm

Quickstart

Initializes a new Nx workspace, creates a React application, visualizes the project graph, serves the application, and runs its tests.

# Create a new Nx workspace with a React application
npx create-nx-workspace@latest my-workspace --preset=react --appName=my-app --nxCloud=false
cd my-workspace

# Visualize the project graph
nx graph

# Serve the React application locally
nx serve my-app

# Run tests for the React application
nx test my-app

view raw JSON →