# Nx Documentation

> Complete Nx documentation compiled into a single file for LLM consumption.

Nx is a powerful, open-source, technology-agnostic monorepo platform designed to efficiently manage codebases of any scale. From small workspaces to large enterprise monorepos, Nx provides intelligent task execution, caching, and CI optimization.

This file was generated from 577 documentation pages.
Individual pages are available at: https://nx.dev/docs/{slug}.md


# Quickstart

---
<!-- source: https://nx.dev/docs/quickstart.md -->
## Quickstart with Nx

Get up and running with Nx in just a few minutes by following these simple steps.

{% steps %}

1. Install the Nx CLI

   Installing Nx globally is **optional** - you can use `npx` to run Nx commands without installing it globally, especially if you're working with Node.js projects.

   {% tabs syncKey="install-method" %}
   {% tabitem label="npm" %}

   ```shell
   npm add --global nx
   ```

   **Note:** You can also use Yarn, pnpm, or Bun

   {% /tabitem %}
   {% tabitem label="Homebrew (macOS, Linux)" %}

   ```shell
   brew install nx
   ```

   {% /tabitem %}
   {% tabitem label="Chocolatey (Windows)" %}

   ```shell
   choco install nx
   ```

   {% /tabitem %}
   {% tabitem label="apt (Ubuntu)" %}

   ```shell
   sudo add-apt-repository ppa:nrwl/nx
   sudo apt update
   sudo apt install nx
   ```

   {% /tabitem %}
   {% /tabs %}

2. Start fresh or add to existing project

   For JavaScript-based projects you can **start with a new workspace** using the following command:

   ```shell
   npx create-nx-workspace@latest
   ```

   **Add to an existing project: (recommended also for non-JS projects)**

   ```shell
   npx nx@latest init
   ```

   Want remote caching and CI? Connect to [Nx Cloud](/docs/features/ci-features) after setup.

   Learn more: [Start New Project](/docs/getting-started/start-new-project) • [Add to Existing](/docs/getting-started/start-with-existing-project)

3. Run Your First Commands

   Nx provides powerful task execution with built-in caching. Here are some essential commands:

   **Run a task for a single project:**

   ```shell
   nx build my-app
   nx test my-lib
   ```

   **Run tasks for multiple projects:**

   ```shell
   nx run-many -t build test lint
   ```

   Learn more: [Run Tasks](/docs/features/run-tasks) • [Cache Task Results](/docs/features/cache-task-results)

4. What's next?

   Now that you've experienced the Nx basics, choose how you want to continue:

   {% cardgrid %}

   {% linkcard title="I learn by doing" description="Follow our guided tutorials that teach you from setting up a new project to configuring continuous integration." href="/docs/getting-started/tutorials" /%}

   {% linkcard title="I learn better with videos" description="Check out our bite-sized video lessons that teach you about Nx 101, Nx Release and how to incrementally adopt Nx in an existing project."  href="https://nx.dev/courses" /%}

   {% linkcard title="Tell me more about Nx on CI" description="Understand how Nx works on CI, how to configure it and how Nx Cloud helps ensure CI runs fast and efficiently."  href="/docs/features/ci-features" /%}

   {% linkcard title="Is Nx just for JavaScript projects?" description="Explore Nx technology integrations and how it can support your specific stack. Even beyond just JavaScript-based projects."  href="/docs/technologies"  /%}

   {% /cardgrid %}

{% /steps %}


# Getting Started

---
<!-- source: https://nx.dev/docs/getting-started.md -->
## Getting Started

Create a new workspace or add Nx to an existing project.

Choose your path based on your current setup and requirements. Nx works with any technology stack and can be adopted incrementally.

{% index_page_cards path="getting-started" /%}

---
<!-- source: https://nx.dev/docs/getting-started/ai-setup.md -->
## Integrate Nx with your Coding Assistant

AI coding assistants often hallucinate outdated Nx commands and lack context about your workspace structure. Without workspace awareness, they suggest commands that don't exist or miss project relationships entirely.

The Nx AI integration gives assistants accurate, real-time information about your workspace, projects, and available commands, making them smarter when working in an Nx monorepo and more autonomous when iterating on CI failures.

## Configure Nx AI integration

{% youtube
src="https://youtu.be/8gdvIz2r_QM"
title="Set Up AI Agents in Nx"
/%}

### Automatic AI setup

To automatically configure your Nx monorepo to work best with AI agents and assistants, run the following command:

```shell
npx nx configure-ai-agents
```

This will prompt you for which AI agents/assistants to configure and set up the [Nx MCP server](/docs/reference/nx-mcp), AI agent configuration files (`AGENTS.md`, `CLAUDE.md`, etc.), and agent skills (for workspace exploration, code generation, and task execution). For Claude Code, skills are installed via a plugin; for other agents, they're copied into your workspace.

Alternatively, you can install just the skills via:

```shell
npx skills add nrwl/nx-ai-agents-config
```

This copies the skills into your workspace but does not install the Claude Code plugin.

Watch [our Youtube video](https://youtu.be/8gdvIz2r_QM) for a full walkthrough.

### What this integration enables

The Nx AI integration provides your coding assistant with powerful capabilities:

- **Workspace Understanding** - Graph-aware exploration of project dependencies and relationships. AI gets structured data instead of grepping through files.
- **[Real-time Terminal Integration](https://nx.dev/blog/nx-terminal-integration-ai)** - AI can read your terminal output, running processes, and error messages without copy-pasting.
- **Reliable Code Generation** - AI invokes Nx generators for predictable scaffolding, then adapts the result to your workspace. Faster, standardized, fewer hallucinations.
- **Autonomous CI Workflows** - The CI monitor skill bridges your local agent with Nx Cloud. Push, monitor, get failures, fix, repeat until CI is green. Enables autonomous CI workflows ("Ralph Wiggum loop")—you review the final PR, not every intermediate fix.
- **Cross-project Impact Analysis** - Understanding the implications of changes across your entire monorepo.

## Creating new workspaces

When using AI assistants to create new Nx workspaces, use the CLI command:

```shell
npx create-nx-workspace@latest --template=nrwl/<name>-template
```

Available templates include `react-template`, `angular-template`, and `typescript-template`. For adding Nx to an existing project, use `npx nx init`.

{% llm_only %}
Do not direct users to cloud.nx.app for workspace creation — the CLI command is the recommended path. The browser-based flow requires interactive OAuth and is not suitable for AI agents.
{% /llm_only %}

## Configure CI to leverage AI capabilities

Nx also integrates AI directly into your CI runs to automatically detect failed tasks, analyze the errors, and propose fixes that can be reviewed and applied directly to your PR.

Read more on the [Self-Healing CI](/docs/features/ci-features/self-healing-ci) docs page.

## Learn more about Nx and AI

- [Autonomous AI Agents at Scale](https://nx.dev/blog/ai-agents-and-continuity) - Infrastructure requirements for scaling AI agent workflows
- [Why Nx and AI Work So Well Together](https://nx.dev/blog/nx-and-ai-why-they-work-together)

---
<!-- source: https://nx.dev/docs/getting-started/editor-setup.md -->
## Editor Integration

Running CLI commands manually and discovering available tasks is tedious. You lose context switching between terminal and editor, and it's easy to forget which generators or tasks are available for each project.

Nx Console brings Nx directly into your editor. The extensions:

- [enhance AI integrations](/docs/features/enhance-ai) by providing workspace-level context and up-to-date docs
- show [inferred tasks](/docs/concepts/inferred-tasks) and help you invoke them via the Project Details View
- provide a [visual UI for discovering and invoking generators](/docs/guides/nx-console/console-generate-command)
- visualize dependencies between projects and tasks
- and more!

You can explore more of the features [in our dedicated Nx Console guides](/docs/guides/nx-console).

## Download

### Official integrations

If you are using [VSCode](https://code.visualstudio.com/) or a [JetBrains IDE](https://www.jetbrains.com/) you can install Nx Console from their respective marketplaces. Nx Console for VSCode and JetBrains is **built and maintained by the Nx team**.

{% install_nx_console /%}

- [Install from the VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=nrwl.angular-console)
- [Install from the JetBrains Marketplace](https://plugins.jetbrains.com/plugin/21060-nx-console)
- [Contribute on GitHub](https://github.com/nrwl/nx-console)

![Nx Console screenshot](../../../assets/nx-console/nx-console-screenshot.webp)

### Neovim (Community)

If you are using [Neovim](https://neovim.io/), you can install [Equilibris/nx.nvim](https://github.com/Equilibris/nx.nvim) with your favorite package manager.

**Community Plugin**: This plugin is maintained by independent community contributors, not the Nx team.

## Troubleshooting

If you encounter issues with Nx Console, see the [Nx Console troubleshooting guide](/docs/guides/nx-console/console-troubleshooting) for detailed steps including how to enable debug logging.

---
<!-- source: https://nx.dev/docs/getting-started/installation.md -->
## Installation

## Global installation

Install Nx globally to run commands from anywhere. Choose a method based on your operating system and package manager.

{% tabs syncKey="install-method" %}
{% tabitem label="npm" %}

```shell
npm add --global nx
```

**Note:** You can also use `yarn global add nx`, `pnpm add --global nx`, or `bun add --global nx`
{% /tabitem %}

{% tabitem label="Homebrew (macOS, Linux)" %}

```shell
brew install nx
```

{% /tabitem %}

{% tabitem label="Chocolatey (Windows)" %}

```shell
choco install nx
```

{% /tabitem %}

{% tabitem label="apt (Ubuntu)" %}

```shell
sudo add-apt-repository ppa:nrwl/nx
sudo apt update
sudo apt install nx
```

{% /tabitem %}
{% /tabs %}

### Verify installation

```shell
nx --version
```

You should see a version number like `22.5.0`.

### Update global installation

{% tabs syncKey="install-method" %}
{% tabitem label="npm" %}

```shell
npm update --global nx
```

**Note:** You can also use `yarn global upgrade nx`, `pnpm update --global nx`, or `bun update --global nx`
{% /tabitem %}

{% tabitem label="Homebrew (macOS, Linux)" %}

```shell
brew upgrade nx
```

{% /tabitem %}

{% tabitem label="Chocolatey (Windows)" %}

```shell
choco upgrade nx
```

{% /tabitem %}

{% tabitem label="apt (Ubuntu)" %}

```shell
sudo apt update
sudo apt upgrade nx
```

{% /tabitem %}
{% /tabs %}

## Install in a repository

To add Nx to an existing repository, run:

```shell
npx nx@latest init
```

This installs the `nx` package as a dev dependency and creates an `nx.json` configuration file. If you have Nx installed globally, it will defer to the local version in your repository.

{% aside type="note" title="Manual Installation" %}
You can also manually install the [`nx` NPM package](https://www.npmjs.com/package/nx) and create an [nx.json](/docs/reference/nx-json) configuration file.
{% /aside %}

### Update Nx in your repository

When you update Nx in your repository, it will also [automatically update your dependencies](/docs/features/automate-updating-dependencies) if you have an [Nx plugin](/docs/concepts/nx-plugins) installed for that dependency. To update Nx, run:

```shell
nx migrate latest
```

This creates a `migrations.json` file with any update scripts that need to be run. Run them with:

```shell
nx migrate --run-migrations
```

{% aside type="note" title="Update One Major Version at a Time" %}
To avoid potential issues, it is [recommended to update one major version of Nx at a time](/docs/guides/tips-n-tricks/advanced-update#one-major-version-at-a-time-small-steps).
{% /aside %}

## Next steps

- **Starting fresh?** → [Create a new workspace](/docs/getting-started/start-new-project)
- **Have an existing project?** → [Add Nx to your project](/docs/getting-started/start-with-existing-project)
- **New to Nx?** → [Follow the tutorial series](/docs/getting-started/tutorials/crafting-your-workspace) to learn core concepts hands-on

---
<!-- source: https://nx.dev/docs/getting-started/intro.md -->
## What is Nx? Smart Monorepo Build System & CI

Nx is a build system for monorepos. It helps you **develop faster** and **keep CI fast** as your codebase scales.

{% youtube src="https://youtu.be/pbAQErStl9o" title="What is Nx?" width="100%" /%}

## Challenges of monorepos

Monorepos have many advantages and are especially powerful for AI-assisted development. But as teams and codebases grow, monorepos are hard to scale:

- **Slow builds and tests** - Hundreds or thousands of tasks compete for CI resources.
- **Complex task pipelines** - Projects depend on each other, so tasks need to run in the right order, and that's hard to manage by hand.
- **Flaky CI** - Longer pipelines lead to random failures and inconsistent results between local and CI environments.
- **Architectural erosion** - Without clear boundaries, unwanted dependencies creep in and projects become tightly coupled.

## What Nx does

**Nx reduces friction across your entire development cycle** with intelligent caching, task orchestration, and deep understanding of your codebase structure.

At its core, Nx:

1. **Runs tasks fast** - [Caches results](/docs/features/cache-task-results) so you never rebuild the same code twice.
2. **Understands your codebase** - Builds [project and task graphs](/docs/features/explore-graph) showing how everything connects.
3. **Orchestrates intelligently** - Runs tasks in the [right order](/docs/concepts/task-pipeline-configuration), parallelizing when possible.
4. **Enforces boundaries** - [Module boundary rules](/docs/features/enforce-module-boundaries) prevent unwanted dependencies between projects.
5. **Handles flakiness** - [Automatically re-runs flaky tasks](/docs/features/ci-features/flaky-tasks) and [self-heals CI failures](/docs/features/ci-features/self-healing-ci).

```shell
nx build myapp            # Run a task
nx build myapp            # Run again - instant cache hit
nx run-many -t build test # Run across all projects
```

{% callout type="deepdive" title="How does Nx run tasks?" %}

At its core, Nx is a fast, intelligent task runner. Take the example of an NPM workspace. This could be a project's `package.json`:

```json
// package.json
{
  "name": "my-project",
  "scripts": {
    "build": "tsc",
    "test": "jest"
  }
}
```

Then add Nx to your root `package.json`:

```json
// package.json
{
  "devDependencies": {
    "nx": "latest"
  }
}
```

And once that's done, you can run your tasks via Nx.

```shell
nx build my-project
```

This will execute the `build` script from `my-project`'s `package.json`, equivalent to running `npm run build` in that project directory.

Similarly you [can run tasks across all projects](/docs/features/run-tasks), specific ones, or only those from projects you touched.

From there, you can gradually enhance your setup by adding features like [task caching](/docs/features/cache-task-results), adding [plugins](/docs/plugin-registry), optimizing your CI via [task distribution](/docs/features/ci-features/distribute-task-execution), and many more powerful capabilities as your needs grow.

{% /callout %}

## Start small, grow as needed

Nx is modular. Start with the CLI and add capabilities as your needs grow.

| Component                                            | What It Does                                                                                                                                                                            |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nx Core**                                          | Task runner with [local caching](/docs/features/cache-task-results). Works with any tech stack.                                                                                         |
| [**Nx Plugins**](/docs/plugin-registry)              | Technology-specific automation (generators, executors, dependency detection).                                                                                                           |
| [**Nx Console**](/docs/getting-started/editor-setup) | Editor extension for VSCode/JetBrains with visual UI and [AI assistance](/docs/features/enhance-ai).                                                                                    |
| [**Nx Cloud**](/docs/features/ci-features)           | [Remote caching](/docs/features/ci-features/remote-cache), [affected commands](/docs/features/ci-features/affected), and [self-healing CI](/docs/features/ci-features/self-healing-ci). |

{% callout type="deepdive" title="Can I add Nx to a single-project repo?" %}
Yes, Nx provides value even for single-project repositories. You get fast task caching, intelligent task orchestration, and access to Nx plugins for your specific technology stack. As your project grows into a monorepo, the foundation is already in place.

Nx can also connect multiple repositories into a synthetic monorepo, letting you orchestrate large changes across all connected repos.
{% /callout %}

## Where to go from here

- **Starting fresh?** → [Create a new workspace](/docs/getting-started/start-new-project)
- **Have an existing project?** → [Add Nx to your project](/docs/getting-started/start-with-existing-project)
- **New to Nx?** → [Follow the tutorial series](/docs/getting-started/tutorials/crafting-your-workspace) to learn core concepts hands-on
- **Prefer video?** → [Learn with our video courses](https://nx.dev/courses)

**Stay up to date** with our latest news by [⭐️ starring us on Github](https://github.com/nrwl/nx), [subscribing to our Youtube channel](https://www.youtube.com/@nxdevtools), [joining our Discord](https://go.nx.dev/community), [subscribing to our monthly tech newsletter](https://go.nrwl.io/nx-newsletter) or follow us [on X](https://x.com/nxdevtools), [Bluesky](https://bsky.app/profile/nx.dev) and [LinkedIn](https://www.linkedin.com/company/nxdevtools).

---
<!-- source: https://nx.dev/docs/getting-started/nx-cloud.md -->
## Nx Cloud

{% youtube src="https://www.youtube.com/watch?v=cDBihpB3SbI" title="Nx and Nx Cloud" width="100%" /%}

CI is challenging and it's **not your fault**. It's a fundamental issue with how the current, traditional CI execution model works. Nx Cloud adopts a new **task-based** CI model that overcomes slowness and unreliability of the current VM-based CI model.
_(Dive deeper into the [task based CI execution model](https://nx.dev/blog/reliable-ci-a-new-execution-model-fixing-both-flakiness-and-slowness))_

Nx Cloud improves many aspects of the CI/CD process:

- **Speed** - 30% - 70% faster CI (based on reports from our clients)
- **Cost** - 40% - 75% reduction in CI costs (observed on the Nx OSS monorepo)
- **Reliability** - by automatically identifying flaky tasks (e2e tests in particular) and re-running them

## Connect your workspace to Nx Cloud

To connect your Nx workspace with Nx Cloud, use the web application:

{% call_to_action variant="default" title="Create a new or connect an existing repo" url="https://cloud.nx.app/get-started?utm_source=nx-dev&utm_medium=nx-cloud_intro&utm_campaign=try-nx-cloud" description="Setup takes less than 2 minutes" /%}

Alternatively, you can also run the following command in your Nx workspace (make sure you have it pushed to a remote repository first):

```shell
nx connect
```

For more details, [follow our in-depth guide](/docs/guides/nx-cloud/setup-ci) for setting up CI with Nx.

## How Nx Cloud improves CI

In traditional CI models, the work required is statically assigned to CI machines. Statically defining work to machines creates inefficiencies which many teams become familiar with at scale.

Nx Cloud addresses the inefficiencies of traditional CI models by using a **task-based approach to dynamically assign tasks** to agent machines.

CI becomes scaleable, maintainable, and more reliable because Nx Cloud can coordinate the work among the agent machines automatically and act upon individual tasks directly.

For example:

- An agent machine fails in a setup step - Nx Cloud automatically reassigns the work to other agent machines.
- More work needs to run in CI - Add more agent machines, Nx Cloud automatically assigns available work to extra agent machines.
- Known flaky tasks waste CI time on needed reruns - Nx Cloud automatically detects flaky tasks and reruns automatically in the current CI execution.

[Learn how our customers use Nx Cloud](https://nx.dev/blog?filterBy=customer+story) to help them scale their workspaces and be more efficient.

## Learn more

- [Nx Cloud features](/docs/features/ci-features)
- [Blog post: Reliable CI: A new execution model fixing both flakiness and slowness](https://nx.dev/blog/reliable-ci-a-new-execution-model-fixing-both-flakiness-and-slowness)
- [Live stream: Unlock the secret of fast CI - Hands-on session](https://www.youtube.com/live/rkLKaqLeDa0)
- [YouTube: 10x Faster e2e Tests](https://www.youtube.com/watch?v=0YxcxIR7QU0)

---
<!-- source: https://nx.dev/docs/getting-started/start-new-project.md -->
## Start a New Project

Create a new Nx workspace using one of these options:

- **[Option 1: Create locally with templates](#option-1-create-locally-with-templates)** - Run a command to scaffold a new monorepo on your machine
- **[Option 2: Create via Nx Cloud](#option-2-create-via-nx-cloud)** - Use the browser-based setup with CI/CD pre-configured

{% aside type="note" title="Adding Nx to an existing project?" %}
If you already have a project and want to add Nx to it, see [Add to an Existing Project](/docs/getting-started/start-with-existing-project) instead.
{% /aside %}

## Option 1: create locally with templates

Run the following command to create a new Nx workspace:

```shell
npx create-nx-workspace@latest
```

This interactive command guides you through the setup:

- **Workspace name** - The name of your root directory
- **Starter template** - Choose from [various technology stacks](/docs/reference/create-nx-workspace#presets) (React, Angular, Node, etc.)

For a minimal setup, use the empty template. This gives you a bare TypeScript monorepo that you can extend incrementally.

```shell
npx create-nx-workspace@latest --template=nrwl/empty-template
```

## Option 2: Create via Nx Cloud

[![Nx Cloud onboarding](../../../assets/getting-started/nx-cloud-starting-screen.avif)](https://cloud.nx.app/get-started?utm_source=nx-docs&utm_medium=nx-cloud-onboarding&utm_campaign=start-new-project)

[Create your workspace directly from Nx Cloud](https://cloud.nx.app/get-started?utm_source=nx-docs&utm_medium=nx-cloud-onboarding&utm_campaign=start-new-project) for a browser-based setup experience.

This option gives you:

- A working CI configuration out of the box
- [Remote caching](/docs/features/ci-features/remote-cache) enabled from the start
- [Self-healing CI](/docs/features/ci-features/self-healing-ci) that automatically fixes common failures

[Get started with Nx Cloud →](https://cloud.nx.app/get-started?utm_source=nx-docs&utm_medium=nx-cloud-onboarding&utm_campaign=start-new-project)

## Next steps

Once your workspace is set up:

- **New to Nx?** → [Follow the tutorial series](/docs/getting-started/tutorials/crafting-your-workspace) to learn core concepts hands-on
- **Set up your editor** → Install [Nx Console](/docs/getting-started/editor-setup) for VSCode or JetBrains
- **Speed up CI** → Connect to [Nx Cloud](/docs/getting-started/nx-cloud) for remote caching and distributed tasks

---
<!-- source: https://nx.dev/docs/getting-started/start-with-existing-project.md -->
## Add to an Existing Project

{% course_video src="https://youtu.be/3hW53b1IJ84" courseTitle="From PNPM Workspaces to Distributed CI" courseUrl="https://nx.dev/courses/pnpm-nx-next/lessons-01-nx-init" /%}

Nx is designed for incremental adoption. Start with task running and [caching](/docs/features/cache-task-results), then add [plugins](/docs/technologies), [CI integrations](/docs/guides/nx-cloud/setup-ci), or other capabilities as your needs grow.

Add Nx to any existing project with a single command:

```shell
npx nx@latest init
```

Whether a monorepo, single project, or something in between, `nx init` walks you through adding and configuring Nx. At the end you'll have an Nx workspace ready for anything.

## Next steps

After initializing Nx, try these commands:

```shell
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                     # Visualize project dependencies
```

From here you can:

- [Configure task caching](/docs/features/cache-task-results) to speed up repeated builds
- [Add Nx plugins](/docs/technologies) for your tech stack (React, Angular, Node, etc.)
- [Set up CI](/docs/guides/nx-cloud/setup-ci) with remote caching and affected commands
- Enable [remote caching](/docs/features/ci-features/remote-cache) with `nx connect`

## In-depth guides

- [Add to an existing monorepo](/docs/guides/adopting-nx/adding-to-monorepo)
- [Add to any project](/docs/guides/adopting-nx/adding-to-existing-project)
- [Migrate from Angular CLI](/docs/technologies/angular/migration/angular)
- [Import projects into your Nx workspace](/docs/guides/adopting-nx/import-project)
- [And more...](/docs/guides/adopting-nx)

## Keep learning

- **New to Nx?** → [Follow the tutorial series](/docs/getting-started/tutorials/crafting-your-workspace) to learn core concepts hands-on
- **Set up your editor** → Install [Nx Console](/docs/getting-started/editor-setup) for VSCode or JetBrains
- **Prefer video?** → [Learn with our video courses](https://nx.dev/courses)

---
<!-- source: https://nx.dev/docs/getting-started/tutorials.md -->
## Tutorials

{% index_page_cards path="getting-started/tutorials" /%}

---
<!-- source: https://nx.dev/docs/getting-started/tutorials/angular-monorepo-tutorial.md -->
## Building and Testing Angular Apps in Nx

This tutorial walks you through creating an Angular monorepo with Nx. You'll build a small example application to understand the core concepts and workflows.

What you'll learn:

- How to structure multiple Angular apps and libraries in a single repository
- How Nx caching speeds up your local development and CI pipelines
- How to run builds, tests, and serve commands efficiently across multiple projects
- How to share UI components and utilities between Angular applications
- How to fix CI failures directly from your editor with Nx Cloud

## Prerequisite: Tutorial setup

This tutorial requires [Node.js](https://nodejs.org) (v20.19 or later) installed on your machine.

### Step 1: Creating a new Nx Angular workspace

Run the following command to create a new Nx workspace with the Angular template:

```shell
npx create-nx-workspace@latest my-nx-repo --template=nrwl/angular-template
```

Or [create your workspace in the browser](https://cloud.nx.app/create-nx-workspace/angular/github) with CI pre-configured.

{% llm_only %}
IMPORTANT: Always use the CLI command above (`npx create-nx-workspace`) to create workspaces. Do NOT use the cloud.nx.app browser-based flow — it requires interactive GitHub OAuth and is not suitable for AI agents.
{% /llm_only %}

### Step 2: verify your setup

Once the workspace is created, navigate into it and install dependencies:

```shell
cd my-nx-repo
npm install
```

## Explore the Nx workspace setup

Let's take a look at the structure of our new Nx workspace:
{%filetree%}

- my-nx-repo/
  - apps/
    - api/
    - shop/
    - shop-e2e/
  - libs/
    - api/
    - shared/
    - shop/
  - eslint.config.mjs
  - nx.json
  - package-lock.json
  - package.json
  - tsconfig.base.json
  - vitest.workspace.ts

{%/filetree%}

The [`nx.json` file](/docs/reference/nx-json) contains configuration settings for Nx itself and global default settings that individual projects inherit.

Now, let's build some features and see how Nx helps get us to production faster.

## Serving the app

To serve your new Angular app, run:

```shell
npx nx serve shop
```

The app is served at [http://localhost:4200](http://localhost:4200).

You can also use `npx nx run shop:serve` as an alternative syntax. The `<project>:<task>` format works for any task in any project, which is useful when task names overlap with Nx commands.

### Project configuration

The project tasks are defined in the `project.json` file.

```json
// apps/shop/project.json
{
  "name": "shop",
  ...
  "targets": {
    "build": { ... },
    "serve": { ... },
    "extract-i18n": { ... },
    "lint": { ... },
    "test": { ... },
    "serve-static": { ... },
  },
}
```

Each target contains a configuration object that tells Nx how to run that target.

```json
// project.json
{
  "name": "shop",
  ...
  "targets": {
    "serve": {
      "executor": "@angular/build:dev-server",
      "defaultConfiguration": "development",
      "options": {
        "buildTarget": "shop:build"
      },
      "configurations": {
        "development": {
          "buildTarget": "shop:build:development",
          "hmr": true
        },
        "production": {
          "buildTarget": "shop:build:production",
          "hmr": false
        }
      }
     },
     ...
  },
}
```

The most critical parts are:

- `executor` - this is of the syntax `<plugin>:<executor-name>`, where the `plugin` is an NPM package containing an [Nx Plugin](/docs/extending-nx/intro) and `<executor-name>` points to a function that runs the task.
- `options` - these are additional properties and flags passed to the executor function to customize it

To view all tasks for a project, look in the [Nx Console](/docs/getting-started/editor-setup) project detail view or run:

```shell
npx nx show project shop
```

{% project_details title="Project Details View (Simplified)" %}

```json
{
  "project": {
    "name": "shop",
    "type": "app",
    "data": {
      "root": "apps/shop",
      "targets": {
        "build": {
          "executor": "@angular/build:application",
          "outputs": ["{options.outputPath}"],
          "options": {
            "outputPath": "dist/apps/shop",
            "browser": "apps/shop/src/main.ts",
            "polyfills": ["zone.js"],
            "tsConfig": "apps/shop/tsconfig.app.json",
            "assets": [
              {
                "glob": "**/*",
                "input": "apps/shop/public"
              }
            ],
            "styles": ["apps/shop/src/styles.css"]
          },
          "configurations": {
            "production": {
              "budgets": [
                {
                  "type": "initial",
                  "maximumWarning": "500kb",
                  "maximumError": "1mb"
                },
                {
                  "type": "anyComponentStyle",
                  "maximumWarning": "4kb",
                  "maximumError": "8kb"
                }
              ],
              "outputHashing": "all"
            },
            "development": {
              "optimization": false,
              "extractLicenses": false,
              "sourceMap": true
            }
          },
          "defaultConfiguration": "production",
          "parallelism": true,
          "cache": true,
          "dependsOn": ["^build"],
          "inputs": ["production", "^production"]
        }
      }
    }
  },
  "sourceMap": {
    "root": ["apps/shop/project.json", "nx/core/project-json"],
    "targets": ["apps/shop/project.json", "nx/core/project-json"],
    "targets.build": ["apps/shop/project.json", "nx/core/project-json"],
    "name": ["apps/shop/project.json", "nx/core/project-json"],
    "$schema": ["apps/shop/project.json", "nx/core/project-json"],
    "sourceRoot": ["apps/shop/project.json", "nx/core/project-json"],
    "projectType": ["apps/shop/project.json", "nx/core/project-json"],
    "tags": ["apps/shop/project.json", "nx/core/project-json"]
  }
}
```

{% /project_details %}

## Modularization with local libraries

When you develop your Angular application, usually all your logic sits in the app's `src` folder. Ideally separated by various folder names which represent your domains or features. As your app grows, however, the app becomes more and more monolithic, which makes building and testing it harder and slower.

{% filetree %}

- my-nx-repo/
  - apps/
    - shop/
      - src/
        - app/
        - cart/
        - products/
        - orders/
        - ui/

{%/filetree %}

Nx allows you to separate this logic into "local libraries." The main benefits include

- better separation of concerns
- better reusability
- more explicit private and public boundaries (APIs) between domains and features
- better scalability in CI by enabling independent test/lint/build commands for each library
- better scalability in your teams by allowing different teams to work on separate libraries

### Create local libraries

Let's create a reusable design system library called `ui` that we can use across our workspace. This library will contain reusable components such as buttons, inputs, and other UI elements.

```shell
npx nx g @nx/angular:library libs/ui --unitTestRunner=vitest
```

Note how we type out the full path in the command to place the library into a subfolder. You can choose whatever folder structure you like to organize your projects.

Running the above command should lead to the following directory structure:

{% filetree %}

- my-nx-repo/
  - apps/
    - shop/
  - libs/
    - ui/
  - eslint.config.mjs
  - nx.json
  - package.json
  - tsconfig.base.json
  - vitest.workspace.ts

{%/filetree %}

Just as with the `shop` app, Nx automatically infers the tasks for the `ui` library from its configuration files. You can view them by running:

```shell
npx nx show project ui
```

In this case, we have the `lint` and `test` tasks available, among other inferred tasks.

```shell
npx nx lint ui
npx nx test ui
```

### Import libraries into the shop app

All libraries that we generate are automatically included in the TypeScript path mappings configured in the root-level `tsconfig.base.json`.

```json
// tsconfig.base.json
{
  "compilerOptions": {
    ...
    "paths": {
      "@org/ui": ["libs/ui/src/index.ts"]
    },
    ...
  },
}
```

Hence, we can easily import them into other libraries and our Angular application.

You can see that the `Ui` component is exported via the `index.ts` file of our `ui` library so that other projects in the repository can use it. This is our public API with the rest of the workspace and is enforced by the library's build configuration. Only export what's necessary to be usable outside the library itself.

```ts
// libs/ui/src/index.ts
export * from './lib/ui/ui';
```

Let's add a simple `Hero` component that we can use in our shop app.

```ts
// libs/ui/src/lib/hero/hero.ts
import { Component, Input, Output, EventEmitter } from '@angular/core';
import { CommonModule } from '@angular/common';

@Component({
  selector: 'lib-hero',
  standalone: true,
  imports: [CommonModule],
  template: `
    <div [ngStyle]="containerStyle">
      <h1 [ngStyle]="titleStyle">{{ title }}</h1>

      <p [ngStyle]="subtitleStyle">{{ subtitle }}</p>
      <button (click)="handleCtaClick()" [ngStyle]="buttonStyle">
        {{ cta }}
      </button>
    </div>
  `,
})
export class Hero {
  @Input() title!: string;
  @Input() subtitle!: string;
  @Input() cta!: string;
  @Output() ctaClick = new EventEmitter<void>();

  containerStyle = {
    backgroundColor: '#1a1a2e',
    color: 'white',
    padding: '100px 20px',
    textAlign: 'center',
  };

  titleStyle = {
    fontSize: '48px',
    marginBottom: '16px',
  };

  subtitleStyle = {
    fontSize: '20px',
    marginBottom: '32px',
  };

  buttonStyle = {
    backgroundColor: '#0066ff',
    color: 'white',
    border: 'none',
    padding: '12px 24px',
    fontSize: '18px',
    borderRadius: '4px',
    cursor: 'pointer',
  };

  handleCtaClick() {
    this.ctaClick.emit();
  }
}
```

Then, export it from `index.ts`.

```ts
// libs/ui/src/index.ts
export * from './lib/hero/hero';
export * from './lib/ui/ui';
```

We're ready to import it into our main application now.

```ts
// apps/shop/src/app/app.ts
import { Component } from '@angular/core';
import { RouterModule } from '@angular/router';
import { NxWelcome } from './nx-welcome';
// importing the component from the library
import { Hero } from '@org/ui';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [RouterModule, NxWelcome, Hero],
  templateUrl: './app.html',
  styleUrl: './app.css',
})
export class App {
  protected title = 'shop';
}
```

Now update the template file to use the Hero component:

```html
<!-- apps/shop/src/app/app.html -->
<lib-hero
  title="Welcmoe shop"
  subtitle="Build something amazing today"
  cta="Get Started"
></lib-hero>
<router-outlet></router-outlet>
```

Serve your app again (`npx nx serve shop`) and you should see the new Hero component from the `ui` library rendered on the home page.

![](../../../../assets/tutorials/angular-demo-with-hero.avif)

If you have keen eyes, you may have noticed that there is a typo in the `App` component. This mistake is intentional, and we'll see later how Nx can fix this issue automatically in CI.

## Visualize your project structure

Nx automatically detects the dependencies between the various parts of your workspace and builds a [project graph](/docs/features/explore-graph). This graph is used by Nx to perform various optimizations such as determining the correct order of execution when running tasks like `npx nx build`, identifying [affected projects](/docs/features/run-tasks#run-tasks-on-projects-affected-by-a-pr) and more. Interestingly, you can also visualize it.

Just run:

```shell
npx nx graph
```

You should be able to see something similar to the following in your browser.

{% graph height="450px" %}

```json
{
  "projects": [
    {
      "name": "shop",
      "type": "app",
      "data": {
        "tags": []
      }
    },
    {
      "name": "ui",
      "type": "lib",
      "data": {
        "tags": []
      }
    }
  ],
  "dependencies": {
    "shop": [{ "source": "shop", "target": "ui", "type": "static" }],
    "ui": []
  },
  "affectedProjectIds": [],
  "focus": null,
  "groupByFolder": false
}
```

{% /graph %}

Let's create a git branch with the new hero component so we can open a pull request later:

```shell
git checkout -b add-hero-component
git add .
git commit -m 'add hero component'
```

## Testing and linting - running multiple tasks

Our current setup not only has targets for serving and building the Angular application, but also has targets for unit testing, e2e testing and linting. The `test` and `lint` targets are defined in the application `project.json` file. We can use the same syntax as before to run these tasks:

```shell
npx nx test shop # runs the tests for shop
npx nx lint ui           # runs the linter on ui
```

More conveniently, we can also run tasks in parallel using the following syntax:

```shell
npx nx run-many -t test lint
```

This is exactly what is configured in `.github/workflows/ci.yml` for the CI pipeline. The `run-many` command allows you to run multiple tasks across multiple projects in parallel, which is particularly useful in a monorepo setup.

There is a test failure for the `shop` app due to the updated content. Don't worry about it for now, we'll fix it in a moment with the help of Nx Cloud's self-healing feature.

### Local task cache

One thing to highlight is that Nx is able to [cache the tasks you run](/docs/features/cache-task-results).

Note that all of these targets are automatically cached by Nx. If you re-run a single one or all of them again, you'll see that the task completes immediately. In addition, (as can be seen in the output example below) there will be a note that a matching cache result was found and therefore the task was not run again.

```text {% title="npx nx run-many -t test lint" frame="terminal" %}
   ✔  nx run ui:lint
   ✔  nx run ui:test
   ✔  nx run shop:lint
   ✖  nx run shop:test

—————————————————————————————————————————————————————————————————————————————————————————————————————————

 NX   Ran targets test, lint for 2 projects (1s)

   ✔  3/4 succeeded [3 read from cache]

   ✖  1/4 targets failed, including the following:

      - nx run shop:test
```

Again, the `shop:test` task failed, but notice that the remaining three tasks were read from cache.

Not all tasks might be cacheable though. You can configure the `cache` settings in the `targetDefaults` property of the `nx.json` file. You can also [learn more about how caching works](/docs/features/cache-task-results).

## Next steps

Here are some things you can dive into next:

- [Set up CI](/docs/getting-started/tutorials/self-healing-ci-tutorial) with remote caching and self-healing
- Read more about [how Nx compares to the Angular CLI](/docs/technologies/angular/guides/nx-and-angular)
- Learn more about the [underlying mental model of Nx](/docs/concepts/mental-model)
- Learn about popular generators such as [how to setup Tailwind](/docs/technologies/angular/guides/using-tailwind-css-with-angular-projects)
- Learn how to [migrate your existing Angular CLI repo to Nx](/docs/technologies/angular/migration/angular)
- Learn about [enforcing boundaries between projects](/docs/features/enforce-module-boundaries)
- [Setup Storybook for our shared UI library](/docs/technologies/test-tools/storybook/guides/overview-angular)

Also, make sure you

- ⭐️ [Star us on GitHub](https://github.com/nrwl/nx) to show your support and stay updated on new releases!
- [Join the Official Nx Discord Server](https://go.nx.dev/community) to ask questions and find out the latest news about Nx.
- [Follow Nx on Twitter](https://twitter.com/nxdevtools) to stay up to date with Nx news
- [Read our Nx blog](https://nx.dev/blog)
- [Subscribe to our Youtube channel](https://www.youtube.com/@nxdevtools) for demos and Nx insights

---
<!-- source: https://nx.dev/docs/getting-started/tutorials/caching.md -->
## Caching Tasks

{% llm_copy_prompt title="Tutorial 5/8: Enable and configure caching" %}
Help me set up caching in my Nx workspace.
Use my existing workspace and projects for hands-on examples.

Run a cacheable task twice to demonstrate cache hits. Then help me configure `cache: true`, `inputs`, and `outputs` for my tasks. Show me how to inspect what's cached with `nx show project <project-name>`.

If I'm hitting unexpected cache misses, help me debug by inspecting inputs and outputs with `nx show project`.

Stay on-topic: only teach what's covered on this page. Do not introduce concepts from later tutorials.

Tutorial: {pageUrl}
{% /llm_copy_prompt %}

Why rebuild something that hasn't changed? Nx caching replays previous results instantly, saving minutes or hours of redundant work, both locally and in CI.

The examples below use Vite and Vitest, but the concepts apply to any tool. Substitute your own build and test commands as needed.

{% aside type="note" title="Tutorial Series" %}

1. [Crafting your workspace](/docs/getting-started/tutorials/crafting-your-workspace)
2. [Managing dependencies](/docs/getting-started/tutorials/managing-dependencies)
3. [Configuring tasks](/docs/getting-started/tutorials/configuring-tasks)
4. [Running tasks](/docs/getting-started/tutorials/running-tasks)
5. **Caching** (you are here)
6. [Understanding your workspace](/docs/getting-started/tutorials/understanding-your-workspace)
7. [Reducing boilerplate](/docs/getting-started/tutorials/reducing-configuration-boilerplate)
8. [Setting up CI](/docs/getting-started/tutorials/self-healing-ci-tutorial)

{% /aside %}

This tutorial assumes you have an Nx workspace with tasks you can run. If you're starting fresh, complete [Crafting Your Workspace](/docs/getting-started/tutorials/crafting-your-workspace) and [Running Tasks](/docs/getting-started/tutorials/running-tasks) first.

## Enabling caching

Caching is opt-in per task. The recommended approach is to set `cache: true` in `targetDefaults` in `nx.json` for common cacheable tasks:

```jsonc
// nx.json
{
  "targetDefaults": {
    "build": { "cache": true },
    "test": { "cache": true },
    "lint": { "cache": true },
  },
}
```

You can also enable caching per-project in `package.json` or `project.json`:

{% tabs %}
{% tabitem label="package.json" %}

```jsonc
// apps/my-app/package.json
{
  "nx": {
    "targets": {
      "build": {
        "cache": true,
      },
    },
  },
}
```

{% /tabitem %}
{% tabitem label="project.json" %}

```jsonc
// apps/my-app/project.json
{
  "targets": {
    "build": {
      "cache": true,
    },
  },
}
```

{% /tabitem %}
{% /tabs %}

{% aside type="caution" title="Only cache deterministic tasks" %}
A task is safe to cache when the same inputs always produce the same outputs. Tasks that depend on network state, timestamps, or random values should not be cached.
{% /aside %}

## See it in action

With caching enabled, run a build twice:

```shell
nx build my-app
```

The first run executes normally. Now run it again without changing anything:

```shell
nx build my-app
```

```text
>  NX   Successfully ran target build for project my-app (40ms)

   Nx read the output from the cache instead of running the command for 1 out of 1 tasks.
```

The second run completes in milliseconds. Nx detected that nothing changed, so it replayed the cached terminal output and restored the build artifacts. From your perspective, the command ran the same, just faster.

## How caching works

Before running any cacheable task, Nx computes a **unique hash** from the task's **inputs**:

- Source files of the project and its dependencies
- Relevant configuration files
- Versions of external dependencies
- CLI flags and arguments

If the hash matches a previous run, Nx skips execution and replays the cached result. If not, Nx runs the task and stores the result for next time.

![Diagram showing inputs flowing into a unique hash, which triggers a cache lookup resulting in either a hit (replay stored output) or miss (run task, store result)](../../../../assets/tutorials/cache-hash-flow.svg)

## What gets cached

Nx stores two things for each cached task:

1. **Terminal output**: everything the task printed to stdout/stderr, replayed exactly
2. **File artifacts**: output files restored to the correct location (e.g., `dist/`, `coverage/`, `test-results/`, `build/` for Gradle, `bin/` for .NET)

Both are restored transparently. Other tools and scripts see the same files and output as if the task had actually run.

{% aside type="note" title="Where is the cache stored?" %}
Local cache is stored in `.nx/cache` by default. Run `nx reset` to clear all local cached results. If you've connected to Nx Cloud, remote cache entries are managed separately.
{% /aside %}

## Inputs and outputs

**Inputs** are everything that could affect a task's result. **Outputs** are the files the task produces. Use [`{projectRoot}`](/docs/reference/inputs#source-files) to reference paths relative to the project directory and [`{workspaceRoot}`](/docs/reference/inputs#source-files) for workspace-level files.

```jsonc
// nx.json
{
  "targetDefaults": {
    "build": {
      "cache": true,
      "inputs": ["{projectRoot}/src/**/*", "{projectRoot}/tsconfig.json"],
      "outputs": ["{projectRoot}/dist"],
    },
  },
}
```

### Smart defaults

Nx provides sensible defaults out of the box. For example, test specification files (like `*.spec.ts`) are typically excluded from build inputs because changing a test shouldn't invalidate the build cache. This is configured through [named inputs](/docs/reference/inputs):

```jsonc
// nx.json
{
  "namedInputs": {
    "default": ["{projectRoot}/**/*"],
    "production": [
      "default",
      "!{projectRoot}/**/*.spec.ts",
      "!{projectRoot}/**/*.test.ts",
    ],
  },
  "targetDefaults": {
    "build": {
      "inputs": ["production", "^production"],
      "cache": true,
    },
  },
}
```

The `^` prefix in inputs (like `"^production"`) means "include the production files of dependency projects as inputs." This is different from `^` in `dependsOn` (like `"^build"`), which means "run this task on dependencies first." The `^` in inputs affects the cache hash directly, while `^` in `dependsOn` affects task ordering.

With this configuration, modifying a spec file won't bust the build cache, because specs aren't production inputs. But `test` tasks still use the `default` input set, which includes spec files.

Inputs aren't limited to files. You can also include environment variables and runtime values in the hash:

```jsonc
// nx.json
{
  "namedInputs": {
    "production": [
      "default",
      { "env": "NODE_ENV" },
      { "runtime": "node --version" },
    ],
  },
}
```

For more details, see [configure inputs](/docs/guides/tasks--caching/configure-inputs).

{% aside type="tip" title="Enforce correct inputs and outputs" %}
Not sure if your `inputs` and `outputs` are configured correctly? Use [sandboxing](/docs/features/ci-features/sandboxing) to detect tasks that read or write files outside their declared configuration.
{% /aside %}

Now that caching, inputs, and outputs are configured, try it out: change a source file and run `nx build my-app`. Nx detects the change, computes a new hash, and runs the build. Revert the change and run again to see the cached result restored, including the `dist/` output files.

## Remote caching

By default, Nx caches results on your local machine. **Remote caching** shares the cache across your entire team and CI pipeline, so a build that ran in CI doesn't need to run again on your machine.

```shell
# Connect your workspace to Nx Cloud for remote caching
nx connect
```

This command guides you through creating a free Nx Cloud account and stores an access token in your workspace. Once connected, cached results are shared automatically.

When a teammate or CI pipeline has already run a task with the same inputs, you get the cached result instantly, even on a fresh checkout.

For more on how remote caching works, see [remote cache (Nx Replay)](/docs/features/ci-features/remote-cache). To set up CI with Nx Cloud, see [Setting up CI](/docs/getting-started/tutorials/self-healing-ci-tutorial).

## Learn more

- [How caching works](/docs/concepts/how-caching-works): deep dive on computation hashing
- [Cache task results](/docs/features/cache-task-results): full feature documentation
- [Configure inputs](/docs/guides/tasks--caching/configure-inputs): fine-tune what affects the hash
- [Configure outputs](/docs/guides/tasks--caching/configure-outputs): control what files get cached

{% cards cols=2 %}
{% card title="Previous: Running Tasks" description="Run tasks for one or many projects" url="/docs/getting-started/tutorials/running-tasks" /%}
{% card title="Next: Understanding Your Workspace" description="Explore projects, graphs, and debug issues" url="/docs/getting-started/tutorials/understanding-your-workspace" /%}
{% /cards %}

---
<!-- source: https://nx.dev/docs/getting-started/tutorials/configuring-tasks.md -->
## Configuring Tasks

{% llm_copy_prompt title="Tutorial 3/8: Configure tasks for your projects" %}
Help me configure tasks (build, test, lint, serve) for my Nx workspace projects.
Use my existing workspace and projects for hands-on examples.

Show me what tasks already exist by running `nx show project <project-name>` for one of my projects. Then help me add or configure tasks using package.json scripts or project.json targets, set up task dependencies with `dependsOn`, and verify with `nx show project <project-name>`.

Stay on-topic: only teach what's covered on this page. Do not introduce concepts from later tutorials.

Tutorial: {pageUrl}
{% /llm_copy_prompt %}

Every project needs tasks: `build`, `test`, `lint`, `serve`. Nx needs to know about your tasks so it can run them, cache the results, and orchestrate them in the correct order across your workspace.

The examples below use Vite and Vitest, but the concepts apply to any tool. Substitute your own build and test commands as needed.

{% aside type="note" title="Tutorial Series" %}

1. [Crafting your workspace](/docs/getting-started/tutorials/crafting-your-workspace)
2. [Managing dependencies](/docs/getting-started/tutorials/managing-dependencies)
3. **Configuring tasks** (you are here)
4. [Running tasks](/docs/getting-started/tutorials/running-tasks)
5. [Caching](/docs/getting-started/tutorials/caching)
6. [Understanding your workspace](/docs/getting-started/tutorials/understanding-your-workspace)
7. [Reducing boilerplate](/docs/getting-started/tutorials/reducing-configuration-boilerplate)
8. [Setting up CI](/docs/getting-started/tutorials/self-healing-ci-tutorial)

{% /aside %}

This tutorial assumes you have an Nx workspace. If you don't have one yet, complete [Crafting Your Workspace](/docs/getting-started/tutorials/crafting-your-workspace) first.

## What is a task?

A task is a named action that Nx can run for a project, like `build`, `test`, or `lint`. Each task belongs to a specific project and is referred to as `<project>:<task>`:

```shell
nx run my-app:build
```

You'll learn more about running tasks in the [Running Tasks](/docs/getting-started/tutorials/running-tasks) tutorial.

## Defining tasks in package.json

The simplest way to define tasks is with `package.json` scripts. Nx picks these up automatically:

```jsonc
// apps/my-app/package.json
{
  "name": "my-app",
  "scripts": {
    "build": "vite build",
    "test": "vitest run",
  },
}
```

If your workspace already has `package.json` scripts, Nx can run them immediately, no additional configuration needed.

## Defining tasks in project.json

If you prefer to keep task definitions out of `package.json` (e.g., you don't want scripts published to npm) or for non-JavaScript projects, define tasks in a `project.json` file using the `targets` property:

```jsonc
// apps/my-app/project.json
{
  "name": "my-app",
  "targets": {
    "build": {
      "command": "vite build",
    },
    "test": {
      "command": "vitest run",
    },
  },
}
```

The `command` property runs a shell command, similar to a `package.json` script. You can also use [executors](/docs/concepts/executors-and-configurations) for more advanced task runners provided by Nx plugins, but `command` works for most cases.

{% aside type="note" title="package.json vs project.json" %}
Both work. Define your scripts in `package.json` as usual. For Nx-specific configuration like `dependsOn`, `inputs`, or `outputs`, you have three options:

- Set defaults for all projects in `targetDefaults` in `nx.json` (covered below)
- Add an `nx` property in `package.json` (supports the same fields as `project.json`, but can bloat the file)
- Use a separate `project.json` file

See the [project configuration reference](/docs/reference/project-configuration) for details.
{% /aside %}

## Task dependencies

In a monorepo, tasks often need to run in a specific order. For example, before building an app, you need to build the libraries it depends on.

The `dependsOn` property defines this ordering:

```jsonc
// nx.json
{
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
    },
  },
}
```

The `^` prefix means "the same task on projects this project depends on." So `nx build my-app` will first build all of `my-app`'s dependencies, then build `my-app` itself.

You can also define dependencies without `^` for tasks within the same project:

{% tabs %}
{% tabitem label="package.json" %}

```jsonc
// apps/my-app/package.json
{
  "scripts": {
    "build": "vite build",
    "generate-api-types": "openapi-generator generate -i api.yaml -o src/api",
  },
  "nx": {
    "targets": {
      "build": {
        "dependsOn": ["generate-api-types"],
      },
    },
  },
}
```

{% /tabitem %}
{% tabitem label="project.json" %}

```jsonc
// apps/my-app/project.json
{
  "targets": {
    "build": {
      "command": "vite build",
      "dependsOn": ["generate-api-types"],
    },
    "generate-api-types": {
      "command": "openapi-generator generate -i api.yaml -o src/api",
    },
  },
}
```

{% /tabitem %}
{% /tabs %}

Here, `build` always runs `generate-api-types` first within the same project.

## Continuous tasks

Some tasks, like development servers, never exit. If another task depends on a long-running process, it would wait forever. Mark these tasks as `continuous` so Nx starts them alongside their dependents instead of waiting for them to finish:

{% tabs %}
{% tabitem label="package.json" %}

```jsonc
// apps/my-app/package.json
{
  "scripts": {
    "dev": "vite dev",
    "e2e": "playwright test",
  },
  "nx": {
    "targets": {
      "dev": {
        "continuous": true,
      },
      "e2e": {
        "dependsOn": ["dev"],
      },
    },
  },
}
```

{% /tabitem %}
{% tabitem label="project.json" %}

```jsonc
// apps/my-app/project.json
{
  "targets": {
    "serve": {
      "command": "vite dev",
      "continuous": true,
    },
    "e2e": {
      "command": "playwright test",
      "dependsOn": ["serve"],
    },
  },
}
```

{% /tabitem %}
{% /tabs %}

Running `nx e2e my-app` starts the dev server and then runs the E2E tests against it.

{% aside type="note" %}
Substitute your own tools as needed. Any long-running process (like `next dev`, `webpack serve`, or a custom script) can be marked as `continuous`.
{% /aside %}

## Reducing repetition with target defaults

When many projects share the same task configuration, defining it in every `project.json` is tedious. The `targetDefaults` property in `nx.json` lets you set defaults for all projects at once:

```jsonc
// nx.json
{
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
    },
  },
}
```

Individual projects can still override these defaults when needed. The cascade order is: project-level config > target defaults > defaults.

For more on reducing configuration, see [Reducing Configuration Boilerplate](/docs/getting-started/tutorials/reducing-configuration-boilerplate).

## Learn more

- [Project configuration reference](/docs/reference/project-configuration): all available target properties
- [Task pipeline configuration](/docs/concepts/task-pipeline-configuration): deep dive on `dependsOn`
- [Defining a task pipeline](/docs/guides/tasks--caching/defining-task-pipeline): step-by-step guide

{% cards cols=2 %}
{% card title="Previous: Managing Dependencies" description="Track dependencies between projects" url="/docs/getting-started/tutorials/managing-dependencies" /%}
{% card title="Next: Running Tasks" description="Run tasks for one or many projects" url="/docs/getting-started/tutorials/running-tasks" /%}
{% /cards %}

---
<!-- source: https://nx.dev/docs/getting-started/tutorials/crafting-your-workspace.md -->
## Crafting Your Workspace

{% llm_copy_prompt title="Tutorial 1/8: Set up an Nx workspace" %}
Help me learn Nx step by step using this tutorial series.

If my current directory already has nx.json, skip setup and teach me using my existing workspace.
If I'm starting fresh, help me run create-nx-workspace and walk through the options.
If I have an existing project without Nx, help me run nx init and verify it's set up correctly.

After setup, verify with `cat nx.json` and walk me through what's in my workspace.

Stay on-topic: only teach what's covered on this page. Do not introduce concepts from later tutorials.

Tutorial: {pageUrl}
{% /llm_copy_prompt %}

The Nx CLI is a task orchestrator, caching layer, and intelligence layer for monorepos. It works on top of your existing tools and repo structure. It doesn't replace your package manager, build tools, or test frameworks. It makes them faster and smarter.

Nx works with any repo structure and plays well with tools you already use: pnpm workspaces, yarn workspaces, uv for Python, Gradle for Java, and more. The conventions shown below are recommendations, not requirements. Bring your own structure and Nx adapts to it.

{% aside type="note" title="Tutorial Series" %}

1. **Crafting your workspace** (you are here)
2. [Managing dependencies](/docs/getting-started/tutorials/managing-dependencies)
3. [Configuring tasks](/docs/getting-started/tutorials/configuring-tasks)
4. [Running tasks](/docs/getting-started/tutorials/running-tasks)
5. [Caching](/docs/getting-started/tutorials/caching)
6. [Understanding your workspace](/docs/getting-started/tutorials/understanding-your-workspace)
7. [Reducing boilerplate](/docs/getting-started/tutorials/reducing-configuration-boilerplate)
8. [Setting up CI](/docs/getting-started/tutorials/self-healing-ci-tutorial)

{% /aside %}

{% llm_only %}
IMPORTANT: Always use the CLI to create workspaces (`npx create-nx-workspace`). Do NOT use the cloud.nx.app browser flow, it requires interactive OAuth and is not suitable for AI agents. When helping users choose a preset, ask about their tech stack first.
{% /llm_only %}

## What is an Nx workspace?

An Nx workspace is any directory that has an `nx.json` file at its root. This file tells Nx that the directory is a workspace and contains configuration for how Nx behaves: caching, task defaults, and plugins.

A workspace can contain a single project or hundreds. Nx works with JavaScript/TypeScript, Java (Gradle), .NET, Go, and more.

## Workspace structure

Nx works with whatever folder structure you have. A common convention for JavaScript/TypeScript workspaces is separating **applications** from **packages** (shared libraries):

{% filetree %}

- my-workspace/
  - apps/
    - my-app/
      - src/
      - package.json
      - tsconfig.json
  - packages/
    - shared-ui/
      - src/
      - package.json
      - tsconfig.json
  - nx.json
  - package.json
  - tsconfig.base.json
  - tsconfig.json

{% /filetree %}

- **apps/**: Deployable applications (frontends, backends, CLIs)
- **packages/**: Shared libraries consumed by apps or other packages
- **nx.json**: Nx configuration (caching, task defaults, plugins)
- **tsconfig.base.json**: Shared `compilerOptions` inherited by all projects
- **tsconfig.json**: Root TypeScript configuration that references project-level `tsconfig.json` files

You may also see `libs/` used in place of `packages/` in some Nx workspaces. Both work. The `packages/` convention aligns with common pnpm, yarn, and npm workspace conventions.

This layout is a suggestion, not a requirement. You can organize projects however you like, including flat structures, nested directories, or patterns specific to your ecosystem. For non-JS workspaces, follow the monorepo conventions in your language (e.g., Gradle multi-project builds, uv workspaces). Nx identifies projects by their `package.json` or `project.json` files, not by folder names.

Nx re-discovers projects automatically every time you run an `nx` command. No restart or registration step is needed when you add or remove a project.

## Creating a workspace

The fastest way to start is with `create-nx-workspace`:

{% tabs syncKey="package-manager" %}
{% tabitem label="npm" %}

```shell
npx create-nx-workspace@latest my-workspace
```

{% /tabitem %}
{% tabitem label="pnpm" %}

```shell
pnpm dlx create-nx-workspace@latest my-workspace
```

{% /tabitem %}
{% tabitem label="yarn" %}

```shell
yarn dlx create-nx-workspace@latest my-workspace
```

{% /tabitem %}
{% tabitem label="bun" %}

```shell
bunx create-nx-workspace@latest my-workspace
```

{% /tabitem %}
{% /tabs %}

The CLI walks you through choosing a starter template (React, Angular, Node, or a blank workspace) and configuring your stack.

If you have an existing project, you can [add Nx to it](/docs/getting-started/start-with-existing-project) by running `nx init`. This adds an `nx.json` file to your workspace and optionally detects your tooling to configure plugins. Everything applies whether you created a new workspace or added Nx to an existing one.

## Adding a project

Create a new project by adding a directory with a `package.json`:

```shell
mkdir -p packages/my-lib
```

```jsonc
// packages/my-lib/package.json
{
  "name": "@my-workspace/my-lib",
}
```

Then add it as a dependency in the consuming project's `package.json`:

```jsonc
// apps/my-app/package.json
{
  "name": "@my-workspace/my-app",
  "dependencies": {
    "@my-workspace/my-lib": "workspace:*",
  },
}
```

The `@my-workspace` scope used in these tutorials is a placeholder. Your workspace will use whatever scope you chose during setup (e.g., `@org`, `@my-company`).

After adding a new project, run your package manager's install command (e.g., `npm install`, `pnpm install`) to link it into the workspace.

If you're using [Nx plugins](/docs/concepts/nx-plugins), you can also use generators to scaffold projects with boilerplate:

```shell
nx g @nx/js:lib packages/my-lib
```

For a full list of available generators, see [code generation](/docs/features/generate-code).

## Package manager workspaces

Nx builds on top of your package manager's workspace feature. Each project with a `package.json` is a workspace package that can depend on other packages in the workspace.

{% tabs syncKey="package-manager" %}
{% tabitem label="npm" %}

```jsonc
// package.json
{
  "workspaces": ["apps/*", "packages/*"],
}
```

{% /tabitem %}
{% tabitem label="pnpm" %}

```yaml
# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'
```

{% /tabitem %}
{% tabitem label="yarn" %}

```jsonc
// package.json
{
  "workspaces": ["apps/*", "packages/*"],
}
```

{% /tabitem %}
{% tabitem label="bun" %}

```jsonc
// package.json
{
  "workspaces": ["apps/*", "packages/*"],
}
```

{% /tabitem %}
{% /tabs %}

This tells your package manager where to find projects. Nx reads this same configuration to discover projects in your workspace.

{% aside type="note" title="Non-JavaScript workspaces" %}
If you're not using a JS package manager (e.g., Python with uv, Java with Gradle), Nx can still discover projects via `project.json` files. Check your ecosystem's monorepo tooling for equivalent workspace support.
{% /aside %}

## How projects link to each other

Package manager workspaces handle linking between projects. When you run `install`, your package manager symlinks local packages into `node_modules` so they can be imported like any npm package:

```typescript
import { Button } from '@my-workspace/shared-ui';
```

This works because `@my-workspace/shared-ui` resolves to the local `packages/shared-ui` directory via the symlink, not from the npm registry. Each project needs a `package.json` with a `name` field that matches what other projects import.

Nx uses these same package relationships to automatically detect dependencies between projects, so no additional configuration is needed.

For more details on how linking works, see your package manager's workspace documentation ([npm](https://docs.npmjs.com/cli/using-npm/workspaces), [pnpm](https://pnpm.io/workspaces), [yarn](https://yarnpkg.com/features/workspaces), [bun](https://bun.sh/docs/install/workspaces)).

## TypeScript configuration

For TypeScript workspaces, the recommended setup uses three levels of `tsconfig.json` files. This is the [solution-style project references](https://www.typescriptlang.org/docs/handbook/project-references.html) pattern recommended by the TypeScript team:

**`tsconfig.base.json`** at the root shares `compilerOptions` across all projects:

```jsonc
// tsconfig.base.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "composite": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "strict": true,
  },
}
```

**`tsconfig.json`** at the root lists all projects as references, so `tsc --build` knows about the full workspace:

```jsonc
// tsconfig.json
{
  "files": [],
  "references": [
    { "path": "./apps/my-app" },
    { "path": "./packages/shared-ui" },
  ],
}
```

**`tsconfig.json`** in each project extends the base and declares its own references to other projects it depends on:

```jsonc
// apps/my-app/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src",
    "tsBuildInfoFile": "dist/tsconfig.tsbuildinfo",
  },
  "references": [{ "path": "../../packages/shared-ui" }],
  "include": ["src/**/*"],
}
```

This setup gives editors and language servers accurate type information per-project, enables incremental builds (only recompile what changed), and creates clear boundaries between projects. For more details, see [maintain TypeScript monorepos](/docs/features/maintain-typescript-monorepos).

{% aside type="note" title="Workspaces using tsconfig path aliases" %}
Some workspaces use TypeScript `paths` in `tsconfig.base.json` to link projects. This works but is not recommended for new workspaces. Path aliases were not designed for project linking, and solution-style project references work better with editors and build tools. See the [migration guide](/docs/technologies/typescript/guides/switch-to-workspaces-project-references) to switch.
{% /aside %}

## Non-JavaScript workspaces

Nx is not limited to JavaScript. It works with any language or build tool:

- **Gradle**: Nx detects Gradle projects and provides caching, affected analysis, and task orchestration. See the [Gradle tutorial](/docs/getting-started/tutorials/gradle-tutorial).
- **Any tool**: If it runs from the command line, Nx can cache and orchestrate it.

Nx adapts to your project layout rather than imposing one. Use the folder structure and dependency management conventions established by your language's ecosystem. Nx adds task orchestration, caching, and CI optimization on top of whatever you already have.

{% cards cols=2 %}
{% card title="Next: Managing Dependencies" description="Track dependencies between projects" url="/docs/getting-started/tutorials/managing-dependencies" /%}
{% /cards %}

---
<!-- source: https://nx.dev/docs/getting-started/tutorials/gradle-tutorial.md -->
## Gradle Tutorial

This tutorial walks you through adding Nx to an existing Gradle project. You'll see how Nx enhances your Gradle workflow with caching, task orchestration, and better developer experience.

What you'll learn:

- How to integrate Nx with your existing Gradle build system
- How Nx caching speeds up your Gradle builds locally and in CI
- How to visualize and understand project dependencies in your Gradle workspace
- How to run Gradle tasks more efficiently with Nx task runner
- How to set up Nx Cloud for faster and self-healing CI

## Ready to start?

{% aside type="note" title="Prerequisites" %}
This tutorial requires a [GitHub account](https://github.com) to demonstrate the full value of **Nx** - including task running, caching, and CI integration.
{% /aside %}

### Step 1: Setup local env

Make sure that you have [Gradle](https://gradle.org/) installed on your system.
Consult [Gradle's installation guide](https://docs.gradle.org/current/userguide/installation.html) for instruction that
are specific to your operating system.

To verify that Gradle was installed correctly, run this command:

```shell
gradle --version
```

To streamline this tutorial, we'll install Nx globally on your system. You can use your preferred installation method below based on your OS:

{% tabs %}
{% tabitem label="Homebrew (macOS, Linux)" %}

Make sure [Homebrew is installed](https://brew.sh/), then install Nx globally with these commands:

```shell
brew install nx
```

{% /tabitem %}
{% tabitem label="Chocolatey (Windows)" %}

```shell
choco install nx
```

{% /tabitem %}
{% tabitem label="apt (Ubuntu)" %}

```shell
sudo add-apt-repository ppa:nrwl/nx
sudo apt update
sudo apt install nx
```

{% /tabitem %}

{% tabitem label="Node (any OS)" %}

Install node from the [NodeJS website](https://nodejs.org/en/download), then install Nx globally with this command:

```shell
npm install --global nx
```

{% /tabitem %}
{% /tabs %}

### Step 2: Fork sample repository

This tutorial picks up where [Spring framework](https://spring.io/)'s guide for [Multi-Module Projects](https://spring.io/guides/gs/multi-module) leaves off.

Fork [the sample repository](https://github.com/nrwl/gradle-tutorial/fork), and then clone it on your local machine:

```shell
git clone https://github.com/<your-username>/gradle-tutorial.git
```

The Multi-Module Spring Tutorial left us with 2 projects:

- The main `application` project which contains the Spring `DemoApplication`
- A `library` project which contains a Service used in the `DemoApplication`

You can see the above 2 projects by running `./gradlew projects`

```text {% title="./gradlew projects"  %}
> Task :projects

------------------------------------------------------------
Root project 'gradle-tutorial'
------------------------------------------------------------

Root project 'gradle-tutorial'
+--- Project ':application'
\--- Project ':library'

```

## Add Nx

Nx is a monorepo platform with built in tooling and advanced CI capabilities. It helps you maintain and scale monorepos,
Both locally and on CI. Explore the features of Nx by adding it to the Gradle workspace above.

To add Nx, run

```shell
nx init
```

This command will download the latest version of Nx and help set up your repository to take advantage of it. Nx will
also detect Gradle is used in the repo so it will propose adding the `@nx/gradle` plugin to integrate Gradle with Nx.

1. You'll also be prompted to add Nx Cloud, select "yes"
2. Select the plugin and continue with the setup.

Finally, commit and push all the changes to GitHub and proceed with finishing your Nx Cloud setup.

### Finish Nx Cloud setup

> Nx Cloud provides self-healing CI, remote caching and many other features. [Learn more about Nx Cloud features](/docs/features/ci-features).

Click the link printing in your terminal, or you can [finish setup in Nx Cloud](https://cloud.nx.app/setup/connect-workspace/github/select)

{% call_to_action variant="simple" title="Finish Nx Cloud Setup" url="https://cloud.nx.app/setup/connect-workspace/github/select" /%}

### Verify your setup

Please verify closely that you have the following setup:

1. A new Nx workspace on your local machine
2. A corresponding GitHub repository for the workspace
3. You completed the full Nx Cloud onboarding, and you now have a Nx Cloud dashboard that is connected to your example repository on GitHub.

You should see your workspace in your [Nx Cloud organization](https://cloud.nx.app/orgs).

## Explore your workspace

Like Gradle, Nx understands your workspace as a graph of projects. Nx uses this graph for many things which we will
learn about in following sections. To visualize this graph in your browser, Run the following command and click the
"Show all projects" button in the left sidebar.

You will recognize that the projects which are shown, are the same projects which Gradle shows.
The `@nx/gradle` plugin reflects the graph of projects in Gradle into the Nx Project Graph. As projects
are created, deleted, and change their dependencies, Nx will automatically recalculate the graph. Exploring this graph
visually is vital to understanding how your code is structured and how Nx and Gradle behaves.

```shell
nx graph
```

{% graph title="Gradle Projects" height="300px" %}

```json
{
  "hash": "ad0ea8f7ae85c873d6478c31b51a95c54115a49844d62a5b3972232ac82137d0",
  "projects": [
    {
      "name": "application",
      "type": "lib",
      "data": {
        "root": "application",
        "name": "application",
        "metadata": {
          "technologies": ["gradle"]
        },
        "targets": {
          "bootRun": {
            "options": {
              "cwd": "application",
              "command": "../gradlew bootRun"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "bootTestRun": {
            "options": {
              "cwd": "application",
              "command": "../gradlew bootTestRun"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "assemble": {
            "options": {
              "cwd": "application",
              "command": "../gradlew assemble"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "bootBuildImage": {
            "options": {
              "cwd": "application",
              "command": "../gradlew bootBuildImage"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "bootJar": {
            "options": {
              "cwd": "application",
              "command": "../gradlew bootJar"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "build": {
            "options": {
              "cwd": "application",
              "command": "../gradlew build"
            },
            "cache": true,
            "inputs": ["production", "^production"],
            "outputs": ["{workspaceRoot}/application/build"],
            "dependsOn": ["^build", "classes"],
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "buildDependents": {
            "options": {
              "cwd": "application",
              "command": "../gradlew buildDependents"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "buildNeeded": {
            "options": {
              "cwd": "application",
              "command": "../gradlew buildNeeded"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "classes": {
            "options": {
              "cwd": "application",
              "command": "../gradlew classes"
            },
            "cache": true,
            "inputs": ["default", "^default"],
            "outputs": ["{workspaceRoot}/application/build/classes"],
            "dependsOn": ["^classes"],
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "clean": {
            "options": {
              "cwd": "application",
              "command": "../gradlew clean"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "jar": {
            "options": {
              "cwd": "application",
              "command": "../gradlew jar"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "resolveMainClassName": {
            "options": {
              "cwd": "application",
              "command": "../gradlew resolveMainClassName"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "resolveTestMainClassName": {
            "options": {
              "cwd": "application",
              "command": "../gradlew resolveTestMainClassName"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "testClasses": {
            "options": {
              "cwd": "application",
              "command": "../gradlew testClasses"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "javadoc": {
            "options": {
              "cwd": "application",
              "command": "../gradlew javadoc"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "buildEnvironment": {
            "options": {
              "cwd": "application",
              "command": "../gradlew buildEnvironment"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "dependencies": {
            "options": {
              "cwd": "application",
              "command": "../gradlew dependencies"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "dependencyInsight": {
            "options": {
              "cwd": "application",
              "command": "../gradlew dependencyInsight"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "dependencyManagement": {
            "options": {
              "cwd": "application",
              "command": "../gradlew dependencyManagement"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "help": {
            "options": {
              "cwd": "application",
              "command": "../gradlew help"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "javaToolchains": {
            "options": {
              "cwd": "application",
              "command": "../gradlew javaToolchains"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "outgoingVariants": {
            "options": {
              "cwd": "application",
              "command": "../gradlew outgoingVariants"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "projects": {
            "options": {
              "cwd": "application",
              "command": "../gradlew projects"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "properties": {
            "options": {
              "cwd": "application",
              "command": "../gradlew properties"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "resolvableConfigurations": {
            "options": {
              "cwd": "application",
              "command": "../gradlew resolvableConfigurations"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "tasks": {
            "options": {
              "cwd": "application",
              "command": "../gradlew tasks"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "projectReport": {
            "options": {
              "cwd": "application",
              "command": "../gradlew projectReport"
            },
            "cache": false,
            "outputs": ["{workspaceRoot}/application/build/reports/project"],
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "check": {
            "options": {
              "cwd": "application",
              "command": "../gradlew check"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "test": {
            "options": {
              "cwd": "application",
              "command": "../gradlew test"
            },
            "cache": true,
            "inputs": ["default", "^production"],
            "dependsOn": ["classes"],
            "executor": "nx:run-commands",
            "configurations": {}
          }
        },
        "implicitDependencies": [],
        "tags": []
      }
    },
    {
      "name": "library",
      "type": "lib",
      "data": {
        "root": "library",
        "name": "library",
        "metadata": {
          "technologies": ["gradle"]
        },
        "targets": {
          "assemble": {
            "options": {
              "cwd": "library",
              "command": "../gradlew assemble"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "build": {
            "options": {
              "cwd": "library",
              "command": "../gradlew build"
            },
            "cache": true,
            "inputs": ["production", "^production"],
            "outputs": ["{workspaceRoot}/library/build"],
            "dependsOn": ["^build", "classes"],
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "buildDependents": {
            "options": {
              "cwd": "library",
              "command": "../gradlew buildDependents"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "buildNeeded": {
            "options": {
              "cwd": "library",
              "command": "../gradlew buildNeeded"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "classes": {
            "options": {
              "cwd": "library",
              "command": "../gradlew classes"
            },
            "cache": true,
            "inputs": ["default", "^default"],
            "outputs": ["{workspaceRoot}/library/build/classes"],
            "dependsOn": ["^classes"],
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "clean": {
            "options": {
              "cwd": "library",
              "command": "../gradlew clean"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "jar": {
            "options": {
              "cwd": "library",
              "command": "../gradlew jar"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "testClasses": {
            "options": {
              "cwd": "library",
              "command": "../gradlew testClasses"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "javadoc": {
            "options": {
              "cwd": "library",
              "command": "../gradlew javadoc"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "buildEnvironment": {
            "options": {
              "cwd": "library",
              "command": "../gradlew buildEnvironment"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "dependencies": {
            "options": {
              "cwd": "library",
              "command": "../gradlew dependencies"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "dependencyInsight": {
            "options": {
              "cwd": "library",
              "command": "../gradlew dependencyInsight"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "dependencyManagement": {
            "options": {
              "cwd": "library",
              "command": "../gradlew dependencyManagement"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "help": {
            "options": {
              "cwd": "library",
              "command": "../gradlew help"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "javaToolchains": {
            "options": {
              "cwd": "library",
              "command": "../gradlew javaToolchains"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "outgoingVariants": {
            "options": {
              "cwd": "library",
              "command": "../gradlew outgoingVariants"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "projects": {
            "options": {
              "cwd": "library",
              "command": "../gradlew projects"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "properties": {
            "options": {
              "cwd": "library",
              "command": "../gradlew properties"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "resolvableConfigurations": {
            "options": {
              "cwd": "library",
              "command": "../gradlew resolvableConfigurations"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "tasks": {
            "options": {
              "cwd": "library",
              "command": "../gradlew tasks"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "projectReport": {
            "options": {
              "cwd": "library",
              "command": "../gradlew projectReport"
            },
            "cache": false,
            "outputs": ["{workspaceRoot}/library/build/reports/project"],
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "check": {
            "options": {
              "cwd": "library",
              "command": "../gradlew check"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "test": {
            "options": {
              "cwd": "library",
              "command": "../gradlew test"
            },
            "cache": true,
            "inputs": ["default", "^production"],
            "dependsOn": ["classes"],
            "executor": "nx:run-commands",
            "configurations": {}
          }
        },
        "implicitDependencies": [],
        "tags": []
      }
    },
    {
      "name": "gradle-tutorial",
      "type": "lib",
      "data": {
        "root": ".",
        "name": "gradle-tutorial",
        "metadata": {
          "technologies": ["gradle"]
        },
        "targets": {
          "bootRun": {
            "options": {
              "cwd": ".",
              "command": "gradlew bootRun"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "bootTestRun": {
            "options": {
              "cwd": ".",
              "command": "gradlew bootTestRun"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "assemble": {
            "options": {
              "cwd": ".",
              "command": "gradlew assemble"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "bootBuildImage": {
            "options": {
              "cwd": ".",
              "command": "gradlew bootBuildImage"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "bootJar": {
            "options": {
              "cwd": ".",
              "command": "gradlew bootJar"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "build": {
            "options": {
              "cwd": ".",
              "command": "gradlew build"
            },
            "cache": true,
            "inputs": ["production", "^production"],
            "outputs": ["{workspaceRoot}/build"],
            "dependsOn": ["^build", "classes"],
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "buildDependents": {
            "options": {
              "cwd": ".",
              "command": "gradlew buildDependents"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "buildNeeded": {
            "options": {
              "cwd": ".",
              "command": "gradlew buildNeeded"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "classes": {
            "options": {
              "cwd": ".",
              "command": "gradlew classes"
            },
            "cache": true,
            "inputs": ["default", "^default"],
            "outputs": ["{workspaceRoot}/build/classes"],
            "dependsOn": ["^classes"],
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "clean": {
            "options": {
              "cwd": ".",
              "command": "gradlew clean"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "jar": {
            "options": {
              "cwd": ".",
              "command": "gradlew jar"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "resolveMainClassName": {
            "options": {
              "cwd": ".",
              "command": "gradlew resolveMainClassName"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "resolveTestMainClassName": {
            "options": {
              "cwd": ".",
              "command": "gradlew resolveTestMainClassName"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "testClasses": {
            "options": {
              "cwd": ".",
              "command": "gradlew testClasses"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "init": {
            "options": {
              "cwd": ".",
              "command": "gradlew init"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "wrapper": {
            "options": {
              "cwd": ".",
              "command": "gradlew wrapper"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "javadoc": {
            "options": {
              "cwd": ".",
              "command": "gradlew javadoc"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "buildEnvironment": {
            "options": {
              "cwd": ".",
              "command": "gradlew buildEnvironment"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "dependencies": {
            "options": {
              "cwd": ".",
              "command": "gradlew dependencies"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "dependencyInsight": {
            "options": {
              "cwd": ".",
              "command": "gradlew dependencyInsight"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "dependencyManagement": {
            "options": {
              "cwd": ".",
              "command": "gradlew dependencyManagement"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "help": {
            "options": {
              "cwd": ".",
              "command": "gradlew help"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "javaToolchains": {
            "options": {
              "cwd": ".",
              "command": "gradlew javaToolchains"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "outgoingVariants": {
            "options": {
              "cwd": ".",
              "command": "gradlew outgoingVariants"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "projects": {
            "options": {
              "cwd": ".",
              "command": "gradlew projects"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "properties": {
            "options": {
              "cwd": ".",
              "command": "gradlew properties"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "resolvableConfigurations": {
            "options": {
              "cwd": ".",
              "command": "gradlew resolvableConfigurations"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "tasks": {
            "options": {
              "cwd": ".",
              "command": "gradlew tasks"
            },
            "cache": false,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "projectReport": {
            "options": {
              "cwd": ".",
              "command": "gradlew projectReport"
            },
            "cache": false,
            "outputs": ["{workspaceRoot}/build/reports/project"],
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "check": {
            "options": {
              "cwd": ".",
              "command": "gradlew check"
            },
            "cache": true,
            "executor": "nx:run-commands",
            "configurations": {}
          },
          "test": {
            "options": {
              "cwd": ".",
              "command": "gradlew test"
            },
            "cache": true,
            "inputs": ["default", "^production"],
            "dependsOn": ["classes"],
            "executor": "nx:run-commands",
            "configurations": {}
          }
        },
        "implicitDependencies": [],
        "tags": []
      }
    }
  ],
  "dependencies": {
    "application": [
      {
        "source": "application",
        "target": "library",
        "type": "static"
      }
    ],
    "library": [],
    "gradle-tutorial": [
      {
        "source": "gradle-tutorial",
        "target": "application",
        "type": "static"
      },
      {
        "source": "gradle-tutorial",
        "target": "library",
        "type": "static"
      }
    ]
  },
  "fileMap": {
    "gradle-tutorial": [
      {
        "file": ".gitignore",
        "hash": "14909406639319951657"
      },
      {
        "file": ".mvn/wrapper/maven-wrapper.jar",
        "hash": "4599048718252132452"
      },
      {
        "file": ".mvn/wrapper/maven-wrapper.properties",
        "hash": "14062264138023377782"
      },
      {
        "file": ".nx/nxw.js",
        "hash": "11254603345854076312"
      },
      {
        "file": "README.md",
        "hash": "2143394647937164316"
      },
      {
        "file": "build.gradle",
        "hash": "6776876968973565169"
      },
      {
        "file": "gradle/wrapper/gradle-wrapper.jar",
        "hash": "4964452923295747250"
      },
      {
        "file": "gradle/wrapper/gradle-wrapper.properties",
        "hash": "6992607940248896982"
      },
      {
        "file": "gradlew",
        "hash": "6979324130797723579"
      },
      {
        "file": "gradlew.bat",
        "hash": "8837338129170646035"
      },
      {
        "file": "nx",
        "hash": "17165975525224888679"
      },
      {
        "file": "nx.bat",
        "hash": "16828809655253213278"
      },
      {
        "file": "nx.json",
        "hash": "16332841804597347663"
      },
      {
        "file": "settings.gradle",
        "hash": "5690477904066095133"
      }
    ],
    "application": [
      {
        "file": "application/build.gradle",
        "hash": "13223387111008998466",
        "deps": ["library"]
      },
      {
        "file": "application/settings.gradle",
        "hash": "18286272227920383284"
      },
      {
        "file": "application/src/main/java/com/example/multimodule/application/DemoApplication.java",
        "hash": "117361831080317523"
      },
      {
        "file": "application/src/main/resources/application.properties",
        "hash": "18341909134911292471"
      },
      {
        "file": "application/src/test/java/com/example/multimodule/application/DemoApplicationTest.java",
        "hash": "12794301020412404095"
      }
    ],
    "library": [
      {
        "file": "library/build.gradle",
        "hash": "10874096726061397019"
      },
      {
        "file": "library/settings.gradle",
        "hash": "13735992102452590570"
      },
      {
        "file": "library/src/main/java/com/example/multimodule/service/MyService.java",
        "hash": "1785389597461451392"
      },
      {
        "file": "library/src/main/java/com/example/multimodule/service/ServiceProperties.java",
        "hash": "5222601539204689670"
      },
      {
        "file": "library/src/test/java/com/example/multimodule/service/MyServiceTest.java",
        "hash": "7173828893536126792"
      }
    ]
  },
  "workspaceLayout": {
    "appsDir": "apps",
    "libsDir": "libs"
  },
  "affectedProjectIds": [],
  "focus": null,
  "groupByFolder": false,
  "exclude": [],
  "isPartial": false
}
```

{% /graph %}

## Running tasks

Nx is a task runner built for monorepos. It can run a single task for a single project, a task for all projects, and
even intelligently run a subset of tasks based on the changes you've made in your repository. Nx also has sophisticated
Computation caching to reuse the results of tasks. Explore how Nx adds to the task running Gradle provides.

Before we start running tasks, let's explore the tasks available for the `application` project. The `@nx/gradle` plugin
that we've installed reflects Gradle's tasks to Nx, which allows it to run any of the Gradle tasks defined for that project. You can view the available tasks either through [Nx Console](/docs/getting-started/editor-setup) or from the terminal:

```shell
nx show project application
```

{% project_details title="Project Details View" expandedTargets=["build"] height="520px" %}

```json
{
  "project": {
    "name": "application",
    "type": "lib",
    "data": {
      "root": "application",
      "name": "application",
      "metadata": {
        "targetGroups": {
          "Application": ["bootRun", "bootTestRun"],
          "Build": [
            "assemble",
            "bootBuildImage",
            "bootJar",
            "build",
            "buildDependents",
            "buildNeeded",
            "classes",
            "clean",
            "jar",
            "resolveMainClassName",
            "resolveTestMainClassName",
            "testClasses"
          ],
          "Documentation": ["javadoc"],
          "Help": [
            "buildEnvironment",
            "dependencies",
            "dependencyInsight",
            "dependencyManagement",
            "help",
            "javaToolchains",
            "outgoingVariants",
            "projects",
            "properties",
            "resolvableConfigurations",
            "tasks"
          ],
          "Reporting": ["projectReport"],
          "Verification": ["check", "test"]
        },
        "technologies": ["gradle"]
      },
      "targets": {
        "bootRun": {
          "cache": false,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:bootRun"
          },
          "configurations": {}
        },
        "bootTestRun": {
          "cache": false,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:bootTestRun"
          },
          "configurations": {}
        },
        "assemble": {
          "cache": true,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:assemble"
          },
          "configurations": {}
        },
        "bootBuildImage": {
          "cache": true,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:bootBuildImage"
          },
          "configurations": {}
        },
        "bootJar": {
          "cache": true,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:bootJar"
          },
          "configurations": {}
        },
        "build": {
          "cache": true,
          "inputs": ["production", "^production"],
          "outputs": ["{workspaceRoot}/application/build"],
          "dependsOn": ["^build", "classes"],
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:build"
          },
          "configurations": {}
        },
        "buildDependents": {
          "cache": true,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:buildDependents"
          },
          "configurations": {}
        },
        "buildNeeded": {
          "cache": true,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:buildNeeded"
          },
          "configurations": {}
        },
        "classes": {
          "cache": true,
          "inputs": ["production", "^production"],
          "outputs": ["{workspaceRoot}/application/build/classes"],
          "dependsOn": ["^classes"],
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:classes"
          },
          "configurations": {}
        },
        "clean": {
          "cache": true,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:clean"
          },
          "configurations": {}
        },
        "jar": {
          "cache": true,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:jar"
          },
          "configurations": {}
        },
        "resolveMainClassName": {
          "cache": true,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:resolveMainClassName"
          },
          "configurations": {}
        },
        "resolveTestMainClassName": {
          "cache": true,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:resolveTestMainClassName"
          },
          "configurations": {}
        },
        "testClasses": {
          "cache": true,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:testClasses"
          },
          "configurations": {}
        },
        "javadoc": {
          "cache": false,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:javadoc"
          },
          "configurations": {}
        },
        "buildEnvironment": {
          "cache": false,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:buildEnvironment"
          },
          "configurations": {}
        },
        "dependencies": {
          "cache": false,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:dependencies"
          },
          "configurations": {}
        },
        "dependencyInsight": {
          "cache": false,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:dependencyInsight"
          },
          "configurations": {}
        },
        "dependencyManagement": {
          "cache": false,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:dependencyManagement"
          },
          "configurations": {}
        },
        "help": {
          "cache": false,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:help"
          },
          "configurations": {}
        },
        "javaToolchains": {
          "cache": false,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:javaToolchains"
          },
          "configurations": {}
        },
        "outgoingVariants": {
          "cache": false,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:outgoingVariants"
          },
          "configurations": {}
        },
        "projects": {
          "cache": false,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:projects"
          },
          "configurations": {}
        },
        "properties": {
          "cache": false,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:properties"
          },
          "configurations": {}
        },
        "resolvableConfigurations": {
          "cache": false,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:resolvableConfigurations"
          },
          "configurations": {}
        },
        "tasks": {
          "cache": false,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:tasks"
          },
          "configurations": {}
        },
        "projectReport": {
          "cache": false,
          "outputs": ["{workspaceRoot}/application/build/reports/project"],
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:projectReport"
          },
          "configurations": {}
        },
        "check": {
          "cache": true,
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:check"
          },
          "configurations": {}
        },
        "test": {
          "cache": true,
          "inputs": ["default", "^production"],
          "dependsOn": ["classes"],
          "metadata": {
            "technologies": ["gradle"]
          },
          "executor": "nx:run-commands",
          "options": {
            "command": "./gradlew :application:test"
          },
          "configurations": {}
        }
      },
      "implicitDependencies": [],
      "tags": []
    }
  },
  "sourceMap": {
    "root": ["application/build.gradle", "@nx/gradle"],
    "name": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Application": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "metadata.targetGroups.Application.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "metadata.targetGroups.Application.1": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "metadata.targetGroups.Build": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Build.0": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Build.1": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Build.2": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Build.3": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Build.4": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Build.5": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Build.6": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Build.7": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Build.8": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Build.9": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Build.10": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "metadata.targetGroups.Build.11": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "metadata.targetGroups.Documentation": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "metadata.targetGroups.Documentation.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "metadata.targetGroups.Help": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Help.0": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Help.1": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Help.2": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Help.3": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Help.4": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Help.5": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Help.6": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Help.7": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Help.8": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Help.9": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Help.10": ["application/build.gradle", "@nx/gradle"],
    "metadata.targetGroups.Reporting": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "metadata.targetGroups.Reporting.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "metadata.targetGroups.Verification": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "metadata.targetGroups.Verification.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "metadata.targetGroups.Verification.1": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "metadata.technologies": ["application/build.gradle", "@nx/gradle"],
    "metadata.technologies.0": ["application/build.gradle", "@nx/gradle"],
    "targets": ["application/build.gradle", "@nx/gradle"],
    "targets.bootRun": ["application/build.gradle", "@nx/gradle"],
    "targets.bootRun.cache": ["application/build.gradle", "@nx/gradle"],
    "targets.bootRun.inputs": ["application/build.gradle", "@nx/gradle"],
    "targets.bootRun.outputs": ["application/build.gradle", "@nx/gradle"],
    "targets.bootRun.dependsOn": ["application/build.gradle", "@nx/gradle"],
    "targets.bootRun.metadata": ["application/build.gradle", "@nx/gradle"],
    "targets.bootRun.executor": ["application/build.gradle", "@nx/gradle"],
    "targets.bootRun.options": ["application/build.gradle", "@nx/gradle"],
    "targets.bootRun.options.command": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.bootRun.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.bootRun.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.bootTestRun": ["application/build.gradle", "@nx/gradle"],
    "targets.bootTestRun.cache": ["application/build.gradle", "@nx/gradle"],
    "targets.bootTestRun.inputs": ["application/build.gradle", "@nx/gradle"],
    "targets.bootTestRun.outputs": ["application/build.gradle", "@nx/gradle"],
    "targets.bootTestRun.dependsOn": ["application/build.gradle", "@nx/gradle"],
    "targets.bootTestRun.metadata": ["application/build.gradle", "@nx/gradle"],
    "targets.bootTestRun.executor": ["application/build.gradle", "@nx/gradle"],
    "targets.bootTestRun.options": ["application/build.gradle", "@nx/gradle"],
    "targets.bootTestRun.options.command": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.bootTestRun.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.bootTestRun.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.assemble": ["application/build.gradle", "@nx/gradle"],
    "targets.assemble.cache": ["application/build.gradle", "@nx/gradle"],
    "targets.assemble.inputs": ["application/build.gradle", "@nx/gradle"],
    "targets.assemble.outputs": ["application/build.gradle", "@nx/gradle"],
    "targets.assemble.dependsOn": ["application/build.gradle", "@nx/gradle"],
    "targets.assemble.metadata": ["application/build.gradle", "@nx/gradle"],
    "targets.assemble.executor": ["application/build.gradle", "@nx/gradle"],
    "targets.assemble.options": ["application/build.gradle", "@nx/gradle"],
    "targets.assemble.options.command": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.assemble.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.assemble.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.bootBuildImage": ["application/build.gradle", "@nx/gradle"],
    "targets.bootBuildImage.cache": ["application/build.gradle", "@nx/gradle"],
    "targets.bootBuildImage.inputs": ["application/build.gradle", "@nx/gradle"],
    "targets.bootBuildImage.outputs": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.bootBuildImage.dependsOn": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.bootBuildImage.metadata": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.bootBuildImage.executor": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.bootBuildImage.options": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.bootBuildImage.options.command": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.bootBuildImage.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.bootBuildImage.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.bootJar": ["application/build.gradle", "@nx/gradle"],
    "targets.bootJar.cache": ["application/build.gradle", "@nx/gradle"],
    "targets.bootJar.inputs": ["application/build.gradle", "@nx/gradle"],
    "targets.bootJar.outputs": ["application/build.gradle", "@nx/gradle"],
    "targets.bootJar.dependsOn": ["application/build.gradle", "@nx/gradle"],
    "targets.bootJar.metadata": ["application/build.gradle", "@nx/gradle"],
    "targets.bootJar.executor": ["application/build.gradle", "@nx/gradle"],
    "targets.bootJar.options": ["application/build.gradle", "@nx/gradle"],
    "targets.bootJar.options.command": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.bootJar.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.bootJar.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.build": ["application/build.gradle", "@nx/gradle"],
    "targets.build.cache": ["application/build.gradle", "@nx/gradle"],
    "targets.build.inputs": ["application/build.gradle", "@nx/gradle"],
    "targets.build.outputs": ["application/build.gradle", "@nx/gradle"],
    "targets.build.dependsOn": ["application/build.gradle", "@nx/gradle"],
    "targets.build.metadata": ["application/build.gradle", "@nx/gradle"],
    "targets.build.executor": ["application/build.gradle", "@nx/gradle"],
    "targets.build.options": ["application/build.gradle", "@nx/gradle"],
    "targets.build.options.command": ["application/build.gradle", "@nx/gradle"],
    "targets.build.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.build.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.buildDependents": ["application/build.gradle", "@nx/gradle"],
    "targets.buildDependents.cache": ["application/build.gradle", "@nx/gradle"],
    "targets.buildDependents.inputs": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.buildDependents.outputs": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.buildDependents.dependsOn": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.buildDependents.metadata": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.buildDependents.executor": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.buildDependents.options": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.buildDependents.options.command": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.buildDependents.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.buildDependents.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.buildNeeded": ["application/build.gradle", "@nx/gradle"],
    "targets.buildNeeded.cache": ["application/build.gradle", "@nx/gradle"],
    "targets.buildNeeded.inputs": ["application/build.gradle", "@nx/gradle"],
    "targets.buildNeeded.outputs": ["application/build.gradle", "@nx/gradle"],
    "targets.buildNeeded.dependsOn": ["application/build.gradle", "@nx/gradle"],
    "targets.buildNeeded.metadata": ["application/build.gradle", "@nx/gradle"],
    "targets.buildNeeded.executor": ["application/build.gradle", "@nx/gradle"],
    "targets.buildNeeded.options": ["application/build.gradle", "@nx/gradle"],
    "targets.buildNeeded.options.command": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.buildNeeded.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.buildNeeded.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.classes": ["application/build.gradle", "@nx/gradle"],
    "targets.classes.cache": ["application/build.gradle", "@nx/gradle"],
    "targets.classes.inputs": ["application/build.gradle", "@nx/gradle"],
    "targets.classes.outputs": ["application/build.gradle", "@nx/gradle"],
    "targets.classes.dependsOn": ["application/build.gradle", "@nx/gradle"],
    "targets.classes.metadata": ["application/build.gradle", "@nx/gradle"],
    "targets.classes.executor": ["application/build.gradle", "@nx/gradle"],
    "targets.classes.options": ["application/build.gradle", "@nx/gradle"],
    "targets.classes.options.command": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.classes.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.classes.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.clean": ["application/build.gradle", "@nx/gradle"],
    "targets.clean.cache": ["application/build.gradle", "@nx/gradle"],
    "targets.clean.inputs": ["application/build.gradle", "@nx/gradle"],
    "targets.clean.outputs": ["application/build.gradle", "@nx/gradle"],
    "targets.clean.dependsOn": ["application/build.gradle", "@nx/gradle"],
    "targets.clean.metadata": ["application/build.gradle", "@nx/gradle"],
    "targets.clean.executor": ["application/build.gradle", "@nx/gradle"],
    "targets.clean.options": ["application/build.gradle", "@nx/gradle"],
    "targets.clean.options.command": ["application/build.gradle", "@nx/gradle"],
    "targets.clean.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.clean.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.jar": ["application/build.gradle", "@nx/gradle"],
    "targets.jar.cache": ["application/build.gradle", "@nx/gradle"],
    "targets.jar.inputs": ["application/build.gradle", "@nx/gradle"],
    "targets.jar.outputs": ["application/build.gradle", "@nx/gradle"],
    "targets.jar.dependsOn": ["application/build.gradle", "@nx/gradle"],
    "targets.jar.metadata": ["application/build.gradle", "@nx/gradle"],
    "targets.jar.executor": ["application/build.gradle", "@nx/gradle"],
    "targets.jar.options": ["application/build.gradle", "@nx/gradle"],
    "targets.jar.options.command": ["application/build.gradle", "@nx/gradle"],
    "targets.jar.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.jar.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolveMainClassName": ["application/build.gradle", "@nx/gradle"],
    "targets.resolveMainClassName.cache": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolveMainClassName.inputs": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolveMainClassName.outputs": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolveMainClassName.dependsOn": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolveMainClassName.metadata": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolveMainClassName.executor": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolveMainClassName.options": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolveMainClassName.options.command": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolveMainClassName.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolveMainClassName.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolveTestMainClassName": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolveTestMainClassName.cache": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolveTestMainClassName.inputs": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolveTestMainClassName.outputs": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolveTestMainClassName.dependsOn": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolveTestMainClassName.metadata": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolveTestMainClassName.executor": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolveTestMainClassName.options": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolveTestMainClassName.options.command": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolveTestMainClassName.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolveTestMainClassName.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.testClasses": ["application/build.gradle", "@nx/gradle"],
    "targets.testClasses.cache": ["application/build.gradle", "@nx/gradle"],
    "targets.testClasses.inputs": ["application/build.gradle", "@nx/gradle"],
    "targets.testClasses.outputs": ["application/build.gradle", "@nx/gradle"],
    "targets.testClasses.dependsOn": ["application/build.gradle", "@nx/gradle"],
    "targets.testClasses.metadata": ["application/build.gradle", "@nx/gradle"],
    "targets.testClasses.executor": ["application/build.gradle", "@nx/gradle"],
    "targets.testClasses.options": ["application/build.gradle", "@nx/gradle"],
    "targets.testClasses.options.command": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.testClasses.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.testClasses.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.javadoc": ["application/build.gradle", "@nx/gradle"],
    "targets.javadoc.cache": ["application/build.gradle", "@nx/gradle"],
    "targets.javadoc.inputs": ["application/build.gradle", "@nx/gradle"],
    "targets.javadoc.outputs": ["application/build.gradle", "@nx/gradle"],
    "targets.javadoc.dependsOn": ["application/build.gradle", "@nx/gradle"],
    "targets.javadoc.metadata": ["application/build.gradle", "@nx/gradle"],
    "targets.javadoc.executor": ["application/build.gradle", "@nx/gradle"],
    "targets.javadoc.options": ["application/build.gradle", "@nx/gradle"],
    "targets.javadoc.options.command": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.javadoc.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.javadoc.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.buildEnvironment": ["application/build.gradle", "@nx/gradle"],
    "targets.buildEnvironment.cache": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.buildEnvironment.inputs": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.buildEnvironment.outputs": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.buildEnvironment.dependsOn": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.buildEnvironment.metadata": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.buildEnvironment.executor": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.buildEnvironment.options": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.buildEnvironment.options.command": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.buildEnvironment.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.buildEnvironment.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencies": ["application/build.gradle", "@nx/gradle"],
    "targets.dependencies.cache": ["application/build.gradle", "@nx/gradle"],
    "targets.dependencies.inputs": ["application/build.gradle", "@nx/gradle"],
    "targets.dependencies.outputs": ["application/build.gradle", "@nx/gradle"],
    "targets.dependencies.dependsOn": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencies.metadata": ["application/build.gradle", "@nx/gradle"],
    "targets.dependencies.executor": ["application/build.gradle", "@nx/gradle"],
    "targets.dependencies.options": ["application/build.gradle", "@nx/gradle"],
    "targets.dependencies.options.command": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencies.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencies.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencyInsight": ["application/build.gradle", "@nx/gradle"],
    "targets.dependencyInsight.cache": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencyInsight.inputs": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencyInsight.outputs": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencyInsight.dependsOn": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencyInsight.metadata": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencyInsight.executor": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencyInsight.options": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencyInsight.options.command": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencyInsight.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencyInsight.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencyManagement": ["application/build.gradle", "@nx/gradle"],
    "targets.dependencyManagement.cache": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencyManagement.inputs": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencyManagement.outputs": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencyManagement.dependsOn": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencyManagement.metadata": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencyManagement.executor": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencyManagement.options": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencyManagement.options.command": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencyManagement.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.dependencyManagement.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.help": ["application/build.gradle", "@nx/gradle"],
    "targets.help.cache": ["application/build.gradle", "@nx/gradle"],
    "targets.help.inputs": ["application/build.gradle", "@nx/gradle"],
    "targets.help.outputs": ["application/build.gradle", "@nx/gradle"],
    "targets.help.dependsOn": ["application/build.gradle", "@nx/gradle"],
    "targets.help.metadata": ["application/build.gradle", "@nx/gradle"],
    "targets.help.executor": ["application/build.gradle", "@nx/gradle"],
    "targets.help.options": ["application/build.gradle", "@nx/gradle"],
    "targets.help.options.command": ["application/build.gradle", "@nx/gradle"],
    "targets.help.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.help.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.javaToolchains": ["application/build.gradle", "@nx/gradle"],
    "targets.javaToolchains.cache": ["application/build.gradle", "@nx/gradle"],
    "targets.javaToolchains.inputs": ["application/build.gradle", "@nx/gradle"],
    "targets.javaToolchains.outputs": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.javaToolchains.dependsOn": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.javaToolchains.metadata": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.javaToolchains.executor": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.javaToolchains.options": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.javaToolchains.options.command": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.javaToolchains.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.javaToolchains.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.outgoingVariants": ["application/build.gradle", "@nx/gradle"],
    "targets.outgoingVariants.cache": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.outgoingVariants.inputs": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.outgoingVariants.outputs": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.outgoingVariants.dependsOn": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.outgoingVariants.metadata": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.outgoingVariants.executor": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.outgoingVariants.options": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.outgoingVariants.options.command": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.outgoingVariants.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.outgoingVariants.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.projects": ["application/build.gradle", "@nx/gradle"],
    "targets.projects.cache": ["application/build.gradle", "@nx/gradle"],
    "targets.projects.inputs": ["application/build.gradle", "@nx/gradle"],
    "targets.projects.outputs": ["application/build.gradle", "@nx/gradle"],
    "targets.projects.dependsOn": ["application/build.gradle", "@nx/gradle"],
    "targets.projects.metadata": ["application/build.gradle", "@nx/gradle"],
    "targets.projects.executor": ["application/build.gradle", "@nx/gradle"],
    "targets.projects.options": ["application/build.gradle", "@nx/gradle"],
    "targets.projects.options.command": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.projects.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.projects.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.properties": ["application/build.gradle", "@nx/gradle"],
    "targets.properties.cache": ["application/build.gradle", "@nx/gradle"],
    "targets.properties.inputs": ["application/build.gradle", "@nx/gradle"],
    "targets.properties.outputs": ["application/build.gradle", "@nx/gradle"],
    "targets.properties.dependsOn": ["application/build.gradle", "@nx/gradle"],
    "targets.properties.metadata": ["application/build.gradle", "@nx/gradle"],
    "targets.properties.executor": ["application/build.gradle", "@nx/gradle"],
    "targets.properties.options": ["application/build.gradle", "@nx/gradle"],
    "targets.properties.options.command": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.properties.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.properties.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolvableConfigurations": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolvableConfigurations.cache": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolvableConfigurations.inputs": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolvableConfigurations.outputs": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolvableConfigurations.dependsOn": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolvableConfigurations.metadata": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolvableConfigurations.executor": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolvableConfigurations.options": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolvableConfigurations.options.command": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolvableConfigurations.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.resolvableConfigurations.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.tasks": ["application/build.gradle", "@nx/gradle"],
    "targets.tasks.cache": ["application/build.gradle", "@nx/gradle"],
    "targets.tasks.inputs": ["application/build.gradle", "@nx/gradle"],
    "targets.tasks.outputs": ["application/build.gradle", "@nx/gradle"],
    "targets.tasks.dependsOn": ["application/build.gradle", "@nx/gradle"],
    "targets.tasks.metadata": ["application/build.gradle", "@nx/gradle"],
    "targets.tasks.executor": ["application/build.gradle", "@nx/gradle"],
    "targets.tasks.options": ["application/build.gradle", "@nx/gradle"],
    "targets.tasks.options.command": ["application/build.gradle", "@nx/gradle"],
    "targets.tasks.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.tasks.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.projectReport": ["application/build.gradle", "@nx/gradle"],
    "targets.projectReport.cache": ["application/build.gradle", "@nx/gradle"],
    "targets.projectReport.inputs": ["application/build.gradle", "@nx/gradle"],
    "targets.projectReport.outputs": ["application/build.gradle", "@nx/gradle"],
    "targets.projectReport.dependsOn": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.projectReport.metadata": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.projectReport.executor": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.projectReport.options": ["application/build.gradle", "@nx/gradle"],
    "targets.projectReport.options.command": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.projectReport.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.projectReport.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.check": ["application/build.gradle", "@nx/gradle"],
    "targets.check.cache": ["application/build.gradle", "@nx/gradle"],
    "targets.check.inputs": ["application/build.gradle", "@nx/gradle"],
    "targets.check.outputs": ["application/build.gradle", "@nx/gradle"],
    "targets.check.dependsOn": ["application/build.gradle", "@nx/gradle"],
    "targets.check.metadata": ["application/build.gradle", "@nx/gradle"],
    "targets.check.executor": ["application/build.gradle", "@nx/gradle"],
    "targets.check.options": ["application/build.gradle", "@nx/gradle"],
    "targets.check.options.command": ["application/build.gradle", "@nx/gradle"],
    "targets.check.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.check.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.test": ["application/build.gradle", "@nx/gradle"],
    "targets.test.cache": ["application/build.gradle", "@nx/gradle"],
    "targets.test.inputs": ["application/build.gradle", "@nx/gradle"],
    "targets.test.outputs": ["application/build.gradle", "@nx/gradle"],
    "targets.test.dependsOn": ["application/build.gradle", "@nx/gradle"],
    "targets.test.metadata": ["application/build.gradle", "@nx/gradle"],
    "targets.test.executor": ["application/build.gradle", "@nx/gradle"],
    "targets.test.options": ["application/build.gradle", "@nx/gradle"],
    "targets.test.options.command": ["application/build.gradle", "@nx/gradle"],
    "targets.test.metadata.technologies": [
      "application/build.gradle",
      "@nx/gradle"
    ],
    "targets.test.metadata.technologies.0": [
      "application/build.gradle",
      "@nx/gradle"
    ]
  }
}
```

{% /project_details %}

The Nx command to run the `build` task for the `application` project is:

```shell
nx run application:build
```

When Nx runs a Gradle task, it hands off the execution of that task to Gradle, so all task dependencies and
configuration settings in the Gradle configuration are still respected.

By running the task via Nx, however, the task computation was cached for reuse. Now, running `nx run application:build`
again, will complete almost instantly as the result from the previous execution will be used.

```text {% title="nx run application:build"%}

   ✔  1/1 dependent project tasks succeeded [1 read from cache]

   Hint: you can run the command with --verbose to see the full dependent project outputs

—————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————


> nx run application:classes  [existing outputs match the cache, left as is]

> ./gradlew :application:classes

> Task :library:compileJava UP-TO-DATE
> Task :library:processResources NO-SOURCE
> Task :library:classes UP-TO-DATE
> Task :library:jar UP-TO-DATE
> Task :application:compileJava UP-TO-DATE
> Task :application:processResources UP-TO-DATE
> Task :application:classes UP-TO-DATE

BUILD SUCCESSFUL in 647ms
4 actionable tasks: 4 up-to-date

> nx run application:build  [existing outputs match the cache, left as is]

> ./gradlew :application:build


Deprecated Gradle features were used in this build, making it incompatible with Gradle 9.0.

You can use '--warning-mode all' to show the individual deprecation warnings and determine if they come from your own scripts or plugins.

For more on this, please refer to https://docs.gradle.org/8.5/userguide/command_line_interface.html#sec:command_line_warnings in the Gradle documentation.

BUILD SUCCESSFUL in 768ms
9 actionable tasks: 1 executed, 8 up-to-date

—————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

 NX   Successfully ran target build for project application and 3 tasks it depends on (30ms)

Nx read the output from the cache instead of running the command for 4 out of 4 tasks.
```

Now that we've run one task, let's run all the `build` tasks in the repository with the Nx `run-many` command. This is similar to Gradle's `./gradlew build` command.

```text {% title="nx run-many -t build"%}

   ✔  nx run library:classes  [existing outputs match the cache, left as is]
   ✔  nx run library:build  [existing outputs match the cache, left as is]
   ✔  nx run application:classes  [existing outputs match the cache, left as is]
   ✔  nx run application:build  [existing outputs match the cache, left as is]
   ✔  nx run gradle-tutorial:classes (1s)
   ✔  nx run gradle-tutorial:build (1s)

—————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

 NX   Successfully ran target build for 3 projects and 3 tasks they depend on (2s)

Nx read the output from the cache instead of running the command for 4 out of 6 tasks.
```

Again, because Nx cached the tasks when the application was built, most of the tasks here were near instant. The only
ones which needed to be done is the root project's build. Running the command one more time, will be near instant as
then all the tasks will be restored from the cache.

### Remote cache for faster development

With Nx Cloud connected, your task results are now cached remotely. This means that if another developer runs the same tasks, or if you run them in CI, the results will be retrieved from the remote cache instead of being re-executed.

Try running the build again after making a small change to see how Nx intelligently determines which tasks need to be re-run:

```shell
nx run-many -t build
```

You'll notice that only the affected projects need to rebuild, while others are restored from cache.

## Self-Healing CI with Nx Cloud

Explore how Nx Cloud can help your pull request get to green faster with self-healing CI.

You can copy the example GitHub Action workflow file and place it in the `.github/workflows/ci.yml` directory of your repository. This workflow will run the `lint`, `test`, and `build` tasks for all projects in your repository whenever a pull request is opened or updated.

The `npx nx fix-ci` command that is already included in your GitHub Actions workflow (`github/workflows/ci.yml`) is responsible for enabling self-healing CI and will automatically suggest fixes to your failing tasks.

```yaml {% meta="{34,35}" %}
# .github/workflows/ci.yml
name: CI

on:
  push:
    branches:
      - main
  pull_request:

permissions:
  actions: read
  contents: read

jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          filter: tree:0
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Set up JDK 21 for x64
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
          architecture: x64
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@v4
      - run: npx nx run-many -t lint test build
      - run: npx nx fix-ci
        if: always()
```

You will also need to install the [Nx Console](/docs/getting-started/editor-setup) editor extension for VS Code, Cursor, or IntelliJ. For the complete AI setup guide, see our [AI integration documentation](/docs/getting-started/ai-setup).

{% install_nx_console /%}

### Open a pull request

Start by making a new branch to work on.

```shell
git checkout -b self-healing-ci
```

Now for demo purposes, we'll make a mistake in our `DemoApplication` class that will cause the build to fail.

```diff {% meta="lang='java'" %}
// application/src/main/java/com/example/multimodule/application/DemoApplication.java
    @GetMapping("/")
    public String home() {
+       return myService.messages();
-       return myService.message();
    }
```

Commit the changes and open a new PR on GitHub.

```shell
git add .
git commit -m 'demo self-healing ci'
git push origin self-healing-ci
```

Once pushed, CI will kick off, and we'll run into an error for the `application:build` task.
When the build task fails, you'll see Nx Cloud begin to analyze the failure and suggest a fix. When a fix is proposed, Nx Console will show a notification for you to review the potential fix. From here you can reject or apply the fix. Applying the fix will commit back to your PR and re-trigger CI to run.

You can also see the fix link on the GitHub PR comment that Nx Cloud leaves.

![Nx Cloud PR comment with AI fix suggestion](../../../../assets/tutorials/nx-cloud-gh-comment-self-healing-coment.avif)

From here you can manually apply or reject the fix:

![Nx Cloud apply AI fix suggestion](../../../../assets/tutorials/nx-cloud-apply-fix-self-healing-ci.avif)

For more information about how Nx can improve your CI pipeline, check out our [CI guides](/docs/guides/nx-cloud/setup-ci)

## Summary

Now that you have added Nx to this sample Gradle repository, you have learned several ways that Nx can help your
organization:

- Nx reflects the Gradle graph into the Nx graph
- Nx dependency graph visualisation helps you understand your codebase
- Nx caches task results and reuses them when the same task is rerun later
- Nx Cloud provides self-healing CI and remote caching to speed up CI
- Nx [intelligently determines which tasks are `affected`](/docs/features/ci-features/affected) by code changes to reduce waste in CI

## Next steps

Connect with the rest of the Nx community with these resources:

- ⭐️ [Star us on GitHub](https://github.com/nrwl/nx) to show your support and stay updated on new releases!
- [Join the Official Nx Discord Server](https://go.nx.dev/community) to ask questions and find out the latest news about
  Nx.
- [Follow Nx on Twitter](https://twitter.con/nxdevtools) to stay up to date with Nx news
- [Read our Nx blog](https://nx.dev/blog)
- [Subscribe to our Youtube channel](https://www.youtube.com/@nxdevtools) for demos and Nx insights

---
<!-- source: https://nx.dev/docs/getting-started/tutorials/managing-dependencies.md -->
## Managing Dependencies

{% llm_copy_prompt title="Tutorial 2/8: Understand project dependencies" %}
Help me understand how my Nx workspace tracks dependencies between projects.
Use my existing workspace and projects for hands-on examples.

Run `nx graph` in my workspace and help me interpret the results. Show me which projects depend on each other and explain how Nx detects these relationships.

If dependencies are missing or unexpected, help me debug by checking import paths, tsconfig paths, and package.json entries.

Stay on-topic: only teach what's covered on this page. Do not introduce concepts from later tutorials.

Tutorial: {pageUrl}
{% /llm_copy_prompt %}

As your workspace grows, projects start depending on each other and on external packages. Nx automatically tracks these relationships so it can build projects in the right order, cache intelligently, and tell you what's affected by a change.

{% aside type="note" title="Tutorial Series" %}

1. [Crafting your workspace](/docs/getting-started/tutorials/crafting-your-workspace)
2. **Managing dependencies** (you are here)
3. [Configuring tasks](/docs/getting-started/tutorials/configuring-tasks)
4. [Running tasks](/docs/getting-started/tutorials/running-tasks)
5. [Caching](/docs/getting-started/tutorials/caching)
6. [Understanding your workspace](/docs/getting-started/tutorials/understanding-your-workspace)
7. [Reducing boilerplate](/docs/getting-started/tutorials/reducing-configuration-boilerplate)
8. [Setting up CI](/docs/getting-started/tutorials/self-healing-ci-tutorial)

{% /aside %}

This tutorial assumes you have an Nx workspace with at least two projects. If you're starting fresh, complete [Crafting Your Workspace](/docs/getting-started/tutorials/crafting-your-workspace) first.

## Workspace libraries

Workspace libraries are projects whose source lives in your workspace and are linked together by your package manager (see [Crafting Your Workspace](/docs/getting-started/tutorials/crafting-your-workspace) for how this works). In your project's `package.json`, workspace libraries use `workspace:*` (or `*` for npm) while external packages use version ranges:

{% tabs syncKey="package-manager" %}
{% tabitem label="npm" %}

```jsonc
// apps/my-app/package.json
{
  "dependencies": {
    "react": "^19.0.0",
    "@my-workspace/shared-ui": "*",
  },
}
```

{% /tabitem %}
{% tabitem label="pnpm" %}

```jsonc
// apps/my-app/package.json
{
  "dependencies": {
    "react": "^19.0.0",
    "@my-workspace/shared-ui": "workspace:*",
  },
}
```

{% /tabitem %}
{% tabitem label="yarn" %}

```jsonc
// apps/my-app/package.json
{
  "dependencies": {
    "react": "^19.0.0",
    "@my-workspace/shared-ui": "workspace:*",
  },
}
```

{% /tabitem %}
{% tabitem label="bun" %}

```jsonc
// apps/my-app/package.json
{
  "dependencies": {
    "react": "^19.0.0",
    "@my-workspace/shared-ui": "workspace:*",
  },
}
```

{% /tabitem %}
{% /tabs %}

When one project imports from another, Nx detects the relationship automatically. No configuration required.

```typescript
// apps/my-app/src/app.tsx
import { Button } from '@my-workspace/shared-ui';
```

Nx analyzes your JS/TS source code and `package.json` dependencies to understand how projects relate to each other. Nx uses these relationships to [run tasks](/docs/getting-started/tutorials/running-tasks) in the correct order.

{% aside type="note" title="Non-JavaScript languages" %}
For non-JS languages, Nx does not detect dependencies from source code imports. Declare relationships manually with `implicitDependencies` in `project.json`:

```jsonc
// apps/my-python-app/project.json
{
  "implicitDependencies": ["shared-lib"],
}
```

You can also use [community plugins](/docs/plugin-registry) that provide dependency detection for your language.
{% /aside %}

### Buildable vs non-buildable libraries

Workspace libraries come in two flavors, and the difference is in what their `package.json` `exports` field points to.

**Non-buildable libraries** export their source code directly. Consumers compile the source as part of their own build. This is the simpler setup and works well for most workspace libraries.

```jsonc
// packages/shared-ui/package.json
{
  "name": "@my-workspace/shared-ui",
  "exports": {
    ".": "./src/index.ts",
  },
}
```

**Buildable libraries** export compiled artifacts. They have their own build step that produces output (e.g., to `dist/`), and consumers import the built result. This is useful for libraries that need to be published or that benefit from independent compilation. Use a conditional export so that tooling can still resolve to the source:

```jsonc
// packages/data-access/package.json
{
  "name": "@my-workspace/data-access",
  "exports": {
    ".": {
      "development": "./src/index.ts",
      "default": "./dist/index.js",
    },
  },
}
```

The `development` condition points to source, while `default` points to the built output. Configure `customConditions` in your root `tsconfig.json` so your IDE and TypeScript language server resolve the `development` entry, giving you go-to-definition and type checking against the actual source:

```jsonc
// tsconfig.json
{
  "compilerOptions": {
    "customConditions": ["development"],
  },
}
```

At build time, the bundler resolves the `default` entry and uses the compiled artifacts.

Start with non-buildable libraries. They're simpler and avoid needing to rebuild libraries during development. Switch to buildable when you need to publish a library or want faster incremental builds in large workspaces.

## Single version policy

In a monorepo, some packages, especially frameworks like React, Angular, or Vue, must be the same version everywhere. Having two versions of React in the same app causes runtime errors.

A **single version policy** means defining dependency versions once at the root and having all projects use that version. This prevents version conflicts and simplifies upgrades.

**Catalogs** make this easier by letting you name a version once and reference it everywhere:

{% tabs syncKey="package-manager" %}
{% tabitem label="pnpm" %}

```yaml
# pnpm-workspace.yaml
catalog:
  react: ^19.0.0
  react-dom: ^19.0.0
```

```jsonc
// package.json
{
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:",
  },
}
```

{% /tabitem %}
{% tabitem label="yarn" %}

Define catalogs in `.yarnrc.yml`:

```yaml
# .yarnrc.yml
catalogs:
  default:
    react: ^19.0.0
    react-dom: ^19.0.0
```

```jsonc
// package.json
{
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:",
  },
}
```

{% /tabitem %}
{% tabitem label="npm" %}

npm does not have catalog support. Enforce a single version policy by defining all dependencies in the root `package.json` and using tools like [`syncpack`](https://syncpack.dev/) or the `@nx/dependency-checks` ESLint rule to catch version mismatches.

{% /tabitem %}
{% tabitem label="bun" %}

Bun does not currently support catalogs. Define shared dependency versions in the root `package.json` and reference them using `workspace:*` for internal packages.

{% /tabitem %}
{% /tabs %}

For a deeper comparison of dependency strategies, see [Dependency Management Strategies](/docs/concepts/decisions/dependency-management).

## What Nx does (and doesn't do)

Nx **tracks** dependencies. It builds the project graph, determines build order, and knows what's affected by a change. But Nx **does not install or resolve** dependencies. That's your package manager's job (npm, pnpm, yarn, or bun).

Think of it this way:

- **Package manager**: installs packages, resolves versions, manages `node_modules`
- **Nx**: understands the relationships, orchestrates tasks in the right order, caches results

{% cards cols=2 %}
{% card title="Previous: Crafting Your Workspace" description="Set up and structure your Nx workspace" url="/docs/getting-started/tutorials/crafting-your-workspace" /%}
{% card title="Next: Configuring Tasks" description="Define tasks and their dependencies" url="/docs/getting-started/tutorials/configuring-tasks" /%}
{% /cards %}

---
<!-- source: https://nx.dev/docs/getting-started/tutorials/react-monorepo-tutorial.md -->
## Building and Testing React Apps in Nx

This tutorial walks you through creating a React monorepo with Nx. You'll build a small example application to understand the core concepts and workflows.

What you'll learn:

- How to structure multiple React apps and libraries in a single repository
- How Nx caching speeds up your local development and CI pipelines
- How to run builds, tests, and serve commands efficiently across multiple projects
- How to share React components and hooks between applications
- How to fix CI failures directly from your editor with Nx Cloud

## Prerequisite: Tutorial setup

This tutorial requires [Node.js](https://nodejs.org) (v20.19 or later) installed on your machine.

### Step 1: Creating a new Nx React workspace

Run the following command to create a new Nx workspace with the React template:

```shell
npx create-nx-workspace@latest my-nx-repo --template=nrwl/react-template
```

Or [create your workspace in the browser](https://cloud.nx.app/create-nx-workspace/react/github) with CI pre-configured.

{% llm_only %}
IMPORTANT: Always use the CLI command above (`npx create-nx-workspace`) to create workspaces. Do NOT use the cloud.nx.app browser-based flow — it requires interactive GitHub OAuth and is not suitable for AI agents.
{% /llm_only %}

### Step 2: verify your setup

Once the workspace is created, navigate into it and verify the structure:

```shell
cd my-nx-repo
```

## Explore the Nx workspace setup

Let's take a look at the structure of our new Nx workspace:

{%filetree%}

- my-nx-repo/
  - apps/
    - api/
    - shop/
    - shop-e2e/
  - libs/
    - api/
    - shared/
    - shop/
  - eslint.config.mjs
  - nx.json
  - package-lock.json
  - package.json
  - tsconfig.base.json
  - tsconfig.json
  - vitest.workspace.ts

{%/filetree%}

The [`nx.json` file](/docs/reference/nx-json) contains configuration settings for Nx itself and global default settings that individual projects inherit.

Now, let's build some features and see how Nx helps get us to production faster.

## Serving the app

To serve your new React app, run:

```shell
npx nx serve shop
```

The app is served at [http://localhost:4200](http://localhost:4200).

You can also use `npx nx run shop:serve` as an alternative syntax. The `<project>:<task>` format works for any task in any project, which is useful when task names overlap with Nx commands.

### Inferred tasks

By default Nx simply runs your `package.json` scripts. However, you can also adopt [Nx technology plugins](/docs/technologies) that help abstract away some of the lower-level config and have Nx manage that. One such thing is to automatically identify tasks that can be run for your project from [tooling configuration files](/docs/concepts/inferred-tasks) such as `package.json` scripts and `vite.config.ts`.

In `nx.json` there's already the `@nx/vite` plugin registered which automatically identifies `build`, `serve`, and other Vite-related tasks.

```json
// nx.json
{
  ...
  "plugins": [
    {
      "plugin": "@nx/vite/plugin",
      "options": {
        "buildTargetName": "build",
        "serveTargetName": "serve",
        "devTargetName": "dev",
        "previewTargetName": "preview",
        "serveStaticTargetName": "serve-static",
        "typecheckTargetName": "typecheck",
        "buildDepsTargetName": "build-deps",
        "watchDepsTargetName": "watch-deps"
      }
    }
  ]
}
```

To view the tasks that Nx has detected, look in the [Nx Console](/docs/getting-started/editor-setup) project detail view or run:

```shell
npx nx show project shop
```

{% project_details title="Project Details View (Simplified)" %}

```json
{
  "project": {
    "name": "@org/shop",
    "type": "app",
    "data": {
      "root": "apps/shop",
      "targets": {
        "build": {
          "options": {
            "cwd": "apps/shop",
            "command": "vite build"
          },
          "cache": true,
          "dependsOn": ["^build"],
          "inputs": [
            "production",
            "^production",
            {
              "externalDependencies": ["vite"]
            }
          ],
          "outputs": ["{workspaceRoot}/dist/apps/shop"],
          "executor": "nx:run-commands",
          "configurations": {}
        }
      },
      "name": "shop",
      "$schema": "../../node_modules/nx/schemas/project-schema.json",
      "sourceRoot": "apps/shop/src",
      "projectType": "application",
      "tags": [],
      "implicitDependencies": []
    }
  },
  "sourceMap": {
    "root": ["apps/shop/project.json", "nx/core/project-json"],
    "targets": ["apps/shop/project.json", "nx/core/project-json"],
    "targets.build": ["apps/shop/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.command": ["apps/shop/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.options": ["apps/shop/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.cache": ["apps/shop/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.dependsOn": ["apps/shop/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.inputs": ["apps/shop/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.outputs": ["apps/shop/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.options.cwd": [
      "apps/shop/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "name": ["apps/shop/project.json", "nx/core/project-json"],
    "$schema": ["apps/shop/project.json", "nx/core/project-json"],
    "sourceRoot": ["apps/shop/project.json", "nx/core/project-json"],
    "projectType": ["apps/shop/project.json", "nx/core/project-json"],
    "tags": ["apps/shop/project.json", "nx/core/project-json"]
  }
}
```

{% /project_details %}

If you expand the `build` task, you can see that it was created by the `@nx/vite` plugin by analyzing your `vite.config.ts` file. Notice the outputs are defined as `{projectRoot}/dist`. This value is being read from the `build.outDir` defined in your `vite.config.ts` file. Let's change that value in your `vite.config.ts` file:

```ts
// apps/shop/vite.config.ts
export default defineConfig({
  // ...
  build: {
    outDir: './build',
    // ...
  },
});
```

Now if you look at the project details view, the outputs for the build target will say `{projectRoot}/build`. The `@nx/vite` plugin ensures that tasks and their options, such as outputs, are automatically and correctly configured.

{% aside type="note" title="Overriding inferred task options" %}
You can override the options for inferred tasks by modifying the [`targetDefaults` in `nx.json`](/docs/reference/nx-json#target-defaults) or setting a value in your [`package.json` file](/docs/reference/project-configuration). Nx will merge the values from the inferred tasks with the values you define in `targetDefaults` and in your specific project's configuration.
{% /aside %}

## Modularization with local libraries

When you develop your React application, usually all your logic sits in the app's `src` folder. Ideally separated by various folder names which represent your domains or features. As your app grows, however, the app becomes more and more monolithic, which makes building and testing it harder and slower.

{%filetree%}

- my-nx-repo/
  - apps/
    - shop/
      - src/
        - app/
        - cart/
        - products/
        - orders/
        - ui/

{%/filetree%}

Nx allows you to separate this logic into "local libraries." The main benefits include

- better separation of concerns
- better reusability
- more explicit private and public boundaries (APIs) between domains and features
- better scalability in CI by enabling independent test/lint/build commands for each library
- better scalability in your teams by allowing different teams to work on separate libraries

### Create local libraries

Let's create a reusable design system library called `ui` that we can use across our workspace. This library will contain reusable components such as buttons, inputs, and other UI elements.

```shell
npx nx g @nx/react:library libs/ui --unitTestRunner=vitest --bundler=none
```

Note how we type out the full path in the `directory` flag to place the library into a subfolder. You can choose whatever folder structure you like to organize your projects.

Running the above commands should lead to the following directory structure:

{% filetree %}

- my-nx-repo/
  - apps/
    - shop/
  - libs/
    - ui/
  - eslint.config.mjs
  - nx.json
  - package.json
  - tsconfig.base.json
  - tsconfig.json
  - vitest.workspace.ts

{% /filetree %}

Just as with the `shop` app, Nx automatically infers the tasks for the `ui` library from its configuration files. You can view them by running:

```shell
npx nx show project ui
```

In this case, we have the `lint` and `test` tasks available, among other inferred tasks.

```shell
npx nx lint ui
npx nx test ui
```

### Import libraries into the shop app

All libraries that we generate are automatically included in the `workspaces` defined in the root-level `package.json`.

```json
// package.json
{
  "workspaces": ["apps/*", "libs/*"]
}
```

Hence, we can easily import them into other libraries and our React application.

You can see that the `AcmeUi` component is exported via the `index.ts` file of our `ui` library so that other projects in the repository can use it. This is our public API with the rest of the workspace and is enforced by the `exports` field in the `package.json` file. Only export what's necessary to be usable outside the library itself.

```ts
// libs/ui/src/index.ts
export * from './lib/ui';
```

Let's add a simple `Hero` component that we can use in our shop app.

```tsx
// libs/ui/src/lib/hero.tsx
export function Hero(props: {
  title: string;
  subtitle: string;
  cta: string;
  onCtaClick?: () => void;
}) {
  return (
    <div
      style={{
        backgroundColor: '#1a1a2e',
        color: 'white',
        padding: '100px 20px',
        textAlign: 'center',
      }}
    >
      <h1
        style={{
          fontSize: '48px',
          marginBottom: '16px',
        }}
      >
        {props.title}
      </h1>
      <p
        style={{
          fontSize: '20px',
          marginBottom: '32px',
        }}
      >
        {props.subtitle}
      </p>
      <button
        onClick={props.onCtaClick}
        style={{
          backgroundColor: '#0066ff',
          color: 'white',
          border: 'none',
          padding: '12px 24px',
          fontSize: '18px',
          borderRadius: '4px',
          cursor: 'pointer',
        }}
      >
        {props.cta}
      </button>
    </div>
  );
}
```

Then, export it from `index.ts`.

```ts
// libs/ui/src/index.ts
export * from './lib/hero';
export * from './lib/ui';
```

We're ready to import it into our main application now.

```tsx
// apps/shop/src/app/app.tsx
import { Route, Routes } from 'react-router-dom';
// importing the component from the library
import { Hero } from '@org/ui';

export function App() {
  return (
    <>
      <h1>Home</h1>
      <Hero
        title="Welcmoe to our Demo"
        subtitle="Build something amazing today"
        cta="Get Started"
      />
    </>
  );
}

export default App;
```

Serve your app again (`npx nx serve shop`) and you should see the new Hero component from the `ui` library rendered on the home page.

![](../../../../assets/tutorials/react-demo-with-hero.avif)

If you have keen eyes, you may have noticed that there is a typo in the `App` component. This mistake is intentional, and we'll see later how Nx can fix this issue automatically in CI.

## Visualize your project structure

Nx automatically detects the dependencies between the various parts of your workspace and builds a [project graph](/docs/features/explore-graph). This graph is used by Nx to perform various optimizations such as determining the correct order of execution when running tasks like `npx nx build`, enabling intelligent caching, and more. Interestingly, you can also visualize it.

Just run:

```shell
npx nx graph
```

You should be able to see something similar to the following in your browser.

{% graph height="450px" %}

```json
{
  "projects": [
    {
      "name": "@org/shop",
      "type": "app",
      "data": {
        "tags": []
      }
    },
    {
      "name": "@org/ui",
      "type": "lib",
      "data": {
        "tags": []
      }
    }
  ],
  "dependencies": {
    "@org/shop": [
      { "source": "@org/shop", "target": "@org/ui", "type": "static" }
    ],
    "@org/ui": []
  },
  "affectedProjectIds": [],
  "focus": null,
  "groupByFolder": false
}
```

{% /graph %}

Let's create a git branch with the new hero component so we can open a pull request later:

```shell
git checkout -b add-hero-component
git add .
git commit -m 'add hero component'
```

## Testing and linting - running multiple tasks

Our current setup doesn't just come with targets for serving and building the React application, but also has targets for testing and linting. We can use the same syntax as before to run these tasks:

```shell
npx nx test shop # runs the tests for shop
npx nx lint ui   # runs the linter on ui
```

More conveniently, we can also run tasks in parallel using the following syntax:

```shell
npx nx run-many -t test lint
```

This is exactly what is configured in `.github/workflows/ci.yml` for the CI pipeline. The `run-many` command allows you to run multiple tasks across multiple projects in parallel, which is particularly useful in a monorepo setup.

There is a test failure for the `shop` app due to the updated content. Don't worry about it for now, we'll fix it in a moment with the help of Nx Cloud's self-healing feature.

### Local task cache

One thing to highlight is that Nx is able to [cache the tasks you run](/docs/features/cache-task-results).

Note that all of these targets are automatically cached by Nx. If you re-run a single one or all of them again, you'll see that the task completes immediately. In addition, (as can be seen in the output example below) there will be a note that a matching cache result was found and therefore the task was not run again.

```text {% title="npx nx run-many -t test lint" frame="terminal" %}
   ✔  nx run @org/ui:lint
   ✔  nx run @org/ui:test
   ✔  nx run @org/shop:lint
   ✖  nx run @org/shop:test

—————————————————————————————————————————————————————————————————————————————————————————————————————————

 NX   Ran targets test, lint for 2 projects (1s)

   ✔  3/4 succeeded [3 read from cache]

   ✖  1/4 targets failed, including the following:

      - nx run @org/shop:test
```

Again, the `@org/shop:test` task failed, but notice that the remaining three tasks were read from cache.

Not all tasks might be cacheable though. You can configure the `cache` settings in the `targetDefaults` property of the `nx.json` file. You can also [learn more about how caching works](/docs/features/cache-task-results).

## Next steps

Here are some things you can dive into next:

- [Set up CI](/docs/getting-started/tutorials/self-healing-ci-tutorial) with remote caching and self-healing
- Learn more about the [underlying mental model of Nx](/docs/concepts/mental-model)
- Learn how to [migrate your existing project to Nx](/docs/guides/adopting-nx/adding-to-existing-project)
- [Setup Storybook for our shared UI library](/docs/technologies/test-tools/storybook/guides/overview-react)
- [Learn how to setup Tailwind](/docs/technologies/react/guides/using-tailwind-css-in-react)
- Learn about [enforcing boundaries between projects](/docs/features/enforce-module-boundaries)

Also, make sure you

- ⭐️ [Star us on GitHub](https://github.com/nrwl/nx) to show your support and stay updated on new releases!
- [Join the Official Nx Discord Server](https://go.nx.dev/community) to ask questions and find out the latest news about Nx.
- [Follow Nx on Twitter](https://twitter.com/nxdevtools) to stay up to date with Nx news
- [Read our Nx blog](https://nx.dev/blog)
- [Subscribe to our Youtube channel](https://www.youtube.com/@nxdevtools) for demos and Nx insights

---
<!-- source: https://nx.dev/docs/getting-started/tutorials/reducing-configuration-boilerplate.md -->
## Reducing Configuration Boilerplate

{% llm_copy_prompt title="Tutorial 7/8: Reduce configuration with plugins" %}
Help me reduce configuration boilerplate in my Nx workspace.
Use my existing workspace and projects for hands-on examples.

First, consolidate shared task config into `targetDefaults` in `nx.json`. Then show me how to use Nx plugins to automatically infer tasks from my tooling (Vite, Jest, ESLint, etc.) so I don't need to configure each project manually.

Run `nx show project <project-name>` to see where each task's configuration comes from.

Stay on-topic: only teach what's covered on this page. Do not introduce concepts from later tutorials.

Tutorial: {pageUrl}
{% /llm_copy_prompt %}

Manually configuring tasks, caching, inputs, and outputs for every project works, but it doesn't scale to dozens or hundreds of projects. Nx provides two mechanisms to reduce this boilerplate: `targetDefaults` for shared configuration and **plugins** for automatic task inference.

The examples below use Vite and Vitest, but the concepts apply to any tool. Substitute your own build and test commands as needed.

{% aside type="note" title="Tutorial Series" %}

1. [Crafting your workspace](/docs/getting-started/tutorials/crafting-your-workspace)
2. [Managing dependencies](/docs/getting-started/tutorials/managing-dependencies)
3. [Configuring tasks](/docs/getting-started/tutorials/configuring-tasks)
4. [Running tasks](/docs/getting-started/tutorials/running-tasks)
5. [Caching](/docs/getting-started/tutorials/caching)
6. [Understanding your workspace](/docs/getting-started/tutorials/understanding-your-workspace)
7. **Reducing boilerplate** (you are here)
8. [Setting up CI](/docs/getting-started/tutorials/self-healing-ci-tutorial)

{% /aside %}

This tutorial assumes you have an Nx workspace with configured tasks. If you're starting fresh, complete [Configuring Tasks](/docs/getting-started/tutorials/configuring-tasks) first.

## The scaling problem

Consider a workspace with 20 libraries, each with verbose task configuration:

{% tabs %}
{% tabitem label="package.json" %}

```jsonc
// packages/my-lib/package.json
{
  "scripts": {
    "build": "vite build",
    "test": "vitest run",
  },
  "nx": {
    "targets": {
      "build": {
        "cache": true,
        "dependsOn": ["^build"],
        "inputs": [
          "{projectRoot}/src/**/*",
          "{projectRoot}/vite.config.ts",
          "{projectRoot}/tsconfig.json",
        ],
        "outputs": ["{projectRoot}/dist"],
      },
      "test": {
        "cache": true,
        "inputs": ["{projectRoot}/src/**/*", "{projectRoot}/vitest.config.ts"],
        "outputs": ["{projectRoot}/coverage"],
      },
    },
  },
}
```

{% /tabitem %}
{% tabitem label="project.json" %}

```jsonc
// packages/my-lib/project.json
{
  "targets": {
    "build": {
      "command": "vite build",
      "cache": true,
      "dependsOn": ["^build"],
      "inputs": [
        "{projectRoot}/src/**/*",
        "{projectRoot}/vite.config.ts",
        "{projectRoot}/tsconfig.json",
      ],
      "outputs": ["{projectRoot}/dist"],
    },
    "test": {
      "command": "vitest run",
      "cache": true,
      "inputs": ["{projectRoot}/src/**/*", "{projectRoot}/vitest.config.ts"],
      "outputs": ["{projectRoot}/coverage"],
    },
  },
}
```

{% /tabitem %}
{% /tabs %}

That's a lot of repetition across 20 projects. And every time you change the Vite output directory, you'd need to update all of them.

## Step 1: Target defaults

Move shared configuration to `nx.json` so projects inherit defaults:

```jsonc
// nx.json
{
  "targetDefaults": {
    "build": {
      "cache": true,
      "dependsOn": ["^build"],
    },
    "test": {
      "cache": true,
    },
  },
}
```

Now each project only needs to specify what's unique:

{% tabs %}
{% tabitem label="package.json" %}

```jsonc
// packages/my-lib/package.json
{
  "scripts": {
    "build": "vite build",
    "test": "vitest run",
  },
  "nx": {
    "targets": {
      "build": {
        "inputs": ["{projectRoot}/src/**/*", "{projectRoot}/vite.config.ts"],
        "outputs": ["{projectRoot}/dist"],
      },
      "test": {
        "inputs": ["{projectRoot}/src/**/*", "{projectRoot}/vitest.config.ts"],
        "outputs": ["{projectRoot}/coverage"],
      },
    },
  },
}
```

{% /tabitem %}
{% tabitem label="project.json" %}

```jsonc
// packages/my-lib/project.json
{
  "targets": {
    "build": {
      "command": "vite build",
      "inputs": ["{projectRoot}/src/**/*", "{projectRoot}/vite.config.ts"],
      "outputs": ["{projectRoot}/dist"],
    },
    "test": {
      "command": "vitest run",
      "inputs": ["{projectRoot}/src/**/*", "{projectRoot}/vitest.config.ts"],
      "outputs": ["{projectRoot}/coverage"],
    },
  },
}
```

{% /tabitem %}
{% /tabs %}

Better, but you still repeat `inputs` and `outputs` across projects with the same tooling.

## Step 2: Nx plugins (inferred tasks)

Nx plugins can read your existing tooling configuration files, like `vite.config.ts`, `jest.config.ts`, or `eslint.config.mjs`, and automatically create tasks with the correct caching settings. No `project.json` needed.

### Adding a plugin

Try adding a plugin to your workspace:

```shell
nx add @nx/vite
```

This installs `@nx/vite` and registers it in `nx.json`. Some plugins may also need `nx sync` to update workspace configuration files (e.g., TypeScript project references). See [maintain TypeScript monorepos](/docs/features/maintain-typescript-monorepos) for details.

After installing, check what tasks were inferred for one of your projects:

```shell
nx show project my-app
```

You should see tasks like `build`, `test`, and `serve` that were automatically created from your `vite.config.ts` file.

{% aside type="note" title="Prefixed target names" %}
Some plugins use prefixed names (e.g., `next:build`, `next:dev`) to avoid conflicting with existing `package.json` scripts. You can rename these to `build`, `dev`, etc. in the plugin options in `nx.json`, then remove the redundant scripts from `package.json`.
{% /aside %}

The plugin reads your Vite configuration and sets up correct caching, inputs, and outputs without any manual configuration.

The plugin is registered in `nx.json`:

```jsonc
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/vite/plugin",
      "options": {
        "buildTargetName": "build",
        "testTargetName": "test",
        "serveTargetName": "serve",
      },
    },
  ],
}
```

Now, any project with a `vite.config.ts` automatically gets `build`, `test`, and `serve` tasks, with correct `inputs`, `outputs`, and caching, without any `project.json` configuration.

### Seeing what's inferred

Use `nx show project` to see all tasks for a project, including where they come from:

```shell
nx show project my-lib
```

{% project_details title="Project details for my-lib" %}

```json
{
  "project": {
    "name": "my-lib",
    "type": "lib",
    "data": {
      "root": "packages/my-lib",
      "targets": {
        "build": {
          "options": { "cwd": "packages/my-lib", "command": "vite build" },
          "cache": true,
          "dependsOn": ["^build"],
          "inputs": ["production", "^production"],
          "outputs": ["{projectRoot}/dist"],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": { "technologies": ["vite"] }
        },
        "test": {
          "options": { "cwd": "packages/my-lib", "command": "vitest run" },
          "cache": true,
          "inputs": ["default", "^production"],
          "outputs": ["{projectRoot}/coverage"],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": { "technologies": ["vite"] }
        },
        "lint": {
          "cache": true,
          "options": { "cwd": "packages/my-lib", "command": "eslint ." },
          "inputs": ["default", "{workspaceRoot}/eslint.config.mjs"],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": { "technologies": ["eslint"] }
        }
      },
      "name": "my-lib",
      "sourceRoot": "packages/my-lib/src",
      "projectType": "library",
      "tags": [],
      "implicitDependencies": [],
      "metadata": { "technologies": ["react"] }
    }
  },
  "sourceMap": {
    "root": ["packages/my-lib/project.json", "nx/core/project-json"],
    "targets": ["packages/my-lib/project.json", "nx/core/project-json"],
    "targets.build": ["packages/my-lib/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.command": [
      "packages/my-lib/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.options": [
      "packages/my-lib/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.cache": [
      "packages/my-lib/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.inputs": [
      "packages/my-lib/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.outputs": [
      "packages/my-lib/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.test": ["packages/my-lib/vite.config.ts", "@nx/vite/plugin"],
    "targets.test.command": [
      "packages/my-lib/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.test.options": [
      "packages/my-lib/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.test.cache": ["packages/my-lib/vite.config.ts", "@nx/vite/plugin"],
    "targets.test.inputs": [
      "packages/my-lib/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.test.outputs": [
      "packages/my-lib/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.lint": ["packages/my-lib/eslint.config.mjs", "@nx/eslint/plugin"],
    "targets.lint.command": [
      "packages/my-lib/eslint.config.mjs",
      "@nx/eslint/plugin"
    ],
    "targets.lint.options": [
      "packages/my-lib/eslint.config.mjs",
      "@nx/eslint/plugin"
    ],
    "targets.lint.cache": [
      "packages/my-lib/eslint.config.mjs",
      "@nx/eslint/plugin"
    ],
    "targets.lint.inputs": [
      "packages/my-lib/eslint.config.mjs",
      "@nx/eslint/plugin"
    ]
  }
}
```

{% /project_details %}

The project details view shows each task's source (plugin, `targetDefaults`, or `project.json`) and its computed settings.

## How the configuration cascade works

Task configuration can come from three sources, applied in this order:

1. **Plugin-inferred**: automatic from tooling config (lowest priority)
2. **targetDefaults**: shared defaults in `nx.json`
3. **Project-level**: explicit `project.json` or `package.json` config (highest priority)

Each layer can override the previous one. This means you can use plugins for sensible defaults and only add project-level config when a project needs something different.

## This is optional

Plugins are optional. The explicit task configuration from [Configuring Tasks](/docs/getting-started/tutorials/configuring-tasks) works perfectly well. Use plugins when:

- You have many projects with the same tooling (Vite, Jest, ESLint, etc.)
- You want caching configured automatically with correct `inputs`/`outputs`
- You prefer minimal configuration files

Stick with explicit configuration when:

- You have unique build setups that plugins don't cover
- You want full control over every task detail
- Your team prefers explicit over implicit

## Learn more

- [Inferred tasks](/docs/concepts/inferred-tasks): how plugins detect and configure tasks
- [Nx plugins](/docs/concepts/nx-plugins): the full plugin system
- [Reduce repetitive configuration](/docs/guides/tasks--caching/reduce-repetitive-configuration): step-by-step guide
- [Extending Nx](/docs/extending-nx/intro): create your own plugins

{% cards cols=2 %}
{% card title="Previous: Understanding Your Workspace" description="Explore projects, graphs, and debug issues" url="/docs/getting-started/tutorials/understanding-your-workspace" /%}
{% card title="Next: Setting Up CI" description="Configure CI with remote caching and self-healing" url="/docs/getting-started/tutorials/self-healing-ci-tutorial" /%}
{% /cards %}

---
<!-- source: https://nx.dev/docs/getting-started/tutorials/running-tasks.md -->
## Running Tasks

{% llm_copy_prompt title="Tutorial 4/8: Run tasks across your workspace" %}
Help me run tasks in my Nx workspace efficiently.
Use my existing workspace and projects for hands-on examples.

Show me how to run a single task for one project, run multiple tasks across all projects with `nx run-many`, and understand how Nx orders task execution. Do not discuss caching or affected commands — those are covered in later tutorials.

Stay on-topic: only teach what's covered on this page. Do not introduce concepts from later tutorials.

Tutorial: {pageUrl}
{% /llm_copy_prompt %}

You've configured your tasks. Now how do you run them — for one project, for many, or only for what changed?

The examples below use Vite and Vitest, but the concepts apply to any tool. Substitute your own build and test commands as needed.

{% aside type="note" title="Tutorial Series" %}

1. [Crafting your workspace](/docs/getting-started/tutorials/crafting-your-workspace)
2. [Managing dependencies](/docs/getting-started/tutorials/managing-dependencies)
3. [Configuring tasks](/docs/getting-started/tutorials/configuring-tasks)
4. **Running tasks** (you are here)
5. [Caching](/docs/getting-started/tutorials/caching)
6. [Understanding your workspace](/docs/getting-started/tutorials/understanding-your-workspace)
7. [Reducing boilerplate](/docs/getting-started/tutorials/reducing-configuration-boilerplate)
8. [Setting up CI](/docs/getting-started/tutorials/self-healing-ci-tutorial)

{% /aside %}

This tutorial assumes you have an Nx workspace with configured tasks. If you're starting fresh, complete [Configuring Tasks](/docs/getting-started/tutorials/configuring-tasks) first.

## Running a single task

Given a project with tasks defined in `package.json` (or `project.json` for non-JS projects):

{% tabs %}
{% tabitem label="package.json" %}

```jsonc
// apps/my-app/package.json
{
  "name": "my-app",
  "scripts": {
    "build": "vite build",
    "test": "vitest run",
  },
}
```

{% /tabitem %}
{% tabitem label="project.json" %}

```jsonc
// apps/my-app/project.json
{
  "targets": {
    "build": {
      "command": "vite build",
    },
    "test": {
      "command": "vitest run",
    },
  },
}
```

{% /tabitem %}
{% /tabs %}

Run a task with `nx run <project>:<task>`:

```shell
nx run my-app:build
```

Or the shorthand, which works when the task name doesn't conflict with an Nx command:

```shell
nx build my-app
```

You can also `cd` into a project directory and run without specifying the project name:

```shell
cd apps/my-app
nx build
```

Nx resolves the project from the current directory. Try running `nx build` or `nx test` in your own workspace to see it in action.

## Running multiple tasks

Use `run-many` to run one or more tasks across multiple projects:

```shell
# Run build for all projects that have a build task
nx run-many --targets build

# Run multiple tasks
nx run-many --targets build test lint

# Run tasks for specific projects only
nx run-many --targets build --projects my-app
```

The `-t` and `-p` flags are shorthands for `--targets` and `--projects`.

Nx runs tasks in parallel by default, respecting the [task dependencies](/docs/getting-started/tutorials/configuring-tasks) you've configured. For example, with this configuration:

```jsonc
// nx.json
{
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
    },
  },
}
```

Running `nx run-many --targets build` builds dependencies first, then dependents:

![Diagram showing task execution order: shared-ui:build and utils:build run in step 1, then my-app:build and data-access:build run in step 2, driven by dependsOn configuration](../../../../assets/tutorials/task-dependency-order.svg)

Nx handles the ordering automatically, even when running in parallel.

## Passing arguments

Pass arguments directly to the task:

```shell
# Use a named configuration
nx build my-app --configuration=production

# Forward arguments to the underlying tool
nx test my-app --watch
```

For more details, see [pass args to commands](/docs/guides/tasks--caching/pass-args-to-commands).

## Controlling parallelism

By default, Nx runs tasks in parallel. Limit the number of concurrent tasks with `--parallel`:

```shell
nx run-many --targets build --parallel=3
```

Set `--parallel=1` to run tasks sequentially.

## Running continuous tasks

Some tasks run indefinitely, like development servers. When another task depends on a continuous task, Nx starts both concurrently. For example, running an e2e test that needs a dev server:

```shell
nx run my-app:e2e
```

This works when `e2e` depends on a `serve` task marked as `continuous` (configured in [Configuring Tasks](/docs/getting-started/tutorials/configuring-tasks)). Nx starts the server, waits for it to be ready, then runs the tests.

## Nx Console

[Nx Console](/docs/getting-started/editor-setup) is a VS Code and WebStorm extension that provides a visual interface for running tasks, exploring your project graph, and managing your workspace, all without memorizing CLI commands.

## Learn more

- [Run tasks](/docs/features/run-tasks): full feature documentation
- [Pass args to commands](/docs/guides/tasks--caching/pass-args-to-commands): detailed argument handling

{% cards cols=2 %}
{% card title="Previous: Configuring Tasks" description="Define tasks and their dependencies" url="/docs/getting-started/tutorials/configuring-tasks" /%}
{% card title="Next: Caching Tasks" description="Speed up tasks by replaying previous results" url="/docs/getting-started/tutorials/caching" /%}
{% /cards %}

---
<!-- source: https://nx.dev/docs/getting-started/tutorials/self-healing-ci-tutorial.md -->
## Setting Up CI

{% llm_copy_prompt title="Tutorial 8/8: Set up CI with Nx Cloud" %}
Help me set up CI for my Nx workspace.

Connect to Nx Cloud with `nx connect`, generate a CI workflow with `nx g @nx/workspace:ci-workflow`, and walk me through remote caching, affected commands, and self-healing CI.

Stay on-topic: only teach what's covered on this page. Do not introduce concepts from later tutorials.

Tutorial: {pageUrl}
{% /llm_copy_prompt %}

Connect your workspace to Nx Cloud, generate a CI workflow, and enable remote caching, affected commands, distributed task execution, and self-healing to keep your pipeline fast and reliable.

{% aside type="note" title="Tutorial Series" %}

1. [Crafting your workspace](/docs/getting-started/tutorials/crafting-your-workspace)
2. [Managing dependencies](/docs/getting-started/tutorials/managing-dependencies)
3. [Configuring tasks](/docs/getting-started/tutorials/configuring-tasks)
4. [Running tasks](/docs/getting-started/tutorials/running-tasks)
5. [Caching](/docs/getting-started/tutorials/caching)
6. [Understanding your workspace](/docs/getting-started/tutorials/understanding-your-workspace)
7. [Reducing boilerplate](/docs/getting-started/tutorials/reducing-configuration-boilerplate)
8. **Setting up CI** (you are here)

{% /aside %}

This tutorial assumes you have a [GitHub account](https://github.com) and [Node.js](https://nodejs.org) v20.19 or later.

## Connect to Nx Cloud

### Don't have a workspace yet?

Create a workspace, GitHub repository, and Nx Cloud connection in one step:

{% call_to_action variant="default" title="Create a new Nx workspace" url="https://cloud.nx.app/create-nx-workspace?utm_source=nx-dev&utm_medium=ci-tutorial&utm_campaign=try-nx-cloud" description="Setup takes less than 2 minutes" /%}

This also generates a CI workflow, so you can skip ahead to [Remote caching](#remote-caching).

### Connect an existing workspace

If you already have an Nx workspace, connect it to Nx Cloud:

{% aside type="note" title="Prerequisites for nx connect" %}
Your workspace must be pushed to a Git provider (GitHub, GitLab, Bitbucket, or Azure DevOps) before running `nx connect`. After connecting, Nx Cloud opens a PR that adds `nxCloudId` to `nx.json`. Merge this PR before proceeding so CI runs appear on the Nx Cloud dashboard.
{% /aside %}

```shell
nx connect
```

This creates an Nx Cloud account (if you don't have one) and connects your workspace. Once connected, you can see your workspace in your [Nx Cloud organization](https://cloud.nx.app/orgs).

The access token is stored in `nx.json` and should be committed to your repository. It only grants cache read/write access, not admin access to your Nx Cloud organization.

## Generate a CI workflow

If your workspace already has a CI workflow (e.g., `.github/workflows/ci.yml`), skip to [Remote caching](#remote-caching).

Generate a CI workflow for GitHub Actions:

```shell
nx add @nx/workspace
nx g @nx/workspace:ci-workflow --ci=github
```

The `@nx/workspace` package provides the CI workflow generator. Once installed, the generator creates a `.github/workflows/ci.yml` file. It also supports CircleCI, GitLab CI, Azure Pipelines, and Bitbucket Pipelines. Pass a different `--ci` value or run `nx g @nx/workspace:ci-workflow --help` to see all options.

{% aside type="note" title="Generated output may differ" %}
The generated workflow may differ from the example below depending on your workspace setup and Nx version. The key elements (affected command, remote caching, fix-ci) will be present.
{% /aside %}

```yaml
# .github/workflows/ci.yml
name: CI

on:
  push:
    branches:
      - main
  pull_request:

permissions:
  actions: read
  contents: read

jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          filter: tree:0
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - run: npm ci

      - run: npx nx affected -t lint test build

      - run: npx nx fix-ci
        if: always()
```

This workflow includes several Nx CI features out of the box. The sections below explain each one.

## Remote caching

When Nx Cloud is connected, task results are cached remotely. If a task has already run with the same inputs (on any machine or CI run), the result is replayed instantly instead of running again.

This means:

- The second CI run on a PR is faster because unchanged tasks hit the cache
- Developers pulling the latest `main` get cached results from CI
- Build artifacts like `dist/` and test coverage are restored from cache, not recomputed

For more details, see [remote cache (Nx Replay)](/docs/features/ci-features/remote-cache).

## Running only affected tasks

The generated workflow uses `nx affected` instead of `nx run-many`. This compares the PR's changes against the base branch and only runs tasks for projects that could be impacted:

```shell
nx affected -t lint test build
```

Nx determines the base and head commits using `NX_BASE` and `NX_HEAD` environment variables. The generated CI workflow configures these automatically through the `fetch-depth: 0` checkout, which gives Nx access to the full git history for comparison.

On a PR, Nx compares the PR branch against `main` (or whatever `defaultBase` is set to in `nx.json`). On a push to `main`, it compares against the previous commit.

For more details, see [affected](/docs/features/ci-features/affected).

## Distributing tasks across machines

For larger workspaces, you can distribute task execution across multiple machines using Nx Agents. Instead of running all tasks on a single CI runner, Nx Cloud coordinates the work across a fleet of agents:

```yaml
# Add to your CI workflow
- run: npx nx start-ci-run --distribute-on="3 linux-medium-js"
```

Nx Agents automatically split tasks across the available agents, respecting task dependencies and maximizing parallelism. No configuration changes to your tasks are needed.

For more details, see [distribute task execution (Nx Agents)](/docs/features/ci-features/distribute-task-execution).

## Self-healing CI

The `npx nx fix-ci` command at the end of the workflow enables self-healing CI. When a task fails, Nx Cloud analyzes the failure and suggests a fix that you can apply directly from your editor (via [Nx Console](/docs/getting-started/editor-setup)).

This is useful for catching flaky tests, configuration drift, and other issues that can be auto-remediated without manual debugging.

For more details, see [self-healing CI](/docs/features/ci-features/self-healing-ci).

## Next steps

- [Remote cache (Nx Replay)](/docs/features/ci-features/remote-cache): how remote caching works
- [Affected](/docs/features/ci-features/affected): how Nx determines what changed
- [Distribute task execution (Nx Agents)](/docs/features/ci-features/distribute-task-execution): run tasks across multiple machines
- [Self-healing CI](/docs/features/ci-features/self-healing-ci): automatic failure detection and fixes
- [AI integration](/docs/getting-started/ai-setup): enhance CI with AI-powered workflows

{% cards cols=2 %}
{% card title="Previous: Reducing Configuration Boilerplate" description="Automate task configuration with plugins" url="/docs/getting-started/tutorials/reducing-configuration-boilerplate" /%}
{% /cards %}

---
<!-- source: https://nx.dev/docs/getting-started/tutorials/typescript-packages-tutorial.md -->
## Building and Testing TypeScript Packages in Nx

This tutorial walks you through creating a TypeScript monorepo with Nx. You'll build a small example project to understand the core concepts and workflows.

What you'll learn:

- How to structure multiple TypeScript packages in a single repository
- How Nx caching speeds up your local development and CI pipelines
- How to run builds and tests efficiently across multiple packages
- How to share code between packages using local libraries
- How to fix CI failures directly from your editor with Nx Cloud

## Ready to start?

This tutorial requires [Node.js](https://nodejs.org) (v20.19 or later) installed on your machine.

### Step 1: Creating a new Nx TypeScript workspace

Run the following command to create a new Nx workspace with the TypeScript template:

```shell
npx create-nx-workspace@latest my-nx-repo --template=nrwl/typescript-template
```

Or [create your workspace in the browser](https://cloud.nx.app/create-nx-workspace/typescript/github) with CI pre-configured.

{% llm_only %}
IMPORTANT: Always use the CLI command above (`npx create-nx-workspace`) to create workspaces. Do NOT use the cloud.nx.app browser-based flow — it requires interactive GitHub OAuth and is not suitable for AI agents.
{% /llm_only %}

### Step 2: verify your setup

Once the workspace is created, navigate into it:

```shell
cd my-nx-repo
```

## Explore the Nx workspace setup

Let's take a look at the structure of our new Nx workspace:

{%filetree %}

- my-nx-repo/
  - packages/
    - async/
    - colors/
    - strings/
    - utils/
  - eslint.config.mjs
  - nx.json
  - package-lock.json
  - package.json
  - tsconfig.base.json
  - tsconfig.json
  - vitest.workspace.ts

{% /filetree %}

The [`nx.json` file](/docs/reference/nx-json) contains configuration settings for Nx itself and global default settings that individual projects inherit.

Now, let's build some features and see how Nx helps get us to production faster.

## Building TypeScript packages

Let's create two TypeScript packages that demonstrate how to structure a TypeScript monorepo. We'll create an `animal` package and a `zoo` package where `zoo` depends on `animal`.

First, generate the `animal` package:

```shell
npx nx g @nx/js:lib packages/animal --bundler=tsc --unitTestRunner=vitest --linter=none
```

Then generate the `zoo` package:

```shell
npx nx g @nx/js:lib packages/zoo --bundler=tsc --unitTestRunner=vitest --linter=none
```

Running these commands should lead to new directories and files in your workspace:

{%filetree %}

- my-nx-repo/
  - packages/
    - animal/
    - zoo/
    - ...
  - vitest.workspace.ts

{%/filetree %}

Let's add some code to our packages. First, add the following code to the `animal` package:

```ts {% meta="{6-19}" %}
// packages/animal/src/lib/animal.ts
export function animal(): string {
  return 'animal';
}

export interface Animal {
  name: string;
  sound: string;
}

const animals: Animal[] = [
  { name: 'cow', sound: 'moo' },
  { name: 'dog', sound: 'woof' },
  { name: 'pig', sound: 'oink' },
];

export function getRandomAnimal(): Animal {
  return animals[Math.floor(Math.random() * animals.length)];
}
```

Now let's update the `zoo` package to use the `animal` package:

```ts
// packages/zoo/src/lib/zoo.ts
import { getRandomAnimal } from '@org/animal';

export function zoo(): string {
  const result = getRandomAnimal();
  return `${result.name} says ${result.sound}!`;
}
```

Add the `@org/animal` dependency to `zoo`'s `package.json` (use `*` for npm or `workspace:*` for pnpm/yarn):

```json {% meta="{3-5}" %}
// packages/zoo/package.json
{
  "dependencies": {
    "@org/animal": "*"
  }
}
```

Then link the packages:

```shell
npm install
```

Now create an executable entry point for the zoo package:

```ts
// packages/zoo/src/index.ts
import { zoo } from './lib/zoo.js';

console.log(zoo());
```

To build your packages, run:

```shell
npx nx build animal
```

You can also use `npx nx run animal:build` as an alternative syntax. The `<project>:<task>` format works for any task in any project, which is useful when task names overlap with Nx commands.

This creates a compiled version of your package in the `dist/packages/animal` folder. Since the `zoo` package depends on `animal`, building `zoo` will automatically build `animal` first:

```shell
npx nx build zoo
```

You'll see both packages are built, with outputs in their respective `dist` folders. This is how you would prepare packages for use internally or for publishing to a package registry like NPM.

You can also run the `zoo` package to see it in action:

```shell
node packages/zoo/dist/index.js
```

### Inferred tasks

By default Nx simply runs your `package.json` scripts. However, you can also adopt [Nx technology plugins](/docs/technologies) that help abstract away some of the lower-level config and have Nx manage that. One such thing is to automatically identify tasks that can be run for your project from [tooling configuration files](/docs/concepts/inferred-tasks) such as `package.json` scripts and TypeScript configuration.

In `nx.json` there's already the `@nx/js` plugin registered which automatically identifies `typecheck` and `build` targets.

```json
// nx.json
{
  ...
  "plugins": [
    {
      "plugin": "@nx/js/typescript",
      "options": {
        "typecheck": {
          "targetName": "typecheck"
        },
        "build": {
          "targetName": "build",
          "configName": "tsconfig.lib.json",
          "buildDepsName": "build-deps",
          "watchDepsName": "watch-deps"
        }
      }
    }
  ]
}
```

To view the tasks that Nx has detected, look in the [Nx Console](/docs/getting-started/editor-setup) project detail view or run:

```shell
npx nx show project animal
```

{% project_details title="Project Details View (Simplified)" %}

```json
{
  "project": {
    "name": "@org/animal",
    "type": "lib",
    "data": {
      "root": "packages/animal",
      "targets": {
        "typecheck": {
          "dependsOn": ["^typecheck"],
          "options": {
            "cwd": "packages/animal",
            "command": "tsc --build --emitDeclarationOnly"
          },
          "cache": true,
          "inputs": [
            "production",
            "^production",
            {
              "externalDependencies": ["typescript"]
            }
          ],
          "outputs": ["{projectRoot}/dist"],
          "executor": "nx:run-commands",
          "configurations": {}
        },
        "build": {
          "options": {
            "cwd": "packages/animal",
            "command": "tsc --build tsconfig.lib.json"
          },
          "cache": true,
          "dependsOn": ["^build"],
          "inputs": [
            "production",
            "^production",
            {
              "externalDependencies": ["typescript"]
            }
          ],
          "outputs": ["{projectRoot}/dist"],
          "executor": "nx:run-commands",
          "configurations": {}
        }
      },
      "name": "animal",
      "$schema": "../../node_modules/nx/schemas/project-schema.json",
      "sourceRoot": "packages/animal/src",
      "projectType": "library",
      "tags": [],
      "implicitDependencies": []
    }
  },
  "sourceMap": {
    "root": ["packages/animal/project.json", "nx/core/project-json"],
    "targets": ["packages/animal/project.json", "nx/core/project-json"],
    "targets.typecheck": ["packages/animal/project.json", "@nx/js/typescript"],
    "targets.typecheck.command": [
      "packages/animal/project.json",
      "@nx/js/typescript"
    ],
    "targets.typecheck.options": [
      "packages/animal/project.json",
      "@nx/js/typescript"
    ],
    "targets.typecheck.cache": [
      "packages/animal/project.json",
      "@nx/js/typescript"
    ],
    "targets.typecheck.dependsOn": [
      "packages/animal/project.json",
      "@nx/js/typescript"
    ],
    "targets.typecheck.inputs": [
      "packages/animal/project.json",
      "@nx/js/typescript"
    ],
    "targets.typecheck.outputs": [
      "packages/animal/project.json",
      "@nx/js/typescript"
    ],
    "targets.typecheck.options.cwd": [
      "packages/animal/project.json",
      "@nx/js/typescript"
    ],
    "targets.build": ["packages/animal/project.json", "@nx/js/typescript"],
    "targets.build.command": [
      "packages/animal/project.json",
      "@nx/js/typescript"
    ],
    "targets.build.options": [
      "packages/animal/project.json",
      "@nx/js/typescript"
    ],
    "targets.build.cache": [
      "packages/animal/project.json",
      "@nx/js/typescript"
    ],
    "targets.build.dependsOn": [
      "packages/animal/project.json",
      "@nx/js/typescript"
    ],
    "targets.build.inputs": [
      "packages/animal/project.json",
      "@nx/js/typescript"
    ],
    "targets.build.outputs": [
      "packages/animal/project.json",
      "@nx/js/typescript"
    ],
    "targets.build.options.cwd": [
      "packages/animal/project.json",
      "@nx/js/typescript"
    ],
    "name": ["packages/animal/project.json", "nx/core/project-json"],
    "$schema": ["packages/animal/project.json", "nx/core/project-json"],
    "sourceRoot": ["packages/animal/project.json", "nx/core/project-json"],
    "projectType": ["packages/animal/project.json", "nx/core/project-json"],
    "tags": ["packages/animal/project.json", "nx/core/project-json"]
  }
}
```

{% /project_details %}

The `@nx/js` plugin automatically configures both the build and typecheck tasks based on your TypeScript configuration. Notice also how the outputs are set to `{projectRoot}/dist` - this is where your compiled TypeScript files will be placed, and it defined by the `outDir` option in `packages/animal/tsconfig.lib.json`.

{% aside type="note" title="Overriding inferred task options" %}
You can override the options for inferred tasks by modifying the [`targetDefaults` in `nx.json`](/docs/reference/nx-json#target-defaults) or setting a value in your [`project.json` file](/docs/reference/project-configuration). Nx will merge the values from the inferred tasks with the values you define in `targetDefaults` and in your specific project's configuration.
{% /aside %}

## Code sharing with local libraries

When you develop packages, creating shared utilities that multiple packages can use is a common pattern. This approach offers several benefits:

- better separation of concerns
- better reusability
- more explicit APIs between different parts of your system
- better scalability in CI by enabling independent test/lint/build commands for each package
- most importantly: better caching because changes to one package don't invalidate the cache for unrelated packages

### Create a shared utilities library

Let's create a shared utilities library that both our existing packages can use:

```shell
npx nx g @nx/js:library packages/util --bundler=tsc --unitTestRunner=vitest --linter=none
```

Now we have:

{%filetree %}

- my-nx-repo/
  - packages/
    - animal/
    - util/
    - zoo/
  - ...

{%/filetree %}

Let's add a utility function that our packages can share:

```ts {% meta="{6-12}" %}
// packages/util/src/lib/util.ts
export function util(): string {
  return 'util';
}

export function formatMessage(prefix: string, message: string): string {
  return `[${prefix}] ${message}`;
}

export function getRandomItem<T>(items: T[]): T {
  return items[Math.floor(Math.random() * items.length)];
}
```

### Import the shared library

This allows us to easily import them into other packages. Let's update our `animals` package to use the shared utility:

```ts {% meta="{2,19-21}" %}
// packages/animals/src/lib/animals.ts
import { getRandomItem } from '@org/util';

export function animal(): string {
  return 'animal';
}

export interface Animal {
  name: string;
  sound: string;
}

const animals: Animal[] = [
  { name: 'cow', sound: 'moo' },
  { name: 'dog', sound: 'woof' },
  { name: 'pig', sound: 'oink' },
];

export function getRandomAnimal(): Animal {
  return getRandomItem(animals);
}
```

And update the `zoo` package to use the formatting utility:

```ts {% meta="{3,7,8}" %}
// packages/zoo/src/lib/zoo.ts
import { getRandomAnimal } from '@org/animal';
import { formatMessage } from '@org/util';

export function zoo(): string {
  const result = getRandomAnimal();
  const message = `${result.name} says ${result.sound}!`;
  return formatMessage('ZOO', message);
}
```

Update the dependencies in each package's `package.json`:

```json {% meta="{3-5}" %}
// packages/animal/package.json
{
  "dependencies": {
    "@org/util": "*"
  }
}
```

```json {% meta="{3-6}" %}
// packages/zoo/package.json
{
  "dependencies": {
    "@org/animal": "*",
    "@org/util": "*"
  }
}
```

Link the packages:

```shell
npm install
```

Now when you run `npx nx build zoo`, Nx will automatically build all the dependencies in the correct order: first `util`, then `animal`, and finally `zoo`.

Run the `zoo` package to see the updated output format:

```shell
node packages/zoo/dist/index.js
```

## Visualize your project structure

Nx automatically detects the dependencies between the various parts of your workspace and builds a [project graph](/docs/features/explore-graph). This graph is used by Nx to perform various optimizations such as determining the correct order of execution when running tasks like `npx nx build`, enabling intelligent caching, and more. Interestingly, you can also visualize it.

Just run:

```shell
npx nx graph
```

You should be able to see something similar to the following in your browser.

{% graph height="450px" %}

```json
{
  "projects": [
    {
      "name": "@org/animal",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "@org/util",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "@org/zoo",
      "type": "lib",
      "data": {
        "tags": []
      }
    }
  ],
  "dependencies": {
    "@org/animal": [
      { "source": "@org/animal", "target": "@org/util", "type": "static" }
    ],
    "@org/util": [],
    "@org/zoo": [
      { "source": "@org/zoo", "target": "@org/animal", "type": "static" },
      { "source": "@org/zoo", "target": "@org/util", "type": "static" }
    ]
  },
  "affectedProjectIds": [],
  "focus": null,
  "groupByFolder": false
}
```

{% /graph %}

Let's create a git branch with our new packages so we can open a pull request later:

```shell
git checkout -b add-zoo-packages
git add .
git commit -m 'add animal and zoo packages'
```

## Building and testing - running multiple tasks

Our packages come with preconfigured building and testing . Let's intentionally introduce a typo in our test to demonstrate the self-healing CI feature later.

You can run tests for individual packages:

```shell
npx nx build zoo
```

Or run multiple tasks in parallel across all packages:

```shell
npx nx run-many -t build test
```

This is exactly what is configured in `.github/workflows/ci.yml` for the CI pipeline. The `run-many` command allows you to run multiple tasks across multiple projects in parallel, which is particularly useful in a monorepo setup.

There is a test failure for the `zoo` package due to the updated message. Don't worry about it for now, we'll fix it in a moment with the help of Nx Cloud's self-healing feature.

### Local task cache

One thing to highlight is that Nx is able to [cache the tasks you run](/docs/features/cache-task-results).

Note that all of these targets are automatically cached by Nx. If you re-run a single one or all of them again, you'll see that the task completes immediately. In addition, there will be a note that a matching cache result was found and therefore the task was not run again.

```text {% title="npx nx run-many -t built test" frame="terminal" %}
      ✔  nx run @org/util:build
   ✔  nx run @org/util:test
   ✔  nx run @org/animal:test
   ✔  nx run @org/animal:build
   ✖  nx run @org/zoo:test
   ✔  nx run @org/zoo:build

——————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

 NX   Ran targets test, build for 3 projects (800ms)

   ✔  5/6 succeeded [5 read from cache]

   ✖  1/6 targets failed, including the following:

      - nx run @org/zoo:test
```

Not all tasks might be cacheable though. You can configure the `cache` settings in the `targetDefaults` property of the `nx.json` file. You can also [learn more about how caching works](/docs/features/cache-task-results).

The next section deals with publishing packages to a registry like NPM, but if you are not interested in publishing your packages, you can skip to [the end](#next-steps).

## Manage releases

If you decide to publish your packages to NPM, Nx can help you [manage the release process](/docs/features/manage-releases). Release management involves updating the version of your packages, populating a changelog, and publishing the new version to the NPM registry.

First you'll need to define which projects Nx should manage releases for by setting the `release.projects` property in `nx.json`:

```json {% meta="{4-6}" %}
// nx.json
{
  ...
  "release": {
    "projects": ["packages/*"]
  }
}
```

You'll also need to ensure that each package's `package.json` file sets `"private": false` so that Nx can publish them. If you have any packages that you do not want to publish, make sure to set `"private": true` in their `package.json`.

Now you're ready to use the `nx release` command to publish your packages. The first time you run `nx release`, you need to add the `--first-release` flag so that Nx doesn't try to find the previous version to compare against. It's also recommended to use the `--dry-run` flag until you're sure about the results of the `nx release` command, then you can run it a final time without the `--dry-run` flag.

To preview your first release, run:

```shell
npx nx release --first-release --dry-run
```

The command will ask you a series of questions and then show you what the results would be. Once you are happy with the results, run it again without the `--dry-run` flag:

```shell
npx nx release --first-release
```

After this first release, you can remove the `--first-release` flag and just run `nx release --dry-run`. There is also a [dedicated feature page](/docs/features/manage-releases) that goes into more detail about how to use the `nx release` command.

## Next steps

Here are some things you can dive into next:

- [Set up CI](/docs/getting-started/tutorials/self-healing-ci-tutorial) with remote caching and self-healing
- Learn more about the [underlying mental model of Nx](/docs/concepts/mental-model)
- Learn how to [migrate your existing project to Nx](/docs/guides/adopting-nx/adding-to-existing-project)
- [Learn more about Nx release for publishing packages](/docs/features/manage-releases)
- Learn about [enforcing boundaries between projects](/docs/features/enforce-module-boundaries)

Also, make sure you

- ⭐️ [Star us on GitHub](https://github.com/nrwl/nx) to show your support and stay updated on new releases!
- [Join the Official Nx Discord Server](https://go.nx.dev/community) to ask questions and find out the latest news about Nx.
- [Follow Nx on Twitter](https://twitter.com/nxdevtools) to stay up to date with Nx news
- [Read our Nx blog](https://nx.dev/blog)
- [Subscribe to our Youtube channel](https://www.youtube.com/@nxdevtools) for demos and Nx insights

---
<!-- source: https://nx.dev/docs/getting-started/tutorials/understanding-your-workspace.md -->
## Understanding Your Workspace

{% llm_copy_prompt title="Tutorial 6/8: Explore and debug your workspace" %}
Help me explore and debug my Nx workspace.
Use my existing workspace and projects for hands-on examples.

Run `nx show projects` to list all projects, `nx graph` to visualize dependencies, and `nx show project <project-name>` to inspect task details. Help me understand why specific dependencies exist and debug any caching or configuration issues.

For machine-readable output (useful for scripting or AI agents), use `nx show project <name> --json`.

Stay on-topic: only teach what's covered on this page. Do not introduce concepts from later tutorials.

Tutorial: {pageUrl}
{% /llm_copy_prompt %}

As your workspace grows to dozens or hundreds of projects, you need tools to explore it, debug unexpected behavior, and verify your configuration. Nx provides several commands and visualizations for this.

{% aside type="note" title="Tutorial Series" %}

1. [Crafting your workspace](/docs/getting-started/tutorials/crafting-your-workspace)
2. [Managing dependencies](/docs/getting-started/tutorials/managing-dependencies)
3. [Configuring tasks](/docs/getting-started/tutorials/configuring-tasks)
4. [Running tasks](/docs/getting-started/tutorials/running-tasks)
5. [Caching](/docs/getting-started/tutorials/caching)
6. **Understanding your workspace** (you are here)
7. [Reducing boilerplate](/docs/getting-started/tutorials/reducing-configuration-boilerplate)
8. [Setting up CI](/docs/getting-started/tutorials/self-healing-ci-tutorial)

{% /aside %}

This tutorial assumes you have an Nx workspace with projects and configured tasks. If you're starting fresh, complete [Crafting Your Workspace](/docs/getting-started/tutorials/crafting-your-workspace) first.

## The project graph

The best starting point for understanding your workspace is `nx graph`. It opens an interactive visualization with tabs for projects, tasks, and project details:

```shell
nx graph
```

{% graph title="Project graph" height="400px" %}

```json
{
  "projects": [
    { "type": "app", "name": "my-app", "data": {} },
    { "type": "app", "name": "admin", "data": {} },
    { "type": "app", "name": "api", "data": {} },
    { "type": "lib", "name": "shared-ui", "data": {} },
    { "type": "lib", "name": "data-access", "data": {} },
    { "type": "lib", "name": "auth", "data": {} },
    { "type": "lib", "name": "utils", "data": {} },
    { "type": "lib", "name": "models", "data": {} }
  ],
  "groupByFolder": false,
  "workspaceLayout": { "appsDir": "apps", "libsDir": "packages" },
  "dependencies": {
    "my-app": [
      { "target": "shared-ui", "source": "my-app", "type": "direct" },
      { "target": "data-access", "source": "my-app", "type": "direct" },
      { "target": "auth", "source": "my-app", "type": "direct" }
    ],
    "admin": [
      { "target": "shared-ui", "source": "admin", "type": "direct" },
      { "target": "data-access", "source": "admin", "type": "direct" },
      { "target": "auth", "source": "admin", "type": "direct" }
    ],
    "api": [
      { "target": "data-access", "source": "api", "type": "direct" },
      { "target": "auth", "source": "api", "type": "direct" },
      { "target": "models", "source": "api", "type": "direct" }
    ],
    "shared-ui": [
      { "target": "utils", "source": "shared-ui", "type": "direct" }
    ],
    "data-access": [
      { "target": "models", "source": "data-access", "type": "direct" },
      { "target": "utils", "source": "data-access", "type": "direct" }
    ],
    "auth": [{ "target": "utils", "source": "auth", "type": "direct" }],
    "utils": [],
    "models": []
  },
  "affectedProjectIds": []
}
```

{% /graph %}

The project graph shows every project and the dependencies between them. You can:

- **Search** for specific projects
- **Filter** to show only affected projects or specific groups
- **Click edges** between projects to see which files create the dependency (import statements, `package.json` references)

### Why does this dependency exist?

When you see an unexpected dependency in the graph, click the edge between the two projects. The sidebar shows which files contributed to the dependency:

![Project graph showing @my-workspace/my-app depending on @my-workspace/utils, with the edge selected and the sidebar listing the specific files that create the dependency](../../../../assets/tutorials/project-graph-edge.png)

For scripting, write the graph to a JSON file:

```shell
nx graph --file=/tmp/graph.json
```

## The task graph

Switch to the **Tasks** tab in the graph to visualize the task execution plan. Select a task (like `build`) to see which tasks run and in what order:

![Task graph showing @my-workspace/my-app:build depending on @my-workspace/utils:build, with the arrow indicating utils must build first](../../../../assets/tutorials/task-graph-view.png)

You can also open this directly from the CLI:

```shell
nx build my-app --graph
```

This is useful for verifying that your `dependsOn` configuration is correct. Write the task graph to a file for analysis:

```shell
nx build my-app --graph=/tmp/task-graph.json
```

## Inspecting project details

Click any project in the graph to see its details, or use the CLI:

```shell
nx show project my-app
```

{% project_details title="Project details" %}

```json
{
  "project": {
    "name": "my-app",
    "type": "app",
    "data": {
      "root": "apps/my-app",
      "targets": {
        "build": {
          "options": { "cwd": "apps/my-app", "command": "vite build" },
          "cache": true,
          "dependsOn": ["^build"],
          "inputs": ["production", "^production"],
          "outputs": ["{projectRoot}/dist"],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": { "technologies": ["vite"] }
        },
        "test": {
          "options": { "cwd": "apps/my-app", "command": "vitest run" },
          "cache": true,
          "inputs": ["default", "^production"],
          "outputs": ["{projectRoot}/coverage"],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": { "technologies": ["vite"] }
        }
      },
      "name": "my-app",
      "sourceRoot": "apps/my-app/src",
      "projectType": "application",
      "tags": [],
      "metadata": { "technologies": ["react"] }
    }
  },
  "sourceMap": {
    "root": ["apps/my-app/project.json", "nx/core/project-json"],
    "targets.build": ["apps/my-app/vite.config.ts", "@nx/vite/plugin"],
    "targets.test": ["apps/my-app/vite.config.ts", "@nx/vite/plugin"]
  }
}
```

{% /project_details %}

This shows every task, where its configuration comes from, its `inputs`, `outputs`, and `dependsOn`. To drill into a specific task:

```shell
nx show target my-app:build
```

Add `--json` to either command for machine-readable output.

## Listing projects from the CLI

```shell
nx show projects
```

Filter by criteria:

```shell
# Only projects that have a build target
nx show projects --with-target build

# Only projects matching a pattern
nx show projects --projects 'packages/*'
```

## Debugging cache behavior

If a task isn't caching as expected, inspect its inputs and outputs:

```shell
nx show project my-app
```

Check the task's `inputs`. These are the files and values that contribute to the cache hash. If an input changes between runs, the cache is invalidated. Common causes of unexpected cache misses:

- An untracked config file is included in inputs
- An environment variable changed
- A dependency was updated

{% aside type="tip" title="Enforce correct inputs and outputs" %}
Use [sandboxing](/docs/features/ci-features/sandboxing) to detect tasks that read files not listed in their `inputs` or write files not listed in their `outputs`. This catches configuration mistakes that lead to stale caches or missing artifacts.
{% /aside %}

## Nx Console

[Nx Console](/docs/getting-started/editor-setup) brings all of these capabilities into your editor. In VS Code or WebStorm, you can:

- Browse projects and their targets in a tree view
- View the project graph inline
- Run tasks with a visual interface
- Inspect project details without leaving the editor

{% install_nx_console /%}

## Learn more

- [Explore the graph](/docs/features/explore-graph): full graph exploration guide
- [Mental model](/docs/concepts/mental-model): how Nx thinks about projects and tasks

{% cards cols=2 %}
{% card title="Previous: Caching Tasks" description="Speed up tasks by replaying previous results" url="/docs/getting-started/tutorials/caching" /%}
{% card title="Next: Reducing Configuration Boilerplate" description="Automate task configuration with plugins" url="/docs/getting-started/tutorials/reducing-configuration-boilerplate" /%}
{% /cards %}


# Core Concepts

---
<!-- source: https://nx.dev/docs/concepts.md -->
## Core Concepts

Learn about all the different concepts Nx uses to manage your tasks and enhance your productivity.

{% index_page_cards path="concepts" /%}

---
<!-- source: https://nx.dev/docs/concepts/buildable-and-publishable-libraries.md -->
## Publishable and Buildable Nx Libraries

The `--buildable` and `--publishable` options are available on the Nx library generators for the following plugins:

- Angular
- React
- NestJs
- Node

This document will look to explain the motivations for why you would use either the `--buildable` or `--publishable` option, as well as the mechanics of how they adjust the result when you add them to your generator.

## Publishable libraries

You might use the `--publishable` option when generating a new Nx library if your intention is to distribute it outside the monorepo.

One typical scenario for this may be that you use Nx to develop your organizations UI design system component library (maybe using its Storybook integration), which should be available also to your organizations' apps that are not hosted within the same monorepo.

A normal Nx library - let's call it "workspace library" - is not made for building or publishing. Rather it only includes common lint and test targets in its `project.json` file. These libraries are directly referenced from one of the monorepo's applications and built together with them.

Keep in mind that the `--publishable` flag does not enable automatic publishing. Rather it adds to your Nx workspace library a builder target that **compiles** and **bundles** your app. The resulting artifact will be ready to be published to some registry (e.g. [npm](https://npmjs.com/)). By having that builder, you can invoke the build via a command like: `nx build mylib` (where "mylib" is the name of the lib) which will then produce an optimized bundle in the `dist/mylib` folder.

One particularity when generating a library with `--publishable` is that it requires you to also provide an `--importPath`. Your import path is the actual scope of your distributable package (e.g.: `@myorg/mylib`) - which needs to be a [valid npm package name](https://docs.npmjs.com/files/package.json#name).

To publish the library (for example to npm) you can run the CLI command: `npm publish` from the artifact located in the `dist` directory. Setting up some automated script in Nx `tools` folder may also come in handy.

For more details on the mechanics, remember that Nx is an open source project, so you can see the actual impact of the generator by looking at the source code (the best starting point is probably `packages/<framework>/src/generators/library/library.ts`).

## Buildable libraries

Buildable libraries are similar to "publishable libraries" described above. Their scope however is not to distribute or publish them to some external registry. Thus they might not be optimized for bundling and distribution.

Buildable libraries are mostly used for producing some pre-compiled output that can be directly referenced from an Nx workspace application without the need to again compile it. A typical scenario is to leverage Nx incremental building capabilities.

{% aside type="caution" title="More details" %}
In order for a buildable library to be pre-compiled, it can only depend on other buildable libraries. This allows you to take full advantage of incremental builds.
{% /aside %}

For more details on the mechanics, remember that Nx is an open source project, so you can see the actual impact of the generator by looking at the source code (the best starting point is probably `packages/<framework>/src/generators/library/library.ts`).

---
<!-- source: https://nx.dev/docs/concepts/ci-concepts.md -->
## CI Concepts

{% index_page_cards path="concepts/ci-concepts" /%}

---
<!-- source: https://nx.dev/docs/concepts/ci-concepts/building-blocks-fast-ci.md -->
## Building Blocks of Fast CI

Nx has many features that make your CI faster. Each of these features speeds up your CI in a different way, so that enabling an individual feature will have an immediate impact. These features are also designed to complement each other so that you can use them together to create a fully optimized CI pipeline.

## Use fast build tools

The purpose of a CI pipeline is to run tasks like `build`, `test`, `lint` and `e2e`. You use different tools to run these tasks (like Webpack or Vite for you `build` task). If the individual tasks in your CI pipeline are slow, then your overall CI pipeline will be slow. Nx has two ways to help with this.

Nx provides plugins for popular tools that make it easy to update to the latest version of that tool and [automatically updates](/docs/features/automate-updating-dependencies) your configuration files to take advantage of enhancements in the tool. The tool authors are always looking for ways to improve their product and the best way to get the most out of the tool you're using is to make sure you're on the latest version. Also, the recommended configuration settings for a tool will change over time so even if you're on the latest version of a tool, you may be using a slower version of it because you don't know about a new configuration setting. [`nx migrate`](/docs/features/automate-updating-dependencies) will automatically change the default settings of in your tooling config to use the latest recommended settings so that your repo won't be left behind.

Because Nx plugins have a consistent interface for how they are invoked and how they interact with the codebase, it is easier to try out a different tool to see if it is better than what you're currently using. Newer tools that were created with different technologies or different design decisions can be orders of magnitude faster than your existing tools. Or the new tool might not help your project. Browse through the [list of Nx plugins](/docs/plugin-registry), like [vite](/docs/technologies/build-tools/vite/introduction) or [rspack](/docs/technologies/build-tools/rspack/introduction), and try it out on your project with the default settings already configured for you.

## Reduce wasted time

In a monorepo, most PRs do not affect the entire codebase, so there's no need to run every test in CI for that PR. Nx provides the [`nx affected`](/docs/features/ci-features/affected) command to make sure that only the tests that need to be executed are run for a particular PR.

Even if a particular project was affected by a PR, this could be the third time this same PR was run through CI and the build for this project was already run for this same exact set of files twice before. If you enable [remote caching](/docs/features/ci-features/remote-cache), you can make sure that you never run the same command on the same code twice.

For a more detailed analysis of how these features reduce wasted time in different scenarios, read the [Reduce Wasted Time in CI guide](/docs/concepts/ci-concepts/reduce-waste)

## Parallelize and distribute tasks efficiently

Every time you use Nx to run a task, Nx will attempt to run the task and all its dependent tasks in parallel in the most efficient way possible. Because Nx knows about [task pipelines](/docs/concepts/task-pipeline-configuration), it can run all the prerequisite tasks first. Nx will automatically run tasks in parallel processes up to the limit defined in the `parallel` property in `nx.json`.

There's a limit to how many tasks can be run in parallel on the same machine, but the logic that Nx uses to assign tasks to parallel processes can also be used by Nx Cloud to efficiently [distribute tasks across multiple agent machines](/docs/features/ci-features/distribute-task-execution). Once those tasks are run, the [remote cache](/docs/features/ci-features/remote-cache) is used to replay those task results on the main machine. After the pipeline is finished, it looks like all the tasks were run on a single machine - but much faster than a single machine could do it.

For a detailed analysis of different strategies for running tasks concurrently, read the [Parallelization and Distribution guide](/docs/concepts/ci-concepts/parallelization-distribution)

---
<!-- source: https://nx.dev/docs/concepts/ci-concepts/cache-security.md -->
## Cache Security

{% aside type="caution" title="Use Caution With Read-Write Tokens" %}
Read-write tokens allow full write access to your remote cache. They should only be used in trusted environments. For instance, open source projects should only use read-write tokens as secrets configured for protected branches (e.g, main). Read-only tokens should be used in all other cases.
{% /aside %}

A cache allows you to reuse work that has already been done, but it also introduces a potential security risk - cache poisoning. A poisoned cache is one where the cached files have been altered in some way by a malicious actor. When a developer or the CI pipeline use that poisoned cache, the task output will be what the malicious actor wants instead of the correct task output.

Nx takes security seriously and has put in place many precautions (we're [SOC 2 compliant](https://security.nx.app)). Listed below are some precautions that you need to take in your own codebase.

## What data is sent to the cache?

Nx does not send your actual code to the remote cache. There are 3 kinds of data that are sent to the Nx Cloud remote cache for each task:

1. A hash of the inputs to the task. There is no way to reconstitute the actual source code files that were used to create a particular hash value.
2. Any files that were created as outputs from a task.
3. The terminal output created when running the task.

If a malicious actor were able to modify the cache and those output files were then executed, that malicious actor could run arbitrary code on developer machines or in CI.

## Recommended precautions

In order to keep your cache secure, there are a few steps we recommend you take:

### Use personal access tokens to provide fine-Grained access control for local development

When you use a [personal access token](/docs/guides/nx-cloud/personal-access-tokens) to connect to Nx Cloud, you can control the level of access that your developers have to the cache after they authenticate by logging in. By default, all personal access tokens have read-write access to the cache. If you need to give a developer write access to the cache, you can do so in the workspace settings of the Nx Cloud UI.

You can strengthen your workspace security further by revoking all access to the cache for unauthenticated users. This is done by changing the ID Access Level in your workspace settings. By default this is set to `read-write`, but you can change it to `read-only` to limit access or `none` to prevent all access.

### Avoid using CI access tokens in `nx.json`

Avoid [specifying a token](/docs/guides/nx-cloud/access-tokens) with the `nxCloudAccessToken` property in `nx.json` as they're visible to anyone with codebase access. A `read-write` token grants complete cache write access, enabling potential cache poisoning by unauthorized users. Instead, [restrict CI access tokens](/docs/guides/nx-cloud/access-tokens) to protected CI environments and use [personal access tokens](/docs/guides/nx-cloud/personal-access-tokens) for local development.

### Use scoped tokens in CI

We recommend using a [read-write token](/docs/guides/nx-cloud/access-tokens#read-write-access) only for protected branches (branches that don't allow direct push).
A `read-write` access token allows reading from and writing to the shared global cache of your workspace.

In all other branches, we recommend using a [read-only token](/docs/guides/nx-cloud/access-tokens#read-only-access). A `read-only` token only allows reading from the shared global cache, while writing is limited to an execution specific isolated cache.
This allows your CI pipelines to share computational work between the [distributed agents](/docs/features/ci-features/distribute-task-execution).
For workspaces with an enabled [source control integration with Nx Cloud](/docs/guides/nx-cloud/source-control-integration), we can securely scope the isolated cache to the pull request branch, without opening up the possibility of cache poisoning in your trusted environments. Learn more about [access token architecture](/docs/guides/nx-cloud/access-tokens#setting-ci-access-tokens).

### No need to revoke tokens after employees leave

When an employee leaves a company, it is standard practice to change all the passwords that they had access to. That is not necessary for Nx Cloud tokens. In order to poison the cache, the former employee would need to have both the read-write token and the current code on the latest commit on the `main` branch. The odds of the employee being able to guess the hash value that will be created for the current commit on the `main` branch are infinitesimally small even after a single commit.

### Skip the cache when creating a deployment artifact

In order to guarantee that cache poisoning will never affect your end users, [skip the cache](/docs/guides/tasks--caching/skipping-cache) when creating build artifacts that will actually be deployed. Skipping the cache for this one CI run is a very small performance cost, but it gives you 100% confidence that cache poisoning will not be an issue for the end users.

### Do not manually share your local cache

Nx implicitly trusts the local cache which is stored by default in the `.nx/cache` folder. You can change the location of that folder in the `nx.json` file, so it could be tempting to place it on a network drive and easily share your cache with everyone on the company network. However, by doing this you've voided the guarantee of immutability from your cache. If someone has direct access to the cached files, they could directly poison the cache. Nx will automatically detect if a cache entry has been created in your local cache using a different machine and warn you with an [Unknown Local Cache Error](/docs/troubleshooting/unknown-local-cache). Instead, use Nx Cloud [remote caching](/docs/features/ci-features/remote-cache). If you want share your local cache anyway, you can use the [`@nx/shared-fs-cache`](/docs/reference/remote-cache-plugins/shared-fs-cache) plugin.

### Configure end to end encryption

Nx Cloud guarantees your cache entries will remain immutable - once they've been registered they can't be changed. This is guaranteed because the only way to access the cache is through the Nx Cloud API and we have policies enabled in our cloud storage that specifically disables overwrites and deletions of cached artifacts. But what if a hacker were somehow able make their way into the server holding the cache artifacts? Since you set up [end to end encryption](/docs/guides/nx-cloud/encryption), the files they see on disk will be fully encrypted with a key that only exists in your workspace.

### Use an on-Premise version of Nx Cloud if needed

If you need to have all cache artifacts on servers that you control, there is an on-premise version of Nx Cloud that you can use as part of the [Enterprise plan](https://nx.dev/enterprise).

## Security decisions

In any security discussion, there is a trade off between convenience and security. It could be that some of these threats do not apply to your organization. If that is the case you could relax some of the security precautions and gain the performance benefits of more task results being stored in the remote cache. Every organization is different and Nx can be adapted to best meet your needs without opening up vulnerabilities. If you would Nx team members to help your organization fine tune your set up, [talk to us about Nx Enterprise](https://nx.dev/enterprise).

---
<!-- source: https://nx.dev/docs/concepts/ci-concepts/heartbeat-and-manual-shutdown-handling.md -->
## Heartbeat and Main Job Completion Handling

### What is the heartbeat process?

A big challenge in building a task distribution engine is tracking when the main orchestrator job has finished (either successfully or due to an error).
For example, your agents might be busy running your Nx tasks, but GitHub Actions suddenly decides to kill your main job because it is consuming too many resources.
In that case, regardless of how you configured your pipeline or how many shutdown hooks we add to the code, we simply do not have enough time to tell Nx Cloud it can stop running tasks on agents.

To fix this, the first time you run `nx` commands, we create a small background process on your main job that pings Nx Cloud every few seconds. The moment
we stop receiving these pings, we assume the main job has died, and we will fail the CI run and shut down the agents.

This is useful not just for worst-case scenarios, but it also keeps your CI config simple:

```yaml
- run: npx nx start-ci-run --distribute-on="5 linux-medium-js" # start agents and tell Nx to send the below affected tasks to NxCloud rather than execute in-place
- run: npm ci
- run: npx nx affected -t build,lint,test
# That's it - we don't need an extra step to tell NxCloud that we're done running Nx commands.
```

👆In the above case, once all the `affected` commands are executed and the main job shuts down, the heartbeat process will stop the pings. So, we'll assume the main job finished, and we can turn off the agents.

In summary, for 99% of cases, you will never have to think about the heartbeat or care that it exists. Your CI will just work.

### Caveats

In some specific cases, though, the heartbeat process will not work properly. In that case, you will need to [manage completion yourself](/docs/reference/nx-cloud-cli#requireexplicitcompletion):

```yaml
- run: npx nx start-ci-run --distribute-on="5 linux-medium-js" --require-explicit-completion # this option disables the heartbeat
- run: npm ci
- run: npx nx affected -t build,lint,test
- run: npx nx complete-ci-run # this now tells NxCloud to turn off the agents
  if: always() # IMPORTANT: Always run, even in case of failures
```

When you might need to do this:

#### CI provider unexpectedly cleans up background processes

We've noticed that some CI providers tend to be more aggressive with background process management when moving between steps. Assume you have the following configuration:

```yaml
- run: npx nx start-ci-run --distribute-on="5 linux-medium-js"
- run: npm ci
- run: npx nx affected -t build,lint,test # This is the point where we turn on the heartbeat.
- run: ./deploy-my-projects.sh
- run: ./publish-test-results-to-sonarqube
- run: npx nx affected -t e2e
```

👆Notice how after running `npx nx affected -t build,lint,test`, we are doing some other work (deploying the projects, uploading test results, etc.). We've seen
some CI providers occasionally clean up background processes when moving between steps. So, if you see your main job failing when it gets to the `npx nx affected -t e2e` tests,
it might be because Nx Cloud thought the distribution had ended already, and it didn't accept any new Nx tasks.

The heartbeat process is especially vulnerable during these "transition phases" between steps.

To fix this, you can either manage completion explicitly (as mentioned above) or move all your Nx tasks into a single step or `nx` command. Both would fix the issue.

#### Multi-job pipelines with different stages

GitHub Actions supports defining dependencies between jobs. This allows you to create pipelines that spin up multiple machines at different stages, but that still run as part of the same overall "workflow".
Other providers allow you to do this too.

For example, you might want to:

1.  Spin up a job that runs some quick tasks such as formatting and linting.
2.  Once that's finished, create three machines for building and testing your app on Linux, macOS, and Windows.
3.  Finally, once those three machines finish, spin up a machine that deploys your app.

If Nx Cloud doesn't hear back from the heartbeat after a few seconds, it assumes something went wrong and fails the workflow.
When moving from one stage to the next, you need to turn off the first machine and wait for the next machines to boot up and start their heartbeats. This can cause you to go over the heartbeat threshold.

{% aside type="caution" title="Multi Machine/Job workflows" %}
Workflows involving multiple machines/jobs are the main source of heartbeat-related issues, simply because of how long it usually takes to restart the heartbeat after shutting it down.

{% /aside %}

The only fix in this scenario is to handle completion yourself and run `npx nx complete-ci-run` as the last command on your last machine in the pipeline.

### Heartbeat vs. `--stop-agents-after`

While both the heartbeat and `--stop-agents-after` tell Nx Cloud when it can shut down agents, they have different roles:

1.  `--stop-agents-after` is useful purely to avoid wasting unnecessary compute.
    - So, while you might still have agents actively running tasks, Nx Cloud can tell that you won't be sending it any more tasks in the future because of how you configured `--stop-agents-after`.
    - So, it can turn off any agents that are no longer running tasks.
    - [Read more about configuring `--stop-agents-after`](/docs/reference/nx-cloud-cli#stopagentsafter).
2.  The heartbeat, on the other hand, marks the completion of the main job.
    - It makes sure Nx Cloud instantly knows when the main job exited so it can update the status of its CI run.
    - In case of errors, it makes sure that it can instantly abandon any in-progress tasks.

---
<!-- source: https://nx.dev/docs/concepts/ci-concepts/parallelization-distribution.md -->
## Parallelization and Distribution

Nx speeds up your CI in several ways. One method is to reduce wasted calculations with the [affected command](/docs/features/ci-features/affected) and [remote caching](/docs/features/ci-features/remote-cache). No matter how effective you are at eliminating wasted calculations in CI, there will always be some tasks that really do need to be executed and sometimes that list of tasks will be everything in the repository.

To speed up the essential tasks, Nx [efficiently orchestrates](/docs/concepts/task-pipeline-configuration) the tasks so that prerequisite tasks are executed first, but independent tasks can all be executed concurrently. Running tasks concurrently can be done with parallel processes on the same machine or distributed across multiple machines.

## Parallelization

Any time you execute a task, Nx will parallelize as much as possible. If you run `nx build my-project`, Nx will build the dependencies of that project in parallel as much as possible. If you run `nx run-many -t build` or `nx affected -t build`, Nx will run all the specified tasks and their dependencies in parallel as much as possible.

Nx will limit itself to the maximum number of parallel processes set in the `parallel` property in `nx.json`. To set that limit to `2` for a specific command, you can specify `--parallel=2` in the terminal. This flag works for individual tasks as well as `run-many` and `affected`.

Unfortunately, there is a limit to how many processes a single computer can run in parallel at the same time. Once you hit that limit, you have to wait for all the tasks to complete.

#### Pros and cons of using a single machine to execute tasks on parallel processes:

| Characteristic | Pro/Con | Notes                                                                            |
| -------------- | ------- | -------------------------------------------------------------------------------- |
| Complexity     | 🎉 Pro  | The pipeline uses the same commands a developer would use on their local machine |
| Debuggability  | 🎉 Pro  | All build artifacts and logs are on a single machine                             |
| Speed          | ⛔️ Con | The larger a repository gets, the slower your CI will be                         |

## Distribution across machines

Once your repository grows large enough, it makes sense to start using multiple machines to execute tasks in CI. This adds some extra cost to run the extra machines, but the cost of running those machines is much less than the cost of paying developers to sit and wait for CI to finish.

You can either distribute tasks across machines manually, or use Nx Cloud distributed task execution to automatically assign tasks to machines and gather the results back to a single primary machine. When discussing distribution, we refer to the primary machine that determines which tasks to run as the main machine (or job). The machines that only execute the tasks assigned to them are called agent machines (or jobs).

### Manual distribution

One way to manually distribute tasks is to use binning. Binning is a distribution strategy where there is a main job that divides the work into bins, one for each agent machine. Then every agent executes the work prepared for it. Here is a simplified version of the binning strategy.

```yaml
// main-job.yml
# Get the list of affected projects
- nx show projects --affected --json > affected-projects.json
# Store the list of affected projects in a PROJECTS environment variable
# that is accessible by the agent jobs
- node storeAffectedProjects.js
```

```yaml
// lint-agent.yml
# Run lint for all projects defined in PROJECTS
- nx run-many --projects=$PROJECTS -t lint
```

```yaml
// test-agent.yml
# Run test for all projects defined in PROJECTS
- nx run-many --projects=$PROJECTS -t test
```

```yaml
// build-agent.yml
# Run build for all projects defined in PROJECTS
- nx run-many --projects=$PROJECTS -t build
```

Here's a visualization of how this approach works:
![CI using binning](../../../../assets/concepts/ci-concepts/binning.svg)

This is faster than the single machine approach, but you can see that there is still idle time where some agents have to wait for other agents to finish their tasks.

There's also a lot of complexity hidden in the idle time in the graph. If `test-agent` tries to run a `test` task that depends on a `build` task that hasn't been completed yet by the `build-agent`, the `test-agent` will start to run that `build` task without pulling it from the cache. Then the `build-agent` might start to run the same `build` task that the `test-agent` is already working on. Now you've reintroduced waste that remote caching was supposed to eliminate.

It is possible in a smaller repository to manually calculate the best order for tasks and encode that order in a script. But that order will need to be adjusted as the repository structure changes and may even be suboptimal depending on what projects were affected in a given PR.

#### Pros and cons of manually distributing tasks across multiple machines:

| Characteristic | Pro/Con | Notes                                                                                                               |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| Complexity     | ⛔️ Con | You need to write custom scripts to tell agent machines what tasks to execute. Those scripts need to be maintained. |
| Debuggability  | ⛔️ Con | Build artifacts and logs are scattered across agent machines.                                                       |
| Speed          | 🎉 Pro  | Faster than using a single machine                                                                                  |

### Distributed task execution using Nx Agents

When you use **Nx Agents** (feature of Nx Cloud) you gain even more speed than manual distribution while preserving the simple set up and easy debuggability of the single machine scenario.

The setup looks like this:

```yaml
// main-job.yml
# Coordinate the agents to run the tasks and stop agents when the build tasks are done
- npx nx start-ci-run --distribute-on="8 linux-medium-js" --stop-agents-after=build
# Run any commands you want here
- nx affected -t lint test build
```

The visualization looks like this:
![CI using Agents](../../../../assets/concepts/ci-concepts/3agents.svg)

In the same way that Nx efficiently assigns tasks to parallel processes on a single machine so that pre-requisite tasks are executed first, Nx Cloud's distributed task execution efficiently assigns tasks to agent machines so that the idle time of each agent machine is kept to a minimum. Nx performs these calculations for each PR, so no matter which projects are affected or how your project structure changes, Nx will optimally assign tasks to the agents available.

#### Pros and cons of using Nx Cloud's distributed task execution:

| Characteristic | Pro/Con | Notes                                                                                                                           |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Complexity     | 🎉 Pro  | The pipeline uses the same commands a developer would use on their local machine, but with one extra line before running tasks. |
| Debuggability  | 🎉 Pro  | Build artifacts and logs are collated to the main machine as if all tasks were executed on that machine                         |
| Speed          | 🎉 Pro  | Fastest possible task distribution for each PR                                                                                  |

## Conclusion

If your repo is starting to grow large enough that CI times are suffering, or if your parallelization strategy is growing too complex to manage effectively, try [setting up Nx Agents](/docs/features/ci-features/distribute-task-execution). You can [generate a simple workflow](/docs/reference/workspace/generators#ci-workflow) for common CI providers with a `nx g ci-workflow` or follow one of the [CI setup recipes](/docs/guides/nx-cloud/setup-ci).

Organizations that want extra help setting up Nx Cloud or getting the most out of Nx can [sign up for Nx Enterprise](https://nx.dev/enterprise). This package comes with extra support from the Nx team and the option to host Nx Cloud on your own servers.

---
<!-- source: https://nx.dev/docs/concepts/ci-concepts/reduce-waste.md -->
## Reduce Wasted Time in CI

This article explores two ways that Nx improves the average speed of your CI pipeline - `nx affected` and remote caching. Using the `nx affected` command speeds up the first CI run for a PR and remote caching speeds up every CI run after that. Both `nx affected` and remote caching provide more benefits to repositories with more projects and a flatter project structure.

For this discussion, we'll assume you understand the Nx [mental model](/docs/concepts/mental-model) and have an understanding of both [what the affected command is](/docs/features/ci-features/affected) and [how caching works](/docs/concepts/how-caching-works).

## Reduce wasted time with affected

The `nx affected` command allows you to only run tasks on projects that were affected by a particular PR. This effectively eliminates the wasted time and resources that would have been spent executing tasks on projects that were unrelated to a particular PR.

How much benefit you gain from this is different for each repository, but there a few general principles that you can keep in mind as you're assessing the value of the Nx affected command for your repository. You can also use these principles to help inform your architecture decisions as you try to improve the performance of your CI system.

### Repos with more projects gain more value from affected

If we look at these two trivial examples, you can see that the repository with more projects gains more value from the affected command.

{% graph title="One Project" height="200px" %}

```json
{
  "hash": "85fd0561bd88f0bcd8703a9e9369592e2805f390d04982fb2401e700dc9ebc59",
  "projects": [
    {
      "name": "project1",
      "type": "lib",
      "data": {
        "tags": []
      }
    }
  ],
  "dependencies": {
    "project1": [],
    "project2": [],
    "project3": []
  },
  "workspaceLayout": { "appsDir": "apps", "libsDir": "libs" },
  "affectedProjectIds": ["project1"],
  "focus": null,
  "groupByFolder": false,
  "exclude": []
}
```

{% /graph %}

{% graph title="Four Projects" height="200px" %}

```json
{
  "hash": "85fd0561bd88f0bcd8703a9e9369592e2805f390d04982fb2401e700dc9ebc59",
  "projects": [
    {
      "name": "project1",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "project2",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "project3",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "project4",
      "type": "lib",
      "data": {
        "tags": []
      }
    }
  ],
  "dependencies": {
    "project1": [],
    "project2": [],
    "project3": [],
    "project4": []
  },
  "workspaceLayout": { "appsDir": "apps", "libsDir": "libs" },
  "affectedProjectIds": ["project1"],
  "focus": null,
  "groupByFolder": false,
  "exclude": []
}
```

{% /graph %}

In the one project example, every PR will affect the entire repository. In the four project example, modifying one project only affects 25% of the repository. For the one project repository `nx affected -t build` is identical to `nx run-many -t build`, whereas for the four project repository, `nx affected -t build` cuts out the 75% of wasted work.

With this principle in mind, you can add more applications to the repository to gain the [benefits of a monorepo](https://monorepo.tools) without suffering an exponential increase in CI execution time. This principle also encourages splitting projects into multiple projects in order to have a faster CI pipeline for the existing applications.

### Flatter repos gain more value from affected

Consider the following example repo structures.

{% graph title="Stacked" height="350px" %}

```json
{
  "hash": "85fd0561bd88f0bcd8703a9e9369592e2805f390d04982fb2401e700dc9ebc59",
  "projects": [
    {
      "name": "project1",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "project2",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "project3",
      "type": "lib",
      "data": {
        "tags": []
      }
    }
  ],
  "dependencies": {
    "project1": [{ "source": "project1", "target": "project2" }],
    "project2": [{ "source": "project2", "target": "project3" }],
    "project3": []
  },
  "workspaceLayout": { "appsDir": "apps", "libsDir": "libs" },
  "affectedProjectIds": [],
  "focus": null,
  "groupByFolder": false,
  "exclude": []
}
```

{% /graph %}

{% graph title="Grouped" height="200px" %}

```json
{
  "hash": "85fd0561bd88f0bcd8703a9e9369592e2805f390d04982fb2401e700dc9ebc59",
  "projects": [
    {
      "name": "project1",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "project2",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "project3",
      "type": "lib",
      "data": {
        "tags": []
      }
    }
  ],
  "dependencies": {
    "project1": [{ "source": "project1", "target": "project3" }],
    "project2": [{ "source": "project2", "target": "project3" }],
    "project3": []
  },
  "workspaceLayout": { "appsDir": "apps", "libsDir": "libs" },
  "affectedProjectIds": [],
  "focus": null,
  "groupByFolder": false,
  "exclude": []
}
```

{% /graph %}

{% graph title="Flat" height="200px" %}

```json
{
  "hash": "85fd0561bd88f0bcd8703a9e9369592e2805f390d04982fb2401e700dc9ebc59",
  "projects": [
    {
      "name": "project1",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "project2",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "project3",
      "type": "lib",
      "data": {
        "tags": []
      }
    }
  ],
  "dependencies": {
    "project1": [],
    "project2": [],
    "project3": []
  },
  "workspaceLayout": { "appsDir": "apps", "libsDir": "libs" },
  "affectedProjectIds": [],
  "focus": null,
  "groupByFolder": false,
  "exclude": []
}
```

{% /graph %}

If we assume that each project has an independent 50% chance of being modified on a given PR, we can calculate the expected average number of affected projects. Intuitively, the flat structure should have less affected projects than the stacked structure and the grouped structure should fall somewhere in between. That is, in fact, the case.

If we don't use the `nx affected` command in CI, no matter how our repo is structured, the expected number of projects run in CI will be 3 - all of them.

| Repo Structure | Expected Number of Affected Projects |
| -------------- | ------------------------------------ |
| Stacked        | 2.125                                |
| Grouped        | 2                                    |
| Flat           | 1.5                                  |

Note that the 50% chance of any project being modified is an arbitrary number. If we had picked a lower chance of being modified all the expected values would decrease as well. Every repository is different, but this illustrates that a flatter structure will help speed up your CI pipeline.

{% callout title="The Math Behind the Expected Number of Affected Projects" type="deepdive" %}

**Definitions:**

ℙm(1) means the probability project 1 was modified  
ℙm'(1) means the probability project 1 was not modified  
ℙa(1) means the probability project 1 was affected

**Given:**

ℙm(1) = ℙm(2) = ℙm(3) = 0.5

**Stacked:**

ℙa(1) = ℙm(1) + ℙm'(1) \* ℙm(2) + ℙm'(1) \* ℙm'(2) \* ℙm(3) = 0.5 + 0.25 + 0.125 = 0.875  
ℙa(2) = ℙm(2) + ℙm'(2) \* ℙm(3) = 0.5 + 0.25 = 0.75  
ℙa(3) = ℙm(3) = 0.5 = 0.5

**Expected Number of Affected Projects:**  
ℙa(1) + ℙa(2) + ℙa(3) = 0.875 + 0.75 + 0.5 = 2.125

**Grouped:**

ℙa(1) = ℙm(1) + ℙm'(1) \* ℙm(3) = 0.5 + 0.25 = 0.75  
ℙa(2) = ℙm(2) + ℙm'(2) \* ℙm(3) = 0.5 + 0.25 = 0.75  
ℙa(3) = ℙm(3) = 0.5 = 0.5

**Expected Number of Affected Projects:**  
ℙa(1) + ℙa(2) + ℙa(3) = 0.75 + 0.75 + 0.5 = 2

**Flat:**

ℙa(1) = ℙm(1) = 0.5 = 0.5  
ℙa(2) = ℙm(2) = 0.5 = 0.5  
ℙa(3) = ℙm(3) = 0.5 = 0.5

**Expected Number of Affected Projects:**  
ℙa(1) + ℙa(2) + ℙa(3) = 0.5 + 0.5 + 0.5 = 1.5

{% /callout %}

## Reduce wasted time with remote caching

If you use a read/write token on developer machines, CI runs could be dramatically improved because they would be leveraging the work already done on the machine of the developer that pushed the PR. This set up requires you to have full trust in everyone who is capable of viewing the code base, which doesn't make sense for open source projects or for many organizations.

Remote caching is still valuable when only the CI pipelines have a read/write token.

### Remote caching begins helping on the second CI run for a pipeline

The first time CI runs for a particular PR, affected is doing most of the work to speed up your CI run. It is rare for a task to be cached on the first run. However, if the PR doesn't pass in CI, or if you need to make a change for some reason, subsequent runs of that same PR will be able to reuse cached tasks for you.

Take a look at the example below. The projects are setup in the suboptimal stacked arrangement from before. On the first CI run, `project3` was modified, so every project is affected. Then the developer realizes that `project2` should be changed as well and pushes a new commit. For the second CI run, every project is still affected when compared against the `main` branch, but `project3` hasn't changed between the first CI run and the second, so the cache from the first CI run can be used instead of re-running that task. `project2` tasks need to be re-run since it was modified and `project1` tasks need to be re-run since it depends on a project that was modified.

{% graph title="First CI Run" height="300px" %}

```json
{
  "hash": "85fd0561bd88f0bcd8703a9e9369592e2805f390d04982fb2401e700dc9ebc59",
  "projects": [
    {
      "name": "project1",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "project2",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "project3",
      "type": "lib",
      "data": {
        "tags": []
      }
    }
  ],
  "dependencies": {
    "project1": [{ "source": "project1", "target": "project2" }],
    "project2": [{ "source": "project2", "target": "project3" }],
    "project3": []
  },
  "workspaceLayout": { "appsDir": "apps", "libsDir": "libs" },
  "affectedProjectIds": ["project1", "project2", "project3"],
  "focus": null,
  "groupByFolder": false,
  "exclude": []
}
```

{% /graph %}

{% graph title="Second CI Run (project2 Changed)" height="300px" %}

```json
{
  "hash": "85fd0561bd88f0bcd8703a9e9369592e2805f390d04982fb2401e700dc9ebc59",
  "projects": [
    {
      "name": "project1 ↩︎",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "project2 ↩︎",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "project3 ✓",
      "type": "lib",
      "data": {
        "tags": []
      }
    }
  ],
  "dependencies": {
    "project1 ↩︎": [{ "source": "project1 ↩︎", "target": "project2 ↩︎" }],
    "project2 ↩︎": [{ "source": "project2 ↩︎", "target": "project3 ✓" }],
    "project3 ✓": []
  },
  "workspaceLayout": { "appsDir": "apps", "libsDir": "libs" },
  "affectedProjectIds": ["project1 ↩︎", "project2 ↩︎", "project3 ✓"],
  "focus": null,
  "groupByFolder": false,
  "exclude": []
}
```

{% /graph %}

### Caching provides more value when there are more projects and a flatter structure

The exact same reasoning that lead us to encourage more projects and a flatter structure to gain value from the affected command, also applies to caching.

If there is a single project in a repo, the cache will be broken on 100% of changes. If there are 4 unconnected projects, changing one project, allows you to use the cache for the other 3 projects.

Just as modifying a project makes projects that depend on it be `affected`, modifying a project also breaks the cache for projects that depend on it.

---
<!-- source: https://nx.dev/docs/concepts/decisions.md -->
## Architectural Decisions

{% index_page_cards path="concepts/decisions" /%}

---
<!-- source: https://nx.dev/docs/concepts/decisions/code-ownership.md -->
## Code Ownership

One of the most obvious benefits of having a monorepo is that you can easily share code across projects. This enables you to apply the Don't Repeat Yourself principle across the whole codebase. Code sharing could mean using a function or a component in multiple projects. Or code sharing could mean using a typescript interface to define the network API interface for both the front end and back end applications.

Code sharing is usually a good thing, but it can cause problems.

## Too much sharing

If everyone can use and modify every piece of code, you can run into problems:

### Devs modifying another team's code

Another team can add complexity to code that your team maintains to satisfy their one use case. This adds an extra burden on you and may make it difficult to adapt that piece of code for other use cases. This can be solved by using a CODEOWNERS file that explicit defines which people in an organization need to approve PRs that touch a particular section of the codebase.

### Outside devs using internal code

Another team can use a piece of code that is intended to be internal to your project. Now if you change that piece of code, their project is broken. So your team is either locked in to that API or you have to solve problems in another team's project. To solve this, Nx provides a lint rule `enforce-module-boundaries` that will throw an error if a project imports code that is not being exported from the `index.ts` file at the root of a library. Now the `index.ts` file is the definitive published API for that library.

### Projects depending on the wrong libraries

Libraries with presentational components can accidentally use code from a library that holds a data store. Projects with Angular code can accidentally use code from a React project. Projects from team A could accidentally use code in projects that are intended to be only for team B. These kinds of rules will vary based on the organisation, but they can all be enforced automatically using tags and the `enforce-module-boundaries` lint rule.

## Defining code ownership

As more teams are contributing to the same repository, it becomes crucial to establish clear code ownership.

Since Nx allows us to place projects in any directory structure, those directories can become code-ownership boundaries. That's
why the structure of an Nx workspace often reflects the structure of an organization. GitHub users can use
the `CODEOWNERS` file for that.

```plaintext
/libs/happynrwlapp          julie-happynrwlapp-lead
/apps/happynrwlapp          julie-happynrwlapp-lead
/libs/shared/ui             hank-the-ui-guy
/libs/shared/utils-testing  julie,hank
```

If you want to know more about code ownership on GitHub, please
check [the documentation on the `CODEOWNERS` file](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners).

---
<!-- source: https://nx.dev/docs/concepts/decisions/dependency-management.md -->
## Dependency Management Strategies

When working with a monorepo, one of the key architectural decisions is how to manage dependencies across your projects. This document outlines two main strategies and helps you choose the right approach for your team.

The core decision comes down to:

1. Independently maintained dependencies in individual projects
2. A "single version policy", where dependencies are defined once at the root for your entire monorepo

**Nx fully supports both strategies - it's your choice and you can change your approach as your needs evolve, you are never locked in**. You can even mix these strategies, using a single version policy for most dependencies while allowing specific projects to maintain their own versions when necessary. Thanks to its smart dependency graph analysis, Nx can trace dependencies used by different projects and can therefore avoid unnecessary cache misses even when a root level lockfile changes, so that is not a concern.

Let's examine the trade-offs of each approach, using JavaScript/TypeScript as our primary example (though these principles apply to other languages as well):

## Independently maintained dependencies

In this model, each project maintains its own dependency definitions. For JavaScript/TypeScript projects, this means each project has its own `package.json` file specifying runtime dependencies, with development dependencies often still living at the root of the workspace (although they can also be specified at the project level). During builds, each project's bundler includes the necessary dependencies in its final artifact. Dependencies are typically managed using package manager workspaces (npm/yarn/pnpm/bun).

While this approach offers flexibility, it can introduce complexity when sharing code between projects. For example, if `project1` and `project2` use different versions of React, what happens when they try and share components? This can lead to runtime issues that are difficult to detect during development and challenging to debug in production.

A common pitfall occurs when developers have one version of a dependency in the root `node_modules` but a different version specified in their project's `package.json`. This can result in code that works locally but fails in production where the bundled version is used.

**Pros:**

- Teams can independently choose and upgrade their dependencies
- More immediately clear what dependencies are intended for each project
- Easier transition for teams new to monorepos
- Modern tooling around e.g. module federation can help mitigate some of the challenges within applications

**Cons:**

- Complicates deployment when projects share runtime dependencies
- Makes code sharing between projects more challenging
- Can lead to hard-to-detect runtime conflicts
- Increases maintenance and strategy overhead with multiple versions to track

## Single version policy

This strategy centralizes all dependency definitions in the root `package.json` file, ensuring consistent versions across your codebase. While individual projects may still maintain their own `package.json` files for development purposes, the root configuration serves as the single source of truth for versions.

For building and deployment, you'll need to ensure each project only includes its relevant dependencies. Nx helps manage this through its workspace dependency graph and the `@nx/dependency-checks` ESLint rule, which can automatically detect and fix dependency mismatches between project and root configurations.

The main challenge with this approach is coordinating dependency updates across independent teams. When multiple teams work on different, or even the same, applications within the same repo, they need to align on dependency upgrades. While this requires more coordination, it often results in less total work - upgrading a dependency once across all projects is typically more efficient than managing multiple separate upgrades over time.

{% aside type="tip" title="Dependency Catalog Support" %}

When using pnpm or Yarn, use [pnpm catalogs](https://pnpm.io/catalogs) or [Yarn catalogs](https://yarnpkg.com/features/catalogs) to maintain single version policy. Define versions in `pnpm-workspace.yaml` or `.yarnrc.yml` respectively and reference them as `"<package>": "catalog:"` in project `package.json` files (Nx 22+ for pnpm and Nx 22.6+ for Yarn).

{% /aside %}

**Pros:**

- Ensures consistent dependency versions, preventing runtime conflicts
- Simplifies code sharing between projects
- Makes workspace-wide updates more manageable and easier to track

**Cons:**

- Requires coordination between teams for dependency updates
- May slow down teams that need to move at different velocities
- Needs stronger governance and communication processes

For details on using Nx dependency graph in your deployment process, see our guide on [preparing applications for deployment via CI](/docs/guides/ci-deployment).

---
<!-- source: https://nx.dev/docs/concepts/decisions/folder-structure.md -->
## Folder Structure

Nx can work with any folder structure you choose, but it is good to have a plan in place for the folder structure of your monorepo.

Projects are often grouped by _scope_. A project's scope is either the application to which it belongs or (for larger applications) a section within that application.

## Move generator

Don't be too anxious about choosing the exact right folder structure from the beginning. Projects can be moved or renamed using the [`@nx/workspace:move` generator](/docs/reference/workspace/generators#move).

For instance, if a project under the `booking` folder is now being shared by multiple apps, you can move it to the shared folder like this:

```shell
nx g move --project booking-some-project shared/some-project
```

## Remove generator

Similarly, if you no longer need a project, you can remove it with the [`@nx/workspace:remove` generator](/docs/reference/workspace/generators#remove).

```shell
nx g remove booking-some-project
```

## Example workspace

Let's use Nrwl Airlines as an example organization. This organization has two apps, `booking` and `check-in`. In the Nx workspace, projects related to `booking` are grouped under a `libs/booking` folder, projects related to `check-in` are grouped under a `libs/check-in` folder and projects used in both applications are placed in `libs/shared`. You can also have nested grouping folders, (i.e. `libs/shared/seatmap`).

The purpose of these folders is to help with organizing by scope. We recommend grouping projects together which are (usually) updated together. It helps minimize the amount of time a developer spends navigating the folder tree to find the right file.

{% filetree %}

- apps/
  - booking/
  - check-in/
- libs/
  - booking/ <---- grouping folder
    - feature-shell/ <---- project
  - check-in/
    - feature-shell/
  - shared/ <---- grouping folder
    - data-access/ <---- project
    - seatmap/ <---- grouping folder
      - data-access/ <---- project
      - feature-seatmap/ <---- project

{% /filetree %}

## Sharing projects

One of the main advantages of using a monorepo is that there is more visibility into code that can be reused across many different applications. Shared projects are a great way to save developers time and effort by reusing a solution to a common problem.

Let's consider our reference monorepo. The `shared-data-access` project contains the code needed to communicate with the back-end (for example, the URL prefix). We know that this would be the same for all libs; therefore, we should place this in the shared lib and properly document it so that all projects can use it instead of writing their own versions.

{% filetree %}

- libs/
  - booking/
    - data-access/ <---- app-specific project
  - shared/
    - data-access/ <---- shared project
    - seatmap/
      - data-access/ <---- shared project
      - feature-seatmap/ <---- shared project

{% /filetree %}

---
<!-- source: https://nx.dev/docs/concepts/decisions/overview.md -->
## Monorepo or Polyrepo

Monorepos have a lot of benefits, but there are also some costs involved. We feel strongly that the [technical challenges](/docs/concepts/decisions/why-monorepos) involved in maintaining large monorepos are fully addressed through the efficient use of Nx and Nx Cloud. Rather, the limiting factors in how large your monorepo grows are interpersonal.

In order for teams to work together in a monorepo, they need to agree on how that repository is going to be managed. These questions can be answered in many different ways, but if the developers in the repository can't agree on the answers, then they'll need to work in separate repositories.

**Organizational Decisions:**

- [Dependency Management](/docs/concepts/decisions/dependency-management) - Should there be an enforced single version policy or should each project maintain their own dependency versions independently?
- [Code Ownership](/docs/concepts/decisions/code-ownership) - What is the code review process? Who is responsible for reviewing changes to each portion of the repository?
- [Project Dependency Rules](/docs/concepts/decisions/project-dependency-rules) - What are the restrictions on dependencies between projects? Which projects can depend on which other projects?
- [Folder Structure](/docs/concepts/decisions/folder-structure) - What is the folder structure and naming convention for projects in the repository?
- [Project Size](/docs/concepts/decisions/project-size) - What size should projects be before they need to be split into separate projects?
- Git Workflow - What Git workflow should be used? Will you use trunk-based development or long running feature branches?
- CI Pipeline - How is the CI pipeline managed? Who is responsible for maintaining it?
- Deployment - How are deployments managed? Does each project deploy independently or do they all deploy at once?

## How many repositories?

Once you have a good understanding of where people stand on these questions, you'll need to choose between one of the following setups:

### One monorepo to rule them all

If everyone can agree on how to run the repository, having [a single monorepo will provide a lot of benefits](/docs/concepts/decisions/why-monorepos). Every project can share code and maintenance tasks can be performed in one PR for the entire organization. Any task that involves coordination becomes much easier.

Once the repository scales to hundreds of developers, you need to take proactive steps to ensure that your decisions about [code review](/docs/concepts/decisions/code-ownership) and [project dependency restrictions](/docs/features/enforce-module-boundaries) do not inhibit the velocity of your teams. Also, any shared code and tooling (like the CI pipeline or a shared component library) need to be maintained by a dedicated team to help everyone in the monorepo.

### Polyrepos - a repository for each project

If every project is placed in its own repository, each team can make their own organizational decisions without the need to consult with other teams. Unfortunately, this also means that each team has to make their own organizational decisions instead of focusing on feature work that provides business value. Sharing code is difficult with this set up and every maintenance task needs to be repeated across all the repositories in the organization.

Nx can still be useful with this organizational structure. Tooling and maintenance tasks can be centralized through shared [Nx plugins](/docs/concepts/nx-plugins) that each repository can opt-in to using. Since creating repositories is a frequent occurrence in this scenario, Nx [generators](/docs/features/generate-code) can be used to quickly scaffold out the repository with reasonable tooling defaults.

### Multiple monorepos

Somewhere between the single monorepo and the full polyrepo solutions exists the multiple monorepo setup. Typically when there are disagreements about organizational decisions, there are two or three factions that form. These factions can naturally be allocated to separate monorepos that have been configured in a way that best suits the teams that will be working in them.

Compared to the single monorepo setup, this setup requires some extra overhead cost - maintaining multiple CI pipelines and performing the same tooling maintenance tasks on multiple repositories, but this cost could be offset by the extra productivity boost provided by the fact that each team can work in a repository that is optimized for the way that they work.

---
<!-- source: https://nx.dev/docs/concepts/decisions/project-dependency-rules.md -->
## Project Dependency Rules

There are many types of libraries in a workspace. You can identify the type of a library through a naming convention and/or by using the project tagging system. With explicitly defined types, you can also use Nx to enforce project dependency rules based on the types of each project. This article explains one possible way to organize your repository projects by type. Every repository is different and yours may need a different set of types.

In order to maintain a certain sense of order, we recommend having a small number of types, such as the below four (4) types of libraries.

**Feature libraries:**

Developers should consider feature libraries as libraries that implement container components (with access to data sources) for specific business use cases or pages in an application.

**UI libraries:**

A UI library contains only presentational components.

**Data-access libraries:**

A data-access library contains code for interacting with a back-end system. It also includes all the code related to state management.

**Utility libraries:**

A utility library contains low-level utilities used by many libraries and applications.

---

## Feature libraries

**What is it?**

A feature library contains a set of files that configure a business use case or a page in an application. Most of the components in such a library are container components that interact with data sources. This type of library also contains most of the UI logic, form validation code, etc. Feature libraries are almost always app-specific and are often lazy-loaded.

**Naming Convention**

`feature` (if nested) or `feature-*` (e.g., `feature-home`).

**Dependency Constraints**

A feature library can depend on any type of library.

{% filetree %}

- libs/
  - my-app/
    - feature-home/
      - src/
        - index.ts
        - lib/

{% /filetree %}

`feature-home` is the app-specific feature library (in this case, the "my-app" app).

---

## UI libraries

**What is it?**

A UI library is a collection of related presentational components. There are generally no services injected into these components (all of the data they need should come from Inputs).

**Naming Convention**

`ui` (if nested) or `ui-*` (e.g., `ui-buttons`)

**Dependency Constraints**

A ui library can depend on ui and util libraries.

---

## Data-access libraries

**What is it?**

Data-access libraries contain code that function as client-side delegate layers to server tier APIs.

All files related to state management also reside in a `data-access` folder (by convention, they can be grouped under a `+state` folder under `src/lib`).

**Naming Convention**

`data-access` (if nested) or `data-access-*` (e.g. `data-access-seatmap`)

**Dependency Constraints**

A data-access library can depend on data-access and util libraries.

---

## Utility libraries

**What is it?**

A utility library contains low level code used by many libraries. Often there is no framework-specific code and the library is simply a collection of utilities or pure functions.

**Naming Convention**

`util` (if nested), or `util-*` (e.g., `util-testing`)

**Dependency Constraints**

A utility library can depend only on utility libraries.

An example util lib module: **libs/shared/util-formatting**

```typescript
export { formatDate, formatTime } from './src/format-date-fns';
export { formatCurrency } from './src/format-currency';
```

## Enforce project dependency rules

In order to enforce the dependency constraints that were listed for each type, you can add the following rule in your ESLint configuration:

{% tabs syncKey="eslint-config-preference" %}
{% tabitem label="Flat Config" %}

```javascript
// eslint.config.mjs
import nx from '@nx/eslint-plugin';

export default [
  ...nx.configs['flat/base'],
  ...nx.configs['flat/typescript'],
  ...nx.configs['flat/javascript'],
  {
    ignores: ['**/dist'],
  },
  {
    files: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
    rules: {
      '@nx/enforce-module-boundaries': [
        'error',
        {
          allow: [],
          depConstraints: [
            {
              sourceTag: 'type:feature',
              onlyDependOnLibsWithTags: [
                'type:feature',
                'type:ui',
                'type:util',
              ],
            },
            {
              sourceTag: 'type:ui',
              onlyDependOnLibsWithTags: ['type:ui', 'type:util'],
            },
            {
              sourceTag: 'type:util',
              onlyDependOnLibsWithTags: ['type:util'],
            },
          ],
        },
      ],
    },
  },
];
```

{% /tabitem %}
{% tabitem label="Legacy (.eslintrc.json)" %}

```json
// .eslintrc.json
{
  "root": true,
  "ignorePatterns": ["**/*"],
  "plugins": ["@nx"],
  "overrides": [
    {
      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
      "rules": {
        "@nx/enforce-module-boundaries": [
          "error",
          {
            "allow": [],
            "depConstraints": [
              {
                "sourceTag": "type:feature",
                "onlyDependOnLibsWithTags": [
                  "type:feature",
                  "type:ui",
                  "type:util"
                ]
              },
              {
                "sourceTag": "type:ui",
                "onlyDependOnLibsWithTags": ["type:ui", "type:util"]
              },
              {
                "sourceTag": "type:util",
                "onlyDependOnLibsWithTags": ["type:util"]
              }
            ]
          }
        ]
      }
    }
  ]
}
```

{% /tabitem %}
{% /tabs %}

## Other types

You will probably come up with other library types that make sense for your organization. That's fine. Just keep a few things in mind:

- Keep the number of library types low
- Clearly document what each type of library means

---
<!-- source: https://nx.dev/docs/concepts/decisions/project-size.md -->
## Project Size

Like a lot of decisions in programming, deciding to make a new Nx project or not is all about trade-offs. Each organization will decide on their own conventions, but here are some trade-offs to bear in mind as you have the conversation.

## What is a project for?

> Developers new to Nx can be initially hesitant to move their logic into separate projects, because they assume it implies that those projects need to be general purpose and shareable across applications.

**This is a common misconception, moving code into projects can be done from a pure code organization perspective.**

Ease of re-use might emerge as a positive side effect of refactoring code into projects by applying an _"API thinking"_ approach. It is not the main driver though.

In fact when organizing projects you should think about your business domains.

## Should i make a new project?

There are three main benefits to breaking your code up into more projects.

### 1. Faster commands

The more granular your projects are, the more effective `nx affected` and Nx computation cache will be. For example, if `projectA` contains 10 tests, but only 5 of them were affected by a particular code change, all 10 tests will be run by `nx affected -t test`. If you can predict which 5 tests are usually run together, you can split all the related code into a separate project to allow the two groups of 5 tests to be executed independently.

### 2. Visualizing architecture

The `nx graph` command generates a graph of how apps and projects depend on each other. If most of your code lives in a few giant projects, this visualization doesn't provide much value. Adding the `--watch` flag to the command will update the visualization in-browser as you make changes.

### 3. Enforcing constraints

You can enforce constraints on how different types of projects depend on each other [using tags](/docs/features/enforce-module-boundaries). Following pre-determined conventions on what kind of code can go in different types of projects allows your tagging system to enforce good architectural patterns.

Also, each project defines its own API, which allows for encapsulating logic that other parts of codebase can not access. You can even use a [CODEOWNERS file](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners) to assign ownership of a certain project to a user or team.

## Should i add to an existing project?

Limiting the number of projects by keeping code in an existing project also has benefits.

### 1. Consolidating code

Related code should be close together. If a developer can accomplish a task without moving between multiple different folders, it helps them work faster and make less mistakes. Every new project adds some folders and configuration files that are not directly contributing to business value. Nx helps reduce the cost of adding a new project, but it isn't zero.

### 2. Removing constraints

Especially for rapidly evolving code, the standard architectural constraints may just get in the way of experimentation and exploration. It may be worthwhile to develop for a while in a single project in order to allow a real architecture to emerge and then refactoring into multiple projects once the pace of change has slowed down.

---
<!-- source: https://nx.dev/docs/concepts/decisions/why-monorepos.md -->
## Monorepos

A monorepo is a single git repository that holds the source code for multiple applications and libraries, along with the tooling for them.

## What are the benefits of a monorepo?

- **Shared code and visibility** - [Keeps your code DRY across your entire organization.](/docs/concepts/decisions/code-ownership) Reuse validation code, UI components, and types across the codebase. Reuse code between the backend, the frontend, and utility libraries.

- **Atomic changes** - Change a server API and modify the downstream applications that consume that API in the same commit. You can change a button component in a shared library and the applications that use that component in the same commit. A monorepo saves the pain of trying to coordinate commits across multiple repositories.

- **Developer mobility** - Get a consistent way of building and testing applications written using different tools and technologies. Developers can confidently contribute to other teams' applications and verify that their changes are safe.

- **Single set of dependencies** - [Use a single version of all third-party dependencies](/docs/concepts/decisions/dependency-management), reducing inconsistencies between applications. Less actively developed applications are still kept up-to-date with the latest version of a framework, library, or build tool.

## Why not just code collocation?

A naive implementation of a monorepo is code collocation, where you combine all the code from multiple repositories into the same repo. Many large companies that use monorepos don't "simply" put all the code in one place. **That's not enough**. Without adequate tooling to coordinate everything, problems arise with simply collocating code.

- **Running unnecessary tests** - All tests in the entire repository run to ensure nothing breaks from a given change. Even code in projects that are unrelated to the actual change.

- **No code boundaries** - Bugs and inconsistencies are added by a developer from another team changing code in your project. Or worse, another team uses code that you only intended for private use in their application. Now another project code depends on it, keeping you from making changes that may break their application.

- **Inconsistent tooling** - Each project uses its own set of commands for running tests, building, serving, linting, deploying, and so forth. Inconsistency creates mental overhead remembering which commands to use from project to project.

Tools like Lerna and Yarn Workspaces help optimize the installation of node modules, but they **do not** enable Monorepo-style development. In other words, they solve an orthogonal problem and can even be used in combination with Nx. Read more on it [here](https://blog.nrwl.io/why-you-should-switch-from-lerna-to-nx-463bcaf6821).

## Nx + code collocation = monorepo

Nx provides tools to give you the benefits of a monorepo without the drawbacks of simple code collocation.

### Scaling your monorepo with Nx

- **Consistent Command Execution** - Executors allow for consistent commands to test, serve, build, and lint each project using various tools.

- **Consistent Code Generation** - Generators allow you to customize and standardize organizational conventions and structure, removing the need to perform the same manual setup tasks repetitively.

- **Affected Commands** - [Nx affected commands](/docs/reference/nx-commands#nx-affected) analyze your source code, the context of the changes, and only runs tasks on the affected projects impacted by the source code changes.

- **Remote Caching** - Nx provides local caching and support for remote caching of command executions. With remote caching, when someone on your team runs a command, everyone else gets access to those artifacts to speed up their command executions, bringing them down from minutes to seconds. Nx helps you scale your development to massive applications and libraries even more with distributed task execution and incremental builds.

### Scaling your organization with Nx

- **Controlled Code Sharing** - While sharing code becomes much easier to share, there should also be constraints of when and how code should be depended on. Libraries are defined with specific enforced APIs. Rules should be put in place to define which libraries can depend on each other. Also, even though everyone has access to the repo does not mean that anyone should change any project. Projects should have owners such that changes to that project requires their approval. This can be defined using a `CODEOWNERS` file.

- **Consistent Code Generation** - Generators allow you to automate code creation and modification tasks. Instead of writing a 7 steps guide in a readme file, you can create a generator to prompt the developer for inputs and modify the code directly. Nrwl provides plugins containing useful executors and generators for many popular tools. Also, Nx workspaces are extended further through a growing number of community-provided plugins.

- **Accurate Architecture Diagram** - Most architecture diagrams become obsolete in an instant. And every diagram becomes out of date as soon as the code changes. Because Nx understands your code, it generates an up-to-date and accurate diagram of how projects depend on each other. The Nx project dependencies are also pluggable to extend to other programming languages and ecosystems.

---
<!-- source: https://nx.dev/docs/concepts/executors-and-configurations.md -->
## Executors and Configurations

Executors are pre-packaged node scripts that can be used to run tasks in a consistent way.

In order to use an executor, you need to install the plugin that contains the executor and then configure the executor in the project's `project.json` file.

```jsonc title="apps/cart/project.json"
{
  "root": "apps/cart",
  "sourceRoot": "apps/cart/src",
  "projectType": "application",
  "generators": {},
  "targets": {
    "build": {
      "executor": "@nx/webpack:webpack",
      "options": {
        "outputPath": "dist/apps/cart",
        ...
      }
    },
    "test": {
      "executor": "@nx/jest:jest",
      "options": {
        ...
      }
    }
  }
}
```

Each project has targets configured to run an executor with a specific set of options. In this snippet, `cart` has two targets defined - `build` and `test`.

Each executor definition has an `executor` property and, optionally, an `options` and a `configurations` property.

- `executor` is a string of the form `[package name]:[executor name]`. For the `build` executor, the package name is `@nx/webpack` and the executor name is `webpack`.
- `options` is an object that contains any configuration defaults for the executor. These options vary from executor to executor.
- `configurations` allows you to create presets of options for different scenarios. All the configurations start with the properties defined in `options` as a baseline and then overwrite those options. In the example, there is a `production` configuration that overrides the default options to set `sourceMap` to `false`.

Once configured, you can run an executor the same way you would [run any target](/docs/features/run-tasks):

```shell
nx [command] [project]
nx build cart
```

Browse the executors that are available in the [plugin registry](/docs/plugin-registry).

## Run a terminal command from an executor

If defining a new target that needs to run a single shell command, there is a shorthand for the `nx:run-commands` executor that can be used.

```jsonc title="project.json"
{
  "root": "apps/cart",
  "sourceRoot": "apps/cart/src",
  "projectType": "application",
  "generators": {},
  "targets": {
    "echo": {
      "command": "echo 'hello world'",
    },
  },
}
```

For more info, see the [run-commands documentation](/docs/guides/tasks--caching/run-commands-executor)

## Build your own executor

Nx comes with a Devkit that allows you to build your own executor to automate your Nx workspace. Learn more about it in the [docs page about creating a local executor](/docs/extending-nx/local-executors).

## Running executors with a configuration

You can use a specific configuration preset like this:

```shell
nx [command] [project] --configuration=[configuration]
nx build cart --configuration=production
```

## Use task configurations

The `configurations` property provides extra sets of values that will be merged into the options map.

```json title="project.json"
{
  "build": {
    "executor": "@nx/js:tsc",
    "outputs": ["{workspaceRoot}/dist/libs/mylib"],
    "dependsOn": ["^build"],
    "options": {
      "tsConfig": "libs/mylib/tsconfig.lib.json",
      "main": "libs/mylib/src/main.ts"
    },
    "configurations": {
      "production": {
        "tsConfig": "libs/mylib/tsconfig-prod.lib.json"
      }
    }
  }
}
```

You can select a configuration like this: `nx build mylib --configuration=production`
or `nx run mylib:build:production`.

The following code snippet shows how the executor options get constructed:

```javascript
require(`@nx/jest`).executors['jest']({
  ...options,
  ...selectedConfiguration,
  ...commandLineArgs,
}); // Pseudocode
```

The selected configuration adds/overrides the default options, and the provided command line args add/override the
configuration options.

### Default configuration

When using multiple configurations for a given target, it's helpful to provide a default configuration.
For example, running e2e tests for multiple environments. By default it would make sense to use a `dev` configuration for day to day work, but having the ability to run against an internal staging environment for the QA team.

```json title="project.json"
{
  "e2e": {
    "executor": "@nx/cypress:cypress",
    "options": {
      "cypressConfig": "apps/my-app-e2e/cypress.config.ts"
    },
    "configurations": {
      "dev": {
        "devServerTarget": "my-app:serve"
      },
      "qa": {
        "baseUrl": "https://some-internal-url.example.com"
      }
    },
    "defaultConfiguration": "dev"
  }
}
```

When running `nx e2e my-app-e2e`, the _dev_ configuration will be used. In this case using the local dev server for `my-app`.
You can always run the other configurations by explicitly providing the configuration i.e. `nx e2e my-app-e2e --configuration=qa` or `nx run my-app-e2e:e2e:qa`

---
<!-- source: https://nx.dev/docs/concepts/how-caching-works.md -->
## How Caching Works

Before running any cacheable task, Nx computes its computation hash. As long as the computation hash is the same, the output of
running the task is the same.

By default, the computation hash for something like `nx test remixapp` includes:

- All the source files of `remixapp` and its dependencies
- Relevant global configuration
- Versions of external dependencies
- Runtime values provisioned by the user such as the version of Node
- CLI Command flags

![computation-hashing](../../../assets/concepts/caching/nx-hashing.svg)

> This behavior is customizable. For instance, lint checks may only depend on the source code of the project and global
> configs. Builds can depend on the dts files of the compiled libs instead of their source.

After Nx computes the hash for a task, it then checks if it ran this exact computation before. First, it checks locally, and then if it is missing, and if a remote cache is configured, it checks remotely. If a matching computation is found, Nx retrieves and replays it. This includes restoring files.

Nx places the right files in the right folders and prints the terminal output. From the user's point of view, the command ran the same, only a lot faster.

![cache](../../../assets/concepts/caching/cache.svg)

If Nx doesn't find a corresponding computation hash, Nx runs the task, and after it completes, it takes the outputs and the terminal logs and stores them locally (and, if configured, remotely as well). All of this happens transparently, so you don't have to worry about it.

## Optimizations

Nx optimizes the caching experience in several ways. For instance, Nx:

- Captures stdout and stderr to make sure the replayed output looks the same, including on Windows.
- Minimizes the IO by remembering what files are replayed where.
- Only shows relevant output when processing a large task graph.
- Provides affordances for troubleshooting cache misses. And many other optimizations.

As your workspace grows, the task graph looks more like this:

![cache](../../../assets/concepts/caching/task-graph-big.svg)

All of these optimizations are crucial for making Nx usable for any non-trivial workspace. Only the minimum amount of
work happens. The rest is either left as is or restored from the cache.

## Fine-tuning the Nx cache

Each cacheable task defines a set of inputs and outputs. Inputs are factors Nx considers when calculating the computation hash.
Outputs are files that will be cached and restored when the computation hash matches.
For more information on how to fine-tune caching, see the [Fine-tuning Caching with Inputs recipe](/docs/guides/tasks--caching/configure-inputs).

### Inputs

Inputs are factors Nx considers when calculating the computation hash for a task.

For more information on the different types of inputs and how to configure inputs for your tasks, read the [Fine-tuning Caching with Inputs recipe](/docs/guides/tasks--caching/configure-inputs)

## What is cached

Nx cache works on the process level. Regardless of the tools used to build/test/lint/etc.. your project, the results are cached. This includes:

- **Terminal output:** The terminal output generated when running a task. This includes logs, warnings, and errors.
- **Task artifacts:** The output files of a task defined in the [`outputs` property of your project configuration](/docs/guides/tasks--caching/configure-outputs). For example the build output, test results, or linting reports.
- **Hash:** The hash of the inputs to the computation. The inputs include the source code, runtime values, and command line arguments. Note that the hash is included in the cache, but the actual inputs are not.

{% tabs %}
{% tabitem label="package.json" %}

```json title="apps/myapp/package.json"
{
  "name": "myapp",
  "dependencies": {},
  "devDependencies": {},
  "nx": {
    "targets": {
      "build": {
        "outputs": ["{projectRoot}/build", "{projectRoot}/public/build"]
      }
    }
  }
}
```

{% /tabitem %}
{% tabitem label="project.json" %}

```json title="apps/myapp/project.json"
{
  "name": "myapp",
  ...
  "targets": {
    "build": {
      ...
      "outputs": ["dist/dist/myapp"]
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

If the `outputs` property for a given target isn't defined in the project's `package.json` file, Nx will look at the global, workspace-wide definition in the `targetDefaults` section of `nx.json`:

```jsonc title="nx.json"
{
  ...
  "targetDefaults": {
    "build": {
      "dependsOn": [
        "^build"
      ],
      "outputs": [
        "{projectRoot}/dist",
        "{projectRoot}/build",
        "{projectRoot}/public/build"
      ]
    }
  }
}
```

If neither is defined, Nx defaults to caching `dist` and `build` at the root of the repository.

{% aside type="note" title="Output vs OutputPath" %}
Several executors have a property in options called `outputPath`. On its own, this property does not influence caching or what is stored at the end of a run. You can reuse that property though by defining your outputs like: `outputs: [{options.outputPath}]`.
{% /aside %}

## Define cache inputs

By default the cache considers all project files (e.g. `{projectRoot}/**/*`). This behavior can be customized by defining in a much more fine-grained way what files should be included or excluded for each target.

{% tabs %}
{% tabitem label="Globally" %}

```json title="nx.json"
{
  "targetDefaults": {
    "build": {
      "inputs": ["{projectRoot}/**/*", "!{projectRoot}/**/*.md"]
      ...
    },
    "test": {
      "inputs": [...]
    }
  }
}
```

{% /tabitem %}
{% tabitem label="Project Level" %}

```json title="packages/some-project/project.json"
{
  "name": "some-project",
  "targets": {
    "build": {
      "inputs": ["!{projectRoot}/**/*.md"],
      ...
    },
    "test": {
      "inputs": [...]
    }
    ...
  }
}
```

{% /tabitem %}
{% /tabs %}

Inputs may include

- source files
- environment variables
- runtime inputs
- command line arguments

Learn more about fine tuning caching in the [Fine-tuning Caching with Inputs page](/docs/guides/tasks--caching/configure-inputs).

## Args hash inputs

Finally, in addition to Source Code Hash Inputs and Runtime Hash Inputs, Nx needs to consider the arguments: For
example, `nx build remixapp` and `nx build remixapp -- --flag=true` produce different
results.

Note, only the flags passed to the npm scripts itself affect results of the computation. For instance, the following
commands are identical from the caching perspective.

```shell
npx nx build remixapp
npx nx run-many -t build -p remixapp
```

In other words, Nx does not cache what the developer types into the terminal.

If you build/test/lint… multiple projects, each individual build has its own hash value and will either be retrieved
from
cache or run. This means that from the caching point of view, the following command:

```shell
npx nx run-many -t build -p header footer
```

is identical to the following two commands:

```shell
npx nx build header
npx nx build footer
```

## Next steps

{% aside type="tip" title="Learn by doing" %}
Try the [Caching](/docs/getting-started/tutorials/caching) tutorial to apply these concepts in your own workspace.
{% /aside %}

Learn more about how to configure caching, where the cache is stored, how to reset it and more.

- [Cache Task Results](/docs/features/cache-task-results)

---
<!-- source: https://nx.dev/docs/concepts/inferred-tasks.md -->
## Inferred Tasks (Project Crystal)

In Nx version 18, Nx plugins can automatically infer tasks for your projects based on the configuration of different tools. Many tools have configuration files which determine what a tool does. Nx is able to cache the results of running the tool. Nx plugins use the same configuration files to infer how Nx should [run the task](/docs/features/run-tasks). This includes [fine-tuned cache settings](/docs/features/cache-task-results) and automatic [task dependencies](/docs/concepts/task-pipeline-configuration).

For example, the `@nx/webpack` plugin infers tasks to run webpack through Nx based on your repository's webpack configuration. This configuration already defines the destination of your build files, so Nx reads that value and caches the correct output files.

{% youtube
src="https://youtu.be/wADNsVItnsM"
title="Project Crystal"
/%}

## How does a plugin infer tasks?

Every plugin has its own custom logic, but in order to infer tasks, they all go through the following steps.

### 1. detect tooling configuration in workspace

The plugin will search the workspace for configuration files of the tool. For each configuration file found, the plugin will infer tasks. i.e. The `@nx/webpack` plugin searches for `webpack.config.js` files to infer tasks that run webpack.

### 2. create an inferred task

The plugin then configures tasks with a name that you specified in the plugin's configuration in `nx.json`. The settings for the task are determined by the tool configuration.

The `@nx/webpack` plugin creates tasks named `build`, `serve` and `preview` by default and it automatically sets the task caching settings based on the values in the webpack configuration files.

## What is inferred

Nx plugins infer the following properties by analyzing the tool configuration.

- Command - How is the tool invoked
- [Cacheability](/docs/concepts/how-caching-works) - Whether the task will be cached by Nx. When the Inputs have not changed the Outputs will be restored from the cache.
- [Inputs](/docs/guides/tasks--caching/configure-inputs) - Inputs are used by the task to produce Outputs. Inputs are used to determine when the Outputs of a task can be restored from the cache.
- [Outputs](/docs/guides/tasks--caching/configure-outputs) - Outputs are the results of a task. Outputs are restored from the cache when the Inputs are the same as a previous run.
- [Task Dependencies](/docs/concepts/task-pipeline-configuration) - The list of other tasks which must be completed before running this task.

## Nx uses plugins to build the graph

A typical workspace will have many plugins inferring tasks. Nx processes all the plugins registered in `nx.json` to create project configuration for individual projects and a project and task graph that shows the connections between them all.

### Plugin order matters

Plugins are processed in the order that they appear in the `plugins` array in `nx.json`. So, if multiple plugins create a task with the same name, the plugin listed last will win. If, for some reason, you have a project with both a `vite.config.js` file and a `webpack.config.js` file, both the `@nx/vite` plugin and the `@nx/webpack` plugin will try to create a `build` task. The `build` task that is executed will be the task that belongs to the plugin listed lower in the `plugins` array.

### Scope plugins to specific projects

Plugins use config files to infer tasks for projects. You can specify which config files are processed by Nx plugins using the `include` and `exclude` properties in the plugin configuration object.

```jsonc
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/jest/plugin",
      "include": ["packages/**/*"],
      "exclude": ["**/*-e2e/**/*"],
    },
  ],
}
```

The `include` and `exclude` properties are file glob patterns that filter which configuration files the plugin processes. In the example above, the `@nx/jest/plugin` will only infer tasks for projects where the `jest.config.ts` file path matches the `packages/**/*` glob but does not match the `**/*-e2e/**/*` glob.

This is useful when you want a plugin to only affect certain projects, or when you need to apply different plugin options to different sets of projects by registering the same plugin multiple times with different `include`/`exclude` patterns.

## View inferred tasks

To view the task settings for projects in your workspace, [show the project details](/docs/features/explore-graph) either from the command line or using Nx Console.

```shell
nx show project my-project --web
```

{% project_details%}

```json
{
  "project": {
    "name": "myreactapp",
    "type": "app",
    "data": {
      "root": "apps/myreactapp",
      "targets": {
        "build": {
          "options": {
            "cwd": "apps/myreactapp",
            "command": "vite build"
          },
          "cache": true,
          "dependsOn": ["^build"],
          "inputs": [
            "production",
            "^production",
            {
              "externalDependencies": ["vite"]
            }
          ],
          "outputs": ["{workspaceRoot}/dist/apps/myreactapp"],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["vite"]
          }
        },
        "serve": {
          "options": {
            "cwd": "apps/myreactapp",
            "command": "vite serve",
            "continuous": true
          },
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["vite"]
          }
        },
        "preview": {
          "options": {
            "cwd": "apps/myreactapp",
            "command": "vite preview"
          },
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["vite"]
          }
        },
        "serve-static": {
          "executor": "@nx/web:file-server",
          "options": {
            "buildTarget": "build",
            "continuous": true
          },
          "configurations": {}
        },
        "test": {
          "options": {
            "cwd": "apps/myreactapp",
            "command": "vitest run"
          },
          "cache": true,
          "inputs": [
            "default",
            "^production",
            {
              "externalDependencies": ["vitest"]
            }
          ],
          "outputs": ["{workspaceRoot}/coverage/apps/myreactapp"],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["vite"]
          }
        },
        "lint": {
          "cache": true,
          "options": {
            "cwd": "apps/myreactapp",
            "command": "eslint ."
          },
          "inputs": [
            "default",
            "{workspaceRoot}/.eslintrc.json",
            "{workspaceRoot}/apps/myreactapp/.eslintrc.json",
            "{workspaceRoot}/tools/eslint-rules/**/*",
            {
              "externalDependencies": ["eslint"]
            }
          ],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["eslint"]
          }
        }
      },
      "name": "myreactapp",
      "$schema": "../../../node_modules/nx/schemas/project-schema.json",
      "sourceRoot": "apps/myreactapp/src",
      "projectType": "application",
      "tags": [],
      "implicitDependencies": [],
      "metadata": {
        "technologies": ["react"]
      }
    }
  },
  "sourceMap": {
    "root": ["apps/myreactapp/project.json", "nx/core/project-json"],
    "targets": ["apps/myreactapp/project.json", "nx/core/project-json"],
    "targets.build": ["apps/myreactapp/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.command": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.options": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.cache": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.dependsOn": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.inputs": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.outputs": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.options.cwd": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.serve": ["apps/myreactapp/vite.config.ts", "@nx/vite/plugin"],
    "targets.serve.command": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.serve.options": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.serve.options.cwd": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.preview": ["apps/myreactapp/vite.config.ts", "@nx/vite/plugin"],
    "targets.preview.command": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.preview.options": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.preview.options.cwd": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.serve-static": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.serve-static.executor": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.serve-static.options": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.serve-static.options.buildTarget": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.test": ["apps/myreactapp/vite.config.ts", "@nx/vite/plugin"],
    "targets.test.command": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.test.options": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.test.cache": ["apps/myreactapp/vite.config.ts", "@nx/vite/plugin"],
    "targets.test.inputs": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.test.outputs": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.test.options.cwd": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.lint": ["apps/myreactapp/project.json", "@nx/eslint/plugin"],
    "targets.lint.command": [
      "apps/myreactapp/project.json",
      "@nx/eslint/plugin"
    ],
    "targets.lint.cache": ["apps/myreactapp/project.json", "@nx/eslint/plugin"],
    "targets.lint.options": [
      "apps/myreactapp/project.json",
      "@nx/eslint/plugin"
    ],
    "targets.lint.inputs": [
      "apps/myreactapp/project.json",
      "@nx/eslint/plugin"
    ],
    "targets.lint.options.cwd": [
      "apps/myreactapp/project.json",
      "@nx/eslint/plugin"
    ],
    "name": ["apps/myreactapp/project.json", "nx/core/project-json"],
    "$schema": ["apps/myreactapp/project.json", "nx/core/project-json"],
    "sourceRoot": ["apps/myreactapp/project.json", "nx/core/project-json"],
    "projectType": ["apps/myreactapp/project.json", "nx/core/project-json"],
    "tags": ["apps/myreactapp/project.json", "nx/core/project-json"]
  }
}
```

{% /project_details %}

## Overriding inferred task configuration

You can override the task configuration inferred by plugins in several ways.
If you want to overwrite the task configuration for multiple projects, [use the `targetDefaults` object](/docs/reference/nx-json#target-defaults) in the `nx.json` file.
If you only want to override the task configuration for a specific project, [update that project's configuration](/docs/reference/project-configuration) in `package.json` or `project.json`.
This configuration is more specific so it will override both the inferred configuration and the `targetDefaults`.

The order of precedence for task configuration is:

1. Inferred Task Configurations from plugins in `nx.json`.
2. `targetDefaults` in `nx.json`.
3. Project Configuration in `package.json` or `project.json`.

More details about how to override task configuration is available in these guides:

- [Configure Inputs for Task Caching](/docs/guides/tasks--caching/configure-inputs)
- [Configure Outputs for Task Caching](/docs/guides/tasks--caching/configure-outputs)
- [Defining a Task Pipeline](/docs/guides/tasks--caching/defining-task-pipeline)
- [Pass Arguments to Commands](/docs/guides/tasks--caching/pass-args-to-commands)

## Existing Nx workspaces

{% aside type="tip" title="Learn by doing" %}
Try the [Reducing Configuration Boilerplate](/docs/getting-started/tutorials/reducing-configuration-boilerplate) tutorial to apply these concepts in your own workspace.
{% /aside %}

If you have an existing Nx Workspace and upgrade to the latest Nx version, a migration will automatically set `useInferencePlugins` to `false` in `nx.json`. This property allows you to continue to use Nx without inferred tasks.

When `useInferencePlugins` is `false`:

1. A newly generated project will have all targets defined with executors - not with inferred tasks.
2. Running `nx add @nx/some-plugin` will not create a plugin entry for `@nx/some-plugin` in the `nx.json` file. (So that plugin will not create inferred tasks.)

If you want to **migrate** your projects to use inferred tasks, follow the recipe for [migrating to inferred tasks](/docs/guides/tasks--caching/convert-to-inferred).

Even once a repository has fully embraced inferred tasks, `project.json` and executors will still be useful. The `project.json` file is needed to modify inferred task options and to define tasks that can not be inferred. Some executors perform tasks that can not be accomplished by running a tool directly from the command line (i.e. batch mode).

---
<!-- source: https://nx.dev/docs/concepts/mental-model.md -->
## Mental Model

Nx is a VSCode of build tools, with a powerful core, driven by metadata, and extensible through [plugins](/docs/concepts/nx-plugins). Nx works with a few core concepts to drive your monorepo efficiently: project graphs, task graphs, affected commands, computation hashing, and caching.

## The project graph

A project graph is used to reflect the source code in your repository and all the external dependencies that aren't
authored in your repository, such as Webpack, React, Angular, and so forth.

![project-graph](../../../assets/concepts/mental-model/project-graph.svg)

Nx analyzes your file system to detect projects. Projects are identified by the presence of a `package.json` file or `project.json` file. Projects identification can also be customized through plugins. You can manually define dependencies between
the project nodes, but you don't have to do it very often. Nx analyzes files' source code, your installed dependencies, TypeScript
files, and others figuring out these dependencies for you. Nx also stores the cached project graph, so it only
reanalyzes the files you have changed.

![project-graph-updated](../../../assets/concepts/mental-model/project-graph-updated.svg)

Nx provides an updated graph after each analysis is done.

## Metadata-driven

Everything in Nx comes with metadata to enable toolability. Nx gathers information about your projects and tasks and then uses that information to help you understand and interact with your codebase. With the right plugins installed, most of the metadata can be [inferred directly from your existing configuration files](/docs/concepts/inferred-tasks) so you don't have to define it manually.

This metadata is used by Nx itself, by VSCode and WebStorm integrations, by GitHub integration, and by third-party
tools.

![metadata](../../../assets/concepts/mental-model/metadata.png)

These tools are able to implement richer experiences with Nx using this metadata.

## The task graph

Nx uses the project graph to create a task graph. Any time you run anything, Nx creates a task graph from the project
graph and then executes the tasks in that graph.

For instance `nx test lib` creates a task graph with a single node:

{% graph height="100px" type="task" %}

```json
{
  "projects": [
    {
      "name": "lib",
      "type": "lib",
      "data": {
        "tags": [],
        "targets": {
          "test": {}
        }
      }
    }
  ],
  "taskIds": ["lib:test"],
  "taskGraph": {
    "roots": ["lib:test"],
    "tasks": {
      "lib:test": {
        "id": "lib:test",
        "target": {
          "project": "lib",
          "target": "test"
        },
        "projectRoot": "libs/lib",
        "overrides": {}
      }
    },
    "dependencies": {}
  }
}
```

{% /graph %}

A task is an invocation of a target. If you invoke the same target twice, you create two tasks.

Nx uses the [project graph](#the-project-graph), but the task graph and project graph aren't isomorphic, meaning they
aren't directly connected. In the case above, `app1` and `app2` depend on `lib`, but
running `nx run-many -t test -p app1 app2 lib`, the created task graph will look like this:

**Project Graph:**

{% graph height="200px" type="project" %}

```json
{
  "projects": [
    {
      "name": "lib",
      "type": "lib",
      "data": {
        "tags": [],
        "targets": {
          "test": {}
        }
      }
    }
  ],
  "taskIds": ["lib:test"],
  "taskGraph": {
    "roots": ["lib:test"],
    "tasks": {
      "lib:test": {
        "id": "lib:test",
        "target": {
          "project": "lib",
          "target": "test"
        },
        "projectRoot": "libs/lib",
        "overrides": {}
      }
    },
    "dependencies": {}
  }
}
```

{% /graph %}

**Task Graph:**

{% graph height="200px" type="task"%}

```json
{
  "projects": [
    {
      "name": "lib",
      "type": "lib",
      "data": {
        "tags": [],
        "targets": {
          "test": {}
        }
      }
    }
  ],
  "taskIds": ["lib:test"],
  "taskGraph": {
    "roots": ["lib:test"],
    "tasks": {
      "lib:test": {
        "id": "lib:test",
        "target": {
          "project": "lib",
          "target": "test"
        },
        "projectRoot": "libs/lib",
        "overrides": {}
      }
    },
    "dependencies": {}
  }
}
```

{% /graph %}

Even though the apps depend on `lib`, testing `app1` doesn't depend on the testing `lib`. This means that the two tasks
can
run in parallel.

Let's look at the test target relying on its dependencies.

```json
{
  "test": {
    "executor": "@nx/jest:jest",
    "outputs": ["{workspaceRoot}/coverage/apps/app1"],
    "dependsOn": ["^test"],
    "options": {
      "jestConfig": "apps/app1/jest.config.js",
      "passWithNoTests": true
    }
  }
}
```

With this, running the same test command creates the following task graph:

**Project Graph:**

{% graph height="200px" type="project" %}

```json
{
  "projects": [
    {
      "name": "lib",
      "type": "lib",
      "data": {
        "tags": [],
        "targets": {
          "test": {}
        }
      }
    }
  ],
  "taskIds": ["lib:test"],
  "taskGraph": {
    "roots": ["lib:test"],
    "tasks": {
      "lib:test": {
        "id": "lib:test",
        "target": {
          "project": "lib",
          "target": "test"
        },
        "projectRoot": "libs/lib",
        "overrides": {}
      }
    },
    "dependencies": {}
  }
}
```

{% /graph %}

**Task Graph:**

{% graph height="200px" type="task" %}

```json
{
  "projects": [
    {
      "name": "lib",
      "type": "lib",
      "data": {
        "tags": [],
        "targets": {
          "test": {}
        }
      }
    }
  ],
  "taskIds": ["lib:test"],
  "taskGraph": {
    "roots": ["lib:test"],
    "tasks": {
      "lib:test": {
        "id": "lib:test",
        "target": {
          "project": "lib",
          "target": "test"
        },
        "projectRoot": "libs/lib",
        "overrides": {}
      }
    },
    "dependencies": {}
  }
}
```

{% /graph %}

This often makes more sense for builds, where to build `app1`, you want to build `lib` first. You can also define
similar
relationships between targets of the same project, including a test target that depends on the build. Learn more about configuring task pipelines in [Task Pipeline Configuration](/docs/concepts/task-pipeline-configuration).

A task graph can contain different targets, and those can run in parallel. For instance, as Nx is building `app2`, it
can be testing `app1` at the same time.

![task-graph-execution](../../../assets/concepts/mental-model/task-graph-execution.svg)

Nx also runs the tasks in the task graph in the right order. Nx executing tasks in parallel speeds up your overall
execution time.

## Affected commands

When you run `nx test app1`, you are telling Nx to run the `app1:test` task plus all the tasks it depends on.

When you run `nx run-many -t test -p app1 lib`, you are telling Nx to do the same for two
tasks `app1:test`
and `lib:test`.

When you run `nx run-many -t test`, you are telling Nx to do this for all the projects.

As your workspace grows, retesting all projects becomes too slow. To address this Nx implements code change analysis via the [`affected` command](/docs/features/ci-features/affected) to
get the min set of projects that need to be retested. How does it work?

When you run `nx affected -t test`, Nx looks at the files you changed in your PR, it will look at the nature of
change (what exactly did you update in those files), and it uses this to figure the list of projects in the workspace
that can be affected by this change. It then runs the `run-many` command with that list.

For instance, if my PR changes `lib`, and I then run `nx affected -t test`, Nx figures out that `app1` and `app2`
depend on `lib`, so it will invoke `nx run-many -t test -p app1 app2 lib`.

![affected](../../../assets/concepts/mental-model/affected.svg)

Nx analyzes the nature of the changes. For example, if you change the version of Next.js in the package.json, Nx knows
that `app2` cannot be affected by it, so it only retests `app1`.

## Computation hashing and caching

Before running a task, Nx computes a hash based on source files, configuration, dependencies, and other inputs. If the hash matches a previous run, the cached result is replayed — including terminal output and file artifacts. If not, Nx runs the task and stores the result for next time.

![computation-hashing](../../../assets/concepts/mental-model/computation-hashing.svg)

Nx checks the local cache first, then the [remote cache](/docs/features/ci-features/remote-cache) if configured. From the user's point of view, the command ran the same, only a lot faster.

![cache](../../../assets/concepts/mental-model/cache.svg)

See [How Caching Works](/docs/concepts/how-caching-works) for the complete list of hash inputs, cache configuration options, and optimization details.

## Distributed task execution

For large workspaces, even with caching, running all tasks on a single machine can be slow. [Nx Agents](/docs/features/ci-features/distribute-task-execution) can distribute the task graph across multiple machines, running tasks in parallel while using [remote caching](/docs/features/ci-features/remote-cache) to share artifacts between agents. From your CI's perspective, the results appear as if everything ran on a single machine.

![Distribution](../../../assets/concepts/mental-model/dte.svg)

## In summary

- Nx is able to analyze your source code to create a Project Graph.
- Nx can use the project graph and information about projects' targets to create a Task Graph.
- Nx is able to perform code-change analysis to create the smallest task graph for your PR.
- Nx supports [computation caching](/docs/features/cache-task-results) to never execute the same computation twice. This computation cache is pluggable and
  can be distributed.

---
<!-- source: https://nx.dev/docs/concepts/nx-daemon.md -->
## Nx Daemon

In version 13 we introduced the opt-in Nx Daemon which Nx can leverage to dramatically speed up project graph computation, particularly for large workspaces.

## Why is it needed?

Every time you invoke a target directly, such as `nx test myapp`, or run affected commands, such `nx affected:test`, Nx first needs to generate a project graph in order to figure out how all the different projects and files within your workspace fit together. Naturally, the larger your workspace gets, the more expensive this project graph generation becomes.

Thankfully, because Nx stores its metadata on disk, Nx only recomputes what has changed since the last command invocation.

This helps quite a bit, but the recomputation is not very surgical because there is no way for Nx to know what kind of changes you have made, so it has to consider a wide range of possibilities when recomputing the project graph, even with the cache available.

## What is Nx daemon

The Nx Daemon is a process which runs in the background on your local machine. There is one unique Nx Daemon per Nx workspace meaning if you have multiple Nx workspaces on your machine active at the same time, the corresponding Nx Daemon instances will operate independently of one another and can be on different versions of Nx.

{% aside type="note" title="Mac & Linux" %}
On macOS and linux, the server runs as a unix socket, and on Windows it runs as a named pipe.
{% /aside %}

The Nx Daemon is more efficient at recomputing the project graph because it watches the files in your workspaces and updates the project graph right away (intelligently throttling to ensure minimal recomputation). It also keeps everything in memory, so the response tends to be a lot faster.

In order to be most efficient, the Nx Daemon has some built in mechanisms to automatically shut down (including removing all file watchers) when it is not needed. These include:

- after 3 hours of inactivity (meaning the workspace's Nx Daemon did not receive any requests or detect any file changes in that time)
- when the Nx installation changes

If you ever need to manually shut down the Nx Daemon, you can run `nx reset` within the workspace in question.

## Turning it off

The Nx Daemon is enabled by default when running on your local machine. If you want to turn it off

- set `useDaemonProcess: false` in the runners options in `nx.json` or
- set the `NX_DAEMON` env variable to `false`.

When using Nx in a CI environment, the Nx Daemon is disabled by default. Whether the process runs is determined by the following function: [https://github.com/nrwl/nx/blob/master/packages/nx/src/utils/is-ci.ts](https://github.com/nrwl/nx/blob/master/packages/nx/src/utils/is-ci.ts)

## Logs

To see information about the running Nx Daemon (such as its background process ID and log output file), run `nx daemon`. Once you have the path to that log file, you could either open it in your IDE or stream updates in a separate terminal window by running `tail -f {REPLACE_WITH_LOG_PATH}`, for example.

## Customizing the socket location

The Nx Daemon uses a unix socket to communicate between the daemon and the Nx processes. By default this socket gets placed in a temp directory. If you are using Nx in a docker-compose environment, however, you may want to run the daemon manually
and control its location to enable sharing the daemon among your docker containers. To do so, set the `NX_DAEMON_SOCKET_DIR` environment variable to a shared directory.

## Daemon behavior in containers

Nx automatically disables the daemon in Docker containers and CI environments. The daemon's performance benefits come from maintaining state between commands and watching for file changes—in short-lived environments where each command runs in a fresh container, this state cannot be reused, so the overhead of starting a background process provides no benefit.

### Automatic detection

Nx detects Docker containers by checking for `/.dockerenv` or Docker references in `/proc/self/cgroup`. When detected, the daemon is disabled unless explicitly enabled with `NX_DAEMON=true`.

### Enabling the daemon in containers

If you have a long-running container with a persistent filesystem (e.g., a dev container), you can enable the daemon:

```dockerfile
ENV NX_DAEMON=true
```

When enabling the daemon in containers, be aware of these considerations:

- **Volume mounts** can cause inode/mtime changes that interfere with file watching
- **Container restarts** invalidate the daemon's socket, requiring a new daemon process
- **Permission differences** between the container and host may affect socket communication

For docker-compose setups with shared daemon sockets, see the [Customizing the socket location](#customizing-the-socket-location) section above.

{% aside type="note" title="When to enable the daemon" %}
Only enable the daemon in containers that persist across multiple Nx commands. For ephemeral CI containers or frequently restarted dev containers, the default (disabled) behavior is more reliable.
{% /aside %}

---
<!-- source: https://nx.dev/docs/concepts/nx-plugins.md -->
## What Are Nx Plugins?

Nx plugins help developers use a tool or framework with Nx. They allow the plugin author who knows the best way to use a tool with Nx to codify their expertise and allow the whole community to reuse those solutions.

For example, plugins can accomplish the following:

- [Configure Nx cache settings](/docs/concepts/inferred-tasks) for a tool. The [`@nx/webpack`](/docs/technologies/build-tools/webpack/introduction) plugin can automatically configure the [inputs](/docs/guides/tasks--caching/configure-inputs) and [outputs](/docs/guides/tasks--caching/configure-outputs) for a `build` task based on the settings in the `webpack.config.js` file it uses.
- [Update tooling configuration](/docs/features/automate-updating-dependencies) when upgrading the tool version. When Storybook 7 introduced a [new format](https://storybook.js.org/blog/storybook-csf3-is-here) for their configuration files, anyone using the [`@nx/storybook`](/docs/technologies/test-tools/storybook/introduction) plugin could automatically apply those changes to their repository when upgrading.
- [Set up a tool](/docs/features/generate-code) for the first time. With the [`@nx/playwright`](/docs/technologies/test-tools/playwright/introduction) plugin installed, you can use the `@nx/playwright:configuration` code generator to set up Playwright tests in an existing project.
- [Run a tool in an advanced way](/docs/concepts/executors-and-configurations). The [`@nx/js`](/docs/technologies/typescript/introduction) plugin's [`@nx/js:tsc` executor](/docs/technologies/typescript/executors#tsc) combines the Nx understanding of your repository with Typescript's native batch mode feature to make your builds [even more performant](/docs/technologies/typescript/guides/enable-tsc-batch-mode).

## Plugin features

{% linkcard title="Infer tasks" href="/docs/concepts/inferred-tasks" description="Automatically configure Nx settings for tasks based on tooling configuration" /%}
{% linkcard title="Generate Code" href="/docs/features/generate-code" description="Generate and modify code to set up and use the tool or framework" /%}
{% linkcard title="Maintain Dependencies" href="/docs/features/automate-updating-dependencies" description="Automatically update package versions and tooling configuration" /%}
{% linkcard title="Enhance Tooling with Executors" href="/docs/concepts/executors-and-configurations" description="Run a tool in an advanced way that may not be possible from the command line" /%}

## Types of plugins

{% aside type="tip" title="Learn by doing" %}
Try the [Reducing Configuration Boilerplate](/docs/getting-started/tutorials/reducing-configuration-boilerplate) tutorial to apply these concepts in your own workspace.
{% /aside %}

{% linkcard title="Official and Community Plugins" href="/docs/plugin-registry" description="Browse the plugin registry to discover plugins created by the Nx core team and the community" /%}
{% linkcard title="Build Your Own Plugin" href="/docs/extending-nx/organization-specific-plugin" description="Build your own plugin to use internally or share with the community" /%}

---
<!-- source: https://nx.dev/docs/concepts/sync-generators.md -->
## Sync Generators

In Nx 19.8, you can use sync generators to ensure that your repository is maintained in a correct state. One specific application is to use the project graph to update files. These can be global configuration files or scripts, or at the task level to ensure that files are in sync before a task is run.

Sync Generator Examples:

- Update a custom CI script with binning strategies based on the current project graph
- Update TypeScript config files with project references based on the current project graph
- Ensure code is formatted in a specific way before CI is run

## Task sync generators

Sync generators can be associated with a particular task. Nx will use the sync generator to ensure that code is correctly configured before running the task.
Nx does this in different ways, depending on whether the task is being run on a developer machine or in CI.

On a developer machine, the sync generator is run in `--dry-run` mode and if files would be changed by the generator, the user is prompted to run the generator or skip it. This prompt can be disabled by setting the `sync.applyChanges` property to `true` or `false` in the `nx.json` file.

```json title="nx.json" {4-6}
{
  "$schema": "packages/nx/schemas/nx-schema.json",
  ...
  "sync": {
    "applyChanges": true
  }
}
```

{% aside type="caution" title="Opting out of automatic sync" %}
If you set `sync.applyChanges` to `false`, then developers must run `nx sync` manually before pushing changes. Otherwise, CI may fail due to the workspace being out of sync.
{% /aside %}

In CI, the sync generator is run in `--dry-run` mode and if files would be changed by the generator, the task fails with an error provided by the sync generator. The sync generator can be skipped in CI by passing the `--skip-sync` flag when executing the task, or you can skip an individual sync generator by adding that generator to the `sync.disabledTaskSyncGenerators` in `nx.json`.

```json title="nx.json" {4-6}
{
  "$schema": "packages/nx/schemas/nx-schema.json",
  ...
  "sync": {
    "disabledTaskSyncGenerators": ["@nx/js:typescript-sync"]
  }
}

```

Use the project details view to **find registered sync generators** for a given task.

```shell
nx show project <name>
```

The above command opens up the project details view, and the registered sync generators are under the **Sync Generators** for each target. Most sync generators are inferred when using an [inference plugin](/docs/concepts/inferred-tasks). For example, the `@nx/js/typescript` plugin registers the `@nx/js:typescript-sync` generator on `build` and `typecheck` targets.

{% project_details title="Project Details View" expandedTargets=["build"] %}

```json
{
  "project": {
    "name": "foo",
    "data": {
      "root": " packages/foo",
      "projectType": "library",
      "targets": {
        "build": {
          "dependsOn": ["^build"],
          "cache": true,
          "inputs": [
            "{workspaceRoot}/tsconfig.base.json",
            "{projectRoot}/tsconfig.lib.json",
            "{projectRoot}/src/**/*.ts"
          ],
          "outputs": ["{workspaceRoot}/packages/foo/dist"],
          "syncGenerators": ["@nx/js:typescript-sync"],
          "executor": "nx:run-commands",
          "options": {
            "command": "tsc --build tsconfig.lib.json --pretty --verbose"
          }
        }
      }
    }
  },
  "sourceMap": {
    "targets": ["packages/foo/tsconfig.ts", "@nx/js/typescript"],
    "targets.build": ["packages/foo/tsconfig.ts", "@nx/js/typescript"]
  }
}
```

{% /project_details %}

Task sync generators can be thought of like the `dependsOn` property, but for generators instead of task dependencies.

To [register a generator](/docs/extending-nx/create-sync-generator) as a sync generator for a particular task, add the generator to the `syncGenerators` property of the task configuration.

## Global sync generators

Global sync generators are not associated with a particular task and are executed only when the `nx sync` or `nx sync:check` command is explicitly run. They are [registered](/docs/extending-nx/create-sync-generator) in the `nx.json` file with the `sync.globalGenerators` property.

## Sync the project graph and the file system

Nx processes the file system in order to [create the project graph](/docs/features/explore-graph) which is used to run tasks in the correct order and determine project dependencies. Sync generators allow you to also go the other direction and use the project graph to update the file system.

**File System:**

```text
└─ myorg
   ├─ apps
   │  ├─ app1
   │  └─ app2
   ├─ libs
   │  └─ lib
   ├─ nx.json
   └─ package.json
```

**Project Graph:**

{% graph title="Project Graph" height="200px" type="project" %}

```json
{
  "projects": [
    {
      "name": "app1",
      "type": "app",
      "data": {
        "tags": [],
        "targets": {
          "test": {}
        }
      }
    },
    {
      "name": "app2",
      "type": "app",
      "data": {
        "tags": [],
        "targets": {
          "test": {}
        }
      }
    },
    {
      "name": "lib",
      "type": "lib",
      "data": {
        "tags": [],
        "targets": {
          "test": {}
        }
      }
    }
  ],
  "dependencies": {
    "app1": [
      {
        "source": "app1",
        "target": "lib",
        "type": "static"
      }
    ],
    "app2": [
      {
        "source": "app2",
        "target": "lib",
        "type": "static"
      }
    ],
    "lib": []
  },
  "workspaceLayout": {
    "appsDir": "apps",
    "libsDir": "libs"
  },
  "affectedProjectIds": [],
  "focus": null,
  "groupByFolder": false,
  "exclude": []
}
```

{% /graph %}

The ability to update the file system from the project graph makes it possible to use the Nx project graph to change the behavior of other tools that are not part of the Nx ecosystem.

## Run `nx sync:check` in CI

Task sync generators are executed whenever their task is run, but global sync generators need to be triggered manually with `nx sync`. In order to effectively use sync generators, make sure to add `nx sync:check` to the beginning of your CI scripts so that CI can fail quickly if the code is out of sync. It is also helpful to run `nx sync` in a pre-commit or pre-push Git hook to encourage developers to commit code that is already in sync.

---
<!-- source: https://nx.dev/docs/concepts/synthetic-monorepos.md -->
## Synthetic Monorepos

Most organizations don't have a single giant monorepo. They have a handful of monorepos per team or domain, plus dozens of standalone repos. Consolidating everything into one repository is not just a technical challenge. The organizational side (bringing teams along, changing workflows, ensuring adoption) is often harder than the code migration itself.

Synthetic monorepos let you get monorepo benefits without that consolidation.

## What is a synthetic monorepo?

A synthetic monorepo connects separate repositories into a unified dependency graph without moving any code. Which repo depends on which, what a change affects downstream, how projects relate across teams: all of that becomes visible automatically.

![A synthetic monorepo connecting multiple monorepos and standalone repos into a unified dependency graph](../../../assets/concepts/synthetic-monorepo.svg)

Unlike a traditional monorepo where all code lives in one repository, a synthetic monorepo leaves each repository where it is. Instead, it builds a cross-repo graph that tooling can reason about, just as if the code were in one place.

## What synthetic monorepos enable

A synthetic monorepo addresses several downsides of a polyrepo setup:

**Visibility** — An automatic cross-repo dependency graph shows which repo depends on which and what a change affects downstream. Always up to date, discovered from actual code — not a manually maintained spreadsheet or catalog. Nx implements this through the [Workspace Graph](/docs/enterprise/polygraph).

**Coordination** — Cross-repo changes no longer require manually sequencing PRs, managing compatibility, and coordinating release order. Tooling on top of the graph enables impact analysis, coordinated changes, and conformance checking across repo boundaries.

**Governance** — Organizational standards apply across every connected repo through [conformance rules](/docs/enterprise/conformance). Scheduled [custom workflows](/docs/enterprise/custom-workflows) check repos continuously — even ones nobody has touched in months. Detection and enforcement happen automatically, not through tickets and follow-ups.

**CI intelligence** — [Affected detection](/docs/concepts/mental-model#affected-commands), [remote caching](/docs/concepts/how-caching-works), and [distributed task execution](/docs/concepts/ci-concepts/parallelization-distribution) work across the full graph, not just within a single repo.

**AI agents** — AI coding agents are [dramatically less effective in polyrepos](https://youtu.be/alIto5fqrfk) — they can only see one repo at a time, so cross-repo features require you to manually shuttle context between sessions. A synthetic monorepo gives agents cross-repo visibility, enabling coordinated changes, parallel execution, and automatic PR creation across boundaries. [Self-healing CI](/docs/features/ci-features/self-healing-ci) catches failures automatically.

## When to use a synthetic monorepo vs. a real monorepo

A real monorepo is the best option when you can consolidate. It gives you atomic commits, a single toolchain, and the simplest mental model.

A synthetic monorepo is the better starting point when:

- **Consolidation isn't feasible yet:** team autonomy concerns, divergent CI setups, or hundreds of repos make migration impractical.
- **You need cross-repo visibility now:** you can't wait months for a migration to see how projects relate across teams.
- **Teams need to stay autonomous:** each team keeps their repo, workflow, and release cadence while still participating in a unified graph.

The two aren't mutually exclusive. Start synthetic for org-wide visibility, then consolidate tightly coupled teams into real monorepos where it makes sense.

## Synthetic monorepos with Nx Polygraph

Nx implements synthetic monorepos through [Nx Polygraph](/docs/enterprise/polygraph). Polygraph connects existing repositories into a unified, intelligent graph that powers the visibility, coordination, and CI features described above. It works with any repo, even those that don't use Nx, and requires zero changes to target repos.

Learn more about [getting started with Nx Polygraph](/docs/enterprise/polygraph).

---
<!-- source: https://nx.dev/docs/concepts/task-pipeline-configuration.md -->
## What is a Task Pipeline

If you have a monorepo workspace (or modularized app), you rarely just run one task. Almost certainly there are relationships among the projects in the workspace and hence tasks need to follow a certain order.

As you can see in the graph visualization below, the `myreactapp` project depends on other projects. Therefore, when running the build for `myreactapp`, these dependencies need to be built first so that `myreactapp` can use the resulting build artifacts.

{% graph height="450px" %}

```json
{
  "projects": [
    {
      "name": "myreactapp",
      "type": "app",
      "data": {
        "tags": []
      }
    },
    {
      "name": "shared-ui",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "feat-products",
      "type": "lib",
      "data": {
        "tags": []
      }
    }
  ],
  "dependencies": {
    "myreactapp": [
      { "source": "myreactapp", "target": "feat-products", "type": "static" }
    ],
    "shared-ui": [],
    "feat-products": [
      {
        "source": "feat-products",
        "target": "shared-ui",
        "type": "static"
      }
    ]
  },
  "workspaceLayout": { "appsDir": "", "libsDir": "" },
  "affectedProjectIds": [],
  "focus": null,
  "groupByFolder": false
}
```

{% /graph %}

While you could manage these relationships on your own and set up custom scripts to build all projects in the proper order (e.g. first build `shared-ui`, then `feat-products` and finally `myreactapp`), that kind of approach is not scalable and would need constant maintenance as you keep changing and adding projects to your workspace.

This becomes even more evident when you run tasks in parallel. You cannot just naively run all of them at the same time. Instead, the task orchestrator needs to respect the order of the tasks so that it builds libraries first and then resumes building the apps that depend on those libraries in parallel.

![task-graph-execution](../../../assets/concepts/mental-model/task-graph-execution.svg)

Define task dependencies in the form of "rules", which are then followed when running tasks. There's a [detailed recipe](/docs/guides/tasks--caching/defining-task-pipeline) but here's the high-level overview:

```jsonc title="nx.json"
{
  ...
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build", "prebuild"]
    },
    "test": {
      "dependsOn": ["build"]
    }
  }
}
```

{% aside type="caution" title="Older versions of Nx" %}
Older versions of Nx used targetDependencies instead of targetDefaults. `targetDependencies` was removed in version 16, with `targetDefaults` replacing its use case.
{% /aside %}

When running `nx test myproj`, the above configuration would tell Nx to

1. Run the `test` command for `myproj`
2. But since there's a dependency defined from `test` to `build` (see `"dependsOn" :["build"]`), Nx runs `build` for `myproj` first.
3. `build` itself defines a dependency on `prebuild` (on the same project) as well as `build` of all the dependencies. Therefore, it will run the `prebuild` script and will run the `build` script for all the dependencies.

Note, Nx doesn't have to run all builds before it starts running tests. The task orchestrator will run as many tasks in parallel as possible as long as the constraints are met.

These rules can be defined globally in the `nx.json` file or locally per project in the `package.json` or `project.json` files.

## Configure it for your own project

{% aside type="tip" title="Learn by doing" %}
Try the [Configuring Tasks](/docs/getting-started/tutorials/configuring-tasks) tutorial to apply these concepts in your own workspace.
{% /aside %}

Learn about all the details of how to configure [task pipelines in the according recipe section](/docs/guides/tasks--caching/defining-task-pipeline).

---
<!-- source: https://nx.dev/docs/concepts/types-of-configuration.md -->
## Managing Configuration Files

Besides providing caching and task orchestration, Nx also helps incorporate numerous tools and frameworks into your repo. With all these pieces of software commingling, you can end up with a lot of configuration files. Nx plugins help to abstract away some of the difficulties of managing this configuration, but the configuration is all still accessible, in case there is a particular setting that you need to change.

## Different kinds of configuration

When discussing configuration, it helps to categorize the configuration settings in two dimensions:

- **Type** - The two different types we'll discuss are Nx configuration and tooling configuration. Tooling can be any framework or tool that you use in your repo (i.e. React, Jest, Playwright, Typescript, etc)
- **Specificity** - There are two different levels of specificity: global and project-specific. Project-specific configuration is merged into and overwrites global configuration.

For example, Jest has a global `/jest.config.ts` file and a project-specific `/apps/my-app/jest.config.ts` file that extends it.

|                  | Nx                          | Tooling                       |
| ---------------- | --------------------------- | ----------------------------- |
| Global           | `/nx.json`                  | `/jest.config.ts`             |
| Project-specific | `/apps/my-app/project.json` | `/apps/my-app/jest.config.ts` |

## How does Nx help manage tooling configuration?

In a repository with many different projects and many different tools, there will be a lot of tooling configuration. Nx helps reduce the complexity of managing that configuration in two ways:

1. Abstracting away common tooling configuration settings so that if your project is using the tool in the most common way, you won't need to worry about configuration at all. The default settings for any Nx plugin executor are intended to work without modification for most projects in the community.
2. Allowing you to [provide `targetDefaults`](/docs/guides/tasks--caching/reduce-repetitive-configuration) so that the most common settings for projects in your repo can all be defined in one place. Then, only projects that are exceptions need to overwrite those settings. With the judicious application of this method, larger repositories can actually have less lines of configuration after adding Nx than before.

## Determining the value of a configuration property

If you need to track down the value of a specific configuration property (say `runInBand` for `jest` on the `/apps/my-app` project) you need to look in the following locations. The configuration settings are merged with priority being given to the file higher up in the list.

1. In `/apps/my-app/project.json`, the `options` listed under the `test` target that uses the `@nx/jest:jest` executor.
2. In `/nx.json`, the `targetDefaults` listed for the `test` target.
3. One of the `test` target options references `/apps/my-app/jest.config.ts`
4. Which extends `/jest.config.ts`

```text
repo/
├── apps/
│   └── my-app/
│       ├── jest.config.ts
│       └── project.json
├── jest.config.ts
└── nx.json
```

## More information

{% aside type="tip" title="Learn by doing" %}
Try the [Configuring Tasks](/docs/getting-started/tutorials/configuring-tasks) tutorial to apply these concepts in your own workspace.
{% /aside %}

- [Nx Configuration](/docs/reference/nx-json)
- [Project Configuration](/docs/reference/project-configuration)

---
<!-- source: https://nx.dev/docs/concepts/typescript-project-linking.md -->
## TypeScript Project Linking

{% youtube src="https://youtu.be/D9D8KNffyBk" title="TypeScript Monorepos Done Right!" /%}

The naive way to reference code in a separate project is to use a relative path in the `import` statement.

```ts
import { someFunction } from '../../teamA/otherProject';

const result = someFunction();
```

The problem with this approach is that all your import statements become tied to your folder structure. Developers need to know the full path to any project from which they want to import code. Also, if `otherProject` ever moves locations, there will be superfluous code changes across the entire repository.

A more ergonomic solution is to reference your local projects as if they were external npm packages and then use a project linking mechanism to automatically resolve the project file path behind the scenes.

```ts
import { someFunction } from '@myorg/otherProject';

const result = someFunction();
```

There are two different methods that Nx supports for linking TypeScript projects: package manager workspaces and TypeScript path aliases. Project linking with TS path aliases was available with Nx before package managers offered a workspaces project linking approach. The Nx Team has since added full support for workspaces because (1) it has become more common across the TypeScript ecosystem and (2) packages will be resolved using native node module resolution instead of relying on TypeScript. Nx provides a cohesive experience for repositories using TypeScript path aliases without project references or repositories using package manager workspaces with TypeScript project references enabled.

## Project linking with workspaces

Create a new Nx workspace that links projects with package manager workspaces:

```shell
npx create-nx-workspace
```

{% aside type="note" title="Opt-out of Workspaces" %}
You can opt-out of workspaces by running `npx create-nx-workspace --no-workspaces`.
{% /aside %}

### Set up package manager workspaces

The configuration for package manager workspaces varies based on which package manager you're using.

{% tabs %}
{% tabitem label="npm" %}

```json title="package.json"
{
  "workspaces": ["apps/*", "packages/*"]
}
```

Defining the `workspaces` property in the root `package.json` file lets npm know to look for other `package.json` files in the specified folders. With this configuration in place, all the dependencies for the individual projects will be installed in the root `node_modules` folder when `npm install` is run in the root folder. Also, the projects themselves will be linked in the root `node_modules` folder to be accessed as if they were npm packages.

If you want to reference a local library project with its own `build` task, you should include the library in the `devDependencies` of the application/library's `package.json` with `*` specified as the library's version. `*` tells npm to use whatever version of the project is available.

```json title="/apps/my-app/package.json"
{
  "devDependencies": {
    "@my-org/some-project": "*"
  }
}
```

{% /tabitem %}
{% tabitem label="yarn" %}

```json title="package.json"
{
  "workspaces": ["apps/*", "packages/*"]
}
```

Defining the `workspaces` property in the root `package.json` file lets yarn know to look for other `package.json` files in the specified folders. With this configuration in place, all the dependencies for the individual projects will be installed in the root `node_modules` folder when `yarn` is run in the root folder. Also, the projects themselves will be linked in the root `node_modules` folder to be accessed as if they were npm packages.

If you want to reference a local library project with its own `build` task, you should include the library in the `devDependencies` of the application/library's `package.json` with `workspace:*` specified as the library's version. [`workspace:*` tells yarn that the project is in the same repository](https://yarnpkg.com/features/workspaces) and not an npm package. You want to specify local projects as `devDependencies` instead of `dependencies` so that the library is not included twice in the production bundle of the application.

```json title="/apps/my-app/package.json"
{
  "devDependencies": {
    "@my-org/some-project": "*"
  }
}
```

{% /tabitem %}
{% tabitem label="bun" %}

```json title="package.json"
{
  "workspaces": ["apps/*", "packages/*"]
}
```

Defining the `workspaces` property in the root `package.json` file lets bun know to look for other `package.json` files in the specified folders. With this configuration in place, all the dependencies for the individual projects will be installed in the root `node_modules` folder when `bun install` is run in the root folder. Also, the projects themselves will be linked in the root `node_modules` folder to be accessed as if they were npm packages.

If you want to reference a local library project with its own `build` task, you should include the library in the `devDependencies` of the application/library's `package.json` with `workspace:*` specified as the library's version. [`workspace:*` tells bun that the project is in the same repository](https://bun.sh/docs/install/workspaces) and not an npm package. You want to specify local projects as `devDependencies` instead of `dependencies` so that the library is not included twice in the production bundle of the application.

```json title="/apps/my-app/package.json"
{
  "devDependencies": {
    "@my-org/some-project": "workspace:*"
  }
}
```

{% /tabitem %}
{% tabitem label="pnpm" %}

```yaml title="pnpm-workspace.yaml"
packages:
  - 'apps/*'
  - 'packages/*'
```

Defining the `packages` property in the root `pnpm-workspaces.yaml` file lets pnpm know to look for project `package.json` files in the specified folders. With this configuration in place, all the dependencies for the individual projects will be installed in the root `node_modules` folder when `pnpm install` is run in the root folder.

If you want to reference a local library project from an application, you need to include the library in the `devDependencies` of the application's `package.json` with `workspace:*` specified as the library's version. [`workspace:*` tells pnpm that the project is in the same repository](https://pnpm.io/workspaces#workspace-protocol-workspace) and not an npm package. You want to specify local projects as `devDependencies` instead of `dependencies` so that the library is not included twice in the production bundle of the application.

```json title="/apps/my-app/package.json"
{
  "devDependencies": {
    "@my-org/some-project": "workspace:*"
  }
}
```

{% /tabitem %}
{% /tabs %}

### Set up TypeScript project references

With workspaces enabled, you can also configure TypeScript project references to speed up your build and typecheck tasks.

The root `tsconfig.base.json` should contain a `compilerOptions` property and no other properties. `compilerOptions.composite` and `compilerOptions.declaration` should be set to `true`. `compilerOptions.paths` should not be set.

```jsonc title="tsconfig.base.json"
{
  "compilerOptions": {
    // Required compiler options
    "composite": true,
    "declaration": true,
    "declarationMap": true,
    // Other options...
  },
}
```

The root `tsconfig.json` file should extend `tsconfig.base.json` and not include any files. It needs to have `references` for every project in the repository so that editor tooling works correctly.

```jsonc title="tsconfig.json"
{
  "extends": "./tsconfig.base.json",
  "files": [], // intentionally empty
  "references": [
    // UPDATED BY PROJECT GENERATORS
    // All projects in the repository
  ],
}
```

#### Individual project TypeScript configuration

Each project's `tsconfig.json` file should extend the `tsconfig.base.json` file and list `references` to the project's dependencies.

```jsonc title="packages/cart/tsconfig.json"
{
  "extends": "../../tsconfig.base.json",
  "files": [], // intentionally empty
  "references": [
    // UPDATED BY NX SYNC
    // All project dependencies
    {
      "path": "../utils",
    },
    // This project's other tsconfig.*.json files
    {
      "path": "./tsconfig.lib.json",
    },
    {
      "path": "./tsconfig.spec.json",
    },
  ],
}
```

Each project's `tsconfig.lib.json` file extends the `tsconfig.base.json` file and adds `references` to the `tsconfig.lib.json` files of project dependencies.

```jsonc title="packages/cart/tsconfig.lib.json"
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    // Any overrides
  },
  "include": ["src/**/*.ts"],
  "exclude": [
    // exclude config and test files
  ],
  "references": [
    // UPDATED BY NX SYNC
    // tsconfig.lib.json files for project dependencies
    {
      "path": "../utils/tsconfig.lib.json",
    },
  ],
}
```

The project's `tsconfig.spec.json` does not need to reference project dependencies.

```jsonc title="packages/cart/tsconfig.spec.json"
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    // Any overrides
  },
  "include": [
    // test files
  ],
  "references": [
    // tsconfig.lib.json for this project
    {
      "path": "./tsconfig.lib.json",
    },
  ],
}
```

### TypeScript project references performance benefits

{% youtube src="https://youtu.be/O2xBQJMTs9E" title="Why TypeScript Project References Make Your CI Faster!" /%}

Using TypeScript project references improves both the speed and memory usage of build and typecheck tasks. The repository below contains benchmarks showing the difference between running typecheck with and without using TypeScript project references.

{% github_repository title="TypeScript Project References Benchmark" url="https://github.com/jaysoo/typecheck-timings" /%}

Here are the baseline typecheck task performance results.

```text
Typecheck without using project references: 186 seconds, max memory 6.14 GB
```

Using project references allows the TypeScript compiler to individually check the types for each project and store the results of that calculation in a `.tsbuildinfo` file for later use. Because of this, the TypeScript compiler does not need to load the entire codebase into memory at the same time, which you can see from the decreased memory usage on the first run with project references enabled.

```text
Typecheck with project references first run: 175 seconds, max memory 945 MB
```

Once the `.tsbuildinfo` files have been created, subsequent runs will be much faster.

```text
Typecheck with all `.tsbuildinfo` files created: 25 seconds, max memory 429 MB
```

Even if some projects have been updated and individual projects need to be type checked again, the TypeScript compiler can still use the cached `.tsbuildinfo` files for any projects that were not affected. This is very similar to the way Nx caching and affected features work.

```text
Typecheck (1 pkg updated): 36.33 seconds, max memory 655.14 MB
Typecheck (5 pkg updated): 48.21 seconds, max memory 702.96 MB
Typecheck (25 pkg updated): 65.25 seconds, max memory 666.78 MB
Typecheck (100 pkg updated): 80.69 seconds, max memory 664.58 MB
Typecheck (1 nested leaf pkg updated): 26.66 seconds, max memory 407.54 MB
Typecheck (2 nested leaf pkg updated): 31.17 seconds, max memory 889.86 MB
Typecheck (1 nested root pkg updated): 26.67 seconds, max memory 393.78 MB
```

These performance benefits will be more noticeable for larger repositories, but even small code bases will see some benefits.

### Local TypeScript path aliases

If you define TS path aliases in an individual project's tsconfig files, you should not define them also in the root `tsconfig.base.json` file because TypeScript does not merge the paths. The paths defined in the root file would be completely overwritten by the ones defined in the project tsconfig. For instance, you could define paths like this in an application's tsconfig file.

```jsonc title="/apps/my-remix-app/tsconfig.app.json"
{
  "compilerOptions": {
    "paths": {
      "#app/*": ["./app/*"],
      "#tests/*": ["./tests/*"],
      "@/icon-name": [
        "./app/components/ui/icons/name.d.ts",
        "./types/icon-name.d.ts",
      ],
    },
  },
}
```

## Project linking with TypeScript path aliases

{% aside type="caution" title="Path Aliases Overwrite Extended Configuration Files" %}
If you define path aliases in a project's specific `tsconfig.*.json` file, those path aliases will overwrite the path aliases defined in the root `tsconfig.base.json`. You can't use both project-level path aliases and root path aliases.
{% /aside %}

Linking projects with TypeScript path aliases is configured entirely in the tsconfig files. You can still use package manager workspaces to enable you to define separate third-party dependencies for individual projects, but the local project linking is done by TypeScript instead of the package manager.

The paths for each library are defined in the root `tsconfig.base.json` and each project's `tsconfig.json` should extend that file. Note that application projects do not need to have a path defined because no projects will import code from a top-level application.

```jsonc title="/tsconfig.base.json"
{
  "compilerOptions": {
    // common compiler option defaults for all projects
    // ...
    // These compiler options must be false or undefined
    "composite": false,
    "declaration": false,
    "paths": {
      // These paths are automatically added by Nx library generators
      "@myorg/shared-ui": ["packages/shared-ui/src/index.ts"],
      // ...
    },
  },
}
```


# Features

---
<!-- source: https://nx.dev/docs/features.md -->
## Features

Learn the core features of Nx with in depth guides.

{% index_page_cards path="features" /%}

---
<!-- source: https://nx.dev/docs/features/automate-updating-dependencies.md -->
## Automate Updating Dependencies

{% youtube
src="https://youtu.be/A0FjwsTlZ8A"
title="How Automated Code Migrations Work"
/%}

Keeping your tooling up to date is crucial for the health of your project. Tooling maintenance work can be tedious and time consuming, though. The **Nx migrate** functionality provides a way for you to

- automatically update your **`package.json` dependencies**
- migrate your **configuration files** (e.g. Jest, ESLint, Nx config)
- **adjust your source code** to match the new versions of packages (e.g., migrating across breaking changes)

To update your workspace, run:

```shell
npx nx@latest migrate latest
```

{% aside type="note" title="Visual migration tool from Nx Console" %}
Want a more visual and guided way to migrate? Check out the [Migrate UI](/docs/guides/nx-console/console-migrate-ui) that comes with the [Nx Console extension](/docs/getting-started/editor-setup).
{% /aside %}

## How does it work?

Nx knows where its configuration files are located and ensures they match the expected format. This automated update process, commonly referred to as "migration," becomes even **more powerful when you leverage [Nx plugins](/docs/plugin-registry)**. Each plugin can provide migrations for its area of competency.

For example, the [Nx React plugin](/docs/technologies/react/introduction) knows where to look for React and Nx specific configuration files and knows how to apply certain changes when updating to a given version of React.

In the example below, the React plugin defines a migration script (`./src/migrations/.../add-babel-core`) that runs when upgrading to Nx `16.7.0-beta.2` (or higher).

```json {% meta="{7,8}" %}
// migrations.json
{
  "generators": {
    ...
    "add-babel-core": {
       ...
      "version": "16.7.0-beta.2",
      "implementation": "./src/migrations/update-16-7-0/add-babel-core"
    },
  },
}
```

When running `nx migrate latest`, Nx parses all the available plugins and their migration files and applies the necessary changes to your workspace.

## How do i upgrade my Nx workspace?

Updating your Nx workspace happens in three steps:

1. The **installed dependencies**, including the `package.json` and `node_modules`, are updated.
2. Nx produces a `migrations.json` file containing the **migrations to be run** based on your workspace configuration. You can inspect and adjust the file. Run the migrations to update your configuration files and source code.
3. Optionally, you can remove the `migrations.json` file or keep it to re-run the migration in different Git branches.

You can intervene at each step and make adjustments as needed for your specific workspaces. This is especially important in large codebases where you might want to control the changes more granularly.

### Step 1: update dependencies and generate migrations

First, run the `migrate` command:

```shell
nx migrate latest
```

Note you can also specify an exact version by replacing `latest` with `nx@<version>`.

{% aside title="Update One Major Version at a Time" %}
To avoid potential issues, it is [recommended to update one major version of Nx at a time](/docs/guides/tips-n-tricks/advanced-update#one-major-version-at-a-time-small-steps).
{% /aside %}

This results in:

- The `package.json` being updated
- A `migrations.json` being generated if there are pending migrations.

At this point, no packages have been installed, and no other files have been touched.

Now, you can **inspect `package.json` to see if the changes make sense**. Sometimes the migration can update a package to a version that is either not allowed or conflicts with another package. Feel free to manually apply the desired adjustments. Also look at the `migrations.json` for the type of migrations that are going to be applied.

### Step 2: Run migrations

You can now run the actual code migrations that were generated in the `migrations.json` in the previous step.

```shell
nx migrate --run-migrations
```

Depending on the migrations that ran, this might **update your source code** and **configuration files** in your workspace. All the changes will be unstaged ready for you to review and commit yourself.

{% aside type="tip" title="Migrations are version specific" %}
Note that each Nx plugin is able to provide a set of migrations which are relevant to particular versions of the package. Hence `migrations.json` will only contain migrations which are appropriate for the update you are currently applying.
{% /aside %}

### Step 3: Clean up

After you run all the migrations, you can remove `migrations.json` and commit any outstanding changes.

Note: You may want to keep the `migrations.json` until every branch that was created before the migration has been merged. Leaving the `migrations.json` in place allows devs to run `nx migrate --run-migrations` to apply the same migration process to their newly merged code as well.

### Step 4: Update community plugins (Optional)

If you have any [Nx community plugins](/docs/plugin-registry) installed you need to migrate them individually (assuming they provide migration scripts) by using the following command:

```shell
nx migrate my-plugin
```

For a list of all the plugins you currently have installed, run:

```shell
nx report
```

## Keep Nx packages on the same version

When you run `nx migrate`, the `nx` package and all the `@nx/` packages get updated to the same version. It is important to [keep these versions in sync](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync) to have Nx work properly.

As long as you run `nx migrate` instead of manually changing the version numbers, you shouldn't have to worry about it. Also, when you add a new plugin, use `nx add <plugin>` to automatically install the version that matches your repository's version of Nx.

## Need to opt-out of some migrations?

Sometimes you need to temporarily opt-out from some migrations because your workspace is not ready yet. You can manually adjust the `migrations.json` or run the update with the `--interactive` flag to choose which migrations you accept.

Find more details in our [Advanced Update Process](/docs/guides/tips-n-tricks/advanced-update) guide.

---
<!-- source: https://nx.dev/docs/features/cache-task-results.md -->
## Cache Task Results

{% youtube src="https://youtu.be/o-6jb78uuP0" title="Remote Caching with Nx Replay" /%}

Rebuilding and retesting the same code repeatedly is costly. Nx offers a sophisticated and battle-tested computation caching system that ensures **code is never rebuilt twice**. This:

- drastically **speeds up your task execution times** while developing locally and even more [in CI](/docs/features/ci-features/remote-cache)
- **saves you money on CI/CD costs** by reducing the number of tasks that need to be executed

Nx **restores both the terminal output and the files** created from running the task (e.g., your build or dist directory). If you want to learn more about the conceptual model behind Nx caching, read [How Caching Works](/docs/concepts/how-caching-works).

## Define cacheable tasks

{% tabs syncKey="nx-version" %}
{% tabitem label="Nx >= 17" %}

To enable caching for `build` and `test`, edit the `targetDefaults` property in `nx.json` to include the `build` and `test` tasks:

```json
// nx.json
{
  "targetDefaults": {
    "build": {
      "cache": true
    },
    "test": {
      "cache": true
    }
  }
}
```

{% /tabitem %}
{% tabitem label="Nx < 17" %}

To enable caching for `build` and `test`, edit the `cacheableOperations` property in `nx.json` to include the `build` and `test` tasks:

```json
// nx.json
{
  "tasksRunnerOptions": {
    "default": {
      "runner": "nx/tasks-runners/default",
      "options": {
        "cacheableOperations": ["build", "test"]
      }
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

{% aside type="note" title="Cacheable operations need to be side effect free" %}
This means that given the same input they should always result in
the same output. As an example, e2e test runs that hit the backend API cannot be cached as the backend might influence
the result of the test run.
{% /aside %}

## Enable remote caching

By default, Nx caches task results locally. The biggest benefit of caching comes from using remote caching in CI, where you can **share the cache between different runs**. Nx comes with a managed remote caching solution built on top of Nx Cloud.

To enable remote caching, connect your workspace to [Nx Cloud](https://nx.dev/nx-cloud) by running the following command:

```shell
npx nx@latest connect
```

Learn more about [remote caching with Nx Cloud](/docs/features/ci-features/remote-cache).

## Fine-tune caching with inputs and outputs

Nx caching feature starts with sensible defaults, but you can also **fine-tune the defaults** to control exactly what gets cached and when. There are two main options that control caching:

- **Inputs -** define what gets included as part of the calculated hash (e.g. files, environment variables, etc.)
- **Outputs -** define folders where files might be placed as part of the task execution.

You can define these inputs and outputs at the project level (`project.json`) or globally for all projects (in `nx.json`).

Take the following example: we want to exclude all `*.md` files from the cache so that whenever we change the README.md (or any other markdown file), it does _not_ invalidate the build cache. We also know that the build output will be stored in a folder named after the project name in the `dist` folder at the root of the workspace.

To achieve this, we can add `inputs` and `outputs` definitions globally for all projects or at a per-project level:

{% tabs %}
{% tabitem label="Globally" %}

```json
// nx.json
{
  "targetDefaults": {
    "build": {
      "inputs": ["{projectRoot}/**/*", "!{projectRoot}/**/*.md"],
      "outputs": ["{workspaceRoot}/dist/{projectName}"]
    }
  }
}
```

{% /tabitem %}
{% tabitem label="Project Level (project.json)" %}

```json
// packages/some-project/project.json
{
  "name": "some-project",
  "targets": {
    "build": {
      ...
      "inputs": ["!{projectRoot}/**/*.md"],
      "outputs": ["{workspaceRoot}/dist/apps/some-project"],
      ...
    }
    ...
  }
}
```

{% /tabitem %}
{% tabitem label="Project Level (package.json)" %}

```json
// packages/some-project/package.json
{
  "name": "some-project",
  "nx": {
    "targets": {
      "build": {
        ...
        "inputs": ["!{projectRoot}/**/*.md"],
        "outputs": ["{workspaceRoot}/dist/apps/some-project"],
        ...
      }
      ...
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

Note that you only need to define output locations if they differ from the usual `dist` or `build` directory, which Nx automatically recognizes.

Learn more [about configuring inputs including `namedInputs`](/docs/guides/tasks--caching/configure-inputs).

## Configure caching automatically

When using [Nx plugins](/docs/concepts/nx-plugins), many tasks have caching configured automatically, saving you the effort of manual setup. **Nx plugins can [automatically infer tasks](/docs/concepts/inferred-tasks) and configure caching** based on your underlying tooling configuration files.

For example, if you add the `@nx/vite` plugin using the following command...

```shell
npx nx add @nx/vite
```

...it automatically detects your `vite.config.ts` file, infers the tasks you'd be able to run, such as `build`, and **automatically configures the cache settings** for these tasks as well as the [task pipeline](/docs/concepts/task-pipeline-configuration) (e.g., triggering dependent builds).

This means **you don't need to manually specify cacheable operations for Vite tasks** and the cache setting such as inputs and outputs are always in sync with the `vite.config.ts` file.

To view the task settings that have been automatically configured by a plugin, use the following command:

```shell
nx show project <project-name> --web
```

Alternatively, you can view these directly in your editor by installing [Nx Console](/docs/getting-started/editor-setup).

Learn more details about [Nx plugins](/docs/concepts/nx-plugins) and [inferred tasks](/docs/concepts/inferred-tasks).

## Troubleshoot cache settings

Caching is hard. If you run into issues, check out the following resources:

- [Debug cache misses](/docs/troubleshooting/troubleshoot-cache-misses)
- [Turn off or skip the cache](/docs/guides/tasks--caching/skipping-cache)
- [Change the cache location](/docs/guides/tasks--caching/change-cache-location)
- [Clear the local or remote cache](/docs/reference/nx-commands#nx-reset)

---
<!-- source: https://nx.dev/docs/features/ci-features.md -->
## Orchestration & CI with Nx Cloud

{% youtube src="https://www.youtube.com/watch?v=cDBihpB3SbI" title="Nx and Nx Cloud" width="100%" /%}

CI is challenging and it's **not your fault**. It's a fundamental issue with how the current, traditional CI execution model works. Nx Cloud adopts a new **task-based** CI model that overcomes slowness and unreliability of the current VM-based CI model.

Nx Cloud improves many aspects of the CI/CD process:

- **Speed** - 30% - 70% faster CI (based on reports from our clients)
- **Cost** - 40% - 75% reduction in CI costs (observed on the Nx OSS monorepo)
- **Reliability** - by automatically identifying flaky tasks (e2e tests in particular) and re-running them

## Connect your workspace to Nx Cloud

Run the following command in your Nx workspace (make sure you have it pushed to a remote repository first):

```shell
npx nx connect
```

This connects your workspace to Nx Cloud and enables remote caching and CI features. For more details, [follow our in-depth guide](/docs/guides/nx-cloud/setup-ci) for setting up CI with Nx.

## How Nx Cloud improves CI

In traditional CI models, work is statically assigned to CI machines. This creates inefficiencies that many teams experience at scale.

Nx Cloud uses a **task-based approach to dynamically assign tasks** to agent machines. CI becomes scalable, maintainable, and more reliable because Nx Cloud coordinates work among agent machines automatically and acts on individual tasks directly.

For example:

- An agent machine fails in a setup step — Nx Cloud automatically reassigns the work to other agent machines.
- More work needs to run in CI — add more agent machines, Nx Cloud automatically assigns available work.
- Known flaky tasks waste CI time on needed reruns — Nx Cloud automatically detects flaky tasks and reruns them in the current CI execution.

[Learn how our customers use Nx Cloud](https://nx.dev/blog?filterBy=customer+story) to scale their workspaces and be more efficient.

## Nx Cloud features

{% index_page_cards path="features/ci-features" /%}

## Learn more

- [Blog post: Reliable CI: A new execution model fixing both flakiness and slowness](https://nx.dev/blog/reliable-ci-a-new-execution-model-fixing-both-flakiness-and-slowness)
- [Live stream: Unlock the secret of fast CI - Hands-on session](https://www.youtube.com/live/rkLKaqLeDa0)
- [YouTube: 10x Faster e2e Tests](https://www.youtube.com/watch?v=0YxcxIR7QU0)

---
<!-- source: https://nx.dev/docs/features/ci-features/affected.md -->
## Run Only Tasks Affected by a PR

{% youtube src="https://youtu.be/q-cu5Lw3DoE" title="Only Run Tasks for Projects That Changed" /%}

As your workspace grows, re-testing, re-building, and re-linting **all projects becomes too slow**. To address this, Nx comes with an "affected" command. Using this command, Nx

- determines the minimum set of **projects that are affected by the change**
- only runs tasks on those affected projects

This drastically improves the speed of your CI and reduces the amount of compute needed. This advantage is further enhanced when [paired with remote caching and distribution](#best-paired-with-remote-caching-and-distribution).

{% graph title="Making a change in lib10 only affects a sub-part of the project graph (shown in purple)" height="400px" %}

```json
{
  "projects": [
    {
      "type": "app",
      "name": "app1",
      "data": {}
    },
    {
      "type": "app",
      "name": "app2",
      "data": {}
    },
    {
      "type": "lib",
      "name": "lib1",
      "data": {}
    },
    {
      "type": "lib",
      "name": "lib2",
      "data": {}
    },
    {
      "type": "lib",
      "name": "lib3",
      "data": {}
    },
    {
      "type": "lib",
      "name": "lib4",
      "data": {}
    },
    {
      "type": "lib",
      "name": "lib5",
      "data": {}
    },
    {
      "type": "lib",
      "name": "lib6",
      "data": {}
    },
    {
      "type": "lib",
      "name": "lib7",
      "data": {}
    },
    {
      "type": "lib",
      "name": "lib8",
      "data": {}
    },
    {
      "type": "lib",
      "name": "lib9",
      "data": {}
    },
    {
      "type": "lib",
      "name": "lib10",
      "data": {}
    },
    {
      "type": "lib",
      "name": "lib11",
      "data": {}
    },
    {
      "type": "lib",
      "name": "lib12",
      "data": {}
    }
  ],
  "groupByFolder": false,
  "workspaceLayout": {
    "appsDir": "apps",
    "libsDir": "libs"
  },
  "dependencies": {
    "app1": [
      {
        "target": "lib1",
        "source": "app1",
        "type": "direct"
      },
      {
        "target": "lib2",
        "source": "app1",
        "type": "direct"
      }
    ],
    "app2": [
      {
        "target": "lib4",
        "source": "app2",
        "type": "direct"
      },
      {
        "target": "lib5",
        "source": "app2",
        "type": "direct"
      },
      {
        "target": "lib6",
        "source": "app2",
        "type": "direct"
      }
    ],
    "lib1": [
      {
        "target": "lib7",
        "source": "lib1",
        "type": "direct"
      },
      {
        "target": "lib8",
        "source": "lib1",
        "type": "direct"
      }
    ],
    "lib2": [
      {
        "target": "lib3",
        "source": "lib2",
        "type": "direct"
      }
    ],
    "lib3": [
      {
        "target": "lib8",
        "source": "lib3",
        "type": "direct"
      }
    ],
    "lib4": [
      {
        "target": "lib3",
        "source": "lib4",
        "type": "direct"
      },
      {
        "target": "lib9",
        "source": "lib4",
        "type": "direct"
      },
      {
        "target": "lib10",
        "source": "lib4",
        "type": "direct"
      }
    ],
    "lib5": [
      {
        "target": "lib10",
        "source": "lib5",
        "type": "direct"
      },
      {
        "target": "lib11",
        "source": "lib5",
        "type": "direct"
      },
      {
        "target": "lib12",
        "source": "lib5",
        "type": "direct"
      }
    ],
    "lib6": [
      {
        "target": "lib12",
        "source": "lib6",
        "type": "direct"
      }
    ],
    "lib7": [],
    "lib8": [],
    "lib9": [],
    "lib10": [],
    "lib11": [],
    "lib12": []
  },
  "affectedProjectIds": ["lib10", "lib4", "lib5", "app2"]
}
```

{% /graph %}

## Using Nx affected commands

To leverage this feature, use the following command when running your tasks, particularly on CI:

```shell
nx affected -t <task>
```

When you run `nx affected -t test`, Nx will:

- Use Git to determine the files you changed in your PR.
- Use the [project graph](/docs/features/explore-graph) to determine which projects the files belong to.
- Determine which projects depend on the projects you modified.

Once the projects are identified, Nx runs the tasks you specified on that subset of projects.

You can also visualize the affected projects using the [Nx graph](/docs/features/explore-graph). Simply run:

```shell
nx graph --affected
```

## Best paired with remote caching and distribution

Using `nx affected` is a powerful tool to reduce the amount of compute that needs to be run. However, this might not be sufficient to significantly speed up your CI pipeline. For example:

- If you're modifying a **project that is used by a large portion** of your monorepo projects, you might end up running tasks for almost all the projects in the workspace.
- If you have a set of 10 projects affected by a PR and you continue making changes, you will **always end up running tasks for those 10 projects**. The set of affected projects doesn't change but is always calculated with respect to your last successful run on the main branch.

This is why Nx Affected is best paired with [remote caching](/docs/features/ci-features/remote-cache) and [distributed task execution](/docs/features/ci-features/distribute-task-execution).

## Configure affected on CI

To understand which projects are affected, Nx uses the Git history and the [project graph](/docs/features/explore-graph). Git knows which files changed, and the Nx project graph knows which projects those files belong to.

The affected command takes a `base` and `head` commit. The default `base` is your `main` branch, and the default `head` is your current file system. This is generally what you want when developing locally, but in CI, you need to customize these values.

```shell
nx affected -t build --base=origin/main --head=$PR_BRANCH_NAME # where PR_BRANCH_NAME is defined by your CI system
nx affected -t build --base=origin/main~1 --head=origin/main # rerun what is affected by the last commit in main
```

You can also set the base and head SHAs as environment variables:

```shell
NX_BASE=origin/main~1
NX_HEAD=origin/main
```

**The recommended approach is to set the base SHA to the latest successful commit** on the `main` branch. This ensures that all changes since the last successful CI run are accounted for.

See our guides to get the [last successful CI run for your CI provider](/docs/guides/nx-cloud/setup-ci#get-the-commit-of-the-last-successful-build).

## Ignoring files from affected commands

Nx provides two methods to exclude glob patterns (files and folders) from `affected:*` commands:

- Glob patterns defined in your `.gitignore` file are ignored.
- Glob patterns defined in an optional `.nxignore` file are ignored.

## Marking projects affected by dependency updates

By default, Nx will mark all projects as affected whenever your package manager's lock file changes. This behavior is a failsafe in case Nx misses a project that should be affected by a dependency update. If you'd like to opt into smarter behavior, you can configure Nx to only mark projects as affected if they actually depend on the updated packages.

```json
// nx.json
{
  "pluginsConfig": {
    "@nx/js": {
      "projectsAffectedByDependencyUpdates": "auto"
    }
  }
}
```

The flag `projectsAffectedByDependencyUpdates` can be set to `auto`, `all`, or an array that contains project specifiers. The default value is `all`.

## Not using git

If you aren't using Git, you can pass `--files` to any affected command to indicate what files have been changed.

---
<!-- source: https://nx.dev/docs/features/ci-features/distribute-task-execution.md -->
## Distribute Task Execution (Nx Agents)

{% youtube
src="https://youtu.be/XS-exYYP_Gg"
title="Nx Agents Walkthrough"
/%}

Nx Agents is a **distributed task execution system that intelligently allocates tasks across multiple machines**, optimizing your CI pipeline for speed and efficiency. While using [Nx Affected](/docs/features/ci-features/affected) and [remote caching (Nx Replay)](/docs/features/ci-features/remote-cache) can significantly speed up your CI pipeline, you might still encounter bottlenecks as your codebase scales. Combining affected runs and remote caching with task distribution is key to maintaining low CI times. Nx Agents handles this distribution efficiently, avoiding the complexity and maintenance required if you were to set it up manually.

![Nx Cloud visualization of how tasks are being distributed with Nx Agents](../../../../assets/features/nx-agents-live-chart.avif)

Nx Agents offer several key advantages:

- **Declarative Configuration:** No maintenance is required as your monorepo evolves, thanks to a declarative setup.
- **Efficient Task Replay:** By leveraging [remote caching](/docs/features/ci-features/remote-cache), tasks can be replayed efficiently across machines, enhancing distribution speed.
- **Intelligent Task Distribution:** Tasks are distributed based on historical run times and dependencies, ensuring correct and optimal execution.
- **Dynamic Resource Allocation:** Agents are [allocated dynamically based on the size of the PR](/docs/features/ci-features/dynamic-agents), balancing cost and speed.
- **Seamless CI Integration:** Easily adopt Nx Agents with your [existing CI provider](/docs/guides/nx-cloud/setup-ci), requiring minimal setup changes.
- **Simple Activation:** Enable distribution with just a [single line of code](#enable-nx-agents) in your CI configuration.

## Enable Nx Agents

To enable task distribution with Nx Agents, make sure your Nx workspace is connected to Nx Cloud. If you haven't connected your workspace to Nx Cloud yet, run the following command:

```shell
npx nx@latest connect
```

Check out the [connect to Nx Cloud recipe](/docs/guides/nx-cloud/setup-ci) for more details.

Then, adjust your CI pipeline configuration to **enable task distribution**. If you don't have a CI config yet, you can generate a new one using the following command:

```shell
npx nx g ci-workflow
```

The key line in your CI config is the `start-ci-run` command:

```yaml {% meta="{15}" %}
// .github/workflows/ci.yml
name: CI
...

jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      ...
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          filter: tree:0

      - run: pnpm dlx nx start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"

      # Cache node_modules
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
      ...

      # Nx Affected runs only tasks affected by the changes in this PR/commit. Learn more: https://nx.dev/ci/features/affected
      - run: pnpm exec nx affected -t lint test build
```

This command tells Nx Cloud to:

- Start a CI run (`npx nx start-ci-run`)
- Collect all Nx commands that are being issued (e.g., `pnpm exec nx affected -t lint test build`) and
- Distribute them across 3 agents (`3 linux-medium-js`) where `linux-medium-js` is a predefined agent [launch template](/docs/reference/nx-cloud/launch-templates).

### Configure Nx Agents on your CI Provider

Every organization manages their CI/CD pipelines differently, so the guides don't cover org-specific aspects of CI/CD (e.g., deployment). They mainly focus on configuring Nx correctly using Nx Agents and [Nx Replay](/docs/features/ci-features/remote-cache).

Read our [setup guides on for your CI provider of choice](/docs/guides/nx-cloud/setup-ci).

## How Nx Agents work

![Distribute Task Execution with Nx Agents](../../../../assets/features/nx-agents-orchestration-diagram.svg)

_**Nx Agents are declarative**_ in that you only specify the number of agents and the type of agent you want to use. Nx Cloud then picks up the Nx commands that are being issued on your CI and distributes them automatically. This results in **low maintenance and a much more efficient distribution strategy**. A non-declarative approach would be one where you define which tasks or projects get executed on which machine, requiring you to adjust the configuration as your codebase changes.

_**Nx Agents use a task-centric approach**_ to distribution. Current CI systems use VM-centric approaches, where tasks must be predefined for specific machines, often leading to inefficiencies as your codebase grows. Instead of defining which tasks run on which machine upfront, Nx Agents dynamically process tasks based on availability and task dependencies/ordering. Tasks are picked up by agents based on the task's required processing time (from historical data) and task dependency/ordering (from the Nx graph). This results in a faster and resource efficient processing, and is also more resilient to failures since any other agent can pick up work if one agent fails during bootup. Read more [on our blog post](https://nx.dev/blog/reliable-ci-a-new-execution-model-fixing-both-flakiness-and-slowness).

_**Nx Agents are cost and resource-efficient**_ as the tasks are automatically distributed - **optimizing for speed while also ensuring resource utilization is high** and idle time is low. You can also [dynamically adjust the number of agents](/docs/features/ci-features/dynamic-agents) based on the size of the PR, and we're working on [some more AI-powered features](/docs/features/ci-features/self-healing-ci) to optimize this even further. In addition, [remote caching](/docs/features/ci-features/remote-cache) guarantees tasks are not run twice, and artifacts are shared efficiently among agents.

_**Nx Agents are non-invasive**_ in that you don't need to completely overhaul your existing CI configuration or your Nx workspace to use them. You can start using Nx Agents with your existing CI provider by adding the `nx start-ci-run...` command mentioned previously. In addition, all artifacts and logs are played back to the main job so you can keep processing them as if they were run on the main job. Hence, your existing post-processing steps should still keep working as before.

For a more thorough explanation of how Nx Agents optimize your CI pipeline, read this [guide to parallelization and distribution in CI](/docs/concepts/ci-concepts/parallelization-distribution).

## Nx Agents features

{% cardgrid %}

{% linkcard title="Create Custom Launch Templates" description="Define your own launch templates to set up agents in the exact right way"  href="/docs/reference/nx-cloud/launch-templates" /%}

{% linkcard title="Dynamically Allocate Agents" description="Assign a different number of agents to a pipeline based on the size of the PR"  href="/docs/features/ci-features/dynamic-agents" /%}

{% linkcard title="Automatically Split E2E Tasks" description="Split large e2e tasks into a separate task for each spec file"  href="/docs/features/ci-features/split-e2e-tasks" /%}

{% linkcard title="Identify and Re-run Flaky Tasks" description="Re-run flaky tasks in CI whenever they fail" href="/docs/features/ci-features/flaky-tasks" /%}

{% /cardgrid %}

## Relevant repositories and examples

By integrating Nx Agents into your CI pipeline, you can significantly reduce build times, optimize resource use, and maintain a scalable, efficient development workflow.

- [Reliable CI: A New Execution Model Fixing Both Flakiness and Slowness](https://nx.dev/blog/reliable-ci-a-new-execution-model-fixing-both-flakiness-and-slowness)
- [Nx: On how to make your CI 16 times faster with a small config change](https://github.com/vsavkin/interstellar)
- ["Lerna & Distributed Task Execution" Example](https://github.com/vsavkin/lerna-dte)

---
<!-- source: https://nx.dev/docs/features/ci-features/dynamic-agents.md -->
## Dynamically Allocate Agents

By default, when you set up [Nx Agents](/docs/features/ci-features/distribute-task-execution) you specify the number and type of agents to use.

```yaml {% meta="{9}" %}
// .github/workflows/main.yaml"
...
jobs:
  - job: main
    name: Main Job
    ...
    steps:
      ...
      - run: npx nx start-ci-run --distribute-on="8 linux-medium-js" --stop-agents-after="e2e-ci"
      - ...
```

This works great, but may not be the most cost-effective way to run your tasks. The goal is to **balance cost and speed**. For example, you might want to run a small PR on a few agents to save costs, but use many agents for a large PR to get the fastest possible build time.

## Configure dynamic agents based on PR size

You can configure Nx Cloud to execute a different number of agents based on the size of your PR's affected changes. Define any number of **changesets** (the number of agents and types of agents) to use for different sized PRs and pass them in a configuration file to your `start-ci-run` command.

Start by creating a file called `distribution-config.yaml` in the `.nx/workflows` directory of your repo. This file will contain a `distribute-on` property that will be used to define the changesets to use for your PR. You can name your changesets anything you want.

{% aside type="caution" title="The order of your changesets matters!" %}
Define your changesets in order of increasing size (i.e. smallest changesets are defined before larger changesets). Nx Cloud uses the position of your changesets as part of its calculations to dynamically determine the correct changeset to use for your PR.
{% /aside %}

```yaml
// .nx/workflows/distribution-config.yaml
distribute-on:
  small-changeset: 3 linux-medium-js
  medium-changeset: 6 linux-medium-js
  large-changeset: 10 linux-medium-js
```

You can also specify a `default` changeset if you only want one changeset to be used for all PRs. Note that `default` is a reserved keyword so do not use it if you would like to define multiple changesets.

```yaml
// .nx/workflows/distribution-config.yaml
distribute-on:
  default: 3 linux-medium-js
```

You can have as many changesets as you want. Based on the number of changesets specified, each changeset is assigned an equal percentage out of 100. Nx Cloud can determine the percentage of affected projects in your PR and use that value to evaluate which changeset to use.

{% callout type="deepdive" title="How is the size of the PR determined?" %}
Nx Cloud calculates the relationship between the number of [affected projects](/docs/features/ci-features/affected) and the total number of projects in the workspace to determine the size of a PR.
{% /callout %}

## Setting up dynamic agents in your CI pipeline

In the example below, each changeset would be assigned an equal percentage range out of 100%. If Nx Cloud determines that 30% of your projects have been affected, then it will use the medium changeset to distribute the workload on. If Nx Cloud determines that 55% of your projects have been affected, it will use the large changeset.

```yaml
// .nx/workflows/distribution-config.yaml
distribute-on:
  small-changeset: 3 linux-medium-js # Distribute on small if 1-25% of projects affected in PR
  medium-changeset: 6 linux-medium-js # Distribute on medium if 26-50% of projects affected in PR
  large-changeset: 10 linux-medium-js # Distribute on large if 51-75% of projects affected in PR
  extra-large-changeset: 15 linux-medium-js # Distribute on extra-large if 76-100% of projects affected in PR
```

You can then reference your distribution configuration in your CI pipeline configuration:

```yaml {% meta="{9}" %}
// .github/workflows/main.yaml
...
jobs:
  - job: main
    name: Main Job
    ...
    steps:
      ...
      - run: npx nx start-ci-run --distribute-on=".nx/workflows/distribution-config.yaml" --stop-agents-after="e2e-ci"
      - ...
```

Now your agents will distribute your tasks dynamically—scaling and adapting to your PR sizes.
This feature helps save costs on smaller PRs while maintaining the high performance necessary for large PRs.

---
<!-- source: https://nx.dev/docs/features/ci-features/flaky-tasks.md -->
## Identify and Re-run Flaky Tasks

Tasks that fail only sometimes and only in certain environments are called "flaky tasks". They are enormously time consuming to identify and debug. Nx Cloud can **reliably detect flaky tasks** and **automatically schedule them to be re-run** on a different agent.

Ideally as a developer you don't even notice flaky tasks any more as they're automatically re-run and solved for you.

## Enable flaky task detection

Flaky Task Detection is enabled by default if your workspace is connected to Nx Cloud and leverages [Nx Agents](/docs/features/ci-features/distribute-task-execution).

To connect your workspace to Nx Cloud run:

```shell
npx nx@latest connect
```

See the [connect to Nx Cloud recipe](/docs/guides/nx-cloud/setup-ci) for all the details.

## How Nx identifies flaky tasks

Nx leverages its cache mechanism to identify flaky tasks.

- Nx creates a **hash of all the inputs** for a task whenever it is run.
- If Nx ever encounters a task that fails with a particular set of inputs and then succeeds with those same inputs, Nx **knows for a fact that the task is flaky**.

Nx can't know with certainty when the task has been fixed to no longer be flaky, so if a particular task has **no flakiness incidents for 2 weeks**, the `flaky` flag is removed for that task.

![Flaky tasks in CI](../../../../assets/features/ci-features/flaky-tasks-ci.png)

In this image, the `e2e-ci--src/e2e/app.cy.ts` task is a flaky task that has been automatically retried once. There is a `1 retry` indicator to show that it has been retried and, once expanded, you can see tabs that contain the logs for `Attempt 1` and `Attempt 2`. With this UI, you can easily compare the output between a successful and unsuccessful run of a flaky task.

## Automatically re-run flaky tasks

When a flaky task fails in CI with [distributed task execution](/docs/features/ci-features/distribute-task-execution) enabled, Nx will **automatically send that task to a different agent** and run it again (up to 2 tries in total). Its important to run the task on a different agent to ensure that the agent itself or the other tasks that were run on that agent are not the reason for the flakiness.

## Flaky task analytics

{% aside type="note" title="Enterprise Feature" %}
Workspace flaky task analytics is currently available for organizations on the Enterprise plan. Reach out if your organization is [interested in Nx Enterprise](https://nx.dev/enterprise?utm_source=nx.dev&utm_medium=callout&utm_campaign=flaky-task-analytics).
{% /aside %}

Nx Cloud provides analytics to help you understand and manage flaky tasks across your workspace. The analytics dashboard gives you insights into which tasks are flaky, how often they fail, and how much time is being wasted on reruns.

![Flaky Tasks dashboard](../../../../assets/features/ci-features/nx-cloud-flaky-tasks-metrics-chart.avif)

The dashboard displays key metrics over the time range selected (7 days vs 30 days) to give you a quick overview of your workspace health.

- **Active flaky tasks** - The total number of tasks in your workspace that have a flake rate greater than 0 within the selected time window.
- **Average flake rate** - A weighted average flake rate across all tasks in your workspace. This metric uses the sample size to weight each task's flake rate proportionally, so a task that ran 1000 times with 5% flake rate has more impact than one that ran 10 times with 50% flake rate.
- **High risk tasks** - The number of tasks with a flake rate higher than 20%, indicating severe reliability issues that need immediate attention.

The chart shown provides a visual representation of your flaky tasks, helping you quickly identify which tasks need the most attention.

Tasks are plotted based on their **impact score**, which is calculated as `flake_rate × sample_size`. This means frequently-run flaky tasks are weighted higher than rarely-run flaky tasks.

Priority levels are determined using percentile-based thresholds that scale across organizations of any size:

- **High priority** (red) - Top 10% of tasks by impact score (90th percentile and above). These tasks have severe flakiness and should be addressed immediately.
- **Medium priority** (yellow) - Next 23% of tasks by impact score (67th-90th percentile). These tasks have moderate flakiness with sufficient data.
- **Low priority** (gray) - Bottom 67% of tasks by impact score. These tasks have minor flakiness or not enough data to be concerning.

Tasks on the right side of the chart typically represent the highest priority items that need attention. The scatter plot shows up to 50 results, sorted by most recent flaked tasks.

### Flaky task table

The table provides detailed information about each flaky task in your workspace:

![Flaky Tasks Analytics Table](../../../../assets/features/ci-features/nx-cloud-flaky-tasks-table.avif)

By default, the table loads your most recent flaky tasks. Each row includes:

- **Task** - The project and target combination (e.g., `my-app:test`)
- **Flake rate** - Measures how often a task succeeds due to flakiness. Specifically, it represents the percentage of total successes that came from unreliable (flaky) task hashes: `flaky_successes / (flaky_successes + non_flaky_successes)`. This tells you: "Of all the times this task succeeded, how many successes came from unreliable code?"
- **Total reruns** - The number of times a task was executed more than once due to flakiness. This counts the "extra" executions that happened because the task failed and needed to be retried. Calculated as: `total_executions - unique_hash_count`
- **Time wasted** - An estimate of the total time spent on reruns, calculated by multiplying the total reruns by the average task duration
- **Last failure** - The timestamp of the most recent failure across all contributing task hashes

#### Flaky task detail view

Click on any row in the table to view detailed information about a specific flaky task.

The **Overview** tab shows summary statistics and trends for the selected task such as flake rate, time wasted and automatic deflake counts

![Flaky Task Detail Overview](../../../../assets/features/ci-features/nx-cloud-flaky-tasks-details.avif)

The **Activity** tab displays a timeline of all executions, showing when the task failed and succeeded to jump directly into the runs.

![Flaky Task Detail Activity](../../../../assets/features/ci-features/nx-cloud-flaky-tasks-detail-activity.avif)

The **Environments** tab provides insights into the different environments where the task was executed, helping identify if certain environments contribute to flakiness.

![Flaky Task Detail Environments](../../../../assets/features/ci-features/nx-cloud-flaky-tasks-detail-environment.avif)

---
<!-- source: https://nx.dev/docs/features/ci-features/github-integration.md -->
## GitHub Integration

Any CI tool requires tight integration with your existing version control system. Nx Cloud offers first class integration with GitHub in the following ways.

## Easy workspace setup

![Screenshot of Nx Cloud connecting a GitHub repository](../../../../assets/features/ci-features/github-onboarding.avif)

Get started quickly with Nx Cloud with our GitHub connection process. Connect your workspace by selecting your repo and organization from GitHub, and Nx Cloud will create a pull request with all the necessary configuration. User access is automatically connected to GitHub, and a PR is created to connect your workspace. Your repo now has [distributed caching](/docs/features/ci-features/remote-cache) in less than 5 minutes.

You can also create a new workspace from a template for experimentation. This workspace will come pre-configured with Nx Cloud and examples of core Nx concepts. [Create a new Nx workspace](https://cloud.nx.app/create-nx-workspace) to get started.

[Connect your Nx Cloud account to GitHub](/docs/features/ci-features/github-integration#connect-to-github) to use this feature.

## Pull request insights

![Screenshot of Nx Cloud app for GitHub showing pull request insights](../../../../assets/features/ci-features/github-pr-bot.avif)

Good CI checks require fast and easy access to results. That's why Nx Cloud will update your PR with the current running status of your tasks and a convenient link to your Nx Cloud results and logs. Take advantage of the enhanced developer experience of structured and searchable logs. Quick insight to PR task progress, so you're not stuck waiting for every task to complete. And with Nx Replay, developers can quickly replay tasks locally to avoid running tasks that CI has already completed.

This feature is available in workspaces with the [Nx Cloud GitHub App installed](/docs/guides/nx-cloud/source-control-integration/github#install-the-app).

## Access control

![Diagram showing users syncing from GitHub to Nx Cloud](../../../../assets/features/ci-features/github-user-management.avif)

Nx Cloud organization access can be linked to a Github organization, so that memberships are automatically synced. This allows Nx Cloud to fit in to any existing on-boarding or off-boarding process. There's no need to manually manage users separately. Get your engineers Nx Cloud access right alongside their GitHub access so they can get to work fast. Use [personal access tokens](/docs/guides/nx-cloud/personal-access-tokens) to further enhance your security.

[Connect your Nx Cloud account to GitHub](/docs/features/ci-features/github-integration#connect-to-github) to use this feature. Members of your GitHub organization will also need to connect their GitHub accounts to access the organization.

## Connect to GitHub

Get started by connecting your Nx Cloud account to GitHub. This will allow you to access GitHub-powered organizations that you're a member of, easily connect workspaces, and configure automatic access control through GitHub.

{% call_to_action title="Connect to GitHub" url="https://cloud.nx.app/profile/vcs-integrations" icon="nxcloud" description="Connect your Nx Cloud account to GitHub in your profile settings" %}
Connect to GitHub
{% /call_to_action %}

Note that it doesn't matter what method you use to log into Nx Cloud, connecting your GitHub account is a separate step.

## Connect to GitHub during initial setup

1. Visit [Nx Cloud](https://cloud.nx.app) and click **Connect a workspace** at the top.
2. Select **Connect existing repository** from the dropdown.
3. Follow the prompts to select a repo.
4. If that repo is controlled by a GitHub organization, you will be prompted to use that organization.
5. Follow the prompts to create a pull request to complete your connection to Nx Cloud.

{% call_to_action title="Connect a workspace to Nx Cloud" url="https://cloud.nx.app/setup/connect-workspace/github/select" icon="nxcloud" description="Connect an Nx workspace in GitHub to Nx Cloud" %}
Connect an Nx workspace in GitHub to Nx Cloud
{% /call_to_action %}

## Connect an organization to GitHub after initial setup

If you already have an organization in Nx Cloud, and you'd like to use your GitHub organization to manage access to it:

1. Go to the organization in Nx Cloud while logged in as an admin user.
2. Click on **Settings** in the top menu
3. Go to **Connect GitHub organization in the sidebar**
4. Follow the prompts there to connect to GitHub. Note that for every workspace in the Nx Cloud organization, there must be a corresponding repo in the GitHub organization.

## Connect a workspace to GitHub after initial setup

If you already have a workspace connected to Nx Cloud, and you'd like to connect it to a GitHub repo to enable PR insights, [install the Nx Cloud GitHub App](/docs/guides/nx-cloud/source-control-integration/github#install-the-app).

---
<!-- source: https://nx.dev/docs/features/ci-features/remote-cache.md -->
## Remote Caching (Nx Replay)

{% youtube
src="https://youtu.be/NF1__N_snog"
title="Remote Caching with Nx Replay"
 /%}

Nx [caches task results locally](/docs/features/cache-task-results) to avoid rebuilding the same code twice. Remote caching extends this by **sharing the cache across your team and CI**.

![Diagram showing Teika sharing his cache with CI, Kimiko and James](../../../../assets/features/distributed-caching.svg)

- **Zero config** and **secure** by default
- Drastically **speeds up task execution times** during local development, and more critically in CI
- **Saves money on CI/CD costs** by reducing the number of tasks that need to be executed (we observed 30-70% faster CI & half the cost)

Nx **restores terminal output, along with the files and artifacts** created from running the task (e.g., your build or dist directory). If you want to learn more about the conceptual model behind Nx caching, read [How Caching Works](/docs/concepts/how-caching-works).

## Configure remote caching

To use **Nx Replay**, you need to connect your workspace to Nx Cloud (if you haven't already).

```shell
npx nx@latest connect
```

See the [connect to Nx Cloud recipe](/docs/guides/nx-cloud/setup-ci) for all the details.

## Why use remote caching (Nx Replay)?

Nx Replay directly benefits your organization by:

- **Speeding up CI pipelines:** With Nx Replay, tasks that have already been executed in a PR's initial CI pipeline run can **reuse cached results in subsequent runs**. This reduces the need to re-run unaffected tasks, significantly speeding up the CI process for modified PRs. This benefit complements the [affected command](/docs/features/ci-features/affected), which optimizes pipelines by only running tasks for projects that could be impacted by code changes.

- **Boosting local developer efficiency:** Depending on [how cache permissions](/docs/guides/nx-cloud/access-tokens) are set for your workspace, developers can reuse cached results from CI on their local machines. As a result, tasks like builds and tests can complete instantly if they were already executed in CI. This accelerates developer workflows without any extra steps required.

- **Enabling Nx Agents:** Nx Replay is crucial for [Nx Agents](/docs/features/ci-features/distribute-task-execution) to function efficiently. Nx Agents leverage remote caching as a **transport mechanism** for transferring task artifacts between machines as it distributes tasks. When a task depends on another task that may have been executed on a different agent, Nx Replay ensures the necessary artifacts are transferred seamlessly. This allows each agent to execute only its assigned tasks while relying on cached results for dependencies, ensuring tasks run only once and are shared across all agents. [Learn more about Nx Agents](/docs/features/ci-features/distribute-task-execution).

## What gets stored?

Nx Cloud stores the following:

- **Terminal output:** The terminal output generated when running a task. This includes logs, warnings, and errors.
- **Task artifacts:** The output files of a task defined in the [`outputs` property of your project configuration](/docs/guides/tasks--caching/configure-outputs). For example, the build output, test results, or linting reports.
- **Hash:** The hash of the inputs to the computation. The inputs include the source code, runtime values, and command line arguments. Note that the hash is included in the cache, but the actual inputs are not.

Learn more about [how caching works](/docs/concepts/how-caching-works#what-is-cached).

Cache correctness depends on your tasks declaring the right `inputs` and `outputs`. If a task reads a file that isn't in its inputs, cache hits can serve stale results. If it writes outside its declared outputs, those files go missing on a cache restore. [Task sandboxing](/docs/features/ci-features/sandboxing) uses IO tracing to catch these mismatches so you can fix them before they cause problems.

## Security in remote caching

Since we work with many large corporations (including banks, insurance companies, and governments), we take security very seriously. Nx Cloud provides several features to ensure your data remains safe and secure:

- **Immutability:** Each cache entry is immutable, meaning once an entry is created, it cannot be altered. This ensures that cached results cannot be tampered with by malicious parties, preventing the injection of vulnerabilities into your build process.

- **Access Control via Tokens:** Nx Cloud allows you to [control who can read from and write to the cache](/docs/guides/nx-cloud/access-tokens). For example, you can configure these settings to restrict cache write access to your CI pipeline while allowing all developers to only read.

- **End-to-End Encryption:** Nx Cloud supports end-to-end encryption to protect your data. Task artifacts are encrypted before being sent to the remote cache and decrypted when retrieved. This ensures that even if someone gains access to Nx Cloud servers, they cannot view your stored artifacts. For more details, visit the [encryption documentation](/docs/guides/nx-cloud/encryption).

- **Nx Enterprise (Self-Hosting and EU Regions):** For organizations with specific compliance or data residency requirements, Nx Enterprise offers the option to self-host Nx Cloud on your own infrastructure. Additionally, you can choose to host in EU regions, ensuring that your data complies with regional data protection laws. This is available to our [Nx Enterprise customers](https://nx.dev/enterprise).

- **SOC Certification:** Nx and Nx Cloud are SOC Type 1 and Type 2 certified, providing an additional layer of assurance that your data is handled according to industry-standard security practices. For more details, you can visit our [security page](https://security.nx.app).

### Configure caching access

Caching access can be restricted in terms of read/write access. You can configure this in your [Nx Cloud dashboard](https://nx.app). Learn more about [cache security here](/docs/concepts/ci-concepts/cache-security).

## FAQ

### What if the remote cache is offline?

Nx Replay automatically syncs the remote cache to the local cache folder. As such, if the remote cache is not available, it will automatically fall back to the local cache or just run the task if it is not cached.

### Can I self-host my remote cache?

If you're an enterprise and have special restrictions, [reach out to us](https://nx.dev/enterprise/trial). Our enterprise plan includes various hosting options, from dedicated EU region hosting, to single-tenant and also on-premise.

### How can I skip Nx Cloud caching?

To learn more about how to temporarily skip task caching, head over to [our corresponding docs page](/docs/guides/tasks--caching/skipping-cache#skip-remote-caching-from-nx-cloud).

---
<!-- source: https://nx.dev/docs/features/ci-features/sandboxing.md -->
## Task Sandboxing

Task sandboxing monitors file system access during task execution and flags any reads or writes
that fall outside the declared `inputs` and `outputs` in your
[project configuration](/docs/reference/project-configuration)
(whether explicit or [inferred](/docs/concepts/inferred-tasks)).
It doesn't block access to the rest of the file system, but undeclared dependencies have direct
implications on [caching](/docs/features/cache-task-results) correctness, from false cache hits
serving stale results to missing output files after a cache restore.

{% aside type="note" title="Enterprise Feature" %}
Sandboxing is available on the [Nx Enterprise plan](https://nx.dev/enterprise).
[Reach out to learn more](https://nx.dev/enterprise).
{% /aside %}

{% aside type="caution" title="Nx 22.5+ Required" %}
Task sandboxing requires Nx 22.5 or later.
{% /aside %}

## Why hermeticity matters

A task is _hermetic_ when it only reads from its declared inputs and only writes to its declared
outputs.
Hermetic tasks are safe to cache and replay because their behavior is fully described by their
configuration.

![Diagram showing declared inputs flowing into vite build, producing declared outputs, with a cache key derived from the input hash](../../../../assets/features/sandboxing-cache-flow.svg)

[Computation caching](/docs/features/cache-task-results) relies on declared `inputs` and `outputs`
to determine when a cache entry is valid.
If a task reads a file that isn't listed in its inputs, the cache has no way to know that file
changed, and it'll serve a stale result.
If a task writes files outside its declared outputs, those files won't be captured in the cache
and will go missing on a cache hit.

Undeclared dependencies are difficult to catch through code review alone.
A task might work correctly for months until an unrelated change to an undeclared input causes a
cache-related failure that's hard to trace back to the root cause.

### Example: undeclared input (false cache hit)

An API app reads `app.yaml` from the project root at startup to configure routes and middleware.
If `app.yaml` isn't included in the target's `inputs`, changing the configuration won't invalidate
the cache.
The next CI run serves stale output built against the old configuration.

Sandboxing catches this because it sees the build process reading `app.yaml` even though it isn't
declared.
Add the file to the target's `inputs` in `project.json` to fix it:

```json {% meta="{4}" %}
{
  "targets": {
    "build": {
      "inputs": ["{projectRoot}/app.yaml"]
    }
  }
}
```

### Example: undeclared output (missing artifacts on replay)

When using TypeScript `*.d.ts` generation (such as `vite-plugin-dts`) to emit type declarations
outside of `dist/`, the build produces two output directories:

```text {% meta="{3-4}" %}
packages/
  my-package/
    dist/
    types/
    src/
    package.json
```

If the target's `outputs` only lists `["{projectRoot}/dist"]`, the `types/` directory isn't
[stored in the remote cache](/docs/features/ci-features/remote-cache#what-gets-stored).
On a cache hit, `dist/` is restored but the type declarations are missing, breaking downstream
library consumers.

Sandboxing catches this because it sees writes to `types/` that aren't covered by the declared
outputs.
Include both directories in `outputs` so they can be replayed from cache:

```json {% meta="{4}" %}
{
  "targets": {
    "build": {
      "outputs": ["{projectRoot}/dist", "{projectRoot}/types"]
    }
  }
}
```

## How sandboxing works

Sandboxing runs each task in a monitored environment where all file system reads and writes are
tracked.
When a task accesses a file outside its declared inputs or writes to a path outside its declared
outputs, Nx Cloud flags it.

You get an audit trail of every file each task touched during execution, warnings when tasks have
undeclared dependencies, and confidence that your cache configuration is correct rather than just
"working so far."

In **Warning** mode (recommended when getting started), violations are reported in the Nx Cloud UI
but tasks continue to completion.
In **Strict** mode, tasks fail immediately when a violation is detected.
See [Cloud settings](#cloud-settings) to configure the enforcement mode.

## Investigating violations

When sandboxing detects undeclared file access, a warning banner appears on the CI Pipeline
Execution (CIPE) page in Nx Cloud.
Runs that contain violations are tagged with a "sandbox violation" badge.

![CIPE page showing sandbox violations detected in 109 tasks, with a run tagged as sandbox violation](../../../../assets/features/sandboxing-cipe-violations.png)

Click into a run to see which individual tasks have violations.
Click the **Sandbox violations** button to filter the task list to only tasks with undeclared reads
or writes.

![Task list showing individual tasks with sandbox violation badges](../../../../assets/features/sandboxing-task-violations.png)

Open the task details and switch to the **Sandbox analysis** tab.
The process tree shows every process spawned during the task, along with the files each one read
and wrote.
Click a process to see its full file access list.
Files flagged as "unexpected read" or "unexpected write" are the ones not covered by your declared
`inputs` and `outputs`.

![Sandbox analysis tab showing process tree with unexpected reads and writes highlighted](../../../../assets/features/sandboxing-analysis.png)

To export the raw trace data for further analysis, click **View raw sandbox report** to download
the JSON report.

![View raw sandbox report button](../../../../assets/features/sandboxing-raw-report.png)

## Inspecting inputs and outputs

Check what your tasks currently declare before enabling sandboxing.
Use `nx show target` to inspect a specific target's resolved inputs and outputs:

{% aside type="caution" title="Nx 22.6+ Required" %}
The `--inputs` and `--outputs` flags for `nx show target` require Nx 22.6 or later.
{% /aside %}

```shell
nx show target <project>:<target> --inputs --outputs
```

Add the `--json` flag for machine-readable output:

```shell
nx show target <project>:<target> --inputs --outputs --json
```

For a broader view of the full project configuration, run `nx show project`:

```shell
nx show project <project>
```

You can also use the [project details view](/docs/features/explore-graph) in Nx Console:

{% project_details title="Project Details View" expandedTargets=["build"] %}

```json
{
  "project": {
    "name": "myapp",
    "type": "app",
    "data": {
      "root": "apps/myapp",
      "targets": {
        "build": {
          "options": {
            "cwd": "apps/myapp",
            "command": "vite build"
          },
          "cache": true,
          "dependsOn": ["^build"],
          "inputs": [
            "production",
            "^production",
            {
              "externalDependencies": ["vite"]
            }
          ],
          "outputs": ["{projectRoot}/dist"],
          "executor": "nx:run-commands",
          "configurations": {}
        }
      },
      "sourceRoot": "apps/myapp/src",
      "projectType": "application",
      "tags": []
    }
  },
  "sourceMap": {
    "root": ["apps/myapp/project.json", "nx/core/project-json"],
    "targets.build": ["apps/myapp/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.inputs": ["apps/myapp/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.outputs": ["apps/myapp/vite.config.ts", "@nx/vite/plugin"]
  }
}
```

{% /project_details %}

The `inputs` and `outputs` arrays show exactly what the cache tracks.
Sandboxing compares these declarations against what the task actually reads and writes at runtime
and reports discrepancies.

## Enabling sandboxing

Sandboxing is available for [Nx Enterprise](https://nx.dev/enterprise) customers on
[single-tenant](/docs/enterprise/single-tenant/overview) deployments using
[Nx Agents](/docs/features/ci-features/distribute-task-execution).
It is not supported with [manual distributed task execution](/docs/guides/nx-cloud/manual-dte).
Contact your Nx Enterprise representative to enable sandboxing for your deployment.

### Excluding paths

Create a `.nx/workflows/sandboxing-config.yaml` file to exclude paths from sandboxing checks.

```yaml
# .nx/workflows/sandboxing-config.yaml
exclude-reads:
  - '**/vite.config.*.timestamp-*'

task-exclusions:
  - project: myapp
    target: build
    exclude-reads:
      - .next/cache/**
    exclude-writes:
      - logs/**
  - target: lint
    exclude-reads:
      - .eslintcache/**
```

Global `exclude-reads` and `exclude-writes` apply to all tasks.
Use `task-exclusions` to scope exclusions to a specific project, target, or combination of both.

Patterns use glob syntax relative to the workspace root.

## Cloud settings

Enterprise customers with sandboxing enabled can configure the enforcement mode in the Nx Cloud
workspace settings under **Settings > General**.

![Nx Cloud settings sidebar showing General settings](../../../../assets/features/sandboxing-settings-sidebar.png)

Three enforcement modes are available:

- **Strict** — tasks that violate sandbox isolation fail immediately.
- **Warning** — tasks complete but violations are reported in the Nx Cloud UI.
- **Off** — sandboxing is disabled.

![Sandboxing enforcement mode setting with Strict, Warning, and Off options](../../../../assets/features/sandboxing-settings.png)

## Learn more

- [Cache task results](/docs/features/cache-task-results)
- [Remote cache](/docs/features/ci-features/remote-cache)
- [Project configuration reference](/docs/reference/project-configuration)
- [Nx Enterprise](https://nx.dev/enterprise)

---
<!-- source: https://nx.dev/docs/features/ci-features/self-healing-ci.md -->
## AI-Powered Self-Healing CI

{% youtube
src="https://youtu.be/aQUlsilNSQ8"
title="How Nx Self-Healing CI Works"
/%}

Nx Cloud Self-Healing CI is an **AI-powered system that automatically detects, analyzes, and proposes fixes for CI failures**, offering several key advantages:

- **Improves Time to Green (TTG):** Automatically proposes fixes when tasks fail, significantly reducing the time to get your PR merge-ready. No more babysitting PRs.
- **Keeps You in the Flow:** Get notified about failed PRs and proposed fixes via PR/MR comments or directly in your editor with Nx Console (VS Code, Cursor, or WebStorm). Review, approve, and keep working while AI handles the rest.
- **Leverages Deep Context:** AI agents understand your workspace structure, project relationships, and build configurations through the Nx [project graph](/docs/features/explore-graph) and metadata.
- **Non-Invasive Integration:** Works with your existing CI provider without overhauling your current setup.

## Enable self-healing CI

{% aside title="VCS Integration Required" type="note" %}
Your Nx Cloud workspace needs to have a [VCS integration enabled](/docs/guides/nx-cloud/source-control-integration) to use Self-Healing CI. Self-Healing CI supports GitHub, GitLab, Azure DevOps, and Bitbucket.
{% /aside %}

To enable Self-Healing CI in your workspace, you'll need to connect to Nx Cloud and configure your CI pipeline.

If you haven't already connected to Nx Cloud, run the following command:

```shell
npx nx@latest connect
```

Next, check the [Nx Cloud workspace settings](https://cloud.nx.app/go/workspace/settings/self-healing-ci) in the Nx Cloud web application to ensure that "Self-Healing CI" is enabled.

### Configure your CI pipeline

Add a step to your CI configuration's "main" job that runs the `fix-ci` command. It doesn't matter exactly what this job is called, it is whichever job in your config where you invoke `nx start-ci-run` and kick off your `nx run-many` or `nx affected` commands.

By default, your CI provider will only run the step if the previous steps succeeded, but by definition we want to run Self-Healing CI even when previous steps fail. Therefore make sure you are using a condition of `if: always()` or equivalent to ensure it runs even when previous steps fail:

{% tabs %}

{% tabitem label="GitHub Actions" %}

```yaml
# .github/workflows/ci.yml
name: CI

jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      # Your existing steps which check out the repo, start-ci-run, install
      # dependencies, etc.
      # These are just illustrative examples...
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
      - run: npx nx start-ci-run
      - run: npm ci
      - run: npx nx affected -t lint test build

      # NEW: Add this step at the end of your job
      - run: npx nx fix-ci
        if: always() # IMPORTANT: Always run
```

{% /tabitem %}

{% tabitem label="GitLab CI" %}

```yaml
# .gitlab-ci.yml
stages:
  - build

main:
  stage: build
  script:
    # Your existing steps which check out the repo, start-ci-run, install
    # dependencies, etc.
    - npx nx start-ci-run
    - npm ci
    - npx nx affected -t lint test build
  # NEW: Add this section at the end of your job if you don't
  # already have an after_script section
  after_script:
    # IMPORTANT: after_script runs regardless of job success/failure
    # so it's like if: always() on GitHub
    - npx nx fix-ci
```

{% /tabitem %}

{% tabitem label="Azure DevOps" %}

```yaml
# azure-pipelines.yml
trigger:
  - main

pool:
  vmImage: 'ubuntu-latest'

steps:
  # Your existing steps which check out the repo, start-ci-run, install
  # dependencies, etc.
  # These are just illustrative examples...
  - task: NodeTool@0
    inputs:
      versionSpec: '22.x'
  - script: npx nx start-ci-run
  - script: npm ci
  - script: npx nx affected -t lint test build

  # NEW: Add this step at the end of your job
  - script: npx nx fix-ci
    condition: always() # IMPORTANT: Always run
```

{% /tabitem %}

{% tabitem label="Bitbucket Pipelines" %}

```yaml
# bitbucket-pipelines.yml
image: node:22

pipelines:
  pull-requests:
    '**':
      - step:
          name: CI
          script:
            # Your existing steps which start-ci-run, install
            # dependencies, etc.
            # These are just illustrative examples...
            - npx nx start-ci-run
            - npm ci
            - npx nx affected -t lint test build
          after-script:
            # NEW: Add this section at the end of your step
            # IMPORTANT: after-script runs regardless of step success/failure
            # so it's like if: always() on GitHub
            - npx nx fix-ci
```

{% /tabitem %}

{% /tabs %}

> NOTE: If all tasks succeed then the `fix-ci` command becomes a no-op automatically, so that is why "always" is recommended.

{% aside type="note" title="Using manual DTE?" %}
If you use [manual distributed task execution](/docs/guides/nx-cloud/manual-dte) instead of the Nx Agents, Self-Healing CI works the same way. Add `nx fix-ci` to both the **main job** (the orchestrator) and each **agent job** with the appropriate "always run" condition. See the [manual DTE guide](/docs/guides/nx-cloud/manual-dte) for complete examples.
{% /aside %}

## Configuring self-healing CI

Self-Healing CI configuration is primarily managed through your [Nx Cloud workspace settings](https://cloud.nx.app/go/workspace/settings/self-healing-ci) in the Nx Cloud dashboard. This provides a centralized, auditable way to control the feature's behavior.

### General settings

| Setting                       | Description                                                                                                                                                                                                                                   |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Enable Self-Healing CI**    | Enable Self-Healing CI for PRs in the current workspace                                                                                                                                                                                       |
| **GitHub PR comments**        | Show Self-Healing CI feedback and actions within GitHub PR comments (in addition to the Nx Cloud UI)                                                                                                                                          |
| **Auto-retry flaky tasks**    | Automatically re-run tasks that are detected as flaky to improve CI reliability. This works by pushing an empty commit to the PR branch                                                                                                       |
| **Allow public link access**  | Allow anyone with access to the link the ability to apply or reject a suggested change (not recommended unless absolutely necessary)                                                                                                          |
| **Draft PR handling**         | Allow Self-Healing CI to create fixes for draft PRs                                                                                                                                                                                           |
| **Protected branch prefixes** | Configure branch prefixes for which fixes should not be generated (e.g., `release/` will match `release/v1.0`). The default branch and branches named `main`, `master`, `trunk`, `dev`, `stable`, or `canary` will never have fixes generated |

### Eligible tasks

Control which failing tasks Nx Cloud will actively try and fix for pull request CI pipeline executions.

{% aside type="note" title="CLI Override Available" %}
This is analogous to the `--fix-tasks` flag on `nx start-ci-run`. Anything set on the CLI will take precedence over the settings here.
{% /aside %}

You can choose between two modes:

| Mode                  | Description                                                                      |
| --------------------- | -------------------------------------------------------------------------------- |
| **Any failing task**  | Any task that fails during PR CI pipeline executions is eligible (recommended)   |
| **Specific patterns** | Limit Self-Healing CI to failing PR tasks that match the specified glob patterns |

You can also specify **Never fix** patterns to exclude certain tasks from ever being fixed by Self-Healing CI. For example, `*e2e*` would exclude all e2e-related tasks.

### Auto-apply verified code changes

{% youtube
src="https://youtu.be/30qh5W8zXTY"
title="Self-Healing CI Auto-Apply Suggestions"
/%}

Automatically commit code change suggestions to the PR branch **when ALL of these are true**:

1. The task **matches the glob patterns** configured below
2. The AI agent is **highly confident** that the suggested code change will fix the failing task
3. The suggestion has been **explicitly verified** to fix the failing task

{% aside type="note" title="CLI Override Available" %}
This is analogous to the `--auto-apply-fixes` flag on `nx start-ci-run`. Anything set on the CLI will take precedence over the settings here.
{% /aside %}

#### Deterministic Nx checks

A built-in preset that auto-fixes failures from `nx format:check`, `nx sync:check`, and `nx conformance:check` commands. The AI agent has special knowledge of these commands and will invoke the corresponding "writable" version to fix the issue (e.g., `nx format`). You can safely enable this preset even if you only use a subset of these commands.

#### Additional include patterns

Tasks matching these patterns will also have high-confidence, verified code changes auto-applied. For example: `*build*`, `*test*`, `lint`.

#### Exclude patterns

Tasks matching these patterns will **never** have code changes auto-applied, even if they match the include patterns or presets specified above. For example: `*e2e*`.

## Configuration with SELF_HEALING.md

Create a `.nx/SELF_HEALING.md` file in your repository to provide project-specific instructions to the Self-Healing CI agent. This file contains freeform markdown that the AI agent reads and interprets naturally.

{% aside title="Why a dedicated file?" type="note" %}
Using `.nx/SELF_HEALING.md` instead of `AGENTS.md` (or equivalent) separates CI-specific instructions from local development context. The file lives in the `.nx` directory alongside other Nx Cloud configuration.
{% /aside %}

### Example SELF_HEALING.md

```markdown
# Self-Healing Configuration

## Confidence Rules

- Fixes involving "test" targets should require high confidence
- Formatting fixes can be applied with medium confidence

## Off-Limits Areas

- `/src/generated/` - auto-generated, do not modify
- `/legacy/` - requires manual review

## Fix Preferences

- Prefer updating ESLint rules over adding disable comments
- For type errors, prefer explicit types over `any`

## Context

See ARCHITECTURE.md for module boundaries.
```

### What to include

| Section              | Purpose                                             | Example                                                                      |
| -------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------- |
| **Confidence Rules** | Override how the AI categorizes failure severity    | "Failures in `**/migrations/**` should be classified as `environment_state`" |
| **Off-Limits Areas** | Directories or files the agent should never modify  | "`/src/generated/` - auto-generated code"                                    |
| **Fix Preferences**  | Guide the agent's approach to common issues         | "Prefer updating ESLint rules over adding disable comments"                  |
| **Predefined Fixes** | Specify deterministic solutions for known failures  | "For lint failures, always try running `nx lint --fix` first"                |
| **Context**          | Reference other documentation the agent should read | "See ARCHITECTURE.md for module boundaries"                                  |

### Using CLAUDE.md

If your repository already has a `CLAUDE.md` file at the root, the Self-Healing CI agent will read it for additional context. When both files exist:

- **SELF_HEALING.md takes precedence** for any conflicting instructions
- Both files are read, so general context in `CLAUDE.md` is still available
- CI-specific instructions should go in `SELF_HEALING.md`

This allows teams to maintain `CLAUDE.md` for local development workflows while using `SELF_HEALING.md` for CI-specific behavior.

### Viewing configuration status

After a CI run, navigate to the pipeline execution in Nx Cloud and check the **Configurations** tab to see whether `SELF_HEALING.md` was detected and applied.

## Receiving fix notifications

### In your editor

With [Nx Console](/docs/getting-started/editor-setup) installed, you'll receive notifications directly in VS Code, Cursor, or WebStorm when a fix is available:

![Notification in your editor about an AI fix](../../../../assets/features/notification-self-healing-ci.avif)

### On your pull request/Merge request

Self-Healing CI posts a comment on your PR with:

- A summary of the reasoning behind the fix
- A diff view showing the proposed changes
- Buttons to apply or reject the fix

![Self-Healing CI GitHub Comment](../../../../assets/features/self-healing-fix-gh-comment.avif)

## Applying and reverting fixes

### Applying a fix

You can apply a proposed fix through:

1. **Editor notification** - Click "Apply" in the Nx Console notification
2. **PR/MR comment** - Click the "Apply" button
3. **Nx Cloud UI** - Use the apply button in the diff viewer

### Applying locally for fine-tuning

If a fix is 90% correct but needs minor adjustments:

1. Click "Apply Locally" in the GitHub comment or Nx Cloud UI
2. Run the provided command in your terminal
3. Make your adjustments and commit

![Apply Self-Healing Fixes Locally](../../../../assets/features/self-healing-apply-locally.avif)

### Reverting a fix

If you accidentally applied a fix, you can:

1. Manually revert the Git commit
2. Use the "Revert changes" button in the Nx Cloud diff viewer

## Advanced: CLI overrides

{% aside type="caution" title="Prefer workspace settings" %}
We recommend configuring Self-Healing CI through **[workspace settings](https://cloud.nx.app/go/workspace/settings/self-healing-ci)** in the Nx Cloud dashboard. CLI overrides should only be used for temporary, branch-specific adjustments.
{% /aside %}

{% youtube
  src="https://youtu.be/KSb48zHbaHg"
  title="Specify Which Tasks to Fix"
/%}

### When to use CLI overrides

- **Temporarily disable** Self-Healing CI on a sensitive branch
- **Test configurations** before committing to workspace settings

### Available flags

Pass these flags to `nx start-ci-run`:

| Flag                 | Description                                 | Example                       |
| -------------------- | ------------------------------------------- | ----------------------------- |
| `--fix-tasks`        | Override which tasks are eligible for fixes | `--fix-tasks="*lint*,*test*"` |
| `--auto-apply-fixes` | Override which tasks can be auto-applied    | `--auto-apply-fixes="*lint*"` |

### Disabling features via CLI

Use an empty string to **disable** a feature for a specific CI run:

```shell
# Disable fix generation entirely for this run
npx nx start-ci-run --fix-tasks=""

# Disable auto-apply entirely for this run
npx nx start-ci-run --auto-apply-fixes=""
```

Both flags treat empty string consistently as an explicit "disable" override.

### Pattern syntax

Patterns use glob syntax to match task names:

```shell
# Only fix lint and test tasks
npx nx start-ci-run --fix-tasks="*lint*,*test*"

# Fix everything except e2e tasks
npx nx start-ci-run --fix-tasks="!*e2e*"

# Auto-apply only lint fixes
npx nx start-ci-run --auto-apply-fixes="lint"
```

### Precedence rules

When both workspace settings and CLI overrides are present:

1. **CLI override** (if provided) always takes precedence
2. Falls back to **workspace settings** if no CLI override
3. Empty string (`""`) is an explicit "disable", not "use defaults"

### Viewing applied configuration

After your CI runs, navigate to the CIPE → **Configurations** tab to see:

- What workspace settings were relevant at the time of the CI pipeline execution
- What CLI overrides were applied, if any
- What the final, effective configuration was

---

## Learn more

- [Nx AI Documentation](/docs/features/enhance-ai)
- [Nx Console Editor Setup](/docs/getting-started/editor-setup)
- [Nx Cloud](/docs/features/ci-features)

---
<!-- source: https://nx.dev/docs/features/ci-features/split-e2e-tasks.md -->
## Automatically Split Slow Tasks by File (Atomizer)

{% youtube
src="https://youtu.be/0YxcxIR7QU0"
title="10x Faster e2e Tests!"
width="100%" /%}

Certain tasks like end-to-end (e2e) tests, integration tests, or large unit test suites can be large, monolithic tasks that take a considerable amount of time to execute. As a result, teams often push them to a nightly or even weekly build rather than running them for each PR. This approach is suboptimal as it increases the risk of merging problematic PRs.

Manually splitting these slow tasks can be complex and require ongoing maintenance. Nx Atomizer solves this by **automatically generating runnable targets for each test file**. For example, a task that takes 10 minutes can be split and distributed as five 2-minute tasks per agent. This allows for:

- parallelization across multiple machines with [Nx Agents](/docs/features/ci-features/distribute-task-execution)
- faster [flakiness detection & retries](/docs/features/ci-features/flaky-tasks) by isolating and re-running only the failed tests

## Enable automated task splitting

### Step 1: Connect to Nx Cloud

To use **automated task splitting**, you need to connect your workspace to Nx Cloud (if you haven't already).

```shell
npx nx@latest connect
```

See the [connect to Nx Cloud recipe](/docs/guides/nx-cloud/setup-ci) for all the details.

### Step 2: add the appropriate plugin

Run this command to set up inferred tasks and enable task splitting for each plugin:

{% tabs syncKey="test-runner" %}
{% tabitem label="Cypress" %}

```shell
nx add @nx/cypress
```

{% /tabitem %}
{% tabitem label="Playwright" %}

```shell
nx add @nx/playwright
```

{% /tabitem %}
{% tabitem label="Jest" %}

```shell
nx add @nx/jest
```

{% /tabitem %}
{% tabitem label="Vitest" %}

```shell
nx add @nx/vitest
```

{% /tabitem %}
{% tabitem label="Gradle" %}

```shell
nx add @nx/gradle
```

{% /tabitem %}
{% /tabs %}

This command will register the appropriate plugin in the `plugins` array of `nx.json`.

If you upgraded Nx from an older version, ensure that [inferred tasks](/docs/concepts/inferred-tasks#existing-nx-workspaces) are enabled in `nx.json`:

```json
// nx.json
{
  ...
  // turned on by default; just make sure it is not set to false
  useInferencePlugins: true
}
```

## Update an existing project to use automated task splitting

If you are already using the `@nx/cypress`, `@nx/playwright`, `@nx/jest`, `@nx/vitest`, or `@nx/gradle` plugin, you need to manually add the appropriate configuration to the `plugins` array of `nx.json`. Follow the instructions for the plugin you are using:

- [Configure Cypress Task Splitting](/docs/technologies/test-tools/cypress/introduction#nxcypress-configuration)
- [Configure Playwright Task Splitting](/docs/technologies/test-tools/playwright/introduction#nxplaywright-configuration)
- [Configure Jest Task Splitting](/docs/technologies/test-tools/jest/introduction#splitting-e2e-tests)
- [Configure Vitest Task Splitting](/docs/technologies/test-tools/vitest/introduction#splitting-e2e-tests)
- [Configure Gradle Testing Task Splitting](/docs/technologies/java/gradle/introduction#test-distribution)

## Verify automated task splitting works

Run the following command to open the project detail view for your test project:

{% tabs %}
{% tabitem label="CLI" %}

```shell
nx show project my-project-e2e
```

{% /tabitem %}
{% tabitem label="Project Detail View" %}

{% project_details title="Project Details View" %}

```json
{
  "project": {
    "name": "admin-e2e",
    "data": {
      "metadata": {
        "targetGroups": {
          "E2E (CI)": [
            "e2e-ci--src/e2e/app.cy.ts",
            "e2e-ci--src/e2e/login.cy.ts",
            "e2e-ci"
          ]
        }
      },
      "root": "apps/admin-e2e",
      "projectType": "application",
      "targets": {
        "e2e": {
          "cache": true,
          "inputs": ["default", "^production"],
          "outputs": [
            "{workspaceRoot}/dist/cypress/apps/admin-e2e/videos",
            "{workspaceRoot}/dist/cypress/apps/admin-e2e/screenshots"
          ],
          "executor": "nx:run-commands",
          "dependsOn": ["^build"],
          "options": {
            "cwd": "apps/admin-e2e",
            "command": "cypress run"
          },
          "configurations": {
            "production": {
              "command": "cypress run --env webServerCommand=\"nx run admin:preview\""
            }
          },
          "metadata": {
            "technologies": ["cypress"]
          }
        },
        "e2e-ci--src/e2e/app.cy.ts": {
          "outputs": [
            "{workspaceRoot}/dist/cypress/apps/admin-e2e/videos",
            "{workspaceRoot}/dist/cypress/apps/admin-e2e/screenshots"
          ],
          "inputs": [
            "default",
            "^production",
            {
              "externalDependencies": ["cypress"]
            }
          ],
          "cache": true,
          "options": {
            "cwd": "apps/admin-e2e",
            "command": "cypress run --env webServerCommand=\"nx run admin:serve-static\" --spec src/e2e/app.cy.ts"
          },
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["cypress"]
          }
        },
        "e2e-ci--src/e2e/login.cy.ts": {
          "outputs": [
            "{workspaceRoot}/dist/cypress/apps/admin-e2e/videos",
            "{workspaceRoot}/dist/cypress/apps/admin-e2e/screenshots"
          ],
          "inputs": [
            "default",
            "^production",
            {
              "externalDependencies": ["cypress"]
            }
          ],
          "cache": true,
          "options": {
            "cwd": "apps/admin-e2e",
            "command": "cypress run --env webServerCommand=\"nx run admin:serve-static\" --spec src/e2e/login.cy.ts"
          },
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["cypress"]
          }
        },
        "e2e-ci": {
          "executor": "nx:noop",
          "cache": true,
          "inputs": [
            "default",
            "^production",
            {
              "externalDependencies": ["cypress"]
            }
          ],
          "outputs": [
            "{workspaceRoot}/dist/cypress/apps/admin-e2e/videos",
            "{workspaceRoot}/dist/cypress/apps/admin-e2e/screenshots"
          ],
          "dependsOn": [
            {
              "target": "e2e-ci--src/e2e/app.cy.ts",
              "projects": "self",
              "params": "forward",
              "options": "forward"
            },
            {
              "target": "e2e-ci--src/e2e/login.cy.ts",
              "projects": "self",
              "params": "forward",
              "options": "forward"
            }
          ],
          "options": {},
          "configurations": {},
          "metadata": {
            "technologies": ["cypress"]
          }
        },
        "lint": {
          "executor": "@nx/eslint:lint",
          "inputs": ["default", "{workspaceRoot}/.eslintrc.json"],
          "cache": true,
          "outputs": ["{options.outputFile}"],
          "options": {},
          "configurations": {},
          "metadata": {
            "technologies": ["eslint"]
          }
        }
      },
      "name": "admin-e2e",
      "$schema": "../../node_modules/nx/schemas/project-schema.json",
      "sourceRoot": "apps/admin-e2e/src",
      "tags": [],
      "implicitDependencies": ["admin"]
    }
  },
  "sourceMap": {
    "root": ["apps/admin-e2e/project.json", "nx/core/project-json"],
    "projectType": ["apps/admin-e2e/project.json", "nx/core/project-json"],
    "targets": ["apps/admin-e2e/project.json", "nx/core/project-json"],
    "targets.e2e": ["apps/admin-e2e/project.json", "nx/core/target-defaults"],
    "targets.e2e.options": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e.cache": [
      "apps/admin-e2e/project.json",
      "nx/core/target-defaults"
    ],
    "targets.e2e.inputs": [
      "apps/admin-e2e/project.json",
      "nx/core/target-defaults"
    ],
    "targets.e2e.outputs": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e.configurations": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e.executor": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e.options.cwd": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e.options.command": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e.configurations.production": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e.configurations.production.command": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e-ci--src/e2e/app.cy.ts": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e-ci--src/e2e/app.cy.ts.outputs": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e-ci--src/e2e/app.cy.ts.inputs": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e-ci--src/e2e/app.cy.ts.cache": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e-ci--src/e2e/app.cy.ts.options": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e-ci--src/e2e/app.cy.ts.executor": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e-ci--src/e2e/app.cy.ts.options.cwd": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e-ci--src/e2e/app.cy.ts.options.command": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e-ci--src/e2e/login.cy.ts": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e-ci--src/e2e/login.cy.ts.outputs": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e-ci--src/e2e/login.cy.ts.inputs": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e-ci--src/e2e/login.cy.ts.cache": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e-ci--src/e2e/login.cy.ts.options": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e-ci--src/e2e/login.cy.ts.executor": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e-ci--src/e2e/login.cy.ts.options.cwd": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e-ci--src/e2e/login.cy.ts.options.command": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e-ci": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e-ci.executor": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e-ci.cache": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e-ci.inputs": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e-ci.outputs": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e-ci.dependsOn": [
      "apps/admin-e2e/cypress.config.ts",
      "@nx/cypress/plugin"
    ],
    "targets.e2e.dependsOn": [
      "apps/admin-e2e/project.json",
      "nx/core/target-defaults"
    ],
    "targets.lint": ["apps/admin-e2e/project.json", "nx/core/project-json"],
    "targets.lint.executor": [
      "apps/admin-e2e/project.json",
      "nx/core/project-json"
    ],
    "targets.lint.inputs": [
      "apps/admin-e2e/project.json",
      "nx/core/target-defaults"
    ],
    "targets.lint.cache": [
      "apps/admin-e2e/project.json",
      "nx/core/target-defaults"
    ],
    "name": ["apps/admin-e2e/project.json", "nx/core/project-json"],
    "$schema": ["apps/admin-e2e/project.json", "nx/core/project-json"],
    "sourceRoot": ["apps/admin-e2e/project.json", "nx/core/project-json"],
    "tags": ["apps/admin-e2e/project.json", "nx/core/project-json"],
    "implicitDependencies": [
      "apps/admin-e2e/project.json",
      "nx/core/project-json"
    ],
    "implicitDependencies.admin": [
      "apps/admin-e2e/project.json",
      "nx/core/project-json"
    ],
    "targets.lint.outputs": [
      "apps/admin-e2e/project.json",
      "nx/core/project-json"
    ]
  }
}
```

{% /project_details %}

{% /tabitem %}
{% /tabs %}

If you configured Nx Atomizer properly, you'll see that there are tasks named `e2e`, `e2e-ci` (or similar for other test types) and a task for each test file.

During local development, you'll want to continue using the base task (e.g., `e2e`, `test`) as it is more efficient on a single machine.

```shell
nx e2e my-project-e2e
```

The `-ci` variant task truly shines when configured and run on CI.

## Configure automated task splitting on CI

Update your CI pipeline to run the `-ci` variant task (e.g., `e2e-ci`, `test-ci`), which will automatically run all the inferred tasks for the individual test files. Here's an example of a GitHub Actions workflow:

```yaml {% meta="{17,27}" %}
// .github/workflows/ci.yml
name: CI
# ...
jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          filter: tree:0

      - uses: pnpm/action-setup@v4
        with:
          version: 9

      - run: pnpm dlx nx start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="e2e-ci"

      - uses: actions/setup-node@v3
        with:
          node-version: 20
          cache: 'pnpm'

      - run: pnpm install --frozen-lockfile
      - uses: nrwl/nx-set-shas@v4

      - run: pnpm exec nx affected -t lint test build e2e-ci
```

Learn more about configuring your [CI provider by following these detailed recipes](/docs/guides/nx-cloud/setup-ci).

---
<!-- source: https://nx.dev/docs/features/enforce-module-boundaries.md -->
## Enforce Module Boundaries

If you partition your code into well-defined cohesive units, even a small organization will end up with a dozen apps and dozens or hundreds of libs. If all of them can depend on each other freely, chaos will ensue, and the workspace will become unmanageable.

To help with that, Nx provides powerful mechanisms to enforce architectural boundaries and ensure projects can only depend on each other according to your organization's rules. You can declaratively define constraints using project tags and enforce them automatically.

{% youtube
src="https://www.youtube.com/embed/q0en5vlOsWY"
title="Applying Module Boundaries"
/%}

## How to enforce boundaries

Nx offers two complementary approaches to enforce module boundaries:

**ESLint Integration** - For JavaScript/TypeScript projects, enforce boundaries on code imports using the `@nx/enforce-module-boundaries` ESLint rule. This checks TypeScript imports and `package.json` dependencies during linting.

**Language-Agnostic Conformance** - For any project type (e.g. Java, Python, PHP, JavaScript, etc.), use the [Conformance plugin's Enforce Project Boundaries rule](/docs/enterprise/conformance). This rule checks dependencies in the Nx graph during `nx conformance:check`. Requires [Nx Enterprise plan](https://nx.dev/enterprise).

Both approaches use the same tag-based constraint system described below.

## Tags

Nx comes with a generic mechanism for expressing constraints on project dependencies: tags.

First, use your project configuration (in `project.json` or `package.json`) to annotate your projects with `tags`. In this example, we will use three tags: `scope:client`. `scope:admin`, `scope:shared`.

{% tabs syncKey="project-config-file" %}
{% tabitem label="package.json" %}

```jsonc
// client/package.json
{
  // ... more project configuration here
  "nx": {
    "tags": ["scope:client"],
  },
}
```

```jsonc
// admin/package.json
{
  // ... more project configuration here
  "nx": {
    "tags": ["scope:admin"],
  },
}
```

```jsonc
// utils/package.json
{
  // ... more project configuration here
  "nx": {
    "tags": ["scope:shared"],
  },
}
```

{% /tabitem %}
{% tabitem label="project.json" %}

```jsonc
// client/project.json
{
  // ... more project configuration here
  "tags": ["scope:client"],
}
```

```jsonc
// admin/project.json
{
  // ... more project configuration here
  "tags": ["scope:admin"],
}
```

```jsonc
// utils/project.json
{
  // ... more project configuration here
  "tags": ["scope:shared"],
}
```

{% /tabitem %}
{% /tabs %}

## Configure boundary rules

Once you have tagged your projects, configure the dependency constraints based on your chosen approach:

{% tabs syncKey="eslint-config-preference" %}
{% tabitem label="ESLint" %}

For JavaScript/TypeScript projects, configure the `@nx/enforce-module-boundaries` ESLint rule:

```shell
nx add @nx/eslint-plugin @nx/devkit
```

And configure the rule in your ESLint configuration:

{% tabs syncKey="eslint-config-preference" %}
{% tabitem label="Flat Config" %}

```javascript
// eslint.config.mjs
import nx from '@nx/eslint-plugin';

export default [
  ...nx.configs['flat/base'],
  ...nx.configs['flat/typescript'],
  ...nx.configs['flat/javascript'],
  {
    files: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
    rules: {
      '@nx/enforce-module-boundaries': [
        'error',
        {
          allow: [],
          // update depConstraints based on your tags
          depConstraints: [
            {
              sourceTag: 'scope:shared',
              onlyDependOnLibsWithTags: ['scope:shared'],
            },
            {
              sourceTag: 'scope:admin',
              onlyDependOnLibsWithTags: ['scope:shared', 'scope:admin'],
            },
            {
              sourceTag: 'scope:client',
              onlyDependOnLibsWithTags: ['scope:shared', 'scope:client'],
            },
          ],
        },
      ],
    },
  },
];
```

{% /tabitem %}
{% tabitem label="Legacy (.eslintrc.json)" %}

```jsonc
// .eslintrc.json
{
  // ... more ESLint config here

  // @nx/enforce-module-boundaries should already exist within an "overrides" block using `"files": ["*.ts", "*.tsx", "*.js", "*.jsx",]`
  "@nx/enforce-module-boundaries": [
    "error",
    {
      "allow": [],
      // update depConstraints based on your tags
      "depConstraints": [
        {
          "sourceTag": "scope:shared",
          "onlyDependOnLibsWithTags": ["scope:shared"],
        },
        {
          "sourceTag": "scope:admin",
          "onlyDependOnLibsWithTags": ["scope:shared", "scope:admin"],
        },
        {
          "sourceTag": "scope:client",
          "onlyDependOnLibsWithTags": ["scope:shared", "scope:client"],
        },
      ],
    },
  ],

  // ... more ESLint config here
}
```

{% /tabitem %}
{% /tabs %}

If you violate the constraints, you will get an error when linting:

```plaintext
A project tagged with "scope:admin" can only depend on projects
tagged with "scoped:shared" or "scope:admin".
```

Read more about [ESLint rule options](/docs/technologies/eslint/eslint-plugin/guides/enforce-module-boundaries).

{% /tabitem %}
{% tabitem label="Conformance" %}

For any project type or to enforce boundaries on the complete dependency graph, use the Conformance plugin:

```shell
nx add @nx/conformance
```

Configure rules in your `nx.json`:

```jsonc
// nx.json
{
  "conformance": {
    "rules": [
      {
        "rule": "@nx/conformance/enforce-project-boundaries",
        "options": {
          "depConstraints": [
            {
              "sourceTag": "scope:shared",
              "onlyDependOnProjectsWithTags": ["scope:shared"],
            },
            {
              "sourceTag": "scope:admin",
              "onlyDependOnProjectsWithTags": ["scope:shared", "scope:admin"],
            },
            {
              "sourceTag": "scope:client",
              "onlyDependOnProjectsWithTags": ["scope:shared", "scope:client"],
            },
          ],
        },
      },
    ],
  },
}
```

Run conformance checks in CI:

```yaml
- name: Enforce all conformance rules
  run: npx nx conformance:check
```

Learn more about [Conformance rules](/docs/enterprise/conformance).

{% /tabitem %}
{% /tabs %}

With these constraints in place, `scope:client` projects can only depend on projects with `scope:client` or `scope:shared`. And `scope:admin` projects can only depend on projects with `scope:admin` or `scope:shared`. So `scope:client` and `scope:admin` cannot depend on each other.

Projects without any tags cannot depend on any other projects. The exception to this rule is by explicitly allowing all tags (see below).

### Tag formats

- `*`: allow all tags

Example: projects with any tags (including untagged) can depend on any other project.

```jsonc
{
  "sourceTag": "*",
  "onlyDependOnLibsWithTags": ["*"],
}
```

- `string`: allow exact tags

Example: projects tagged with `scope:client` can only depend on projects tagged with `scope:util`.

```jsonc
{
  "sourceTag": "scope:client",
  "onlyDependOnLibsWithTags": ["scope:util"],
}
```

- `regex`: allow tags matching the regular expression

Example: projects tagged with `scope:client` can depend on projects with a tag matching the regular expression `/^scope.*/`. In this case, the `scope:util`, `scope:client`, etc. are all allowed tags for dependencies.

```json
{
  "sourceTag": "scope:client",
  "onlyDependOnLibsWithTags": ["/^scope.*/"]
}
```

- `glob`: allow tags matching the glob

Example: projects with a tag starting with `scope:` can depend on projects with a tag that starts with `scope:*`. In this case `scope:a`, `scope:b`, etc are all allowed tags for dependencies.

```json
{
  "sourceTag": "scope:*",
  "onlyDependOnLibsWithTags": ["scope:*"]
}
```

Globbing supports only the basic use of `*`. For more complex scenarios use the `regex` above.

---
<!-- source: https://nx.dev/docs/features/enhance-ai.md -->
## Enhance Your AI Coding Agent

AI agents are moving beyond autocomplete. They can now operate independently across projects. But most setups hit a wall: agents lack workspace context (seeing files, not architecture), generate inconsistent code, and have a hard time to interact with CI.

Nx monorepos solve this by enabling cross-project reasoning and by providing the structured metadata and CI integration that agents need to work autonomously:

- Deep **workspace architecture** understanding and project relationships
- **Code generators** for fast, predictable scaffolding
- **CI pipeline integration** to fix failures autonomously
- The ability to **iterate until CI is green** without human intervention

## Setup

To configure your Nx workspace for AI agents, run:

```shell
npx nx configure-ai-agents
```

This sets up:

- **Agent configuration files**: `CLAUDE.md`, `AGENTS.md` with workspace-specific guidelines
- **Agent skills**: Domain-specific knowledge for monorepo workflows — workspace exploration, code generation, task execution, CI monitoring, and package linking. Skills teach agents _how_ to work with Nx rather than dumping data into context.
- **Nx MCP server**: Provides connectivity to Nx Cloud CI pipelines, self-healing fixes, running processes, and Nx documentation — things agents can't easily reach on their own

### Creating new workspaces

For creating new Nx workspaces, use `npx create-nx-workspace@latest --template=nrwl/<name>-template` (e.g. `react-template`, `angular-template`, `typescript-template`). For existing projects, use `npx nx init`.

## What this enables

### Self-healing CI integration

Nx Cloud provides AI-powered [Self-Healing CI](/docs/features/ci-features/self-healing-ci) that analyzes failed runs and proposes verified fixes. With `configure-ai-agents`, your local agent connects to this CI counterpart via skills and the Nx MCP, gaining full context about run information, failures, and suggested fixes.

Your agent can autonomously iterate until CI passes:

```text
Commit this work, create a PR, and monitor CI until it's green.
```

The workflow:

1. Agent pushes changes and creates PR
2. Monitors CI pipeline
3. Receives failure context from Nx Cloud and Self-Healing CI
4. Accepts proposed fix or pulls context locally and manually applies it
5. Repeats until CI is green

This reduces context-switching—you review the final PR rather than intervening at each failure.

### Workspace architecture understanding

Nx exposes the project graph and relevant metadata to AI agents. This helps them move faster and more precisely:

- Identify all applications and libraries in the workspace
- Understand project relationships and dependencies
- Recognize project types and ownership via tags
- Determine which projects are affected by changes
- Suggest where to implement new functionality based on existing structure

This architectural awareness is critical for agents operating in large monorepos where understanding project relationships determines the quality of generated code.

### Predictable, fast code generation

AI-generated code is token-intensive, slow, and not guaranteed to align with patterns in other projects. Nx generators solve this by providing predictable scaffolding that agents can invoke and then adapt.

Your AI agent can:

1. Find generators from [Nx plugins](/docs/plugin-registry) or custom [local workspace generators](/docs/extending-nx/local-generators)
2. Run the generator with correct options
3. Make small adjustments based on the specific situation

This approach is faster, produces consistent code across projects, and reduces hallucinations.

## Learn more

- [Autonomous AI Agents at Scale](https://nx.dev/blog/ai-agents-and-continuity): Infrastructure requirements for AI agent workflows
- [Why Nx and AI Work So Well Together](https://nx.dev/blog/nx-and-ai-why-they-work-together): The foundation for AI-powered development
- [Nx MCP Server Reference](/docs/reference/nx-mcp): Complete tool reference and setup instructions

---
<!-- source: https://nx.dev/docs/features/explore-graph.md -->
## Explore your Workspace

Nx understands your workspace as a collection of projects.
Each project can be explored to view the different tasks which can be run.

The projects in the workspace have dependencies between them and form a graph known as the **Project Graph**.
Nx uses this project graph in many ways to make informed decisions such as which tasks to run, when the results of a task can be restored from cache, and more.

In addition to the project graph, Nx also runs your tasks as a **Task Graph**.
This is a separate graph of tasks and their dependencies which is based on the project graph and determines the way in which the tasks are executed.

Nx allows you to interactively explore your workspace through a UI which shows the information above.
Using this tool is _vital_ to understanding both your workspace as well as how Nx behaves.

Teach you to use this tool to explore projects, the project graph, and the task graphs for your workspace.

## Explore projects in your workspace

Projects in Nx are the different parts of the monorepo which can have tasks run for them.

The best way to see what projects are in your workspace is to view the [project graph](#explore-the-project-graph) which will be covered in the next section.
Another way is to look at the **Projects** pane in [Nx Console](/docs/getting-started/editor-setup) or run `nx show projects` to show a list of projects in your terminal.

You can see more details about a specific project in Nx Console or by running `nx show project <project-name> --web`. Both methods will show something like the example below:

{% project_details %}

```json
{
  "project": {
    "name": "myreactapp",
    "type": "app",
    "data": {
      "root": "apps/myreactapp",
      "targets": {
        "build": {
          "options": {
            "cwd": "apps/myreactapp",
            "command": "vite build"
          },
          "cache": true,
          "dependsOn": ["^build"],
          "inputs": [
            "production",
            "^production",
            {
              "externalDependencies": ["vite"]
            }
          ],
          "outputs": ["{workspaceRoot}/dist/apps/myreactapp"],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["vite"]
          }
        },
        "serve": {
          "options": {
            "cwd": "apps/myreactapp",
            "command": "vite serve",
            "continuous": true
          },
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["vite"]
          }
        },
        "preview": {
          "options": {
            "cwd": "apps/myreactapp",
            "command": "vite preview"
          },
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["vite"]
          }
        },
        "serve-static": {
          "executor": "@nx/web:file-server",
          "options": {
            "buildTarget": "build",
            "continuous": true
          },
          "configurations": {}
        },
        "test": {
          "options": {
            "cwd": "apps/myreactapp",
            "command": "vitest run"
          },
          "cache": true,
          "inputs": [
            "default",
            "^production",
            {
              "externalDependencies": ["vitest"]
            }
          ],
          "outputs": ["{workspaceRoot}/coverage/apps/myreactapp"],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["vite"]
          }
        },
        "lint": {
          "cache": true,
          "options": {
            "cwd": "apps/myreactapp",
            "command": "eslint ."
          },
          "inputs": [
            "default",
            "{workspaceRoot}/.eslintrc.json",
            "{workspaceRoot}/apps/myreactapp/.eslintrc.json",
            "{workspaceRoot}/tools/eslint-rules/**/*",
            {
              "externalDependencies": ["eslint"]
            }
          ],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["eslint"]
          }
        }
      },
      "name": "myreactapp",
      "$schema": "../../../node_modules/nx/schemas/project-schema.json",
      "sourceRoot": "apps/myreactapp/src",
      "projectType": "application",
      "tags": [],
      "implicitDependencies": [],
      "metadata": {
        "technologies": ["react"]
      }
    }
  },
  "sourceMap": {
    "root": ["apps/myreactapp/project.json", "nx/core/project-json"],
    "targets": ["apps/myreactapp/project.json", "nx/core/project-json"],
    "targets.build": ["apps/myreactapp/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.command": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.options": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.cache": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.dependsOn": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.inputs": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.outputs": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.options.cwd": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.serve": ["apps/myreactapp/vite.config.ts", "@nx/vite/plugin"],
    "targets.serve.command": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.serve.options": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.serve.options.cwd": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.preview": ["apps/myreactapp/vite.config.ts", "@nx/vite/plugin"],
    "targets.preview.command": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.preview.options": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.preview.options.cwd": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.serve-static": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.serve-static.executor": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.serve-static.options": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.serve-static.options.buildTarget": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.test": ["apps/myreactapp/vite.config.ts", "@nx/vite/plugin"],
    "targets.test.command": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.test.options": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.test.cache": ["apps/myreactapp/vite.config.ts", "@nx/vite/plugin"],
    "targets.test.inputs": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.test.outputs": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.test.options.cwd": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.lint": ["apps/myreactapp/project.json", "@nx/eslint/plugin"],
    "targets.lint.command": [
      "apps/myreactapp/project.json",
      "@nx/eslint/plugin"
    ],
    "targets.lint.cache": ["apps/myreactapp/project.json", "@nx/eslint/plugin"],
    "targets.lint.options": [
      "apps/myreactapp/project.json",
      "@nx/eslint/plugin"
    ],
    "targets.lint.inputs": [
      "apps/myreactapp/project.json",
      "@nx/eslint/plugin"
    ],
    "targets.lint.options.cwd": [
      "apps/myreactapp/project.json",
      "@nx/eslint/plugin"
    ],
    "name": ["apps/myreactapp/project.json", "nx/core/project-json"],
    "$schema": ["apps/myreactapp/project.json", "nx/core/project-json"],
    "sourceRoot": ["apps/myreactapp/project.json", "nx/core/project-json"],
    "projectType": ["apps/myreactapp/project.json", "nx/core/project-json"],
    "tags": ["apps/myreactapp/project.json", "nx/core/project-json"]
  }
}
```

{% /project_details %}

The view shows a list of targets which can be [run by Nx](/docs/features/run-tasks).
Each target has different options which determine how Nx runs the task.

## Explore the project graph

Nx understands the projects in your workspace as a graph and uses this understanding to behave intelligently.
Exploring this graph visually is vital to understanding how your code is structured and how Nx behaves.
It always stays up to date without having to actively maintain a document as it is calculated by analyzing your source code.

### Launching the project graph

To launch the project graph visualization for your workspace, use [Nx Console](/docs/getting-started/editor-setup) or run:

```shell
npx nx graph
```

This will open a browser window with an interactive view of the project graph of your workspace.

### Focusing on valuable projects

Viewing the entire graph can be unmanageable even for smaller repositories, so there are several ways to narrow the
focus of the visualization down to the most useful part of the graph at the moment.

1. Focus on a specific project and then use the proximity and group by folder controls in the sidebar to modify the graph around that
   project. You can also start the graph with a project focused by running `nx graph --focus <project-name>`.
2. Use the search bar to find all projects with names that contain a certain string.
3. Manually hide or show projects in the sidebar.

Once the graph is displayed, you can explore deeper by clicking on nodes and edges in the graph.
Click on a node to show a tooltip which also has a link to view more details about the project.
You can trace the dependency chain between two projects by choosing a **Start** and **End** point in the project tooltips.
Click on any dependency line to find which file(s) created the dependency.

Composite nodes represent a set of projects in the same folder and can be expanded in place to show all the individual projects and their dependencies. You can also "focus" a composite node to render a graph of just the projects inside that node. Composite nodes are essential to navigate a graph of even a moderate size.

Try playing around with a [fully interactive graph on a sample repo](https://nrwl-nx-examples-dep-graph.netlify.app/?focus=cart) or look at the more limited example below:

**Project View:**

{% graph height="450px" title="Project View" %}

```json
{
  "composite": false,
  "projects": [
    {
      "name": "shared-product-state",
      "type": "lib",
      "data": {
        "root": "shared/product-state",
        "tags": ["scope:shared", "type:state"]
      }
    },
    {
      "name": "shared-product-types",
      "type": "lib",
      "data": {
        "root": "shared/product-types",
        "tags": ["type:types", "scope:shared"]
      }
    },
    {
      "name": "shared-product-data",
      "type": "lib",
      "data": {
        "root": "shared/product-data",
        "tags": ["type:data", "scope:shared"]
      }
    },
    {
      "name": "cart-cart-page",
      "type": "lib",
      "data": {
        "root": "cart/cart-page",
        "tags": ["scope:cart", "type:feature"]
      }
    },
    {
      "name": "shared-styles",
      "type": "lib",
      "data": {
        "root": "shared/styles",
        "tags": ["scope:shared", "type:styles"]
      }
    },
    {
      "name": "e2e-cart",
      "type": "e2e",
      "data": {
        "root": "e2e/cart",
        "tags": ["scope:cart", "type:e2e"]
      }
    },
    {
      "name": "cart",
      "type": "app",
      "data": {
        "root": "cart",
        "tags": ["type:app", "scope:cart"]
      }
    }
  ],
  "dependencies": {
    "shared-product-state": [
      {
        "source": "shared-product-state",
        "target": "shared-product-data",
        "type": "static"
      },
      {
        "source": "shared-product-state",
        "target": "shared-product-types",
        "type": "static"
      }
    ],
    "shared-product-types": [],
    "shared-product-data": [
      {
        "source": "shared-product-data",
        "target": "shared-product-types",
        "type": "static"
      }
    ],
    "shared-e2e-utils": [],
    "cart-cart-page": [
      {
        "source": "cart-cart-page",
        "target": "shared-product-state",
        "type": "static"
      }
    ],
    "shared-styles": [],
    "e2e-cart": [
      { "source": "e2e-cart", "target": "cart", "type": "implicit" }
    ],
    "cart": [
      { "source": "cart", "target": "shared-styles", "type": "implicit" },
      { "source": "cart", "target": "cart-cart-page", "type": "static" }
    ]
  },
  "workspaceLayout": {
    "appsDir": "apps",
    "libsDir": "libs"
  },
  "affectedProjectIds": [],
  "focus": null,
  "groupByFolder": false,
  "exclude": [],
  "enableTooltips": false
}
```

{% /graph %}

**Composite View (Nx 20+):**

{% graph height="450px" title="Composite View (Nx 20+)" %}

```json
{
  "composite": true,
  "projects": [
    {
      "name": "shared-product-state",
      "type": "lib",
      "data": {
        "root": "shared/product-state",
        "tags": ["scope:shared", "type:state"]
      }
    },
    {
      "name": "shared-product-types",
      "type": "lib",
      "data": {
        "root": "shared/product-types",
        "tags": ["type:types", "scope:shared"]
      }
    },
    {
      "name": "shared-product-data",
      "type": "lib",
      "data": {
        "root": "shared/product-data",
        "tags": ["type:data", "scope:shared"]
      }
    },
    {
      "name": "cart-cart-page",
      "type": "lib",
      "data": {
        "root": "cart/cart-page",
        "tags": ["scope:cart", "type:feature"]
      }
    },
    {
      "name": "shared-styles",
      "type": "lib",
      "data": {
        "root": "shared/styles",
        "tags": ["scope:shared", "type:styles"]
      }
    },
    {
      "name": "e2e-cart",
      "type": "e2e",
      "data": {
        "root": "e2e/cart",
        "tags": ["scope:cart", "type:e2e"]
      }
    },
    {
      "name": "cart",
      "type": "app",
      "data": {
        "root": "cart/cart",
        "tags": ["type:app", "scope:cart"]
      }
    }
  ],
  "dependencies": {
    "shared-product-state": [
      {
        "source": "shared-product-state",
        "target": "shared-product-data",
        "type": "static"
      },
      {
        "source": "shared-product-state",
        "target": "shared-product-types",
        "type": "static"
      }
    ],
    "shared-product-types": [],
    "shared-product-data": [
      {
        "source": "shared-product-data",
        "target": "shared-product-types",
        "type": "static"
      }
    ],
    "shared-e2e-utils": [],
    "cart-cart-page": [
      {
        "source": "cart-cart-page",
        "target": "shared-product-state",
        "type": "static"
      }
    ],
    "shared-styles": [],
    "e2e-cart": [
      { "source": "e2e-cart", "target": "cart", "type": "implicit" }
    ],
    "cart": [
      { "source": "cart", "target": "shared-styles", "type": "implicit" },
      { "source": "cart", "target": "cart-cart-page", "type": "static" }
    ]
  },
  "workspaceLayout": {
    "appsDir": "apps",
    "libsDir": "libs"
  },
  "affectedProjectIds": [],
  "focus": null,
  "groupByFolder": false,
  "exclude": [],
  "enableTooltips": false
}
```

{% /graph %}

### Export project graph to JSON

If you prefer to analyze the underlying data of the project graph with a script or some other tool, you can run:

```shell
nx graph --file=output.json
```

This will give you all the information that is used to create the project graph visualization.

### Export the project graph as an image

There is a floating action button in the bottom right of the project graph view which will save the graph as a `.png` file.
Sharing this image with other developers is a great way to express how a project fits into the workspace.
Some moments which you may want to share these images are:

- When providing a high-level overview of the workspace
- When introducing new project(s) into the workspace
- When changing how project(s) are related
- To share which other projects are directly affected by changes you are making

## Explore the task graph

Nx uses the project graph of your workspace to determine the order in which to [run tasks](/docs/features/run-tasks). Pass the `--graph` flag to view the **task graph** which is executed by Nx when running a command.

```shell
nx build myreactapp --graph # View the graph for building myreactapp
nx run-many --targets build --graph # View the graph for building all projects
nx affected --targets build --graph # View the graph for building the affected projects
```

Click on the nodes of this graph to see more information about the task such as:

- Which executor was used to run the command
- Which [inputs](/docs/guides/tasks--caching/configure-inputs) are used to calculate the computation hash.
- A link to see more details about the project which the task belongs to

Dependencies in this graph mean that Nx will need to wait for all task dependencies to complete successfully before running the task.

---
<!-- source: https://nx.dev/docs/features/generate-code.md -->
## Generate Code

{% youtube src="https://youtu.be/hSM6MgWOYr8" title="Generate Code" /%}

Code generators are like automation scripts that help you scaffold projects, enforce best practices, and automate repetitive tasks. Essentially, they are TypeScript functions that accept parameters and help boost your productivity by:

- Allowing you to **scaffold new projects** or **augment existing projects** with new features, like [adding Storybook support](/docs/technologies/test-tools/storybook/introduction#generating-storybook-configuration)
- **Automating repetitive tasks** in your development workflow
- Ensuring your **code is consistent and follows best practices**

## Invoke generators

Generators come as part of [Nx plugins](/docs/concepts/nx-plugins) and can be invoked using the `nx generate` command (or `nx g`) using the following syntax: `nx g <plugin-name>:<generator-name> [options]`.

Here's an example of generating a React library:

```shell
nx g @nx/react:lib packages/mylib
```

You can also specify just the generator name and Nx will prompt you to pick between the installed plugins that provide a generator with that name.

```shell
nx g lib packages/mylib
```

When running this command, you could be prompted to choose between the `@nx/react` and `@nx/js` plugins that each provide a library generator.

To see a list of available generators in a given plugin, run `nx list <plugin-name>`. As an example, to list all generators in the @nx/react plugin:

```shell
nx list @nx/react
```

### Use Nx Console

If you prefer a visual interface, then [Nx Console](/docs/getting-started/editor-setup) is an excellent alternative. It provides a way to visually find and run generators:

![Using Nx Console to run generators](../../../assets/nx-console/nx-console-gen-code.avif)

Nx Console is an IDE extension that can be [installed here](/docs/getting-started/editor-setup).

## Build your own generator

You can also customize existing generators by overwriting their behavior or create completely new ones. This is a powerful mechanism as it allows you to:

- **automate** your organization's specific processes and workflows
- **standardize** how and where projects are created in your workspace to make sure they reflect your organization's best practices and coding standards
- **ensure** that your codebase follows your organization's best practices and style guides

At their core, generators are just functions with a specific signature and input options that get invoked by Nx. Something like the following:

```typescript
// generator.ts
import { Tree, formatFiles, installPackagesTask } from '@nx/devkit';

export default async function (tree: Tree, schema: any) {
  // Your implementation here
  // ...

  await formatFiles(tree);
  return () => {
    installPackagesTask(tree);
  };
}
```

To help build generators, Nx provides the `@nx/devkit` package containing utilities and helpers. Learn more about creating your own generators on [our docs page](/docs/extending-nx/local-generators) or watch the video below:

{% youtube src="https://www.youtube.com/embed/myqfGDWC2go" title="Scaffold new Pkgs in a PNPM Workspaces Monorepo" caption="Demonstrates how to use Nx generators in a PNPM workspace to automate the creation of libraries" /%}

---
<!-- source: https://nx.dev/docs/features/maintain-typescript-monorepos.md -->
## Maintain TypeScript Monorepos

Keeping all the industry-standard tools involved in a large TypeScript monorepo correctly configured and working well together is a difficult task. And the more tools you add, the more opportunity there is for tools to conflict with each other in some way.

In addition to [generating default configuration files](/docs/features/generate-code) and [automatically updating dependencies](/docs/features/automate-updating-dependencies) to versions that we know work together, Nx makes managing all the tools in your monorepo easier in two ways:

- Rather than adding another tool that you have to configure, Nx configures itself to match the existing configuration of other tools.
- Nx also enhances certain tools to be more usable in a monorepo context.

## Auto-configuration

Whenever possible, Nx will detect the existing configuration settings of other tools and update itself to match.

### Project detection with workspaces

If your repository is using package manager workspaces, Nx will use those settings to find all the [projects](/docs/reference/project-configuration) in your repository. So you don't need to define a project for your package manager and separately identify the project for Nx. The `workspaces` configuration allows Nx to detect the project graph.

```json
// package.json
{
  "workspaces": ["apps/*", "packages/*"]
}
```

{% graph height="200px" title="Project View" %}

```json
{
  "composite": false,
  "projects": [
    {
      "name": "product-state",
      "type": "lib",
      "data": {
        "root": "packages/cart/product-state",
        "tags": ["scope:cart", "type:state"]
      }
    },
    {
      "name": "ui-buttons",
      "type": "lib",
      "data": {
        "root": "packages/ui/buttons",
        "tags": ["scope:shared", "type:ui"]
      }
    },
    {
      "name": "cart",
      "type": "app",
      "data": {
        "root": "apps/cart",
        "tags": ["type:app", "scope:cart"]
      }
    }
  ],
  "dependencies": {
    "product-state": [],
    "ui-buttons": [],
    "cart": [
      { "source": "cart", "target": "product-state", "type": "static" },
      { "source": "cart", "target": "ui-buttons", "type": "static" }
    ]
  },
  "workspaceLayout": {
    "appsDir": "apps",
    "libsDir": "libs"
  },
  "affectedProjectIds": [],
  "focus": null,
  "groupByFolder": false,
  "exclude": [],
  "enableTooltips": false
}
```

{% /graph %}

### Inferred tasks with tooling plugins

Nx [plugins](/docs/concepts/nx-plugins) for tools like Vite, TypeScript, Playwright, and Jest automatically [infer task configuration](/docs/concepts/inferred-tasks) from your existing tooling config files — keeping them as the single source of truth.

In the example below, because the `/apps/cart/vite.config.ts` file exists, Nx knows that the `cart` project can run a `build` task using Vite. If you expand the `build` task, you can also see that Nx configured the output directory for the [cache](/docs/features/cache-task-results) to match the `build.outDir` provided in the Vite configuration file.

```ts
// /apps/cart/vite.config.ts
/// <reference types='vitest' />
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  root: __dirname,
  cacheDir: '../../node_modules/.vite/apps/cart',
  plugins: [react()],
  build: {
    outDir: './dist',
    emptyOutDir: true,
    reportCompressedSize: true,
    commonjsOptions: {
      transformMixedEsModules: true,
    },
  },
});
```

{% project_details %}

```json
{
  "project": {
    "name": "cart",
    "type": "app",
    "data": {
      "root": "apps/cart",
      "targets": {
        "build": {
          "options": {
            "cwd": "apps/cart",
            "command": "vite build"
          },
          "cache": true,
          "dependsOn": ["^build"],
          "inputs": [
            "production",
            "^production",
            {
              "externalDependencies": ["vite"]
            }
          ],
          "outputs": ["{projectRoot}/dist"],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["vite"]
          }
        }
      },
      "name": "cart",
      "$schema": "../../../node_modules/nx/schemas/project-schema.json",
      "sourceRoot": "apps/cart/src",
      "projectType": "application",
      "tags": [],
      "implicitDependencies": [],
      "metadata": {
        "technologies": ["react"]
      }
    }
  },
  "sourceMap": {
    "root": ["apps/cart/project.json", "nx/core/project-json"],
    "targets": ["apps/cart/project.json", "nx/core/project-json"],
    "targets.build": ["apps/cart/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.command": ["apps/cart/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.options": ["apps/cart/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.cache": ["apps/cart/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.dependsOn": ["apps/cart/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.inputs": ["apps/cart/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.outputs": ["apps/cart/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.options.cwd": [
      "apps/cart/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "name": ["apps/cart/project.json", "nx/core/project-json"],
    "$schema": ["apps/cart/project.json", "nx/core/project-json"],
    "sourceRoot": ["apps/cart/project.json", "nx/core/project-json"],
    "projectType": ["apps/cart/project.json", "nx/core/project-json"],
    "tags": ["apps/cart/project.json", "nx/core/project-json"]
  }
}
```

{% /project_details %}

## Enhance tools for monorepos

Nx does not just reduce its own configuration burden, it also improves the functionality of your existing tools so that they work better in a monorepo context.

### Keep TypeScript project references in sync

TypeScript provides a feature called [Project References](https://www.typescriptlang.org/docs/handbook/project-references.html) that allows the TypeScript compiler to build and typecheck each project independently. When each project is typechecked, the TypeScript compiler will output an intermediate `*.tsbuildinfo` file that can be used by other projects instead of re-typechecking all dependencies. This feature can provide [significant performance improvements](/docs/concepts/typescript-project-linking#typescript-project-references-performance-benefits), particularly in a large monorepo.

The main downside of this feature is that you have to manually define each project's references (dependencies) in the appropriate `tsconfig.*.json` file. This process is tedious to set up and very difficult to maintain as the repository changes over time. Nx can help by using a [sync generator](/docs/concepts/sync-generators) to automatically update the references defined in the `tsconfig.json` files based on the project graph it already knows about.

{% graph height="200px" title="Project View" %}

```json
{
  "composite": false,
  "projects": [
    {
      "name": "product-state",
      "type": "lib",
      "data": {
        "root": "packages/cart/product-state",
        "tags": ["scope:cart", "type:state"]
      }
    },
    {
      "name": "ui-buttons",
      "type": "lib",
      "data": {
        "root": "packages/ui/buttons",
        "tags": ["scope:shared", "type:ui"]
      }
    },
    {
      "name": "cart",
      "type": "app",
      "data": {
        "root": "apps/cart",
        "tags": ["type:app", "scope:cart"]
      }
    }
  ],
  "dependencies": {
    "product-state": [],
    "ui-buttons": [],
    "cart": [
      { "source": "cart", "target": "product-state", "type": "static" },
      { "source": "cart", "target": "ui-buttons", "type": "static" }
    ]
  },
  "workspaceLayout": {
    "appsDir": "apps",
    "libsDir": "libs"
  },
  "affectedProjectIds": [],
  "focus": null,
  "groupByFolder": false,
  "exclude": [],
  "enableTooltips": false
}
```

{% /graph %}

```jsonc
// apps/cart/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "files": [], // intentionally empty
  "references": [
    // UPDATED BY NX SYNC
    // All project dependencies
    {
      "path": "../../packages/product-state",
    },
    {
      "path": "../../packages/ui/buttons",
    },
    // This project's other tsconfig.*.json files
    {
      "path": "./tsconfig.lib.json",
    },
    {
      "path": "./tsconfig.spec.json",
    },
  ],
}
```

Later, if someone adds another dependency to the `cart` app and then runs the `build` task, Nx will detect that the project references are out of sync and ask if the references should be updated.

```plaintext {% title="nx build cart" frame="terminal" %}
 NX   The workspace is out of sync

[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references to the projects they depend on or contain outdated project references.

This will result in an error in CI.

? Would you like to sync the identified changes to get your workspace up to date? …
❯ Yes, sync the changes and run the tasks
  No, run the tasks without syncing the changes
```

---
<!-- source: https://nx.dev/docs/features/manage-releases.md -->
## Manage Releases

Once you have leveraged Nx powerful code generation and task running capabilities to build your libraries and applications, you will want to share them with your users.

{% linkcard title="Free Course: Versioning and Releasing NPM packages with Nx" href="https://www.epicweb.dev/tutorials/versioning-and-releasing-npm-packages-with-nx" /%}

Nx provides a set of tools to help you manage your releases called `nx release`.

> We recommend always starting with --dry-run, because publishing is difficult to undo

```shell
nx release --dry-run
```

## What makes up a release?

A release can be thought about in three main phases:

1. **Versioning** - The process of determining the next version of your projects, and updating any projects that depend on them to use the new version.
2. **Changelog** - The process of deriving a changelog from your commit messages or [version plan](/docs/guides/nx-release/file-based-versioning-version-plans) files, which can be used to communicate the changes to your users.
3. **Publishing** - The process of publishing your projects to a registry, such as npm for TypeScript/JavaScript libraries, crates.io for Rust, or Docker registries for container images.

## Running releases

The `nx release` command is used to run the release process from end to end. It is a wrapper around the three main phases of a release to provide maximum convenience and ease of use.

By default, when you run `nx release` it will prompt you for a version keyword (e.g. major, minor, patch) or a custom version number. The release command will then run the three phases of the release process in order: versioning, changelog generation, and publishing.

When trying it out for the first time, you need to pass the `--first-release` flag since there is no previous release to compare against for changelog purposes. It is strongly recommended to use the `--dry-run` flag to see what will be published in the first release without actually pushing anything to the registry.

```shell
nx release --first-release --dry-run
```

{% aside type="tip" title="Semantic Versioning" %}
By default, the version follows semantic versioning (semver) rules. To disable this behavior, set `release.releaseTag.requireSemver` to `false` in your `nx.json` file. This allows you to use custom versioning schemes.
{% /aside %}

## Set up your workspace

Follow our guides to set up Nx Release for your workspace.

{% cardgrid %}

{% linkcard title="TypeScript/JavaScript to NPM" description="Publish TypeScript and JavaScript packages to NPM or private registries with semantic versioning." href="/docs/guides/nx-release/release-npm-packages" /%}

{% linkcard title="Docker Images" description="Version and publish Docker images with calendar-based versioning for continuous deployment."  href="/docs/guides/nx-release/release-docker-images" /%}

{% linkcard title="Rust Crates" description="Publish Rust packages to crates.io with cargo integration." href="/docs/guides/nx-release/publish-rust-crates" /%}

{% /cardgrid %}

## Basic configuration

Configure Nx Release in your `nx.json` file:

```jsonc
// nx.json
{
  "release": {
    "projects": ["packages/*"],
  },
}
```

The nx release command is customizable. You can customize the versioning, changelog, and publishing phases of the release process independently through a mixture of configuration and CLI arguments.

See the [configuration reference](/docs/reference/nx-json#release) for all available options.

## Using the programmatic API for Nx release

A powerful feature of Nx Release is the fact that it is designed to be used via a Node.js programmatic API in addition to the `nx release` CLI.

Releases are a hugely complex and nuanced process, filled with many special cases and idiosyncratic preferences, and it is impossible for a CLI to be able to support all of them out of the box. By having a first-class programmatic API, you can go beyond the CLI and create custom release workflows that are highly dynamic and tailored to your specific needs.

See our dedicated guide on the [programmatic API](/docs/guides/nx-release/programmatic-api) to learn more and see some example release scripts.

## Learn more

### Configuration & customization

- **[Version Projects Independently](/docs/guides/nx-release/release-projects-independently)** - Version projects independently or together
- **[Release Groups](/docs/guides/nx-release/release-groups)** - Organize projects into release groups with specific configuration for each group
- **[Conventional Commits](/docs/guides/nx-release/automatically-version-with-conventional-commits)** - Automate versioning based on commit messages
- **[Custom Registries](/docs/guides/nx-release/configure-custom-registries)** - Publish to private or alternative registries
- **[CI/CD Integration](/docs/guides/nx-release/publish-in-ci-cd)** - Automate releases in your pipeline
- **[Changelog Customization](/docs/guides/nx-release/configure-changelog-format)** - Control changelog generation and formatting
- **[Custom Commit Types](/docs/guides/nx-release/customize-conventional-commit-types)** - Define custom conventional commit types
- **[Version Prefixes](/docs/guides/nx-release/configuration-version-prefix)** - Configure version prefix patterns

### Workflows

- **[Automate with GitHub Actions](/docs/guides/nx-release/automate-github-releases)** - Set up automated releases in GitHub workflows
- **[Release Projects Independently](/docs/guides/nx-release/release-projects-independently)** - Manage independent versioning for projects
- **[Use Conventional Commits](/docs/guides/nx-release/automatically-version-with-conventional-commits)** - Enable automatic versioning from commits
- **[Build Before Versioning](/docs/guides/nx-release/build-before-versioning)** - Run builds before version updates

### References

- **[`nx.json` configuration options](/docs/reference/nx-json#release)** - All available options for configuring `nx release`
- **[`nx release` command](/docs/reference/nx-commands#nx-release)** - Run versioning, changelog generation, and publishing
- **[`nx release version` command](/docs/reference/nx-commands#nx-release-version)** - Run only the versioning step
- **[`nx release changelog` command](/docs/reference/nx-commands#nx-release-changelog)** - Run only the changelog generation step
- **[`nx release publish` command](/docs/reference/nx-commands#nx-release-publish)** - Run only the publishing step
- **[`nx release plan` command](/docs/reference/nx-commands#nx-release-plan)** - Create a version plan file for file-based versioning

---
<!-- source: https://nx.dev/docs/features/run-tasks.md -->
## Run Tasks

{% youtube src="https://youtu.be/aEdfYiA5U34" title="Run tasks with Nx" /%}

In a monorepo setup, you don't just run tasks for a single project; you might have hundreds to manage. To help with this, Nx provides a powerful task runner that allows you to:

- easily **run multiple targets** for multiple projects **in parallel**
- define **task pipelines** to run tasks in the correct order
- only run tasks for **projects affected by a given change**
- **speed up task execution** with [caching](/docs/features/cache-task-results)

## Define tasks

Nx tasks can be created from existing `package.json` scripts, [inferred from tooling configuration files](/docs/concepts/inferred-tasks), or defined in a `project.json` file. Nx combines these three sources to determine the tasks for a particular project.

{% tabs syncKey="project-config-file" %}
{% tabitem label="package.json" %}

```json
// libs/mylib/package.json
{
  "name": "mylib",
  "scripts": {
    "build": "tsc -p tsconfig.lib.json",
    "test": "jest"
  }
}
```

{% /tabitem %}
{% tabitem label="project.json" %}

```json
// libs/mylib/project.json
{
  "root": "libs/mylib",
  "targets": {
    "build": {
      "command": "tsc -p tsconfig.lib.json"
    },
    "test": {
      "executor": "@nx/jest:jest",
      "options": {
        /* ... */
      }
    }
  }
}
```

{% /tabitem %}
{% tabitem label="Inferred by Nx Plugins" %}

[Nx plugins](/docs/concepts/nx-plugins) can detect your tooling configuration files (e.g. `vite.config.ts` or `.eslintrc.json`) and automatically configure runnable tasks including [Nx cache](/docs/features/cache-task-results). For example, the `@nx/jest` plugin will automatically create a `test` task for a project that uses Jest. The names can be configured in the `nx.json` file:

```json
// nx.json
{
  ...
  "plugins": [
    {
      "plugin": "@nx/vite/plugin",
      "options": {
        "buildTargetName": "build",
        "testTargetName": "test",
        "serveTargetName": "serve",
        "previewTargetName": "preview",
        "serveStaticTargetName": "serve-static"
      }
    },
    {
      "plugin": "@nx/eslint/plugin",
      "options": {
        "targetName": "lint"
      }
    },
    {
      "plugin": "@nx/jest/plugin",
      "options": {
        "targetName": "test"
      }
    }
  ],
  ...
}
```

Learn more about [inferred tasks here](/docs/concepts/inferred-tasks).

{% /tabitem %}
{% /tabs %}

The [project configuration docs](/docs/reference/project-configuration) has the details for all the available configuration options.

## Run tasks

Nx uses the following syntax:

![Syntax for Running Tasks in Nx](../../../assets/features/run-target-syntax.svg)

{% aside type="tip" title="Terminal UI" %}

In Nx 21, task output is displayed in an [interactive terminal UI](/docs/guides/tasks--caching/terminal-ui) that allows you to actively choose which task output to display, search through the list of tasks and display multiple tasks side by side.

{% /aside %}

### Run a single task

To run the `test` task for the `header` project run this command:

```shell
npx nx test header
```

### Run tasks for multiple projects

You can use the `run-many` command to run a task for multiple projects. Here are a couple of examples.

Run the `build` task for all projects in the repo:

```shell
npx nx run-many -t build
```

Run the `build`, `lint` and `test` task for all projects in the repo:

```shell
npx nx run-many -t build lint test
```

Run the `build`, `lint`, and `test` tasks only on the `header` and `footer` projects:

```shell
npx nx run-many -t build lint test -p header footer
```

Nx parallelizes these tasks, ensuring they **run in the correct order based on their dependencies** and [task pipeline configuration](/docs/concepts/task-pipeline-configuration). You can also [control how many tasks run in parallel at once](/docs/guides/tasks--caching/run-tasks-in-parallel).

Learn more about the [run-many](/docs/reference/nx-commands#nx-run-many) command.

### Run tasks on projects affected by a PR

You can also run a command for all the projects affected by your PR like this:

```shell
npx nx affected -t test
```

Learn more about the [affected command here](/docs/features/ci-features/affected).

## Defining a task pipeline

It is pretty common to have dependencies between tasks, requiring one task to be run before another. For example, you might want to run the `build` target on the `header` project before running the `build` target on the `app` project.

Nx can automatically detect the dependencies between projects (see [project graph](/docs/features/explore-graph)).

{% graph height="450px" %}

```json
{
  "projects": [
    {
      "name": "myreactapp",
      "type": "app",
      "data": {
        "tags": []
      }
    },
    {
      "name": "shared-ui",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "feat-products",
      "type": "lib",
      "data": {
        "tags": []
      }
    }
  ],
  "dependencies": {
    "myreactapp": [
      { "source": "myreactapp", "target": "feat-products", "type": "static" }
    ],
    "shared-ui": [],
    "feat-products": [
      {
        "source": "feat-products",
        "target": "shared-ui",
        "type": "static"
      }
    ]
  },
  "workspaceLayout": { "appsDir": "", "libsDir": "" },
  "affectedProjectIds": [],
  "focus": null,
  "groupByFolder": false
}
```

{% /graph %}

However, you need to specify for which targets this ordering is important. In the following example we are telling Nx that before running the `build` target it needs to run the `build` target on all the projects the current project depends on:

```json
// nx.json
{
  ...
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}
```

This means that if we run `nx build myreactapp`, Nx will first execute `build` on `shared-ui` and `feat-products` before running `build` on `myreactapp`.

You can define these task dependencies globally for your workspace in `nx.json` or individually in each project's `project.json` file.

Learn more about:

- [What a task pipeline is all about](/docs/concepts/task-pipeline-configuration)
- [How to configure a task pipeline](/docs/guides/tasks--caching/defining-task-pipeline)

## Reduce repetitive configuration

Learn more about leveraging `targetDefaults` to reduce repetitive configuration in the [dedicated recipe](/docs/guides/tasks--caching/reduce-repetitive-configuration).

## Run root-level tasks

Sometimes, you need tasks that apply to the entire codebase rather than a single project. To still benefit from caching, you can run these tasks through the "Nx pipeline". Define them in the root-level `package.json` or `project.json` as follows:

{% tabs syncKey="project-config-file" %}
{% tabitem label="package.json" %}

```json
// package.json
{
  "name": "myorg",
  "scripts": {
    "docs": "node ./generateDocsSite.js"
  },
  "nx": {}
}
```

> Note the `nx: {}` property on the `package.json`. This is necessary to inform Nx about this root-level project. The property can also be expanded to specify cache inputs and outputs.

If you want Nx to cache the task, but prefer to use npm (or pnpm/yarn) to run the script (i.e. `npm run docs`) you can use the [nx exec](/docs/reference/nx-commands#nx-exec) command:

```json
// package.json
{
  "name": "myorg",
  "scripts": {
    "docs": "nx exec -- node ./generateDocsSite.js"
  },
  "nx": {}
}
```

{% /tabitem %}
{% tabitem label="project.json" %}

```json
// project.json
{
  "name": "myorg",
  ...
  "targets": {
    "docs": {
      "command": "node ./generateDocsSite.js"
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

To invoke the task, use:

```shell
npx nx docs
```

Learn more about root-level tasks on [our dedicated recipe page](/docs/guides/tasks--caching/root-level-scripts).


# Guides

---
<!-- source: https://nx.dev/docs/guides.md -->
## Guides

{% index_page_cards path="guides" /%}

---
<!-- source: https://nx.dev/docs/guides/adopting-nx.md -->
## Adopting Nx

{% index_page_cards path="guides/adopting-nx" /%}

---
<!-- source: https://nx.dev/docs/guides/adopting-nx/adding-to-existing-project.md -->
## Adding Nx to your Existing Project

Nx can be added to any type of project, not just monorepos. A large benefit of Nx is its caching feature for package
scripts. Each project usually has a set of scripts in the `package.json`:

```json
// package.json
{
  ...
  "scripts": {
    "build": "next build",
    "lint": "eslint ./src",
    "test": "node ./run-tests.js"
  }
}
```

You can make these scripts faster by leveraging Nx [caching capabilities](/docs/features/cache-task-results). For example:

- You change some spec files: in that case the `build` task can be cached and doesn't have to re-run.
- You update your docs, changing a couple of markdown files: then there's no need to re-run builds, tests, linting on
  your CI. All you might want to do is trigger the Docusaurus build.

Additionally, Nx also [speeds up your CI ⚡](#fast-ci) with [remote caching](/docs/features/ci-features/remote-cache) and [distributed task execution](/docs/features/ci-features/distribute-task-execution).

## Install Nx on a non-Monorepo project

Run the following command:

```shell
npx nx@latest init
```

Running this command will ask you a few questions about your workspace and then set up Nx for you accordingly. The setup
process detects tools which are used in your workspace and suggests installing Nx plugins to integrate the tools you use
with Nx. Running those tools through Nx will have caching enabled when possible, providing you with a faster alternative
for running those tools. You can start with a few to see how it works and then add more with
the [`nx add`](/docs/reference/nx-commands#nx-add) command later. You can also decide to add them all and get the full experience
right
away because adding plugins will not break your existing workflow.

The first thing you may notice is that Nx updates your `package.json` scripts during the setup process. Nx Plugins setup
Nx commands which run the underlying tool with caching enabled. When a `package.json` script runs a command which can be
run through Nx, Nx will replace that script in the `package.json` scripts with an Nx command that has
caching automatically enabled. Anywhere those `package.json` scripts are used, including your CI, will become faster
when possible. Let's go through an example where the `@nx/next/plugin` and `@nx/eslint/plugin` plugins are added to a
workspace with the
following `package.json`.

```diff
// package.json
{
  "name": "my-workspace",
  ...
  "scripts": {
-     "build": "next build && echo 'Build complete'",
+     "build": "nx next:build && echo 'Build complete'",
-     "lint": "eslint ./src",
+     "lint": "nx eslint:lint",
    "test": "node ./run-tests.js"
  },
+   "nx": {}
}
```

The `@nx/next/plugin` plugin adds a `next:build` target which runs `next build` and sets up caching correctly. In other
words, running `nx next:build` is the same as running `next build` with the added benefit of it being cacheable. Hence,
Nx replaces `next build` in the `package.json` `build` script to add caching to anywhere running `npm run build`.
Similarly, `@nx/eslint/plugin` sets up the `nx eslint:lint` command to run `eslint ./src` with caching enabled.
The `test` script was not recognized by any Nx plugin, so it was left as is. After Nx has been setup,
running `npm run build` or `npm run lint` multiple times, will be instant when possible.

You can also run any npm scripts directly through Nx with `nx build` or `nx lint` which will run the `npm run build`
and `npm run lint` scripts respectively. In the later portion of the setup flow, Nx will ask if you would like some of
those npm scripts to be cacheable. By making those cacheable, running `nx build` rather than `npm run build` will add
another layer of cacheability. However, `nx build` must be run instead of `npm run build` to take advantage of the
cache.

## Inferred tasks

You may have noticed that `@nx/next` provides `dev` and `start` tasks in addition to the `next:build` task. Those tasks
were created by the `@nx/next/plugin` plugin from your existing Next.js configuration. You can see the configuration for
the Nx Plugins in `nx.json`:

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/eslint/plugin",
      "options": {
        "targetName": "eslint:lint"
      }
    },
    {
      "plugin": "@nx/next/plugin",
      "options": {
        "buildTargetName": "next:build",
        "devTargetName": "dev",
        "startTargetName": "start"
      }
    }
  ]
}
```

Each plugin can accept options to customize the projects which they create. You can see more information about
configuring the plugins on the [`@nx/next/plugin`](/docs/technologies/react/next/introduction) and [`@nx/eslint/plugin`](/docs/technologies/eslint/introduction) plugin pages.

To view all available tasks, open the Project Details view with Nx Console or use the terminal to launch the project
details in a browser window.

```shell
nx show project my-workspace --web
```

{% project_details title="Project Details View" %}

```json
{
  "project": {
    "name": "my-workspace",
    "data": {
      "root": ".",
      "targets": {
        "eslint:lint": {
          "cache": true,
          "options": {
            "cwd": ".",
            "command": "eslint ./src"
          },
          "inputs": [
            "default",
            "{workspaceRoot}/.eslintrc",
            "{workspaceRoot}/tools/eslint-rules/**/*",
            {
              "externalDependencies": ["eslint"]
            }
          ],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["eslint"]
          }
        },
        "next:build": {
          "options": {
            "cwd": ".",
            "command": "next build"
          },
          "dependsOn": ["^build"],
          "cache": true,
          "inputs": [
            "default",
            "^default",
            {
              "externalDependencies": ["next"]
            }
          ],
          "outputs": ["{projectRoot}/.next", "{projectRoot}/.next/!(cache)"],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["next"]
          }
        },
        "dev": {
          "options": {
            "cwd": ".",
            "command": "next dev",
            "continuous": true
          },
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["next"]
          }
        },
        "start": {
          "options": {
            "cwd": ".",
            "command": "next start",
            "continuous": true
          },
          "dependsOn": ["build"],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["next"]
          }
        }
      },
      "sourceRoot": ".",
      "name": "my-workspace",
      "projectType": "library",
      "implicitDependencies": [],
      "tags": []
    }
  },
  "sourceMap": {
    "root": ["package.json", "nx/core/package-json-workspaces"],
    "targets": ["package.json", "nx/core/package-json-workspaces"],
    "targets.eslint:lint": [".eslintrc.json", "@nx/eslint/plugin"],
    "targets.eslint:lint.command": [".eslintrc.json", "@nx/eslint/plugin"],
    "targets.eslint:lint.cache": [".eslintrc.json", "@nx/eslint/plugin"],
    "targets.eslint:lint.options": [".eslintrc.json", "@nx/eslint/plugin"],
    "targets.eslint:lint.inputs": [".eslintrc.json", "@nx/eslint/plugin"],
    "targets.eslint:lint.options.cwd": [".eslintrc.json", "@nx/eslint/plugin"],
    "targets.next:build": ["next.config.js", "@nx/next/plugin"],
    "targets.next:build.command": ["next.config.js", "@nx/next/plugin"],
    "targets.next:build.options": ["next.config.js", "@nx/next/plugin"],
    "targets.next:build.dependsOn": ["next.config.js", "@nx/next/plugin"],
    "targets.next:build.cache": ["next.config.js", "@nx/next/plugin"],
    "targets.next:build.inputs": ["next.config.js", "@nx/next/plugin"],
    "targets.next:build.outputs": ["next.config.js", "@nx/next/plugin"],
    "targets.next:build.options.cwd": ["next.config.js", "@nx/next/plugin"],
    "targets.dev": ["next.config.js", "@nx/next/plugin"],
    "targets.dev.command": ["next.config.js", "@nx/next/plugin"],
    "targets.dev.options": ["next.config.js", "@nx/next/plugin"],
    "targets.dev.options.cwd": ["next.config.js", "@nx/next/plugin"],
    "targets.start": ["next.config.js", "@nx/next/plugin"],
    "targets.start.command": ["next.config.js", "@nx/next/plugin"],
    "targets.start.options": ["next.config.js", "@nx/next/plugin"],
    "targets.start.dependsOn": ["next.config.js", "@nx/next/plugin"],
    "targets.start.options.cwd": ["next.config.js", "@nx/next/plugin"],
    "sourceRoot": ["package.json", "nx/core/package-json-workspaces"],
    "name": ["package.json", "nx/core/package-json-workspaces"],
    "projectType": ["package.json", "nx/core/package-json-workspaces"],
    "targets.nx-release-publish": [
      "package.json",
      "nx/core/package-json-workspaces"
    ],
    "targets.nx-release-publish.dependsOn": [
      "package.json",
      "nx/core/package-json-workspaces"
    ],
    "targets.nx-release-publish.executor": [
      "package.json",
      "nx/core/package-json-workspaces"
    ],
    "targets.nx-release-publish.options": [
      "package.json",
      "nx/core/package-json-workspaces"
    ]
  }
}
```

{% /project_details %}

The project detail view lists all available tasks, the configuration values for those tasks and where those
configuration values are being set.

## Configure an existing script to run with Nx

If you want to run one of your existing scripts with Nx, you need to tell Nx about it.

1. Preface the script with `nx exec -- ` to have `npm run test` invoke the command with Nx.
2. Define caching settings.

The `nx exec` command allows you to keep using `npm test` or `npm run test` (or other package manager's alternatives) as
you're accustomed to. But still get the benefits of making those operations cacheable. Configuring the `test` script
from the example above to run with Nx would look something like this:

```json
// package.json
{
  "name": "my-workspace",
  ...
  "scripts": {
    "build": "nx next:build",
    "lint": "nx eslint:lint",
    "test": "nx exec -- node ./run-tests.js"
  },
  ...
  "nx": {
    "targets": {
      "test": {
        "cache": "true",
        "inputs": [
          "default",
          "^default"
        ],
        "outputs": []
      }
    }
  }
}
```

Now if you run `npm run test` or `nx test` twice, the results will be retrieved from the cache. The `inputs` used in
this example are as cautious as possible, so you can significantly improve the value of the cache
by [customizing Nx Inputs](/docs/guides/tasks--caching/configure-inputs) for each task.

## Fast CI ⚡

This tutorial walked you through how Nx can improve the local development experience, but the biggest difference Nx makes is in CI. As repositories get bigger, making sure that the CI is fast, reliable and maintainable can get very challenging. Nx provides a solution.

- Nx reduces wasted time in CI with the [`affected` command](/docs/features/ci-features/affected).
- Nx Replay's [remote caching](/docs/features/ci-features/remote-cache) will reuse task artifacts from different CI executions making sure you will never run the same computation twice.
- Nx Agents [efficiently distribute tasks across machines](/docs/concepts/ci-concepts/parallelization-distribution) ensuring constant CI time regardless of the repository size. The right number of machines is allocated for each PR to ensure good performance without wasting compute.
- Nx Atomizer [automatically splits](/docs/features/ci-features/split-e2e-tasks) large e2e tests to distribute them across machines. Nx can also automatically [identify and rerun flaky e2e tests](/docs/features/ci-features/flaky-tasks).

### Connect to Nx Cloud

Nx Cloud is a companion app for your CI system that provides remote caching, task distribution, e2e tests deflaking, better DX and more.

Now that we're working on the CI pipeline, it is important for your changes to be pushed to a GitHub repository.

1. Commit your existing changes with `git add . && git commit -am "updates"`
2. [Create a new GitHub repository](https://github.com/new)
3. Follow GitHub instructions to push your existing code to the repository

Now connect your repository to Nx Cloud with the following command:

```shell
npx nx@latest connect
```

A browser window will open to register your repository in your [Nx Cloud](https://cloud.nx.app) account. The link is also printed to the terminal if the windows does not open, or you closed it before finishing the steps. The app will guide you to create a PR to enable Nx Cloud on your repository.

![](../../../../assets/guides/adopting-nx/nx-cloud-github-connect.avif)

Once the PR is created, merge it into your main branch.

![](../../../../assets/guides/adopting-nx/github-cloud-pr-merged.avif)

And make sure you pull the latest changes locally:

```shell
git pull
```

You should now have an `nxCloudId` property specified in the `nx.json` file.

### Create a CI workflow

Use the following command to generate a CI workflow file.

```shell
npx nx generate ci-workflow --ci=github
```

This generator creates a `.github/workflows/ci.yml` file that contains a CI pipeline that will run the `lint`, `test`, `build` and `e2e` tasks for projects that are affected by any given PR. Since we are using Nx Cloud, the pipeline will also distribute tasks across multiple machines to ensure fast and reliable CI runs.

The key lines in the CI pipeline are:

```yml {% meta="{10-14,21-22}" %}
// .github/workflows/ci.yml
name: CI
# ...
jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          filter: tree:0

      # This enables task distribution via Nx Cloud
      # Run this command as early as possible, before dependencies are installed
      # Learn more at https://nx.dev/ci/reference/nx-cloud-cli#npx-nxcloud-startcirun
      # Connect your workspace by running "nx connect" and uncomment this
      - run: npx nx start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"
      - uses: actions/setup-node@v3
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - uses: nrwl/nx-set-shas@v4
      # Nx Affected runs only tasks affected by the changes in this PR/commit. Learn more: https://nx.dev/ci/features/affected
      - run: npx nx affected -t lint test build
```

### Open a pull request

Commit the changes and open a new PR on GitHub.

```shell
git add .
git commit -m 'add CI workflow file'
git push origin add-workflow
```

When you view the PR on GitHub, you will see a comment from Nx Cloud that reports on the status of the CI run.

![Nx Cloud report](../../../../assets/guides/adopting-nx/github-pr-cloud-report.avif)

The `See all runs` link goes to a page with the progress and results of tasks that were run in the CI pipeline.

![Run details](../../../../assets/guides/adopting-nx/nx-cloud-run-details.avif)

For more information about how Nx can improve your CI pipeline, check out our [CI setup guides](/docs/guides/nx-cloud/setup-ci).

## Learn more

{% cardgrid %}

{% linkcard title="Customizing Inputs and Named Inputs" description="Learn more about how to fine-tune caching with custom inputs" href="/docs/guides/tasks--caching/configure-inputs" /%}

{% linkcard title="Cache Task Results" description="Learn more about how caching works" href="/docs/features/cache-task-results" /%}

{% linkcard title="Adding Nx to NPM/Yarn/PNPM Workspace" description="Learn more about how to add Nx to an existing monorepo" href="/docs/guides/adopting-nx/adding-to-monorepo" /%}

{% /cardgrid %}

---
<!-- source: https://nx.dev/docs/guides/adopting-nx/adding-to-monorepo.md -->
## Adding Nx to NPM/Yarn/PNPM Workspace

{% aside type="note" title="Migrating from Lerna?" %}
Interested in migrating from [Lerna](https://github.com/lerna/lerna) in particular? In case you missed it, Lerna v6 is
powering Nx underneath. As a result, Lerna gets all the modern features such as caching and task pipelines. Read more
on [https://lerna.js.org/upgrade](https://lerna.js.org/upgrade).
{% /aside %}

Nx has first-class support for [monorepos](/docs/getting-started/tutorials/crafting-your-workspace). If you have
an existing NPM/Yarn or PNPM-based monorepo setup, you can easily add Nx to get

- fast [task scheduling](/docs/features/run-tasks)
- high-performance task [caching](/docs/features/cache-task-results)
- [fast CI ⚡](#fast-ci) with [remote caching](/docs/features/ci-features/remote-cache) and [distributed task execution](/docs/features/ci-features/distribute-task-execution)

This is a low-impact operation because all that needs to be done is to install the `nx` package at the root level and
add an `nx.json` for configuring caching and task pipelines.

{% course_video src="https://youtu.be/3hW53b1IJ84" courseTitle="From PNPM Workspaces to Distributed CI" courseUrl="https://nx.dev/courses/pnpm-nx-next/lessons-01-nx-init" /%}

## Installing Nx

Run the following command to automatically set up Nx:

```shell
npx nx@latest init
```

Running this command will ask you a few questions about your workspace and then set up Nx for you accordingly. The setup
process detects tools which are used in your workspace and suggests installing Nx plugins to integrate the tools you use
with Nx. Running those tools through Nx will have caching enabled when possible, providing you with a faster alternative
for running those tools. You can start with a few to see how it works and then add more with
the [`nx add`](/docs/reference/nx-commands#nx-add) command later. You can also decide to add them all and get the full experience
right
away because adding plugins will not break your existing workflow.

The first thing you may notice is that Nx updates your `package.json` scripts during the setup process. Nx Plugins setup
Nx commands which run the underlying tool with caching enabled. When a `package.json` script runs a command which can be
run through Nx, Nx will replace that script in the `package.json` scripts with an Nx command that has
caching automatically enabled. Anywhere those `package.json` scripts are used, including your CI, will become faster
when possible. Let's go through an example where the `@nx/next/plugin` and `@nx/eslint/plugin` plugins are added to a
workspace with the
following `package.json`.

```diff
// package.json
{
  "name": "my-workspace",
  ...
  "scripts": {
-     "build": "next build && echo 'Build complete'",
+     "build": "nx next:build && echo 'Build complete'",
-     "lint": "eslint ./src",
+     "lint": "nx eslint:lint",
    "test": "node ./run-tests.js"
  },
  ...
}
```

The `@nx/next/plugin` plugin adds a `next:build` target which runs `next build` and sets up caching correctly. In other
words, running `nx next:build` is the same as running `next build` with the added benefit of it being cacheable. Hence,
Nx replaces `next build` in the `package.json` `build` script to add caching to anywhere running `npm run build`.
Similarly, `@nx/eslint/plugin` sets up the `nx eslint:lint` command to run `eslint ./src` with caching enabled.
The `test` script was not recognized by any Nx plugin, so it was left as is. After Nx has been setup,
running `npm run build` or `npm run lint` multiple times, will be instant when possible.

You can also run any npm scripts directly through Nx with `nx build` or `nx lint` which will run the `npm run build`
and `npm run lint` scripts respectively. In the later portion of the setup flow, Nx will ask if you would like some of
those npm scripts to be cacheable. By making those cacheable, running `nx build` rather than `npm run build` will add
another layer of cacheability. However, `nx build` must be run instead of `npm run build` to take advantage of the
cache.

## Inferred tasks

You may have noticed that `@nx/next` provides `dev` and `start` tasks in addition to the `next:build` task. Those tasks
were created by the `@nx/next/plugin` plugin from your existing Next.js configuration. You can see the configuration for
the Nx Plugins in `nx.json`:

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/eslint/plugin",
      "options": {
        "targetName": "eslint:lint"
      }
    },
    {
      "plugin": "@nx/next/plugin",
      "options": {
        "buildTargetName": "next:build",
        "devTargetName": "dev",
        "startTargetName": "start"
      }
    }
  ]
}
```

Each plugin can accept options to customize the projects which they create. You can see more information about
configuring the plugins on the [`@nx/next/plugin`](/docs/technologies/react/next/introduction) and [`@nx/eslint/plugin`](/docs/technologies/eslint/introduction) plugin pages.

To view all available tasks, open the Project Details view with Nx Console or use the terminal to launch the project
details in a browser window.

```shell
nx show project my-workspace --web
```

{% project_details title="Project Details View" %}

```json
{
  "project": {
    "name": "my-workspace",
    "data": {
      "root": ".",
      "targets": {
        "eslint:lint": {
          "cache": true,
          "options": {
            "cwd": ".",
            "command": "eslint ./src"
          },
          "inputs": [
            "default",
            "{workspaceRoot}/.eslintrc",
            "{workspaceRoot}/tools/eslint-rules/**/*",
            {
              "externalDependencies": ["eslint"]
            }
          ],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["eslint"]
          }
        },
        "next:build": {
          "options": {
            "cwd": ".",
            "command": "next build"
          },
          "dependsOn": ["^build"],
          "cache": true,
          "inputs": [
            "default",
            "^default",
            {
              "externalDependencies": ["next"]
            }
          ],
          "outputs": ["{projectRoot}/.next", "{projectRoot}/.next/!(cache)"],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["next"]
          }
        },
        "dev": {
          "options": {
            "cwd": ".",
            "command": "next dev",
            "continuous": true
          },
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["next"]
          }
        },
        "start": {
          "options": {
            "cwd": ".",
            "command": "next start",
            "continuous": true
          },
          "dependsOn": ["build"],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["next"]
          }
        }
      },
      "sourceRoot": ".",
      "name": "my-workspace",
      "projectType": "library",
      "implicitDependencies": [],
      "tags": []
    }
  },
  "sourceMap": {
    "root": ["package.json", "nx/core/package-json-workspaces"],
    "targets": ["package.json", "nx/core/package-json-workspaces"],
    "targets.eslint:lint": [".eslintrc.json", "@nx/eslint/plugin"],
    "targets.eslint:lint.command": [".eslintrc.json", "@nx/eslint/plugin"],
    "targets.eslint:lint.cache": [".eslintrc.json", "@nx/eslint/plugin"],
    "targets.eslint:lint.options": [".eslintrc.json", "@nx/eslint/plugin"],
    "targets.eslint:lint.inputs": [".eslintrc.json", "@nx/eslint/plugin"],
    "targets.eslint:lint.options.cwd": [".eslintrc.json", "@nx/eslint/plugin"],
    "targets.next:build": ["next.config.js", "@nx/next/plugin"],
    "targets.next:build.command": ["next.config.js", "@nx/next/plugin"],
    "targets.next:build.options": ["next.config.js", "@nx/next/plugin"],
    "targets.next:build.dependsOn": ["next.config.js", "@nx/next/plugin"],
    "targets.next:build.cache": ["next.config.js", "@nx/next/plugin"],
    "targets.next:build.inputs": ["next.config.js", "@nx/next/plugin"],
    "targets.next:build.outputs": ["next.config.js", "@nx/next/plugin"],
    "targets.next:build.options.cwd": ["next.config.js", "@nx/next/plugin"],
    "targets.dev": ["next.config.js", "@nx/next/plugin"],
    "targets.dev.command": ["next.config.js", "@nx/next/plugin"],
    "targets.dev.options": ["next.config.js", "@nx/next/plugin"],
    "targets.dev.options.cwd": ["next.config.js", "@nx/next/plugin"],
    "targets.start": ["next.config.js", "@nx/next/plugin"],
    "targets.start.command": ["next.config.js", "@nx/next/plugin"],
    "targets.start.options": ["next.config.js", "@nx/next/plugin"],
    "targets.start.dependsOn": ["next.config.js", "@nx/next/plugin"],
    "targets.start.options.cwd": ["next.config.js", "@nx/next/plugin"],
    "sourceRoot": ["package.json", "nx/core/package-json-workspaces"],
    "name": ["package.json", "nx/core/package-json-workspaces"],
    "projectType": ["package.json", "nx/core/package-json-workspaces"],
    "targets.nx-release-publish": [
      "package.json",
      "nx/core/package-json-workspaces"
    ],
    "targets.nx-release-publish.dependsOn": [
      "package.json",
      "nx/core/package-json-workspaces"
    ],
    "targets.nx-release-publish.executor": [
      "package.json",
      "nx/core/package-json-workspaces"
    ],
    "targets.nx-release-publish.options": [
      "package.json",
      "nx/core/package-json-workspaces"
    ]
  }
}
```

{% /project_details %}

The project detail view lists all available tasks, the configuration values for those tasks and where those
configuration values are being set.

## Configure an existing script to run with Nx

If you want to run one of your existing scripts with Nx, you need to tell Nx about it.

1. Preface the script with `nx exec -- ` to have `npm run test` invoke the command with Nx.
2. Define caching settings.

The `nx exec` command allows you to keep using `npm test` or `npm run test` (or other package manager's alternatives) as
you're accustomed to. But still get the benefits of making those operations cacheable. Configuring the `test` script
from the example above to run with Nx would look something like this:

```json
// package.json
{
  "name": "my-workspace",
  ...
  "scripts": {
    "build": "nx next:build",
    "lint": "nx eslint:lint",
    "test": "nx exec -- node ./run-tests.js"
  },
  ...
  "nx": {
    "targets": {
      "test": {
        "cache": "true",
        "inputs": [
          "default",
          "^default"
        ],
        "outputs": []
      }
    }
  }
}
```

Now if you run `npm run test` or `nx test` twice, the results will be retrieved from the cache. The `inputs` used in
this example are as cautious as possible, so you can significantly improve the value of the cache
by [customizing Nx Inputs](/docs/guides/tasks--caching/configure-inputs) for each task.

## Incrementally adopting Nx

All the features of Nx can be enabled independently of each other. Hence, Nx can easily be adopted incrementally by
initially using Nx just for a subset of your scripts and then gradually adding more.

For example, use Nx to run your builds:

```shell
npx nx run-many -t build
```

But instead keep using NPM/Yarn/PNPM workspace commands for your tests and other scripts. Here's an example of using
PNPM commands to run tests across packages

```shell
pnpm run -r test
```

This allows for incrementally adopting Nx in your existing workspace.

## Fast CI ⚡

This tutorial walked you through how Nx can improve the local development experience, but the biggest difference Nx makes is in CI. As repositories get bigger, making sure that the CI is fast, reliable and maintainable can get very challenging. Nx provides a solution.

- Nx reduces wasted time in CI with the [`affected` command](/docs/features/ci-features/affected).
- Nx Replay's [remote caching](/docs/features/ci-features/remote-cache) will reuse task artifacts from different CI executions making sure you will never run the same computation twice.
- Nx Agents [efficiently distribute tasks across machines](/docs/concepts/ci-concepts/parallelization-distribution) ensuring constant CI time regardless of the repository size. The right number of machines is allocated for each PR to ensure good performance without wasting compute.
- Nx Atomizer [automatically splits](/docs/features/ci-features/split-e2e-tasks) large e2e tests to distribute them across machines. Nx can also automatically [identify and rerun flaky e2e tests](/docs/features/ci-features/flaky-tasks).

### Connect to Nx Cloud

Nx Cloud is a companion app for your CI system that provides remote caching, task distribution, e2e tests deflaking, better DX and more.

Now that we're working on the CI pipeline, it is important for your changes to be pushed to a GitHub repository.

1. Commit your existing changes with `git add . && git commit -am "updates"`
2. [Create a new GitHub repository](https://github.com/new)
3. Follow GitHub instructions to push your existing code to the repository

Now connect your repository to Nx Cloud with the following command:

```shell
npx nx@latest connect
```

A browser window will open to register your repository in your [Nx Cloud](https://cloud.nx.app) account. The link is also printed to the terminal if the windows does not open, or you closed it before finishing the steps. The app will guide you to create a PR to enable Nx Cloud on your repository.

![](../../../../assets/guides/adopting-nx/nx-cloud-github-connect.avif)

Once the PR is created, merge it into your main branch.

![](../../../../assets/guides/adopting-nx/github-cloud-pr-merged.avif)

And make sure you pull the latest changes locally:

```shell
git pull
```

You should now have an `nxCloudId` property specified in the `nx.json` file.

### Create a CI workflow

Use the following command to generate a CI workflow file.

```shell
npx nx generate ci-workflow --ci=github
```

This generator creates a `.github/workflows/ci.yml` file that contains a CI pipeline that will run the `lint`, `test`, `build` and `e2e` tasks for projects that are affected by any given PR. Since we are using Nx Cloud, the pipeline will also distribute tasks across multiple machines to ensure fast and reliable CI runs.

The key lines in the CI pipeline are:

```yml {% meta="{11-15,22-23}" %}
// .github/workflows/ci.yml"
name: CI
# ...
jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          filter: tree:0

      # This enables task distribution via Nx Cloud
      # Run this command as early as possible, before dependencies are installed
      # Learn more at https://nx.dev/ci/reference/nx-cloud-cli#npx-nxcloud-startcirun
      # Connect your workspace by running "nx connect" and uncomment this
      - run: npx nx start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"
      - uses: actions/setup-node@v3
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - uses: nrwl/nx-set-shas@v4
      # Nx Affected runs only tasks affected by the changes in this PR/commit. Learn more: https://nx.dev/ci/features/affected
      - run: npx nx affected -t lint test build
```

### Open a pull request

Commit the changes and open a new PR on GitHub.

```shell
git add .
git commit -m 'add CI workflow file'
git push origin add-workflow
```

When you view the PR on GitHub, you will see a comment from Nx Cloud that reports on the status of the CI run.

![Nx Cloud report](../../../../assets/guides/adopting-nx/github-pr-cloud-report.avif)

The `See all runs` link goes to a page with the progress and results of tasks that were run in the CI pipeline.

![Run details](../../../../assets/guides/adopting-nx/nx-cloud-run-details.avif)

For more information about how Nx can improve your CI pipeline, check out our [detailed tutorial for you CI provider](/docs/guides/nx-cloud/setup-ci).

## Learn more

{% cardgrid %}

{% linkcard title="Cache Task Results" description="Learn more about how caching works" href="/docs/features/cache-task-results" /%}

{% linkcard title="Task Pipeline Configuration" description="Learn more about how to setup task dependencies" href="/docs/concepts/task-pipeline-configuration" /%}

{% linkcard title="Nx Ignore" description="Learn about how to ignore certain projects using .nxignore" href="/docs/reference/nxignore" /%}

{% linkcard title="Migrating from Turborepo to Nx" description="Read about Migrating from Turborepo to Nx" href="/docs/guides/adopting-nx/from-turborepo" /%}

{% /cardgrid %}

---
<!-- source: https://nx.dev/docs/guides/adopting-nx/from-turborepo.md -->
## Migrating from Turborepo to Nx

{% aside type="note" title="Looking for a comparison?" %}
For a data-driven comparison of Nx and Turborepo covering setup complexity, CI performance, and advanced capabilities, see [Nx vs Turborepo](/docs/guides/adopting-nx/nx-vs-turborepo).
{% /aside %}

Nx is a superset of Turborepo, so migrating requires minimal effort. The diff is tiny: an `nx.json` file (equivalent to `turbo.json`), the `nx` package added to `package.json`, and a `.gitignore` entry for the Nx cache. No changes to your existing projects or scripts are needed.

## Easy automated migration example

1. Let's create a new Turborepo workspace using the recommended `create-turbo` command:

```shell
npx create-turbo@latest
```

2. Once that is finished, literally all we need to do make it a valid Nx workspace is run `nx init`:

```shell
npx nx@latest init
```

That's it! As you can see, the diff is tiny:

```diff
.gitignore        | 3 +++ # Ignore the Nx cache
package.json      | 1 + # Add the "nx" package
package-lock.json |
nx.json           | # Equivalent to turbo.json
```

- An `nx.json` file that is equivalent to the `turbo.json` file was added
- The `package.json` file was updated to add the `nx` dev dependency (and the package-lock.json was updated accordingly)
- The .gitignore entry for the Nx cache was added automatically

It's important to remember that Nx is a superset of Turborepo, it can do everything Turborepo can do and much more, so there is absolutely no special configuration needed for Nx, it just works on the Turborepo workspace.

### Example: Basic configuration comparison

To help with understanding the new `nx.json` file, let's compare it to the `turbo.json` file:

```json
{
  "$schema": "https://turbo.build/schema.json",
  // Nx will automatically use an appropriate terminal output style for the tasks you run
  "ui": "tui",
  "tasks": {
    "build": {
      // This syntax of build depending on the build of its dependencies using ^ is the same
      // in Nx
      "dependsOn": ["^build"],
      // Inputs and outputs are in Turborepo are relative to a particular package, whereas in Nx they are consistently from the workspace root and it therefore has {projectRoot} and {projectName} helpers
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "lint": {
      // Turborepo tasks are assumed to be cacheable by default, so there is no recognizable configuration here. In Nx, the "cache" value is clearly set to true.
      "dependsOn": ["^lint"]
    },
    "check-types": {
      "dependsOn": ["^check-types"]
    },
    "dev": {
      // Nx uses "continuous" instead of "persistent"
      "persistent": true
    }
  }
}
```

After running `nx init`, you'll automatically have an equivalent `nx.json`:

```json
{
  "$schema": "./node_modules/nx/schemas/nx-schema.json",
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["{projectRoot}/**/*", "{projectRoot}/.env*"],
      "outputs": ["{projectRoot}/.next/**", "!{projectRoot}/.next/cache/**"],
      "cache": true
    },
    "lint": {
      "dependsOn": ["^lint"],
      "cache": true
    },
    "check-types": {
      "dependsOn": ["^check-types"],
      "cache": true
    },
    "dev": {
      "continuous": true
    }
  }
}
```

## Configuration migration guide

Most settings in the old `turbo.json` file can be converted directly into `nx.json` equivalents. Here's how to map each configuration property:

### Global configuration

| Turborepo Property     | Nx Equivalent                                                                                                                                                                                                                  |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `cacheDir`             | Set in [`cacheDirectory`](/docs/reference/nx-json#task-options)                                                                                                                                                                |
| `daemon`               | Use [`NX_DAEMON=false` or set `useDaemonProcess: false`](/docs/concepts/nx-daemon#turning-it-off) in `nx.json`                                                                                                                 |
| `envMode`              | Nx core does not block any environment variables. See [React](/docs/technologies/react/guides/use-environment-variables-in-react) and [Angular](/docs/technologies/angular/guides/use-environment-variables-in-angular) guides |
| `globalDependencies`   | Add to the [`sharedGlobals` `namedInput`](/docs/guides/tasks--caching/configure-inputs)                                                                                                                                        |
| `globalEnv`            | Add to the [`sharedGlobals` `namedInput`](/docs/guides/tasks--caching/configure-inputs) as an [`env` input](/docs/reference/inputs#environment-variables)                                                                      |
| `globalPassThroughEnv` | N/A. See [Defining Environment Variables](/docs/guides/tips-n-tricks/define-environment-variables)                                                                                                                             |
| `remoteCache`          | See [Nx Replay](/docs/features/ci-features/remote-cache)                                                                                                                                                                       |
| `ui`                   | Nx will intelligently pick the most appropriate terminal output style, but it can be overridden with [`--output-style`](/docs/reference/nx-commands#outputstyle)                                                               |

### Task configuration

| Turborepo Property | Nx Equivalent                                                                                                                                     |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `extends`          | N/A. Projects always extend `targetDefaults` from `nx.json`                                                                                       |
| `dependsOn`        | [Same syntax](/docs/reference/project-configuration#dependson)                                                                                    |
| `env`              | Define [env `inputs`](/docs/reference/inputs#environment-variables)                                                                               |
| `passThroughEnv`   | N/A. See [Defining Environment Variables](/docs/guides/tips-n-tricks/define-environment-variables)                                                |
| `outputs`          | [Similar syntax](/docs/reference/project-configuration#outputs)                                                                                   |
| `cache`            | [Similar syntax](/docs/reference/project-configuration#cache)                                                                                     |
| `inputs`           | [Similar syntax](/docs/reference/inputs#source-files)                                                                                             |
| `outputLogs`       | Use [`--output-style`](/docs/reference/nx-commands#outputstyle)                                                                                   |
| `persistent`       | Use [`continuous`](/docs/guides/tasks--caching/defining-task-pipeline#continuous-task-dependencies)                                               |
| `interactive`      | N/A. Tasks marked [`continuous`](/docs/guides/tasks--caching/defining-task-pipeline#continuous-task-dependencies) can accept stdin automatically. |

## Command equivalents

Here's how Turborepo commands map to Nx:

| Turborepo Command            | Nx Equivalent                                                                                                                                                                |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `turbo run test lint build`  | [`nx run-many -t test lint build`](/docs/reference/nx-commands#nx-run-many)                                                                                                  |
| `turbo run build --affected` | [`nx affected -t build`](/docs/reference/nx-commands#nx-affected)                                                                                                            |
| `turbo devtools`             | [`nx graph`](/docs/reference/nx-commands#nx-graph) for full interactive experience, also available in [Nx Console](/docs/getting-started/editor-setup)                       |
| `--cache-dir`                | Set in [`nx.json` under `cacheDirectory`](/docs/reference/nx-json#task-options)                                                                                              |
| `--concurrency`              | [`--parallel`](/docs/reference/nx-commands#parallel)                                                                                                                         |
| `--continue`                 | [Use `--nx-bail`](/docs/reference/nx-commands#nxbail) with the inverse value                                                                                                 |
| `--cpuprofile`               | Use [`NX_PROFILE=profile.json`](/docs/troubleshooting/performance-profiling)                                                                                                 |
| `--cwd`                      | Available in [`run-commands` executor](/docs/reference/nx/executors#run-commands#cwd)                                                                                        |
| `--daemon`                   | Use [`NX_DAEMON=false` or set `useDaemonProcess: false`](/docs/concepts/nx-daemon#turning-it-off)                                                                            |
| `--dry-run`                  | Use [`nx show target <project>:<target> --inputs --outputs`](/docs/reference/nx-commands#nx-show-target) to preview inputs and outputs (available since 22.6.0+)             |
| `--env-mode`                 | See [React](/docs/technologies/react/guides/use-environment-variables-in-react) and [Angular](/docs/technologies/angular/guides/use-environment-variables-in-angular) guides |
| `--filter`                   | Use lots of advanced project matcher syntax like [`-p admin-*` or `-p tag:api-*`](/docs/reference/nx-commands#nx-run-many)                                                   |
| `--force`                    | [`nx reset`](/docs/reference/nx-commands#nx-reset) and then run the command again                                                                                            |
| `--framework-inference`      | N/A. [Nx plugins infer tasks automatically as a first class feature](/docs/concepts/inferred-tasks)                                                                          |
| `--global-deps`              | Use the [`sharedGlobals` `namedInput`](/docs/guides/tasks--caching/configure-inputs). Nx is far more flexible with composable [`namedInputs`](/docs/reference/inputs)        |
| `--graph`                    | [Similar syntax](/docs/reference/nx-commands#graph) or [`nx graph`](/docs/reference/nx-commands#nx-graph) for full interactive experience                                    |
| `--heap`                     | N/A. Use [`--verbose`](/docs/reference/nx-commands#verbose)                                                                                                                  |
| `--ignore`                   | Use [`.nxignore`](/docs/reference/nxignore) or `.gitignore`                                                                                                                  |
| `--log-order`                | Use [`--output-style`](/docs/reference/nx-commands#outputstyle)                                                                                                              |
| `--no-cache`                 | Use [`--skip-nx-cache`](/docs/reference/nx-commands#skipnxcache)                                                                                                             |
| `--output-logs`              | Use [`--output-style`](/docs/reference/nx-commands#outputstyle)                                                                                                              |
| `--only`                     | N/A                                                                                                                                                                          |
| `--parallel`                 | N/A                                                                                                                                                                          |
| `--preflight`                | N/A                                                                                                                                                                          |
| `--summarize`                | N/A                                                                                                                                                                          |
| `--token`                    | Set [Nx Cloud CI Access Token](/docs/guides/nx-cloud/access-tokens#setting-ci-access-tokens)                                                                                 |
| `--team`                     | See `--token` for Nx Cloud workspace selection                                                                                                                               |
| `--trace`                    | N/A. Use [`--verbose`](/docs/reference/nx-commands#verbose)                                                                                                                  |
| `--verbosity`                | Use [`--verbose`](/docs/reference/nx-commands#verbose)                                                                                                                       |
| `turbo gen`                  | [Use `nx generate`](/docs/features/generate-code)                                                                                                                            |
| `turbo login`                | `nx login` - [Create an Nx Cloud account](/docs/reference/nx-commands#nx-login)                                                                                              |
| `turbo link`                 | `nx connect` - [Connect a workspace to an Nx Cloud account](/docs/reference/nx-commands#nx-connect)                                                                          |

For a complete list of Nx commands and options, see the [Nx CLI documentation](/docs/reference/nx-commands).

---
<!-- source: https://nx.dev/docs/guides/adopting-nx/import-project.md -->
## Import an Existing Project into an Nx Workspace

{% youtube src="https://youtu.be/hnbwoV2-620" title="Importing an existing project into your monorepo" /%}

Nx can help with the process of moving an existing project from another repository into an Nx workspace. In order to communicate clearly about this process, we'll call the repository we're moving the project out of the "source repository" and the repository we're moving the project into the "destination repository". Here's an example of what those repositories might look like.

**Source Repository**

{% filetree %}

- inventory-app/
  - ... (other files)
  - public/
    - ... (public files)
  - src/
    - assets/
    - App.css
    - App.tsx
    - index.css
    - main.tsx
  - .eslintrc.cjs
  - index.html
  - package.json
  - README.md
  - tsconfig.json
  - tsconfig.node.json
  - vite.config.ts

{% /filetree %}
**Destination Repository**

{% filetree %}

- myorg/
  - ... (other files)
  - packages/
    - ... (shared packages)
  - apps/
    - account/
      - ... (account app files)
    - cart/
      - ... (cart app files)
    - users/
      - ... (users app files)
  - .eslintrc.json
  - .gitignore
  - nx.json
  - package.json
  - README.md
  - tsconfig.base.json

{% /filetree %}

In this example, the source repository contains a single application while the destination repository is already a monorepo. You can also import a project from a sub-directory of the source repository (if the source repository is a monorepo, for instance). The `nx import` command can be run with no arguments and you will be prompted to for the required arguments:

```shell
nx import
```

Make sure to run `nx import` from within the **destination repository**.

You can also directly specify arguments from the terminal, like one of these commands:

```shell
nx import [sourceRepository] [destinationDirectory]
nx import ../inventory-app apps/inventory
nx import https://github.com/myorg/inventory-app.git apps/inventory
```

{% aside type="tip" title="Source Repository Local or Remote" %}
The sourceRepository argument for `nx import` can be either a local file path to the source git repository on your local machine or a git URL to the hosted git repository.
{% /aside %}

The `nx import` command will:

- Maintain the git history from the source repository
- Suggest adding plugins to the destination repository based on the newly added project code

Every code base is different, so you will still need to manually:

- Manage any dependency conflicts between the two code bases
- Migrate over code outside the source project's root folder that the source project depends on

## Manage dependencies

If both repositories are managed with npm workspaces, the imported project will have all its required dependencies defined in its `package.json` file that is moved over. You'll need to make sure that the destination repository includes the `destinationDirectory` in the `workspaces` defined in the root `package.json`.

If the destination repository does not use npm workspaces, it will ease the import process to temporarily enable it. With npm workspaces enabled, you can easily import a self-contained project and gain the benefits of code sharing, atomic commits and shared infrastructure. Once the import process is complete, you can make a follow-up PR that merges the dependencies into the root `package.json` and disables npm workspaces again.

## Migrate external code and configuration

Few projects are completely isolated from the rest of the repository where they are located. After `nx import` has run, here are a few types of external code references that you should account for:

- Project configuration files that extend root configuration files
- Scripts outside the project folder that are required by the project
- Local project dependencies that are not present or have a different name in the destination repository

{% aside type="note" title="Importing Multiple Projects" %}
If multiple projects need to be imported into the destination repository, try to import as many of the projects together as possible. If projects need to be imported with separate `nx import` commands, start with the leaf projects in the dependency graph (the projects without any dependencies) and then work your way up to the top level applications. This way every project that is imported into the destination repository will have its required dependencies available.
{% /aside %}

---
<!-- source: https://nx.dev/docs/guides/adopting-nx/manual.md -->
## Manual Migration of Existing Code Bases

The easiest way to start using Nx is to run the `nx init` command.

```shell
npx nx@latest init
```

If you don't want to run the script, walk you through doing everything the script does manually.

## Install `nx` as a `devDependency`

We'll start by installing the `nx` package:

{% tabs syncKey="install-type" %}
{% tabitem label="npm" %}

```shell
npm add -D nx@latest
```

{% /tabitem %}
{% tabitem label="yarn" %}

```shell
yarn add -D nx@latest
```

{% /tabitem %}
{% tabitem label="pnpm" %}

```shell
pnpm add -D nx@latest
```

{% /tabitem %}
{% tabitem label="bun" %}

```shell
bun add -D nx@latest
```

{% /tabitem %}
{% /tabs %}

## Create a basic `nx.json` file

Next, we'll create a blank `nx.json` configuration file for Nx:

```json
// nx.json
{}
```

## Add `.nx` directories to `.gitignore`

Next, we'll add the Nx default task cache directory and the project graph cache directory to the list of files to be ignored by Git. Update the `.gitignore` file adding the `.nx/cache` and `.nx/workspace-data` entry:

```text
// .gitignore
...
.nx/cache
.nx/workspace-data
```

## Set up caching for a task

Now, let's set up caching for a script in your `package.json` file. Let's say you have a `build` script that looks like this:

```json
// package.json
{
  "scripts": {
    "build": "tsc -p tsconfig.json"
  }
}
```

In order for Nx to cache this task, you need to:

- run the script through Nx using `nx exec -- `
- configure caching settings in the `nx` property of `package.json`

The new `package.json` will look like this:

```json
// package.json
{
  "scripts": {
    "build": "nx exec -- tsc -p tsconfig.json"
  },
  "nx": {
    "targets": {
      "build": {
        "cache": true,
        "inputs": [
          "{projectRoot}/**/*.ts",
          "{projectRoot}/tsconfig.json",
          { "externalDependencies": ["typescript"] }
        ],
        "outputs": ["{projectRoot}/dist"]
      }
    }
  }
}
```

Now, if you run `npm build` or `nx build` twice, the second run will be retrieved from the cache instead of being executed.

## Enable more features of Nx as needed

You could stop here if you want, but there are many more features of Nx that might be useful to you. Many [plugins](/docs/plugin-registry) can automate the process of configuring the way Nx runs your tools. Plugins also provide [code generators](/docs/features/generate-code) and [automatic dependency updates](/docs/features/automate-updating-dependencies). You can speed up your CI with [remote caching](/docs/features/ci-features/remote-cache) and [distributed task execution](/docs/features/ci-features/distribute-task-execution).

---
<!-- source: https://nx.dev/docs/guides/adopting-nx/nx-vs-turborepo.md -->
## Nx vs Turborepo

Both Nx and Turborepo seem to cover very similar ground. They provide task scheduling, caching (local and remote), and affected detection. The differences emerge as your needs grow. While **Turbo covers just the basics**, **Nx provides solutions along the entire software growth lifecycle**, even when you need more advanced features such as distributed CI, polyglot builds, or AI-powered CI workflows. That's where the gap widens.

This doesn't come at the cost of adoption complexity though. Nx is designed to be modular from the ground up and can be **adopted incrementally as you need more**.

{% aside type="note" title="Benchmarks" %}
All benchmarks on this page use the same [pnpm workspace](https://github.com/meeroslav/pnpm-workspace-baseline) migrated with both tools.
{% /aside %}

This page starts with the basics, like onboarding, and progressively moves into more advanced capabilities.

| Topic                                               | Nx                                                                | Turborepo                                                 |
| --------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------- |
| [Onboarding](#onboarding)                           | Zero-config or guided `nx init` (+3 lines)                        | Manual `turbo.json` (+144 lines)                          |
| [Running tasks](#running-tasks)                     | Runs `package.json` scripts, optional plugin-based task inference | Runs `package.json` scripts, requires `turbo.json` config |
| [Caching](#caching)                                 | Explicit opt-in, composable `namedInputs`                         | Cached by default, flat input lists                       |
| [Task sandboxing](#task-sandboxing)                 | IO tracing + cache poisoning protection                           | Not available                                             |
| [Code generation](#code-generation)                 | Programmatic generators with AST transforms and graph awareness   | Template-based file scaffolding (Plop)                    |
| [Module boundary rules](#module-boundary-rules)     | Tag-based lint rule + conformance rules (polyglot)                | Experimental `turbo boundaries` (since 2024)              |
| [Polyglot support](#polyglot-support)               | Native support for JS/TS, Java, .NET, Python, Rust                | Any CLI via `package.json` scripts, no native graph       |
| [AI integration](#ai-integration)                   | Agent skills, MCP, `configure-ai-agents`, self-healing CI         | Official skill, no MCP or CI integration                  |
| [CI solution](#running-nx-vs-turbo-on-ci)           | Nx Cloud: distribution (9m 20s), self-healing, flaky detection    | No CI solution (19m 18s with manual binning)              |
| [Cross-repo coordination](#cross-repo-coordination) | Polygraph (synthetic monorepo)                                    | Not available                                             |
| [Release management](#release-management)           | Built-in versioning, changelogs, and publishing                   | Requires manual setup or 3rd party tools                  |
| [Observability](#observability)                     | Integrated dashboards and AI-powered run analysis                 | Experimental OpenTelemetry (OTLP) export                  |
| [Developer experience](#developer-experience)       | TUI, IDE extensions, and interactive project graph                | Basic TUI and LSP support                                 |

## Onboarding

Nx works with your existing `package.json` scripts out of the box. Add the `nx` package to your workspace and you immediately get task orchestration, affected detection, and local caching, without writing any task configuration.

Turborepo requires every task to be explicitly declared in `turbo.json` before anything runs, even if the same tasks already work with your package manager directly:

```plaintext
• turbo 2.8.7
  × Missing tasks in project
  ╰─▶   × Could not find task `build` in project
```

For a more guided experience, run `npx nx init`. The interactive setup detects your existing tooling, asks which tasks should be cacheable, and scaffolds an `nx.json` with the right configuration. If you have Next.js and ESLint, for example, Nx automatically infers `build`, `dev`, `start`, and `lint` targets without you declaring them.

Looking at the raw impact on a repository using the same [pnpm workspace](https://github.com/meeroslav/pnpm-workspace-baseline) migrated with both tools:

| Setup        | Config written     | Net impact on codebase                                                    |
| ------------ | ------------------ | ------------------------------------------------------------------------- |
| Nx (minimal) | 3 lines            | [+3 lines](https://github.com/meeroslav/pnpm-workspace-baseline/pull/4)   |
| Nx (guided)  | 85 lines           | [-15 lines](https://github.com/meeroslav/pnpm-workspace-baseline/pull/2)  |
| Turborepo    | 122 lines (manual) | [+144 lines](https://github.com/meeroslav/pnpm-workspace-baseline/pull/3) |

For a full walkthrough, see [Adding Nx to your Existing Project](/docs/guides/adopting-nx/adding-to-existing-project). If you're coming from Turborepo, see [Migrating from Turborepo to Nx](/docs/guides/adopting-nx/from-turborepo).

## Running tasks

Once installed, both tools run your existing `package.json` scripts. If your project has a `build` script, `nx build` runs it, just like `turbo run build`. No rewiring needed.

```shell
nx run-many -t build test lint
```

Nx also provides [`nx affected`](/docs/features/ci-features/affected) to run only tasks affected by your current changes, which works immediately without configuration.

Where Nx goes further is with [plugins](/docs/concepts/inferred-tasks). Adding an Nx plugin like `@nx/vite` automatically infers tasks from your existing tool configuration (e.g. `vite.config.mts`), so you don't need to maintain manual script definitions. Plugins also read your tool's config to set cache `inputs` and `outputs` automatically, meaning caching works correctly from the start without manual tuning.

## Caching

Both tools cache task results, but the defaults and depth of caching support differ significantly. Better cache configuration means fewer false positives, fewer unnecessary re-runs, and faster CI.

**Turborepo caches every task by default**, so you opt out of caching with `cache: false` on tasks like `dev`. **Nx does the opposite: nothing is cached unless you explicitly set `cache: true`.** This is a more cautious opt-in model, since not all tasks are cacheable by default.

Nx also provides [`namedInputs`](/docs/reference/inputs), reusable input patterns that you can compose across targets. You define a pattern once (like "production sources") and reference it everywhere. Turborepo's `inputs` are flat lists with no composition, so every target repeats the same exclusions.

Here's the same workspace configured with both tools:

{% tabs %}
{% tabitem label="nx.json" %}

```json
{
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "sharedGlobals": ["{workspaceRoot}/.github/workflows/ci.yml"],
    "production": [
      "default",
      "!{projectRoot}/**/?(*.)+(spec|test).[jt]s?(x)?(.snap)",
      "!{projectRoot}/tsconfig.spec.json",
      "!{projectRoot}/vitest.config.[jt]s",
      "!{projectRoot}/jest.config.[jt]s"
    ]
  },
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["production", "^production"],
      "outputs": ["{projectRoot}/dist"],
      "cache": true,
      "configurations": {
        "prod": {}
      }
    },
    "check-types": {
      "dependsOn": ["^check-types"],
      "inputs": ["production", "^production"],
      "cache": true
    },
    "test": {
      "inputs": ["default", "^production"],
      "outputs": ["{projectRoot}/coverage"],
      "cache": true
    },
    "lint": {
      "inputs": ["default", "{workspaceRoot}/eslint.config.mjs"],
      "cache": true
    },
    "dev": {
      "continuous": true
    },
    "@org/shop-e2e:test:e2e": {
      "dependsOn": ["@org/shop:build"]
    },
    "@org/admin-e2e:test:e2e": {
      "dependsOn": ["@org/admin:build"]
    }
  }
}
```

{% /tabitem %}
{% tabitem label="turbo.json" %}

```json
{
  "tasks": {
    "build": {
      "outputs": ["dist/**"],
      "dependsOn": ["^build"],
      "inputs": [
        "$TURBO_DEFAULT$",
        "!eslint.config.mjs",
        "!**/*.spec.ts",
        "!**/*.test.ts",
        "!**/*.spec.tsx",
        "!**/*.test.tsx",
        "!**/*.spec.js",
        "!**/*.test.js",
        "!**/*.spec.jsx",
        "!**/*.test.jsx",
        "!tsconfig.spec.json",
        "!vitest.config.ts",
        "!jest.config.js"
      ]
    },
    "build:prod": {
      "outputs": ["dist/**"],
      "dependsOn": ["^build"],
      "inputs": [
        "$TURBO_DEFAULT$",
        "!eslint.config.mjs",
        "!**/*.spec.ts",
        "!**/*.test.ts",
        "!**/*.spec.tsx",
        "!**/*.test.tsx",
        "!**/*.spec.js",
        "!**/*.test.js",
        "!**/*.spec.jsx",
        "!**/*.test.jsx",
        "!tsconfig.spec.json",
        "!vitest.config.ts",
        "!jest.config.js"
      ]
    },
    "check-types": {
      "dependsOn": ["^check-types"],
      "inputs": [
        "$TURBO_DEFAULT$",
        "!eslint.config.mjs",
        "!**/*.spec.ts",
        "!**/*.test.ts",
        "!**/*.spec.tsx",
        "!**/*.test.tsx",
        "!**/*.spec.js",
        "!**/*.test.js",
        "!**/*.spec.jsx",
        "!**/*.test.jsx",
        "!tsconfig.spec.json",
        "!vitest.config.ts",
        "!jest.config.js"
      ]
    },
    "test": {},
    "lint": {},
    "dev": { "persistent": true, "cache": false },
    "@org/shop-e2e#test:e2e": { "dependsOn": ["@org/shop#build"] },
    "@org/admin-e2e#test:e2e": { "dependsOn": ["@org/admin#build"] }
  }
}
```

{% /tabitem %}
{% /tabs %}

The `production` pattern in Nx is defined once and reused across `build` and `test`. A change to a spec file won't invalidate the build cache because `production` explicitly excludes test files.

In Turborepo, the same exclusion list is repeated across `build`, `build:prod`, and `check-types`. There's no way to define it once and reuse it.

## Task sandboxing

A cache is only valuable if you can trust it. Turborepo has no task sandboxing. During execution, tasks can read and write anywhere on the filesystem. A task can read files that aren't declared as inputs and produce undeclared outputs that get cached and replayed into a different context. The result: false cache hits, missing artifacts, and hard-to-trace failures.

Nx provides [task sandboxing](/docs/features/ci-features/sandboxing) that monitors filesystem access during execution and flags any reads or writes outside declared `inputs` and `outputs`. Undeclared dependencies are surfaced automatically rather than discovered through debugging production incidents.

This matters for security too. [CVE-2025-36852](https://www.cve.org/CVERecord?id=CVE-2025-36852) (CREEP) demonstrated that build systems without cache isolation are vulnerable to cache poisoning, where any contributor with PR access can inject compromised artifacts into production. Nx Cloud prevents this through branch-scoped cache isolation. For more details, see [cache security](/docs/concepts/ci-concepts/cache-security).

Task sandboxing is an architectural difference, not a configuration problem. There's no workaround on the Turborepo side.

## Code generation

Both tools offer code generation, but the depth differs significantly.

Turborepo provides `turbo gen`, a thin wrapper around [Plop.js](https://plopjs.com/). It can scaffold new workspaces and create files from Handlebars templates, but it's limited to template-based file creation and simple string append/prepend operations. There's no AST-level code modification, no awareness of the project graph, and no migration/codemod system.

Nx generators are built on top of [Nx Devkit](/docs/extending-nx/intro), a full programmatic API for workspace manipulation. Generators can read and modify the project graph, perform AST-level TypeScript transforms, and compose with other generators. You can create [local workspace generators](/docs/features/generate-code#creating-custom-generators) that encode your team's specific patterns.

The real value isn't raw scaffolding, AI can do that too. It's deterministic, convention-aware generation. **AI agents can invoke your generators to produce code matching your patterns from the start.** This is faster and more token-efficient than generating everything from scratch.

## Module boundary rules

In large workspaces, unchecked dependencies between projects lead to architectural drift. Both tools offer mechanisms to enforce boundaries, but with different maturity and scope.

Nx has provided [module boundary rules](/docs/features/enforce-module-boundaries) since its earliest versions. You assign tags to projects and define which tags can depend on which, enforced as a lint rule. For polyglot workspaces where ESLint isn't available, Nx also offers [conformance rules](/docs/enterprise/conformance) that work across any language.

This becomes especially important with AI coding agents. Boundary rules act as guardrails, preventing agents from creating arbitrary cross-project dependencies that violate your architecture.

Turborepo added experimental [`turbo boundaries`](https://turborepo.dev/docs/reference/boundaries) in 2024, which can define allowed dependencies in `turbo.json` and visualize them in their devtools graph view.

## Polyglot support

Nx provides [first-party plugins](/docs/plugin-registry) for Maven, Gradle, .NET, and Docker, plus community plugins for Python (UV, Poetry), Rust (Cargo), Go, and PHP.
Each plugin provides automatic dependency detection, target inference, caching, affected detection, and distribution.

Turborepo can orchestrate any language by wrapping CLI commands in `package.json` scripts. However, non-JS projects still require a `package.json`, and Turborepo provides no automatic dependency graph analysis or target inference for those languages. You must define everything manually.

**This difference is critical for AI readiness.** When your backend is in Go and your frontend is in Next.js, an AI agent with Nx can see the full cross-language dependency chain. With Turborepo, those services are "islands," and an agent has no way to reason about how a change in the Go API affects the frontend.

## AI integration

Nx actively embraces AI and autonomous agents across the entire development lifecycle, not just individual features. Running [`nx configure-ai-agents`](/blog/nx-ai-agent-skills) sets up everything your AI agent needs in one command: agent skills, an MCP server, and `CLAUDE.md` / `AGENTS.md` guidelines. It works across **Claude Code, Cursor, GitHub Copilot, Gemini, Codex, and OpenCode**.

- **[Agent skills](/blog/why-we-deleted-most-of-our-mcp-tools)** teach agents _how_ to work in your monorepo: when to use generators, how to explore the project graph, how to run tasks efficiently. Skills are loaded incrementally, keeping context focused and token-efficient.
- **[Self-healing CI](/docs/features/ci-features/self-healing-ci)** is a specialized AI agent that runs on CI, monitors runs, diagnoses broken tasks, provides verified fixes, and automatically identifies and [re-runs flaky tasks](/docs/features/ci-features/flaky-tasks).
- Dedicated skills and an **[MCP server](/docs/reference/nx-mcp)** allow the local coding agent to connect and [coordinate with the remote CI agent](/blog/autonomous-ai-workflows-with-nx), creating fully autonomous push-fix-verify loops.
- The **Nx CLI is [optimized for agentic use](/blog/making-nx-agent-ready)**: commands like `nx init`, `nx import`, and `create-nx-workspace` detect when they're called by an agent and emit structured JSON output instead of interactive prompts, reducing wasted tokens and retries.

Turborepo provides an [official skill](https://skills.sh/vercel/turborepo-skills) covering task configuration and caching strategies, plus a `turbo docs` command. However, no CI integration for agents, and no AI powered self-healing CI system.

## Running Nx vs Turbo on CI

Nx works on any CI provider out of the box. Run `nx affected` or `nx run-many` in your existing pipeline and you get caching, affected detection, and task orchestration without additional setup. For teams that need more, [Nx Cloud](/docs/features/ci-features) layers on remote caching, intelligent task distribution across machines, self-healing CI, and flaky task detection, all integrated directly into your existing CI provider.

Turborepo has no CI-specific solution. It runs tasks on CI the same way it does locally, with no built-in distribution, failure recovery, or CI-aware features.

![Nx Cloud CI report integrated into a GitHub PR](../../../../assets/guides/adopting-nx/ci-report.avif)

### Single-machine CI performance

On a single CI runner with no cache hits, Nx is measurably faster.
Its Rust-powered task scheduler produces a more optimal execution order, and its file hashing and cache restoration are more efficient.

![Nx 21m 56s vs Turborepo 25m 32s on a single CI runner](../../../../assets/guides/adopting-nx/single-machine.avif)

| Tool      | Duration | Difference  |
| --------- | -------- | ----------- |
| Nx        | 21m 56s  | N/A         |
| Turborepo | 25m 32s  | ~16% slower |

A 16% gap may sound modest, but on a 30-minute pipeline that's nearly 4 minutes saved on every run. Note that these numbers are without any cache optimization, just both tools running out of the box on the same codebase.

### Distributed CI

When a single machine is no longer enough, the tools diverge significantly.

On the same workspace distributed across 4 machines:

| Metric         | Nx Agents      | Turborepo (binning) |
| -------------- | -------------- | ------------------- |
| Total duration | 9m 20s         | 19m 18s             |
| Agent spread   | 5m 1s - 9m 16s | 2m 50s - 18m 20s    |

{% tabs %}
{% tabitem label="Nx Agents" %}

**Nx Agents** splits work across multiple CI machines at the individual task level, dynamically balancing load based on historical timing data. The scheduler keeps all agents busy with minimal idle time.

![Nx Agents distributing work evenly across 4 machines](../../../../assets/guides/adopting-nx/nx-dte.avif)

{% /tabitem %}
{% tabitem label="Turborepo (binning)" %}

**Turborepo** has no built-in distribution. Scaling to multiple machines requires manual "binning," where you statically assign tasks to runners and rebalance by hand as the codebase evolves.

![Turborepo binning with severely unbalanced agent utilization](../../../../assets/guides/adopting-nx/turbo-binning.avif)

{% /tabitem %}
{% /tabs %}

Turborepo is 2x slower even on this small sample.
One Turborepo agent ran for 18 minutes while another sat idle after 3 minutes. The gap grows with more machines.

**The core difference is declarative vs imperative**:

- With Nx you declare _what_ should run on CI, and Nx Cloud figures out the optimal distribution automatically. Nx Agents adapts automatically and gets smarter over time.
- With Turborepo, you imperatively assign tasks to machines and maintain that mapping as the codebase evolves.

To learn more about distribution on CI, read [Distribute Task Execution (Nx Agents)](/docs/features/ci-features/distribute-task-execution).

Nx also provides **Atomizer**, which automatically splits slow e2e and integration test suites into per-file tasks that can run in parallel across machines.
For more information, see [split e2e tasks](/docs/features/ci-features/split-e2e-tasks).

### CI throughput

Raw CI speed is one part of throughput. The other is avoiding failed PRs. A failing PR means a developer has to stop, inspect logs, provide a fix, push again, and wait for another CI run. As AI agents ship more PRs, CI quickly becomes the bottleneck.

Nx Cloud's [self-healing CI](/docs/features/ci-features/self-healing-ci) places a specialized AI agent on CI that analyzes failures, proposes fixes, and auto-applies verified fixes. This reduces friction on the developer side, allowing PRs to move forward without manual intervention.

[Flaky task detection](/docs/features/ci-features/flaky-tasks) identifies flaky tests and re-runs them in isolation, preventing false failures from blocking your pipeline.

![Time to green data: ~1h reduction per PR, 1h 24m developer time saved, 22.6% fewer context switches](../../../../assets/guides/adopting-nx/time-to-green.avif)

_The metrics shown above are extracted directly from the Nx Cloud dashboard._

Turborepo offers neither. A flaky test fails the build, and every failure requires a full human round trip.

### Observability

Both tools offer visibility into your pipelines, but through different models.

**Nx Cloud** provides integrated dashboards out of the box. You get detailed run reports, timing data, cache hit/miss trends, and historical performance analysis without any external setup. These insights are also queryable via the MCP server, letting AI assistants analyze CI performance conversationally.

![Nx DTE across 12 Nx Agents - all agents have minimum 97% utilization](../../../../assets/guides/adopting-nx/dte-chart.avif)

_Nx Agent utilization chart, showing even distribution across CI runners._

For deep dives into resource utilization, see [CI Resource Usage](/docs/guides/nx-cloud/ci-resource-usage).

**Turborepo** exposes run metrics via experimental **OpenTelemetry (OTLP)**. This is useful if you already have a mature observability stack (like Datadog or Grafana) and want to route build metrics into it, though it requires significant manual setup and maintenance of your own collector and visualization layer.

## Cross-repo coordination

Most organizations don't have a single monorepo. They have several monorepos plus standalone repos across teams.

Nx Cloud's [Polygraph](/docs/enterprise/polygraph) creates a [synthetic monorepo](/docs/concepts/synthetic-monorepos): a unified dependency graph across separate repositories without moving any code. AI agents can read the cross-repo graph, coordinate changes across repos, and manage PRs across repo boundaries.

Turborepo has no cross-repo coordination.

## Release management

Versioning and publishing libraries in a monorepo is a complex orchestration task. You need to identify what changed, determine the next version for each package, update internal dependencies, generate changelogs, and publish to registries.

**Nx provides a first-party, unified release system** via [`nx release`](/docs/features/manage-releases) that automates the entire lifecycle of versioning, changelog generation, and publishing with a single, highly configurable command.

Turborepo has no built-in release solution. Teams usually end up manually configuring third-party tools like [Changesets](https://changesets.js.org/) or [Lerna](https://lerna.js.org/), adding another layer of manual setup and tool maintenance to the workspace.

## Developer experience

### Project graph

Both tools can visualize the dependency graph, but the implementations differ significantly at scale. Turborepo renders every node at once, which becomes unreadable past a few dozen projects. Nx provides an interactive graph that lets you filter, group, and search projects, then drill into any node for details on demand.

{% tabs %}
{% tabitem label="Nx (grouped)" %}

![Nx project graph with projects grouped by directory](../../../../assets/guides/adopting-nx/nx-graph-grouping.avif)

{% /tabitem %}
{% tabitem label="Nx (ungrouped)" %}

![Nx project graph with clean nodes and clear connections](../../../../assets/guides/adopting-nx/nx-graph.avif)

{% /tabitem %}
{% tabitem label="Turborepo" %}

![Turborepo graph rendering all nodes at once](../../../../assets/guides/adopting-nx/turbo-repo-graph.avif)

{% /tabitem %}
{% /tabs %}

The Nx graph is also available inside [Nx Console](/docs/getting-started/editor-setup), so you can explore dependencies without leaving your editor.

{% aside type="tip" title="Ready to migrate?" %}
For step-by-step migration instructions, including configuration mapping and command equivalents, see [Migrating from Turborepo to Nx](/docs/guides/adopting-nx/from-turborepo).
{% /aside %}

### Terminal UI

Nx ships with a full [terminal UI](/docs/guides/tasks--caching/terminal-ui) that adapts to what you're running.
For multi-task runs, it shows a task overview with filtering, pinning, and layout switching.
For a single task with no dependencies, it drops into a simplified view with the output front and center.
Colors, order, and indentation from your underlying tools are preserved.

Turborepo has a more simplified version of a TUI which shows task output in a split view. You can opt-in to that TUI experience.

### IDE extensions

[Nx Console](/docs/getting-started/editor-setup) provides extensions for VS Code and WebStorm/IntelliJ with close to 2 million installations.
You can run tasks, explore the project graph, scaffold with generators, and inspect Nx Cloud CI runs directly from your editor.
It also includes a language server that provides autocompletion in `nx.json` and `project.json` files.

Turborepo provides basic LSP support for `turbo.json`.

---
<!-- source: https://nx.dev/docs/guides/adopting-nx/preserving-git-histories.md -->
## Preserving Git Histories when Migrating Projects to Nx

{% aside type="note" title="Automatically import with 'nx import'" %}

In Nx 19.8 we introduced `nx import` which helps you import projects into your Nx workspace, including preserving the Git history. [Read more in the according doc](/docs/guides/adopting-nx/import-project).

{% /aside %}

The nature of a monorepo is to swallow up standalone projects as your organization buys into the benefits of a monorepo workflow.

As your monorepo consumes other projects though, it's important to ensure that git history for those projects is preserved inside of our Nx Workspace.

Git has some helpful tools for this, and some of the common pitfalls and gotchas of this task!

## Merging in a standalone project

To merge in another project, we'll essentially use the standard `git merge` command, but with a few lesser known options/caveats.

If your standalone project was not an Nx workspace, it's likely that your migration work will also entail moving directories to match a typical Nx Workspace structure. You can find more information in the [Manual migration](/docs/guides/adopting-nx/manual) page, but when migrating an existing project, you'll want to ensure that you use [`git mv`](https://git-scm.com/docs/git-mv) when moving a file or directory to ensure that file history from the old standalone repo is not lost!

In order to avoid merge conflicts later, it's best to first do the folder reorganization in the _standalone project repo_. For example, assuming you want the standalone app to end up at `apps/my-standalone-app` in the monorepo and your main branch is called `master`:

```shell
cd my-standalone-app
git checkout main
git fetch
git checkout -b monorepo-migration main
mkdir -p apps/my-standalone-app
git ls-files | sed 's!/.*!!'| uniq | xargs -i git mv {} apps/my-standalone-app
```

Check if you need to move back the `.gitignore` file to the root and/or update any paths so you don't commit previously ignored files/folders.
If all is well proceed with the commit and push.

```shell
git commit -m "Move files in preparation for monorepo migration"
git push --set-upstream origin monorepo-migration
```

Next, in your monorepo, we'll add a remote repository url for where the standalone app is located:

```shell
git remote add my-standalone-app <repository url>
git fetch my-standalone-app
```

Then we'll run

```shell
git merge my-standalone-app/monorepo-migration --allow-unrelated-histories
```

Note that without the `--allow-unrelated-histories` option, the command would fail with the message: `fatal: refusing to merge unrelated histories`.

---
<!-- source: https://nx.dev/docs/guides/ci-deployment.md -->
## Prepare Applications for Deployment via CI

{% aside type="note" title="Using TS Solution Setup?" %}
If your workspace uses TS project references (the default in Nx 20+), use the [prune workflow](/docs/technologies/node/guides/deploying-node-projects) instead. The `generatePackageJson` approach below applies to workspaces without TS Solution Setup.
{% /aside %}

A common approach to deploying applications is via docker containers. Some applications can be built into bundles that are environment agnostic, while others depend on OS-specific packages being installed. For these situations, having just bundled code is not enough, we also need to have `package.json`.

Nx supports the generation of the project's `package.json` by identifying all the project's dependencies. The generated `package.json` is created next to the built artifacts (usually at `dist/apps/name-of-the-app`).

Additionally, we should generate pruned lock file according to the generated `package.json`. This makes the installation in the container significantly faster as we only need to install a subset of the packages.

Nx offers two varieties of Webpack plugin which can be used to generate `package.json`.

## Basic plugin configuration

`@nx/webpack/plugin` plugin is compatible with a conventional webpack configuration setup which offers a smooth integration with the Webpack CLI.
It is configured in the `plugins` array in `nx.json`.

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/webpack/plugin",
      "options": {
        "buildTargetName": "build",
        "serveTargetName": "serve",
        "serveStaticTargetName": "serve-static",
        "previewStaticTargetName": "preview"
      }
    }
  ]
}
```

Where `build`, `serve`, `serve-static` and `preview` in conjunction with your `webpack.config.js` are the names of the targets that are used to _build_, _serve_, and _preview_ the application respectively.

### NxAppWebpackPlugin

The [`NxAppWebpackPlugin`](/docs/technologies/build-tools/webpack/guides/webpack-plugins#nxappwebpackplugin) plugin takes a `main` entry file and produces a bundle in the output directory as defined in `output.path`. You can also pass the `index` option if it is a web app, which will handle outputting scripts and stylesheets in the output file.

To generate a `package.json` we would declare it in the plugin options.

```js
// apps/acme/app/webpack.config.js
const { NxAppWebpackPlugin } = require('@nx/webpack/app-plugin');
const { join } = require('path');

module.exports = {
  output: {
    path: join(__dirname, '../../dist/apps/acme'),
  },
  devServer: {
    port: 4200,
  },
  plugins: [
    new NxAppWebpackPlugin({
      tsConfig: './tsconfig.app.json',
      compiler: 'swc',
      main: './src/main.tsx',
      index: '.src/index.html',
      styles: ['./src/styles.css'],
      generatePackageJson: true,
    }),
  ],
};
```

## Programmatic usage

If you are using a custom setup that does not support the creation of a `package.json` or a lock file, you can still use Nx to generate them via The `createPackageJson` and `createLockFile` functions which are exported from `@nx/js`:

{% tabs %}

{% tabitem label="Custom script" %}

If you need to use a custom script, to build your application it should look similar to the following:

```javascript
// scripts/create-package-json.js
const {
  createProjectGraphAsync,
  readCachedProjectGraph,
  detectPackageManager,
  writeJsonFile,
} = require('@nx/devkit');
const {
  createLockFile,
  createPackageJson,
  getLockFileName,
} = require('@nx/js');
const { writeFileSync } = require('fs');

async function main() {
  const outputDir = 'dist'; // You can replace this with the output directory you want to use
  // Detect the package manager you are using (npm, yarn, pnpm, bun)
  const pm = detectPackageManager();
  let projectGraph = readCachedProjectGraph();
  if (!projectGraph) {
    projectGraph = await createProjectGraphAsync();
  }
  // You can replace <NX_TASK_TARGET_PROJECT> with the name of the project if you want.
  const projectName = process.env.NX_TASK_TARGET_PROJECT;
  const packageJson = createPackageJson(projectName, projectGraph, {
    isProduction: true, // Used to strip any non-prod dependencies
    root: projectGraph.nodes[projectName].data.root,
  });

  const lockFile = createLockFile(
    packageJson,
    projectGraph,
    detectPackageManager()
  );

  const lockFileName = getLockFileName(pm);

  writeJsonFile(`${outputDir}/package.json`, packageJson);
  writeFileSync(`${outputDir}/${lockFileName}`, lockFile, {
    encoding: 'utf8',
  });

  //... Any additional steps you want to run
}

main();
```

Then to run the script, update your `package.json` to include the following:

```json
// package.json
{
  "scripts": {
    "copy-package-json": "node scripts/create-package-json.js",
    "custom-build": "nx build && npm run copy-package-json"
  }
}
```

Now, you can run `npm run custom-build` to build your application and generate the `package.json` and lock file.

You can replace _npm_ with _yarn_, _pnpm_, or _bun_ if you are using those package managers.

{% /tabitem %}

{% tabitem label="Custom executor" %}

```typescript
// Custom executor
import { Schema } from './schema';
import { createPackageJson, createLockFile, getLockFileName } from '@nx/js';
import { writeFileSync } from 'fs';
import {
  detectPackageManager,
  ExecutorContext,
  writeJsonFile,
} from '@nx/devkit';

export default async function buildExecutor(
  options: Schema,
  context: ExecutorContext
) {
  // ...your executor code
  const packageManager = detectPackageManager();

  const packageJson = createPackageJson(
    context.projectName,
    context.projectGraph,
    {
      root: context.root,
      isProduction: true, // We want to strip any non-prod dependencies
    }
  );

  // do any additional manipulations to "package.json" here

  const lockFile = createLockFile(
    packageJson,
    context.projectGraph,
    packageManager
  );
  const lockFileName = getLockFileName(packageManager);
  writeJsonFile(`${options.outputPath}/package.json`, packageJson);
  writeFileSync(`${options.outputPath}/${lockFileName}`, lockFile, {
    encoding: 'utf-8',
  });

  // any subsequent executor code
}
```

{% /tabitem %}
{% /tabs %}

{% aside type="note" %}
**What about Vite?**

Vite is a build tool that is great for development, and we want to make sure that it is also great for production. We are working on an `NxVitePlugin` plugin for Vite that will have parity with the `NxWebpackPlugin`. Stay tuned for updates.
{% /aside %}

---
<!-- source: https://nx.dev/docs/guides/enforce-module-boundaries.md -->
## Enforce Module Boundaries

{% index_page_cards path="guides/enforce-module-boundaries" /%}

---
<!-- source: https://nx.dev/docs/guides/enforce-module-boundaries/ban-dependencies-with-tags.md -->
## Ban Dependencies with Certain Tags

Specifying which tags a project is allowed to depend on can sometimes lead to a long list of possible options:

```jsonc
{
  "sourceTag": "scope:client",
  // we actually want to say it cannot depend on `scope:admin`
  "onlyDependOnLibsWithTags": [
    "scope:shared",
    "scope:utils",
    "scope:core",
    "scope:client",
  ],
}
```

The property `notDependOnLibsWithTags` is used to invert this condition by explicitly specifying which tag(s) it cannot depend on:

```jsonc
{
  "sourceTag": "scope:client",
  // we accept any tag except for `scope:admin`
  "notDependOnLibsWithTags": ["scope:admin"],
}
```

In contrast to `onlyDependOnLibsWithTags`, the `notDependOnLibsWithTags` will also follow down the _entire dependency tree_ to make sure there are no sub-dependencies that violate this rule. You can also use a combination of these two rules to restrict certain types of projects to be imported:

```jsonc
{
  "sourceTag": "type:react",
  "onlyDependOnLibsWithTags": [
    "type:react",
    "type:utils",
    "type:animation",
    "type:model",
  ],
  // make sure no `angular` code ends up being referenced by react projects
  "notDependOnLibsWithTags": ["type:angular"],
}
```

---
<!-- source: https://nx.dev/docs/guides/enforce-module-boundaries/ban-external-imports.md -->
## Ban External Imports

**This constraint is only available for projects using ESLint.**

You may want to constrain what external packages a project may import. For example, you may want to prevent backend projects from importing packages related to your frontend framework. You can ban these imports using `bannedExternalImports` property in your dependency constraints configuration.

A common example of this is for backend projects that use NestJS and frontend projects that use Angular. Both frameworks contain a class named `Injectable`. It's very easy for a developer to import the wrong one by mistake, especially when using auto-import in an IDE. To prevent this, add tags to define the type of project to distinguish between backend and frontend projects. Each tag should define its own list of banned external imports.

{% tabs syncKey="eslint-config-preference" %}
{% tabitem label="Flat Config" %}

```javascript
// eslint.config.mjs
import nx from '@nx/eslint-plugin';

export default [
  ...nx.configs['flat/base'],
  ...nx.configs['flat/typescript'],
  ...nx.configs['flat/javascript'],
  {
    files: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
    rules: {
      '@nx/enforce-module-boundaries': [
        'error',
        {
          allow: [],
          // update depConstraints based on your tags
          depConstraints: [
            // projects tagged with "frontend" can't import from "@nestjs/common"
            {
              sourceTag: 'frontend',
              bannedExternalImports: ['@nestjs/common'],
            },
            // projects tagged with "backend" can't import from "@angular/core"
            {
              sourceTag: 'backend',
              bannedExternalImports: ['@angular/core'],
            },
          ],
        },
      ],
    },
  },
];
```

{% /tabitem %}
{% tabitem label="Legacy (.eslintrc.json)" %}

```jsonc
// .eslintrc.json
{
  // ... more ESLint config here

  // @nx/enforce-module-boundaries should already exist at the top-level of your config
  "@nx/enforce-module-boundaries": [
    "error",
    {
      "allow": [],
      // update depConstraints based on your tags
      "depConstraints": [
        // projects tagged with "frontend" can't import from "@nestjs/common"
        {
          "sourceTag": "frontend",
          "bannedExternalImports": ["@nestjs/common"],
        },
        // projects tagged with "backend" can't import from "@angular/core"
        {
          "sourceTag": "backend",
          "bannedExternalImports": ["@angular/core"],
        },
      ],
    },
  ],

  // ... more ESLint config here
}
```

{% /tabitem %}
{% /tabs %}

Another common example is ensuring that util libraries stay framework-free by banning imports from these frameworks. You can use wildcard `*` to match multiple projects e.g. `react*` would match `react`, but also `react-dom`, `react-native` etc. You can also have multiple wildcards e.g. `*react*` would match any package with word `react` in it's name. A workspace using React would have a configuration like this.

{% tabs syncKey="eslint-config-preference" %}
{% tabitem label="Flat Config" %}

```javascript
// eslint.config.mjs
import nx from '@nx/eslint-plugin';

export default [
  ...nx.configs['flat/base'],
  ...nx.configs['flat/typescript'],
  ...nx.configs['flat/javascript'],
  {
    files: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
    rules: {
      '@nx/enforce-module-boundaries': [
        'error',
        {
          allow: [],
          // update depConstraints based on your tags
          depConstraints: [
            // projects tagged with "type:util" can't import from "react" or related projects
            {
              sourceTag: 'type:util',
              bannedExternalImports: ['*react*'],
            },
          ],
        },
      ],
    },
  },
];
```

{% /tabitem %}
{% tabitem label="Legacy (.eslintrc.json)" %}

```jsonc
// .eslintrc.json
{
  // ... more ESLint config here
  // @nx/enforce-module-boundaries should already exist at the top-level of your config
  "@nx/enforce-module-boundaries": [
    "error",
    {
      "allow": [],
      // update depConstraints based on your tags
      "depConstraints": [
        // projects tagged with "type:util" can't import from "react" or related projects
        {
          "sourceTag": "type:util",
          "bannedExternalImports": ["*react*"],
        },
      ],
    },
  ],

  // ... more ESLint config here
}
```

{% /tabitem %}
{% /tabs %}

## Allowlist external imports with `allowedExternalImports`

If you need a more restrictive approach, you can use the `allowedExternalImports` option to ensure that a project only imports from a specific set of packages.
This is useful if you want to enforce separation of concerns _(e.g. keeping your domain logic clean from infrastructure concerns, or ui libraries clean from data access concerns)_ or keep some parts of your codebase framework-free or library-free.

{% tabs syncKey="eslint-config-preference" %}
{% tabitem label="Flat Config" %}

```javascript
// eslint.config.mjs
import nx from '@nx/eslint-plugin';

export default [
  ...nx.configs['flat/base'],
  ...nx.configs['flat/typescript'],
  ...nx.configs['flat/javascript'],
  {
    files: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
    rules: {
      '@nx/enforce-module-boundaries': [
        'error',
        {
          allow: [],
          // update depConstraints based on your tags
          depConstraints: [
            // limiting the dependencies of util libraries to the bare minimum
            // projects tagged with "type:util" can only import from "date-fns"
            {
              sourceTag: 'type:util',
              allowedExternalImports: ['date-fns'],
            },
            // ui libraries clean from data access concerns
            // projects tagged with "type:ui" can only import packages matching "@angular/*" except "@angular/common/http"
            {
              sourceTag: 'type:ui',
              allowedExternalImports: ['@angular/*'],
              bannedExternalImports: ['@angular/common/http'],
            },
            // keeping the domain logic clean from infrastructure concerns
            // projects tagged with "type:core" can't import any external packages.
            {
              sourceTag: 'type:core',
              allowedExternalImports: [],
            },
          ],
        },
      ],
    },
  },
];
```

{% /tabitem %}
{% tabitem label="Legacy (.eslintrc.json)" %}

```jsonc
// .eslintrc.json
{
  // ... more ESLint config here

  // @nx/enforce-module-boundaries should already exist at the top-level of your config
  "@nx/enforce-module-boundaries": [
    "error",
    {
      "allow": [],
      // update depConstraints based on your tags
      "depConstraints": [
        // limiting the dependencies of util libraries to the bare minimum
        // projects tagged with "type:util" can only import from "date-fns"
        {
          "sourceTag": "type:util",
          "allowedExternalImports": ["date-fns"],
        },
        // ui libraries clean from data access concerns
        // projects tagged with "type:ui" can only import packages matching "@angular/*" except "@angular/common/http"
        {
          "sourceTag": "type:ui",
          "allowedExternalImports": ["@angular/*"],
          "bannedExternalImports": ["@angular/common/http"],
        },
        // keeping the domain logic clean from infrastructure concerns
        // projects tagged with "type:core" can't import any external packages.
        {
          "sourceTag": "type:core",
          "allowedExternalImports": [],
        },
      ],
    },
  ],
}
```

{% /tabitem %}
{% /tabs %}

---
<!-- source: https://nx.dev/docs/guides/enforce-module-boundaries/tag-multiple-dimensions.md -->
## Tag in Multiple Dimensions

The example listed in [Enforce Module Boundaries](/docs/features/enforce-module-boundaries#tags) shows using a single dimension: `scope`. It's the most commonly used one. But you can find other dimensions useful. You can define which projects contain components, state management code, and features, so you, for instance, can disallow projects containing presentational UI components to depend on state management code. You can define which projects are experimental and which are stable, so stable applications cannot depend on experimental projects etc. You can define which projects have server-side code and which have client-side code to make sure your node app doesn't bundle in your frontend framework.

Let's consider our previous three scopes - `scope:client`. `scope:admin`, `scope:shared`. By using just a single dimension, our `client-e2e` application would be able to import `client` application or `client-feature-main`. This is likely not something we want to allow as it's using framework that our E2E project doesn't have.

Let's add another dimension - `type`. Some of our projects are applications, some are UI features and some are just plain helper libraries. Let's define three new tags: `type:app`, `type:feature`, `type:ui` and `type:util`.

Our project configurations might now look like this:

```jsonc {% title="client" %}
{
  // ... more project configuration here

  "tags": ["scope:client", "type:app"],
}
```

```jsonc {% title="client-e2e" %}
{
  // ... more project configuration here

  "tags": ["scope:client", "type:app"],
  "implicitDependencies": ["client"],
}
```

```jsonc {% title="admin" %}
{
  // ... more project configuration here

  "tags": ["scope:admin", "type:app"],
}
```

```jsonc {% title="admin-e2e" %}
{
  // ... more project configuration here

  "tags": ["scope:admin", "type:app"],
  "implicitDependencies": ["admin"],
}
```

```jsonc {% title="client-feature-main" %}
{
  // ... more project configuration here

  "tags": ["scope:client", "type:feature"],
}
```

```jsonc {% title="admin-feature-permissions" %}
{
  // ... more project configuration here

  "tags": ["scope:admin", "type:feature"],
}
```

```jsonc {% title="components-shared" %}
{
  // ... more project configuration here

  "tags": ["scope:shared", "type:ui"],
}
```

```jsonc {% title="utils" %}
{
  // ... more project configuration here

  "tags": ["scope:shared", "type:util"],
}
```

We can now restrict projects within the same group to depend on each other based on the type:

- `app` can only depend on `feature`, `ui` or `util`, but not other apps
- `feature` cannot depend on app or another feature
- `ui` can only depend on other `ui`
- everyone can depend on `util` including `util` itself

{% tabs syncKey="eslint-config-preference" %}
{% tabitem label="Flat Config" %}

```javascript
// eslint.config.mjs
import nx from '@nx/eslint-plugin';

export default [
  ...nx.configs['flat/base'],
  ...nx.configs['flat/typescript'],
  ...nx.configs['flat/javascript'],
  {
    files: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
    rules: {
      '@nx/enforce-module-boundaries': [
        'error',
        {
          allow: [],
          // update depConstraints based on your tags
          depConstraints: [
            {
              sourceTag: 'scope:shared',
              onlyDependOnLibsWithTags: ['scope:shared'],
            },
            {
              sourceTag: 'scope:admin',
              onlyDependOnLibsWithTags: ['scope:shared', 'scope:admin'],
            },
            {
              sourceTag: 'scope:client',
              onlyDependOnLibsWithTags: ['scope:shared', 'scope:client'],
            },
            {
              sourceTag: 'type:app',
              onlyDependOnLibsWithTags: [
                'type:feature',
                'type:ui',
                'type:util',
              ],
            },
            {
              sourceTag: 'type:feature',
              onlyDependOnLibsWithTags: ['type:ui', 'type:util'],
            },
            {
              sourceTag: 'type:ui',
              onlyDependOnLibsWithTags: ['type:ui', 'type:util'],
            },
            {
              sourceTag: 'type:util',
              onlyDependOnLibsWithTags: ['type:util'],
            },
          ],
        },
      ],
    },
  },
];
```

{% /tabitem %}
{% tabitem label="Legacy (.eslintrc.json)" %}

```jsonc
// .eslintrc.json
{
  // ... more ESLint config here

  // @nx/enforce-module-boundaries should already exist at the top-level of your config
  "@nx/enforce-module-boundaries": [
    "error",
    {
      "allow": [],
      // update depConstraints based on your tags
      "depConstraints": [
        {
          "sourceTag": "scope:shared",
          "onlyDependOnLibsWithTags": ["scope:shared"],
        },
        {
          "sourceTag": "scope:admin",
          "onlyDependOnLibsWithTags": ["scope:shared", "scope:admin"],
        },
        {
          "sourceTag": "scope:client",
          "onlyDependOnLibsWithTags": ["scope:shared", "scope:client"],
        },
        {
          "sourceTag": "type:app",
          "onlyDependOnLibsWithTags": ["type:feature", "type:ui", "type:util"],
        },
        {
          "sourceTag": "type:feature",
          "onlyDependOnLibsWithTags": ["type:ui", "type:util"],
        },
        {
          "sourceTag": "type:ui",
          "onlyDependOnLibsWithTags": ["type:ui", "type:util"],
        },
        {
          "sourceTag": "type:util",
          "onlyDependOnLibsWithTags": ["type:util"],
        },
      ],
    },
  ],

  // ... more ESLint config here
}
```

{% /tabitem %}
{% /tabs %}

There are no limits to the number of tags, but as you add more tags the complexity of your dependency constraints rises exponentially. It's always good to draw a diagram and carefully plan the boundaries.

## Matching multiple source tags

Matching just a single source tag is sometimes not enough for solving complex restrictions. To avoid creating ad-hoc tags that are only meant for specific constraints, you can also combine multiple tags with `allSourceTags`. Each tag in the array must be matched for a constraint to be applied:

{% tabs syncKey="eslint-config-preference" %}
{% tabitem label="Flat Config" %}

```javascript
// eslint.config.mjs
import nx from '@nx/eslint-plugin';

export default [
  ...nx.configs['flat/base'],
  ...nx.configs['flat/typescript'],
  ...nx.configs['flat/javascript'],
  {
    files: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
    rules: {
      '@nx/enforce-module-boundaries': [
        'error',
        {
          allow: [],
          // update depConstraints based on your tags
          depConstraints: [
            {
              // this constraint applies to all "admin" projects
              sourceTag: 'scope:admin',
              onlyDependOnLibsWithTags: ['scope:shared', 'scope:admin'],
            },
            {
              sourceTag: 'type:ui',
              onlyDependOnLibsWithTags: ['type:ui', 'type:util'],
            },
            {
              // we don't want our admin ui components to depend on anything except utilities,
              // and we also want to ban router imports
              allSourceTags: ['scope:admin', 'type:ui'],
              onlyDependOnLibsWithTags: ['type:util'],
              bannedExternalImports: ['*router*'],
            },
          ],
        },
      ],
    },
  },
];
```

{% /tabitem %}
{% tabitem label="Legacy (.eslintrc.json)" %}

```jsonc
// .eslintrc.json
{
  // ... more ESLint config here

  // @nx/enforce-module-boundaries should already exist at the top-level of your config
  "@nx/enforce-module-boundaries": [
    "error",
    {
      "allow": [],
      // update depConstraints based on your tags
      "depConstraints": [
        {
          // this constraint applies to all "admin" projects
          "sourceTag": "scope:admin",
          "onlyDependOnLibsWithTags": ["scope:shared", "scope:admin"],
        },
        {
          "sourceTag": "type:ui",
          "onlyDependOnLibsWithTags": ["type:ui", "type:util"],
        },
        {
          // we don't want our admin ui components to depend on anything except utilities,
          // and we also want to ban router imports
          "allSourceTags": ["scope:admin", "type:ui"],
          "onlyDependOnLibsWithTags": ["type:util"],
          "bannedExternalImports": ["*router*"],
        },
      ],
    },
  ],

  // ... more ESLint config here
}
```

{% /tabitem %}
{% /tabs %}

## Further reading

- [Article: Taming Code Organization with Module Boundaries in Nx](https://nx.dev/blog/mastering-the-project-boundaries-in-nx)

---
<!-- source: https://nx.dev/docs/guides/enforce-module-boundaries/tags-allow-list.md -->
## Tags Allow List

Sometimes there are specific situations where you want to break the tag rules you've set up for project dependencies.

Each project can set an `allow` property in the project configuration to override the tagging rules that have been set up.

- `"allow": ['@myorg/mylib/testing']` allows importing `'@myorg/mylib/testing'`.
- `"allow": ['@myorg/mylib/*']` allows importing `'@myorg/mylib/a'` but not `'@myorg/mylib/a/b'`.
- `"allow": ['@myorg/mylib/**']` allows importing `'@myorg/mylib/a'` and `'@myorg/mylib/a/b'`.
- `"allow": ['@myorg/**/testing']` allows importing `'@myorg/mylib/testing'` and `'@myorg/nested/lib/testing'`.

---
<!-- source: https://nx.dev/docs/guides/installation.md -->
## Guides

{% index_page_cards path="guides/installation" /%}

---
<!-- source: https://nx.dev/docs/guides/installation/install-non-javascript.md -->
## Install Nx in a Non-JavaScript Repository

Nx can manage its own installation without requiring a `package.json` file or a `node_modules` folder. This type of installation is useful for repositories that may not contain any JavaScript or TypeScript (e.g. .Net or Java based workspaces that want to leverage Nx features). In this setup, the Nx CLI is all contained within a `.nx` folder.

## Globally install Nx

First globally install Nx using Homebrew (Mac and Linux) or with a manually installed version of Node (any OS).

{% tabs syncKey="install-type" %}
{% tabitem label="Homebrew" %}

If you have [Homebrew installed](https://brew.sh/), you can install Nx globally with these commands:

```shell
brew install nx
```

{% /tabitem %}
{% tabitem label="Node" %}

If you have [Node installed](https://nodejs.org/en/download), you can install Nx globally with this command:

```shell
npm install --global nx
```

{% /tabitem %}
{% /tabs %}

## Usage

You can install Nx in the `.nx/installation` directory of your repository by running `nx init` in a directory without a `package.json` file.

```shell
nx init
```

When Nx is installed in `.nx`, you can run Nx via a global Nx installation or the nx and nx.bat scripts that were created. In either case, the wrapper (.nx/nxw.js) will be invoked and ensure that the current workspace is up to date prior to invoking Nx.

{% tabs %}
{% tabitem label="Global Install" %}

```shell
nx build my-project
nx generate application
nx graph
```

{% /tabitem %}
{% tabitem label="nx shell script" %}

```shell
./nx build my-project
./nx generate application
./nx graph
```

{% /tabitem %}
{% tabitem label="nx.bat" %}

```shell
./nx.bat build my-project
./nx.bat generate application
./nx.bat graph
```

{% /tabitem %}
{% /tabs %}

---
<!-- source: https://nx.dev/docs/guides/installation/update-global-installation.md -->
## Update Your Global Nx Installation

There are some cases where an issue could arise when using an outdated global installation of Nx. If the structure of your Nx workspace no longer matches up with what the globally installed copy of Nx expects, it may fail to hand off to your local installation properly and instead error. This commonly results in errors such as:

- `Could not find Nx modules in this workspace.`
- `The current directory isn't part of an Nx workspace.`

If you find yourself in this position, you will need to update your global installation of Nx.

In most cases, you can update a globally installed npm package by rerunning the command you used to install it.

If you cannot remember which package manager you installed Nx globally with or are still encountering issues, you can locate other installations of Nx with these commands:

{% tabs syncKey="install-type" %}
{% tabitem label="npm" %}

```shell
npm list --global nx
```

{% /tabitem %}
{% tabitem label="yarn" %}

**yarn 2+**

```shell
yarn dlx list nx
```

yarn 1.x

```shell
yarn global list nx
```

{% /tabitem %}
{% tabitem label="pnpm" %}

```shell
pnpm list --global nx
```

{% /tabitem %}
{% /tabs %}

You can then remove the extra global installations by running the following commands for the duplicate installations:

{% tabs syncKey="install-type" %}
{% tabitem label="npm" %}

```shell
npm rm --global nx
```

{% /tabitem %}
{% tabitem label="yarn" %}

```shell
yarn global remove nx
```

{% /tabitem %}
{% tabitem label="pnpm" %}

```shell
pnpm rm --global nx
```

{% /tabitem %}
{% /tabs %}

Finally, to complete your global installation update, simply reinstall it as described [above](#update-your-global-nx-installation).

---
<!-- source: https://nx.dev/docs/guides/nx-cloud.md -->
## Nx Cloud Guides

{% index_page_cards path="guides/nx-cloud" /%}

---
<!-- source: https://nx.dev/docs/guides/nx-cloud/access-tokens.md -->
## Nx CLI and CI Access Tokens

{% youtube src="https://youtu.be/vBokLJ_F8qs" title="Configure CI access tokens" /%}

The permissions and membership define what developers can access on [nx.app](https://cloud.nx.app?utm_source=nx.dev&utm_medium=docs&utm_campaign=nx-cloud-security), but they don't affect what happens when you run Nx commands in CI. To manage that, you need to provision CI access tokens in your workspace settings, under the `Access Control` tab.
Learn more about [cache security best practices](/docs/concepts/ci-concepts/cache-security).

![Access Control Settings Page](../../../../assets/nx-cloud/access-control-settings.avif)

## Access types

{% aside type="caution" title="Use Caution With Read-Write Tokens" %}
The `read-write` tokens allow full write access to your remote cache. They should only be used in trusted environments.
{% /aside %}

There are currently two (2) types of CI Access Token for Nx Cloud's runner that you can use with your workspace. Both support distributed task execution and allow Nx Cloud to store metadata about runs.

- `read-only`
- `read-write`

### Read only access

The `read-only` access tokens can only read from the global remote cache. Task results produced with this type of access token will be stored in an isolated remote cache accessible _only_ by that specific branch in a CI context, and cannot influence the global shared cache.  
The isolated remote cache produced with a `read-only` token is accessible to all machines or agents in the same CI execution, enabling cache sharing during distributed task execution.

### Read & write access

The `read-write` access tokens allow task results to be stored in the remote cache for other machines or CI pipelines to download and replay. This access level should only be used for trusted environments such as protected branches within your CI Pipeline.

## Setting CI access tokens

You can configure an access token in CI by setting the `NX_CLOUD_ACCESS_TOKEN` environment variable.

The `NX_CLOUD_ACCESS_TOKEN` takes precedence over any authentication method in your `nx.json`.

We recommend setting up a `read-write` token for you protected branches in CI and a `read-only` token for unprotected branches. You can leverage your CI provider's environment variables management to accomplish this.

### Azure DevOps

Azure DevOps provides various [mechanisms to limit access to secrets](https://learn.microsoft.com/en-us/azure/devops/pipelines/security/secrets?view=azure-devops#limit-access-to-secret-variables). We'll be using _Variable groups_ in this process, but you can achieve the same result leveraging [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/general/overview).

1. In your project, navigate to Pipelines > Library.
   ![Variable group settings page](../../../../assets/nx-cloud/ado-library-start.avif)
2. Create a new _Variable group_ called _protected_.
   - If you already have a variable group for protected environments, we recommend reusing that variable group.
3. Add the `NX_CLOUD_ACCESS_TOKEN` environment variable with the `read-write` token from Nx Cloud.
   ![create protected variable group](../../../../assets/nx-cloud/ado-protected-var-group.avif)
4. In _Pipeline permissions_, add your current pipeline configuration.
   ![variable group pipeline permission settings](../../../../assets/nx-cloud/ado-pipeline-permission.avif)
5. In _Approvals and checks_, add a new _Branch control_ check.
   ![variable group branch control settings](../../../../assets/nx-cloud/ado-add-branch-control.avif)
6. Create the _Branch control_ check with only allowing your protected branches and checking _Verify branch protection_ option.
   ![variable group branch control settings](../../../../assets/nx-cloud/ado-protected-branch.avif)
7. Create another variable group called _unprotected_.
8. Add the `NX_CLOUD_ACCESS_TOKEN` environment variable with the `read-only` token from Nx Cloud.
9. In _Pipeline permissions_, add your current pipeline configuration.
10. In _Approvals and checks_, add a new _Branch control_ check with the `*` wildcard for branches and leaving _Verify branch protection_ unchecked.
    ![unprotected variable group settings](../../../../assets/nx-cloud/ado-unprotected-branch.avif)
11. Now you should see 2 _Variable groups_ for _protected_ and _unprotected_ usage.
    ![completed variable group setup](../../../../assets/nx-cloud/ado-library-end.avif)
12. Update your pipeline to include the 2 variable groups, with conditional access for the _protected_ variable group.

Example usage:

```yaml {% meta="{3-5}" %}
// azure-pipelines.yml
variables:
  - group: unprotected
  - ${{ if eq(variables['Build.SourceBranchName'], 'main') }}:
      - group: protected
```

{% aside type="tip" title="Can't someone change the variable group?" %}
Since we use the _Verify branch protection_ option, CI can only read the variable when running in a protected branch. If a developer tries to edit the pipeline to use the _protected_ variable group, the pipeline will error out since permissions require running in on a protected branch.

Take caution though, if you allow team members to have direct write access to a protected branch, then they could modify the pipeline to write to the nx cache without having a code review first.
{% /aside %}

### BitBucket Cloud

BitBucket Cloud supports setting environment variables per environment called _Deployment variables_. You can read the [official BitBucket Pipelines documentation](https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/#Deployment-variables) for more details.

1. In your repository, navigate to the _Repository settings_ > _Deployment_.
2. Select an environment you have configured for protected branches, or create a new one and protect your primary branches.
   - Note: selecting branch protection rules is a premium feature of BitBucket Cloud.
     ![Use deployments variables to provide protected environment variable access](../../../../assets/nx-cloud/bitbucket-deployment-env.avif)
3. Set the environment variable `NX_CLOUD_ACCESS_TOKEN` with the `read-write` token from Nx Cloud.
4. Navigate to the _Repository settings_ > _Repository variables_ tab and set the variable `NX_CLOUD_ACCESS_TOKEN` with the `read-only` token from Nx Cloud.
   ![add read-only Nx Cloud access token to bitbucket](../../../../assets/nx-cloud/bitbucket-repo-vars.avif)
5. Update the `bitbucket-pipelines.yml` file to include the deployment name mentioned in step 2.

Example usage:

```yaml {% meta="{7}" %}
// bitbucket-pipelines.yml
pipelines:
  branches:
    main:
      - step:
          name: 'main checks'
          deployment: Production
          ...
```

### CircleCI

Circle CI allows creating _contexts_ and restricting those based on various rules. You can read the [official CircleCI documentation](https://circleci.com/docs/contexts/#restrict-a-context) for more details.

1. In your organization, navigate to _Organization settings_ > _Contexts_ and create a new context.
   - If you already have a context for protected environments, we recommend reusing that context.
     ![create a new context for protected environments](../../../../assets/nx-cloud/circle-new-context.avif)
2. Click on _Add Expression Restriction_ that restricts the context to protected branches only such as only the `main` branch, e.g., `pipeline.git.branch == "main"`.
   ![restrict context to protected branches](../../../../assets/nx-cloud/circle-expression-restriction.avif)
3. Click on _Add Environment Variable_ and add the `NX_CLOUD_ACCESS_TOKEN` environment variable with the `read-write` token from Nx Cloud.
4. Back on the organization home page, navigate to your projects, then view the pipeline settings.
5. Navigate to _Environment Variables_ and click _Add Environment Variable_ and add the `NX_CLOUD_ACCESS_TOKEN` environment variable with the `read-only` token from Nx Cloud.
   ![add read-only Nx Cloud access token to circleci](../../../../assets/nx-cloud/circle-new-env-var-token.avif)
6. Update your pipeline to include steps where you want to write to the nx cache with the correct contexts.

Example usage:

```yaml {% meta="{11-20}" %}
// .circleci/config.yml
jobs:
  run-tests-protected:
    - ...
  run-tests-prs:
    - ...

workflows:
  my-workflow:
    jobs:
      - run-tests-protected:
          context:
            - protected-branches
          filters:
            branches:
              only: main
      - run-tests-prs:
          filters:
            branches:
              ignore: main
```

### GitHub Actions

GitHub allows specifying different secrets for each environment, where an environment can be on a specific branch.
You can read the [official GitHub Actions documentation](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-an-environment) for more details.

1. In your repository, navigate to Settings tab.
2. Click on "Environments" and create an environment for your protected branches.
   - Typically, organizations already have some kind of 'release' or 'protected' environments that can be leveraged.
   - If you do not have any protected branches, it's recommended to make at least your _default_ branch a protected branch i.e., `main`/`master`.
3. Add a restriction for how the environment will be applied, and apply to all protected branches.
   ![Select protected branches for the environment restriction configuration](../../../../assets/nx-cloud/github-select-protected-branches.avif)
4. Add the `read-write` access token with the name `NX_CLOUD_ACCESS_TOKEN` to your environment.
5. Click the _Secrets and variables_ > _Actions_ tab in the sidebar.
6. Add the `read-only` access token with the name `NX_CLOUD_ACCESS_TOKEN` to the repository secrets.
7. Now you should see 2 secrets where 1 is a part of the protected environment and the other is the default repository secrets.
   ![overview of GitHub Action secret configuration settings with environments set](../../../../assets/nx-cloud/github-secrets-settings.avif)

Example usage:

```yaml {% meta="{4-5}" %}
// .github/workflows/ci.yml
name: CI

env:
  NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}

jobs:
  main:
    runs-on: ubuntu-latest
    steps: ...
```

### GitLab

GitLab allows creating variables scoped to specific environments. You can read the [Official GitLab documentation](https://docs.gitlab.com/ci/environments/#limit-the-environment-scope-of-a-cicd-variable) for more details.

1. In your project, navigate to _Operate_ > _Environments_ and create a new environment. You do not need to fill out the External Url or GitLab agent.
   - Most projects already have a production/protected environments, so we recommend using this one if it's already defined.
     ![define gitlab environment for protected branches](../../../../assets/nx-cloud/gitlab-new-environment.avif)
2. In your project, navigate to _Settings_ > _CI/CD_ tab and expand the _Variables_ section.
3. Click on _Add variable_ and fill in the following information:
   - Type: _Variable_
   - Environments: _All_
   - Visibility: _Masked and hidden_
   - Flags: uncheck _Protected variable_
   - Description: "read-only token for nx-cloud"
   - Key: `NX_CLOUD_ACCESS_TOKEN`
   - Value: Your `read-only` token from Nx Cloud
4. Click _Add variable_.
   ![add read-only Nx Cloud access token to gitlab](../../../../assets/nx-cloud/gitlab-variable-settings-readonly.avif)
5. Click on _Add variable_ again and fill in the following information:
   - Type: _Variable_
   - Environments: Your protected environment created in step 1
   - Visibility: _Masked and hidden_
   - Flags: check _Protected variable_
   - Description: "read-write token for nx-cloud"
   - Key: `NX_CLOUD_ACCESS_TOKEN`
   - Value: Your `read-write` token from Nx Cloud
6. Click _Add variable_.
   ![add read-write Nx Cloud access token to gitlab](../../../../assets/nx-cloud/gitlab-variable-settings-readwrite.avif)
7. Now you should see 2 secrets where 1 is a part of the protected & tagged to the environment and the other is not.
   ![GitLab project variable configuration screen](../../../../assets/nx-cloud/gitlab-variable-setting.avif)
8. Update your pipeline to include steps where you want to write to the nx cache with the correct contexts.

Example usage:

```yaml {% meta="{3-4}" %}
// .gitlab-ci.yml
<job-name>:
  environment:
    name: <environment-name>
```

{% aside type="tip" title="Can't someone change the step environment?" %}
Since we use the _Protected variable_ flag, CI can only read the variable when running in a protected branch. If a developer tries to edit the steps to run a PR in the environment with the `read-write` token will, then the token will not be populated in CI since their branch is not marked as protected.

Take caution though, if you allow team members to have direct write access to a protected branch, then they could modify the steps to write to the nx cache without having a code review first.
{% /aside %}

### Jenkins

Jenkins configuration can be quite extensive making each Jenkins instance unique. Because of this we can only provide a minimal viable approach, but there can be multiple ways to provide scoped access tokens to your pipelines. The goal is to create two areas within Jenkins, where one is the _protected_ and the other is the _unprotected_. These specifically map to how you deem your branches should have read/write vs read permissions. We recommend making branches that developers cannot directly push to and require a code review to merge to, as the _protected_ branches, and the rest being _unprotected_.

1. Minimally, this can be achieved via the following Jenkins plugins:
   - [Folders](https://plugins.jenkins.io/cloudbees-folder/), [Credentials](https://plugins.jenkins.io/credentials/), [Credentials Binding](https://plugins.jenkins.io/credentials-binding/)
2. Create a folder for the _unprotected_ and _protected_ pipelines.
   - The names can be anything that makes sense for your organization, such as _releases_ or _PRs_ etc.
3. Go into the _unprotected_ folder and create a credential for `NX_CLOUD_ACCESS_TOKEN` with the `read-only` token from Nx Cloud.
4. Go into the _protected_ folder and create a credential for `NX_CLOUD_ACCESS_TOKEN` with the `read-write` token from Nx Cloud.
5. Use the credential inside your pipeline `Jenkinsfile` with the Credential Binding plugin.

Example usage:

```groovy {% meta="{7-8}" %}
// Jenkinsfile
pipeline {
  agent any
  stages {
    stage('Build') {
      steps {
        withCredentials([string(credentialsId: 'NX_CLOUD_ACCESS_TOKEN', variable: 'NX_CLOUD_ACCESS_TOKEN')]) {
          sh 'echo "Nx Cloud access token is now set in this context"'
        }
      }
    }
  }
}
```

### Legacy methods of setting CI access tokens

#### Using CI access tokens in nx.json

We **do not recommend** that you commit an access token to your repository but older versions of Nx do support this and if you open your `nx.json`, you may see something like this:

{% tabs %}
{% tabitem label="Nx >= 17" %}

```json
{
  "nxCloudAccessToken": "SOMETOKEN"
}
```

{% /tabitem %}
{% tabitem label="Nx < 17" %}

```json
{
  "tasksRunnerOptions": {
    "default": {
      "runner": "nx-cloud",
      "options": {
        "accessToken": "SOMETOKEN"
      }
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

{% aside type="caution" title="Nx Cloud authentication is changing" %}
From Nx 19.7 new workspaces are connected to Nx Cloud with a property called `nxCloudId` instead, and we recommend developers use [`nx login`](/docs/reference/nx-cloud-cli#npx-nxcloud-login) to provision their own local [personal access tokens](/docs/guides/nx-cloud/personal-access-tokens) for user based authentication.
{% /aside %}

#### Using `nx-cloud.env`

You can set an environment variable locally via the `nx-cloud.env` file. Nx Cloud CLI will look in this file to load custom configuration like `NX_CLOUD_ACCESS_TOKEN`. These environment variables will take precedence over the configuration in `nx.json`.

---
<!-- source: https://nx.dev/docs/guides/nx-cloud/ci-resource-usage.md -->
## Track CI Resource Usage

Nx Cloud tracks CPU and memory usage for each task in your CI pipeline. Use this data to find resource bottlenecks, debug out-of-memory errors, and pick the right agent size for your workload.

{% aside type="note" title="Requirements" %}
Requires Nx 22.1 or higher.

The CI resource usage feature with Nx Cloud requires an [Enterprise plan](https://nx.dev/enterprise?utm_source=nx.dev&utm_medium=documentation-guide&utm_campaign=nx-cloud-task-metrics).
{% /aside %}

## Resource usage with Nx Agents

With [Nx Agents](/docs/features/ci-features/distribute-task-execution), resource metrics are collected automatically. You can view this data in the Nx Cloud dashboard for any CI pipeline execution.

### Viewing the analysis summary

Open any CI pipeline execution in Nx Cloud and go to the analysis section. You'll see a list of agents used for the run, along with:

- Average and maximum CPU usage
- Average and maximum memory usage
- Machine specs for that resource class

This gives you a quick look at how resources were used across all agents.

![Resource usage summary showing agents with CPU and memory stats](../../../../assets/guides/nx-cloud/agent-resource-usage-table.png)

### Viewing usage details

Click on any agent to see a breakdown of resource usage over time. The detail view shows:

- Memory usage by process
- CPU usage by process
- Resource consumption for each task
- Nx CLI overhead

This view helps you find exactly which task is using the most resources, not just that "something" in your pipeline is the problem.

![Resource usage details showing memory and CPU by process](../../../../assets/guides/nx-cloud/resource-chart-details.png)

### Using the detail view

The detail view has a few features to help you dig into resource usage:

- **Legend**: Click items in the legend to focus on specific tasks or processes
  ![Using the legend to focus on specific tasks](../../../../assets/guides/nx-cloud/resource-chart-legend.png)

- **Timeline scrubber**: Use the scrubber at the bottom to jump to specific points in time or zoom in on peak usage
  ![Timeline scrubber for navigating resource usage over time](../../../../assets/guides/nx-cloud/resource-chart-scrubber.jpg)

- **View modes**: Switch between "stacked" view (total usage at any time) and "individual" view (each process separately)
  ![Stacked view showing total resource usage](../../../../assets/guides/nx-cloud/resource-stacked-chart-view.png)

- **CSV export**: Download the raw data if you need to dig into sub-process details

## Common use cases

- **Finding memory-hungry tasks**: Figure out which project eats the most memory when running tasks in parallel. You can then run just that project with lower parallelism instead of slowing down everything.
- **Spotting misconfigured tooling**: See when a bundler or build tool is pulling in more files than it should.
- **Debugging E2E bottlenecks**: Find out if the slow part is the tests themselves or something in the dependency chain.
- **Comparing before and after upgrades**: Check if a dependency upgrade caused a spike in resource usage.
- **Detecting memory leaks**: Look for tasks where memory keeps climbing over time.
- **Picking the right resource class**: Figure out the right agent size when moving to Nx Agents from GitHub Actions or other CI providers.

## Manual metrics upload

If you're running your own CI runners instead of Nx Agents, you can still collect resource metrics and upload them to Nx Cloud.

### How it works

Nx writes resource metrics to a local directory during task execution. To view this data in Nx Cloud:

1. Save the metrics directory as a CI artifact
2. Download the artifact after the run finishes
3. Upload the metrics file in the Nx Cloud analysis screen

### Configuration

Metrics collection is currently on by default for enterprise users with Nx version 22.1 or higher. To disable it, set the `NX_CLOUD_DISABLE_METRICS_COLLECTION` environment variable:

```shell
export NX_CLOUD_DISABLE_METRICS_COLLECTION=true
```

Metrics are written to the local Nx cache directory by default (`.nx/cache/metrics` unless manually overridden). You can change this directory by setting the `NX_CLOUD_METRICS_DIRECTORY` environment variable.

```shell
export NX_CLOUD_METRICS_DIRECTORY=/path/to/metrics
```

### Saving metrics as CI artifacts

Set up your CI to save the metrics directory as an artifact so you can download it later. The following examples assume that the default cache directory (`.nx/cache/metrics`) is used. If you overwrite the metrics directory, adjust the paths in the artifact upload step accordingly.

{% tabs syncKey="ci-provider" %}
{% tabitem label="GitHub Actions" %}

```yaml
# .github/workflows/ci.yml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npx nx affected -t build test lint
      - name: Upload metrics artifact
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: nx-metrics
          path: ${{ github.workspace }}/.nx/cache/metrics
```

{% /tabitem %}
{% tabitem label="GitLab CI" %}

```yaml
# .gitlab-ci.yml
build:
  script:
    - npm ci
    - npx nx affected -t build test lint
  artifacts:
    paths:
      - .nx/cache/metrics
    when: always
```

{% /tabitem %}
{% tabitem label="CircleCI" %}

```yaml
# .circleci/config.yml
jobs:
  build:
    docker:
      - image: cimg/node:lts
    steps:
      - checkout
      - run: npm ci
      - run: npx nx affected -t build test lint
      - store_artifacts:
          path: .nx/cache/metrics
          destination: nx-metrics
```

{% /tabitem %}
{% /tabs %}

### Uploading metrics to Nx Cloud

Once your CI run finishes, download the metrics artifact from your CI provider. Then go to the CI pipeline execution in Nx Cloud, open the analysis screen, and upload the metrics file.

![Manual upload interface in the Nx Cloud analysis screen](../../../../assets/guides/nx-cloud/resource-usage-manual-upload.png)

---
<!-- source: https://nx.dev/docs/guides/nx-cloud/cipe-affected-project-graph.md -->
## Reduce the Number of Affected Projects in a CI Pipeline Execution

When it comes to troubleshooting long-running CI pipeline executions, there are different tools available to help you identify the potential issues. One such tool is the **Affected Project Graph** feature on the CI Pipeline Execution page.

## Getting to the CI pipeline execution affected project graph

To access the affected project graph for the CI pipeline execution, navigate to the CI pipeline execution details page and click on the **Affected Project Graph** navigation item.

![CIPE Affected Project Graph](../../../../assets/nx-cloud/cipe-affected-project-graph-nav-item.png)

The affected project graph visualizes the projects that are part of the **current** CI pipeline execution.

## Identifying a potential over-run of a CI pipeline execution

In this recipe, a scenario where the affected project graph can be used to identify a potential over-run of a CI pipeline execution.

This is our repository structure:

{% filetree %}

- apps/
  - web/
  - web-e2e
  - nx-graph-test/
  - nx-graph-test-e2e/
  - recipes/
    - client/
    - client-e2e/
- libs/
  - ui/ (button and icon components)
  - forms/
    - input/
  - tooltip/

{% /filetree %}

Our most recent CI pipeline execution affects everything in the repository.

![CIPE Affected Project Graph -- every tasks](../../../../assets/nx-cloud/cipe-affected-project-graph-every-tasks.png)

Likewise, the affected project graph for the Ci pipeline execution also visualizes all projects because everything is affected.

![CIPE Affected Project Graph -- affect everything](../../../../assets/nx-cloud/cipe-affected-project-graph-every-projects.png)

## Create a new CI pipeline execution with a code change

Our `ui` library has 2 components: `button` and `tooltip`. From the graph, we can see that both our apps `client` and `web` depend on the `ui` library: `client` uses the `tooltip` component and `web` uses the `button` component.

Let's make an update to the `tooltip` component and see how it affects our next CI pipeline execution. Pushing this change to our repository will trigger a new CI pipeline execution.

![CIPE Affected Project Graph -- new CIPE](../../../../assets/nx-cloud/cipe-affected-project-graph-tooltip-tasks.png)

This CI pipeline execution contains 14 tasks that are affected by the change we made to the `tooltip` component.

![CIPE Affected Project Graph -- new CIPE tasks](../../../../assets/nx-cloud/cipe-affected-project-graph-tooltip-affected.png)

The affected project graph also shows that the change to `tooltip` component , which is part of the `ui` library, affects both the `client` and `web` apps.

At this point, we can ask ourselves that "Should a change to the `tooltip` component affect both the `client` and `web` apps or should it only affect the `web` app?" Our goal should be to always have the most efficient CI pipeline executions possible. Decreasing the number of affected projects will allow the number of tasks to be reduced, which will reduce the overall CI pipeline execution time.

## Break up the source of the affected projects

To achieve our goal, we can break up the `ui` library into 2 separate libraries: `button` and `tooltip`.

> Check out our [blog post](https://nx.dev/blog/improve-architecture-and-ci-times-with-projects) about splitting large projects into smaller ones.

Once we have done this, we will end up with the following project graph:

![CIPE Affected Project Graph -- break up ui](../../../../assets/nx-cloud/cipe-affected-project-graph-break-up-ui.png)

Let's make a change to the `button` component this time and see how it affects our next CI pipeline execution.

![CIPE Affected Project Graph -- button tasks](../../../../assets/nx-cloud/cipe-affected-project-graph-button-tasks.png)

We've reduced the number of affected tasks from 14 to 8.

![CIPE Affected Project Graph -- button affected](../../../../assets/nx-cloud/cipe-affected-project-graph-button-affected.png)

And the affected project graph also reflects that change properly.

{% aside type="tip" %}
**Does your Affected Project Graph only show affected projects and not touched?**

- If your commit has changes to one of the global inputs, your projects will be affected but no specific project is touched directly.
- Make sure you are calling `start-ci-run` to start using Nx Agents for touched projects to be recorded. Learn more about [Nx Agents](/docs/features/ci-features/distribute-task-execution)

{% /aside %}

---
<!-- source: https://nx.dev/docs/guides/nx-cloud/enable-ai-features.md -->
## Enable AI Features

This guide walks you through enabling AI features in Nx Cloud for both cloud-hosted and on-prem installations.

## Nx Cloud hosted setup

To enable AI features for your organization, go to [your organization's settings](https://cloud.nx.app/go/organization/edit) on Nx Cloud and select the organization where you want to enable AI.

In the **settings** menu, find the "AI Features" section and toggle it to "On".

![enable ai features](../../../../assets/features/ci-features/ai-features.avif)

Ensure that you **accept the AI terms** to start using the AI features.

{% aside type="note" title="AI Features Availability" %}

AI features are available on Hobby, Team and Enterprise [Nx Cloud plans](https://nx.dev/pricing).

{% /aside %}

## Self-healing CI for enterprise on-prem installations

To enable Self-Healing CI for enterprise on-prem installations, follow these steps:

### Setup

Add the following configuration to your `helm-values.yaml` file:

```yaml
nxApi
  deployment:
    env:
      - name: NX_CLOUD_AI_ENABLED
        value: 'true'
      - name: NX_CLOUD_AI_TOKEN_PROVIDER_TYPE
        value: 'fixed'
      - name: NX_CLOUD_ANTHROPIC_API_KEY
        value: 'sk-ant-...'

frontend
  deployment:
    env:
      - name: NX_CLOUD_AI_ENABLED
        value: 'true'
```

Then, enable AI features in the [organization settings](https://cloud.nx.app/go/organization/edit) and enable Self-Healing CI in the [workspace settings](https://cloud.nx.app/go/workspace/settings).

### Running self-healing CI on-prem

#### Automatic DTE agents

If using DTE agents, the self-healing CI step will be automatically added when the setting is enabled in the workspace settings.

#### Manual DTE

For manual DTE configurations, the `nx fix-ci` command must be included in the agent configuration after running nx tasks.

**Important:** This command must run **always**, meaning that even when previous nx tasks fail, the `fix-ci` command should still execute.

#### Non-DTE

For non-DTE setups, refer to the [Self-Healing CI documentation](/docs/features/ci-features/self-healing-ci) for detailed configuration instructions.

## Regional availability

AI features are not available for the EU cluster in public cloud installations due to regional restrictions. However, on-prem customers in the EU can still use these features by providing their own Anthropic API key (for Self-Healing CI) and enabling the required environment variables.

---
<!-- source: https://nx.dev/docs/guides/nx-cloud/encryption.md -->
## Enable End to End Encryption

To turn on end to end encryption, specify an encryption key in one of two ways:

- Set the `nxCloudEncryptionKey` property in `nx.json`
- Set the `NX_CLOUD_ENCRYPTION_KEY` environment variable

The key can be any string up to 32 characters long.

Providing an encryption key tells Nx to encrypt task artifacts on your machine before they are sent to the remote cache. Then when cached results are downloaded to your machine they are decrypted before they are used. This ensures that even if someone gained access to the Nx Cloud servers, they wouldn't be able to view your task artifacts.

## Metadata

All the artifacts Nx Cloud uses to replay a task for you are encrypted. That means that even if someone gets access to your Nx Cloud storage bucket, they will not be able to tamper with the files and terminal output that is restored when the task is replayed on your CI or developer's machines.

We also store an un-encrypted version of the terminal output separately that is accessible only to invited members of the workspace on the Nx Cloud web app, so they can see why certain tasks failed. This un-encrypted output is only used in the browser, and not used when replaying the task.

## Summary

Data is encrypted both at rest and in transit.

- Every communication with the Nx Cloud API is encrypted in transit, including fetching/storing artifacts.
- When using Nx Public Cloud, the stored metadata is encrypted.
- When using Nx Public Cloud and e2e encryption, stored artifacts are encrypted.
- When using the on-prem version of Nx Cloud, the stored metadata is encrypted if you run MongoDB yourself with encryption on
- When using the on-prem version of Nx Cloud, stored artifacts are encrypted using e2e encryption.

---
<!-- source: https://nx.dev/docs/guides/nx-cloud/google-auth.md -->
## Connecting Nx Cloud to your existing Google identity provider

If your organization uses [Google Identity](https://cloud.google.com/identity) or [Google Workspaces](https://workspace.google.com/intl/en_uk/) to manage employee accounts and permissions, your Nx Cloud workspace members can re-use the same accounts to sign-in to Nx Cloud and view runs, cache stats etc. Besides being more convenient for the employee, as they don't have to sign-in again, it also has a security benefit: if an employee leaves the company and their Google account is disabled, they won't be able to sign-in to Nx Cloud anymore.

By default, when you invite a member by email, they can create a separate Nx Cloud account using their work e-mail address. **If their primary email address gets disabled, they will still be able to sign-in with their Nx Cloud account, unless you explicitly revoke their membership from the Members page.**

If you'd like them to sign-in with Google directly, which ensures they automatically lose access to their Nx Cloud account if their email gets disabled, you need to enable this option when inviting them: "_Require Social OAuth Sign-In_". They will then only be able to accept the invite if they sign-in with Google directly.

![Require Google OAuth Sign-In toggle](../../../../assets/nx-cloud/require-google-signin.webp)

## SAML integration

Direct integration with SAML identity providers is a feature of [Nx Enterprise](https://nx.dev/enterprise). You can, however, connect your existing SAML provider to Google, and then use the method above to invite employees:

- [Azure AD](https://docs.microsoft.com/en-us/azure/active-directory/saas-apps/google-apps-tutorial)
- [Okta](https://www.okta.com/integrations/google-workspace/#overview)

---
<!-- source: https://nx.dev/docs/guides/nx-cloud/manual-dte.md -->
## Manual Distributed Task Execution

Using [Nx Agents](/docs/features/ci-features/distribute-task-execution) is the easiest way to distribute task execution, but your organization may not be able to use hosted Nx Agents. You can set up distributed task execution on your own CI provider using the recipes below.

{% tabs syncKey="ci-provider" %}

{% tabitem label="GitHub" %}

Our [reusable GitHub workflow](https://github.com/nrwl/ci) represents a good set of defaults that works for a large number of our users. However, reusable GitHub workflows come with their [limitations](https://docs.github.com/en/actions/using-workflows/reusing-workflows).

If the reusable workflow above doesn't satisfy your needs you should create a custom workflow. If you were to rewrite the reusable workflow yourself, it would look something like this:

```yaml
// .github/workflows/ci.yml
name: CI
on:
  push:
    branches:
      - main
  pull_request:

# Needed for nx-set-shas when run on the main branch
permissions:
  actions: read
  contents: read

env:
  NX_CLOUD_DISTRIBUTED_EXECUTION: true # this enables DTE
  NX_BRANCH: ${{ github.event.number || github.ref_name }}
  NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
  NPM_TOKEN: ${{ secrets.NPM_TOKEN }} # this is needed if our pipeline publishes to npm

jobs:
  main:
    name: Nx Cloud - Main Job
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          # We need to fetch all branches and commits so that Nx affected has a base to compare against.
          fetch-depth: 0
          filter: tree:0

      # Set node/npm/yarn versions using volta
      - uses: volta-cli/action@v4
        with:
          package-json-path: '${{ github.workspace }}/package.json'

      - name: Use the package manager cache if available
        uses: actions/setup-node@v3
        with:
          node-version: 20
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Derive appropriate SHAs for base and head for `nx affected` commands
        uses: nrwl/nx-set-shas@v4

      - name: Initialize the Nx Cloud distributed CI run and stop agents when the build tasks are done
        run: npx nx start-ci-run --distribute-on="manual" --stop-agents-after=e2e-ci

      - name: Check the formatting
        run: npx nx record -- nx format:check

      - name: Lint, test, build, and run e2e
        run: npx nx affected -t lint,test,build,e2e-ci --configuration=ci

      # Self-Healing CI: recommend fixes for failures. Learn more: https://nx.dev/ci/features/self-healing-ci
      - name: Self-Healing CI
        run: npx nx fix-ci
        if: always()

  agents:
    name: Agent ${{ matrix.agent }}
    runs-on: ubuntu-latest
    strategy:
      matrix:
        # Add more agents here as your repository expands
        agent: [1, 2, 3]
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      # Set node/npm/yarn versions using volta
      - uses: volta-cli/action@v4
        with:
          package-json-path: '${{ github.workspace }}/package.json'

      - name: Use the package manager cache if available
        uses: actions/setup-node@v3
        with:
          node-version: 20
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Start Nx Agent ${{ matrix.agent }}
        run: npx nx start-agent
        env:
          NX_AGENT_NAME: ${{ matrix.agent }}

      # Self-Healing CI: recommend fixes for failures. Learn more: https://nx.dev/ci/features/self-healing-ci
      - name: Self-Healing CI
        run: npx nx fix-ci
        if: always()
        env:
          NX_AGENT_NAME: ${{ matrix.agent }}
```

There are comments throughout the workflow to help you understand what is happening in each section.

{% /tabitem %}

{% tabitem label="Circle CI" %}

Run agents directly on Circle CI with the workflow below:

```yaml
// .circleci/config.yml
version: 2.1
orbs:
  nx: nrwl/nx@1.5.1
jobs:
  main:
    docker:
      - image: cimg/node:lts-browsers
    steps:
      - checkout
      - run: npm ci
      - nx/set-shas

      # Tell Nx Cloud to use DTE and stop agents when the e2e-ci tasks are done
      - run: npx nx start-ci-run --distribute-on="manual" --stop-agents-after=e2e-ci
      # Send logs to Nx Cloud for any CLI command
      - run: npx nx record -- nx format:check
      # Lint, test, build and run e2e on agent jobs for everything affected by a change
      - run: npx nx affected --base=$NX_BASE --head=$NX_HEAD -t lint,test,build,e2e-ci --parallel=2 --configuration=ci
      # Self-Healing CI: recommend fixes for failures. Learn more: https://nx.dev/ci/features/self-healing-ci
      - run: npx nx fix-ci
        when: always
  agent:
    docker:
      - image: cimg/node:lts-browsers
    parameters:
      ordinal:
        type: integer
    steps:
      - checkout
      - run: npm ci
      # Wait for instructions from Nx Cloud
      - run:
          command: npx nx start-agent
          no_output_timeout: 60m
          environment:
            NX_AGENT_NAME: << parameters.ordinal >>
      # Self-Healing CI: recommend fixes for failures. Learn more: https://nx.dev/ci/features/self-healing-ci
      - run:
          command: npx nx fix-ci
          environment:
            NX_AGENT_NAME: << parameters.ordinal >>
        when: always
workflows:
  build:
    jobs:
      - agent:
          matrix:
            parameters:
              ordinal: [1, 2, 3]
      - main
```

This configuration is setting up two types of jobs - a main job and three agent jobs.

The main job tells Nx Cloud to use DTE and then runs normal Nx commands as if this were a single pipeline set up. Once the commands are done, it notifies Nx Cloud to stop the agent jobs.

The agent jobs set up the repo and then wait for Nx Cloud to assign them tasks.

{% /tabitem %}

{% tabitem label="Azure" %}

Run agents directly on Azure Pipelines with the workflow below:

```yaml
// azure-pipelines.yml
trigger:
  - main
pr:
  - main

variables:
  CI: 'true'
  ${{ if eq(variables['Build.Reason'], 'PullRequest') }}:
    NX_BRANCH: $(System.PullRequest.PullRequestNumber)
    TARGET_BRANCH: $[replace(variables['System.PullRequest.TargetBranch'],'refs/heads/','origin/')]
    BASE_SHA: $(git merge-base $(TARGET_BRANCH) HEAD)
  ${{ if ne(variables['Build.Reason'], 'PullRequest') }}:
    NX_BRANCH: $(Build.SourceBranchName)
    BASE_SHA: $(git rev-parse HEAD~1)
  HEAD_SHA: $(git rev-parse HEAD)

jobs:
  - job: agents
    strategy:
      parallel: 3
    displayName: Nx Cloud Agent
    pool:
      vmImage: 'ubuntu-latest'
    steps:
      - checkout: self
        fetchDepth: '0'
        fetchFilter: tree:0
        persistCredentials: true

      - script: npm ci
      - script: npx nx start-agent
        env:
          NX_AGENT_NAME: $(System.JobPositionInPhase)

      # Self-Healing CI: recommend fixes for failures. Learn more: https://nx.dev/ci/features/self-healing-ci
      - script: npx nx fix-ci
        condition: always()
        env:
          NX_AGENT_NAME: $(System.JobPositionInPhase)

  - job: main
    displayName: Nx Cloud Main
    pool:
      vmImage: 'ubuntu-latest'
    steps:
      # Get last successfull commit from Azure Devops CLI
      - bash: |
          LAST_SHA=$(az pipelines build list --branch $(Build.SourceBranchName) --definition-ids $(System.DefinitionId) --result succeeded --top 1 --query "[0].triggerInfo.\"ci.sourceSha\"")
          if [ -z "$LAST_SHA" ]
          then
            echo "Last successful commit not found. Using fallback 'HEAD~1': $BASE_SHA"
          else
            echo "Last successful commit SHA: $LAST_SHA"
            echo "##vso[task.setvariable variable=BASE_SHA]$LAST_SHA"
          fi
        displayName: 'Get last successful commit SHA'
        condition: ne(variables['Build.Reason'], 'PullRequest')
        env:
          AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)

      - script: git branch --track main origin/main
      - script: npm ci
      - script: npx nx start-ci-run --distribute-on="manual" --stop-agents-after="e2e-ci"
      - script: npx nx record -- nx format:check --base=$(BASE_SHA) --head=$(HEAD_SHA)
      - script: npx nx affected --base=$(BASE_SHA) --head=$(HEAD_SHA) -t lint,test,build,e2e-ci --parallel=2 --configuration=ci

      # Self-Healing CI: recommend fixes for failures. Learn more: https://nx.dev/ci/features/self-healing-ci
      - script: npx nx fix-ci
        condition: always()
```

This configuration is setting up two types of jobs - a main job and three agent jobs.

The main job tells Nx Cloud to use DTE and then runs normal Nx commands as if this were a single pipeline set up. Once the commands are done, it notifies Nx Cloud to stop the agent jobs.

The agent jobs set up the repo and then wait for Nx Cloud to assign them tasks.

{% /tabitem %}

{% tabitem label="Bitbucket" %}

Run agents directly on Bitbucket Pipelines with the workflow below:

```yaml
// bitbucket-pipelines.yml
image: node:20

clone:
  depth: full

definitions:
  steps:
    - step: &agent
        name: Agent
        script:
          - export NX_BRANCH=$BITBUCKET_PR_ID
          - export NX_AGENT_NAME=$BITBUCKET_STEP_UUID

          - npm ci
          - npx nx start-agent
        after-script:
          # Self-Healing CI: recommend fixes for failures. Learn more: https://nx.dev/ci/features/self-healing-ci
          - export NX_AGENT_NAME=$BITBUCKET_STEP_UUID
          - npx nx fix-ci

pipelines:
  pull-requests:
    '**':
      - parallel:
          - step:
              name: CI
              script:
                - export NX_BRANCH=$BITBUCKET_PR_ID

                - npm ci
                - npx nx start-ci-run --distribute-on="manual" --stop-agents-after="e2e-ci"
                - npx nx record -- nx format:check
                - npx nx affected --target=lint,test,build,e2e-ci --parallel=2
              after-script:
                # Self-Healing CI: recommend fixes for failures. Learn more: https://nx.dev/ci/features/self-healing-ci
                - npx nx fix-ci
          - step: *agent
          - step: *agent
          - step: *agent
```

This configuration is setting up two types of jobs - a main job and three agent jobs.

The main job tells Nx Cloud to use DTE and then runs normal Nx commands as if this were a single pipeline set up. Once the commands are done, it notifies Nx Cloud to stop the agent jobs.

The agent jobs set up the repo and then wait for Nx Cloud to assign them tasks.

{% /tabitem %}

{% tabitem label="GitLab" %}

Run agents directly on GitLab with the workflow below:

```yaml
// .gitlab-ci.yml
image: node:18

# Creating template for DTE agents
.dte-agent:
  interruptible: true
  cache:
    key:
      files:
        - yarn.lock
    paths:
      - '.yarn-cache/'
  script:
    - yarn install --cache-folder .yarn-cache --prefer-offline --frozen-lockfile
    - export NX_AGENT_NAME=$CI_JOB_ID
    - yarn nx start-agent
  # Self-Healing CI: recommend fixes for failures. Learn more: https://nx.dev/ci/features/self-healing-ci
  after_script:
    - export NX_AGENT_NAME=$CI_JOB_ID
    - yarn nx fix-ci

# Creating template for a job running DTE (orchestrator)
.base-pipeline:
  interruptible: true
  only:
    - main
    - merge_requests
  cache:
    key:
      files:
        - yarn.lock
    paths:
      - '.yarn-cache/'
  before_script:
    - yarn install --cache-folder .yarn-cache --prefer-offline --frozen-lockfile
    - NX_HEAD=$CI_COMMIT_SHA
    - NX_BASE=${CI_MERGE_REQUEST_DIFF_BASE_SHA:-$CI_COMMIT_BEFORE_SHA}

  artifacts:
    expire_in: 5 days
    paths:
      - dist

# Main job running DTE
nx-dte:
  stage: affected
  extends: .base-pipeline
  script:
    - yarn nx start-ci-run --distribute-on="manual" --stop-agents-after=e2e-ci
    - yarn nx record -- nx format:check --base=$NX_BASE --head=$NX_HEAD
    - yarn nx affected --base=$NX_BASE --head=$NX_HEAD -t lint,test,build,e2e-ci --parallel=2
  # Self-Healing CI: recommend fixes for failures. Learn more: https://nx.dev/ci/features/self-healing-ci
  after_script:
    - yarn nx fix-ci

# Create as many agents as you want
nx-dte-agent1:
  extends: .dte-agent
  stage: affected
nx-dte-agent2:
  extends: .dte-agent
  stage: affected
nx-dte-agent3:
  extends: .dte-agent
  stage: affected
```

This configuration is setting up two types of jobs - a main job and three agent jobs.

The main job tells Nx Cloud to use DTE and then runs normal Nx commands as if this were a single pipeline set up. Once the commands are done, it notifies Nx Cloud to stop the agent jobs.

The agent jobs set up the repo and then wait for Nx Cloud to assign them tasks.

{% /tabitem %}

{% tabitem label="Jenkins" %}

Run agents directly on Jenkins with the workflow below:

```groovy
// Jenkinsfile
pipeline {
    agent none
    environment {
        NX_BRANCH = env.BRANCH_NAME.replace('PR-', '')
    }
    stages {
        stage('Pipeline') {
            parallel {
                stage('Main') {
                    when {
                        branch 'main'
                    }
                    agent any
                    steps {
                        sh "npm ci"
                        sh "npx nx start-ci-run --distribute-on='manual' --stop-agents-after='e2e-ci'"
                        sh "npx nx record -- nx format:check"
                        sh "npx nx affected --base=HEAD~1 -t lint,test,build,e2e-ci --configuration=ci --parallel=2"
                    }
                    post {
                        // Self-Healing CI: recommend fixes for failures. Learn more: https://nx.dev/ci/features/self-healing-ci
                        always {
                            sh "npx nx fix-ci"
                        }
                    }
                }
                stage('PR') {
                    when {
                        not { branch 'main' }
                    }
                    agent any
                    steps {
                        sh "npm ci"
                        sh "npx nx start-ci-run --distribute-on='manual' --stop-agents-after='e2e-ci'"
                        sh "npx nx record -- nx format:check"
                        sh "npx nx affected --base origin/${env.CHANGE_TARGET} -t lint,test,build,e2e-ci --parallel=2 --configuration=ci"
                    }
                    post {
                        // Self-Healing CI: recommend fixes for failures. Learn more: https://nx.dev/ci/features/self-healing-ci
                        always {
                            sh "npx nx fix-ci"
                        }
                    }
                }

                # Add as many agent you want
                stage('Agent1') {
                   agent any
                   environment {
                    NX_AGENT_NAME = '1'
                   }
                   steps {
                    sh "npm ci"
                    sh "npx nx start-agent"
                   }
                   post {
                        // Self-Healing CI: recommend fixes for failures. Learn more: https://nx.dev/ci/features/self-healing-ci
                        always {
                            sh "npx nx fix-ci"
                        }
                   }
                }
                stage('Agent2') {
                   agent any
                   environment {
                    NX_AGENT_NAME = '2'
                   }
                   steps {
                    sh "npm ci"
                    sh "npx nx start-agent"
                   }
                   post {
                        // Self-Healing CI: recommend fixes for failures. Learn more: https://nx.dev/ci/features/self-healing-ci
                        always {
                            sh "npx nx fix-ci"
                        }
                   }
                }
                stage('Agent3') {
                   agent any
                   environment {
                    NX_AGENT_NAME = '3'
                   }
                   steps {
                    sh "npm ci"
                    sh "npx nx start-agent"
                   }
                   post {
                        // Self-Healing CI: recommend fixes for failures. Learn more: https://nx.dev/ci/features/self-healing-ci
                        always {
                            sh "npx nx fix-ci"
                        }
                   }
                }
            }
        }
    }
}
```

This configuration is setting up two types of jobs - a main job and three agent jobs.

The main job tells Nx Cloud to use DTE and then runs normal Nx commands as if this were a single pipeline set up. Once the commands are done, it notifies Nx Cloud to stop the agent jobs.

The agent jobs set up the repo and then wait for Nx Cloud to assign them tasks.

{% /tabitem %}

{% /tabs %}

{% aside type="caution" title="Two types of parallelization" %}
The agent configuration and the `--parallel` flag both parallelize tasks, but in different ways.
In the examples above, there will be 3 agents running tasks and each agent will try to run 2 tasks at once. If a particular CI run only has 2 tasks, only one agent will be used.
{% /aside %}

## Rerunning jobs with DTE

Rerunning only failed jobs results in agent jobs not running, which causes the CI pipeline to hang and eventually timeout. This is a common pitfall when using a CI providers "rerun failed jobs", or equivalent, feature since agent jobs will always complete successfully.

To enforce rerunning all jobs, you can set up your CI pipeline to exit early with a helpful error.
For example:

> You reran only failed jobs, but CI requires rerunning all jobs.
> Rerun all jobs in the pipeline to prevent this error.

At a high level:

1. Create a job that always succeeds and uploads an artifact on the pipeline with the run attempt number of the pipeline.
2. The main and agent jobs can read the artifact file when starting and assert they are on the same re-try attempt.
3. If the reattempt number does not match, then error with a message stating to rerun all jobs. Otherwise, the pipelines are on the same rerun and can proceed as normally.

---
<!-- source: https://nx.dev/docs/guides/nx-cloud/optimize-your-ttg.md -->
## Optimize Your Time to Green (TTG)

Time to Green (TTG) is the **time from when a pull request (PR) opens and triggers CI to the moment all checks are green and the PR is review-ready**.

TTG is a practical sub-metric of Time to Merge (TTM): by compressing TTG (lower is better), you remove the biggest day‑to‑day bottlenecks that developers feel, which in turn improves overall TTM.

## Why is this important?

<!-- {% ci-bottleneck /%} -->

The biggest day‑to‑day waste in engineering teams: **constant context switching and PR babysitting**. The common loop is:

- 🧑‍💻 Write code
- 🧑‍💻 Push PR
- ⏳ CI runs
- ❌ CI fails 2 minutes later
- ⏳ Discover it much later
- ‍🧑‍💻 Switch context to debug and trigger CI run
- ⏳ Re-running CI
- ❌ Flaky test fails CI
- ‍🧑‍💻 Switch context to debug and trigger CI run
- ⏳ Re-running CI
- ✅ CI is finally green
- ‍🧑‍💻 Reach out to someone to review

This delay compounds across teams and drastically slows delivery. **Nx Cloud fixes this.**

## How to improve TTG

High TTG usually comes from three sources: slow failure discovery, disruptive PR babysitting, and raw execution time. Tackle them in this order.

**Prerequisite: Connect your workspace to Nx Cloud**

If you haven't already, run the following command to connect your workspace to Nx Cloud:

```shell
npx nx@latest connect
```

### 1) Get failure feedback immediately (avoid late discovery)

When you don't notice CI failed, you lose time before you can act. Tighten the loop so failures surface where you're working.

**What to do:** See failures immediately where you work by getting a notification in your editor: install [Nx Console](/docs/getting-started/editor-setup).

### 2) Eliminate PR babysitting (minimize context switching)

The expensive loop is switching branches to fix, re‑pushing, waiting, and repeating; especially with flakes.

**What to do:**

- Approve fixes instead of branch‑hopping: enable **[Self‑Healing CI](/docs/features/ci-features/self-healing-ci#configure-your-ci-pipeline)** to analyze failed tasks, propose and verify fixes, and commit to your PR after approval.
- Also enable **[flaky task detection and retries](/docs/features/ci-features/flaky-tasks)** to automatically re-run flaky tasks in the background while you keep working undisturbed.

### 3) Shorten actual CI time (make the pipeline fast)

Once feedback and context switching are handled, compress the compute side.

**What to do:**

- Reuse work with **[Remote caching (Nx Replay)](/docs/features/ci-features/remote-cache)**.
- Run more in parallel with **[Distributed task execution (Nx Agents)](/docs/features/ci-features/distribute-task-execution)**.
- Scale long suites with **[E2E test splitting](/docs/features/ci-features/split-e2e-tasks)** so they finish quickly.

## Measure TTG and diagnose bottlenecks

![TTG metrics](../../../../assets/nx-cloud/nx-cloud-ttg-stats.avif)

**Doing too much work on PRs**

- Use [Nx Affected](/docs/features/ci-features/affected) to only run what changed.

**Cache hit rate is low**

- Ensure tasks are cacheable and deterministic. Define `outputs` and configure `inputs`/`namedInputs` correctly. See: [Configure Inputs](/docs/guides/tasks--caching/configure-inputs), [Configure Outputs](/docs/guides/tasks--caching/configure-outputs), [Inputs Reference](/docs/reference/inputs)
- Standardize Node/PNPM versions across dev and CI; avoid environment variables that unintentionally affect inputs.
- Use [Remote caching (Nx Replay)](/docs/features/ci-features/remote-cache) to share results between CI and dev machines.

**Agents are idle, or queue time is high**

- Increase or right-size distributed capacity and parallelism with [Nx Agents](/docs/features/ci-features/distribute-task-execution).
- Use [Dynamic Agents](/docs/features/ci-features/dynamic-agents) to scale based on PR size.
- Remove unnecessary serialization (global locks, [overly strict `dependsOn`](/docs/guides/tasks--caching/defining-task-pipeline)).

**E2E suites take too long**

- Enable [E2E test splitting](/docs/features/ci-features/split-e2e-tasks) so large suites run across agents.
- Ensure tests are shardable (no hidden global state, independent specs).

**Flaky task rate is high**

- Enable [Flaky task detection and automatic retries](/docs/features/ci-features/flaky-tasks).
- Isolate and quarantine persistently flaky suites to keep pipelines green.

**Late failure discovery / PR babysitting**

- Install [Nx Console](/docs/getting-started/editor-setup) for instant failure and fix notifications in your editor.
- Enable [Self‑Healing CI](/docs/features/ci-features/self-healing-ci) to propose and validate fixes automatically (ensure the `npx nx fix-ci` step runs with `if: always()`).

## Talk to us

If you still need help feel free to [reach out to us](/contact).

---
<!-- source: https://nx.dev/docs/guides/nx-cloud/personal-access-tokens.md -->
## Nx Cloud and Personal Access Tokens

{% youtube src="https://www.youtube.com/watch?v=vX-wgI1zlao" title="Configure your Nx Cloud Personal Access Token" /%}

From Nx 19.7 repositories are connected to Nx Cloud via a property in `nx.json` called `nxCloudId`. By default this value allows anyone who clones the repository `read-write` access to Nx Cloud features for that workspace. These permissions can be updated in the workspace settings. To disallow access to anonymous users or allow `read-write` access to known users it is required that all users provision their own personal access token. To do that they need to use [`npx nx login`](/docs/reference/nx-cloud-cli#npx-nxcloud-login).

{% aside type="caution" title="Personal Access Tokens require the `nxCloudId` field in `nx.json`" %}
Ensure that you have the `nxCloudId` property in your `nx.json` file to connect to Nx Cloud with a Personal Access Token. If you have been using `nxCloudAccessToken`, you can convert it to `nxCloudId` by running [`npx nx-cloud convert-to-nx-cloud-id`](/docs/reference/nx-cloud-cli#npx-nxcloud-converttonxcloudid).
{% /aside %}

{% tabs %}
{% tabitem label="Nx >= 19.7" %}

```json
// nx.json
{
  "nxCloudId": "SOMEID"
}
```

{% /tabitem %}
{% tabitem label="Nx <= 19.6" %}

```json
// nx.json
"tasksRunnerOptions": {
    "default": {
      "runner": "nx-cloud",
      "options": {
        "nxCloudId": "SOMEID"
      }
    }
  }
```

To utilize personal access tokens and Nx Cloud ID with Nx <= 19.6, the nx-cloud npm package is also required to be installed in your workspaces `package.json`.

```json
// package.json
{
  "devDependencies": {
    "nx-cloud": "latest"
  }
}
```

{% /tabitem %}
{% /tabs %}

## Personal access tokens (PATs)

When you run [`npx nx login`](/docs/reference/nx-cloud-cli#npx-nxcloud-login) you will be directed to the Nx Cloud app where you will be required to create an account and login. A new personal access token will be provisioned and saved in a local configuration file in your home folder (the location of this will be displayed when login is complete and varies depending on OS).

### View your personal access tokens

You can view your personal access tokens in the Nx Cloud app by navigating to your profile settings. Click your user icon in the top right corner of the app and select `Profile`.

![Profile Settings](../../../../assets/nx-cloud/profile-page.avif)

From there, click on the `Personal access tokens` tab.

![Personal Access Tokens](../../../../assets/nx-cloud/personal-access-tokens-profile.avif)

### Manually create a personal access token

Personal access tokens can also be manually created in the Nx Cloud app. Navigate to your profile settings and click on the `Personal access tokens` tab. Select `New access token`, enter a name for the token and click `Generate Token`. The token will be displayed on the screen and can be copied to your clipboard.

You can then use [nx-cloud configure](/docs/reference/nx-cloud-cli#npx-nxcloud-configure) in your terminal to set the token in your local configuration file.

## Permissions

There are two types of permissions that can be granted to users.

### Workspace ID access level

These are the permissions granted to users who are not [logged in](/docs/reference/nx-cloud-cli#npx-nxcloud-login) or are not members of the Nx Cloud organization for this workspace. By default, all users have `read-write` access to the workspace. This can be updated in the workspace settings to `read-only` or `none`.

While the initial setting for workspace ID access level is `read-write`, we recommend that you change this setting to `read-only` or `none` for any repository that is visible to people that do not have permission to edit the repository (i.e. open source repositories or repositories that are visible across an organization, but only editable by a specific team).

### Personal access token access level

When a workspace member logs in with a personal access token after running [`npx nx login`](/docs/reference/nx-cloud-cli#npx-nxcloud-login) they are granted access to Nx Cloud features.
By default all personal access tokens have `read-write` access to the remote cache. This can be updated to `read-only` in the workspace settings if required.

## Better security

Without an access token committed to your `nx.json` file you gain more fine-grained control over who has access to your cache artifacts and who can utilise Nx Cloud features that you pay for. When you remove a member from your organization they will immediately lose access to all Nx Cloud features saving you the trouble of needing to cycle any tokens you were previously committing to the repository.

---
<!-- source: https://nx.dev/docs/guides/nx-cloud/record-commands.md -->
## Recording Non-Nx Commands

Build and deploy pipelines often do much more than run builds. Unfortunately, this creates more opportunities for pieces to fail. To minimize the number of different sites you need to visit to diagnose issues, Nx Cloud 13.3 and above is capable of recording and saving output from arbitrary commands.

## Enable command recording

To record a command with Nx Cloud:

1. Identify a command you would like recorded from your CI/CD configuration, or think of one to run on your machine. (example: echo "hello world")
2. Prefix your command with `npx nx record --`, or the appropriate execute command of your package manager. The `--` is optional but makes it easier to read what portion of the command will be recorded. (example: npx nx record -- echo "hello world")
3. Run the command! Nx Cloud will record output and status codes, and generate a link for you to view your output on so you can easily view or share the result. Make sure you run this command from your workspace root or one of its subdirectories so Nx Cloud can properly locate configuration information.

![npx nx record -- echo "hello world"](../../../../assets/nx-cloud/set-up/record-hello-world.webp)

## Locating command output in Nx Cloud

Commands that Nx Cloud stores will appear under your "Runs" view. For easy identification, the stored output will be displayed as a "record-output" target being invoked on the "nx-cloud-tasks-runner" project.

![nx record -- nx format:check](https://nx.dev/nx-cloud/set-up/record-format-check.webp)

If you use the Nx Cloud GitHub Integration, links to recorded output will also be displayed based on the exit code in the summary comment.

![Nx Cloud Report](../../../../assets/nx-cloud/set-up/record-report.webp)

---
<!-- source: https://nx.dev/docs/guides/nx-cloud/setup-ci.md -->
## Setting Up CI for Nx Cloud

Learn how to set up Nx Cloud for your workspace with your preferred CI platform. Get started connecting to Nx Cloud by running

```shell
nx connect
```

Each platform has specific configurations and optimizations that help you build and test only what is affected, retrieve previous successful builds, and optimize CI performance.

{% course_video src="https://www.youtube.com/watch?v=8mqHXYIl_qI" courseTitle="From PNPM Workspaces to Distributed CI" courseUrl="https://nx.dev/courses/pnpm-nx-next/lessons-06-nx-cloud-setup" /%}

## CI configuration

{% tabs syncKey="ci-provider" %}
{% tabitem label="GitHub" %}
Need a starting point? Generate a new workflow file with the following command:

```shell
nx g ci-workflow --ci=github
```

Below is an example of a GitHub Actions setup, building, and testing only what is affected.

```yaml
// .github/workflows/ci.yml
name: CI

on:
  push:
    branches:
      - main
  pull_request:

permissions:
  actions: read
  contents: read

jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          filter: tree:0
          fetch-depth: 0

      # This enables task distribution via Nx Cloud
      # Run this command as early as possible, before dependencies are installed
      # Learn more at https://nx.dev/ci/reference/nx-cloud-cli#npx-nxcloud-startcirun
      # Connect your workspace by running "nx connect" and uncomment this line to enable task distribution
      # - run: npx nx start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"

      # Cache node_modules
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - run: npm ci
      - uses: nrwl/nx-set-shas@v4

      # Prepend any command with "nx record --" to record its logs to Nx Cloud
      # - run: npx nx record -- echo Hello World
      - run: npx nx affected -t lint test build
      # Nx Cloud recommends fixes for failures to help you get CI green faster. Learn more: https://nx.dev/ci/features/self-healing-ci
      - run: npx nx fix-ci
        if: always()
```

{% /tabitem %}

{% tabitem label="CircleCI" %}

Need a starting point? Generate a new workflow file with the following command:

```shell
nx g ci-workflow --ci=circleci
```

Below is an example of a Circle CI setup, building, and testing only what is affected.

```yaml
// .circleci/config.yml
version: 2.1

orbs:
  nx: nrwl/nx@1.7.0

jobs:
  main:
    docker:
      - image: cimg/node:lts-browsers
    steps:
      - checkout

      # This enables task distribution via Nx Cloud
      # Run this command as early as possible, before dependencies are installed
      # Learn more at https://nx.dev/ci/reference/nx-cloud-cli#npx-nxcloud-startcirun
      # Connect your workspace by running "nx connect" and uncomment this line to enable task distribution
      # - run: npx nx start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"

      - run: npm ci
      - nx/set-shas:
          main-branch-name: 'main'

      # Prepend any command with "nx record --" to record its logs to Nx Cloud
      # - run: npx nx record -- echo Hello World
      - run:
          command: npx nx affected -t lint test build
      # Nx Cloud recommends fixes for failures to help you get CI green faster. Learn more: https://nx.dev/ci/features/self-healing-ci
      - run:
          command: npx nx fix-ci
          when: always

workflows:
  version: 2

  ci:
    jobs:
      - main
```

{% /tabitem %}

{% tabitem label="GitLab" %}
Need a starting point? Generate a new workflow file with the following command:

```shell
nx g ci-workflow --ci=gitlab
```

Below is an example of a GitLab setup, building and testing only what is affected.

```yaml
// .gitlab-ci.yml
image: node:20
variables:
  CI: 'true'

# Main job
CI:
  interruptible: true
  only:
    - main
    - merge_requests
  script:
    # This enables task distribution via Nx Cloud
    # Run this command as early as possible, before dependencies are installed
    # Learn more at https://nx.dev/ci/reference/nx-cloud-cli#npx-nxcloud-startcirun
    # Connect your workspace by running "nx connect" and uncomment this line to enable task distribution
    # - npx nx start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"

    - npm ci
    - NX_HEAD=$CI_COMMIT_SHA
    - NX_BASE=${CI_MERGE_REQUEST_DIFF_BASE_SHA:-$CI_COMMIT_BEFORE_SHA}

    # Prepend any command with "nx record --" to record its logs to Nx Cloud
    # - npx nx record -- echo Hello World
    - npx nx affected -t lint test build
    # Nx Cloud recommends fixes for failures to help you get CI green faster. Learn more: https://nx.dev/ci/features/self-healing-ci

  after_script:
    - npx nx fix-ci
```

{% /tabitem %}

{% tabitem label="Azure" %}

Need a starting point? Generate a new workflow file with the following command:

```shell
nx g ci-workflow --ci=azure-pipelines
```

Below is an example of an Azure Pipelines setup building and testing only what is affected.

```yaml
// azure-pipelines.yml
name: CI

trigger:
  - main
pr:
  - main

variables:
  CI: 'true'
  ${{ if eq(variables['Build.Reason'], 'PullRequest') }}:
    NX_BRANCH: $(System.PullRequest.PullRequestNumber)
    TARGET_BRANCH: $[replace(variables['System.PullRequest.TargetBranch'],'refs/heads/','origin/')]
    BASE_SHA: $(git merge-base $(TARGET_BRANCH) HEAD)
  ${{ if ne(variables['Build.Reason'], 'PullRequest') }}:
    NX_BRANCH: $(Build.SourceBranchName)
    BASE_SHA: $(git rev-parse HEAD~1)
  HEAD_SHA: $(git rev-parse HEAD)

jobs:
  - job: main
    pool:
      vmImage: 'ubuntu-latest'
    steps:
      - checkout: self
        fetchDepth: '0'
        fetchFilter: tree:0
      # Set Azure Devops CLI default settings
      - bash: az devops configure --defaults organization=$(System.TeamFoundationCollectionUri) project=$(System.TeamProject)
        displayName: 'Set default Azure DevOps organization and project'
      # Get last successfull commit from Azure Devops CLI
      - bash: |
          LAST_SHA=$(az pipelines build list --branch $(Build.SourceBranchName) --definition-ids $(System.DefinitionId) --result succeeded --top 1 --query "[0].triggerInfo.\"ci.sourceSha\"")
          if [ -z "$LAST_SHA" ]
          then
            echo "Last successful commit not found. Using fallback 'HEAD~1': $BASE_SHA"
          else
            echo "Last successful commit SHA: $LAST_SHA"
            echo "##vso[task.setvariable variable=BASE_SHA]$LAST_SHA"
          fi
        displayName: 'Get last successful commit SHA'
        condition: ne(variables['Build.Reason'], 'PullRequest')
        env:
          AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)

      # This enables task distribution via Nx Cloud
      # Run this command as early as possible, before dependencies are installed
      # Learn more at https://nx.dev/ci/reference/nx-cloud-cli#npx-nxcloud-startcirun
      # Connect your workspace by running "nx connect" and uncomment this line to enable task distribution
      # - script: npx nx start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"

      - script: npm ci
      - script: git branch --track main origin/main
        condition: eq(variables['Build.Reason'], 'PullRequest')

      # Prepend any command with "nx record --" to record its logs to Nx Cloud
      # - script: npx nx record -- echo Hello World
      - script: npx nx affected --base=$(BASE_SHA) --head=$(HEAD_SHA) -t lint test build
      # Nx Cloud recommends fixes for failures to help you get CI green faster. Learn more: https://nx.dev/ci/features/self-healing-ci
      - script: npx nx fix-ci
        condition: always()
```

{% /tabitem %}

{% tabitem label="Jenkins" %}

Below is an example of a Jenkins setup, building and testing only what is affected.

```groovy
pipeline {
    agent none
    environment {
        NX_BRANCH = env.BRANCH_NAME.replace('PR-', '')
    }
    stages {
        stage('Pipeline') {
            parallel {
                stage('Main') {
                    when {
                        branch 'main'
                    }
                    agent any
                    steps {
                        // This line enables distribution
                        // The "--stop-agents-after" is optional, but allows idle agents to shut down once the "e2e-ci" targets have been requested
                        // sh "npx nx start-ci-run --distribute-on='3 linux-medium-js' --stop-agents-after='e2e-ci'"
                        sh "npm ci"

                        // Prepend any command with "nx record --" to record its logs to Nx Cloud
                        // This requires connecting your workspace to Nx Cloud. Run "nx connect" to get started w/ Nx Cloud
                        // sh "npx nx record -- nx format:check"

                        // Without Nx Cloud, run format:check directly
                        sh "npx nx format:check"
                        sh "npx nx affected --base=HEAD~1 -t lint test build e2e-ci"
                    }
                }
                stage('PR') {
                    when {
                        not { branch 'main' }
                    }
                    agent any
                    steps {
                        // This line enables distribution
                        // The "--stop-agents-after" is optional, but allows idle agents to shut down once the "e2e-ci" targets have been requested
                        // sh "npx nx start-ci-run --distribute-on='3 linux-medium-js' --stop-agents-after='e2e-ci'"
                        sh "npm ci"

                        // Prepend any command with "nx record --" to record its logs to Nx Cloud
                        // This requires connecting your workspace to Nx Cloud. Run "nx connect" to get started w/ Nx Cloud
                        // sh "npx nx record -- nx format:check"

                        // Without Nx Cloud, run format:check directly
                        sh "npx nx format:check"
                        sh "npx nx affected --base origin/${env.CHANGE_TARGET} -t lint test build e2e-ci"
                    }
                }
            }
        }
    }
}
```

{% /tabitem %}

{% tabitem label="Bitbucket" %}

Need a starting point? Generate a new workflow file with the following command:

```shell
nx g ci-workflow --ci=bitbucket-pipelines
```

Below is an example of a Bitbucket Pipelines, building and testing only what is affected.

```yaml
// bitbucket-pipelines.yml
image: node:20

clone:
  depth: full

pipelines:
  pull-requests:
    '**':
      - step:
          name: 'Build and test affected apps on Pull Requests'
          script:
            - export NX_BRANCH=$BITBUCKET_PR_ID

            # This enables task distribution via Nx Cloud
            # Run this command as early as possible, before dependencies are installed
            # Learn more at https://nx.dev/ci/reference/nx-cloud-cli#npx-nxcloud-startcirun
            # Connect your workspace by running "nx connect" and uncomment this line to enable task distribution
            # - npx nx start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"

            - npm ci

            # Prepend any command with "nx record --" to record its logs to Nx Cloud
            # npx nx record -- echo Hello World
            - npx nx affected --base=origin/main -t lint test build
            # Nx Cloud recommends fixes for failures to help you get CI green faster. Learn more: https://nx.dev/ci/features/self-healing-ci

          after-script:
            - npx nx fix-ci

  branches:
    main:
      - step:
          name: 'Build and test affected apps on "main" branch changes'
          script:
            - export NX_BRANCH=$BITBUCKET_BRANCH
            # This enables task distribution via Nx Cloud
            # Run this command as early as possible, before dependencies are installed
            # Learn more at https://nx.dev/ci/reference/nx-cloud-cli#npx-nxcloud-startcirun
            # Connect your workspace by running "nx connect" and uncomment this
            # - npx nx start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"

            - npm ci

            # Prepend any command with "nx record --" to record its logs to Nx Cloud
            # - npx nx record -- echo Hello World
            - npx nx affected -t lint test build --base=HEAD~1
```

The `pull-requests` and `main` jobs implement the CI workflow.
{% /tabitem %}
{% /tabs %}

## Get the commit of the last successful build

{% tabs syncKey="ci-provider" %}
{% tabitem label="GitHub" %}
The `GitHub` can track the last successful run on the `main` branch and use this as a reference point for the `BASE`. The [nrwl/nx-set-shas](https://github.com/marketplace/actions/nx-set-shas) provides a convenient implementation of this functionality, which you can drop into your existing CI workflow.

To understand why knowing the last successful build is important for the affected command, check out the [in-depth explanation in Actions's docs](https://github.com/marketplace/actions/nx-set-shas#background).
{% /tabitem %}

{% tabitem label="CircleCI" %}
`CircleCI` can track the last successful run on the `main` branch and use this as a reference point for the `BASE`. The [Nx Orb](https://github.com/nrwl/nx-orb) provides a convenient implementation of this functionality, which you can drop into your existing CI workflow. Specifically, for push commits, `nx/set-shas` populates the `$NX_BASE` environment variable with the commit SHA of the last successful run.

To understand why knowing the last successful build is important for the affected command, check out the [in-depth explanation in Orb's docs](https://github.com/nrwl/nx-orb#background).

### Using CircleCI in a private repository

To use the [Nx Orb](https://github.com/nrwl/nx-orb) with a private repository on your main branch, you need to grant the orb access to your CircleCI API. Create an environment variable called `CIRCLE_API_TOKEN` in the context of the project.

{% aside type="caution" title="Caution" %}
It should be a user token, not the project token.
{% /aside %}
{% /tabitem %}

{% tabitem label="GitLab" %}
GitLab CI/CD uses built-in environment variables to determine the commit range for affected commands. The configuration automatically sets:

- `NX_HEAD=$CI_COMMIT_SHA` - Current commit SHA
- `NX_BASE=${CI_MERGE_REQUEST_DIFF_BASE_SHA:-$CI_COMMIT_BEFORE_SHA}` - Base commit for comparison

This approach works for both merge requests and direct pushes to main, using GitLab's built-in variables to determine the appropriate base commit.
{% /tabitem %}

{% tabitem label="Azure" %}
In the example above, we ran a script to retrieve the commit of the last successful build. The idea is to
use [Azure Devops CLI](https://learn.microsoft.com/en-us/cli/azure/pipelines?view=azure-cli-latest) directly in the [Pipeline Yaml](https://learn.microsoft.com/en-us/azure/devops/cli/azure-devops-cli-in-yaml?view=azure-devops)

First, we configure Devops CLI

```yaml
# Set Azure Devops CLI default settings
- bash: az devops configure --defaults organization=$(System.TeamFoundationCollectionUri) project=$(System.TeamProject)
  displayName: 'Set default Azure DevOps organization and project'
```

Then we can query the pipelines API (providing the auth token)

```yaml
# Get last successfull commit from Azure Devops CLI
- bash: |
    LAST_SHA=$(az pipelines build list --branch $(Build.SourceBranchName) --definition-ids $(System.DefinitionId) --result succeeded --top 1 --query "[0].triggerInfo.\"ci.sourceSha\"")
    if [ -z "$LAST_SHA" ]
    then
      echo "Last successful commit not found. Using fallback 'HEAD~1': $BASE_SHA"
    else
      echo "Last successful commit SHA: $LAST_SHA"
      echo "##vso[task.setvariable variable=BASE_SHA]$LAST_SHA"
    fi
  displayName: 'Get last successful commit SHA'
  condition: ne(variables['Build.Reason'], 'PullRequest')
  env:
    AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)
```

We can target a specific build; in this example, we specified:

- The branch (--branch)
- The result type (--result)
- The number of the result (--top)

The command returns an entire JSON object with all the information. But we can narrow it down to the desired result with the `--query` param that uses [JMESPath](https://jmespath.org/)
format ([more details](https://learn.microsoft.com/en-us/cli/azure/query-azure-cli?tabs=concepts%2Cbash))

Finally, we extract the result in a common [custom variable](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/set-variables-scripts?view=azure-devops&tabs=bash)
named `BASE_SHA` used later by the `nx format` and `nx affected` commands.
{% /tabitem %}

{% tabitem label="Jenkins" %}
Unlike `GitHub Actions` and `CircleCI`, you don't have the metadata to help you track the last successful run on `main`. In the example below, the base is set to `HEAD~1` (for push) or branching point (for pull requests), but a more robust solution would be to tag an SHA in the main job once it succeeds and then use this tag as a base. See the [nx-tag-successful-ci-run](https://github.com/nrwl/nx-tag-successful-ci-run) and [nx-set-shas](https://github.com/nrwl/nx-set-shas) (version 1 implements tagging mechanism) repositories for more information.

We also have to set `NX_BRANCH` explicitly.
{% /tabitem %}

{% tabitem label="Bitbucket" %}
Unlike `GitHub Actions` and `CircleCI`, you don't have the metadata to help you track the last successful run on `main`. In the example below, the base is set to `HEAD~1` (for push) or branching point (for pull requests), but a more robust solution would be to tag an SHA in the main job once it succeeds and then use this tag as a base. See the [nx-tag-successful-ci-run](https://github.com/nrwl/nx-tag-successful-ci-run) and [nx-set-shas](https://github.com/nrwl/nx-set-shas) (version 1 implements tagging mechanism) repositories for more information.

We also have to set `NX_BRANCH` explicitly.
{% /tabitem %}
{% /tabs %}

## Common features across platforms

### Task distribution with Nx Cloud

All CI platforms support task distribution via Nx Cloud. To enable it:

1. Connect your workspace by running `nx connect`
2. Uncomment the `npx nx start-ci-run` command in your CI configuration
3. Configure the distribution settings based on your needs

Learn more at [Nx Cloud CI Reference](https://nx.dev/ci/reference/nx-cloud-cli#npx-nxcloud-startcirun).

### Self-healing CI

Nx Cloud can recommend fixes for failures to help you get CI green faster. The `nx fix-ci` command is included in all platform configurations and runs automatically after failures.

Learn more about [Self-Healing CI features](https://nx.dev/ci/features/self-healing-ci).

### Recording commands

You can record any command's logs to Nx Cloud by prepending it with `nx record --`. This helps with debugging and monitoring your CI pipeline.

Example:

```bash
npx nx record -- echo Hello World
```

---
<!-- source: https://nx.dev/docs/guides/nx-cloud/source-control-integration.md -->
## Source Control Integration

{% index_page_cards path="guides/nx-cloud/source-control-integration" /%}

---
<!-- source: https://nx.dev/docs/guides/nx-cloud/source-control-integration/azure-devops.md -->
## Azure DevOps Integration

The Nx Cloud + Azure Devops Integration lets you access the result of every run—with all its logs and build insights—straight from your PR.

## Connecting your workspace

![Access VCS Setup](../../../../../assets/nx-cloud/set-up/access-vcs-setup.webp)

Once on the VCS Integrations setup page, select "Azure DevOps". You will be prompted to enter the name of your organization and project.

Identifying your organization and project can be done by looking at the URL of your project summary page.

```text
// URL format
https://dev.azure.com/[organization]/[project]
```

For example, the url `https://dev.azure.com/nrwl/my-monorepo-project` has an organization name of "nrwl", and a project name of "large-monorepo".

You will also need to provide the id of your Azure Git repository, this can either be the internal GUID identifier, if known, or you can use the name of the repository from the URL you use to access it.

For example, a URL of `https://dev.azure.com/nrwl/_git/large-monorepo` has the repository id of "large-monorepo".

![Add Azure DevOps Repository](../../../../../assets/nx-cloud/set-up/add-azure-devops-repository.webp)

### Configuring authentication

#### Using a personal access token

To use a Personal Access Token for authentication, one must be generated with proper permissions. The minimum required permissions are shown in the screenshot below.

![Work Items - Read, Code - Read, Build - Read & execute, Release - Read, write, & execute](../../../../../assets/nx-cloud/set-up/minimal-ado-access-token.webp)

Once this token is created paste the value and then click "Connect".

This will verify that Nx Cloud can connect to your repo. Upon a successful test, your configuration is saved, and setup is complete.

Please note that Azure DevOps will impose rate limits which can degrade the performance of the integration leading to missing data or functionality. To mitigate the impact, we recommend you assign the [Basic + Test plan](https://learn.microsoft.com/en-us/azure/devops/organizations/billing/buy-basic-access-add-users?view=azure-devops#assign-basic-or-basic--test-plans) to the user whose token you utilise for this integration.

### Advanced configuration

If your company runs a self-hosted Azure DevOps installation, you may need to override the default URL that Nx Cloud uses to connect to the Azure Devops API. To do so, check the box labeled "Override Azure DevOps API URL" and enter the correct URL for your organization.

---
<!-- source: https://nx.dev/docs/guides/nx-cloud/source-control-integration/bitbucket.md -->
## Bitbucket Integration

The Nx Cloud + Bitbucket Integration lets you access the result of every run—with all its logs and build insights—straight from your PR.

### Using an API token

API tokens can be generated on a user account level and can be scoped to specific applications like Bitbucket. This is the recommended approach for Nx Cloud integration.

An API token is a secure credential that allows scripts and other processes to authenticate with Bitbucket Cloud applications. You should treat API tokens as securely as any other password.

#### Creating an API token

1. First, navigate to your [BitBucket user security settings](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Select "Create API token with scopes"

![Create API Token](../../../../../assets/nx-cloud/set-up/bitbucket-api-tokens-create-screen.jpg)

3. Give your token a name and proceed to the next step

4. When prompted to select the app, choose **Bitbucket**. This ensures the API token can only access Bitbucket APIs and perform git operations:

![Select Bitbucket App](../../../../../assets/nx-cloud/set-up/bitbucket-api-tokens-create-scope.jpg)

5. The required permissions for Nx Cloud are:
   - `read:pullrequest:bitbucket` - to read pull request information
   - `write:pullrequest:bitbucket` - to write comments on pull requests
   - `read:repository:bitbucket` - to read repository contents
   - `write:repository:bitbucket` - to write files to the repository
   - `read:user:bitbucket` - verify username from email address
   - `account:read` - verify username from email address

6. Click "Create token" and copy your newly created API token

#### Configuring Nx Cloud with your API Token

Once your API token is created, head back to your workspace settings on NxCloud to set up the BitBucket integration:

![Access VCS Setup](../../../../../assets/nx-cloud/set-up/access-vcs-setup.webp)

1. Fill-in all the required fields for selecting your BitBucket repository
2. Username is found on the [account settings](https://bitbucket.org/account/settings/) screen (it is not your email address)
3. Paste your API token created earlier into the API Token box
4. Click "Connect" to finish the setup

### Using an HTTP access token

If you are using BitBucket Data Center (on-prem) you need to enable an [HTTP access token for authentication](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html).

{% aside type="note" title="User linked Access Tokens" %}
Due to the type of APIs NxCloud needs to call, we need to create an Access Token [**at the user level**](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html). Repo level access tokens will not work.
{% /aside %}

The minimum required permissions are write access to the repository:

![Create an Access Token](../../../../../assets/nx-cloud/set-up/bitbucket-data-center-access-token.png)

Once the Access Token is created, save it in a secure location and then head back to your workspace settings on NxCloud and let's set up a BitBucket integration:

![Access VCS Setup](../../../../../assets/nx-cloud/set-up/access-vcs-setup.webp)

1. Fill-in all the required fields for selecting your Bitbucket repository
2. Username is found on the [account settings](https://your-bitbucket-instance.com/profile) screen (it is not your email address)
3. Paste your Access Token created earlier into the Access Token box
4. Make sure you give NxCloud the URL of your BitBucket instance (this can be in the simple form of `https://your-bitbucket-instance.com`)
5. Click "Connect" to finish the setup

---
<!-- source: https://nx.dev/docs/guides/nx-cloud/source-control-integration/github.md -->
## GitHub Integration

Integrate Nx Cloud with your source control platform to access run results, logs, and build insights directly from your pull requests or merge requests. This integration is required to use core Nx Cloud features like task distribution and flaky task re-trying.

The [Nx Cloud GitHub App](https://github.com/marketplace/official-nx-cloud-app) lets you access the result of every run—with all its logs and build insights—straight from your PR. It will comment on your PR with the results of the latest CI run, with a summary of the results and links to detailed, structured logs. If you’re using Self-Healing CI, Nx Cloud will comment with proposed fixes for CI failures.

## Install the app

For the best experience, install the [Nx Cloud GitHub App](https://github.com/marketplace/official-nx-cloud-app). Using the app provides the most seamless authentication experience. This is not required if you wish to authenticate with a personal access token that you generate yourself.

For a detailed breakdown of each permission the GitHub App requires and why, see the [GitHub App Permissions](/docs/guides/nx-cloud/source-control-integration/github-app-permissions) reference.

## Connecting your workspace

Once you have installed the Nx Cloud GitHub App, you must link your workspace to the installation. To do this, sign in to Nx Cloud and navigate to the VCS Integrations setup page. This page can be found in your workspace settings, you need to be admin of the organization in order to access it.
Once on the VCS Integrations setup page, you can choose what VCS you want to connect to your workspace.

![Access VCS Setup](../../../../../assets/nx-cloud/set-up/access-vcs-setup.webp)

### Choosing an authentication method

The easiest way to configure the Nx Cloud GitHub Integration is through the Nx Cloud GitHub App, and this method should be preferred for users on [https://cloud.nx.app](https://cloud.nx.app). Users with strict privacy considerations may wish to generate a personal access token (PAT) instead.

#### Using the GitHub app

To use the Nx Cloud GitHub App for authentication, select the **Use GitHub application** radio button and then click **Connect**.
This will verify that Nx Cloud can connect to your repo. Upon a successful test, your configuration is saved.
Check if there's any [additional setup required for your CI platform](/docs/guides/nx-cloud/source-control-integration#ci-platform-considerations), then your setup is complete.

![Use GitHub App for Authentication](../../../../../assets/nx-cloud/set-up/use-github-app-auth.webp)

#### Using a personal access token

Note that users who authenticate with a PAT will not receive Nx Cloud comments with command results and self-healing CI fixes.

Github supports two [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#about-personal-access-tokens) types: classic and fine-grained.

To use a personal access token for authentication, one must be generated with proper permissions. The minimum required permissions are shown in the screenshot below.

{% tabs %}
{% tabitem label="Classic Token" %}

![Minimum GitHub Personal Access Token Permissions](../../../../../assets/nx-cloud/set-up/minimal-github-access-token.webp)

{% /tabitem %}

{% tabitem label="Fine-Grained Token" %}

![Minimum GitHub Fine-grained Personal Access Token Permissions](../../../../../assets/nx-cloud/set-up/fine-grained-gh-pat-permissions.avif)

{% /tabitem %}
{% /tabs %}

Once this token is created, select the radio button for providing a personal access token, paste the value, and then click "Connect". This will verify that Nx Cloud can connect to your repo. Upon a successful test, your configuration is saved. Check the "_CI Platform Considerations_" section below, and if there are no additional instructions for your platform of choice, setup is complete.

### Advanced configuration

If your company runs a self-hosted GitHub installation, you may need to override the default URL that Nx Cloud uses to connect to the GitHub API. To do so, check the box labeled "Override GitHub API URL" and enter the correct URL for your organization.

### Connect to GitHub for more features

Get access to [easy workspace setup](/docs/features/ci-features/github-integration#easy-workspace-setup) and [access control through GitHub organizations](/docs/features/ci-features/github-integration#access-control) when you [connect your GitHub account to Nx Cloud](/docs/features/ci-features/github-integration#connect-to-github).

## CI platform considerations

If you are using CircleCI, TravisCI, GitHub Actions or GitHub, there is nothing else you need to do. If you are using other CI providers, you need to set the `NX_BRANCH` environment variable in your CI configuration. The variable has to be set to a PR number.

For instance, this is an example of doing it in Azure pipelines.

### Azure pipelines

```yml
// azure-pipelines.yml
variables:
  NX_BRANCH: $(System.PullRequest.PullRequestNumber)
```

### CircleCI

Make sure [GitHub checks are enabled](https://circleci.com/docs/2.0/enable-checks/#to-enable-github-checks).

### Jenkins

[Install the Jenkins plugin](https://plugins.jenkins.io/github-checks/).

Ensure this step from the plugin instructions is followed:

    Prerequisite: only GitHub App with proper permissions can publish checks, this guide helps you authenticate your Jenkins as a GitHub App.

## GitHub status checks

The Nx Cloud GitHub Integration updates your PR with commit statuses that reflect the real-time progress of your runs. These statuses are generated dynamically based on your running commands. Enforcing these dynamically-named checks within your branch protection rules is not recommended, as it can result in stuck checks displaying `Waiting for status to be reported`.

From your repository, go to `Settings -> Branches -> Protect matching branches` and ensure that no Nx Cloud status checks are listed in the `Require status checks to pass before merging` list. Enforcing that status checks pass on your default branch is sufficient.
![Ensure that any NxCloud status check is deselected from your branch protection rules](../../../../../assets/nx-cloud/set-up/do-not-enforce-nx-cloud-status-checks.webp)

---
<!-- source: https://nx.dev/docs/guides/nx-cloud/source-control-integration/github-app-permissions.md -->
## GitHub App Permissions

The Nx Cloud GitHub App requires the following permissions to provide CI/CD integration and setup experiences. Most information is used transiently during operations and not stored in our systems.

## Required permissions

Repository permissions:

- `Administration: Read & Write`
- `Checks: Read & Write`
- `Contents: Read & Write`
- `Commit Statuses: Read`
- `Issues: Read & Write`
- `Metadata: Read`
- `Pull requests: Read & Write`
- `Workflows: Read & Write`
- `Actions: Read`

Organization permissions:

- `Administration: Read Only`
- `Members: Read Only`

## Permission details

### Administration (write)

**Used for:** Creating new repositories with a pre-configured Nx workspace during initial onboarding.

**When it's used:** Only when you explicitly choose to create a new workspace through Nx Cloud's setup flow. [Single tenant instances](/docs/enterprise/single-tenant/overview) can safely forego this scope and will only lose the ability to create new workspaces through the app.

### Checks (write)

**Used for:** Updating CI run statuses so you can see the progress and results of your Nx Cloud pipeline executions directly in GitHub. Also used for Self-Healing CI status check runs in PRs.

**When it's used:** Automatically during CI runs to provide real-time status updates.

### Contents (read & write)

**Used for:**

- **Read:** Detecting your workspace's current Nx version to ensure compatibility. Reading files for Self-Healing CI.
- **Write:** Adding Nx Cloud configuration (`nxCloudId` or access token) to your repository during setup. Creating commits and pushing fixes for Self-Healing CI.

**When it's used:** During initial setup and configuration, and regularly if Self-Healing CI is enabled.

### Commit statuses (read)

**Used for:** Reading commit status information to coordinate with other CI tools and provide accurate pipeline context.

**When it's used:** During CI pipeline executions to gather context about your commits.

### Issues (read & write)

**Used for:** PR comments (GitHub uses the Issues API for PR comments — see "Pull requests" below for more detail).

**When it's used:** During CI runs and when posting status comments.

### Metadata (read)

**Used for:** Accessing basic repository information (name, description, visibility). This is a required baseline permission for most GitHub App functionality.

### Pull requests (read & write)

**Used for:**

- **Read:** Gathering branch information, SHAs, and metadata necessary for CI pipeline execution and distributed task coordination.
- **Write:** Posting comments on PRs with CI pipeline status, command results, and Self-Healing CI fixes. Creating PRs during initial Nx Cloud setup. Creating demo PRs for optional features like Self-Healing CI (only when you opt in).

**When it's used:** Read operations occur during CI runs. Write operations occur during setup and when posting status comments.

### Workflows (write)

**Used for:** Automatically configuring GitHub Actions workflow files when you opt in to features like Self-Healing CI and distributed task execution.

**When it's used:** Only when you explicitly enable these features through the Nx Cloud interface.

### Actions (read)

**Used for:** Retrieving GitHub Action logs so that they can be surfaced on Nx Cloud to help resolve failures before Nx Cloud had a chance to run tasks, and for Polygraph support.

**When it's used:** Only when using Polygraph, and Nx Cloud MCP tools to get CI information.

## Your data and security

Most information accessed through these permissions is used transiently during operations and is not stored. Limited version control metadata (such as branch names, SHAs, and commit information) may be stored as part of your CI pipeline execution records for analytics and debugging purposes.

[Nx Cloud is SOC2 Type II certified](https://security.nx.app). We implement industry-standard security practices including encryption at rest and in transit, access logging, and regular security audits.

You can revoke access to the Nx Cloud GitHub app at any time through your GitHub settings. Write operations (creating repos, posting comments, modifying workflows) only occur when explicitly triggered by your actions or when you opt in to specific features.

---
<!-- source: https://nx.dev/docs/guides/nx-cloud/source-control-integration/gitlab.md -->
## GitLab Integration

The Nx Cloud GitLab Integration lets you access the result of every run—with all its logs and build insights—straight from your Merge Requests.

### Connecting your workspace

![Access VCS Setup](../../../../../assets/nx-cloud/set-up/access-vcs-setup.webp)

Once on the VCS Integrations setup page, select "GitLab". You will be prompted to enter your project's ID.

![Locate Gitlab Project ID](../../../../../assets/nx-cloud/set-up/find-gitlab-project-id.avif)

To locate the ID for your project, visit the home page of your repository on GitLab. Click the three-dot menu button in the upper right corner and select "Copy project ID" to copy the value to your clipboard.

![Add GitLab Repository](../../../../../assets/nx-cloud/set-up/add-gitlab-repository.webp)

### Using a personal access token

To use a Personal Access Token for authentication, one must be generated with proper permissions. The minimum required permissions are shown in the screenshot below.

![Minimum GitLab Personal Access Token Permissions](../../../../../assets/nx-cloud/set-up/minimal-gitlab-access-token.webp)

Once this token is created, select the radio button for providing a personal access token, paste the value, and then click "Connect".

This will verify that Nx Cloud can connect to your repo. Upon a successful test, your configuration is saved, and setup is complete.

### Advanced configuration

If your company runs a self-hosted GitLab installation, you may need to override the default URL that Nx Cloud uses to connect to the GitLab API. To do so, check the box labeled "Override GitLab API URL" and enter the correct URL for your organization.

---
<!-- source: https://nx.dev/docs/guides/nx-cloud/use-bun.md -->
## Set Up Bun with Mise on CI

Bun works as a drop-in package manager for Nx workspaces.
You can use it to install dependencies and run Nx commands via `bunx`.
To use bun with [Nx Agents](/docs/features/ci-features/distribute-task-execution),
you need a custom launch template because the default templates only support npm, yarn, and pnpm.

Using [mise](https://mise.jdx.dev/) to manage your toolchain isn't strictly required,
but Nx Cloud launch templates have built-in support for it.
Pinning tool versions in a single `mise.toml` gives you a predictable,
reproducible setup across local development, CI, and Nx Agents.

## Configure your workspace

Create a `mise.toml` at the root of your workspace to pin your toolchain versions:

```toml
// mise.toml
[tools]
node = "24.11.0"
bun = "1.3.11"
```

Then install dependencies with bun:

```shell
bun install
```

Bun generates a `bun.lock` file.
Commit it alongside your `mise.toml` and remove any previous lockfile
(`package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml`).

Run Nx commands with `bunx`:

```shell
bunx nx run-many -t build test lint
```

## Set up CI

Generate a starting CI workflow with:

```shell
nx g ci-workflow --ci=github
```

Then adjust the generated configuration to use bun.
If you haven't connected your workspace to Nx Cloud yet,
run `nx connect` and configure your
[CI access token](/docs/guides/nx-cloud/access-tokens).

Below is an example GitHub Actions workflow using bun with Nx Cloud:

```yaml
// .github/workflows/ci.yml
name: CI
on:
  push:
    branches:
      - main
  pull_request:

permissions:
  actions: read
  contents: read

env:
  NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}

jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
          filter: tree:0

      - run: npx nx start-ci-run --distribute-on="5 linux-large" --stop-agents-after="e2e"

      - name: Setup toolchains with mise
        uses: jdx/mise-action@v3

      - name: Install dependencies
        run: bun install --frozen-lockfile

      - uses: nrwl/nx-set-shas@v5

      - run: bunx nx record -- nx format:check
      - run: bunx nx run-many -t lint test build
      - run: bunx nx run-many -t e2e

      - name: Self-healing
        run: bunx nx fix-ci
        if: always()
```

The `jdx/mise-action` reads your `mise.toml` and installs both Node and bun
at the pinned versions.
No separate `setup-node` or `setup-bun` action is needed.

The `nx start-ci-run` command runs before dependencies are installed,
so it uses `npx` instead of `bunx`.

## Configure Nx Agents

{% aside type="note" title="Nx Cloud required" %}
Nx Agents are part of [Nx Cloud](/docs/getting-started/nx-cloud).
If you haven't set up Nx Cloud yet, see the [getting started guide](/docs/getting-started/nx-cloud).
{% /aside %}

The default Nx Cloud launch templates use the
[`install-node-modules`](https://github.com/nrwl/nx-cloud-workflows/tree/main/workflow-steps/install-node-modules)
workflow step, which doesn't support `bun.lock`.
Create a **[custom launch template](/docs/reference/nx-cloud/launch-templates)**
that installs bun via mise and runs `bun install` directly.

Add `.nx/workflows/agents.yaml` to your workspace:

```yaml
// .nx/workflows/agents.yaml
common-init-steps: &common-init-steps
  - name: Checkout
    uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/checkout/main.yaml'

  - name: Setup toolchains
    uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-mise/main.yaml'

  - name: Install dependencies
    script: |
      bun install --frozen-lockfile

launch-templates:
  linux-large:
    resource-class: 'docker_linux_amd64/large'
    image: 'ubuntu22.04-node24.14-v1'
    init-steps: *common-init-steps
```

The [`install-mise`](https://github.com/nrwl/nx-cloud-workflows/tree/main/workflow-steps/install-mise)
workflow step reads your `mise.toml` and installs the specified toolchains on the agent.
All environments (local, CI, and agents) stay in sync through a single config file.

Reference the template name in your CI workflow:

```shell
npx nx start-ci-run --distribute-on="5 linux-large" --stop-agents-after="e2e"
```

You can define multiple templates with different resource classes for different workloads.
For all available options, see the [launch templates reference](/docs/reference/nx-cloud/launch-templates).

---
<!-- source: https://nx.dev/docs/guides/nx-console.md -->
## Nx Console

{% index_page_cards path="guides/nx-console" /%}

---
<!-- source: https://nx.dev/docs/guides/nx-console/console-generate-command.md -->
## Nx Console Generate Command

The `Generate` action allows you to choose a generator and then opens a form listing out all the options for that generator. As you make changes to the form, the generator is executed in `--dry-run` mode in a terminal so you can preview the results of running the generator in real time.

{% youtube
src="https://www.youtube.com/embed/-nUr66MWRiE"
title="Nx Console Generate UI Form"
/%}

**From the Command Palette**

You can also launch the `Generate` action from the Command Palette (`⇧⌘P`) by selecting `nx: generate (ui)`.

{% youtube
src="https://www.youtube.com/embed/Sk2XjFwF8Zo"
title="Nx Console Generate UI from Command Palette"
/%}

You can even construct the generator options while staying entirely within the Command Palette. Use `⇧⌘P` to open the Command Palette, then select `nx: generate`. After choosing a generator, select any of the listed options to modify the generator command. When you're satisfied with the constructed command, choose the `Execute` command at the top of the list.

{% youtube
src="https://www.youtube.com/embed/q5NTTqRYq9c"
title="Nx Console Generate with Command Palette"
/%}

---
<!-- source: https://nx.dev/docs/guides/nx-console/console-migrate-ui.md -->
## Nx Console Migrate UI

The Nx Console Migrate UI provides a visual, guided way to apply migrations in your Nx workspace. This tool simplifies the process of updating your workspace by offering an easy-to-use interface that walks you through each step of the migration process.

## Starting the migration

The Migrate UI is available for VSCode and Cursor editors. Make sure you have the [Nx Console extension](/docs/getting-started/editor-setup) installed before you continue.

When an update to Nx is available, a badge will appear on the Nx Console icon in your Activity Bar. Bring up the Nx Console view (Hint: type in `> Show Nx Console` in the Command Palette), and you'll see a `Nx Migrate` section in the sidebar. Clicking `Start Migration` starts the migration process.

![](../../../../assets/guides/nx-console/console-migrate-1-start.avif)

By default, clicking the migration button starts the migration process by upgrading to the recommended Nx version — the latest version of the next major release. This method ensures you upgrade one major version at a time in order to [avoid breakages](/docs/guides/tips-n-tricks/advanced-update#one-major-version-at-a-time-small-steps). To customize the version, click the pencil icon to provide a specific version to update to. You may also provide additional CLI options such as `--to` or `--from`.

![](../../../../assets/guides/nx-console/console-migrate-2-customize-version.avif)

{% aside type="note" title="Ensure clean git status" %}
If you have uncommitted changes, stash or commit them before initiating a migration. Otherwise, the migration button will be disabled.
{% /aside %}

Once you start the migration, Nx Console runs the `nx migrate` command to update your dependency versions and generate a `migrations.json` file. You'll be prompted to inspect the changes made to your `package.json` before installing them and proceeding.

![](../../../../assets/guides/nx-console/console-migrate-3-confirm.avif)

## The migration process

After confirming the `package.json` changes, the Migrate UI opens and guides you step-by-step through each migration action. Each migration will be executed in the order as they appear in `migration.json`. If a migration results in file changes, you will be prompted to review the changes before continuing. You can either `Accept` or `Undo` the migration.

![](../../../../assets/guides/nx-console/console-migrate-4-approve.avif)

If a migration step encounters an error, the process pauses so you can inspect the error details.

![](../../../../assets/guides/nx-console/console-migrate-5-error.avif)

You can click through to view the migration source code, giving you the opportunity to patch it for your specific use-case or make necessary adjustments to your repository before rerunning the migration.

Alternatively, you may choose to skip a problematic migration.

## Finalizing the migration

When all migrations are done, or you don't want to run further migrations, you can finish the process by clicking the Finish button. By default, this will squash all commits created during the migration together, but you can opt into preserving them.

You will be prompted for the git commit message, once you enter it the `migrations.json` file is removed and the migration process is finished.

![](../../../../assets/guides/nx-console/console-migrate-6-finish.avif)

---
<!-- source: https://nx.dev/docs/guides/nx-console/console-nx-cloud.md -->
## Nx Console & Nx Cloud Integration

Nx Console for VSCode is integrated with Nx Cloud to help you stay on top of your CI Pipelines without leaving the editor.

If your workspace is connected to Nx Cloud, you will have access to a new view in the Nx Console sidebar that provides at-a-glance information about your running and recent CI pipeline executions.

![Nx Console Nx Cloud View](../../../../assets/guides/nx-console/cloud-view.png)

{% aside type="note" %}
Nx Console will only show information about CI Pipelines from the last hour and triggered from branches that you have modified locally. If you want to see information about other pipelines, use the Nx Cloud application at [cloud.nx.app](https://cloud.nx.app).
{% /aside %}

## Notifications

In addition to the view, you will receive notifications when a pipeline completes or a task in it fails.

![Nx Console Nx Cloud Notifications](../../../../assets/guides/nx-console/cloud-notification.png)

You can click on the buttons to view the results directly in Nx Cloud or open the Pull Request in the browser.

To only be notified on failure or turn off notifications altogether, you can change the `nxConsole.nxCloudNotifications` setting.

## JetBrains

This feature is only available in VSCode but coming soon to JetBrains. For now, you can see whether you're connected to Nx Cloud and navigate directly to the Nx Cloud application from the Nx Console Toolwindow.

---
<!-- source: https://nx.dev/docs/guides/nx-console/console-project-details.md -->
## Nx Console Project Details View

Nx Console provides seamless integration with the [Project Details View](/docs/features/explore-graph#explore-projects-in-your-workspace).
You can learn more about your project, run tasks or navigate the task graph with just a few clicks!

![console-pdv-example.png](../../../../assets/guides/nx-console/console-pdv-example.png)

You can access the integrated Project Details View in multiple ways:

- By clicking on the Preview icon to the top right of your `project.json`, `package.json` or any file that modifies targets (for example `jest.config.ts` or `cypress.config.ts`)
- By using the codelenses in any of these files
- By running the `Nx: Open Project Details to Side` action while any file in a project is open

In addition to viewing the Project Details View, Codelenses in tooling configuration files (like `jest.config.ts`) allow you to run targets via Nx with a single click.
If you would like to disable the Codelens feature, you can do so easily:

- In VSCode, simply turn off the `nxConsole.enableCodeLens` setting
- In JetBrains IDEs, right-click a Codelens and select ``Hide `Code Vision: Nx Config Files` Inlay Hints ``

---
<!-- source: https://nx.dev/docs/guides/nx-console/console-run-command.md -->
## Nx Console Run Command

You can construct the executor command options while staying entirely within the Command Palette. Use `⇧⌘P` to open the Command Palette, then select `Nx: Run`. After choosing a project, select a target and any of the listed options to modify the executor command options. When you're satisfied with the constructed command, choose the `Execute` command at the top of the list.
You can also use `Nx: Run Target` to select a target first and then a matching project.

{% youtube
src="https://www.youtube.com/embed/CsUkSyQcxwQ"
title="Nx Console Run from Command Palette"
/%}

---
<!-- source: https://nx.dev/docs/guides/nx-console/console-telemetry.md -->
## Nx Console Telemetry

To ensure that we focus on creating features that benefit your day-to-day workflow, we collect some data from the Nx Console extensions.

## Collected data

Here's the information we collect for each extension.

### User data

> None of the information that we ask for is used to track any personal information

| Property    | Description                                                                               |
| ----------- | ----------------------------------------------------------------------------------------- |
| Client ID   | These are retrieved by APIs provided by each editor. We do not generate this information. |
| User ID     | We use the same value as the Client ID                                                    |
| Session ID  | Generated UUID                                                                            |
| OS          | What operating system are you using?                                                      |
| Editor      | What editor are you using? Visual Studio Code, Intellij, etc                              |
| App Version | What version of the extension is being used?                                              |

### Event data

| Property            | Description                        |
| ------------------- | ---------------------------------- |
| Extension Activated | Extension activation timings       |
| Action Triggered    | Nx Generate, Nx Run, Nx Graph, etc |

## Visual studio code

For Visual Studio Code, we use the global telemetry setting provided by the editor. This is controlled by the `telemetry.telemetryLevel` setting

#### How to disable telemetry for visual studio code

Setting `telemetry.telemetryLevel` to `off` will disable telemetry for Nx Console in Visual Studio Code. Read more about the telemetry settings in Visual Studio Code [here](https://code.visualstudio.com/docs/getstarted/telemetry#_disable-telemetry-reporting)

## Jetbrains (IntelliJ, webstorm, etc)

When the plugin is first installed, we will prompt you to opt in or out of reporting telemetry.

#### How to disable telemetry for jetbrains editors

To turn off telemetry after opting in, go to **Settings** > **Tools** > **Nx Console** > Uncheck **Enable Telemetry**

---
<!-- source: https://nx.dev/docs/guides/nx-console/console-troubleshooting.md -->
## Troubleshoot Nx Console Issues

Often, issues with Nx Console are the result of underlying issues with Nx. Make sure to read the [Nx installation troubleshooting docs](/docs/troubleshooting/troubleshoot-nx-install-issues) for more help.

## Enable debug logging

If you're experiencing issues with Nx Console, enabling debug logging can help diagnose the problem by providing detailed information about the extension's internal operations.

### VS Code

1. Open Settings (`Ctrl/Cmd + ,`)
2. Search for `nxConsole.enableDebugLogging`
3. Enable the checkbox
4. Restart VS Code or reload the window (`Ctrl/Cmd + Shift + P` → `Developer: Reload Window`)

#### Viewing debug logs

1. Open Command Palette (`Ctrl/Cmd + Shift + P`)
2. Run `View: Toggle Output`
3. Select from the dropdown:
   - **Nx Console** - Main extension output
   - **Nx Language Server** - Language server diagnostics

### JetBrains IDEs (IntelliJ, WebStorm, etc.)

1. Enable verbose logging:
   - Go to `Help` → `Diagnostic Tools` → `Debug Log Settings...`
   - Add: `#dev.nx.console:trace`
   - Click `OK` and restart the IDE
2. Reproduce the issue
3. Access logs via `Help` → `Show Log in Explorer` (Windows) / `Show Log in Finder` (macOS) / `Show Log in Files` (Linux)
4. Look for `idea.log` file and paste relevant sections when reporting issues

## Configuration settings

For a complete reference of all available configuration settings, see the [Nx Console Settings Reference](/docs/reference/nx-console-settings).

## VSCode + nvm issues

VSCode loads a version of Node when it starts. It can use versions set via [`nvm`](https://github.com/nvm-sh/nvm) but there are some caveats.

- If you've installed Node outside of `nvm` (for example using the Node installer or `brew` on Mac), VSCode will always use that version. You can check by running `nvm list` and looking for a `system` alias. To enable VSCode to pick up your `nvm` version, make sure to uninstall the version of Node that was installed outside of `nvm`.
- VSCode will load the `default` alias from `nvm` at startup. You can set it by running `nvm alias default [version]`. The `default` alias needs to be set in your OS' default terminal for VSCode to pick it up. Setting it in a VSCode-integrated terminal won't persist after it's closed. Similarly, setting it in a third-party app like iTerm won't influence VSCode by default.
- VSCode only loads the `default` version when the app is first started. This means that in order to change it, you need to close all VSCode windows and restart the app - running `Reload Window` won't work.
- If you work with lots of different Node versions, there are various VSCode extensions available to dynamically run `nvm use` whenever you open a new integrated terminal. Search for `nvm`.
- You can set a static version by using a launch configuration with `runtimeVersion` set. Refer to [this guide](https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_multi-version-support).

We try to make noticing discrepancies easier by showing you the currently loaded Node version on startup. To enable this, toggle the `nxConsole.showNodeVersionOnStartup` setting in VSCode.

## JetBrains WSL support

The Node interpreter under Languages & Frameworks > Node.js needs to be configured to use the Node executable within the WSL distribution. You can read more on the [official Jetbrains docs](https://www.jetbrains.com/help/webstorm/how-to-use-wsl-development-environment-in-product.html#ws_wsl_node_interpreter_configure).

---
<!-- source: https://nx.dev/docs/guides/nx-release.md -->
## Nx Release

{% index_page_cards path="guides/nx-release" /%}

---
<!-- source: https://nx.dev/docs/guides/nx-release/automate-github-releases.md -->
## Automate GitHub Releases

Nx Release can automate the creation of [GitHub releases](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) for you. GitHub releases are a great way to communicate the changes in your projects to your users.

## Authenticating with GitHub

In order to be able to create the release on GitHub, you need to provide a valid token which can be used for authenticating with the GitHub API.

Nx release supports two main ways of doing this:

1. In all environments it will preferentially check for an environment variable (the environment variable can either be called `GITHUB_TOKEN` or `GH_TOKEN`). Please ensure that this environment variable is set in your CI environment (and that the token it has been set to has been configured with the appropriate permissions to create releases) before attempting to create a release in CI.
2. It can also detect if you have a valid, authenticated installation of the [official `gh` CLI tool](https://cli.github.com), and leverage that automatically as a fallback when no environment variable is set.

## GitHub release contents

When a GitHub release is created, it will include the changelog that Nx Release generates with entries based on the changes since the last release. Nx Release will parse the `feat` and `fix` type commits according to the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification and sort them into appropriate sections of the changelog. Take a look at the [Nx releases page](https://github.com/nrwl/nx/releases) to see examples of GitHub releases generated by Nx Release.

## Enable release creation

To enable GitHub release creation for your workspace, set `release.changelog.workspaceChangelog.createRelease` to `'github'` in `nx.json`:

```jsonc
// nx.json
{
  "release": {
    "changelog": {
      "workspaceChangelog": {
        "createRelease": "github",
      },
    },
  },
}
```

## Preview the release

Use `nx release --dry-run` to preview the GitHub release instead of creating it. This allows you to see what the release will look like without pushing anything to GitHub.

## Disable file creation

Since GitHub releases contain the changelog, you may wish to disable the generation and management of local the `CHANGELOG.md` file. To do this, set `release.changelog.workspaceChangelog.file` to `false` in `nx.json`:

```jsonc
// nx.json
{
  "release": {
    "changelog": {
      "workspaceChangelog": {
        "file": false,
        "createRelease": "github",
      },
    },
  },
}
```

Note: When configured this way, Nx Release will not delete existing changelog files, just ignore them.

## Project level changelogs

Nx Release supports creating GitHub releases for project level changelogs as well. This is particularly useful when [releasing projects independently](/docs/guides/nx-release/release-projects-independently). To enable this, set `release.changelog.projectChangelogs.createRelease` to `'github'` in `nx.json`:

```jsonc
// nx.json
{
  "release": {
    "changelog": {
      "projectChangelogs": {
        "createRelease": "github",
      },
    },
  },
}
```

{% aside type="caution" title="Project and Workspace GitHub Releases" %}
Nx Release does not support creating GitHub releases for both project level changelogs and the workspace changelog. You will need to choose one or the other.
{% /aside %}

## Customizing the GitHub instance to use GitHub enterprise server

If you are not using github.com, and instead using a self-hosted GitHub Enterprise Server instance, you can use a configuration object instead of the string for "createRelease" to provide the relevant hostname, and optionally override the API base URL, although this is not typically needed as it will default to `https://${hostname}/api/v3`.

```jsonc
// nx.json
{
  "release": {
    "changelog": {
      "workspaceChangelog": {
        "createRelease": {
          "provider": "github-enterprise-server",
          "hostname": "github.example.com",
        },
      },
    },
  },
}
```

---
<!-- source: https://nx.dev/docs/guides/nx-release/automate-gitlab-releases.md -->
## Automate GitLab Releases

Nx Release can automate the creation of [GitLab releases](https://docs.gitlab.com/user/project/releases/) for you. GitLab releases are a great way to communicate the changes in your projects to your users.

## Authenticating with GitLab

In order to be able to create the release on GitLab, you need to provide a valid token which can be used for authenticating with the GitLab API.

Nx release supports two main ways of doing this:

1. In all environments it will preferentially check for an environment variable (the environment variable can either be called `GITLAB_TOKEN` or `GL_TOKEN`).
2. In GitLab CI it will check for and use the automatically created GitLab token in the `CI_JOB_TOKEN` environment variable.

## GitLab release contents

When a GitLab release is created, it will include the changelog that Nx Release generates with entries based on the changes since the last release. Nx Release will parse the `feat` and `fix` type commits according to the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification and sort them into appropriate sections of the changelog.

## Enable release creation

To enable GitLab release creation for your workspace, set `release.changelog.workspaceChangelog.createRelease` to `'gitlab'` in `nx.json`:

```jsonc
// nx.json
{
  "release": {
    "changelog": {
      "workspaceChangelog": {
        "createRelease": "gitlab",
      },
    },
  },
}
```

## Preview the release

Use `nx release --dry-run` to preview the GitLab release instead of creating it. This allows you to see what the release will look like without pushing anything to GitLab.

## Disable file creation

Since GitLab releases contain the changelog, you may wish to disable the generation and management of the local `CHANGELOG.md` file. To do this, set `release.changelog.workspaceChangelog.file` to `false` in `nx.json`:

```jsonc
// nx.json
{
  "release": {
    "changelog": {
      "workspaceChangelog": {
        "file": false,
        "createRelease": "gitlab",
      },
    },
  },
}
```

Note: When configured this way, Nx Release will not delete existing changelog files, just ignore them.

## Project level changelogs

Nx Release supports creating GitLab releases for project level changelogs as well. This is particularly useful when [releasing projects independently](/docs/guides/nx-release/release-projects-independently). To enable this, set `release.changelog.projectChangelogs.createRelease` to `'gitlab'` in `nx.json`:

```jsonc
// nx.json
{
  "release": {
    "changelog": {
      "projectChangelogs": {
        "createRelease": "gitlab",
      },
    },
  },
}
```

{% aside type="caution" title="Project and Workspace GitLab Releases" %}
Nx Release does not support creating GitLab releases for both project level changelogs and the workspace changelog. You will need to choose one or the other.
{% /aside %}

## Customizing the GitLab instance

If you are not using gitlab.com, and are instead using a self-hosted GitLab instance, you can use a configuration object instead of the string for "createRelease" to provide the relevant hostname, and optionally override the API base URL, although this is not typically needed as it will default to `https://${hostname}/api/v4`.

```jsonc
// nx.json
{
  "release": {
    "changelog": {
      "workspaceChangelog": {
        "createRelease": {
          "provider": "gitlab",
          "hostname": "gitlab.example.com",
        },
      },
    },
  },
}
```

---
<!-- source: https://nx.dev/docs/guides/nx-release/automatically-version-with-conventional-commits.md -->
## Automatically Version with Conventional Commits

If you wish to bypass the versioning prompt, you can configure Nx Release to defer to the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard to determine the version bump automatically. This is useful for automating the versioning process in a CI/CD pipeline. See the [`nx release version`](/docs/reference/nx-commands#nx-release-version) CLI reference for all available versioning options.

## Enable automatic versioning

To enable automatic versioning via conventional commits, set the `release.version.conventionalCommits` property to `true` in `nx.json`:

```json
// nx.json
{
  "release": {
    "version": {
      "conventionalCommits": true
    }
  }
}
```

## Determine the version bump

Nx Release will use the commit messages since the last release to determine the version bump. It will look at the type of each commit and determine the highest version bump from the following list:

- 'feat' -> minor
- 'fix' -> patch

For example, if the git history looks like this:

```text
  - fix(pkg-1): fix something
  - feat(pkg-2): add a new feature
  - chore(pkg-3): update docs
  - chore(release): 1.0.0
```

then Nx Release will select the `minor` version bump and elect to release version 1.1.0. This is because there is a `feat` commit since the last release of 1.0.0. To customize the version bump for different types of commits, or to trigger a version bump with custom commit types, see the [Customize Conventional Commit Types](/docs/guides/nx-release/customize-conventional-commit-types) recipe.

{% aside type="note" title="No changes detected" %}
If Nx Release does not find any relevant commits since the last release, it will skip releasing a new version. This works with [independent releases](/docs/guides/nx-release/release-projects-independently) as well, allowing for only some projects to be released and some to be skipped.
{% /aside %}

## Usage with independent releases

If you are using [independent releases](/docs/guides/nx-release/release-projects-independently), Nx Release will determine the version bump for each project independently. For example, if the git history looks like this:

```text
  - fix(pkg-1): fix something
  - feat(pkg-2): add a new feature
  - chore(pkg-3): update docs
  - chore(release): publish
```

Nx Release will select the `patch` version bump for `pkg-1` and `minor` for `pkg-2`. `pkg-3` will be skipped entirely, since it has no `feat` or `fix` commits.

{% aside type="note" title="Determining if a commit affects a project" %}
Note that this determination is made based on files changed by each commit, _not_ by the scope of the commit message itself. This means that `feat(pkg-2): add a new feature` could trigger a version bump for a project other than `pkg-2` if it updated files in another project.
{% /aside %}

An example partial output of running Nx Release with independent releases and conventional commits enabled:

```plaintext {% frame="terminal" title="nx release" %}

 NX   Running release version for project: pkg-1

pkg-1 🏷️ Resolved the current version as 0.4.0 from git tag "pkg-1@0.4.0", based on releaseTag.pattern "{projectName}@{version}"
pkg-1 📄 Resolved the specifier as "patch" using git history and the conventional commits standard
pkg-1 ❓ Applied semver relative bump "patch", derived from conventional commits data, to get new version 0.4.1
pkg-1 ✍️ New version 0.4.1 written to manifest: packages/pkg-1/package.json

 NX   Running release version for project: pkg-2

pkg-2 🏷️ Resolved the current version as 0.4.0 from git tag "pkg-2@0.4.0", based on releaseTag.pattern "{projectName}@{version}"
pkg-2 📄 Resolved the specifier as "minor" using git history and the conventional commits standard
pkg-2 ❓ Applied semver relative bump "minor", derived from conventional commits data, to get new version 0.5.0
pkg-2 ✍️ New version 0.5.0 written to manifest: packages/pkg-2/package.json

 NX   Running release version for project: pkg-3

pkg-3 🏷️ Resolved the current version as 0.4.0 from git tag "pkg-3@0.4.0", based on releaseTag.pattern "{projectName}@{version}"
pkg-3 🚫 No changes were detected using git history and the conventional commits standard

```

---
<!-- source: https://nx.dev/docs/guides/nx-release/build-before-versioning.md -->
## Build Before Versioning

In order to ensure that projects are built before the new version is applied to their package manifest, you can use the `preVersionCommand` property in `nx.json`:

```json
// nx.json
{
  "release": {
    "version": {
      "preVersionCommand": "npx nx run-many -t build"
    }
  }
}
```

This command will run the `build` target for all projects before the version step of Nx Release. Any command can be specified, including non-nx commands. This step is often required when [publishing from a custom dist directory](/docs/guides/nx-release/updating-version-references#scenario-2-i-want-to-publish-from-a-custom-dist-directory-and-update-references-in-my-both-my-source-and-dist-packagejson-files), as the dist directory must be built before the version is applied to the dist directory's package manifest.

When using release groups in which the member projects are versioned together, you can use `groupPreVersionCommand` and it will be executed before the versioning step for that release group.

```json
// nx.json
{
  "release": {
    "groups": {
      "my-group": {
        "projects": ["my-lib-one", "my-lib-two"],
        "version": {
          "groupPreVersionCommand": "npx nx run-many -t build -p my-lib-one,my-lib-two"
        }
      }
    }
  }
}
```

The `groupPreVersionCommand` will run in addition to the global `preVersionCommand`.

## Build before Docker versioning

In order to ensure that images are built before versioning, use the `preVersionCommand` property in the `docker` section of `nx.json`.

```jsonc
// nx.json
{
  "release": {
    "docker": {
      "preVersionCommand": "npx nx run-many -t docker:build",
    },
  },
}
```

If `preVersionCommand` is not set, the default is `npx nx run-many -t docker:build`, which builds all projects with a `docker:build` target. You can customize this command to be anything that runs prior to Docker versioning.

When using release groups with Docker, use the `groupPreVersionCommand` option to run a command before the versioning step for that group.

```jsonc
// nx.json
{
  "release": {
    "groups": {
      "my-group": {
        "projects": ["api", "microservice"],
        "docker": {
          "groupPreVersionCommand": "npx nx run-many -t docker:build -p api,microservice",
        },
      },
    },
  },
}
```

The `groupPreVersionCommand` will run in addition to the global `preVersionCommand` for Docker.

---
<!-- source: https://nx.dev/docs/guides/nx-release/configuration-version-prefix.md -->
## Configuring Version Prefix for Dependencies

This guide explains how to configure a custom version prefix in Nx Release using the `versionPrefix` option. The version prefix allows you to automatically add a specific prefix format to dependencies, providing control over how dependency versions are specified in your project's manifest files (such as `package.json`, `Cargo.toml`, etc.).

## The `versionPrefix` option

The `versionPrefix` option controls which prefix is applied to dependency versions during the versioning process. By default, `versionPrefix` is set to `"auto"`, which selects a prefix format (either `""`, `"~"`, `"^"`, or `"="`) by respecting what is already in the manifest file.

For example, having the following `package.json` file as an example manifest:

```json
{
  "name": "my-package",
  "version": "0.1.1",
  "dependencies": {
    "dependency-one": "~1.2.3",
    "dependency-two": "^2.3.4",
    "dependency-three": "3.0.0"
  }
}
```

Then next patch bump will be:

```json
{
  "name": "my-package",
  "version": "0.1.2",
  "dependencies": {
    "dependency-one": "~1.2.4",
    "dependency-two": "^2.3.4",
    "dependency-three": "3.0.0"
  }
}
```

Preserving the prefix for `dependency-one` and `dependency-two` and continuing to use no prefix for `dependency-three`.

### Available prefix options

You can set `versionPrefix` to one of the following values:

- `"auto"`: Automatically chooses a prefix based on the existing declaration in the manifest file. This is the default value.
- `""`: Uses the exact version without a prefix.
- `"~"`: Specifies compatibility with patch-level updates.
- `"^"`: Specifies compatibility with minor-level updates.
- `"="`: Locks the version to an exact match (the `=` is not commonly used in the JavaScript ecosystem, but is in others such as Cargo for Rust).

Example configuration:

```json
// nx.json
{
  "release": {
    "version": {
      "versionPrefix": "~"
    }
  }
}
```

## Configuring version prefix in `nx.json` or `project.json`

To set the versionPrefix option globally or for a specific project, add it to either your `nx.json` or `project.json` configuration files:

```jsonc
{
  "release": {
    "version": {
      "versionPrefix": "^", // or "", "~", "^", "=" depending on your preference
    },
  },
}
```

With the `versionPrefix` option set to `^`, your `package.json` dependencies might look like this:

```json
{
  "name": "my-package",
  "version": "0.1.1",
  "dependencies": {
    "dependency-one": "^1.0.0",
    "dependency-two": "^2.3.4",
    "dependency-three": "^3.0.0"
  }
}
```

This configuration helps enforce a consistent approach to dependency management, allowing flexibility in how updates to dependencies are tracked and managed across your project.

---
<!-- source: https://nx.dev/docs/guides/nx-release/configure-changelog-format.md -->
## Configure Changelog Format

The default changelog renderer for `nx release` generates a changelog entry for each released project similar to the following:

```md
## 7.9.0 (2024-05-13)

### 🚀 Features

- **rule-tester:** check for missing placeholder data in the message ([#9039](https://github.com/typescript-eslint/typescript-eslint/pull/9039))

### ❤️ Thank You

- Kirk Waiblinger
- Sheetal Nandi
- Vinccool96
```

## Include all metadata

There are a few options available to modify the default changelog renderer output. They can be applied to both `workspaceChangelog` and `projectChangelogs` in exactly the same way. All four options are true by default:

```json
// nx.json
{
  "release": {
    "changelog": {
      "projectChangelogs": {
        "renderOptions": {
          "authors": true,
          "applyUsernameToAuthors": true,
          "commitReferences": true,
          "versionTitleDate": true
        }
      }
    }
  }
}
```

#### `authors`

Whether the commit authors should be added to the bottom of the changelog in a "Thank You" section. Defaults to `true`.

#### `applyUsernameToAuthors`

If authors is enabled, controls whether or not to try to map the authors to their GitHub usernames using https://ungh.cc (from https://github.com/unjs/ungh) and the email addresses found in the commits. Defaults to `true`.

You should disable this option if you don't want to make any external requests to https://ungh.cc

NOTE: Prior to Nx v21, this option was named `mapAuthorsToGitHubUsernames`.

#### `commitReferences`

Whether the commit references (such as commit and/or PR links) should be included in the changelog. Defaults to `true`.

#### `versionTitleDate`

Whether to include the date in the version title. It can be set to `false` to disable it, or `true` to enable with the default of (YYYY-MM-DD). Defaults to `true`.

## Remove all metadata

If you prefer a more minimalist changelog, you can set all the options to false, like this:

```json
// nx.json
{
  "release": {
    "changelog": {
      "projectChangelogs": {
        "renderOptions": {
          "authors": false,
          "applyUsernameToAuthors": false,
          "commitReferences": false,
          "versionTitleDate": false
        }
      }
    }
  }
}
```

Which will generate a changelog that looks similar to the following:

```md
## 7.9.0

### 🚀 Features

- **rule-tester:** check for missing placeholder data in the message
```

## Custom changelog renderer {% badge  text="Nx 22+" /%}

For complete control over changelog formatting, you can provide a custom changelog renderer implementation. The renderer can be specified as a path to a module that exports a class extending the base `ChangelogRenderer`.

```jsonc
{
  "release": {
    "changelog": {
      "projectChangelogs": {
        "renderer": "./tools/custom-changelog-renderer.ts",
      },
    },
  },
}
```

Your custom renderer must extend the `ChangelogRenderer` class and implement the required methods:

```typescript
// tools/custom-changelog-renderer.ts
import { ChangelogRenderer, ChangelogRenderOptions } from '@nx/js/release';

export default class CustomChangelogRenderer extends ChangelogRenderer {
  async renderMarkdown(
    changes: any[],
    options: ChangelogRenderOptions
  ): Promise<string> {
    // Your custom changelog generation logic
    return '# My Custom Changelog\n\n...';
  }
}
```

{% aside type="note" title="Programmatic API" %}
When using the programmatic `ReleaseClient` API (Nx 22+), you can also pass the renderer implementation class directly instead of a file path, allowing for dynamic renderer selection without file system access.
{% /aside %}

---
<!-- source: https://nx.dev/docs/guides/nx-release/configure-custom-registries.md -->
## Configure Custom Registries

To publish JavaScript packages, Nx Release uses the `npm` CLI under the hood, which defaults to publishing to the `npm` registry (`https://registry.npmjs.org/`). If you need to publish to a different registry, you can configure the registry in the `.npmrc` file in the root of your workspace or at the project level in the project configuration.

## Set the registry in the root .npmrc file

The easiest way to configure a custom registry is to set it in the `npm` configuration via the root `.npmrc` file. This file is located in the root of your workspace, and Nx Release will use it for publishing all projects. To set the registry, add the 'registry' property to your root `.npmrc` file:

```bash
// .npmrc
registry=https://my-custom-registry.com/
```

### Authenticate to the Registry in CI

To authenticate with a custom registry in CI, you can add authentication tokens to the `.npmrc` file:

```bash
// .npmrc
registry=https://my-custom-registry.com/
//my-custom-registry.com/:_authToken=<TOKEN>
```

See the [npm documentation](https://docs.npmjs.com/cli/v10/configuring-npm/npmrc#auth-related-configuration) for more information.

## Configure multiple registries

The recommended way to determine which registry packages are published to is by using [npm scopes](https://docs.npmjs.com/cli/v10/using-npm/scope). All packages with a name that starts with your scope will be published to the registry specified in the `.npmrc` file for that scope. Consider the following example:

```bash
// .npmrc
@my-scope:registry=https://my-custom-registry.com/
//my-custom-registry.com/:_authToken=<TOKEN>

@other-scope:registry=https://my-other-registry.com/
//my-other-registry.com/:_authToken=<OTHER_TOKEN>

registry=https://my-default-registry.com/
//my-default-registry.com/:_authToken=<DEFAULT_TOKEN>
```

With the above `.npmrc`, the following packages would be published to the specified registries:

- `@my-scope/pkg-1` -> `https://my-custom-registry.com/`
- `@other-scope/pkg-2` -> `https://my-other-registry.com/`
- `pkg-3` -> `https://my-default-registry.com/`

## Specify an alternate registry for a single package

In some cases, you may want to configure the registry on a per-package basis instead of by scope. This can be done by setting options in the project's configuration.

{% aside type="note" title="Authentication" %}
All registries set for specific packages must still have authentication tokens set in the root `.npmrc` file for publishing in CI. See [Authenticate to the Registry in CI](#authenticate-to-the-registry-in-ci) for an example.
{% /aside %}

### Set the registry in the project configuration

The project configuration for Nx Release is in two parts - one for the version step and one for the publish step.

#### Update the version step

The version step of Nx Release is responsible for determining the new version of the package. If you have set the `version.currentVersionResolver` to 'registry', then Nx Release will check the remote registry for the current version of the package.

**Note:** If you do not use the 'registry' current version resolver, then this step is not needed.

To set custom registry options for the current version lookup, add the registry and/or tag to the `currentVersionResolverMetadata` in the project configuration:

```json
// project.json
{
  "name": "pkg-5",
  "sourceRoot": "...",
  "targets": {
    ...
  },
  "release": {
    "version": {
      "currentVersionResolverMetadata": {
        "registry": "https://my-unique-registry.com/",
        "tag": "next"
      }
    }
  }
}
```

#### Update the publish step

The publish step of Nx Release is responsible for publishing the package to the registry. To set custom registry options for publishing, you can add the `registry` and/or `tag` options for the `nx-release-publish` target in the project configuration:

```json
// project.json
{
  "name": "pkg-5",
  "sourceRoot": "...",
  "targets": {
    ...,
    "nx-release-publish": {
      "options": {
        "registry": "https://my-unique-registry.com/",
        "tag": "next"
      }
    }
  }
}
```

### Set the registry in the package manifest

It is not recommended to set the registry for a package in the `publishConfig` property of its `package.json` file. `npm publish` will always prefer the registry from the `publishConfig` over the `--registry` argument.
Because of this, the `--registry` CLI and programmatic API options of Nx Release will no longer be able to override the registry for purposes such as publishing locally for end to end testing.

---
<!-- source: https://nx.dev/docs/guides/nx-release/customize-conventional-commit-types.md -->
## Customize Conventional Commit Types

[Nx release](/docs/features/manage-releases) allows you to leverage the [conventional commits](/docs/guides/nx-release/automatically-version-with-conventional-commits) standard to automatically determine the next version increment.

By default, this results in:

- `feat(...)` triggering a minor version bump (`1.?.0`)
- `fix(...)` triggering a patch version bump (`1.?.x`)
- `BREAKING CHANGE` in the footer of the commit message or with an exclamation mark after the commit type (`fix(...)!`) triggers a major version bump (`?.0.0`)

{% aside type="note" title="No changes detected" %}
If Nx Release does not find any relevant commits since the last release, it will skip releasing a new version. This works with [independent releases](/docs/guides/nx-release/release-projects-independently) as well, allowing for only some projects to be released while others are skipped.
{% /aside %}

However, you can customize how Nx interprets these conventional commits, for both **versioning** and **changelog** generation.

## Disable a commit type for versioning and changelog generation

To disable a commit type, set it to `false`.

```json
// nx.json
{
  "release": {
    "conventionalCommits": {
      "types": {
        // disable the docs type for versioning and in the changelog
        "docs": false,
        ...
      }
    }
  }
}
```

If you just want to disable a commit type for versioning, but still want it to appear in the changelog, set `semverBump` to `none`.

```json
// nx.json
{
  "release": {
    "conventionalCommits": {
      "types": {
        // disable the docs type for versioning, but still include it in the changelog
        "docs": {
          "semverBump": "none",
          ...
        },
        ...
      }
    }
  }
}
```

## Changing the type of semver version bump

Assume you'd like `docs(...)` commit types to cause a `patch` version bump. You can define that as follows:

```json
// nx.json
{
  "release": {
    "conventionalCommits": {
      "types": {
        "docs": {
          "semverBump": "patch",
          ...
        },
      }
    }
  }
}
```

## Renaming the changelog section for a commit type

To rename the changelog section for a commit type, set the `title` property.

```json
// nx.json
{
  "release": {
    "conventionalCommits": {
      "types": {
        ...
        "docs": {
          ...
          "changelog": {
            "title": "Documentation Changes"
          }
        },
        ...
      }
    }
  }
}
```

## Hiding a commit type from the changelog

To hide a commit type from the changelog, set `changelog` to `false`.

```json
// nx.json
{
  "release": {
    "conventionalCommits": {
      "types": {
        ...
        "chore": {
          "changelog": false
        },
        ...
      }
    }
  }
}
```

Alternatively, you can set `hidden` to `true` to achieve the same result.

```json
// nx.json
{
  "release": {
    "conventionalCommits": {
      "types": {
        ...
        "chore": {
          "changelog": {
            "hidden": true
          }
        },
        ...
      }
    }
  }
}
```

## Defining non-standard commit types

If you want to use custom, non-standard conventional commit types, you can define them in the `types` object. If you don't specify a `semverBump`, Nx will default to `patch`.

```json
// nx.json
{
  "release": {
    "conventionalCommits": {
      "types": {
        "awesome": {}
      }
    }
  }
}
```

## Including invalid commits in the changelog

Nx Release ignores all commits that do not conform to the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) standard by default. A special `__INVALID__` type is available in situations where you want to process invalid messages.

{% aside type="caution" title="Invalid != Unmatched" %}
This type will only include **invalid** commits. _e.g. those that do not follow the `<type>: <message>...` format._ Commits that are otherwise valid, but with a type that is not enabled, will not be matched by this group.
{% /aside %}

This can be useful in cases where you have not managed to be consistent with your use of the Conventional Commits standard (e.g. when applying it retroactively to an existing codebase) but still want a changelog to be generated with the contents of each commit message and/or for invalid commits to still affect project versioning.

{% aside type="note" title="Alternative to Conventional Commits" %}
If you cannot adhere to the Conventional Commits standard for your commits, file based versioning via Nx Release Version Plans could be a good alternative for managing your releases. See our docs on [File Based Versioning](/docs/guides/nx-release/file-based-versioning-version-plans) for more information.
{% /aside %}

```json
// nx.json
{
  "release": {
    "conventionalCommits": {
      "types": {
        "__INVALID__": {
          "semverBump": "patch", // Note: the default is "none"
          "changelog": {
            "title": "Uncategorized changes"
          }
        }
      }
    }
  }
}
```

---
<!-- source: https://nx.dev/docs/guides/nx-release/file-based-versioning-version-plans.md -->
## File Based Versioning (Version Plans)

Tools such as Changesets and Beachball helped popularize the concept of tracking the desired semver version bump in a separate file on disk (which is committed to your repository alongside your code changes). This has the advantage of separating the desired bump from your git commits themselves, which can be very useful if you are not able to enforce that all contributors follow a strict commit message format ([e.g. Conventional Commits](/docs/guides/nx-release/automatically-version-with-conventional-commits)), or if you want multiple commits to be included in the same version bump and therefore not map commits 1:1 with changelog entries.

Nx release supports file based versioning as a first class use-case through a feature called "version plans". The idea behind the name is that you are creating a _plan_ to version; a plan which will be _applied_ sometime in the future when you actually invoke the `nx release` CLI or programmatic API. Therefore you can think about version plans as having two main processes:

- creating version plans and
- applying version plans.

Both in this recipe, but first we need to enable the feature itself.

## Enable version plans

To enable version plans as a feature in your workspace, set `release.versionPlans` to `true` in `nx.json`:

```jsonc
// nx.json
{
  "release": {
    "versionPlans": true,
    // other release config such as projects to include in releases etc
    // projects: ["packages/**/*"]
    // ...
  },
}
```

You can also enable or disable this for specific release groups by setting the property at the group level if you don't want to apply it to all matching projects in your workspace.

## Create version plans

Version plan files live in the `.nx/version-plans/` directory within your workspace (which needs to be tracked by git, so ensure that you are not ignoring the whole `.nx` directory, and instead only the `.nx/workspace-data` and `.nx/cache` directories).

The files themselves are written in markdown (`.md` files) and contain Front Matter YAML metadata at the top of the file. The Front Matter YAML section is denoted via triple dashes `---` at the start and end of the section. For example:

```md
## // .nx/version-plans/version-plan-1723732065047.md

#

# FRONT MATTER YAML HERE

#

---

#

# Regular markdown here

#
```

We leverage the Front Matter YAML section to store a mapping of project or release group names to desired semver bump types. The general markdown section represents the description of the change(s) made that will be used in any relevant `CHANGELOG.md` files that are generated later at release time.

For example, the following Front Matter YAML section specifies that the `my-app` project should have a `minor` version bump and describes the changes (again, note that there are no constraints on the format of the description, it can contain multiple lines, paragraphs etc):

```md
## // .nx/version-plans/version-plan-1723732065047.md

## my-app: minor

This is an awesome change!

A new paragraph describing the change in greater detail. All of this will be included in the CHANGELOG.md. All of this structure within the markdown section is optional and flexible.
```

Any number of different projects and different desired semver bumps can be combined within a single version plan file (which represents one change and therefore changelog entry, if applicable). For example:

```md
## // .nx/version-plans/version-plan-1723732065047.md

my-app: minor
my-lib: patch
release-group-a: major

---

One change that affects multiple projects and release groups.
```

The project or release group names specified in the Front Matter YAML section must match the names of the projects and/or release groups in your workspace. If a project or release group is not found, an error will be thrown when applying the version plan as part of running `nx release`.

{% aside type="note" title="Single Version for All Packages" %}

If you use a single version for all your packages (see [Release projects independetly](/docs/guides/nx-release/release-projects-independently)) your version plan file might look like this:

```md
## // .nx/version-plans/version-plan-1723732065047.md

## **default**: minor

This is an awesome change!
```

While you could still specify the name of the project it is redundant in this case because all projects will be bumped to the same version.

{% /aside %}

Because these are just files, they can be created manually or by any custom scripts you may wish to write. They simply have to follow the guidance above around structure, location (`./.nx/version-plans/`) and naming (`.md` extension). The exact file name does not matter, it just needs to be unique within the `.nx/version-plans/` directory.

To make things easier, Nx release comes with a built in command to help you generate valid version plan files. See the [`nx release plan`](/docs/reference/nx-commands#nx-release-plan) CLI reference for all available options.

```shell
nx release plan
```

When you run this command you will receive a series of interactive prompts which guide you through the process of creating a version plan file. It will generate a unique name for you and ensure it is written to the correct location.

## Apply version plans at release time

Using version plans does not change how versioning, changelog generation and publishing is invoked, you can still use the `nx release` CLI or programmatic API as you would for any other versioning strategy.

The only difference is that Nx release will know to reference your version plan files as the source of truth for the desired version bumps. You still retain the same control around resolving the current version (disk vs registry vs git tags) however you want, and other configuration options around things like git operations are all still applicable.

When you run `nx release` or use the programmatic API, Nx will look for version plan files in the `.nx/version-plans/` directory and apply the desired version bumps to the projects and release groups specified in the Front Matter YAML section of each file. If a project or release group is not found, an error will be thrown and the release will not proceed. Once a particular version plan has been applied it will be deleted from the `.nx/version-plans/` directory so that it does not inadvertently get applied again in the future. The deleted file will be staged and committed alongside your other changed files that were modified directly as part of the release command (depending on your Nx release configuration).

## Ensure that version plans exist for relevant changes

When making changes to your codebase and using version plans as your versioning strategy it is likely that you will want to ensure that a version plan file exists for the changes you are making.

Attempting to keep track of this manually as a part of pull request reviews can be error prone and time consuming, therefore Nx release provides a `nx release plan:check` command which can be used to ensure that a version plan file exists for the changes you are making.

```shell
nx release plan:check
```

Running this command will analyze the changed files (supporting the same options you may be familiar with from `nx affected`, such as `--base`, `--head`, `--files`, `--uncommitted`, etc) and then determine which projects have been "touched" as a result. Note that it is specifically touched projects, and not affected in this case, because only directly changed projects are relevant for versioning. The side-effects of versioning independently released dependents are handled by the release process itself (controllable via the `version.updateDependents` option).

### Running release plan:check in CI

As mentioned, `nx release plan:check` supports the same options as `nx affected` for determining the range of commits to consider. Therefore, in CI, you must also ensure that the base and head are set appropriately just like you would for `nx affected`.

For GitHub Actions, we provide a utility action to do this for you:

```yaml
# ...other steps
- uses: nrwl/nx-set-shas@v4
# ...other steps including the use of `nx release plan:check`
```

For CircleCI, you can reference our custom orb as a step:

```yaml
# ...other steps
- nx/set-shas
# ...other steps including the use of `nx release plan:check`
```

You can read more about these utilities and why they are needed on their respective READMEs:

- https://github.com/nrwl/nx-set-shas?tab=readme-ov-file#background
- https://github.com/nrwl/nx-orb#background

Nx release will compare the touched projects to the projects and release groups that are specified in the version plan files in the `.nx/version-plans/` directory. If a version plan file does not exist, the command will print an error message and return a non-zero exit code, which can be used to fail CI builds or other automation.

By default, all files that have changed are considered, but you may not want all files under a project to require a version plan be created for them. For example, you may wish to ignore test only files from consideration from this check. The way you can achieve this is by setting version plans to be a configuration object instead of a boolean, and set the `ignorePatternsForPlanCheck` property to an array of glob patterns that should be ignored when checking for version plans. For example:

```jsonc
{
  "release": {
    "versionPlans": {
      "ignorePatternsForPlanCheck": ["**/*.spec.ts"],
    },
  },
}
```

{% aside type="caution" title="Important: Pattern Syntax" %}

The `ignorePatternsForPlanCheck` patterns follow [gitignore semantics](https://git-scm.com/docs/gitignore). When using negation patterns (patterns starting with `!`) to "un-ignore" certain files, be aware that:

**Working patterns:**

- `["**/*.spec.ts"]` - ignore all spec files
- `["**/*.ts", "!**/src/**"]` - ignore all .ts files except those in src/ directories

**Non-working patterns:**

- `["*", "!src/"]` - this does NOT work as expected because `*` in gitignore matches at the root level and negation patterns cannot properly un-ignore nested paths

If you want to ignore all files except those in specific directories, use file extension patterns instead of wildcards:

```jsonc
{
  "release": {
    "versionPlans": {
      "ignorePatternsForPlanCheck": ["**/*.ts", "**/*.json", "!**/src/**"],
    },
  },
}
```

{% /aside %}

To see more details about the changed files that were detected and the filtering logic that was used to determine the ultimately changed projects behind the scenes, you can pass `--verbose` to the command:

```shell
nx release plan:check --verbose
```

---
<!-- source: https://nx.dev/docs/guides/nx-release/programmatic-api.md -->
## Programmatic API

{% aside type="note" title="Learn about Nx Release" %}
Be sure to read our introduction to [Nx Release](/docs/features/manage-releases) to understand the basics of how Nx Release works and the different phases of a release before moving onto the programmatic API.
{% /aside %}

A powerful feature of Nx Release is the fact that it is designed to be used via a Node.js programmatic API in addition to the [`nx release`](/docs/reference/nx-commands#nx-release) CLI.

Releases are a hugely complex and nuanced process, filled with many special cases and idiosyncratic preferences, and it is impossible for a CLI to be able to support all of them out of the box. By having a first-class programmatic API, you can go beyond the CLI and create custom release workflows that are highly dynamic and tailored to your specific needs.

Just as with the CLI, the programmatic API is broken up into the distinct phases of a release: versioning, changelog generation, and publishing. These are available via the `releaseChangelog`, `releasePublish`, and `releaseVersion` functions, which are importable from the `nx/release` entrypoint.

These functions are the exact functions used behind the scenes by the CLI, and so they will read from the "release" config in `nx.json` in just the same way. If you need even more fine grained control over configuration via the programmatic API, see the section on using the [`ReleaseClient` class](#using-the-releaseclient-class) below.

## Using the programmatic API

```ts
import { releaseChangelog, releasePublish, releaseVersion } from 'nx/release';
```

The functions are all asynchronous and return data relevant to their specific phase of the release process. They all support `dryRun` and `verbose` boolean options. For `releaseVersion` and `releaseChangelog`, `dryRun` prevents changes from being applied. For `releasePublish`, `dryRun` is forwarded to the underlying executor (see the [releasePublish section](#releasepublish) for important details). You can inspect their types to see what each one supports in terms of additional config options.

{% aside type="caution" title="Project or Group Filtering" %}
If you apply project or group filtering to the programmatic API via the `projects` or `groups` options that each function supports, be sure to pass the same filters to all three functions.
{% /aside %}

### releaseVersion

`releaseVersion` will return a `NxReleaseVersionResult` object containing the following properties:

- `workspaceVersion`: The new overall version of the workspace. This is only applicable in cases where all projects are versioned together in a single release group. In all other cases, this will be `null`.

- `projectsVersionData`: A map of project names to their version data. The version data is a `VersionData` object, which contains the following properties:
  - `currentVersion`: The current version of the project. This is the version that the project was at before the versioning process began.
  - `newVersion`: The new version of the project.
  - `dockerVersion`: The new version of the project if it is a docker project.
  - `dependentProjects`: A list of projects that depend on the current project.

- `releaseGraph`: The release graph that was generated for the nx release config and workspace data. This can be passed to subsequent operations (changelog, publish) to avoid recomputing and improve performance.

```ts
const { workspaceVersion, projectsVersionData, releaseGraph } =
  await releaseVersion({
    // E.g. if releasing a specific known version
    // otherwise if using e.g. conventional-commits this is not needed
    specifier: '1.0.0',
    dryRun: true,
    verbose: true,
    // ... other options
  });

console.log(workspaceVersion);
console.log(projectsVersionData);
console.log(releaseGraph);
```

### releaseChangelog

`releaseChangelog` will return a `NxReleaseChangelogResult` object containing the following properties:

- `workspaceChangelog`: The changelog data for the workspace, if applicable based on the nx release config.
  - `releaseVersion`: Relevant version data for the new changelog entry.
  - `contents`: The changelog entry contents.

- `projectChangelogs`: A map of project names to their changelog data, if applicable based on the nx release config.
  - `releaseVersion`: Relevant version data for the new changelog entry.
  - `contents`: The changelog entry contents.

```ts
const { workspaceChangelog, projectChangelogs } = await releaseChangelog({
  // Re-use the existing release graph from the releaseVersion
  // call (if applicable) to avoid recomputing in each subcommand
  releaseGraph,

  // NOTE: One of either version or versionData must be provided
  versionData: projectsVersionData, // Pass the detailed project version data from the releaseVersion call
  version: workspaceVersion, // Pass the new workspace version from the releaseVersion call

  dryRun: true,
  verbose: true,

  // ... other options
});
```

### releasePublish

`releasePublish` will return a `PublishProjectsResult` object, which is a map of project names to their publish result which is a simple object with a `code` property representing the exit code of the publish operation for the project.

{% aside type="caution" title="dryRun Behavior" %}
Unlike `releaseVersion` and `releaseChangelog`, the `dryRun` option for `releasePublish` does **not** prevent the underlying commands from being executed. Instead, the `dryRun` flag is forwarded to the `nx-release-publish` executor as an option, and the `NX_DRY_RUN` environment variable is set to `'true'`.

The built-in `@nx/js:release-publish` executor handles this correctly and will skip actual publishing when `dryRun` is `true`. However, **custom `nx-release-publish` executors must implement `dryRun` support themselves** by checking either the `dryRun` option or the `NX_DRY_RUN` environment variable.
{% /aside %}

```ts
const publishResults = await releasePublish({
  // Re-use the existing release graph from the releaseVersion
  // call (if applicable) to avoid recomputing in each subcommand
  releaseGraph,

  dryRun: true,
  verbose: true,

  // ... other options
});
```

You can optionally pass through the version data (e.g. if you are using a custom publish executor that needs to be aware of versions). It will then be provided to the publish executor options as `nxReleaseVersionData` and can be accessed in the publish executor options like any other option.

```ts
const publishResults = await releasePublish({
  releaseGraph,
  versionData: projectsVersionData,
  dryRun: true,
  verbose: true,
});
```

NOTE: Passing `versionData` to `releasePublish` is not required for the default @nx/js publish executor.

It is recommended to use the publishResults to determine the overall success or failure of the release process, for example:

```ts
process.exit(
  Object.values(publishResults).every((result) => result.code === 0) ? 0 : 1
);
```

## Example release script

How you compose these functions in your release script is of course entirely up to you, and you may even want to break them up into multiple files depending on your use-case.

The below is purely an example of you might compose them together into one holistic release script which uses `yargs` to parse script options from the command line (nx release does not require `yargs`, it is simply a common choice for this use-case, you can parse arguments however you wish).

```ts
// scripts/release.ts

import { releaseChangelog, releasePublish, releaseVersion } from 'nx/release';
import * as yargs from 'yargs';

(async () => {
  const options = await yargs
    .version(false) // don't use the default meaning of version in yargs
    .option('version', {
      description:
        'Explicit version specifier to use, if overriding conventional commits',
      type: 'string',
    })
    .option('dryRun', {
      alias: 'd',
      description:
        'Whether or not to perform a dry-run of the release process, defaults to true',
      type: 'boolean',
      default: true,
    })
    .option('verbose', {
      description:
        'Whether or not to enable verbose logging, defaults to false',
      type: 'boolean',
      default: false,
    })
    .parseAsync();

  const { workspaceVersion, projectsVersionData, releaseGraph } =
    await releaseVersion({
      specifier: options.version,
      dryRun: options.dryRun,
      verbose: options.verbose,
    });

  await releaseChangelog({
    releaseGraph, // Re-use the existing release graph to avoid recomputing in each subcommand
    versionData: projectsVersionData,
    version: workspaceVersion,
    dryRun: options.dryRun,
    verbose: options.verbose,
  });

  // publishResults contains a map of project names and their exit codes
  const publishResults = await releasePublish({
    releaseGraph, // Re-use the existing release graph to avoid recomputing in each subcommand
    dryRun: options.dryRun,
    verbose: options.verbose,
  });

  process.exit(
    Object.values(publishResults).every((result) => result.code === 0) ? 0 : 1
  );
})();
```

To perform a dry-run of version `1.0.0`, you would therefore run the script like so:

```sh
npx tsx scripts/release.ts --version 1.0.0
```

(Or by using `ts-node` or any other tool you prefer to run TS scripts.)

## Using the `ReleaseClient` class

The standalone functions that we covered in the previous sections are actually just bound methods of the `ReleaseClient` class that has been pre-instantiated for you.

For an extra layer of control, you can import the `ReleaseClient` directly instead of the standalone functions and use your instance's methods for versioning, changelog generation, and publishing.

The reason you might want to do this is configuration. The `ReleaseClient` constructor allows you to either override release configuration found in `nx.json`, or completely replace it.

```ts
import { ReleaseClient } from 'nx/release';

const releaseClientWithMergedConfig = new ReleaseClient(
  {
    projects: ['project-1', 'project-2'],
    // ... more nx release config options
  },
  false // Do NOT ignore nx.json config, merge whatever was given in the first parameter with it
);

const releaseClientWithIsolatedConfig = new ReleaseClient(
  {
    projects: ['project-1', 'project-2'],
    // ... more nx release config options
  },
  true // Ignore nx.json config, only the configuration given in the first parameter will be used
);
```

Ignoring the Nx Release configurations in `nx.json` can be useful for cases where you have a large, complex workspace and your script only needs to focus on a specific subset in a granular way. One such example would be a script that only focuses on changelog generation for a specific project or projects and does not want to invoke any versioning or publishing logic.

### Using the `ReleaseClient`

Once you have the instantiated `ReleaseClient` class, the usage pattern is the same as with the standalone functions.

```ts
import { ReleaseClient } from 'nx/release';

const releaseClient = new ReleaseClient({});

const { workspaceVersion, projectsVersionData, releaseGraph } =
  await releaseClient.releaseVersion({
    // ... options
  });

const { workspaceChangelog, projectChangelogs } =
  await releaseClient.releaseChangelog({
    releaseGraph,
    // ... other options
  });

const publishResults = await releaseClient.releasePublish({
  releaseGraph,
  // ... other options
});
```

---
<!-- source: https://nx.dev/docs/guides/nx-release/publish-in-ci-cd.md -->
## Publish in CI/CD

Nx Release makes it easy to move your publishing process into your CI/CD pipeline across different package ecosystems.

## General concepts

### Automatically skip publishing locally

When running `nx release`, after the version updates and changelog generation, you will be prompted with the following question:

```text {% frame="terminal" title="nx release" %}
...
? Do you want to publish these versions? (y/N) ›
```

To move publishing into an automated pipeline, you will want to skip publishing when running [`nx release`](/docs/reference/nx-commands#nx-release) locally. To do this automatically, use the `--skip-publish` flag:

```text {% frame="terminal" title="nx release --skip-publish" %}
...

Skipped publishing packages.
```

### Use the publish subcommand

Nx Release provides a publishing subcommand ([`nx release publish`](/docs/reference/nx-commands#nx-release-publish)) that performs just the publishing step. Use this in your CI/CD pipeline to publish the packages.

```text {% frame="terminal" title="nx release publish" %}
NX   Running target nx-release-publish for 3 projects:

- pkg-1
- pkg-2
- pkg-3

...
```

## Publishing npm packages

### Example npm publish output

```text {% frame="terminal" title="nx release publish" %}
NX   Running target nx-release-publish for 3 projects:

- pkg-1
- pkg-2
- pkg-3

—————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

> nx run pkg-1:nx-release-publish


📦  @myorg/pkg-1@0.0.2
=== Tarball Contents ===

233B README.md
277B package.json
53B  src/index.ts
61B  src/lib/pkg-1.ts
=== Tarball Details ===
name:          @myorg/pkg-1
version:       0.0.2
filename:      testorg-pkg-1-0.0.2.tgz
package size:  531 B
unpacked size: 624 B
shasum:        {shasum}
integrity:     {integrity}
total files:   12

Published to https://registry.npmjs.org with tag "latest"

> nx run pkg-2:nx-release-publish


📦  @myorg/pkg-2@0.0.2
=== Tarball Contents ===

233B README.md
277B package.json
53B  src/index.ts
61B  src/lib/pkg-2.ts
=== Tarball Details ===
name:          @myorg/pkg-2
version:       0.0.2
filename:      testorg-pkg-2-0.0.2.tgz
package size:  531 B
unpacked size: 624 B
shasum:        {shasum}
integrity:     {integrity}
total files:   12

Published to https://registry.npmjs.org with tag "latest"

> nx run pkg-3:nx-release-publish


📦  @myorg/pkg-3@0.0.2
=== Tarball Contents ===

233B README.md
277B package.json
53B  src/index.ts
61B  src/lib/pkg-3.ts
=== Tarball Details ===
name:          @myorg/pkg-3
version:       0.0.2
filename:      testorg-pkg-3-0.0.2.tgz
package size:  531 B
unpacked size: 624 B
shasum:        {shasum}
integrity:     {integrity}
total files:   12

Published to https://registry.npmjs.org with tag "latest"

—————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

NX   Successfully ran target nx-release-publish for 3 projects
```

### npm publishing in GitHub actions

A common way to automate publishing NPM packages is via GitHub Actions. An example of a publish workflow is as follows:

```yaml
// ./.github/workflows/publish.yml
name: Publish

on:
  push:
    tags:
      - v*.*.*

jobs:
  test:
    name: Publish
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write # needed for provenance data generation
    timeout-minutes: 10
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          filter: tree:0

      - name: Install Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: https://registry.npmjs.org/

      - name: Install dependencies
        run: npm install
        shell: bash

      - name: Print Environment Info
        run: npx nx report
        shell: bash

      - name: Publish packages
        run: npx nx release publish
        shell: bash
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_ACCESS_TOKEN }}
          NPM_CONFIG_PROVENANCE: true
```

This workflow will install node, install npm dependencies, then run `nx release publish` to publish the packages. It will run on every push to the repository that creates a tag that matches the pattern `v*.*.*`. A release process using this workflow is as follows:

1. Run `nx release --skip-publish` locally. This will create a commit with the version and changelog updates, then create a tag for the new version.
2. Push the changes (including the new tag) to the remote repository with `git push && git push --tags`.
3. The publish workflow will automatically trigger and publish the packages to the npm registry.

{% aside type="note" title="This template is designed for fixed versioning" %}
The example workflow above triggers on a single tag pattern (`v*.*.*`), which works best when all packages share the same version (**fixed versioning strategy**). With fixed versioning, `nx release` creates one tag per release.

If you're using **independent versioning** (where each project has its own version), see the [Considerations for Independent Versioning](#considerations-for-independent-versioning) section below.
{% /aside %}

### Considerations for independent versioning

When using independent versioning, `nx release` creates a separate tag for each project being released (e.g., `pkg-1@1.0.0`, `pkg-2@2.1.0`). This introduces some challenges with tag-triggered workflows:

#### GitHub tag event limitation

GitHub Actions has an important limitation: **workflows triggered by the `push` event will not run if more than 3 tags are created at once**. This means if you run `nx release` and it creates tags for 4 or more projects, the publish workflow will not be triggered.

This limitation is documented in [GitHub workflow events documentation](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#create).

#### Alternative approaches for independent versioning

There are several ways to work around this limitation:

**Option 1: Use `workflow_dispatch` with Manual Trigger**

Instead of triggering on tags, use a manual workflow dispatch after pushing your release:

```yaml
// .github/workflows/publish.yml
name: Publish

on:
  workflow_dispatch:
    inputs:
      dry-run:
        description: 'Run in dry-run mode (no actual publishing)'
        required: false
        default: 'false'
        type: boolean

jobs:
  publish:
    name: Publish
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: https://registry.npmjs.org/

      - name: Install dependencies
        run: npm install

      - name: Publish packages
        run: npx nx release publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_ACCESS_TOKEN }}
          NPM_CONFIG_PROVENANCE: true
```

With this approach:

1. Run `nx release --skip-publish` locally and push the commits and tags.
2. Manually trigger the workflow from the GitHub Actions UI after the push completes.

**Option 2: Trigger on Push to Main Branch**

Trigger the workflow when the release commit is pushed to your main branch:

```yaml
on:
  push:
    branches:
      - main
    paths:
      - '**/package.json'
```

This approach requires additional logic in your workflow to determine if a release was just made (e.g., by checking the commit message or comparing versions).

**Option 3: Push Tags in Batches**

If you prefer tag-triggered workflows, push tags in smaller batches (3 or fewer at a time) to ensure each push triggers the workflow. This can be automated with a script that pushes tags individually or in small groups.

### Configure the NODE_AUTH_TOKEN

The `NODE_AUTH_TOKEN` environment variable is needed to authenticate with the npm registry. In the above workflow, it is passed into the Publish packages step via a [GitHub Secret](https://docs.github.com/en/actions/reference/encrypted-secrets).

#### Generate a NODE_AUTH_TOKEN for npm

To generate the correct `NODE_AUTH_TOKEN` for the npmJS registry specifically, first login to [https://www.npmjs.com/](https://www.npmjs.com/). Select your profile icon, then navigate to "Access Tokens". Generate a new Granular Access Token. Ensure that the token has read and write access to both the packages you are publishing and their organization (if applicable). Copy the generated token and add it as a secret to your GitHub repository.

#### Add the nODE_AUTH_TOKEN to GitHub secrets

To add the token as a secret to your GitHub repository, navigate to your repository, then select "Settings" > "Secrets and Variables" > "Actions". Add a new Repository Secret with the name `NPM_ACCESS_TOKEN` and the value of the token you generated in the previous step.

Note: The `NPM_ACCESS_TOKEN` name is not important other than that it matches the usage in the workflow:

```yaml
- name: Publish packages
  run: npx nx release publish
  shell: bash
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_ACCESS_TOKEN }}
    NPM_CONFIG_PROVENANCE: true
```

### npm provenance

To verify your packages with [npm provenance](https://docs.npmjs.com/generating-provenance-statements), set the `NPM_CONFIG_PROVENANCE` environment variable to `true` in the step where `nx release publish` is performed. The workflow will also need the `id-token: write` permission to generate the provenance data:

```yaml
jobs:
  test:
    name: Publish
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write # needed for provenance data generation
```

```yaml
- name: Publish packages
  run: npx nx release publish
  shell: bash
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_ACCESS_TOKEN }}
    NPM_CONFIG_PROVENANCE: true
```

## Publishing Docker Images {% badge variant="caution" text="experimental" /%}

Docker support in Nx is currently experimental and may undergo breaking changes without following semantic versioning.

{% aside type="note" title="Nx Cloud Agents Compatibility" %}
Docker operations in `nx release` are currently supported in standard CI/CD environments like GitHub Actions, GitLab CI, and Jenkins.

For Nx Cloud Agents compatibility, please contact [Nx Enterprise support](https://nx.dev/contact/sales) to explore available options for your team.
{% /aside %}

When using Nx Release with Docker images, the publishing process differs from npm packages.

Docker images are built with the `npx nx run-many -t docker:build` command, which is the default for [`preVersionCommand`](/docs/guides/nx-release/build-before-versioning#build-before-docker-versioning) in `nx.json`.

You may also run the build command manually before running `nx release`. After the images are built, they are tagged during the versioning phase, then pushed to a registry during the publish phase.

### Docker registry authentication

Before publishing Docker images, ensure you're authenticated with your Docker registry:

```yaml
// .github/workflows/publish.yml
- name: Login to Docker Hub
  uses: docker/login-action@v2
  with:
    username: ${{ secrets.DOCKER_USERNAME }}
    password: ${{ secrets.DOCKER_TOKEN }}

- name: Build and tag Docker images
  run: npx nx release version --dockerVersionScheme=production

- name: Publish Docker images
  run: npx nx release publish
```

See the [`nx release version`](/docs/reference/nx-commands#nx-release-version) and [`nx release publish`](/docs/reference/nx-commands#nx-release-publish) CLI references for all available options.

For changelogs, you can run [`nx release changelog`](/docs/reference/nx-commands#nx-release-changelog) `<version>` locally with the new version from the pipeline. For example, if the new version is `2501.01.be49ad6` you would run `npx nx release changelog 2501.01.be49ad6`. This will create or update the `CHANGELOG.md` files in your projects.

### Using different registries

Configure alternative registries in your `nx.json`:

```jsonc
// nx.json
{
  "release": {
    "docker": {
      "registryUrl": "ghcr.io", // GitHub Container Registry
    },
  },
}
```

### Example GitHub Actions Workflow for Docker

```yaml
// .github/workflows/docker-publish.yml
name: Docker Publish

on:
  push:
    branches: [main]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci

      - name: Build applications
        run: npx nx run-many -t build

      - name: Login to Docker Hub
        uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_TOKEN }}

      - name: Build and tag Docker images
        run: npx nx release version --dockerVersionScheme=production

      - name: Publish Docker images
        run: npx nx release publish
```

---
<!-- source: https://nx.dev/docs/guides/nx-release/publish-rust-crates.md -->
## Using Nx Release with Rust

This recipe guides you through versioning Rust libraries, generating changelogs, and publishing Rust crates in a monorepo with Nx Release.

{% github_repository url="https://github.com/JamesHenry/release-js-and-rust" /%}

{% aside type="caution" title="Currently requires legacy versioning" %}
In Nx v21, the implementation details of versioning were rewritten to enhance flexibility and allow for better cross-ecosystem support. An automated migration was provided in Nx v21 to update your configuration to the new format when running `nx migrate`.

During the lifecycle of Nx v21, you can still opt into the old versioning by setting `release.version.useLegacyVersioning` to `true`, which will keep the original configuration structure and behavior. In Nx v22, the legacy versioning implementation has been removed entirely, so this should only be done temporarily to ease the transition.

Importantly, this recipe currently requires the use of legacy versioning, because the `@monodon/rust` plugin does not yet provide the necessary `VersionActions` implementation to support the new versioning behavior. This will be added in a minor release of Nx v21 and this recipe will be updated accordingly.
{% /aside %}

## Initialize Nx release in your workspace

### Install Nx

Ensure that Nx is installed in your monorepo. Check out the [Installation docs](/docs/getting-started/installation) for instructions on created a new Nx workspace or adding Nx to an existing project.

### Add the @monodon/rust plugin

The [`@monodon/rust` package](https://github.com/Cammisuli/monodon) is required for Nx Release to manage and release Rust crates. Add it if it is not already installed:

```shell
nx add @monodon/rust
```

### Configure projects to release

Nx Release uses Nx powerful [Project Graph](/docs/features/explore-graph) to understand your projects and their dependencies.

If you want to release all of the projects in your workspace, such as when dealing with a series of Rust crates, no configuration is required.

If you have a mixed workspace in which you also have some applications, e2e testing projects or other things you don't want to release, you can configure `nx release` to target only the projects you want to release.

Configure which projects to release by adding the `release.projects` property to nx.json. The value is an array of strings, and you can use any of the same specifiers that are supported by `nx run-many`'s [projects filtering](/docs/reference/nx-commands#nx-run-many), such as explicit project names, Nx tags, directories and glob patterns, including negation using the `!` character.

For example, to release just the projects in the `crates` directory:

```jsonc
// nx.json
{
  "release": {
    "projects": ["crates/*"],
    "version": {
      // Legacy versioning is currently required for the @monodon/rust plugin, see the note above for more details
      "useLegacyVersioning": true,
    },
  },
}
```

## Create the first release

The first time you release with Nx Release in your monorepo, you will need to use the `--first-release` option. This tells Nx Release not to expect the existence of any git tags, changelog files, or published packages.

{% aside type="note" title="Use the --dry-run option" %}
The `--dry-run` option is useful for testing your configuration without actually creating a release. It is always recommended to run Nx Release once with `--dry-run` first to ensure everything is configured correctly.
{% /aside %}

To preview your first release, run:

```shell
nx release --first-release --dry-run
```

### Pick a new version

Nx Release will prompt you to pick a version bump for all the crates in the release. By default, all crate versions are kept in sync, so the prompt only needs to be answered one time. If needed, you can [configure Nx to release projects independently](/docs/guides/nx-release/release-projects-independently).

```text {% frame="terminal" title="nx release --first-release --dry-run" %}

NX   Running release version for project: pkg-1

pkg-1 🔍 Reading data for crate "pkg-1" from crates/crates/pkg-1/Cargo.toml
pkg-1 📄 Resolved the current version as 0.1.0 from crates/pkg-1/Cargo.toml
? What kind of change is this for the 3 matched projects(s)? …
❯ major
  premajor
  minor
  preminor
  patch
  prepatch
  prerelease
  Custom exact version
```

### Preview the results

After this prompt, the command will finish, showing you the preview of changes that would have been made if the `--dry-run` option was not passed.

```text {% frame="terminal" title="nx release --first-release --dry-run" %}

NX   Running release version for project: pkg-1

pkg-1 🔍 Reading data for crate "pkg-1" from crates/crates/pkg-1/Cargo.toml
pkg-1 📄 Resolved the current version as 0.1.0 from crates/pkg-1/Cargo.toml
✔ What kind of change is this for the 3 matched projects(s)? · patch
pkg-1 ✍️  New version 0.1.1 written to crates/crates/pkg-1/Cargo.toml

NX   Running release version for project: pkg-2

pkg-2 🔍 Reading data for crate "pkg-2" from crates/crates/pkg-2/Cargo.toml
pkg-2 📄 Resolved the current version as 0.1.0 from crates/pkg-2/Cargo.toml
pkg-2 ✍️  New version 0.1.1 written to crates/crates/pkg-2/Cargo.toml

NX   Running release version for project: pkg-3

pkg-3 🔍 Reading data for crate "pkg-3" from crates/crates/pkg-3/Cargo.toml
pkg-3 📄 Resolved the current version as 0.1.0 from crates/pkg-3/Cargo.toml
pkg-3 ✍️  New version 0.1.1 written to crates/crates/pkg-3/Cargo.toml

UPDATE crates/pkg-1/Cargo.toml [dry-run]

  [package]
  name = "pkg-1"
- version = "0.1.0"
+ version = "0.1.1"
  edition = "2021"


UPDATE crates/pkg-2/Cargo.toml [dry-run]

  [package]
  name = "pkg-2"
- version = "0.1.0"
+ version = "0.1.1"
  edition = "2021"


UPDATE crates/pkg-3/Cargo.toml [dry-run]

  [package]
  name = "pkg-3"
- version = "0.1.0"
+ version = "0.1.1"
  edition = "2021"


NX   Updating Cargo.lock file


NX   Staging changed files with git


NX   Previewing an entry in CHANGELOG.md for v0.1.1


CREATE CHANGELOG.md [dry-run]
+ ## 0.1.1 (2024-02-29)
+
+ This was a version bump only, there were no code changes.


NX   Staging changed files with git


NX   Committing changes with git


NX   Tagging commit with git


NX   Skipped publishing packages.


NOTE: The "dryRun" flag means no changes were made.
```

### Run without `--dry-run`

If the preview looks good, run the command again without the `--dry-run` option to actually create the release.

```shell
nx release --first-release
```

The command will proceed as before, prompting for a version bump and showing a preview of the changes. However, this time, it will prompt you to publish the crates to the remote registry. If you say no, the publishing step will be skipped. If you say yes, the command will publish the crates to https://crates.io.

```text {% frame="terminal" title="nx release --first-release" %}
...

✔ Do you want to publish these versions? (y/N) · true

NX   Running target nx-release-publish for 3 projects:

- pkg-1
- pkg-2
- pkg-3

—————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

(...cargo publish output here...)

—————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

NX   Successfully ran target nx-release-publish for 3 projects

```

## Manage git operations

By default, Nx Release will stage all changes it makes with git. This includes updating `Cargo.toml` files, creating changelog files, and updating the `Cargo.lock` file. After staging the changes, Nx Release will commit the changes and create a git tag for the release.

### Customize the commit message and tag pattern

The commit message created by Nx Release defaults to 'chore(release): publish {version}', where `{version}` will be dynamically interpolated with the relevant value based on your actual release, but can be customized with the `release.git.commitMessage` property in nx.json.

The structure of the git tag defaults to `v{version}`. For example, if the version is `1.2.3`, the tag will be `v1.2.3`. This can be customized by setting the `release.releaseTag.pattern` property (Nx 22+) or `release.releaseTagPattern` property (Nx < 22) in nx.json.

For this same example, if you want the commit message to be 'chore(release): 1.2.3' and the tag to be `release/1.2.3`, you would configure nx.json like this:

{% tabs syncKey="nx-release-configuration" %}
{% tabitem label="Nx 22+" %}

```json
// nx.json
{
  "release": {
    "releaseTag": {
      "pattern": "release/{version}"
    },
    "git": {
      "commitMessage": "chore(release): {version}"
    }
  }
}
```

{% /tabitem %}
{% tabitem label="Nx < 22" %}

```json
// nx.json
{
  "release": {
    "releaseTagPattern": "release/{version}",
    "git": {
      "commitMessage": "chore(release): {version}"
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

When using release groups in which the member projects are versioned together, you can also leverage `{releaseGroupName}` and it will be interpolated appropriately in the commit/tag that gets created for that release group.

## Future releases

After the first release, the `--first-release` option will no longer be required. Nx Release will expect to find git tags and changelog files for each package.

Future releases will also generate entries in `CHANGELOG.md` based on the changes since the last release. Nx Release will parse the `feat` and `fix` type commits according to the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification and sort them into appropriate sections of the changelog. An example of these changelogs can be seen on the [Nx releases page](https://github.com/nrwl/nx/releases).

---
<!-- source: https://nx.dev/docs/guides/nx-release/release-docker-images.md -->
## Release Docker Images

This guide walks you through setting up Nx Release to version and publish Docker images from your monorepo.

{% youtube title="What is Nx?" src="https://www.youtube.com/embed/TOPxKJXUaqw" /%}

## Prerequisites

Before starting, ensure you have:

1. Docker installed and running locally
2. Run `docker login` to authenticate with your Docker registry (e.g., `docker login docker.io` for Docker Hub)

## Install Nx Docker plugin

```shell
nx add @nx/docker
```

This command adds the `@nx/docker` plugin to your `nx.json` so that projects with a `Dockerfile` is automatically configured with Docker targets (e.g. `docker:build` and `docker:run`).

## Create basic Node.js backend {% badge text="optional" /%}

If you don't already have a backend application, create one using `@nx/node`:

```shell
nx add @nx/node
nx g @nx/node:app apps/api --docker --framework=express
```

This generates a Node.js application with a Dockerfile like the following:

```dockerfile
// apps/api/Dockerfile
FROM docker.io/node:lts-alpine

ENV HOST=0.0.0.0
ENV PORT=3000

WORKDIR /app

RUN addgroup --system api && \
adduser --system -G api api

COPY dist app/
COPY package.json app/
RUN chown -R api:api .

# You can remove this install step if you build with `--bundle` option.
# The bundled output will include external dependencies.
RUN npm --prefix api --omit=dev -f install

CMD [ "node", "app" ]
```

You should be able to run the following commands to compile the application and create a Docker image:

```shell
nx build api
nx docker:build api
```

## Set up a new release group

Configure Docker applications in a separate release group called `apps` so it does not conflict with any existing release projects.

To learn more about release groups, see the [Release Groups](/docs/guides/nx-release/release-groups) guide.

{% tabs syncKey="nx-release-configuration" %}
{% tabitem label="Nx 22+" %}

```jsonc
// nx.json
{
  "release": {
    "releaseTag": {
      "pattern": "release/{projectName}/{version}",
    },
    "groups": {
      "apps": {
        "projects": ["api"],
        "projectsRelationship": "independent",
        "docker": {
          // This should be true to skip versioning with other tools like NPM or Rust crates.
          "skipVersionActions": true,
          // You can also use a custom registry like `ghcr.io` for GitHub Container Registry.
          // `docker.io` is the default so you could leave this out for Docker Hub.
          "registryUrl": "docker.io",
          // The pre-version command is run before versioning, useful for verifying the Docker image.
          "groupPreVersionCommand": "echo BEFORE VERSIONING",
        },
        "changelog": {
          "projectChangelogs": true,
        },
      },
    },
  },
}
```

{% /tabitem %}
{% tabitem label="Nx < 22" %}

```jsonc
// nx.json
{
  "release": {
    "releaseTagPattern": "release/{projectName}/{version}",
    "groups": {
      "apps": {
        "projects": ["api"],
        "projectsRelationship": "independent",
        "docker": {
          // This should be true to skip versioning with other tools like NPM or Rust crates.
          // Only set this if you are not using {versionActionsVersion} in your docker version scheme
          "skipVersionActions": true,
          // You can also use a custom registry like `ghcr.io` for GitHub Container Registry.
          // `docker.io` is the default so you could leave this out for Docker Hub.
          "registryUrl": "docker.io",
          // The pre-version command is run before versioning, useful for verifying the Docker image.
          "groupPreVersionCommand": "echo BEFORE VERSIONING",
        },
        "changelog": {
          "projectChangelogs": true,
        },
      },
    },
  },
}
```

{% /tabitem %}
{% /tabs %}

The `release.groups.apps.docker.skipVersionActions` option should be set to `true` to skip versioning for other tooling such as NPM or Rust crates.

The `release.groups.apps.projectsRelationship` is set to `independent` and `release.groups.apps.changelog` is set to `projectChangelogs` so that each application within the group maintains its own release cadence and changelog.

The `release.groups.apps.docker.groupPreVersionCommand` is an optional command that runs before the versioning step, allowing you to perform any pre-version checks such as image verification before continuing the release.

## Set up app repository

Docker images have to be pushed to a repository, and this must be set on each application you want to release. This must be set as `release.docker.repositoryName` in the project's `project.json `or `package.json` file.

For example, from the previous `apps/api` Node.js application, you can set the `nx.release.docker.repositoryName` in `package.json`.

```json {% meta="{6-10}" %}
// apps/api/package.json
{
  "name": "@acme/api",
  "version": "0.0.1",
  "nx": {
    "release": {
      "docker": {
        "repositoryName": "acme/api"
      }
    }
    // ...
  }
}
```

Or if you don't have a `package.json` (e.g. for non-JS projects), set it in `project.json`:

```json {% meta="{6-10}" %}
// apps/api/project.json
{
  "name": "api",
  "root": "apps/api",
  "projectType": "application",
  "release": {
    "docker": {
      "repositoryName": "acme/api"
    }
  }
  // ...
}
```

You should replace `acme` with your organization or username for the Docker registry that you are logged into.

{% aside title="Docker Image Reference Override" type="note" %}
The `release.docker.registryUrl` option can be used to override the Docker registry URL. This is useful if you want to push to a private registry like GitHub Container Registry.

If you need even more control during CI/CD pipelines, for example if you target different registries for different environments, you can use the `NX_DOCKER_IMAGE_REF` environment variable.
Note that the value you set this to will need to include the `repositoryName` as well. e.g. `NX_DOCKER_IMAGE_REF=ghcr.io/acme/api:2508.16.1`.

Versioning will continue to work as normal.
{% /aside %}

## Your first Docker release

Dry run your first Docker release with calendar versioning. See the [`nx release`](/docs/reference/nx-commands#nx-release) CLI reference for all available options.

```shell
nx release --dockerVersionScheme=production --first-release --dry-run
```

When you are ready, run the release command again without `--dry-run`:

```shell
nx release --dockerVersionScheme=production --first-release
```

When prompted to publish the image, choose `yes`, or you can pass the `--yes` flag to skip the prompt.

This will:

- Build your Docker images
- Tag them with a calendar version (e.g., `2501.01.a1b2c3d`)
- Update the app's changelog (e.g. `apps/api/CHANGELOG.md`)
- Update git tags (you can check with `git --no-pager tag --sort=-version:refname | head -5`)
- Push the image to the configured Docker registry (e.g., `docker.io/acme/api:2501.01.a1b2c3d`)

### Understanding calendar versioning

There are many different implementations of Calendar versioning but they consist of four main segments:

- **Major**: The first number in the version and the most common calendar-based component.
- **Minor**: The second number in the version, also usually calendar-based.
- **Micro**: The third and usually final number in the version, sometimes referred to as a "patch" or "build" number.
- **Modifier**: An optional text tag, such as "alpha", "dev", "hotfix"

By default, Nx Release uses the following patterns for calendar versioning

- **Production**: `YYMM.DD.SHA`
- **Hotfix**: `YYMM.DD.SHA-hotfix`

Where the following tokens are replaced:

- `YYMM`: Year and month
- `DD`: Day of the month
- `SHA`: Short commit hash

Note: The timezone is UTC to ensure consistency across different environments.

{% aside title="Default Versioning Schemes" type="note" %}
Using `SHA` for the micro version may not be the best choice for your workflow. If you are using a CI/CD pipeline, you may want to use a build number instead. See the [Customizing Version Schemes](#customizing-version-schemes) section for more details.
{% /aside %}

## Future releases

After the first release, you can run `nx release` without the `--first-release` flag. If you do not specify `--dockerVersionScheme`, then you will be prompted to choose one:

- `production` - for regular releases from the `main` or stable branch
- `hotfix` - for bug fixes from a hotfix branch

These are the default schemes that come with Nx Release. These schemes support workflows where you have a stable branch that developers continuously integrate with, and a hotfix branch reserved for urgent production fixes.

### Using explicit Docker versions

If you need to specify an exact Docker version instead of using version schemes, you can use the `--dockerVersion` flag:

```shell
nx release --dockerVersion=1.2.3
```

This will bypass the version scheme logic entirely and tag your Docker images with the exact version you specify. This is useful when you need to:

- Align Docker versions with external versioning systems
- Override the calendar-based versioning for specific releases
- Set custom version tags that don't follow the standard patterns

### Customizing version schemes

You can customize Docker version schemes in your `nx.json` to match your deployment workflow. The version patterns support several interpolation tokens:

```json
// nx.json
{
  "release": {
    "docker": {
      "versionSchemes": {
        "production": "{currentDate|YYMM.DD}.{env.BUILD_NUMBER}",
        "staging": "{currentDate|YYMM.DD}-staging.{shortCommitSha}",
        "ci": "{env.BUILD_NUMBER}-{shortCommitSha}"
      }
    }
  }
}
```

The above configuration swaps `hotfix` scheme for `staging` and adds a `ci` scheme that uses an environment variable. You can customize this list to fit your needs, and you can also change the patterns for each scheme.

Version patterns can include environment variables using the `{env.VAR_NAME}` syntax, allowing you to inject CI/CD pipeline information like build numbers or deployment environments directly into your Docker tags.

You can also include the semantic version generated during version actions using `{versionActionsVersion}`. For example:

```json
"production": "{projectName}-{versionActionsVersion}"
```

If you use `{versionActionsVersion}`, do not enable `docker.skipVersionActions` (or include the project in `skipVersionActions`) because the placeholder cannot be resolved when version actions are skipped.

See the [`docker.versionScheme` documentation](/docs/reference/nx-json#version-scheme-syntax) for more details on how to customize the tag pattern.

---
<!-- source: https://nx.dev/docs/guides/nx-release/release-groups.md -->
## Release Groups

Nx supports workspaces of any size and scale, and that means that projects can often be worked on in the same Nx workspace that have very different release requirements.

Nx release supports the concept of release groups to allow you to configure different subsets of projects in different ways. Importantly, projects in different release groups can still depend on each other, and nx release can automatically handle updating dependencies and dependents across any number of group boundaries.

{% aside type="note" title="Default Group" %}
Technically, even if you have no nx release configuration at all, you are always dealing with release groups. Behind the scenes, if no release groups are configured, Nx will automatically create an implicit `__default__` release group for you that includes all projects in the workspace that are able to be released.

When you use the `"projects"` property in the `"release"` config at the top level, you are really adjusting the projects that are present in that `__default__` group.
{% /aside %}

## Understanding release groups

Release groups provide a way to organize your projects based on their release requirements. Each group can have its own:

- **Projects Relationship** - Whether projects within the group are versioned independently or in lock step (fixed)
- **Version configuration** - Custom conventional commits, version prefixes, and more
- **Changelog configuration** - Different changelog formats and locations
- **Release tag** - Various options related to the git tags that influence the release process
- **Docker configuration** - Specific Docker versioning schemes

## Creating release groups

To create release groups, define them in your `nx.json` file under the `release.groups` property:

```jsonc
// nx.json
{
  "release": {
    "groups": {
      "backend": {
        "projects": ["api", "auth-service", "payment-service"],
        "projectsRelationship": "fixed",
      },
      "frontend": {
        "projects": ["web-app", "mobile-app"],
        "projectsRelationship": "independent",
      },
    },
  },
}
```

### Project selection

You can specify projects for a group using project matchers that you may already be familiar with from `nx run-many` command filters:

- **Explicit project names**: `"projects": ["project-a", "project-b"]`
- **Glob patterns**: `"projects": ["packages/shared-*"]`
- **Tag references**: `"projects": ["tag:npm-public"]`
- **Negation**: `"projects": ["!ignore-me"]`

{% aside type="note" title="Project Uniqueness" %}
Each project can only belong to one release group. If you try to assign a project to multiple groups, Nx will throw an error during configuration validation.
{% /aside %}

## Projects relationship

The `projectsRelationship` property determines how projects within a group are released:

### Fixed

When `projectsRelationship` is set to `"fixed"` (the default):

- All projects in the group share the same version number
- When one project requires a version bump, all projects in the group are versioned together
- Dependencies between projects in the group are always automatically updated
- Each project will receive a changelog entry, with a specific (configurable) message for those projects that were only bumped to align with the group version

```jsonc
// nx.json
{
  "release": {
    "groups": {
      "shared-libraries": {
        "projects": ["ui-components", "utils", "data-access"],
        // this is also the default and can be omitted
        "projectsRelationship": "fixed",
        // ... other group configuration options ...
      },
    },
  },
}
```

### Independent

When `projectsRelationship` is set to `"independent"`:

- Each project in the group maintains its own version
- Projects are versioned only when they have changes (apart from the influence of ["updateDependents" configuration](#update-dependents), learn more below)
- Changelog entries are generated only when there are direct or indirect ("updateDependents") changes to the project

```jsonc
// nx.json
{
  "release": {
    "groups": {
      "microservices": {
        "projects": ["user-service", "order-service", "inventory-service"],
        "projectsRelationship": "independent",
        // ... other group configuration options ...
      },
    },
  },
}
```

## Group-specific configuration

Each release group can override the root `"release"` configuration with its own settings:

### Version configuration

Customize versioning behavior per group:

```jsonc
{
  "release": {
    "version": {
      "conventionalCommits": false,
      "versionPrefix": "~",
      "updateDependents": "always",
    },
    "groups": {
      "npm-packages": {
        "projects": ["package-*"],
        "version": {
          // These properties override the root version
          //configuration for this specific group
          "conventionalCommits": true,
          "versionPrefix": "^",
          "updateDependents": "auto",
        },
      },
    },
  },
}
```

### Changelog configuration

Configure changelog generation per group:

```jsonc
{
  "release": {
    "changelog": {
      "projectChangelogs": {
        "file": false,
        // ... other changelog configuration options ...
      },
    },
    "groups": {
      "public-apis": {
        "projects": ["api-*"],
        // overrides at the group level
        "changelog": {
          "file": "{projectRoot}/CHANGELOG.md",
          "createRelease": "github",
          "renderer": "@my-org/custom-changelog-renderer",
        },
      },
    },
  },
}
```

### Release tag patterns

Customize how relevant git tags should be discovered and created for each group independently:

```jsonc
{
  "release": {
    "groups": {
      "backend": {
        "projects": ["backend-*"],
        "releaseTag": {
          "pattern": "backend-{version}",
          "requireSemver": true,
        },
      },
      "frontend": {
        "projects": ["frontend-*"],
        "releaseTag": {
          "pattern": "frontend-{version}",
        },
      },
    },
  },
}
```

## Update dependents

For independently versioned projects, regardless of whether they are in the same release group or not, we will have to consider what happens when those projects depend on one another.

```jsonc
// nx.json
{
  "release": {
    "groups": {
      "group1": {
        // project-a depends on project-b, even though it
        // happens to be in a different release group here
        "projects": ["project-a"],
      },
      "group2": {
        // project-a depends on project-b, even though it
        // happens to be in a different release group here
        "projects": ["project-b"],
      },
    },
  },
}
```

Nx can handle this cascade of updates automatically, across any number of release group boundaries, and this behavior is configurable via the `version.updateDependents` option.

See the [Update Dependents](/docs/guides/nx-release/update-dependents) guide for more details.

## More examples

### Mixed relationship groups

You can have different relationship types for different groups in the same workspace:

```jsonc
{
  "release": {
    "groups": {
      "platform": {
        "projects": ["core", "common", "shared"],
        "projectsRelationship": "fixed",
      },
      "applications": {
        "projects": ["app-*"],
        "projectsRelationship": "independent",
      },
    },
  },
}
```

### Group-specific pre-version commands

Run different build or preparation commands for each group:

```jsonc
{
  "release": {
    "groups": {
      "compiled-packages": {
        "projects": ["lib-*"],
        "version": {
          "groupPreVersionCommand": "nx run-many -t build --projects=...",
        },
      },
      "documentation": {
        "projects": ["docs-*"],
        "version": {
          "groupPreVersionCommand": "nx run-many -t generate-docs --projects=...",
        },
      },
    },
  },
}
```

### Version plans with groups

When using [version plans](/docs/guides/nx-release/file-based-versioning-version-plans), you can target specific groups:

```jsonc
{
  "release": {
    "groups": {
      "backend": {
        "projects": ["api-*"],
        "versionPlans": true,
      },
      "frontend": {
        "projects": ["ui-*"],
        // version plans is not enabled here and
        // it's not set at the root level either
      },
    },
  },
}
```

## Processing order

Nx Release processes groups in topological order based on their dependencies:

1. Groups with no dependencies are processed first
2. Groups that depend on already-processed groups are processed next
3. Within each group, projects are also processed in topological order

This ensures that:

- Dependencies are always versioned before their dependents
- Version updates cascade correctly through the `ReleaseGraph` that is constructed behind the scenes

NOTE: Circular dependencies are not recommended, but can be tolerated by nx release, as it can sometimes be unavoidable.

## Using filters with groups

You can filter which groups or projects to release. See the [`nx release`](/docs/reference/nx-commands#nx-release) CLI reference for all available options.

```bash
# Release only a specific group
nx release --groups=backend

# Release specific independent projects across any groups
nx release --projects=api,web-app

# Combine with dry-run to preview
nx release --groups=frontend --dry-run
```

{% aside type="caution" title="Fixed Groups and Filters" %}
When filtering projects in a fixed release group, you must include all projects in that group. You cannot release a subset of projects from a fixed group as they must be versioned together.
{% /aside %}

## Next steps

- Learn about [conventional commits](/docs/guides/nx-release/automatically-version-with-conventional-commits) for automatic versioning
- Explore [version plans](/docs/guides/nx-release/file-based-versioning-version-plans) for file based versioning
- Configure [custom registries](/docs/guides/nx-release/configure-custom-registries) for publishing
- Set up [CI/CD integration](/docs/guides/nx-release/publish-in-ci-cd) for automated releases

---
<!-- source: https://nx.dev/docs/guides/nx-release/release-npm-packages.md -->
## Release TypeScript/JavaScript Packages to NPM

This guide walks you through setting up Nx Release to version, generate changelogs, and publish TypeScript/JavaScript packages to NPM from your monorepo.

{% linkcard title="Free Course: Versioning and Releasing NPM packages with Nx"  href="https://www.epicweb.dev/tutorials/versioning-and-releasing-npm-packages-with-nx" /%}

## Setting up your NPM release workflow

### Install Nx

Ensure that Nx is installed in your monorepo. Check out the [Installation docs](/docs/getting-started/installation) for instructions on created a new Nx workspace or adding Nx to an existing project.

### Add the JavaScript plugin

The [`@nx/js` package](/docs/technologies/typescript/introduction) is required for Nx Release to manage and release JavaScript packages. Add it if it is not already installed:

```shell
nx add @nx/js
```

### Configure projects to release

Nx Release uses Nx powerful [Project Graph](/docs/features/explore-graph) to understand your projects and their dependencies.

If you want to release all of the projects in your workspace, such as when dealing with a series of npm library packages, no configuration is required.

If you have a mixed workspace in which you also have some applications, e2e testing projects or other things you don't want to release, you can configure `nx release` to target only the projects you want to release.

Configure which projects to release by adding the `release.projects` property to nx.json. The value is an array of strings, and you can use any of the same specifiers that are supported by `nx run-many`'s [projects filtering](/docs/reference/nx-commands#nx-run-many), such as explicit project names, Nx tags, directories and glob patterns, including negation using the `!` character.

For example, to release just the projects in the `packages` directory:

```json
// nx.json
{
  "release": {
    "projects": ["packages/*"]
  }
}
```

## Create the first release

The first time you release with Nx Release in your monorepo, you will need to use the `--first-release` option. This tells Nx Release not to expect the existence of any git tags, changelog files, or published packages.

{% aside type="note" title="Use the --dry-run option" %}
The `--dry-run` option is useful for testing your configuration without actually creating a release. It is always recommended to run Nx Release once with `--dry-run` first to ensure everything is configured correctly.
{% /aside %}

To preview your first release, run:

```shell
nx release --first-release --dry-run
```

### Pick a new version

Nx Release will prompt you to pick a version bump for all the packages in the release. By default, all package versions are kept in sync, so the prompt only needs to be answered one time. If needed, you can [configure Nx to release projects independently](/docs/guides/nx-release/release-projects-independently).

```text {% frame="terminal" title="nx release --first-release --dry-run" %}
? What kind of change is this for the 3 matched projects(s)? …
❯ major
  premajor
  minor
  preminor
  patch
  prepatch
  prerelease
  Custom exact version
```

### Preview the results

After this prompt, the command will finish, showing you the preview of changes that would have been made if the `--dry-run` option was not passed.

```text {% frame="terminal" title="nx release --first-release --dry-run" %}

 NX   Running release version for project: pkg-1

pkg-1 📄 Resolved the current version as 0.0.1 from manifest: packages/pkg-1/package.json
pkg-1 ❓ Applied semver relative bump "major", from the prompted specifier, to get new version 1.0.0
pkg-1 ✍️ New version 1.0.0 written to manifest: packages/pkg-1/package.json

 NX   Running release version for project: pkg-2

pkg-2 📄 Resolved the current version as 0.0.1 from manifest: packages/pkg-2/package.json
pkg-2 ❓ Applied version 1.0.0 directly, because the project is a member of a fixed release group containing pkg-1
pkg-2 ✍️ New version 1.0.0 written to manifest: packages/pkg-2/package.json

 NX   Running release version for project: pkg-3

pkg-3 📄 Resolved the current version as 0.0.1 from manifest: packages/pkg-3/package.json
pkg-3 ❓ Applied version 1.0.0 directly, because the project is a member of a fixed release group containing pkg-1
pkg-3 ✍️ New version 1.0.0 written to manifest: packages/pkg-3/package.json

UPDATE packages/pkg-1/package.json [dry-run]

    "name": "@myorg/pkg-1",
-   "version": "0.0.1",
+   "version": "0.0.2",
    "dependencies": {
      "tslib": "^2.3.0",
-     "@myorg/pkg-2": "0.0.1"
+     "@myorg/pkg-2": "0.0.2"
    },

 UPDATE packages/pkg-2/package.json [dry-run]

    "name": "@myorg/pkg-2",
-   "version": "0.0.1",
+   "version": "0.0.2",
    "dependencies": {

 UPDATE packages/pkg-3/package.json [dry-run]

    "name": "@myorg/pkg-3",
-   "version": "0.0.1",
+   "version": "0.0.2",
    "dependencies": {


NX   Updating npm lock file


NX   Staging changed files with git


NOTE: The "dryRun" flag means no changes were made.

NX   Previewing an entry in CHANGELOG.md for v0.0.2


CREATE CHANGELOG.md [dry-run]
+ ## 0.0.2 (2024-01-23)
+
+ This was a version bump only, there were no code changes.

NX   Staging changed files with git


NOTE: The "dryRun" flag means no changelogs were actually created.

NX   Committing changes with git


NX   Tagging commit with git

Skipped publishing packages.
```

### Run without `--dry-run`

If the preview looks good, run the command again without the `--dry-run` option to actually create the release.

```shell
nx release --first-release
```

The command will proceed as before, prompting for a version bump and showing a preview of the changes. However, this time, it will prompt you to publish the packages to NPM. If you say no, the publishing step will be skipped. If you say yes, the command will publish the packages to the NPM registry.

```text {% frame="terminal" title="nx release --first-release" %}
...

✔ Do you want to publish these versions? (y/N) · true

NX   Running target nx-release-publish for 3 projects:

- pkg-1
- pkg-2
- pkg-3

—————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

> nx run pkg-1:nx-release-publish


📦  @myorg/pkg-1@0.0.2
=== Tarball Contents ===

233B README.md
277B package.json
53B  src/index.ts
61B  src/lib/pkg-1.ts
=== Tarball Details ===
name:          @myorg/pkg-1
version:       0.0.2
filename:      testorg-pkg-1-0.0.2.tgz
package size:  531 B
unpacked size: 624 B
shasum:        {shasum}
integrity:     {integrity}
total files:   12

Published to https://registry.npmjs.org with tag "latest"

> nx run pkg-2:nx-release-publish


📦  @myorg/pkg-2@0.0.2
=== Tarball Contents ===

233B README.md
277B package.json
53B  src/index.ts
61B  src/lib/pkg-2.ts
=== Tarball Details ===
name:          @myorg/pkg-2
version:       0.0.2
filename:      testorg-pkg-2-0.0.2.tgz
package size:  531 B
unpacked size: 624 B
shasum:        {shasum}
integrity:     {integrity}
total files:   12

Published to https://registry.npmjs.org with tag "latest"

> nx run pkg-3:nx-release-publish


📦  @myorg/pkg-3@0.0.2
=== Tarball Contents ===

233B README.md
277B package.json
53B  src/index.ts
61B  src/lib/pkg-3.ts
=== Tarball Details ===
name:          @myorg/pkg-3
version:       0.0.2
filename:      testorg-pkg-3-0.0.2.tgz
package size:  531 B
unpacked size: 624 B
shasum:        {shasum}
integrity:     {integrity}
total files:   12

Published to https://registry.npmjs.org with tag "latest"

—————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

NX   Successfully ran target nx-release-publish for 3 projects

```

## Manage git operations

By default, Nx Release will stage all changes it makes with git. This includes updating `package.json` files, creating changelog files, and updating the `package-lock.json` file. After staging the changes, Nx Release will commit the changes and create a git tag for the release.

### Customize the commit message and tag pattern

The commit message created by Nx Release defaults to 'chore(release): publish {version}', where `{version}` will be dynamically interpolated with the relevant value based on your actual release, but can be customized with the `release.git.commitMessage` property in nx.json.

The structure of the git tag defaults to `v{version}`. For example, if the version is `1.2.3`, the tag will be `v1.2.3`. This can be customized by setting the `release.releaseTag.pattern` property (Nx 22+) or `release.releaseTagPattern` property (Nx < 22) in nx.json.

For this same example, if you want the commit message to be 'chore(release): 1.2.3' and the tag to be `release/1.2.3`, you would configure nx.json like this:

{% tabs syncKey="nx-release-configuration" %}
{% tabitem label="Nx 22+" %}

```json
// nx.json
{
  "release": {
    "releaseTag": {
      "pattern": "release/{version}"
    },
    "git": {
      "commitMessage": "chore(release): {version}"
    }
  }
}
```

{% /tabitem %}
{% tabitem label="Nx < 22" %}

```json
// nx.json
{
  "release": {
    "releaseTagPattern": "release/{version}",
    "git": {
      "commitMessage": "chore(release): {version}"
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

When using release groups in which the member projects are versioned together, you can also leverage `{releaseGroupName}` and it will be interpolated appropriately in the commit/tag that gets created for that release group.

## Future releases

After the first release, the `--first-release` option will no longer be required. Nx Release will expect to find git tags and changelog files for each package. It will also use `npm view` to look up the current version of packages before publishing, ensuring that the package has not already been published and therefore avoid any conflict errors, meaning you can run the same publish action multiple times without any negative side-effects.

Future releases will also generate entries in `CHANGELOG.md` based on the changes since the last release. Nx Release will parse the `feat` and `fix` type commits according to the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification and sort them into appropriate sections of the changelog. An example of these changelogs can be seen on the [Nx releases page](https://github.com/nrwl/nx/releases).

---
<!-- source: https://nx.dev/docs/guides/nx-release/release-projects-independently.md -->
## Release Projects Independently

Nx Release supports releasing projects independently. This is useful when you have a monorepo with projects that are not released on the same schedule.

You can also group projects into multiple release groups for increased flexibility and control. Learn more about [release groups](/docs/guides/nx-release/release-groups).

## Configure independent releases

To configure independent releases, add the following property to your `nx.json` file:

```json
// nx.json
{
  "release": {
    "projectsRelationship": "independent"
  }
}
```

## Differences from fixed releases

Nx release will behave differently when configured for independent releases.

### Prompt for multiple version bumps

When configured for independent releases, Nx Release will prompt for a version bump for each project that is being released. This allows the version of each project to differ over time.

### Create a git tag for each project

Since each project can have a different version, Nx Release will create a git tag for each project that is being released. By default, the tag for each project will follow the pattern `{projectName}@{version}`. For example, if the `pkg-1` project is being released with version `1.1.0`, its git tag will be `pkg-1@1.1.0`.

This can still be changed with the `release.releaseTag.pattern` property (Nx 22+) or `release.releaseTagPattern` (Nx < 22) in `nx.json`, but be sure to include `{projectName}` in the pattern so that each generated tag is unique.

For example, to generate the tags `release/pkg-1/1.1.0` and `release/pkg-2/1.2.1` for the `pkg-1` and `pkg-2` projects respectively, you would use the following configuration in nx.json:

{% tabs syncKey="nx-release-configuration" %}
{% tabitem label="Nx 22+" %}

```json
// nx.json
{
  "release": {
    "releaseTag": {
      "pattern": "release/{projectName}/{version}"
    }
  }
}
```

{% /tabitem %}
{% tabitem label="Nx < 22" %}

```json
// nx.json
{
  "release": {
    "releaseTagPattern": "release/{projectName}/{version}"
  }
}
```

{% /tabitem %}
{% /tabs %}

See the [`releaseTag.pattern` documentation](/docs/reference/nx-json#release-tag) for more details on how to customize the tag pattern.

### Different commit message structure

Even though Nx Release creates a git tag for each project, it will still create a single commit for the entire release. The commit message will still include all of the projects being released with their corresponding version. For example:

```text
chore(release): publish

  - project: pkg-1 1.1.0

  - project: pkg-2 1.2.1

  - project: pkg-3 2.5.7
```

### Changelogs

Nx Release will no longer generate and update a workspace level `CHANGELOG.md` file when configured for independent releases. If you still want changelog generation, you will need to enable project level changelogs. These are similar to the workspace level changelog, but they are generated for each project individually and only contain changes for that specific project. They can be configured with the `release.changelog.projectChangelogs` property in `nx.json`.

```json
// nx.json
{
  "release": {
    "changelog": {
      "projectChangelogs": true
    }
  }
}
```

Just like with [fixed releases](/docs/guides/nx-release/release-npm-packages), you can preview changes to the changelog files by running Nx Release with the `--dry-run` option.

## Use the projects filter

One of the key benefits of independent releases is the ability to release only a subset of projects. Nx Release supports this with the `--projects` option. See the [`nx release`](/docs/reference/nx-commands#nx-release) CLI reference for all available options. The value is an array of strings, and you can use any of the same specifiers that are supported by `nx run-many`'s [projects filtering](/docs/reference/nx-commands#nx-run-many), such as explicit project names, Nx tags, directories and glob patterns, including negation using the `!` character. A few examples:

Release only the `pkg-1` and `pkg-2` projects:

```shell
nx release --projects=pkg-1,pkg-2
```

Release all projects in the `server` directory:

```shell
nx release --projects=server/*
```

Release all projects except those in the `ui` directory:

```shell
nx release --projects='!ui/*'
```

All other projects in the workspace will be ignored and only those that match the filter will be versioned, have their changelogs updated, and published.

## Update dependents

For independently versioned projects, we will have to consider what happens when those projects depend on one another.

```json
// nx.json
{
  "release": {
    "projectsRelationship": "independent",
    // The projects are independently versioned, but project-a depends on
    // project-b, so we need to consider the side-effects of updating project-b
    "projects": ["project-a", "project-b"]
  }
}
```

Nx can handle this cascade of updates automatically, across any number of release group boundaries, and this behavior is configurable via the `version.updateDependents` option.

See the [Update Dependents](/docs/guides/nx-release/update-dependents) guide for more details.

---
<!-- source: https://nx.dev/docs/guides/nx-release/update-dependents.md -->
## Update Dependents

When versioning independently maintained projects, we will have to consider what happens when those projects depend on one another.

For example, `project-a` might be version `1.0.0` and `project-b` might be version `2.0.0`, where `project-a` depends on `project-b`:

`project-a -> project-b`.

**In other words, `project-a` is a dependent of `project-b`, and `project-b` is a dependency of `project-a`.**

This means that whenever we update `project-b` we need to consider the side-effects of that on `project-a`. There will now be a dependency reference, e.g. in a manifest file such as `package.json` for the TypeScript/JavaScript ecosystem, that needs to be updated to reflect the new version of `project-b`.

Nx can handle this cascade of updates automatically, across any number of [Release Group](/docs/guides/nx-release/release-groups) boundaries, and this behavior is configurable via the `version.updateDependents` option.

### Update dependents configuration

- **`"always"`** (introduced in v22 and now the default): Always update dependents when a dependency is versioned, regardless of which group they belong to, or what filters are applied to the release command/programmatic API.
- **`"auto"`**: (old default) Update dependents within the same release group, and only when not filtered out by `--projects` or `--groups`
- **`"never"`**: Never automatically update dependents

When Nx release detects that a side-effectful bump needs to be made, e.g. in our example to `project-a`, it will update any dependency references in manifest files (e.g. `project-a/package.json`), and bump `project-a`'s own version to the next appropriate patch version.

For example, if `project-b` is bumped to version `2.1.0`, `project-a` will be updated to depend on `project-b@2.1.0`, and `project-a` will be bumped to version `1.0.1`.

```json
// Before
{
  "name": "project-a",
  "version": "1.0.0",
  "dependencies": {
    "project-b": "2.0.0"
  }
}
```

```json
// After
{
  "name": "project-a",
  "version": "1.0.1", // Side-effectful patch of project-a
  "dependencies": {
    "project-b": "2.1.0" // New version of project-b
  }
}
```

---
<!-- source: https://nx.dev/docs/guides/nx-release/update-local-registry-setup.md -->
## Update Your Local Registry Setup to use Nx Release

Nx will create a `tools/start-local-registry.ts` script for starting a local registry and publishing packages to it in preparation for running end to end tests. If you have an existing `tools/start-local-registry.ts` script from a previous version of Nx, you should update it to use Nx Release to publish packages to the local registry. This will ensure that newly generated libraries are published appropriately when running end to end tests.

## The previous version

The previous version of the `tools/start-local-registry.ts` script used publish targets on each project to publish the packages to the local registry. This is no longer necessary with Nx Release. You can identify the previous version by the `nx run-many` command that publishes the packages:

```typescript
/**
 * This script starts a local registry for e2e testing purposes.
 * It is meant to be called in jest's globalSetup.
 */
import { startLocalRegistry } from '@nx/js/plugins/jest/local-registry';
import { execFileSync } from 'child_process';

export default async () => {
  // local registry target to run
  const localRegistryTarget = '@demo-plugin-1800/source:local-registry';
  // storage folder for the local registry
  const storage = './tmp/local-registry/storage';

  global.stopLocalRegistry = await startLocalRegistry({
    localRegistryTarget,
    storage,
    verbose: false,
  });
  const nx = require.resolve('nx/bin/nx');
  execFileSync(
    nx,
    ['run-many', '--targets', 'publish', '--ver', '0.0.0-e2e', '--tag', 'e2e'],
    { env: process.env, stdio: 'inherit' }
  );
};
```

If your script looks like this, you should update it.

## The updated version

The updated version of the `tools/start-local-registry.ts` script uses Nx Release to publish the packages to the local registry. This is done by running `releaseVersion` and `releasePublish` functions from `nx/release`. Your updated script should look like this:

```typescript
/**
 * This script starts a local registry for e2e testing purposes.
 * It is meant to be called in jest's globalSetup.
 */
import { startLocalRegistry } from '@nx/js/plugins/jest/local-registry';
import { execFileSync } from 'child_process';
import { releasePublish, releaseVersion } from 'nx/release';

export default async () => {
  // local registry target to run
  const localRegistryTarget = '@demo-plugin-1800/source:local-registry';
  // storage folder for the local registry
  const storage = './tmp/local-registry/storage';

  global.stopLocalRegistry = await startLocalRegistry({
    localRegistryTarget,
    storage,
    verbose: false,
  });

  await releaseVersion({
    specifier: '0.0.0-e2e',
    stageChanges: false,
    gitCommit: false,
    gitTag: false,
    firstRelease: true,
    versionActionsOptionsOverrides: {
      skipLockFileUpdate: true,
    },
  });
  await releasePublish({
    tag: 'e2e',
    firstRelease: true,
  });
};
```

---
<!-- source: https://nx.dev/docs/guides/nx-release/updating-version-references.md -->
## Updating Version References in Manifest Files

The versioning stage of Nx Release is customizable and programming language agnostic, but some of its capabilities are dictated by the tooling you are using. This is particularly true when it comes to updating version references in manifest files, such as `package.json`.

Nx provides the TypeScript/JavaScript (and therefore `package.json`) functionality out of the box, so that is what will be covered in more detail in this recipe. For other ecosystems, please see the documentation of the respective plugins.

An important characteristic of Nx release is that it does not directly manipulate your packages in memory before releasing them. This maintains complete transparency between you and the tooling being leveraged to publish your packages, such as `npm publish` or `pnpm publish`, which are leveraged automatically by Nx Release during its publishing phase. The relevance of this will become clear for [Scenario 4 below](#scenario-4-i-want-to-update-package-versions-directly-in-my-source-files-but-use-local-dependency-references-via-fileworkspace).

{% aside type="note" title="Breaking Changes in Nx v21" %}
In Nx v21, the implementation details of versioning were rewritten to enhance flexibility and allow for better cross-ecosystem support. An automated migration was provided in Nx v21 to update your configuration to the new format when running `nx migrate`.

The following examples shows the Nx v21 and later configuration format, you can view the v20 version of the website to see the legacy format.
{% /aside %}

## Scenario 1: I want to update semantic version numbers directly in my source package.json files

This is the simplest scenario, and default behavior of Nx Release. If you have a TypeScript/JavaScript project which lives at e.g. `packages/my-project` with its package.json at the root of the project, you can run `nx release` or use the programmatic API and it will update the version number and all relevant intra-workspace dependency references in `packages/my-project/package.json` to the new version(s).

For example, with the following project structure:

{% filetree %}

- packages/
  - my-project/
    - package.json
  - my-other-project-in-the-monorepo/
    - package.json

{% /filetree %}

And starting point for package.json sources:

```json
// packages/my-project/package.json
{
  "name": "my-project",
  "version": "0.1.1",
  "dependencies": {
    "my-other-project-in-the-monorepo": "0.1.1"
  }
}
```

```json
// packages/my-other-project-in-the-monorepo/package.json
{
  "name": "my-other-project-in-the-monorepo",
  "version": "0.1.1"
}
```

When running `nx release` and applying a patch release, the following changes will be made to the source package.json files:

```json
// packages/my-project/package.json
{
  "name": "my-project",
  "version": "0.1.2",
  "dependencies": {
    "my-other-project-in-the-monorepo": "0.1.2"
  }
}
```

```json
// packages/my-other-project-in-the-monorepo/package.json
{
  "name": "my-other-project-in-the-monorepo",
  "version": "0.1.2"
}
```

By default, the changes will be staged and committed unless git operations are disabled.

## Scenario 2: I want to publish from a custom dist directory and update references in my both my source and dist package.json files

Nx Release has the concept of a "manifest root", which is different than the project root. The manifest root is the directory from which the project is versioned. By default, the manifest root is the project root detected by Nx as we have seen in Scenario 1 above, but the manifest root can be configured independently to be one or more other locations than the project root.

As of Nx v21, multiple manifest roots can be configured using the `release.version.manifestRootsToUpdate` option, resulting in multiple manifest files (such as `package.json`) being updated at once for a single project during a the versioning phase.

If, for example, we want to build our projects to a centralized `dist/` directory in the Nx workspace, and update both the source and dist package.json files when versioning, we can tell Nx Release to discover it for the versioning and publishing steps by adding the following configuration to the `nx.json` file, or the `project.json` file of relevant projects:

```jsonc
// nx.json
{
  "release": {
    // Ensure that versioning works in both the source and dist directories
    "version": {
      // path structures for both the source and dist directories, where {projectRoot} and {projectName} are available placeholders that will be interpolated by Nx
      "manifestRootsToUpdate": [
        "{projectRoot}",
        // We use the object form of the manifestRootsToUpdate to specify that we want to update the dist package.json files and not preserve the local dependency references (if not using pnpm or bun)
        {
          "path": "dist/packages/{projectName}",
          "preserveLocalDependencyProtocols": false, // (NOT NEEDED WHEN USING pnpm or bun) because we need to ensure our dist package.json files are valid for publishing and the local dependency references such as "workspace:" and "file:" are removed
        },
      ],
    },
  },
  "targetDefaults": {
    // Ensure that publishing works from the dist directory
    // The nx-release-publish target is added implicitly behind the scenes by Nx Release, and we can therefore configure it in targetDefaults
    "nx-release-publish": {
      "options": {
        // the packageRoot property is specific the TS/JS nx-release-publish implementation, other ecosystem plugins may have different options
        "packageRoot": "dist/packages/{projectName}", // path structure for your dist directory, where {projectRoot} and {projectName} are available placeholders that will be interpolated by Nx
      },
    },
  },
}
```

## Scenario 3: I want to publish from a custom dist directory and not update references in my source package.json files

A slight modification of Scenario 2 above, where we want to publish from a custom dist directory and not update references in our source package.json files.

{% aside type="caution" title="The source control tracked package.json files are no longer the source of truth for the package version" %}
Because we are no longer updating the version references in the source package.json files, the source control tracked package.json files are no longer the source of truth for the package version. We need to reference git tags or the latest value in the registry as the source of truth for the package version instead. We will also need to handle intra-workspace dependency references in the source package.json files differently using file/workspace references, which will be covered below.
{% /aside %}

Because our source package.json files are no longer updated during versioning, we will need to handle intra-workspace dependency references in the source package.json files differently. The way to achieve this is by using local `file:` or `workspace:` references in the source package.json files.

For example, using our packages from Scenario 1 above, if we want to reference the `my-other-project-in-the-monorepo` project from `my-project`, we can update the source package.json file as follows:

```jsonc
// packages/my-project/package.json
{
  "name": "my-project", // note there is no version number in the source package.json file because it will never be updated
  "dependencies": {
    "my-other-project-in-the-monorepo": "workspace:*", // or "file:../my-other-project-in-the-monorepo", depending on your preference and which package manager you are using
  },
}
```

If the package manager we are using is not using pnpm or bun (See Scenario 4 below), we will need to let Nx release know that we want to overwrite the workspace reference with the actual version number when publishing, because since Nx v21 it will preserve them by default. We can do this by setting the `release.version.preserveLocalDependencyProtocols` option to `false` in the `nx.json` file:

```jsonc
// nx.json
{
  "release": {
    // Ensure that versioning works only in the dist directory
    "version": {
      "manifestRootsToUpdate": ["dist/packages/{projectName}"], // path structure for your dist directory, where {projectRoot} and {projectName} are available placeholders that will be interpolated by Nx
      "currentVersionResolver": "git-tag", // or "registry", because we are no longer referencing our source package.json as the source of truth for the current version
      "preserveLocalDependencyProtocols": false, // (NOT NEEDED WHEN USING pnpm or bun) because we need to ensure our dist package.json files are valid for publishing and the local dependency references are removed
    },
  },
  "targetDefaults": {
    // Ensure that publishing works from the dist directory
    // The nx-release-publish target is added implicitly behind the scenes by Nx Release, and we can therefore configure it in targetDefaults
    "nx-release-publish": {
      "options": {
        "packageRoot": "dist/packages/{projectName}", // path structure for your dist directory, where {projectRoot} and {projectName} are available placeholders that will be interpolated by Nx
      },
    },
  },
}
```

After applying a patch version, our dist package.json will therefore ultimately look like this:

```jsonc
// dist/packages/my-project/package.json
{
  "name": "my-project",
  "version": "0.1.2", // the version number is applied
  "dependencies": {
    "my-other-project-in-the-monorepo": "0.1.2", // the dependency reference is updated from the workspace reference to the actual version number (if not using pnpm or bun)
  },
}
```

This package.json is now valid and ready to be published to the registry with any package manager.

## Scenario 4: I want to update package versions directly in my source files, but use local dependency references via file/workspace

{% aside type="caution" title="This scenario is currently only fully supported when your package manager is pnpm or bun" %}
pnpm and bun are the only package managers that provide a publish command that both supports dynamically swapping the `file:` and `workspace:*` references with the actual version number at publish time, and provides the customization needed for us to wrap it. `yarn npm publish` does support the replacements but is very limited on customization options.
{% /aside %}

This is a more advanced scenario because it removes the clean separation of concerns between versioning and publishing. The reason for this is that the `file:` and `workspace:*` references simply have to be replaced with actual version numbers before they are written to the registry, otherwise they will break when a user tries to install the package. If versioning does not replace them, publishing needs to.

As mentioned at the start of this recipe, Nx Release intentionally does not manipulate your packages in memory during publishing, so this scenario is only supported when your package manager provides publishing functionality which dynamically swaps the local references. **Currently this is only supported by pnpm and bun.**

As of Nx v21, by default, `release.version.preserveLocalDependencyProtocols` is set to `true`, which means that `file:` and `workspace:*` references are preserved.

For example, using this source package.json file, when applying a patch release:

```jsonc
// packages/my-project/package.json
{
  "name": "my-project",
  "version": "0.1.2",
  "dependencies": {
    "my-other-project-in-the-monorepo": "workspace:*",
  },
}
```

Nx release will see this and update the "version" number to `0.1.3`, and leave the `workspace:*` reference alone:

```jsonc
// packages/my-project/package.json
{
  "name": "my-project",
  "version": "0.1.3", // our version number is updated as expected
  "dependencies": {
    // our workspace dependency reference is preserved
    "my-other-project-in-the-monorepo": "workspace:*",
  },
}
```

Again, this is not in a valid state to be published to the registry, and so the publishing step will need to handle this. **This is only supported by pnpm and bun**, in which case Nx Release invokes `pnpm publish` or `bun publish` instead of `npm publish` behind the scenes during publishing, and you will receive a clear error if you attempt to use such a package.json with npm or yarn.

---
<!-- source: https://nx.dev/docs/guides/tasks--caching.md -->
## Tasks & Caching

{% index_page_cards path="guides/tasks--caching" /%}

---
<!-- source: https://nx.dev/docs/guides/tasks--caching/change-cache-location.md -->
## Change Cache Location

By default the cache is stored locally in `.nx/cache`. Cache results are stored for a week before they get deleted. You can customize the cache location in the `nx.json` file:

```json
// nx.json
{
  "cacheDirectory": "/tmp/mycache"
}
```

---
<!-- source: https://nx.dev/docs/guides/tasks--caching/configure-inputs.md -->
## Configure Inputs for Task Caching

When Nx [computes the hash for a given operation](/docs/concepts/how-caching-works), it takes into account the `inputs` of the target.
The `inputs` are a list of file sets, runtime inputs, and environment variables that affect the output of the target.
If any of the `inputs` change, the cache is invalidated and the target is re-run.

Nx errs on the side of caution when using inputs. Ideally, the "perfect" configuration of inputs will allow Nx to never re-run something when it does not need to. In practice though, it is better to play it safe and include more than strictly necessary in the inputs of a task. Forgetting to consider something during computation hash calculation may lead to negative consequences for end users. Start safe and fine-tune your inputs when there are clear opportunities to improve the cache hit rate.

For an overview of all the possible [types of inputs](/docs/reference/inputs) and how to reuse sets of inputs as [named inputs](/docs/reference/inputs#named-inputs), see the reference documentation.

{% aside type="caution" title="Directory Paths Require Trailing Slash or Glob" %}
When specifying a directory as an input, you must use a trailing slash (`/`) or a glob pattern. For example, `{projectRoot}/src/` or `{projectRoot}/src/**/*` will match all files in the `src` directory, but `{projectRoot}/src` (without trailing slash) will not match any files. This differs from `outputs`, which support naked directory paths.
{% /aside %}

Throughout this recipe, the following project structure of a simple workspace will be used as an example to help understand inputs better.

{% graph height="450px" %}

```json
{
  "projects": [
    {
      "name": "myreactapp",
      "type": "app",
      "data": {
        "tags": []
      }
    },
    {
      "name": "shared-ui",
      "type": "lib",
      "data": {
        "tags": []
      }
    }
  ],
  "dependencies": {
    "myreactapp": [
      { "source": "myreactapp", "target": "shared-ui", "type": "static" }
    ],
    "shared-ui": []
  },
  "workspaceLayout": { "appsDir": "", "libsDir": "" },
  "affectedProjectIds": [],
  "focus": null,
  "groupByFolder": false
}
```

{% /graph %}

## View the inputs of a task

You can view the configuration for a task of a project by adding the `--graph` flag when running the command:

```shell
nx build myreactapp --graph
```

This will show the task graph executed by Nx when running the command.

Clicking the task will open a tooltip which lists out all of the inputs of the task. A button within the tooltip will also reveal more details about the configuration for the project which the task belongs to.

Doing so will show a view such as the one below:

{% project_details%}

```json
{
  "project": {
    "name": "myreactapp",
    "type": "app",
    "data": {
      "root": "apps/myreactapp",
      "targets": {
        "build": {
          "options": {
            "cwd": "apps/myreactapp",
            "command": "vite build"
          },
          "cache": true,
          "dependsOn": ["^build"],
          "inputs": [
            "production",
            "^production",
            {
              "externalDependencies": ["vite"]
            }
          ],
          "outputs": ["{workspaceRoot}/dist/apps/myreactapp"],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["vite"]
          }
        },
        "serve": {
          "options": {
            "cwd": "apps/myreactapp",
            "command": "vite serve",
            "continuous": true
          },
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["vite"]
          }
        },
        "preview": {
          "options": {
            "cwd": "apps/myreactapp",
            "command": "vite preview"
          },
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["vite"]
          }
        },
        "serve-static": {
          "executor": "@nx/web:file-server",
          "options": {
            "buildTarget": "build",
            "continuous": true
          },
          "configurations": {}
        },
        "test": {
          "options": {
            "cwd": "apps/myreactapp",
            "command": "vitest run"
          },
          "cache": true,
          "inputs": [
            "default",
            "^production",
            {
              "externalDependencies": ["vitest"]
            }
          ],
          "outputs": ["{workspaceRoot}/coverage/apps/myreactapp"],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["vite"]
          }
        },
        "lint": {
          "cache": true,
          "options": {
            "cwd": "apps/myreactapp",
            "command": "eslint ."
          },
          "inputs": [
            "default",
            "{workspaceRoot}/.eslintrc.json",
            "{workspaceRoot}/apps/myreactapp/.eslintrc.json",
            "{workspaceRoot}/tools/eslint-rules/**/*",
            {
              "externalDependencies": ["eslint"]
            }
          ],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["eslint"]
          }
        }
      },
      "name": "myreactapp",
      "$schema": "../../../node_modules/nx/schemas/project-schema.json",
      "sourceRoot": "apps/myreactapp/src",
      "projectType": "application",
      "tags": [],
      "implicitDependencies": [],
      "metadata": {
        "technologies": ["react"]
      }
    }
  },
  "sourceMap": {
    "root": ["apps/myreactapp/project.json", "nx/core/project-json"],
    "targets": ["apps/myreactapp/project.json", "nx/core/project-json"],
    "targets.build": ["apps/myreactapp/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.command": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.options": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.cache": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.dependsOn": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.inputs": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.outputs": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.options.cwd": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.serve": ["apps/myreactapp/vite.config.ts", "@nx/vite/plugin"],
    "targets.serve.command": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.serve.options": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.serve.options.cwd": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.preview": ["apps/myreactapp/vite.config.ts", "@nx/vite/plugin"],
    "targets.preview.command": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.preview.options": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.preview.options.cwd": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.serve-static": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.serve-static.executor": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.serve-static.options": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.serve-static.options.buildTarget": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.test": ["apps/myreactapp/vite.config.ts", "@nx/vite/plugin"],
    "targets.test.command": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.test.options": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.test.cache": ["apps/myreactapp/vite.config.ts", "@nx/vite/plugin"],
    "targets.test.inputs": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.test.outputs": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.test.options.cwd": [
      "apps/myreactapp/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.lint": ["apps/myreactapp/project.json", "@nx/eslint/plugin"],
    "targets.lint.command": [
      "apps/myreactapp/project.json",
      "@nx/eslint/plugin"
    ],
    "targets.lint.cache": ["apps/myreactapp/project.json", "@nx/eslint/plugin"],
    "targets.lint.options": [
      "apps/myreactapp/project.json",
      "@nx/eslint/plugin"
    ],
    "targets.lint.inputs": [
      "apps/myreactapp/project.json",
      "@nx/eslint/plugin"
    ],
    "targets.lint.options.cwd": [
      "apps/myreactapp/project.json",
      "@nx/eslint/plugin"
    ],
    "name": ["apps/myreactapp/project.json", "nx/core/project-json"],
    "$schema": ["apps/myreactapp/project.json", "nx/core/project-json"],
    "sourceRoot": ["apps/myreactapp/project.json", "nx/core/project-json"],
    "projectType": ["apps/myreactapp/project.json", "nx/core/project-json"],
    "tags": ["apps/myreactapp/project.json", "nx/core/project-json"]
  }
}
```

{% /project_details %}

Nx Console has a button which will show a preview of this screen when a project level configuration file (`project.json` or `package.json`) is opened in the IDE. Read more at [Nx Console Project Details View](/docs/guides/nx-console/console-project-details).

Another way of accessing this information is to run `nx show project myreactapp --web` and the view above will be opened in a browser.

Use this tool to help understand what inputs are being used by Nx in your workspace.

{% aside title="Note" type="note" %}
If no `inputs` are specified at all, Nx will default to looking at all files of a project and its dependencies. This is a rather cautious approach. This might cause Nx to re-run a task in some cases where the cache could have been used instead but it will always give you correct output.
{% /aside %}

## Configure inputs

The tasks you run in your workspace will likely already have `inputs` defined.
Be sure to [view the existing inputs](#viewing-the-inputs-of-a-task) and start from there.

Inputs of a task are configured in the `inputs` array on the target. This can be done in several different places:

- Nx Plugins often [infer inputs for tasks](/docs/concepts/inferred-tasks) which run other tools.
  - In doing so, they will also define some reasonable defaults for the `inputs` of those tasks.
- The `inputs` array in the `targetDefaults` for a set of targets in `nx.json`.
- The `inputs` array for a specific target in the project configuration file.

{% aside title="Copy the existing inputs before modifying inputs for a task" %}
To override the `inputs` of a task, start by copying over the entire array shown when [viewing the project details](#viewing-the-inputs-of-a-task) and then add/modify/remove inputs as needed.
{% /aside %}

As you configure `inputs`, keep the project details screen open and it will refresh as changes are made. Check to make sure that the intended configuration is shown.

### Workspace level inputs

[Target Defaults](/docs/reference/nx-json#target-defaults) defined in `nx.json` apply to a set of targets. Defining `inputs` here one time will apply to a set of similar targets.

```jsonc {% meta="{5}" %}
// nx.json
{
  "targetDefaults": {
    "build": {
      "inputs": ["production", "^production"],
    },
  },
}
```

The above specifies that all targets with the name `build` will use the `inputs` specified.
This configuration will override any `inputs` inferred by Nx Plugins as you have more direct control in your `nx.json` than the behavior of the Nx Plugin.
The configuration defined here completely overwrites any `inputs` inferred by Nx Plugins and is not merged in any way.
This configuration may be overridden by configuration in project-specific configuration files.

### Project level inputs

Defining `inputs` of a target in `project.json` or `package.json` will apply only to tasks of the specific project.

{% tabs %}
{% tabitem label="project.json" %}

```jsonc {% meta="{6}" %}
// apps/myreactapp/project.json
{
  "name": "myreactapp",
  "targets": {
    "build": {
      "inputs": ["production", "^production"],
    },
  },
}
```

{% /tabitem %}
{% tabitem label="package.json" %}

```jsonc {% meta="{9}" %}
// apps/myreactapp/package.json
{
  "name": "myreactapp",
  "dependencies": {},
  "devDependencies": {},
  ...
  "nx": {
    "targets": {
      "build": {
        "inputs": ["production", "^production"]
      }
      ...
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

The above specifies that the `build` target of the `myreactapp` project will use the `inputs` specified.
This configuration will override any `inputs` inferred by Nx Plugins as well as any `inputs` defined in the [Target Defaults](/docs/reference/nx-json#target-defaults) in the `nx.json` file as this is more specific than those other methods of configuring `inputs`.
The configuration defined here completely overwrites any `inputs` inferred by Nx Plugins or in target defaults and is not merged in any way.

## Common inputs

### Test and config files

Often, projects include some files with runtime behavior and other files for unit testing. When running the `build` task, we do not want Nx to consider test files so updating the test files does not invalidate the cache for `build` tasks.

Plugins which define compile or bundling tasks such as `@nx/webpack/plugin` and `@nx/vite/plugin` will use the following inputs:

```jsonc
"inputs": [
  "production", // All files in a project excluding test files
  "^production" // Inputs of a dependencies which may affect behavior of projects which depend on them
]
```

Plugins which define testing tasks such as `@nx/cypress/plugin`, `@nx/playwright/plugin`, `@nx/jest/plugin` and `@nx/vite/plugin` will infer the following inputs for tasks:

```jsonc
"inputs": [
  "default", // All files in a project including test files
  "^production" // Inputs of a dependencies which may affect behavior of projects which depend on them
]
```

Given the above configurations, exclude the test and config files from the `production` named input:

```jsonc {% meta="{5-9}" %}
// nx.json
{
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "production": [
      "default",
      "!{projectRoot}/jest.config.ts",
      "!{projectRoot}/**/?(*.)+(spec|test).ts",
    ],
  },
}
```

With the above named inputs, Nx will behave in the following way:

- When only test files are changed, Nx will restore previous compilation results from the cache and re-run the tests for the projects containing the test files
- When any production files are changed, Nx will re-run the tests for the project as well as any projects which depend on it

### Specifying dependency file patterns directly

Instead of defining a named input and referencing it with `^`, you can directly specify file patterns to consider from dependency projects using the `^{projectRoot}` syntax:

```jsonc
// nx.json
{
  "targetDefaults": {
    "build": {
      "inputs": [
        "production",
        "^{projectRoot}/src/**/*.ts", // Only consider .ts source files from dependencies
      ],
    },
  },
}
```

This is useful when you want fine-grained control over which files from dependencies affect a task's cache without creating a named input. For example, a `build` task might only need to consider `.ts` files from its dependencies rather than all production files.

You can also use the object format with the `dependencies` property:

```jsonc
{
  "inputs": [
    "production",
    { "fileset": "{projectRoot}/src/**/*.ts", "dependencies": true },
  ],
}
```

### Consider the version of a language for all tasks

Many times, the version of the programming language being used will affect the behavior of all tasks for the workspace.
A runtime input can be added to the `sharedGlobals` named input to consider it for the hash of every task.

For example, to consider the version of Node.js in the hash of every task, add `node --version` as an input.

```jsonc {% meta="{5}" %}
// nx.json
{
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "sharedGlobals": [{ "runtime": "node --version" }],
  },
}
```

---
<!-- source: https://nx.dev/docs/guides/tasks--caching/configure-outputs.md -->
## Configure Outputs for Task Caching

Whenever Nx runs a cacheable task, it will store the results of that task in the cache.
When Nx runs the task again, if the [inputs for that task](/docs/guides/tasks--caching/configure-inputs) have not changed, it will restore the results from the cache instead of spending the time to run the task again.

## Types of outputs

### Terminal output

The terminal output of a task is replayed whenever a task is pulled from cache. Nx will always cache the terminal output of tasks which are cached.

### Output files

Targets can define which files are produced when a task is run. Nx will cache these files so that it can restore them when the task is pulled from cache.

These outputs files can be specified in several ways:

```jsonc
"outputs": [
  "{projectRoot}/dist/libs/mylib", // A directory
  "{workspaceRoot}/dist/{projectRoot}", // A directory based on the project's root
  "{workspaceRoot}/dist/{projectName}", // A directory based on the project's name
  "{workspaceRoot}/test-results.xml", // A file
  "{projectRoot}/dist/libs/mylib/**/*.js", // A glob pattern matching a set of files
  "{options.outputPath}", // A path defined in the options of a task
]
```

All outputs explicitly specifying paths must be prefixed with either `{projectRoot}` or `{workspaceRoot}` to distinguish where the path is resolved from. `{workspaceRoot}` should only appear in the beginning of an `output` but `{projectRoot}` and `{projectName}` can be specified later in the `output` to interpolate the root or name of the project into the output location.

Outputs can also be determined from the `options` of running a task via the `{options.[propertyName]}` syntax.
This is useful when an option for the task determines the output location and could be modified when the task is run.
This path is resolved from the root of the workspace.

If an output file or directory does not exist, it will be ignored.

## View outputs of a task

The outputs of a task can be viewed by adding the `--graph` flag to the command:

```shell
nx build myapp --graph
```

This will open the task graph in the browser.
Clicking on a task in the graph will open a tooltip with a link to see details about the project.
View the project's configuration to see a list of the outputs which are defined for each target.

## Configure outputs

The tasks you run in your workspace will likely already have `outputs` defined.
Be sure to [view the existing outputs](#viewing-outputs-of-a-task) and start from there.

Nx Plugins often [infer outputs for tasks](/docs/concepts/inferred-tasks) which run other tools.
Nx Plugins will look at the configuration files and/or command-line-arguments of the tools in your workspace to understand the outputs of running those tools.
In most cases, this inference will be inline with the outputs of the tool.
Nx will reflect changes to the configuration or command-line arguments of your tools without any additional changes.

In some cases, Nx plugins may not infer the outputs of a task as you expect, they can be configured in the `outputs` array on the target. This can be done in several different places:

- The `outputs` array in the `targetDefaults` for a set of targets in `nx.json`.
- The `outputs` array for a specific target in the project configuration file.

{% aside title="Copy the existing outputs before modifying outputs for a task" %}
To override the `outputs` of a task, start by copying over the entire array shown when [viewing the project details](#viewing-the-outputs-of-a-task) and then add/modify/remove outputs as needed.
{% /aside %}

As you configure `outputs`, keep the project details screen open and it will refresh as changes are made. Check to make sure that the intended configuration is shown.

### Workspace level outputs

[Target Defaults](/docs/reference/nx-json#target-defaults) defined in `nx.json` apply to a set of targets. Defining `outputs` here one time will apply to a set of similar targets.

```jsonc {% meta="{5}" %}
// nx.json
{
  "targetDefaults": {
    "build": {
      "outputs": ["{projectRoot}/dist"],
    },
  },
}
```

The above specifies Nx will cache the `dist` directory under all project roots for all targets with the name `build`.
This configuration will override any `outputs` inferred by Nx Plugins as you have more direct control in your `nx.json` than the behavior of the Nx Plugin.
The configuration defined here completely overwrites any `outputs` inferred by Nx Plugins and is not merged in any way.
This configuration may be overwritten by configuration in project-specific configuration files.

{% aside title="Warning" type="caution" %}
Specifying the same output location for multiple tasks often causes unintentional behavior. While sometimes this is intentional, try and ensure that a set of targets will yield unique output locations for the tasks belonging to different projects. Use the `{projectRoot}` and `{projectName}` notation to include unique characteristics of a project in the output.
{% /aside %}

### Project level outputs

Defining `outputs` of a target in `project.json` or `package.json` will apply only to tasks of the specific project.

{% tabs %}
{% tabitem label="project.json" %}

```jsonc {% meta="{6}" %}
// apps/myreactapp/project.json
{
  "name": "myreactapp",
  "targets": {
    "build": {
      "outputs": ["{projectRoot}/dist"],
    },
  },
}
```

{% /tabitem %}
{% tabitem label="package.json" %}

The `package.json` file may include configuration for a specific Nx project. Defining `outputs` of a target here will apply only to tasks of the specific project.

```jsonc {% meta="{10}" %}
// apps/myreactapp/package.json
{
  "name": "myreactapp",
  "dependencies": {},
  "devDependencies": {},
  ...
  "nx": {
    "targets": {
      "build": {
        "outputs": ["{projectRoot}/dist"]
      }
      ...
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

The above specifies that the `build` target of the `myreactapp` project will use the `outputs` specified.
This configuration will override any `outputs` inferred by Nx Plugins as well as any `outputs` defined in the [Target Defaults](/docs/reference/nx-json#target-defaults) in the `nx.json` file as this is more specific than those other methods of configuring `outputs`.
The configuration defined here completely overwrites any `outputs` inferred by Nx Plugins or in target defaults and is not merged in any way.

---
<!-- source: https://nx.dev/docs/guides/tasks--caching/convert-to-inferred.md -->
## Migrate to Inferred Tasks (Project Crystal)

In this recipe, you'll learn how to migrate an existing Nx workspace from using executors in `project.json` to using [inferred tasks](/docs/concepts/inferred-tasks).

The main benefits of migrating to inferred tasks are

- reducing the amount of configuration needed in `project.json`
- inferring the correct cache settings based on the tool configuration files
- [splitting tasks (Atomizer)](/docs/features/ci-features/split-e2e-tasks) for plugins that support it

{% youtube
src="https://youtu.be/wADNsVItnsM"
title="Project Crystal"
/%}

For the best experience, we recommend that you [migrate](/docs/features/automate-updating-dependencies) to the latest Nx version before continuing. At minimum, you should be on Nx version 19.6.

```shell
npx nx migrate latest
```

## Migrate all plugins

You can use the `infer-targets` generator to quickly migrate all available plugins to use inferred tasks. See the sections below for more details on the individual plugins' migration processes.

```shell
npx nx g infer-targets
```

The generator will automatically detect all available `convert-to-inferred` generators and run the ones you choose. If you only want to try it on a single project, pass the `--project` option.

## Migrate a single plugin

Most of the official plugins come with a `convert-to-inferred` generator. This generator will

- register the inference plugin in the `plugins` section of `nx.json`
- migrate executor options into the tool's configuration files (where applicable)
- clean up `project.json` to remove targets and options that are unnecessary

To get started, run `nx g convert-to-inferred`, and you'll be prompted to choose a plugin to migrate.

```text {% title="npx nx g convert-to-inferred" frame="terminal" %}
? Which generator would you like to use? …
@nx/eslint:convert-to-inferred
@nx/playwright:convert-to-inferred
@nx/vite:convert-to-inferred

None of the above
```

{% aside type="note" title="Third-party plugins" %}
For third-party plugins that provide `convert-to-inferred` generators, you should pick the `None of the above` option and type in the name of the package manually. Alternatively, you can also provide the package explicitly with `nx g <plugin>:convert-to-inferred`.
{% /aside %}

We recommend that you check that the configurations are correct before continuing to the next plugin. If you only want to try it on a single project, pass the `--project` option.

## Understand the migration process

The `convert-to-inferred` generator removes uses of executors from the corresponding plugin. For example, if `@nx/vite` is migrated, then uses of [`@nx/vite:build`](/docs/technologies/build-tools/vite/executors#build), [`@nx/vite:dev-server`](/docs/technologies/build-tools/vite/executors#dev-server), [`@nx/vite:preview-server`](/docs/technologies/build-tools/vite/executors#preview-server), and [`@nx/vite:test`](/docs/technologies/build-tools/vite/executors#test) executors will be removed.

Target and configuration names are maintained for each project in their `project.json` files. A target may be removed from `project.json` if everything is inferred--that is, options and configurations are not customized. To get the full project details (including all inferred tasks), run:

```shell
npx nx show project <project-name>
```

For example, if we migrated the `@nx/vite` plugin for a single app (i.e. `nx g @nx/vite:convert-to-inferred --project demo`), then running `nx show project demo` will show a screen similar to the following.

{% project_details title="Test" height="300px" %}

```json
{
  "project": {
    "name": "demo",
    "data": {
      "root": " apps/demo",
      "projectType": "application",
      "targets": {
        "serve": {
          "executor": "nx:run-commands",
          "options": {
            "command": "vite dev",
            "continuous": true
          }
        },
        "build": {
          "executor": "nx:run-commands",
          "inputs": ["production", "^production"],
          "outputs": ["{projectRoot}/dist"],
          "options": {
            "command": "vite build"
          }
        }
      }
    }
  },
  "sourceMap": {
    "targets": ["apps/demo/vite.config.ts", "@nx/vite"],
    "targets.serve": ["apps/demo/vite.config.ts", "@nx/vite"],
    "targets.build": ["apps/demo/vite.config.ts", "@nx/vite"]
  }
}
```

{% /project_details %}

You'll notice that the `serve` and `build` tasks are running the [Vite CLI](https://vite.dev/guide/cli.html) and there are no references to Nx executors. Since the targets directly invoke the Vite CLI, any options that may be passed to it can be passed via Nx commands. e.g. `nx serve demo --cors --port 8888` enables CORs and uses port `8888` using [Vite CLI options](https://vite.dev/guide/cli.html#options)
The same CLI setup applies to other plugins as well.

- `@nx/cypress` calls the [Cypress CLI](https://docs.cypress.io/guides/guides/command-line)
- `@nx/playwright` calls the [Playwright CLI](https://playwright.dev/docs/test-cli)
- `@nx/webpack` calls the [Webpack CLI](https://webpack.js.org/api/cli/)
- etc.

Read the recipe on [passing args to commands](/docs/guides/tasks--caching/pass-args-to-commands) for more information.

### Configuration file changes

There may also be changes to the configuration files used by the underlying tool. The changes come with comments to explain them, and may also provide next steps for you to take. One common change is to add support for different configuration options. For example, if we have an existing Vite app with the following build target:

```json
// project.json
"build": {
  "executor": "@nx/vite:build",
  "options": {
    "mode": "development"
  },
  "defaultConfiguration": "production",
  "configurations": {
    "development": {},
    "production": {},
    "ci": {}
  }
}
```

Where we have `development`, `production`, and `ci` configurations. Then running `nx g @nx/vite:convert-to-inferred` will result in these lines added to `vite.config.ts`.

```ts {% meta="{7-16}" %}
// vite.config.ts
/// <reference types='vitest' />
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';

// These options were migrated by @nx/vite:convert-to-inferred from the project.json file.
const configValues = { default: {}, development: {}, production: {}, ci: {} };

// Determine the correct configValue to use based on the configuration
const nxConfiguration = process.env.NX_TASK_TARGET_CONFIGURATION ?? 'default';

const options = {
  ...configValues.default,
  ...(configValues[nxConfiguration] ?? {}),
};

export default defineConfig({
  root: __dirname,
  cacheDir: '../../node_modules/.vite/apps/demo',
  // ...
});
```

The configuration changes ensure that passing `--configuration` still work for the target. Differences in options can be added to the `configValues` object, and the right value is determined using the `NX_TASK_TARGET_CONFIGURATION` [environment variable](/docs/reference/environment-variables). Again, there may be other types of changes so read the comments to understand them.

### Register the Plugin with Nx

Lastly, you can inspect the `nx.json` file to see a new `plugins` entry. For `@nx/vite`, there should be an entry like this:

```json
// nx.json
{
  "plugin": "@nx/vite/plugin",
  "options": {
    "buildTargetName": "build",
    "serveTargetName": "serve",
    "previewTargetName": "preview",
    "testTargetName": "test",
    "serveStaticTargetName": "serve-static"
  }
}
```

You may change the target name options to change how Nx adds them to the project. For example, if you use `"serveTargetName": "dev"` then you would run `nx dev demo` rather than `nx serve demo` for your Vite project.

## Verify the migration

The migrations maintain the same targets and configurations for each project, thus to verify it you should run the affected targets.

For example

- for `@nx/vite` you should check the `build`, `serve`, and `test` targets
- for `@nx/playwright` you should check the `e2e` targets
- for `@nx/eslint` you should check the `lint` target
- etc.

Remember that the target names are defined in the plugin configuration in `nx.json`.

Make sure that the tasks are all passing before migrating another plugin.

## Enable atomizer (task splitting)

These plugins come with the [Atomizer](/docs/features/ci-features/split-e2e-tasks) feature.

- `@nx/cypress`
- `@nx/jest`
- `@nx/gradle`
- `@nx/playwright`

The Atomizer splits potentially slow tasks into separate tasks per file. This feature along with [task distribution](/docs/features/ci-features/distribute-task-execution) can speed up CI by distributing the split tasks among many agents.

To enable Atomizer, make sure that you are [connected to Nx Cloud](/docs/guides/nx-cloud/setup-ci), and that you have distribution enabled in CI. Some plugins require extra configuration to enable Atomizer, so check the [individual plugin documentation page](/docs/plugin-registry) for more details.

{% call_to_action title="Connect to Nx Cloud" icon="nxcloud" description="Enable task distribution and Atomizer" url="/docs/guides/nx-cloud/setup-ci" /%}

## Troubleshooting

If you run into any issues during the migration, refer to the [troubleshooting guide](/docs/troubleshooting/troubleshoot-convert-to-inferred).

---
<!-- source: https://nx.dev/docs/guides/tasks--caching/defining-task-pipeline.md -->
## Defining a Task Pipeline

Running a specific task like `build` in a monorepo usually involves running multiple commands.

If you want to learn more about the concept of a task pipeline and its importance in a monorepo, have a look at [the What is a Task Pipeline page](/docs/concepts/task-pipeline-configuration).

{% youtube src="https://youtu.be/_U4hu6SuBaY?si=rSclPBdRh7P_xZ_f" title="Define a task pipeline" /%}

## Define dependencies between tasks

You can define dependencies among tasks by using the `dependsOn` property:

```json
// nx.json
{
  ...
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}
```

## Per project vs global

Task dependencies can be [defined globally](/docs/reference/nx-json#target-defaults) for all projects in `nx.json` file:

```json
// nx.json
{
  ...
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}
```

Or they can be [defined per-project](/docs/reference/project-configuration#dependson) in the `project.json` or `package.json` files. If for example you have a `prebuild` step for a given project, you can define that relationship as follows:

{% tabs %}
{% tabitem label="package.json" %}

```json
// apps/myapp/package.json
{
  "name": "myapp",
  "dependencies": {},
  "devDependencies": {},
  ...
  "nx": {
    "targets": {
      "build": {
        "dependsOn": [
          "prebuild"
        ]
      }
    }
  }
}
```

{% /tabitem %}
{% tabitem label="project.json" %}

```json
// apps/myreactapp/project.json
{
  "name": "myreactapp",
  ...
  "targets": {
    "prebuild": {
      "command": "echo Prebuild"
    },
    "build": {
      "command": "echo Build",
      "dependsOn": ["prebuild"]
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

## Continuous task dependencies

If a task has a dependency that never exits, then the task will never start. To support this scenario, you can mark the dependency as a [continuous task](/docs/reference/project-configuration#continuous). Labeling a task as continuous tells Nx to not wait for the process to exit, and it will be run alongside its dependents.

```json
// apps/myapp/project.json
{
  "targets": {
    "serve": {
      "continuous": true
    }
  }
}
```

The `continuous` option is most useful for running development servers. For example, the `e2e` task depends on a continuous `serve` task that starts the server to be tested againts.

## Visualize task dependencies

You can also visualize the actual task graph (alongside the projects) using [Nx graph](/docs/features/explore-graph). This can be useful for debugging purposes.

To view the task graph in your browser, run:

```shell
npx nx graph
```

And then select "Tasks" from the top-left dropdown, choose the target (e.g. `build`, `test`,..) and either show all tasks or select a specific project you're interested in. Here's an example of the `playwright` Nx plugin `build` target (in the [Nx repo](https://github.com/nrwl/nx)).

![Task graph of the Playwright Nx plugin in the nx repo being rendered in the browser](../../../../assets/guides/running-tasks/task-graph-playwright-nx.webp)

Alternatively you can use the [Nx Console](/docs/getting-started/editor-setup) extension in VSCode or IntelliJ, right-click on the project and select:

![Selecting "Focus task in Nx Graph" from the context menu in VS Code](../../../../assets/guides/running-tasks/task-graph-context-menu.webp)

It'll then visualize within the IDE:

![Task graph of the Playwright Nx plugin in the nx repo being rendered in VS Code](../../../../assets/guides/running-tasks/task-graph-vscode.webp)

---
<!-- source: https://nx.dev/docs/guides/tasks--caching/pass-args-to-commands.md -->
## Pass Args to Commands

When you have an [inferred task](/docs/concepts/inferred-tasks) (or an explicitly defined task using the [`nx:run-commands` executor](/docs/guides/tasks--caching/run-commands-executor#2-update)) running a command, there'll come a time when you'll need to pass args to the underlying command being run. This recipe explains how you can achieve that.

## Example project and tasks

For this recipe we'll use a project with the following `project.json` file:

```json
// apps/my-app/project.json
{
  "sourceRoot": "apps/my-app/src",
  "projectType": "application",
  "targets": {}
}
```

And the following [final configuration](/docs/reference/project-configuration):

{% project_details title="Project Details View" %}

```json
{
  "project": {
    "name": "my-app",
    "type": "app",
    "data": {
      "name": "my-app",
      "root": "apps/my-app",
      "sourceRoot": "apps/my-app/src",
      "projectType": "application",
      "targets": {
        "build": {
          "options": {
            "cwd": "apps/my-app",
            "command": "vite build"
          },
          "cache": true,
          "dependsOn": ["^build"],
          "inputs": [
            "production",
            "^production",
            {
              "externalDependencies": ["vite"]
            }
          ],
          "outputs": ["{workspaceRoot}/dist/apps/my-app"],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["vite"]
          }
        },
        "serve": {
          "options": {
            "cwd": "apps/my-app",
            "command": "vite serve"
          },
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["vite"]
          }
        },
        "preview": {
          "options": {
            "cwd": "apps/my-app",
            "command": "vite preview"
          },
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["vite"]
          }
        },
        "test": {
          "options": {
            "cwd": "apps/my-app",
            "command": "vitest run"
          },
          "cache": true,
          "inputs": [
            "default",
            "^production",
            {
              "externalDependencies": ["vitest"]
            }
          ],
          "outputs": ["{workspaceRoot}/coverage/apps/my-app"],
          "executor": "nx:run-commands",
          "configurations": {},
          "metadata": {
            "technologies": ["vite"]
          }
        }
      },
      "tags": [],
      "implicitDependencies": []
    }
  },
  "sourceMap": {
    "root": ["apps/my-app/project.json", "nx/core/project-json"],
    "targets": ["apps/my-app/project.json", "nx/core/project-json"],
    "targets.build": ["apps/my-app/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.command": ["apps/my-app/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.options": ["apps/my-app/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.cache": ["apps/my-app/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.dependsOn": [
      "apps/my-app/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.build.inputs": ["apps/my-app/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.outputs": ["apps/my-app/vite.config.ts", "@nx/vite/plugin"],
    "targets.build.options.cwd": [
      "apps/my-app/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.serve": ["apps/my-app/vite.config.ts", "@nx/vite/plugin"],
    "targets.serve.command": ["apps/my-app/vite.config.ts", "@nx/vite/plugin"],
    "targets.serve.options": ["apps/my-app/vite.config.ts", "@nx/vite/plugin"],
    "targets.serve.options.cwd": [
      "apps/my-app/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.preview": ["apps/my-app/vite.config.ts", "@nx/vite/plugin"],
    "targets.preview.command": [
      "apps/my-app/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.preview.options": [
      "apps/my-app/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.preview.options.cwd": [
      "apps/my-app/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "targets.test": ["apps/my-app/vite.config.ts", "@nx/vite/plugin"],
    "targets.test.command": ["apps/my-app/vite.config.ts", "@nx/vite/plugin"],
    "targets.test.options": ["apps/my-app/vite.config.ts", "@nx/vite/plugin"],
    "targets.test.cache": ["apps/my-app/vite.config.ts", "@nx/vite/plugin"],
    "targets.test.inputs": ["apps/my-app/vite.config.ts", "@nx/vite/plugin"],
    "targets.test.outputs": ["apps/my-app/vite.config.ts", "@nx/vite/plugin"],
    "targets.test.options.cwd": [
      "apps/my-app/vite.config.ts",
      "@nx/vite/plugin"
    ],
    "name": ["apps/my-app/project.json", "nx/core/project-json"],
    "$schema": ["apps/my-app/project.json", "nx/core/project-json"],
    "sourceRoot": ["apps/my-app/project.json", "nx/core/project-json"],
    "projectType": ["apps/my-app/project.json", "nx/core/project-json"],
    "tags": ["apps/my-app/project.json", "nx/core/project-json"]
  }
}
```

{% /project_details %}

We'll focus on the `build` target of the project. If you expand the `build` target in the Project Details View above, you'll see that it runs the command `vite build`. In the next sections, we'll see how to provide `--assetsInlineLimit=2048` and `--assetsDir=static/assets` args to that command.

## Pass args in the `project.json` task configuration

To statically pass some extra args to a specific project, you can update its `project.json` file. You can do it by either providing the args as individual options or by providing the `args` option:

{% tabs %}
{% tabitem label="Setting args directly as options" %}

{% aside type="note" title="Providing command args as options" %}
Support for providing command args as options was added in **Nx v18.1.1**.
{% /aside %}

```json {% meta="{6-11}" %}
// apps/my-app/project.json
{
  "sourceRoot": "apps/my-app/src",
  "projectType": "application",
  "targets": {
    "build": {
      "options": {
        "assetsInlineLimit": 2048,
        "assetsDir": "static/assets"
      }
    }
  }
}
```

{% /tabitem %}

{% tabitem label="Setting the \"args\" option" %}

```json {% meta="{6-12}" %}
// apps/my-app/project.json
{
  "sourceRoot": "apps/my-app/src",
  "projectType": "application",
  "targets": {
    "build": {
      "options": {
        "args": ["--assetsInlineLimit=2048", "--assetsDir=static/assets"]
        // it also accepts a single string:
        // "args": "--assetsInlineLimit=2048 --assetsDir=static/assets"
      }
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

{% aside type="caution" title="Precedence" %}
Args specified in the `args` option take precedence and will override any arg specified as an option with the same name. So, defining both `"args": ["--assetsDir=static/assets"]` and `"assetsDir": "different/path/to/assets"` will result in Nx running the command with `--assetsDir=static/assets`.
{% /aside %}

## Pass args in the `targetDefaults` for the task

To provide the same args for all projects in the workspace, you need to update the task configuration in the `nx.json` file. Similar to the previous section, you can do it by either providing the args as individual options or by providing the `args` option:

{% tabs %}
{% tabitem label="Setting args directly as options" %}

```json
// nx.json
{
  "targetDefaults": {
    "build": {
      "options": {
        "assetsInlineLimit": 2048,
        "assetsDir": "static/assets"
      }
    }
  }
}
```

{% /tabitem %}

{% tabitem label="Setting the \"args\" option" %}

```json
// nx.json
{
  "targetDefaults": {
    "build": {
      "options": {
        "args": ["--assetsInlineLimit=2048", "--assetsDir=static/assets"]
      }
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

{% aside type="caution" title="Be careful" %}
If multiple targets with the same name run different commands (or use different executors), do not set options in `targetDefaults`. Different commands would accept different options, and the target defaults will apply to all targets with the same name regardless of the command they run. If you were to provide options in `targetDefaults` for them, the commands that don't expect those options could throw an error.
{% /aside %}

## Pass args when running the command in the terminal

To pass args in a one-off manner when running a task, you can also provide them as individual options or by providing the `--args` option when running the task:

{% tabs %}
{% tabitem label="Providing args directly as options" %}

```shell
nx build my-app --assetsInlineLimit=2048 --assetsDir=static/assets
```

{% /tabitem %}

{% tabitem label="Providing the \"--args\" option" %}

```shell
nx build my-app --args="--assetsInlineLimit=2048 --assetsDir=static/assets"
```

{% /tabitem %}
{% /tabs %}

{% aside type="caution" title="Conflicting options" %}

If you provide an arg with the same name as an Nx CLI option (e.g. `--configuration`) or an `nx:run-commands` option (e.g. `--env`), the arg will be parsed as an option for the Nx CLI or the executor and won't be forwarded to the underlying command. You should provide the arg using the `-args` option in such cases.

You can also provide an arg with the same name to both the Nx CLI and the underlying command. For example, to run the `ci` configuration of a `test` target that runs the command `detox test` and pass the `--configuration` arg to the command, you can run:

```shell
nx test mobile-e2e --configuration=ci --args="--configuration=ios.sim.release"
```

{% /aside %}

---
<!-- source: https://nx.dev/docs/guides/tasks--caching/reduce-repetitive-configuration.md -->
## Reduce Repetitive Configuration

Nx can help you dramatically reduce the lines of configuration code that you need to maintain.

Lets say you have three libraries in your repository - `lib1`, `lib2` and `lib3`. The folder structure looks like this:

{% filetree %}

- repo/
  - libs/
    - lib1/
      - tsconfig.lib.json
      - project.json
    - lib2/
      - tsconfig.lib.json
      - project.json
    - lib3/
      - tsconfig.lib.json
      - project.json
  - nx.json

{% /filetree %}

## Initial configuration settings

All three libraries have a similar project configuration. Here is what their `project.json` files look like:

{% tabs %}
{% tabitem label="lib1" %}

```json
// libs/lib1/project.json
{
  "name": "lib1",
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "sourceRoot": "libs/lib1/src",
  "projectType": "library",
  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/libs/lib1",
        "main": "libs/lib1/src/index.ts",
        "tsConfig": "libs/lib1/tsconfig.lib.json",
        "assets": ["libs/lib1/*.md", "libs/lib1/src/images/*"]
      }
    },
    "lint": {
      "executor": "@nx/eslint:lint",
      "outputs": ["{options.outputFile}"],
      "options": {
        "lintFilePatterns": ["libs/lib1/**/*.ts"]
      }
    },
    "test": {
      "executor": "@nx/jest:jest",
      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
      "options": {
        "jestConfig": "libs/lib1/jest.config.ts",
        "passWithNoTests": true
      },
      "configurations": {
        "ci": {
          "ci": true,
          "codeCoverage": true
        }
      }
    }
  },
  "tags": []
}
```

{% /tabitem %}
{% tabitem label="lib2" %}

```json
// libs/lib2/project.json
{
  "name": "lib2",
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "sourceRoot": "libs/lib2/src",
  "projectType": "library",
  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/libs/lib2",
        "main": "libs/lib2/src/index.ts",
        "tsConfig": "libs/lib2/tsconfig.lib.json",
        "assets": ["libs/lib2/*.md"]
      }
    },
    "lint": {
      "executor": "@nx/eslint:lint",
      "outputs": ["{options.outputFile}"],
      "options": {
        "lintFilePatterns": ["libs/lib2/**/*.ts"]
      }
    },
    "test": {
      "executor": "@nx/jest:jest",
      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
      "options": {
        "jestConfig": "libs/lib2/jest.config.ts",
        "passWithNoTests": true,
        "testTimeout": 10000
      },
      "configurations": {
        "ci": {
          "ci": true,
          "codeCoverage": true
        }
      }
    }
  },
  "tags": []
}
```

{% /tabitem %}
{% tabitem label="lib3" %}

```json
// libs/lib3/project.json
{
  "name": "lib3",
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "sourceRoot": "libs/lib3/src",
  "projectType": "library",
  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/libs/lib3",
        "main": "libs/lib3/src/index.ts",
        "tsConfig": "libs/lib3/tsconfig.lib.json",
        "assets": ["libs/lib3/*.md"]
      }
    },
    "lint": {
      "executor": "@nx/eslint:lint",
      "outputs": ["{options.outputFile}"],
      "options": {
        "lintFilePatterns": ["libs/lib3/**/*.ts"]
      }
    },
    "test": {
      "executor": "@nx/jest:jest",
      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
      "options": {
        "jestConfig": "libs/lib3/jest.config.ts",
        "passWithNoTests": true
      },
      "configurations": {
        "ci": {
          "ci": true,
          "codeCoverage": true
        }
      }
    }
  },
  "tags": []
}
```

{% /tabitem %}
{% /tabs %}

If you scan through these three files, they look very similar. The only differences aside from the project paths are that `lib1` has different assets defined for the `build` target and `lib2` has a `testTimeout` set for the `test` target.

## Reduce configuration with targetDefaults

Let's use [the `targetDefaults` property](/docs/reference/nx-json#target-defaults) in `nx.json` to reduce some of this duplicate configuration code.

```json
// nx.json
{
  "targetDefaults": {
    "build": {
      "executor": "@nx/js:tsc",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/{projectRoot}",
        "main": "{projectRoot}/src/index.ts",
        "tsConfig": "{projectRoot}/tsconfig.lib.json",
        "assets": ["{projectRoot}/*.md"]
      }
    },
    "lint": {
      "executor": "@nx/eslint:lint",
      "outputs": ["{options.outputFile}"],
      "options": {
        "lintFilePatterns": ["{projectRoot}/**/*.ts"]
      }
    },
    "test": {
      "executor": "@nx/jest:jest",
      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
      "options": {
        "jestConfig": "{projectRoot}/jest.config.ts",
        "passWithNoTests": true
      },
      "configurations": {
        "ci": {
          "ci": true,
          "codeCoverage": true
        }
      }
    }
  }
}
```

Now the `project.json` files can be reduced to this:

{% tabs %}
{% tabitem label="lib1" %}

```json
// libs/lib1/project.json
{
  "name": "lib1",
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "sourceRoot": "libs/lib1/src",
  "projectType": "library",
  "targets": {
    "build": {
      "options": {
        "assets": ["libs/lib1/*.md", "libs/lib1/src/images/*"]
      }
    },
    "lint": {},
    "test": {}
  },
  "tags": []
}
```

{% /tabitem %}
{% tabitem label="lib2" %}

```json
// libs/lib2/project.json
{
  "name": "lib2",
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "sourceRoot": "libs/lib2/src",
  "projectType": "library",
  "targets": {
    "build": {},
    "lint": {},
    "test": {
      "options": {
        "testTimeout": 10000
      }
    }
  },
  "tags": []
}
```

{% /tabitem %}
{% tabitem label="lib3" %}

```json
// libs/lib3/project.json
{
  "name": "lib3",
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "sourceRoot": "libs/lib3/src",
  "projectType": "library",
  "targets": {
    "build": {},
    "lint": {},
    "test": {}
  },
  "tags": []
}
```

{% /tabitem %}
{% /tabs %}

{% aside type="caution" title="Target defaults" %}
This recipe assumes every target with the same name uses the same executor. If you have targets with the same name using different executors and you're providing target defaults for executor options, don't place the executor options under a default target using the target name as the key. Instead, separate target default configurations can be added using the executors as the keys, each with their specific configuration.
{% /aside %}

## Ramifications

This change adds 33 lines of code to `nx.json` and removes 84 lines of code from the `project.json` files. That's a net reduction of 51 lines of code. And you'll get more benefits from this strategy the more projects you have in your repo.

Reducing lines of code is nice, but just like using the DRY principle in code, there are other benefits:

- You can easily change the default settings for the whole repository in one location.
- When looking at a single project, it is clear how it differs from the defaults.

{% aside type="caution" title="Don't Over Do It" %}
You need to be careful to only put configuration settings in the `targetDefaults` that are actually defaults for the whole repository. If you have to make exceptions for most of the projects in your repository, then that setting probably should not be a default.
{% /aside %}

---
<!-- source: https://nx.dev/docs/guides/tasks--caching/root-level-scripts.md -->
## Run Root-Level NPM Scripts with Nx

{% youtube
src="https://www.youtube.com/embed/PRURABLaS8s"
title="Run root-level NPM scripts with Nx"
/%}

There are often tasks in a codebase that apply to the whole codebase rather than a single project. Nx can run npm scripts directly from the root `package.json`.

Let's say your root `package.json` looks like this:

```json
// package.json
{
  "name": "myorg",
  "scripts": {
    "docs": "node ./generateDocsSite.js"
  }
}
```

We want to be able to run the `docs` script using Nx to get caching and other benefits.

## Setup

To make Nx aware of the root `package.json` scripts, add an `"nx": {}` property to the root `package.json`

```json
// package.json
{
  "name": "myorg",
  "nx": {},
  "scripts": {
    "docs": "node ./generateDocsSite.js"
  }
}
```

## Running a root-level target

Once Nx is aware of your root-level scripts, you can run them the same way you would run any other target. Just use the name of your root `package.json` as the project name, or you can omit the project name and Nx will use the project in the current working directory as the default.

For our example, you would run:

```text {% title="nx docs" frame="terminal" %}
> nx run myorg:docs

yarn run v1.22.19
$ node ./generateDocsSite.js
Documentation site generated in /docs

————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

NX   Successfully ran target docs for project myorg (5s)
```

## Configuring a root-level target

You can also configure the `inputs` and `outputs` or task pipelines for root-level targets the same way you would for any other target.

Our fully configured example would look like this:

```jsonc
// package.json
{
  "name": "myorg",
  "nx": {
    // Nx can't infer the project dependency from the docs script,
    // so we manually create a dependency on the store app
    "implicitDependencies": ["store"],
    "targets": {
      "docs": {
        // generates docs from source code of all dependencies
        "inputs": ["^production"],
        // the docs site is created under /docs
        "outputs": ["{workspaceRoot}/docs"],
      },
    },
  },
  "scripts": {
    "docs": "node ./generateDocsSite.js",
  },
}
```

To cache the `docs` target, you can set `cache: true` on the `docs` target shown in the `package.json` above. Your output would then look as follows:

```text {% title="nx docs" frame="terminal" %}
> nx run myorg:docs  [existing outputs match the cache, left as is]

yarn run v1.22.19
$ node ./generateDocsSite.js
Documentation site generated in /docs

————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

NX   Successfully ran target docs for project myorg (31ms)

Nx read the output from the cache instead of running the command for 1 out of 1 tasks.
```

Read more about [caching task results](/docs/features/cache-task-results) and fine-tuning caching with [task inputs](/docs/guides/tasks--caching/configure-inputs).

## Keep using NPM to run scripts rather than Nx

You can keep using `npm run docs` instead of the new `npx nx docs` version and still leverage the caching. To achieve this you need to wrap your command with `nx exec` s.t. it can be piped through Nx.

```json
// package.json
{
  "name": "myorg",
  "nx": {},
  "scripts": {
    "docs": "nx exec -- node ./generateDocsSite.js"
  }
}
```

Read more in the [Nx exec docs](/docs/reference/nx-commands#nx-exec).

---
<!-- source: https://nx.dev/docs/guides/tasks--caching/run-commands-executor.md -->
## Running Custom Commands

You can easily run any command with the Nx toolchain. The main benefit is to make the [operation cacheable](/docs/concepts/how-caching-works), [distributable](/docs/features/ci-features/distribute-task-execution) as well as being able to use it [with Nx affected commands](/docs/features/ci-features/affected).

## 1. Define the terminal command to be run

The command we want to run for each project is:

```shell
make hello
```

With this `Makefile` in the root of the project:

```make
hello:
  echo "Hello, world!"
```

## 2. Update `project.json`

For each project for which you want to enable `make`, add a target in its `project.json`:

```jsonc
// project.json
// ...
"targets": {
    "make": {
        "command": "make hello"
    }
    // ...
}
```

For more information (e.g. how to forward arguments), see the [run-commands api doc](/docs/reference/nx/executors#run-commands).

## 3. Run the command

To run the command, use the usual Nx syntax:

```shell
nx run my-app:make
```

or

```shell
nx make my-app
```

You can also run the `make` command for all projects it has been defined on:

```shell
nx run-many -t make
```

Or just on a subset of projects that are [affected by a given change](/docs/features/ci-features/affected):

```shell
nx affected -t make
```

---
<!-- source: https://nx.dev/docs/guides/tasks--caching/run-tasks-in-parallel.md -->
## Run Tasks in Parallel

If you want to increase the number of processes running tasks to, say, 5 (by default, it is 3), pass the following:

```shell
npx nx build myapp --parallel=5
```

You can also set parallel based on the percentage of the number of logical CPUs.

```shell
npx nx build myapp --parallel=50%
```

Note, you can also change the default in `nx.json`, like this:

{% tabs %}
{% tabitem label="Nx >= 17" %}

```json
// nx.json
{
  "parallel": 5
}
```

{% /tabitem %}
{% tabitem label="Nx < 17" %}

```json
// nx.json
{
  "tasksRunnerOptions": {
    "default": {
      "runner": "nx/tasks-runners/default",
      "options": {
        "parallel": 5
      }
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

---
<!-- source: https://nx.dev/docs/guides/tasks--caching/self-hosted-caching.md -->
## Remote Cache

Remote caching shares build results across your team and CI so you don't repeat work.
You can use Nx Cloud for a fully managed solution or self-host with one of the available plugins.

{% aside type="note" title="Nx Cloud: Managed Remote Cache" %}

Recommended for everyone.

- [Fully managed multi-tier remote caching with Nx Replay](/docs/features/ci-features/remote-cache)
- [Both secure and fast](https://nx.dev/enterprise/security)
- Generous free plan

You'll also get access to advanced CI features:

- [Automated distribution of tasks across machines with Nx Agents](/docs/features/ci-features/distribute-task-execution)
- [Automated splitting of tasks (including e2e tests) with Nx Atomizer](/docs/features/ci-features/split-e2e-tasks)
- [Detection and re-running of flaky tasks](/docs/features/ci-features/flaky-tasks)
- [Self-healing CI and other AI features](https://nx.dev/ai)

[Get Started](https://cloud.nx.app)
{% /aside %}

{% aside type="note" title="Nx Enterprise" %}

Recommended for large organizations.

Includes everything from Nx Cloud, plus:

- Work hand-in-hand with the Nx team for continual improvement
- Run on the Nx Cloud servers in any region or run fully self-contained, on-prem
- SOC 2 type 1 and 2 compliant and comes with single-tenant, dedicated EU region hosting as well as on-premise

[Reach out for an Enterprise trial](https://nx.dev/enterprise/trial)

{% /aside %}

## Self-hosted cache

Great for proof of concepts and small teams.

{% aside type="caution" title="Bucket-based caches are vulnerable to poisoning and often prohibited in organizations" %}

CREEP (CVE-2025-36852) is a critical vulnerability in bucket-based self-hosted remote caches that allows anyone with PR access to poison production builds. Many organizations are unaware of this security risk. [Learn more](https://nx.dev/blog/creep-vulnerability-build-cache-security)

All packages below (along with other bucket-based remote cache implementations) are listed in the CVE and are not allowed in many organizations.

{% /aside %}

All packages are free but require an activation key. Getting a key is a fully automated, self-service process that happens during package installation. Install any of the following with `nx add`:

| Package                                                                                | Storage                      | Install command              |
| -------------------------------------------------------------------------------------- | ---------------------------- | ---------------------------- |
| [`@nx/s3-cache`](/docs/reference/remote-cache-plugins/s3-cache/overview)               | Amazon S3 bucket             | `nx add @nx/s3-cache`        |
| [`@nx/gcs-cache`](/docs/reference/remote-cache-plugins/gcs-cache/overview)             | Google Cloud Storage         | `nx add @nx/gcs-cache`       |
| [`@nx/azure-cache`](/docs/reference/remote-cache-plugins/azure-cache/overview)         | Azure Blob Storage           | `nx add @nx/azure-cache`     |
| [`@nx/shared-fs-cache`](/docs/reference/remote-cache-plugins/shared-fs-cache/overview) | Shared file system directory | `nx add @nx/shared-fs-cache` |

The `nx add` command installs the package, configures your workspace, and walks you through generating an activation key.
The key is saved to `.nx/key/key.ini` and should be committed to your repository.
In CI or public repositories, set the `NX_KEY` environment variable instead.

If you don't have a key yet, run `nx register` to generate one.
If your existing key is expired or invalid, delete `.nx/key/key.ini` and run `nx register` again.
In CI, verify that the `NX_KEY` environment variable is set and matches the key in `.nx/key/key.ini`.

> Why require an activation key? It simply helps us know and support our users. If you prefer not to provide this information, you can also [build your own cache server](#build-your-own-caching-server).

## Build your own caching server

Starting in Nx version 20.8, you can build your own caching server using the OpenAPI specification below. This allows you to create a custom remote cache server tailored to your specific needs. The server manages all aspects of the remote cache, including storage, retrieval, and authentication.

Implementation is up to you, but the server must adhere to the OpenAPI specification below to ensure compatibility with Nx caching mechanism. The endpoints transfer tar archives as binary data. Note that while the underlying data format may change in future Nx versions, the OpenAPI specification should remain stable.

You can implement your server in any programming language or framework, as long as it adheres to the OpenAPI spec.

### Open API specification

```json
// Nx 20.8+
{
  "openapi": "3.0.0",
  "info": {
    "title": "Nx custom remote cache specification.",
    "description": "Nx is an AI-first monorepo platform that connects everything from your editor to CI. Helping you deliver fast, without breaking things.",
    "version": "1.0.0"
  },
  "paths": {
    "/v1/cache/{hash}": {
      "put": {
        "description": "Upload a task output",
        "operationId": "put",
        "security": [
          {
            "bearerToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully uploaded the output"
          },
          "401": {
            "description": "Missing or invalid authentication token.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "description": "Error message provided to the Nx CLI user"
                }
              }
            }
          },
          "403": {
            "description": "Access forbidden. (e.g. read-only token used to write)",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "description": "Error message provided to the Nx CLI user"
                }
              }
            }
          },
          "409": {
            "description": "Cannot override an existing record"
          }
        },
        "parameters": [
          {
            "in": "header",
            "description": "The file size in bytes",
            "required": true,
            "schema": {
              "type": "number"
            },
            "name": "Content-Length"
          },
          {
            "name": "hash",
            "description": "The task hash corresponding to the uploaded task output",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        }
      },
      "get": {
        "description": "Download a task output",
        "operationId": "get",
        "security": [
          {
            "bearerToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved cache artifact",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary",
                  "description": "An octet stream with the content."
                }
              }
            }
          },
          "403": {
            "description": "Access forbidden",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "description": "Error message provided to the Nx CLI user"
                }
              }
            }
          },
          "404": {
            "description": "The record was not found"
          }
        },
        "parameters": [
          {
            "name": "hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerToken": {
        "type": "http",
        "description": "Auth mechanism",
        "scheme": "bearer"
      }
    }
  }
}
```

### Usage notes

To use your custom caching server, set the `NX_SELF_HOSTED_REMOTE_CACHE_SERVER` environment variable. The following environment variables also affect behavior:

- `NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN`: The authentication token to access the cache server.
- `NODE_TLS_REJECT_UNAUTHORIZED`: Set to `0` to disable TLS certificate validation.

### Migrating from custom tasks runners

You might have used Nx now-deprecated custom task runners API in these scenarios:

- To implement custom self-hosted caching: use one of the implementations listed above
- To inject custom behavior before and after running tasks: use our new API with dedicated pre and post hooks

To learn more about migrating from custom task runners, [please refer to this detailed guide](/docs/reference/deprecated/custom-tasks-runner).

## Looking for conformance or code owners?

If you previously used Nx Powerpack for conformance rules or code ownership, those features are now part of [Nx Enterprise](/docs/enterprise). See:

- [Conformance](/docs/enterprise/conformance) — write and enforce language-agnostic rules across your workspace
- [Owners](/docs/enterprise/owners) — define code ownership at the project level and auto-generate CODEOWNERS files

---
<!-- source: https://nx.dev/docs/guides/tasks--caching/skipping-cache.md -->
## Skip Task Caching

There are times when you might want to bypass the [caching mechanism](/docs/features/cache-task-results), either locally or remotely.

## Skip caching

To skip caching for a specific task, use the `--skip-nx-cache` flag. This can be useful when you want to ensure that a task runs fresh, without using cached results.

```shell
npx nx build --skip-nx-cache
```

This will avoid using any local or remote cache. If using Nx Cloud, the run will not be recorded either.

## Skip remote caching from Nx Cloud

To skip remote caching provided by Nx Cloud, use the `--no-cloud` flag. This ensures that the task does not use cached results from Nx Cloud.

```shell
npx nx build --no-cloud
```

It will **still use the local cache if available**. If using Nx Cloud the run will not be recorded either.

## Reset

To clear the cache and metadata about the workspace and shuts down the Nx Daemon you can use the [reset](/docs/reference/nx-commands#nx-reset) command:

```shell
npx nx reset
```

---
<!-- source: https://nx.dev/docs/guides/tasks--caching/terminal-ui.md -->
## Terminal UI

In version 21, Nx provides an interactive UI in the terminal to help you view the results of multiple tasks that are running in parallel.

{% youtube
src="https://youtu.be/ykaMAh83fPM"
title="New Terminal UI for Nx" /%}

{% aside type="note" title="Windows Compatibility" %}
The initial Nx 21 release disables the Terminal UI on Windows. We are currently working on Windows support, so stay tuned.
{% /aside %}

## Enable/disable the terminal UI

If your terminal and environment are supported then the Terminal UI will be enabled by default when you run any tasks with `nx run`/`nx run-many`/`nx affected` in Nx v21 and later. The Terminal UI will not be used in CI environments.

To manually control the Terminal UI, you can:

- Use the `--no-tui` flag when running commands: `nx run-many -t build --no-tui`
- Use the `--tui` flag to explicitly enable it: `nx run-many -t build --tui`
- Set `NX_TUI=false` in your environment variables
- Set `tui.enabled` to `false` in your `nx.json` configuration file

```json
// nx.json
{
  "tui": {
    "enabled": false
  }
}
```

## Configure the terminal UI

There are also some configuration options that control the way the terminal UI behaves.

### Auto-exit

By default, the Terminal UI will automatically exit 3 seconds after all relevant tasks have finished running. You can adjust this behavior in the following ways:

- Set `"tui.autoExit"` to a number to change the number of seconds to wait before auto-exiting.
- Set `"tui.autoExit"` to `false` to disable auto-exiting and keep the Terminal UI open until you manually exit it with `<ctrl>+c`.
- Set `"tui.autoExit"` to `true` to exit automatically immediately after all tasks have finished running.

```json
// nx.json
{
  "tui": {
    "autoExit": 3 // Equivalent of the default behavior: auto-exit after 3 seconds
  }
}
```

## Use the terminal UI

The terminal UI is entirely controlled through keyboard shortcuts. You can view a list of the available shortcuts by typing `?`:

![Terminal UI Help](../../../../assets/guides/running-tasks/tui-help.png)

You can use these commands to hide and show up to 2 tasks at a time, filter the listed tasks and interact with tasks that are prompting for user input.

---
<!-- source: https://nx.dev/docs/guides/tasks--caching/workspace-watching.md -->
## Workspace Watching

{% youtube src="https://youtu.be/0eVplUl1zBE?si=KtmiyRm1AcYc01td" title="Workspace watching" /%}

Nx can watch your workspace and execute commands based on project or files changes.

Imagine the following project graph with these projects:

{% graph height="450px" %}

```json
{
  "projects": [
    {
      "type": "lib",
      "name": "main-lib",
      "data": {
        "tags": []
      }
    },
    {
      "type": "lib",
      "name": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "type": "lib",
      "name": "lib2",
      "data": {
        "tags": []
      }
    },
    {
      "type": "lib",
      "name": "lib3",
      "data": {
        "tags": []
      }
    }
  ],
  "groupByFolder": false,
  "dependencies": {
    "main-lib": [
      {
        "target": "lib",
        "source": "main-lib",
        "type": "direct"
      },
      {
        "target": "lib2",
        "source": "main-lib",
        "type": "direct"
      },
      {
        "target": "lib3",
        "source": "main-lib",
        "type": "direct"
      }
    ],
    "lib": [],
    "lib2": [],
    "lib3": []
  },
  "workspaceLayout": {
    "appsDir": "apps",
    "libsDir": "libs"
  },
  "affectedProjectIds": [],
  "focus": null,
  "groupByFolder": false,
  "exclude": []
}
```

{% /graph %}

Traditionally, if you want to rebuild your projects whenever they change, you would have to set up an ad-hoc watching system to watch each project. Rather than setting up a watch manually, Nx can be used to watch projects and execute a command whenever they change.

With the following command, Nx is told to watch all projects, and execute `nx run $NX_PROJECT_NAME:build` for each change.

```shell
nx watch --all -- nx run \$NX_PROJECT_NAME:build
```

{% aside type="note" title="Escaping" %}

Note the backslash (`\`) before the `$`. This is needed so that your shell doesn't automatically interpolate the variables.

There are also some quirks if this command is ran with a package manager. [Find out how to run this command with those managers here.](#running-nx-watch-with-package-managers)

{% /aside %}

{% aside type="note" title="Windows" %}

If you're running this command on Windows Powershell (not WSL), the environment variables need to be wrapped in `%`.

For example:

```shell
nx watch --all -- nx run %NX_PROJECT_NAME%:build
```

{% /aside %}

Now every time a package changes, Nx will run the build.

If multiple packages change at the same time, Nx will run the callback for each changed project. Then if additional changes happen while a command is in progress, Nx will batch those changes, and execute them once the current command completes.

## Watch environment variables

Nx will run the watch callback command with the `NX_PROJECT_NAME` and `NX_FILE_CHANGES` environment variables set.

- `NX_PROJECT_NAME` will be the name of the project.
- `NX_FILE_CHANGES` will be a list of files that changed formatted in stdin (ie, if `file1.txt`, and `file2.txt` change, `NX_FILE_CHANGES` will be `file1.txt file2.txt`. This allows you to pass the list of files to other commands that accept this format.)

### Running Nx watch with package managers

In the examples above, the `nx watch` command was run directly in the terminal. Usually environments aren't set up to include node_module bins automatically in the shell path, so using the package manager's run/exec command is used. For example, `npx`, `yarn`, `pnpm run`.

When running `npx nx watch --all -- echo \$NX_PROJECT_NAME`, (or equivalent), the watch command may not execute as expected. For example, the environment variables seem to be blank.

Below are the ways to run the watch with each package manager.

#### pnpm

```shell
pnpm nx watch --all -- echo \$NX_PROJECT_NAME
```

#### yarn

```shell
yarn nx -- watch --all -- echo \$NX_PROJECT_NAME
```

#### npx

```shell
npx -c 'nx watch --all -- echo \$NX_PROJECT_NAME'
```

## Additional use cases

### Watching for specific projects

To watch for specific projects and echo the changed files, run this command:

```shell
nx watch --projects=app1,app2 -- echo \$NX_FILE_CHANGES
```

### Watching for dependent projects

To watch for a project and it's dependencies, run this command:

```shell
nx watch --projects=app1 --includeDependentProjects -- echo \$NX_PROJECT_NAME
```

### Rebuilding dependent projects while developing an application

In a monorepo setup, your application might rely on several libraries that need to be built before they can be used in the application. While the [task pipeline](/docs/guides/tasks--caching/defining-task-pipeline) automatically handles this during builds, you'd want the same behavior during development when serving your application with a dev server.

To watch and rebuild the dependent libraries of an application, use the following command:

```shell
nx watch --projects=my-app --includeDependentProjects -- nx run-many -t build -p \$NX_PROJECT_NAME --exclude=my-app
```

`--includeDependentProjects` ensures that any changes to projects your application depends on trigger a rebuild, while `--exclude=my-app` skips rebuilding the app itself since it's already being served by the development server.

---
<!-- source: https://nx.dev/docs/guides/tips-n-tricks.md -->
## Tips and Tricks

{% index_page_cards path="guides/tips-n-tricks" /%}

---
<!-- source: https://nx.dev/docs/guides/tips-n-tricks/advanced-update.md -->
## Advanced Update Process

This guide describes advanced scenarios when it comes to updating Nx and the workspaces dependencies. It starts with a summary of the [standard update process](/docs/features/automate-updating-dependencies) and continues with those advanced use cases.

## Updating to the latest Nx version

The following steps are a summary of the [standard update process](/docs/features/automate-updating-dependencies). For more information on each step, please visit that page.

### Step 1: Updating dependencies and generating migrations

First, run the `migrate` command:

```shell
nx migrate latest # same as nx migrate nx@latest
```

This performs the following changes:

- Updates the versions of the relevant packages in the `package.json` file.
- Generates a `migrations.json` if there are pending migrations.

### Step 2: Running migrations

The next step in the process involves using the `migrate` command to apply the migrations that were generated in the `migrations.json` file in the previous step. You can do so by running:

```shell
nx migrate --run-migrations
```

All changes to your source code will be unstaged and ready for you to review and commit yourself.

### Step 3: Cleaning up

After you run all the migrations, you can remove `migrations.json` and commit any outstanding changes.

## Recommendations

### One major version at a time, small steps

Migrating Jest, Cypress, ESLint, React, Angular, Next, and more is a difficult task. All the tools change at different rates, and they can conflict with each other. In addition, every workspace is different. Even though our goal is for you to update any version of Nx to a newer version of Nx in a single go, sometimes it doesn't work. The recommended process is to update, at most, one major version at a time.

Say you want to migrate from Nx 17.1.0 to Nx 18.2.4. The following steps are more likely to work comparing to `nx migrate 18.2.4`.

- Run `nx migrate 17.3.2` to update the latest version in the 17.x branch.
- Run `nx migrate --run-migrations`.
- Next, run `nx migrate 18.2.4`.
- Run `nx migrate --run-migrations`.

{% aside type="caution" title="Angular updates" %}
If your workspace uses Angular, this becomes a requirement rather than a recommendation. The Angular packages maintain migrations for a single major version at a time. If you try to update over multiple major versions, only the migrations for the latest major version will be applied. This can lead to issues in your workspace.
{% /aside %}

## Managing migration steps

When you run into problems running the `nx migrate --run-migrations` command, here are some solutions to break the process down into manageable steps.

### Make changes easier to review by committing after each migration runs

Depending on the size of the update (e.g. migrating between major versions is likely to require more significant changes than migrating between feature releases), and the size of the workspace, the overall `nx migrate` process may generate a lot of changes which then need to be reviewed. Particularly if there are then manual changes which need to be made in addition to those made by `nx migrate`, it can make the associated PR harder to review because of not being able to distinguish between what was changed automatically and what was changed manually.

If you pass `--create-commits` to the `--run-migrations` command, Nx will automatically create a dedicated commit for each successfully completed migration, for example:

```shell
nx migrate --run-migrations --create-commits
```

Your git history will then look something like the following:

```text {% title="nx migrate --run-migrations --create-commits" frame="terminal" %}
git log

commit 8c862c780106ab8736985c01de1477309a403548
Author: YOUR_GIT_USERNAME <your_git_email@example.com>
Date:   Thu Apr 14 18:35:44 2022 +0400

    chore: [nx migration] name-of-the-second-migration-which-ran

commit eb83bca97927af26aae731a2cf51ad62cc75efa3
Author: YOUR_GIT_USERNAME <your_git_email@example.com>
Date:   Thu Apr 14 18:35:44 2022 +0400

    chore: [nx migration] name-of-the-first-migration-which-ran

etc
```

By default, nx will apply the prefix of `chore: [nx migration] ` to each commit in order to clearly identify it, but you can also customize this prefix by passing `--commit-prefix` to the command:

```shell
nx migrate --run-migrations --create-commits --commit-prefix="chore(core): AUTOMATED - "
```

```text {% title="git log" frame="terminal" %}
commit 8c862c780106ab8736985c01de1477309a403548
Author: YOUR_GIT_USERNAME <your_git_email@example.com>
Date:   Thu Apr 14 18:35:44 2022 +0400

    chore(core): AUTOMATED - name-of-the-second-migration-which-ran

commit eb83bca97927af26aae731a2cf51ad62cc75efa3
Author: YOUR_GIT_USERNAME <your_git_email@example.com>
Date:   Thu Apr 14 18:35:44 2022 +0400

    chore(core): AUTOMATED - name-of-the-first-migration-which-ran

etc
```

### Customizing which migrations run by altering `migrations.json`

For small projects, running all the migrations at once often succeeds without any issues. For large projects, more flexibility is sometimes needed, and this is where having the separation between generating the migrations to be run, and actually running them, really shines.

All you need to do is amend the JSON file in whatever way makes sense based on your circumstances, for example:

- You may have to skip a migration.
- You may want to run one migration at a time to address minor issues.
- You may want to reorder migrations.
- You may want to run the same migration multiple time if the process takes a long time and you had to rebase.

Because you can run `nx migrate --run-migrations` as many times as you want, you can achieve all of that by commenting out and reordering items in `migrations.json`. The migration process can take a long time, depending on the number of migrations, so it is useful to commit the migrations file with the partially-updated repo alongside any changes which were created by previously completed migrations.

You can even provide a custom location for the migrations file if you wish, you simply pass it to the `--run-migrations` option:

```shell
nx migrate --run-migrations=migrations.json
```

## Choosing optional package updates to apply

While in most cases you want to be up to date with Nx and the dependencies it manages, sometimes you might need to stay on an older version of such a dependency. For example, you might want to update Nx to the latest version but keep Angular on **v15.x.x** and not update it to **v16.x.x**. For such scenarios, `nx migrate` allows you to choose what to update using the `--interactive` flag.

{% aside type="note" title="Optional package updates" %}
You can't choose to skip any arbitrary package update. To ensure that a plugin works well with older versions of a given package, the plugin must support it. Therefore, Nx plugin authors define what package updates are optional.
{% /aside %}

{% aside type="caution" title="Taking control of package updates" %}
While opting out of applying some package updates is supported by Nx, please keep in mind that you are effectively taking control of those package updates and opting out of Nx managing them. This means you'll need to keep up with the version requirements for those packages and those that depend on them. You'll also need to consider more things when updating them at some point [as explained later](#updating-dependencies-that-are-behind-the-versions-nx-manages).
{% /aside %}

### Interactively opting out of package updates

To opt out of package updates, you need to run the migration in interactive mode:

```shell
nx migrate latest --interactive
```

As the migration runs and collects the package updates, you'll be prompted to apply optional package updates, and you can choose what to do based on your needs. The `package.json` will be updated and the `migrations.json` will be generated considering your responses to those prompts.

### Updating dependencies that are behind the versions Nx manages

Once you have skipped some optional updates, there'll come a time when you'll want to update those packages. To do so, you'll need to generate the package updates and migrations from the Nx version that contained those skipped updates.

Say you skipped updating Angular to **v16.x.x**. That package update was meant to happen as part of the `@nx/angular@16.1.0` update, but you decided to skip it at the time. The recommended way to collect the migrations from such an older version is to run the following:

```shell
nx migrate latest --from=nx@16.0.0 --exclude-applied-migrations
```

A couple of things are happening there:

- The `--from=nx@16.0.0` flag tells the `migrate` command to use the version **16.0.0** as the installed version for the `nx` package and all the first-party Nx plugins. Note we use a version lower than the one where the update was meant to happen. This is to account for the fact that the update is normally targeted to a prerelease version for testing it before the final release.
- The `--exclude-applied-migrations` flag tells the `migrate` command not to collect migrations that should have been applied on previous updates.

So, the above command will effectively collect any package update and migration meant to run if your workspace had `nx@16.0.0` installed while excluding those that should have been applied before. You can provide a different older version to collect migrations from.

{% aside type="caution" title="Automatically excluding previously applied migrations" %}
Automatically excluding previously applied migrations doesn't consider migrations manually removed from the `migrations.json` in previous updates. If you've manually removed migrations in the past and want to run them, don't pass the `--exclude-applied-migrations` and collect all previous migrations.
{% /aside %}

### Identifying the Nx version to migrate from to collect previously skipped updates

After running the migrations in interactive mode and opting-out of some package updates, a message is printed to the terminal with the command to run later to collect and apply those skipped updates. For example, if you skipped updating Angular to **v16.0.0**, this is the output you'll see (simplified for brevity):

```shell
nx migrate latest --interactive
Fetching meta data about packages.
It may take a few minutes.
...
✔ Do you want to update to TypeScript v5.0? (Y/n) · false
✔ Do you want to update the Angular version to v16? (Y/n) · false

NX   The migrate command has run successfully.

- package.json has been updated.
- migrations.json has been generated.

NX   Next steps:

- Make sure package.json changes make sense and then run 'pnpm install --no-frozen-lockfile',
- Run 'pnpm exec nx migrate --run-migrations'
- You opted out of some migrations for now. Write the following command down somewhere to apply these migrations later:
- nx migrate 16.5.3 --from nx@16.1.0-beta.0 --exclude-applied-migrations
- To learn more go to https://nx.dev/recipes/other/advanced-update
```

You can see in the "Next steps" section a suggested command to run to apply the skipped package updates. Make sure to store that information somewhere so you can later remember from which version you need to run the migration to apply the skipped package updates.

Please note the suggested command is only based on a particular run of the `nx migrate` command. If you've skipped package updates in previous runs, you'll need to use the oldest version you've stored that you haven't yet run the migration from.

If you don't have the command and need to find out from which version to run the migration, you can take a look at the `migrations.json` file of the relevant package. For example, if you skipped updating Angular to **v16.0.0**, you can take a look at the `migrations.json` file of the `@nx/angular` package and you'll find the following:

```jsonc
// node_modules/@nx/angular/migrations.json
{
  // ...
  "packageJsonUpdates": {
    // ...
    "16.1.0": {
      "version": "16.1.0-beta.1",
      "x-prompt": "Do you want to update the Angular version to v16?",
      "requires": {
        "@angular/core": ">=15.2.0 <16.0.0",
      },
      "packages": {
        "@angular/core": {
          "version": "~16.0.0",
          "alwaysAddToPackageJson": true,
        },
        // ...
      },
    },
    // ...
  },
}
```

You can see the `16.1.0-beta.1` version is the one that contains the update for `@angular/core` to **~16.0.0**. That's the version you need to run the migration from to apply the package update.

## Other advanced capabilities

### Overriding versions

Sometimes, you may want to use a different version of a package than what Nx recommends. To do that, specify the package and version:

```shell
nx migrate latest --to="jest@22.0.0,cypress@3.4.0"
```

By default, Nx uses currently installed packages to calculate what migrations need to run. To override them, override the version:

```shell
nx migrate latest --to="@nx/jest@12.0.0"
```

{% aside type="caution" title="Overriding versions" %}
By choosing a version different of what Nx recommend you might use a package version that might have not been tested for a given Nx version. This might lead to unexpected issues.
{% /aside %}

### Reverting a failed update

Updates are best done on a clean git history so that it can be easily reversed if something fails. We try our best to make sure migrations do not fail but if one does, **please report it** on [GitHub](https://www.github.com/nrwl/nx/issues/new/).

If an update fails for any reason, you can revert it as you do any other set of changes:

```shell
git reset --hard # Reset any changes
git clean -fd # Delete newly added files and directories
```

{% aside type="caution" title="--create-commits" %}
If using `--create-commits`, you will need to first retrieve the SHA of the commit before your first automated migration commit in order to jump back to the point before the migrations ran, e.g. `git reset --hard YOUR_APPROPRIATE_SHA_HERE`)
{% /aside %}

---
<!-- source: https://nx.dev/docs/guides/tips-n-tricks/analyze-source-files.md -->
## Disable Graph Links Created from Analyzing Source Files

If you want to disable detecting dependencies from source code and want to only use the dependencies as defined in `package.json` (the same way yarn does), you can add the following configuration to your `nx.json` file:

```json
// nx.json
{
  "pluginsConfig": {
    "@nx/js": {
      "analyzeSourceFiles": false
    }
  }
}
```

## Default

The default setting for Nx repos is `"analyzeSourceFiles": true`. The assumption is that if there is a real link in the code between projects, you want to know about it. For Lerna repos, the default value is `false` in order to maintain backward compatibility with the way Lerna has always calculated dependencies.

---
<!-- source: https://nx.dev/docs/guides/tips-n-tricks/browser-support.md -->
## Configuring Browser Support

The official Nx plugins rely on [browserslist](https://github.com/browserslist/browserslist) for configuring application browser support. This affects builds, both production and development, and will decide on which transformations will be run on the code when built.

In general, the more modern your applications browser support is, the smaller the filesize as the code can rely on modern API's being present and not have to ship polyfills or shimmed code.

By default, applications generated from official Nx generators ship an aggressively modern browser support config, in the form of a `.browserslistrc` file in the root of the application with the following contents.

```text
last 1 Chrome version
last 1 Firefox version
last 2 Edge major versions
last 2 Safari major version
last 2 iOS major versions
Firefox ESR
not IE 9-11
```

This configuration is used for many tools including babel, autoprefixer, postcss, and more to decide which transforms are necessary on the source code when producing built code to run in the browser.

For additional information regarding the format and rule options, please see: https://github.com/browserslist/browserslist#queries

## Debugging browser support

Sometimes broad configurations like `> 0.5%, not IE 11` can lead to surprising results, due to supporting browsers like Opera Mini or Android UC browser.

To see what browsers your configuration is supporting, run `npx browserslist` in the application's directory to get an output of browsers and versions to support.

```text {% title="npx browserslist" frame="terminal" %}
and_chr 61
chrome 83
edge 83
edge 81
firefox 78
firefox 68
ie 11
ios_saf 13.4-13.5
ios_saf 13.3
ios_saf 13.2
ios_saf 13.0-13.1
ios_saf 12.2-12.4
ios_saf 12.0-12.1
safari 13.1
safari 13
safari 12.1
safari 12
```

Alternatively, if your support config is short you can just add it as a string param on the CLI:

```shell
npx browserslist '> 0.5%, not IE 11'
```

---
<!-- source: https://nx.dev/docs/guides/tips-n-tricks/define-environment-variables.md -->
## Define Environment Variables

Environment variables are global system variables accessible by all the processes running under the Operating System (OS).
Environment variables are useful to store system-wide values such as the directories to search for executable programs
(PATH), OS version, Network Information, and custom variables. These env variables are passed at build time and used at
the runtime of an app.

## Set environment variables

By default, Nx will load any environment variables you place in the following files:

1. `[project-root]/.env.[target-name].[target-configuration-name].local`
2. `[project-root]/.env.[target-name].[target-configuration-name]`
3. `[project-root]/.[target-name].[target-configuration-name].local.env`
4. `[project-root]/.[target-name].[target-configuration-name].env`
5. `[project-root]/.env.[target-configuration-name].local`
6. `[project-root]/.env.[target-configuration-name]`
7. `[project-root]/.[target-configuration-name.local.env`
8. `[project-root]/.[target-configuration-name].env`
9. `[project-root]/.env.[target-name].local`
10. `[project-root]/.env.[target-name]`
11. `[project-root]/.[target-name].local.env`
12. `[project-root]/.[target-name].env`
13. `[project-root]/.env.local`
14. `[project-root]/.local.env`
15. `[project-root]/.env`
16. `.env.[target-name].[target-configuration-name].local`
17. `.env.[target-name].[target-configuration-name]`
18. `.[target-name].[target-configuration-name].local.env`
19. `.[target-name].[target-configuration-name].env`
20. `.env.[target-configuration-name].local`
21. `.env.[target-configuration-name]`
22. `.[target-configuration-name].local.env`
23. `.[target-configuration-name].env`
24. `.env.[target-name].local`
25. `.env.[target-name]`
26. `.[target-name].local.env`
27. `.[target-name].env`
28. `.env.local`
29. `.local.env`
30. `.env`

Or shorter we will use the following order:

- [project-root]/[target-name].[target-configuration-name]
- [project-root]/[target-configuration-name]
- [project-root]/[target-name]
- [project-root]/{general environment variables}
- [target-name].[target-configuration-name]
- [target-configuration-name]
- [target-name]
- {general environment variables}

{% aside type="caution" title="Order is important" %}
Nx will move through the above list, ignoring files it can't find, and loading environment variables
into the current process for the ones it can find. If it finds a variable that has already been loaded into the process,
it will ignore it. It does this for two reasons:

1. Developers can't accidentally overwrite important system level variables (like `NODE_ENV`)
2. Allows developers to create `.env.local` or `.local.env` files for their local environment and override any project
   defaults set in `.env`
3. Allows developers to create target specific `.env.[target-name]` or `.[target-name].env` to overwrite environment variables for specific targets. For instance, you could increase the memory use for node processes only for build targets by setting `NODE_OPTIONS=--max-old-space-size=4096` in `.build.env`

For example:

1. `apps/my-app/.env.local` contains `NX_PUBLIC_API_URL=http://localhost:3333`
2. `apps/my-app/.env` contains `NX_PUBLIC_API_URL=https://api.example.com`
3. Nx will first load the variables from `apps/my-app/.env.local` into the process. When it tries to load the variables
   from `apps/my-app/.env`, it will notice that `NX_PUBLIC_API_URL` already exists, so it will ignore it.

We recommend nesting your **app** specific `env` files in `apps/your-app`, and creating workspace/root level `env` files
for workspace-specific settings (like the [Nx Cloud token](/docs/guides/nx-cloud/access-tokens)).
{% /aside %}

### Environment variables for atomized targets

Atomized targets have their names created dynamically, typically using the file names as a suffix. This makes it difficult to define environment variable files for them.
For atomized targets, Nx will instead search for atomized target's parent and non-atomized target.

Instead of looking for a file named e.g. `.env.e2e-ci--path/to/atomized/file`, Nx will instead look for:

- `.env.e2e-ci` and
- `.env.e2e`

The above order with combinations of targets, configurations and path priority remainst the same:

- [project-root]/[parent-target-name].[target-configuration-name]
- [project-root]/[non-atomized-target-name].[target-configuration-name]
- [project-root]/[target-configuration-name]
- [project-root]/[parent-target-name]
- [project-root]/[non-atomized-target-name]
- [project-root]/{general environment variables}
- [target-name].[target-configuration-name]
- [target-configuration-name]
- [parent-target-name]
- [non-atomized-target-name]
- {general environment variables}

### Environment variables for configurations

Nx will only load environment variable files for a particular configuration if that configuration is defined for a task, even if you specify that configuration name from the command line. So if there is no `development` configuration defined for the `app`'s `build` task, the following command will use `.env.build` instead of `.env.build.development`:

```shell
nx build app --configuration development
```

In order to have Nx actually use the `.env.build.development` environment variables, the `development` configuration needs to be set for the task (even if it is empty).

```jsonc {% meta="{5-7}" %}
// apps/app/project.json
{
  "targets": {
    "build": {
      // ...
      "configurations": {
        "development": {},
      },
    },
  },
}
```

### Point to custom env files

If you want to load variables from `env` files other than the ones listed above:

1. Use the [env-cmd](https://www.npmjs.com/package/env-cmd) package: `env-cmd -f .qa.env nx serve`
2. Use [dotenvx](https://github.com/dotenvx/dotenvx): `dotenvx run --env-file=.qa.env -- nx serve`
3. Use the `envFile` option of the [run-commands](/docs/guides/tasks--caching/run-commands-executor#envfile) builder and execute your command inside of the builder

### Ad-hoc variables

You can also define environment variables in an ad-hoc manner using support from your OS and shell.

**Unix systems**

In Unix systems, we need to set the environment variables before calling a command.

Let's say that we want to define an API URL for the application to use:

```shell
NX_PUBLIC_API_URL=http://localhost:3333 nx build myapp
```

**Windows (cmd.exe)**

```shell
set "NX_PUBLIC_API_URL=http://localhost:3333" && nx build myapp
```

**Windows (Powershell)**

```shell
($env:NX_PUBLIC_API_URL = "http://localhost:3333") -and (nx build myapp)
```

---
<!-- source: https://nx.dev/docs/guides/tips-n-tricks/feature-based-testing.md -->
## Optimize Testing with Feature-Based Testing

Feature-based testing is a strategy that co-locates tests with the features they verify. This approach helps you test only what's changed, reducing unnecessary test execution and improving feedback loops.

## The problem: monolithic test projects

Many projects have a single, large test project that depends on the entire application, such as e2e projects. While this setup ensures tests run when any dependency changes, it also means **all tests run even when only one subset of the app changes**.

{% aside type="tip" title="Beyond E2E Tests" %}
While this guide uses end-to-end (e2e) tests as examples, the same strategy applies to any type of testing—integration tests, component tests, or even large unit test suites.
The principles of feature-based testing work wherever you have monolithic test projects that could benefit from being split by feature.
{% /aside %}

Consider a typical setup where all e2e tests live in a single project at the top of the graph:
{% graph height="400px" %}

```json
{
  "projects": [
    {
      "name": "fancy-app-e2e",
      "type": "app",
      "data": {
        "tags": []
      }
    },
    {
      "name": "fancy-app",
      "type": "app",
      "data": {
        "tags": []
      }
    },
    {
      "name": "shared-ui",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "feat-cart",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "feat-products",
      "type": "lib",
      "data": {
        "tags": []
      }
    }
  ],
  "dependencies": {
    "fancy-app-e2e": [
      { "source": "fancy-app-e2e", "target": "fancy-app", "type": "implicit" }
    ],
    "fancy-app": [
      { "source": "fancy-app", "target": "feat-products", "type": "static" },
      { "source": "fancy-app", "target": "feat-cart", "type": "static" }
    ],
    "shared-ui": [],
    "feat-cart": [
      {
        "source": "feat-cart",
        "target": "shared-ui",
        "type": "static"
      }
    ],
    "feat-products": [
      {
        "source": "feat-products",
        "target": "shared-ui",
        "type": "static"
      }
    ]
  },
  "workspaceLayout": { "appsDir": "", "libsDir": "" },
  "affectedProjectIds": ["feat-cart", "fancy-app-e2e", "fancy-app"],
  "groupByFolder": false,
  "showAffectedWithNodes": true
}
```

{% /graph %}

In this example, when `feat-cart` changes, **all tests in `fancy-app-e2e` run**, which includes tests for `feat-products` along with other unrelated features. This happens because `fancy-app-e2e` depends on the entire application.

Since these features have minimal overlap, you can optimize testing by splitting the monolithic test project into smaller, feature-scoped test projects.

## The solution: Feature-scoped testing

Instead of keeping all tests in one large project, break them down by feature and co-locate them with the feature libraries they test. This way, only the tests for changed features run.

### How to implement feature-Based testing

To set up feature-based testing, add test configurations directly to your feature projects.
Nx provides plugins to automate and speed up the test configuration for common testing tools.
Here are some guides for using each plugins generators:

- [Playwright](/docs/technologies/test-tools/playwright/introduction#add-playwright-e2e-to-an-existing-project)
- [Cypress](/docs/technologies/test-tools/cypress/introduction#configure-cypress-for-an-existing-project)
- [Vitest](/docs/technologies/build-tools/vite/generators#configuration)
- [Jest](/docs/technologies/test-tools/jest/introduction#add-jest-to-a-project)

If there isn't a generator for your testing tool of choice, you can manually set up the configuration on each feature project.
This includes adding relevant configuration files for the testing framework and adding the test target (e.g. `test`, `e2e`) to the project's `project.json` or `package.json`. Typically these can be copied and slightly modified from the existing top-level monolithic project that is being split apart.

With this setup, when you run `nx affected -t e2e`, only the tests for changed features will execute.
For example, when `feat-cart` changes, only `feat-cart:e2e` runs and `feat-products:e2e` does not run since it wasn't affected.

## Best practices

### Combining with automated task splitting (Atomizer)

Typically, teams enable [Atomizer, also known as task splitting](/docs/features/ci-features/split-e2e-tasks), for a quick win to improve CI times when using [Nx Agents](/docs/features/ci-features/distribute-task-execution).
Combining both strategies yields the best results.
Here's how they complement each other:

- **Feature-based testing** ensures only relevant feature tests run when code changes
- **Atomizer** splits each feature's test suite into individual file-level tasks that can be distributed across multiple CI agents.

For example, if `feat-cart` has 10 test files and `feat-products` has 15 test files, when you change the cart feature:

1. Feature-based testing runs only `feat-cart:e2e-ci` (skipping `feat-products:e2e-ci`)
2. Atomizer splits `feat-cart:e2e-ci` into 10 parallel tasks, one per test file
3. These tasks get distributed across your CI agents for faster execution

Learn more about [setting up Automated Task Splitting](/docs/features/ci-features/split-e2e-tasks).

### Keep the top-Level test project

Don't delete your top level test project, `fancy-app-e2e` in this example. Instead, repurpose it for:

- **Smoke tests**: Quick sanity checks that the app starts and critical paths work
- **Cross-feature integration tests**: Tests that verify multiple features work together
- **End-to-end user journeys**: Tests that span multiple features

This gives you a balanced testing strategy: focused feature tests that run frequently, plus comprehensive integration tests when needed.

### Running tests in parallel

When running tests from multiple features in parallel, be mindful of shared resources. Since all feature tests run against the same application instance, avoid conflicts by:

- **Using unique test data**: Don't rely on specific database records or application state
- **Managing ports**: Configure each test to use different ports, or let the test framework find free ports automatically
  - For Cypress, use the [`--port` flag](/docs/technologies/test-tools/cypress/executors) to specify or auto-detect ports
  - For Playwright, the `webServerAddress` can be dynamically assigned
- **Isolating state**: Use test-specific user accounts, temporary data, or cleanup between tests

### Running affected tests

With feature-based testing, you can leverage Nx affected commands to run only the tests that matter:

```shell
# Run all affected tests based on your changes
nx affected -t test

# Run affected e2e tests
nx affected -t e2e
```

This ensures you're only testing what changed, whether locally or in CI.

---
<!-- source: https://nx.dev/docs/guides/tips-n-tricks/identify-dependencies-between-folders.md -->
## Identify Dependencies Between Folders

As projects grow in size, you often need to split out a particular folder in that project into its own library. In order to do this properly, you need to:

1. Generate a new library to set up all the config files
2. Move the code from the existing folder into the new library
3. Clean up paths that were broken when you moved the code

If you're not sure which code you want to split into a new library, this can be a tedious process to repeat multiple times.

Here is a technique to use during the exploration phase to help identify which code makes sense to separate into its own library.

{% aside type="note" title="Requires Nx 15.3" %}

Nx 15.3 introduced nested projects, which are necessary for Nx to be aware of `project.json` files inside of an existing project.

{% /aside %}

## Set up

1. Identify the folders that might make sense to separate into their own library
2. In each folder, create a `project.json` file with the following contents:

```json
// project.json
{
  "name": "[name_of_the_folder]"
}
```

## Analysis

Now, run `nx graph` to view the dependencies between the folders. In the full web view (not in the graph below), you can click on the dependency lines to see which specific files are creating those dependencies.

Here is a graph that was created when doing this exercise on the [Angular Jump Start](https://github.com/DanWahlin/Angular-JumpStart) repo. To reproduce this graph yourself, download the repo, run `nx init` and then add `project.json` files to the folders under `/src/app`.

{% graph height="450px" %}

```json
{
  "hash": "9713539543f19c5299e56715e78c576a40b91056b9cbb4e42118780cfcd22b5e",
  "projects": [
    {
      "name": "customers",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "customer",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "orders",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "shared",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "about",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "login",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "core",
      "type": "lib",
      "data": {
        "tags": []
      }
    },
    {
      "name": "playground",
      "type": "app",
      "data": {
        "tags": []
      }
    },
    {
      "name": "angular-jumpstart",
      "type": "app",
      "data": {
        "tags": []
      }
    }
  ],
  "dependencies": {
    "customers": [
      { "source": "customers", "target": "shared", "type": "static" },
      { "source": "customers", "target": "core", "type": "static" }
    ],
    "customer": [
      { "source": "customer", "target": "shared", "type": "static" },
      { "source": "customer", "target": "core", "type": "static" }
    ],
    "orders": [
      { "source": "orders", "target": "core", "type": "static" },
      { "source": "orders", "target": "shared", "type": "static" }
    ],
    "shared": [],
    "about": [],
    "login": [
      { "source": "login", "target": "core", "type": "static" },
      { "source": "login", "target": "shared", "type": "static" }
    ],
    "core": [
      { "source": "core", "target": "shared", "type": "static" },
      { "source": "core", "target": "angular-jumpstart", "type": "static" }
    ],
    "playground": [
      {
        "source": "playground",
        "target": "angular-jumpstart",
        "type": "static"
      },
      { "source": "playground", "target": "core", "type": "static" },
      { "source": "playground", "target": "customer", "type": "static" },
      { "source": "playground", "target": "customers", "type": "static" },
      { "source": "playground", "target": "orders", "type": "static" },
      { "source": "playground", "target": "about", "type": "static" },
      { "source": "playground", "target": "login", "type": "static" },
      { "source": "playground", "target": "shared", "type": "static" }
    ],
    "angular-jumpstart": []
  },
  "workspaceLayout": { "appsDir": "projects", "libsDir": "projects" },
  "affectedProjectIds": [],
  "focus": null,
  "groupByFolder": false,
  "exclude": []
}
```

{% /graph %}

## Clean up

{% aside type="caution" title="DO NOT COMMIT" %}
Do not commit these empty `project.json` files. They remove files from the cache inputs of the parent project without creating new test or build targets in place to cover those files. So testing and building will not be triggered correctly when those files change.
{% /aside %}

1. Delete the empty `project.json` files.
2. Make new libraries for any folders that were marked to be extracted into new libraries.

---
<!-- source: https://nx.dev/docs/guides/tips-n-tricks/include-all-packagejson.md -->
## Include All package.json Files as Projects

As of Nx 15.0.11, we only include any `package.json` file that is referenced in the `workspaces` property of the root `package.json` file in the graph. (`lerna.json` for Lerna repos or `pnpm-workspaces.yml` for pnpm repos)

If you would prefer to add all `package.json` files as projects, add the following configuration to the `nx.json` file:

```json
// nx.json
{
  "plugins": ["nx/plugins/package-json"]
}
```

---
<!-- source: https://nx.dev/docs/guides/tips-n-tricks/include-assets-in-build.md -->
## Including Assets in Your Build

All the official Nx executors with an `assets` option have the same syntax.

There are two ways to identify assets to be copied into the output bundle:

1. Specify assets with a regex string. This will copy files over in the same folder structure as the source files.
2. Use the object format to redirect files into different locations in the output bundle.

```jsonc
// project.json
"build": {
  "executor": "@nx/js:tsc", // or any other Nx executor that supports the `assets` option
  "options": {
    // shortened...
    "assets": [
      // Copies all the markdown files at the root of the project to the root of the output bundle
      "path-to-my-project/*.md",
      {
        "input": "./path-to-my-project/src", // look in the src folder
        "glob": "**/!(*.ts)", // for any file (in any folder) that is not a typescript file
        "output": "./src" // put those files in the src folder of the output bundle
      },
      {
        "input": "./path-to-my-project", // look in the project folder
        "glob": "executors.json", // for the executors.json file
        "output": "." // put the file in the root of the output bundle
      }
    ]
  }
}
```

---
<!-- source: https://nx.dev/docs/guides/tips-n-tricks/keep-nx-versions-in-sync.md -->
## Keep Nx Versions in Sync

If your Nx plugin versions do not match the version of `nx` in your repository, you may encounter some difficulties when debugging errors. To get your Nx plugins back in sync, follow the steps below:

1. Identify all the official Nx plugins that are used in your repo. This includes `nx` and any packages in the `@nx/` organization scope, except for plugins that are still in [nx-labs](https://github.com/nrwl/nx-labs). Also, `nx-cloud` does not need to match the other package versions.
2. Run `nx report` and identify the minimum and maximum version numbers for all the packages that need to by in sync.
3. Run `nx migrate --from=[minimumVersion] --to=[maximumVersion]`. Note that all the official Nx plugin migration generators are designed to be idempotent - meaning that running them multiple times is equivalent to running them once. This allows you to run the migrations for all plugins without being concerned about re-running a migration that was already run.

Review the [nx migrate](/docs/features/automate-updating-dependencies) documentation for more options.

## Prevention

To ensure that the Nx plugin versions do not get out of sync, make sure to:

- always run `nx add <plugin>` when installing an Nx official plugin instead of using the package manager to install it
- always run `nx migrate <version>` when updating versions instead of manually updating the `package.json` file

---
<!-- source: https://nx.dev/docs/guides/tips-n-tricks/standalone-to-monorepo.md -->
## Convert from a Standalone Repository to a Monorepo

You can always add another app to a standalone repository the same way you would in a monorepo. But at some point, you may want to move the primary app out of the root of your repo because the repo is no longer primarily focused on that one app. There are other apps that are equally important and you want the folder structure to align with the new reality.

{% youtube
src="https://youtu.be/ztNpLf2Zl-c?si=u0CfLAx_tpioZ3Vu"
title="Graduating your Standalone Nx Repo to a Monorepo"
width="100%" /%}

## Run the generator

The `convert-to-monorepo` generator will attempt to convert a standalone repo to a monorepo.

```shell
nx g convert-to-monorepo
```

If you need to do the conversion manually, you can follow the steps below.

## Manual conversion strategy

For this recipe, we'll assume that the root-level app is named `my-app`. The high-level process we'll go through to move the app involves four stages:

1. Create a new app named `temp` under `apps/temp`.
2. Move source and config files from `my-app` into `apps/temp`.
3. Delete the files for `my-app`.
4. Rename `apps/temp` to `apps/my-app`

## Steps

1. If there is a `tsconfig.json` file in the root, rename it to `tsconfig.old.json`

   This step is to make sure that a `tsconfig.base.json` file is generated by the app generator in the next step.

2. Create a new app using the appropriate plugin under `apps/temp`

   ```shell
   nx g app apps/temp
   ```

3. Move the `/src` (and `/public`, if present) folders to `apps/temp/`, overwriting the folders already there.

4. For each config file in `apps/temp`, copy over the corresponding file from the root of the repo.

   It can be difficult to know which files are root-level config files and which files are project-specific config files. Here is a non-exhaustive list of config files to help distinguish between the two.

   | Type of Config  | Files                                                                                                                                                                       |
   | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | _Root-level_    | `.eslintignore`, `.eslintrc.base.json`, `.gitignore`, `.prettierignore`, `jest.config.ts`, `jest.preset.js`, `.prettierrc`, `nx.json`, `package.json`, `tsconfig.base.json` |
   | _Project-level_ | `.eslintrc.json`, `index.html`, `project.json`, `jest.config.app.ts`, `tsconfig.app.json`, `tsconfig.json`, `tsconfig.spec.json`, `vite.config.ts`, `webpack.config.js`     |

   {% aside title="jest.config.app.ts" type="note" %}
   `jest.config.app.ts` in the root should be renamed to `jest.config.ts` when moved to `apps/temp`. Also update the `jestConfig` option in `project.json` to point to `jest.config.ts` instead of `jest.config.app.ts`.
   {% /aside %}

5. Update the paths of the project-specific config files that were copied into `apps/temp`.

   Here is a non-exhaustive list of properties that will need to be updated to have the correct path:

   | Config File(s)                                             | Properties to Check                                                                                                                                                   |
   | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | `project.json`                                             | `$schema`, `sourceRoot`, `root`, `outputPath`, `reportsDirectory`, `cypressConfig`, `lintFilePatterns`, `index`, `main`, `tsConfig`, `assets`, `styles`, `jestConfig` |
   | `tsconfig.json`, `tsconfig.app.json`, `tsconfig.spec.json` | `extends`, `outDir`, `files`                                                                                                                                          |
   | `.eslintrc.json`                                           | `extends`                                                                                                                                                             |
   | `jest.config.ts`                                           | `preset`, `coverageDirectory`                                                                                                                                         |
   | `vite.config.ts`                                           | `cacheDir`, `root`, `dir`                                                                                                                                             |

6. Doublecheck that all the tasks defined in the `apps/temp/project.json` file still work.

   ```shell
   nx build temp
   nx test temp
   nx lint temp
   ```

7. Move the `/e2e/src` folder to `/apps/temp-e2e`, overwriting the folder already there
8. For each config file in `apps/temp-e2e`, copy over the corresponding file from the root of the repo. Update the paths for these files in the same way you did for the `my-app` config files.
9. Update the `/apps/temp-e2e/project.json` `implicitDependencies` to be `temp` instead of `my-app`
10. Doublecheck that all the tasks defined in the `apps/temp-e2e/project.json` file still work.

    ```shell
    nx lint temp-e2e
    nx e2e temp-e2e
    ```

11. Delete all the project specific config files in the root and under `e2e`
12. Once the `project.json` file has been deleted in the root, rename `temp-e2e` to `my-app-e2e` and rename `temp` to `my-app`

    ```shell
    nx g move --projectName=temp-e2e --destination=my-app-e2e
    nx g move --projectName=temp --destination=my-app
    ```

13. Update the `defaultProject` in `nx.json` if needed
14. Check again that all the tasks still work and that the `nx graph` displays what you expect.

---
<!-- source: https://nx.dev/docs/guides/tips-n-tricks/yarn-pnp.md -->
## Using Yarn Plug'n'Play with Nx

Plug'n'Play (PnP) is an innovative installation strategy for Node that tries to solve the challenges of using `node_modules` for storing installed packages:

- slow installation process
- slow node runtime cold start
- expensive packages diffing when adding new packages
- no ability to restrict access and enforce hoisting/nesting

Instead of using the `node_modules` folder, `PnP` creates a map from package names to hoisted package versions and creates dependency edges between packages. The packages are kept in `zip` archives which makes caching and restoring faster.

Read more about `PnP` on [Yarn's official docs](https://yarnpkg.com/features/pnp).

## Switching to Yarn v2+ (aka Berry)

When you run `create-nx-workspace` with the optional `--pm=yarn` flag, Nx uses the default yarn version set in your global `.yarnrc.yml` file (usually in the root of your user folder). To check your current yarn version, run:

```shell
 yarn --version
```

If the version is in the `1.x.x` range, the workspace will be created with yarn classic. To migrate an existing yarn classic workspace to the modern version of yarn, also known as `Berry`, run:

```shell {% title="~/workspace" frame="terminal" %}
 yarn set version stable
```

This command will update `.yarnrc.yml` with the path to the local yarn `bin` of the correct version and will set the `packageManager` property in the root `package.json`:

```jsonc
// package.json
{
  // ...
  "packageManager": "yarn@3.6.1",
}
```

## Switching to PnP

Once you are on the modern version of yarn, you can use the following command to switch to `PnP`:

```shell {% title="~/workspace" frame="terminal" %}
 yarn config set nodeLinker pnp
```

Your `.yarnrc.yml` will now have `nodeLinker` set to a proper method:

```yml
// .yarnrc.yml
nodeLinker: pnp
```

Once the config is changed you need to run the install again:

```shell {% title="~/workspace" frame="terminal" %}
 yarn install
```

Running install generates a `.pnp.cjs` file that contains a mapping of external packages and strips all the packages from the `node_modules`.

## Dealing with inaccessible dependencies

When using Yarn Berry, Nx will set the `nodeLinker` property to a backward compatible `node-modules` value by default. This is to ensure your repository works out of the box.

Some packages come with broken dependency requirements so using strict `PnP` can lead to broken builds. This results in errors similar to the one below:

```shell {% title="yarn nx build my-project" frame="terminal" %}
Error: [BABEL]: @babel/plugin-transform-react-jsx tried to access @babel/core (a peer dependency) but it isn't provided by your application; this makes the require call ambiguous and unsound.

Required package: @babel/core
```

The problem above is something we need to fix by ensuring the requested peer dependency exists and is available:

```shell {% title="~/workspace" frame="terminal" %}
 yarn add -D @babel/core
```

Sometimes, simply adding a missing package doesn't work. In those cases, the only thing we can do is contact the author of the package causing the issues and notify them of the missing dependency requirement.
The alternative is to switch back to using the `node-modules` node linker.


# Extending Nx

---
<!-- source: https://nx.dev/docs/extending-nx.md -->
## Extending Nx

{% index_page_cards path="extending-nx" /%}

---
<!-- source: https://nx.dev/docs/extending-nx/compose-executors.md -->
## Compose Executors

An executor is just a function, so you can import and invoke it directly, as follows:

```typescript
// example-executor.ts
import printAllCaps from 'print-all-caps';

export default async function (
  options: Schema,
  context: ExecutorContext
): Promise<{ success: true }> {
  // do something before
  await printAllCaps({ message: 'All caps' });
  // do something after
}
```

This only works when you know what executor you want to invoke. Sometimes, however, you need to invoke a target. For instance, the e2e target is often configured like this:

```json
// project.json
{
  "e2e": {
    "builder": "@nx/cypress:cypress",
    "options": {
      "cypressConfig": "apps/myapp-e2e/cypress.json",
      "tsConfig": "apps/myapp-e2e/tsconfig.e2e.json",
      "devServerTarget": "myapp:serve"
    }
  }
}
```

In this case we need to invoke the target configured in devSeverTarget. We can do it as follows:

```typescript
// example-executor.ts
async function* startDevServer(
  opts: CypressExecutorOptions,
  context: ExecutorContext
) {
  const { project, target, configuration } = parseTargetString(
    opts.devServerTarget
  );
  for await (const output of await runExecutor<{
    success: boolean;
    baseUrl?: string;
  }>(
    { project, target, configuration },
    {
      watch: opts.watch,
    },
    context
  )) {
    if (!output.success && !opts.watch)
      throw new Error('Could not compile application files');
    yield opts.baseUrl || (output.baseUrl as string);
  }
}
```

The `runExecutor` utility will find the target in the configuration, find the executor, construct the options (as if you invoked it in the terminal) and invoke the executor. Note that `runExecutor` always returns an iterable instead of a promise.

## Devkit helper functions

| Property                 | Description                                                    |
| ------------------------ | -------------------------------------------------------------- |
| logger                   | Wraps `console` to add some formatting                         |
| getPackageManagerCommand | Returns commands for the package manager used in the workspace |
| parseTargetString        | Parses a target string into `{project, target, configuration}` |
| readTargetOptions        | Reads and combines options for a given target                  |
| runExecutor              | Constructs options and invokes an executor                     |

See more helper functions in the [Devkit API Docs](/docs/reference/devkit)

## Using RxJS observables

The Nx devkit only uses language primitives (promises and async iterables). It doesn't use RxJS observables, but you can use them and convert them to a `Promise` or an async iterable.

You can convert `Observables` to a `Promise` with `toPromise`.

```typescript
import { of } from 'rxjs';

export default async function (opts) {
  return of({ success: true }).toPromise();
}
```

You can use the [`rxjs-for-await`](https://www.npmjs.com/package/rxjs-for-await) library to convert an `Observable` into an async iterable.

```typescript
import { of } from 'rxjs';
import { eachValueFrom } from 'rxjs-for-await';

export default async function (opts) {
  return eachValueFrom(of({ success: true }));
}
```

---
<!-- source: https://nx.dev/docs/extending-nx/composing-generators.md -->
## Composing Generators

Generators are useful individually, but reusing and composing generators allows you to build whole workflows out of simpler building blocks.

## Using Nx devkit generators

Nx Devkit generators can be imported and invoked like any javascript function. They often return a `Promise`, so they can be used with the `await` keyword to mimic synchronous code. Because this is standard javascript, control flow logic can be adjusted with `if` blocks and `for` loops as usual.

```typescript
import { libraryGenerator } from '@nx/js';

export default async function (tree: Tree, schema: any) {
  await libraryGenerator(
    tree, // virtual file system tree
    { name: schema.name } // options for the generator
  );
}
```

## Using jscodeshift codemods

Codemods created for use with [`jscodeshift`](https://github.com/facebook/jscodeshift) can be used within Nx Devkit generators using the `visitNotIgnoredFiles` helper function. This way you can compose codemods with other generators while retaining `--dry-run` and Nx Console compatibilities.

```typescript
import { Tree, visitNotIgnoredFiles } from '@nx/devkit';
import { applyTransform } from 'jscodeshift/src/testUtils';
import arrowFunctionsTransform from './arrow-functions';

// The schema path can be an individual file or a directory
export default async function (tree: Tree, schema: { path: string }): any {
  visitNotIgnoredFiles(tree, schema.path, (filePath) => {
    const input = tree.read(filePath).toString();
    const transformOptions = {};
    const output = applyTransform(
      { default: arrowFunctionsTransform, parser: 'ts' },
      transformOptions,
      { source: input, path: filePath }
    );
    tree.write(filePath, output);
  });
}
```

---
<!-- source: https://nx.dev/docs/extending-nx/create-install-package.md -->
## Creating an Install Package

{% youtube src="https://www.youtube.com/embed/ocllb5KEXZk" title="Build your own CLI" width="100%" /%}

Starting a new project should be as seamless as possible. In the JavaScript ecosystem, the idea of bootstrapping a new project with a single command has become a must-have for providing a good DX. So much that all the major package managers have a dedicated feature already built-in: if you publish a package named `create-{x}`, it can be invoked via any of the following:

- npx create-{x}
- yarn create {x}
- npm init {x}
- pnpm init {x}

These packages are used to set up a new project in some form.

Customizing your initial project setup is already possible with an [Nx Preset generator](/docs/extending-nx/create-preset). By creating and shipping a generator named `preset` in your Nx plugin, you can then pass it via the `--preset` flag to the `create-nx-workspace` command:

```shell
npx create-nx-workspace --preset my-plugin
```

This allows you to take full control over the shape of the generated Nx workspace. You might however want to have your own `create-{x}` package, whether that is for marketing purposes, branding or better discoverability. Starting with Nx 16.5 you can now have such a `create-{x}` package generated for you.

## Generating a "Create package"

There are a few methods to create a package that will work with `create-nx-workspace`'s public API to setup a new workspace that uses your Nx plugin.

You can setup a new Nx plugin workspace and immediately pass the `--create-package-name`:

```shell
npx create-nx-plugin my-plugin --create-package-name create-my-plugin
```

Alternatively, if you already have an existing Nx plugin workspace, you can run the following generator to set up a new create package:

```shell
nx g create-package create-my-plugin --project my-plugin
```

## Customize your create package

You'll have 2 packages that are relevant in your workspace:

- The create package (e.g. `create-my-plugin`)
- The plugin package (e.g. `my-plugin`)

Let's take a look at the code that was scaffolded out for your `create-my-plugin` package:

```typescript
// packages/create-my-plugin/bin/index.ts
#!/usr/bin/env node

import { createWorkspace } from 'create-nx-workspace';

async function main() {
  const name = process.argv[2]; // TODO: use libraries like yargs or enquirer to set your workspace name
  if (!name) {
    throw new Error('Please provide a name for the workspace');
  }

  console.log(`Creating the workspace: ${name}`);

  // This assumes "my-plugin" and "create-my-plugin" are at the same version
  // eslint-disable-next-line @typescript-eslint/no-var-requires
  const presetVersion = require('../package.json').version;

  // TODO: update below to customize the workspace
  const { directory } = await createWorkspace(`my-plugin@${presetVersion}`, {
    name,
    nxCloud: 'skip',
    packageManager: 'npm',
  });

  console.log(`Successfully created the workspace: ${directory}.`);
}

main();
```

This is a plain node script at this point, and you can use any dependencies you wish to handle things like prompting or argument parsing. Keeping dependencies small and splitting out the command line tool from the Nx plugin is recommended, and will help keep your CLI feeling fast and snappy.

Note the following code snippet:

```typescript
const { directory } = await createWorkspace(`my-plugin@${presetVersion}`, {
  name,
  nxCloud: 'skip',
  packageManager: 'npm',
});
```

This will invoke the `my-plugin` package's `preset` generator, which will contain the logic for setting up the workspace. This preset generator will be invoked when running either `npx create-nx-workspace --preset my-plugin` or `npx create-my-plugin`. For more information about customizing your preset, see: [Creating a Preset](/docs/extending-nx/create-preset).

## Testing your create package

Because your `create-my-plugin` package will install your plugin package at runtime, both packages must be published in order to run them and see the results. To test your packages without making them publicly available, a `local-registry` target should be present on project in your workspace's root.

```jsonc
// project.json
{
  ...
  "targets": {
    "local-registry": {
      "executor": "@nx/js:verdaccio",
      "options": {
        "port": 4873,
        "config": ".verdaccio/config.yml",
        "storage": "tmp/local-registry/storage"
      }
    }
  }
}
```

_(If you don't have such a `local-registry` target, refer to the following [docs page to generate one](/docs/technologies/typescript/generators#setup-verdaccio))_

By running

```shell
npx nx local-registry
```

...a local instance of [Verdaccio](https://verdaccio.org/) will be launched at http://localhost:4873 and the NPM, Yarn and PNPM registries will be configured to point to it. This means that you can safely publish, without hitting npm, and test as if you were an end user of your package.

{% aside type="note" title="Registry Cleanup & Reset" %}
Note, after terminating the terminal window where the `nx local-registry` command is running (e.g. using `CTRL+c` or `CMD+c`) the registry will be stopped, previously installed packages will be cleaned up and the npm/yarn/pnpm registries will be restored to their original state, pointing to the real NPM servers again.
{% /aside %}

Next, you can **publish** your packages to your new local registry. All of the generated packages can use `nx release` to publish whatever is in your `build` output folder, so you can simply run:

```shell
npx nx run-many --targets build
npx nx release version 1.0.0
npx nx release publish --tag latest
```

Once the packages are published, you should be able to test the behavior of your "create package" as follows:

```shell
npx create-my-plugin test-workspace
```

## Writing and running e2e tests

When setting up the workspace, you should also have gotten a `my-plugin-e2e` package. This package contains the e2e tests for your plugin, and can be run with the following command:

```shell
npx nx e2e my-plugin-e2e
```

Have a look at some of the example tests that were generated for you. When running these tests,

- the local registry will be started automatically
- a new version of the packages will be deployed
- then your test commands will be run (usually triggering processes that setup the workspace, just like the user would type into a command line interface)
- once the test commands have finished, the local registry will be stopped again and cleaned up

## Publishing your create package

Your plugin and create package will both need to be published to NPM to be useable. Publishing your packages is exactly the same as described [previously](#testing-your-create-package), except that you don't run the `local-registry` task so that the `publish` task will publish to the real NPM servers.

## Further reading

- [Blog post: Create your own create-react-app CLI](https://nx.dev/blog/create-your-own-create-react-app-cli)

---
<!-- source: https://nx.dev/docs/extending-nx/create-preset.md -->
## Create a Custom Plugin Preset

When you create a new nx workspace, you run the command: [`npx create-nx-workspace`](/docs/reference/create-nx-workspace).
This command accepts a `--preset` option, for example: `npx create-nx-workspace --preset=react-standalone`.
This preset option is pointing to a special generator function (remember, a generator is a function that simplifies an entire code generation script into a single function) that Nx will call when this `npx create-nx-workspace` command is run, that will generate your initial workspace.

{% youtube src="https://www.youtube.com/embed/yGUrF0-uqaU" title="Develop a Nx Preset for your Nx Plugin" /%}

## What is a preset?

At its core, a preset is a special [generator](/docs/features/generate-code) that is shipped as part of an Nx Plugin package.

All first-party Nx presets are built into Nx itself, but you can [create your own plugin](/docs/extending-nx/intro) and create a generator with the magic name: `preset`. Once you've [published your plugin](/docs/extending-nx/tooling-plugin) on npm, you can now run the `create-nx-workspace` command with the preset option set to the name of your published package.

To use a concrete example, let's look at the [`qwik-nx`](https://www.npmjs.com/package/qwik-nx) Nx community plugin. They include a [preset generator](https://github.com/qwikifiers/qwik-nx/tree/main/packages/qwik-nx/src/generators/preset) that you can use to create a new Nx workspace with Qwik support.

```shell
npx create-nx-workspace --preset=qwik-nx
```

## Create a new Nx plugin

If you **don't** have an existing plugin you can create one by running

```shell
npx create-nx-plugin my-org --pluginName my-plugin
```

## Creating a "Preset" generator

To create our preset inside of our plugin we can run

```shell
nx generate @nx/plugin:generator packages/happynrwl/src/generators/preset
```

{% aside type="caution" title="Double check" %}
The word `preset` is required for the name of this generator
{% /aside %}

You should have a similar structure to this:

{% filetree %}

- happynrwl/
  - e2e/
  - jest.config.js
  - jest.preset.js
  - nx.json
  - package-lock.json
  - package.json
  - packages/
    - happynrwl/
      - src/
        - executors/
        - generators/
          - happynrwl/
          - preset/ <-- Here
        - index.ts
  - tools/
  - tsconfig.base.json/

{% /filetree %}

After the command is finished, the preset generator is created under the folder named **preset**.
The **generator.ts** provides an entry point to the generator. This file contains a function that is called to perform manipulations on a tree that represents the file system. The **schema.json** provides a description of the generator, available options, validation information, and default values.

Here is the sample generator function which you can customize to meet your needs.

```typescript
// generator.ts
export default async function (tree: Tree, options: PresetGeneratorSchema) {
  const normalizedOptions = normalizeOptions(tree, options);
  addProjectConfiguration(tree, normalizedOptions.projectName, {
    root: normalizedOptions.projectRoot,
    projectType: 'application',
    sourceRoot: `${normalizedOptions.projectRoot}/src`,
    targets: {
      exec: {
        executor: 'nx:run-commands',
        options: {
          command: `node ${projectRoot}/src/index.js`,
        },
      },
    },
    tags: normalizedOptions.parsedTags,
  });
  addFiles(tree, normalizedOptions);
  await formatFiles(tree);
}
```

To get an in-depth guide on customizing/running or debugging your generator see [local generators](/docs/extending-nx/local-generators).

## Usage

Before you are able to use your newly created preset you must package and publish it to a registry.

After you have published your plugin to a registry you can now use your preset when creating a new workspace

```shell
npx create-nx-workspace my-workspace --preset=my-plugin-name
```

---
<!-- source: https://nx.dev/docs/extending-nx/create-sync-generator.md -->
## Create a Sync Generator

Sync generators are generators that are used to ensure that your file system is in the correct state before a task is run or the CI process is started. From a technical perspective, a sync generator is no different from any other generator, but it has some additional performance considerations and needs to be registered in a particular way.

{% aside type="caution" title="Disable the Nx Daemon during development" %}
When developing the Nx sync generator, disable the [Nx Daemon](/docs/concepts/nx-daemon) by setting `NX_DAEMON=false`. The daemon caches your plugin code, so changes to your plugin won't be reflected until the daemon restarts.
{% /aside %}

## Create a new sync generator

You can create a new sync generator by hand or use the built-in generator that Nx provides via the `@nx/plugin` package.

### Step 1: Add @nx/plugin

Make sure you have `@nx/plugin` installed or add it to your workspace:

```shell
nx add @nx/plugin
```

### Step 2: Create a local plugin

Create a new local plugin where we can add our new sync generator. You can also add it to an existing local plugin if you already have one. In that case you can skip this step.

```shell
nx g @nx/plugin:plugin tools/my-plugin
```

### Step 3: Scaffold a new sync generator

Create a sync generator the same way you would [create any generator](/docs/extending-nx/local-generators).

```shell
nx g @nx/plugin:generator --path=tools/my-plugin/src/generators/my-sync-generator
```

## Implement a global sync generator

Global sync generators are executed when the `nx sync` or `nx sync:check` command is explicitly run by a user or in a script. They are not associated with an individual task or project and typically update root-level configuration files.

A sync generator should be able to run without any required options, so update the schema accordingly:

```jsonc
// tools/my-plugin/src/generators/my-sync-generator/schema.json
{
  "$schema": "https://json-schema.org/schema",
  "$id": "MySyncGenerator",
  "title": "",
  "type": "object",
  "properties": {},
  "required": [],
}
```

Also update the TypeScript interface to match:

```ts
// tools/my-plugin/src/generators/my-sync-generator/schema.d.ts
export interface MySyncGeneratorSchema {}
```

Sync generators can optionally return an `outOfSyncMessage` to display to users when the sync generator needs to be run.

```ts
// tools/my-plugin/src/generators/my-sync-generator/my-sync-generator.ts
import { Tree } from '@nx/devkit';
import type { SyncGeneratorResult } from 'nx/src/utils/sync-generators';

export async function mySyncGenerator(
  tree: Tree
): Promise<SyncGeneratorResult> {
  if (
    !tree.exists('/legal-message.txt') ||
    tree.read('/legal-message.txt').toString() !==
      'This is an important legal message.'
  ) {
    tree.write('/legal-message.txt', 'This is an important legal message.');
  }
  return {
    outOfSyncMessage: 'The legal-message.txt file needs to be created',
  };
}

export default mySyncGenerator;
```

### Register a global sync generator

Global sync generators are registered in the `nx.json` file like this:

```jsonc
// nx.json
{
  "sync": {
    "globalGenerators": ["@myprg/my-plugin:my-sync-generator"],
  },
}
```

{% aside type="caution" title="Verify the name of your plugin" %}
You might have to adjust the name of your plugin based on your specific workspace scope. Verify the name in `tools/my-plugin/package.json`.
If your package.json has a different name, adjust the `nx.json` configuration accordingly.
{% /aside %}

Now `my-sync-generator` will be executed any time the `nx sync` command is run.

## Implement a task sync generator that uses the project graph

Task sync generators are run before a particular task and are used to ensure that the files are in the correct state for the task to be run. The primary use case for this is to set up configuration files based on the project graph. To read from the project graph, use the [`createProjectGraphAsync`](/docs/reference/devkit/createProjectGraphAsync) from the `@nx/devkit` package. Create a generator in the same way as a global sync generator and then read the project graph like this:

```ts
// tools/my-plugin/src/generators/my-sync-generator/my-sync-generator.ts
import { Tree, createProjectGraphAsync, joinPathFragments } from '@nx/devkit';
import type { SyncGeneratorResult } from 'nx/src/utils/sync-generators';

export async function mySyncGenerator(
  tree: Tree
): Promise<SyncGeneratorResult> {
  const projectGraph = await createProjectGraphAsync();
  Object.values(projectGraph.nodes).forEach((project) => {
    tree.write(
      joinPathFragments(project.data.root, 'license.txt'),
      `${project.name} uses the Acme Corp license.`
    );
  });
  return {
    outOfSyncMessage: 'Some projects are missing a license.txt file.',
  };
}

export default mySyncGenerator;
```

### Register a task sync generator

To register a generator as a sync generator for a particular task, add the generator to the `syncGenerators` property of the task configuration.

{% aside type="note" title="Important: Package.json Configuration" %}
For projects using [inferred targets](/docs/concepts/inferred-tasks) (no project.json file), the sync generators must be registered inside the `nx` property in package.json, not at the root level.
{% /aside %}

{% tabs %}
{% tabitem label="package.json" %}

```jsonc
// apps/my-app/package.json
{
  "name": "my-app",
  ...
  "nx": {
    "targets": {
      "build": {
        "syncGenerators": ["my-plugin:my-sync-generator"]
      }
    }
  }
}
```

{% /tabitem %}
{% tabitem label="project.json" %}

```jsonc
// apps/my-app/project.json
{
  "targets": {
    "build": {
      "syncGenerators": ["my-plugin:my-sync-generator"],
    },
  },
}
```

{% /tabitem %}
{% /tabs %}

{% aside type="caution" title="Verify the name of your plugin" %}
You might have to adjust the name of your plugin based on your specific workspace scope. Verify the name in `tools/my-plugin/package.json`. If the name there is `@myorg/my-plugin` you have to register it as:

```jsonc
{
  "syncGenerators": ["@myorg/my-plugin:my-sync-generator"],
}
```

{% /aside %}

With this configuration in place, running `nx build my-app` will first run `my-sync-generator` and then run the `build` task. The `my-sync-generator` and any other task or global sync generators will be run when `nx sync` or `nx sync:check` is run.

## Performance and DX considerations

Task sync generators will block the execution of the task while they are running and both global and task sync generators will block the CI pipeline until the `nx sync:check` command finishes. Because of this, make sure to keep in mind the following performance tips:

- Make the generator idempotent. Running the generator multiple times in a row should have the same impact as running the generator a single time.
- Only write to the file system when a file is actually changed. Avoid reformatting files that have not been actually modified. Nx will identify the workspace as out of sync if there's any file change after the sync generator is run.
- Make sure to provide an informative `outOfSyncMessage` so that developers know what to do to unblock their tasks.

Do whatever you can to make your sync generators as fast and user-friendly as possible, because users will be running them over and over again without even realizing it.

---
<!-- source: https://nx.dev/docs/extending-nx/createnodes-compatibility.md -->
## CreateNodes API Compatibility

This is a reference for knowing how Nx versions and the `createNodes`/`createNodesV2` APIs interact. If you plan on supporting multiple Nx versions with a custom plugin, then it's important to know which APIs to use.

## Which createNodes version does Nx call?

The following table shows which export Nx will call based on the Nx version:

| Nx Version    | Calls `createNodes` | Calls `createNodesV2` | Nx Call Preference           |
| ------------- | ------------------- | --------------------- | ---------------------------- |
| 17.x - 19.1.x | Yes                 | No                    | Only v1 supported            |
| 19.2.x - 20.x | Yes (fallback)      | Yes (preferred)       | Prefers v2, falls back to v1 |
| 21.x          | No                  | Yes                   | Only v2 supported            |
| 22.x+         | Yes (v2 signature)  | Yes                   | Both use v2 signature        |

## Which Nx versions does my plugin support?

> Note this is the same information as above, but presented as a lookup table for plugin authors.

If you're a plugin author, this table shows which Nx versions your plugin will support based on which exports you provide:

| Plugin Exports                            | Nx 17-19.1       | Nx 19.2-20       | Nx 21-21.x       | Nx 22+           |
| ----------------------------------------- | ---------------- | ---------------- | ---------------- | ---------------- |
| Only `createNodes` (v1)                   | ✅ Supported     | ✅ Supported     | ❌ Not Supported | ❌ Not Supported |
| Only `createNodesV2`                      | ❌ Not Supported | ✅ Supported     | ✅ Supported     | ✅ Supported     |
| Both `createNodes` (v1) & `createNodesV2` | ✅ Supported     | ✅ Supported     | ✅ Supported     | ✅ Supported     |
| Both with v2 signature (Nx 22+)           | ❌ Not Supported | ❌ Not Supported | ✅ Supported     | ✅ Supported     |

## Recommended implementation pattern

### Plugin Support for Nx 21 and later

For plugins targeting **Nx 21 and later**, the recommended pattern is to export both `createNodes` and `createNodesV2` using the same v2 implementation:

```typescript
// my-plugin/index.ts
import {
  CreateNodesV2,
  CreateNodesContextV2,
  createNodesFromFiles,
} from '@nx/devkit';

export interface MyPluginOptions {
  // your options
}

// Export createNodes with v2 signature
export const createNodes: CreateNodesV2<MyPluginOptions> = [
  '**/some-config.json',
  async (configFiles, options, context) => {
    return await createNodesFromFiles(
      (configFile, options, context) =>
        createNodesInternal(configFile, options, context),
      configFiles,
      options,
      context
    );
  },
];

// Re-export as createNodesV2
export const createNodesV2 = createNodes;

async function createNodesInternal(
  configFilePath: string,
  options: MyPluginOptions,
  context: CreateNodesContextV2
) {
  // Your plugin logic here
  return {
    projects: {
      // ...
    },
  };
}
```

This pattern ensures your plugin works with both Nx 21 and Nx 22+.

### Plugin support for Nx 17 through Nx 20

If you need to support Nx versions 17-20, you'll need to provide separate implementations.
In Nx 22 the type for v1 of the create nodes api are removed, you can inline the type to maintain type safety.

```typescript
// my-plugin/index.ts

import {
  CreateNodesV2,
  CreateNodesContextV2,
  CreateNodesResult,
  createNodesFromFiles,
} from '@nx/devkit';

// inlined types for backwards compat to v1 of createNodes
// removed in Nx 22
export interface OldCreateNodesContext extends CreateNodesContextV2 {
  /**
   * The subset of configuration files which match the createNodes pattern
   */
  readonly configFiles: readonly string[];
}

type OldCreateNodes<T = unknown> = readonly [
  projectFilePattern: string,
  createNodesFunction: OldCreateNodesFunction<T>,
];

export type OldCreateNodesFunction<T = unknown> = (
  projectConfigurationFile: string,
  options: T | undefined,
  context: OldCreateNodesContext
) => CreateNodesResult | Promise<CreateNodesResult>;

export interface MyPluginOptions {
  // your options
}

// V1 API for Nx 17-20

export const createNodes: OldCreateNodes<MyPluginOptions> = [
  '**/my-config.json',
  (configFile, options, context: OldCreateNodesContext) => {
    // V1 implementation - processes one file at a time
    return createNodesInternal(configFile, options, context);
  },
];

// V2 API for Nx 19.2+
export const createNodesV2: CreateNodesV2<MyPluginOptions> = [
  '**/my-config.json',

  async (configFiles, options, context: CreateNodesContextV2) => {
    return await createNodesFromFiles(
      (configFile, options, context) =>
        createNodesInternal(configFile, options, context),
      configFiles,
      options,
      context
    );
  },
];

function createNodesInternal(
  configFilePath: string,
  options: MyPluginOptions,
  context: OldCreateNodesContext | CreateNodesContextV2
) {
  // Shared logic that works with both APIs
  return {
    projects: {
      // ...
    },
  };
}
```

## Future deprecation timeline

Nx is standardizing on the v2 API. Here's the planned timeline:

- **Nx 22**: Both `createNodes` and `createNodesV2` can be exported with v2 signature. `createNodes` re-exported as `createNodesV2`.
- **Nx 23**: The `createNodesV2` export will be marked as deprecated in TypeScript types. Use `createNodes` with v2 signature instead.

## Related documentation

- [Extending the Project Graph](/docs/extending-nx/project-graph-plugins) - Learn how to create project graph plugins
- [Integrate a New Tool with a Tooling Plugin](/docs/extending-nx/tooling-plugin) - Tutorial for creating a complete plugin
- [CreateNodesV2 API Reference](/docs/reference/devkit/CreateNodesV2) - Detailed API documentation

---
<!-- source: https://nx.dev/docs/extending-nx/creating-files.md -->
## Creating Files with a Generator

Generators provide an API for managing files within your workspace. You can use generators to do things such as create, update, move, and delete files. Files with static or dynamic content can also be created.

The generator below shows you how to generate a library, and then scaffold out additional files with the newly created library.

First, you define a folder to store your static or dynamic templates used to generated files. This is commonly done in a `files` folder.

```text
happynrwl/
├── apps/
├── libs/
│   └── my-plugin
│       └── src
│           └── generators
│               └── my-generator/
│                    ├── files
│                    │   └── NOTES.md
│                    ├── index.ts
│                    └── schema.json
├── nx.json
├── package.json
└── tsconfig.base.json
```

The files can use EJS syntax to substitute variables and logic. See the [EJS Docs](https://ejs.co/) to see more information about how to write these template files.

Example NOTES.md:

```markdown
Hello, my name is <%= name %>!
```

Next, update the `index.ts` file for the generator, and generate the new files.

```typescript
// index.ts
import {
  Tree,
  formatFiles,
  installPackagesTask,
  generateFiles,
  joinPathFragments,
  readProjectConfiguration,
} from '@nx/devkit';
import { libraryGenerator } from '@nx/js';

export default async function (tree: Tree, schema: any) {
  await libraryGenerator(tree, {
    name: schema.name,
    directory: `libs/${schema.name}`,
  });
  const libraryRoot = readProjectConfiguration(tree, schema.name).root;
  generateFiles(
    tree, // the virtual file system
    joinPathFragments(__dirname, './files'), // path to the file templates
    libraryRoot, // destination path of the files
    schema // config object to replace variable in file templates
  );
  await formatFiles(tree);
  return () => {
    installPackagesTask(tree);
  };
}
```

The exported function first creates the library, then creates the additional files in the new library's folder.

Next, run the generator:

{% aside type="caution" title="Always do a dry-run" %}
Use the `-d` or `--dry-run` flag to see your changes without applying them. This will let you see what the command will do to your workspace.
{% /aside %}

```shell
nx generate my-generator mylib
```

The following information will be displayed.

```text {% title="nx generate my-generator mylib" %}
CREATE libs/mylib/README.md
CREATE libs/mylib/.babelrc
CREATE libs/mylib/src/index.ts
CREATE libs/mylib/src/lib/mylib.spec.ts
CREATE libs/mylib/src/lib/mylib.ts
CREATE libs/mylib/tsconfig.json
CREATE libs/mylib/tsconfig.lib.json
UPDATE tsconfig.base.json
UPDATE nx.json
CREATE libs/mylib/.eslintrc.json
CREATE libs/mylib/jest.config.ts
CREATE libs/mylib/tsconfig.spec.json
UPDATE jest.config.ts
CREATE libs/mylib/NOTES.md
```

`libs/mylib/NOTES.md` will contain the content with substituted variables:

```markdown
Hello, my name is mylib!
```

## Dynamic file names

If you want the generated file or folder name to contain variable values, use `__variable__`. So `NOTES-for-__name__.md` would be resolved to `NOTES_for_mylib.md` in the above example.

## Overwrite mode

By default, generators overwrite files when they already exist.

You can customize this behaviour with an optional argument to `generateFiles` that can take one of three values:

- `OverwriteStrategy.Overwrite` (default): all generated files are created and overwrite existing target files if any.
- `OverwriteStrategy.KeepExisting`: generated files are created only when target file does not exist. Existing target files are kept as is.
- `OverwriteStrategy.ThrowIfExisting`: if a target file already exists, an exception is thrown. Suitable when a pristine target environment is expected.

## EJS syntax quickstart

The [EJS syntax](https://ejs.co/) can do much more than replace variable names with values. Here are some common techniques.

1. Pass a function into the template:

```typescript
// template file
This is my <%= uppercase(name) %>
```

```typescript
// typescript file
function uppercase(val: string) {
  return val.toUpperCase();
}

// later

generateFiles(tree, join(__dirname, './files'), libraryRoot, {
  uppercase,
  name: schema.name,
});
```

2. Use javascript for control flow in the template:

```typescript
<% if(shortVersion) { %>
This is the short version.
<% } else {
  for(let x=0; x<numRepetitions; x++) {
  %>
  This text will be repeated <%= numRepetitions %> times.
<% } // end for loop
} // end else block %>
```

```typescript
// typescript file
generateFiles(tree, join(__dirname, './files'), libraryRoot, {
  shortVersion: false,
  numRepetitions: 3,
});
```

---
<!-- source: https://nx.dev/docs/extending-nx/intro.md -->
## Extending Nx with Plugins

Nx core functionality focuses on task running and understanding your project and task graph. Nx plugins leverage that functionality to enforce best practices, seamlessly integrate tooling and allow developers to get up and running quickly.

As your repository grows, you'll discover more reasons to create your own plugin

- You can help encourage your coworkers to consistently follow best practices by creating [code generators](/docs/features/generate-code) that are custom built for your repository.
- You can remove duplicate configuration and ensure accurate caching settings by writing your own [inferred tasks](/docs/concepts/inferred-tasks).
- For organizations with multiple monorepos, you can encourage consistency across repositories by providing a repository [preset](/docs/extending-nx/create-preset) and writing [migrations](/docs/extending-nx/migration-generators) that will help keep every project in sync.
- You can write a plugin that integrates a tool or framework into Nx and then [share your plugin](/docs/extending-nx/publish-plugin) with the broader community.

## Create your own plugin

Get started developing your own plugin with a few terminal commands:

{% tabs %}
{% tabitem label="Create a plugin in a new workspace" %}

```shell
npx create-nx-plugin my-plugin
```

{% /tabitem %}

{% tabitem label="Add a plugin to an existing workspace" %}

```shell
npx nx add @nx/plugin
npx nx g plugin tools/my-plugin
```

{% /tabitem %}
{% /tabs %}

## Learn by doing

You can follow along with one of the step by step tutorials below that is focused on a particular use-case. These tutorials expect you to already have the following skills:

- [Run tasks](/docs/features/run-tasks) with Nx and configure Nx to [infers tasks for you](/docs/concepts/inferred-tasks)
- [Use code generators](/docs/features/generate-code)
- Understand the [project graph](/docs/features/explore-graph)
- Write [TypeScript](https://www.typescriptlang.org/) code

{% cardgrid %}

{% linkcard title="Enforce Best Practices in Your Repository" href="/docs/extending-nx/organization-specific-plugin" /%}
{% linkcard title="Integrate a Tool Into an Nx Repository"  href="/docs/extending-nx/tooling-plugin"  /%}

{% /cardgrid %}

## Create your first code generator

Wire up a new generator with this terminal command:

```shell
npx nx g generator my-plugin/src/generators/library-with-readme
```

### Understand the generator functionality

This command will register the generator in the plugin's `generators.json` file and create some default generator code in the `library-with-readme` folder. The `libraryWithReadmeGenerator` function in the `generator.ts` file is where the generator functionality is defined.

```typescript
// my-plugin/src/generators/library-with-readme/generator.ts
export async function libraryWithReadmeGenerator(
  tree: Tree,
  options: LibraryWithReadmeGeneratorSchema
) {
  const projectRoot = `libs/${options.name}`;
  addProjectConfiguration(tree, options.name, {
    root: projectRoot,
    projectType: 'library',
    sourceRoot: `${projectRoot}/src`,
    targets: {},
  });
  generateFiles(tree, path.join(__dirname, 'files'), projectRoot, options);
  await formatFiles(tree);
}
```

This generator calls the following functions:

- `addProjectConfiguration` - Create a new project configured for TypeScript code.
- `generateFiles` - Create files in the new project based on the template files in the `files` folder.
- `formatFiles` - Format the newly created files with Prettier.

You can find more helper functions in the [Nx Devkit reference documentation](/docs/reference/devkit).

### Create a rEADME template file

We can remove the generated `index.ts.template` file and add our own `README.md.template` file in the `files` folder.

```typescript
// my-plugin/src/generators/library-with-readme/files/README.md.template
# <%= name %>

This was generated by the `library-with-readme` generator!
```

The template files that are used in the `generateFiles` function can inject variables and functionality using the EJS syntax. Our `README` template will replace `<%= name %>` with the name specified in the generator. Read more about the EJS syntax in the [creating files with a generator recipe](/docs/extending-nx/creating-files).

### Run your generator

You can test your generator in dry-run mode with the following command:

```shell
npx nx g my-plugin:library-with-readme mylib --dry-run
```

If you're happy with the files that are generated, you can actually run the generator by removing the `--dry-run` flag.

## Next steps

- [Browse the plugin registry](/docs/plugin-registry) to find one that suits your needs.
- [Sign up for Nx Enterprise](https://nx.dev/enterprise) to get dedicated support from Nx team members.
- [Collaborate on the Nx Discord](https://go.nx.dev/community) to work with other plugin authors.

---
<!-- source: https://nx.dev/docs/extending-nx/local-executors.md -->
## Write a Simple Executor

Creating Executors for your workspace standardizes scripts that are run during your development/building/deploying tasks in order to provide guidance in the terminal with `--help` and when invoking with [Nx Console](/docs/getting-started/editor-setup)

This guide shows you how to create, run, and customize executors within your Nx workspace. The examples use the trivial use-case of an `echo` command.

## Creating an executor

If you don't already have a plugin, use Nx to generate one:

```shell
nx add @nx/plugin
nx g @nx/plugin:plugin tools/my-plugin
```

Use the Nx CLI to generate the initial files needed for your executor.

```shell
nx generate @nx/plugin:executor tools/my-plugin/src/executors/echo
```

After the command is finished, the executor is created in the plugin `executors` folder.

{% filetree %}

- happynrwl/
  - apps/
  - tools/
    - my-plugin/
      - src/
        - executors/
          - echo/
            - executor.spec.ts
            - executor.ts
            - schema.d.ts
            - schema.json
  - nx.json
  - package.json
  - tsconfig.base.json

{% /filetree %}

### schema.json

This file describes the options being sent to the executor (very similar to the `schema.json` file of generators). Setting the `cli` property to `nx` indicates that you're using the Nx Devkit to make this executor.

```json
// schema.json
{
  "$schema": "https://json-schema.org/schema",
  "type": "object",
  "properties": {
    "textToEcho": {
      "type": "string",
      "description": "Text To Echo"
    }
  }
}
```

This example describes a single option for the executor that is a `string` called `textToEcho`. When using this executor, specify a `textToEcho` property inside the options.

In our `executor.ts` file, we're creating an `Options` interface that matches the json object being described here.

### executor.ts

The `executor.ts` contains the actual code for your executor. Your executor's implementation must export a function that takes an options object and returns a `Promise<{ success: boolean }>`.

```typescript
// executor.ts
import type { ExecutorContext } from '@nx/devkit';
import { exec } from 'child_process';
import { promisify } from 'util';

export interface EchoExecutorOptions {
  textToEcho: string;
}

export default async function echoExecutor(
  options: EchoExecutorOptions,
  context: ExecutorContext
): Promise<{ success: boolean }> {
  console.info(`Executing "echo"...`);
  console.info(`Options: ${JSON.stringify(options, null, 2)}`);

  const { stdout, stderr } = await promisify(exec)(
    `echo ${options.textToEcho}`
  );
  console.log(stdout);
  console.error(stderr);

  const success = !stderr;
  return { success };
}
```

## Running your executor

Our last step is to add this executor to a given project's `targets` object in your project's `project.json` file:

```jsonc {% meta="{6-11}" %}
// project.json
{
  //...
  "targets": {
    // ...
    "echo": {
      "executor": "@my-org/my-plugin:echo",
      "options": {
        "textToEcho": "Hello World",
      },
    },
  },
}
```

{% aside type="caution" title="Use the package.json name" %}
When referencing your plugin, you must use the name defined in `tools/my-plugin/package.json`.
In this example, we're using `@myorg/my-plugin` as the plugin name.
If your package.json has a different name, adjust the command accordingly.
{% /aside %}

Finally, you run the executor via the CLI as follows:

```shell
nx run my-project:echo
```

To which we'll see the console output:

```text {% title="nx run my-project:echo" frame="terminal" %}
Executing "echo"...
Options: {
  "textToEcho": "Hello World"
}
Hello World
```

{% aside type="caution" title="string" %}

Nx uses the paths from `tsconfig.base.json` when running plugins locally, but uses the recommended tsconfig for node 16 for other compiler options. See https://github.com/tsconfig/bases/blob/main/bases/node16.json

{% /aside %}

## Using node child process

[Node.js `childProcess`](https://nodejs.org/api/child_process.html) is often useful in executors.

Part of the power of the executor API is the ability to compose executors via existing targets. This way you can combine other executors from your workspace into one which could be helpful when the process you're scripting is a combination of other existing executors provided by the CLI or other custom executors in your workspace.

Here's an example of this (from a hypothetical project), that serves an api (project name: "api") in watch mode, then serves a frontend app (project name: "web-client") in watch mode:

```typescript
// executor.ts
import { ExecutorContext, runExecutor } from '@nx/devkit';

export interface MultipleExecutorOptions {}

export default async function multipleExecutor(
  options: MultipleExecutorOptions,
  context: ExecutorContext
): Promise<{ success: boolean }> {
  const result = await Promise.race([
    await runExecutor(
      { project: 'api', target: 'serve' },
      { watch: true },
      context
    ),
    await runExecutor(
      { project: 'web-client', target: 'serve' },
      { watch: true },
      context
    ),
  ]);
  for await (const res of result) {
    if (!res.success) return res;
  }

  return { success: true };
}
```

For other ideas on how to create your own executors, you can always check out Nx own open-source executors as well!

{% github_repository url="https://github.com/nrwl/nx/blob/master/packages/cypress/src/executors/cypress/cypress.impl.ts" /%}

## Using custom hashers

For most executors, the default hashing in Nx makes sense. The output of the executor is dependent on the files in the project that it is being run for, or that project's dependencies, and nothing else. Changing a miscellaneous file at the workspace root will not affect that executor, and changing _*any*_ file inside of the project may affect the executor. When dealing with targets which only depend on a small subset of the files in a project, or may depend on arbitrary data that is not stored within the project, the default hasher may not make sense anymore. In these cases, the target will either experience more frequent cache misses than necessary or not be able to be cached.

Executors can provide a custom hasher that Nx uses when determining if a target run should be a cache hit, or if it must be run. When generating an executor for a plugin, you can use `nx g @nx/plugin:executor packages/my-plugin/src/executors/my-executor --includeHasher` to automatically add a custom hasher.

If you want to add a custom hasher manually, create a new file beside your executor's implementation. We will use `hasher.ts` as an example here. You'll also need to update `executors.json`, so that it resembles something like this:

```json
// executors.json
{
  "executors": {
    "echo": {
      "implementation": "./src/executors/my-executor/executor",
      "hasher": "./src/executors/my-executor/hasher",
      "schema": "./src/executors/my-executor/schema.json"
    }
  }
}
```

This would allow you to write a custom function in `hasher.ts`, which Nx would use to calculate the target's hash. As an example, consider the below hasher which mimics the behavior of Nx default hashing algorithm.

```typescript
// hasher.ts
import { CustomHasher, Task, HasherContext } from '@nx/devkit';

export const mimicNxHasher: CustomHasher = async (
  task: Task,
  context: HasherContext
) => {
  return context.hasher.hashTask(task);
};

export default mimicNxHasher;
```

The hash function can do anything it wants, but it is important to remember that the hasher replaces the hashing done normally by Nx. If you change the hasher, Nx may return cache hits when you do not anticipate it. Imagine the below custom hasher:

```typescript
// hasher.ts
import { CustomHasher, Task, HasherContext } from '@nx/devkit';

export const badHasher: CustomHasher = async (
  task: Task,
  context: HasherContext
) => {
  return {
    value: 'my-static-hash',
  };
};

export default badHasher;
```

This hasher would never return a different hash, so every run of a task that consumes the executor would be a cache hit. It is important that anything that would change the result of your executor's implementation is accounted for in the hasher.

---
<!-- source: https://nx.dev/docs/extending-nx/local-generators.md -->
## Local Generators

Local plugin generators provide a way to automate many tasks you regularly perform as part of your development workflow. Whether it is scaffolding out components, features, or ensuring libraries are generated and structured in a certain way, generators help you standardize these tasks in a consistent, and predictable manner.

Nx provides tooling around creating, and running custom generators from within your workspace. This guide shows you how to create, run, and customize generators within your Nx workspace.

{% youtube
src="https://www.youtube.com/embed/myqfGDWC2go"
title="Scaffold new Pkgs in a PNPM Workspaces Monorepo"
caption="Demoes how to use Nx generators in a PNPM workspace to automate the creation of libraries"
/%}

## Creating a generator

If you don't already have a local plugin, use Nx to generate one:

```shell
nx add @nx/plugin
nx g @nx/plugin:plugin tools/my-plugin
```

Note that `latest` should match the version of the `nx` plugins installed in your workspace.

Use the Nx CLI to generate the initial files needed for your generator.

```shell
nx generate @nx/plugin:generator tools/my-plugin/src/generators/my-generator
```

After the command is finished, the generator is created in the plugin `generators` folder.

{% filetree %}

- happynrwl/
  - apps/
  - tools/
    - my-plugin/
      - src/
        - generators/
          - my-generator/
            - generator.spec.ts
            - generator.ts
            - schema.d.ts
            - schema.json
  - nx.json
  - package.json
  - tsconfig.base.json

{% /filetree %}

The `generator.ts` provides an entry point to the generator. The file contains a function that is called to perform manipulations on a tree that represents the file system.
The `schema.json` provides a description of the generator, available options, validation information, and default values.

The initial generator function creates a library.

```typescript
// generator.ts
import { Tree, formatFiles, installPackagesTask } from '@nx/devkit';
import { libraryGenerator } from '@nx/js';

export default async function (tree: Tree, schema: any) {
  await libraryGenerator(tree, { name: schema.name });
  await formatFiles(tree);
  return () => {
    installPackagesTask(tree);
  };
}
```

To invoke other generators, import the entry point function and run it against the tree. `async/await` can be used to make code with Promises read like procedural code. The generator function may return a callback function that is executed after changes to the file system have been applied.

In the `schema.json` file for your generator, the `name` is provided as a default option. The `cli` property is set to `nx` to signal that this is a generator that uses `@nx/devkit` and not `@angular-devkit`.

```json
// schema.json
{
  "cli": "nx",
  "id": "test",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Library name",
      "$default": {
        "$source": "argv",
        "index": 0
      }
    }
  },
  "required": ["name"]
}
```

The `$default` object is used to read arguments from the command-line that are passed to the generator. The first argument passed to this schematic is used as the `name` property.

## Running a generator

To run a generator, invoke the `nx generate` command with the name of the generator.

```shell
nx generate @myorg/my-plugin:my-generator mylib
```

{% aside type="caution" title="Use the package.json name" %}
When referencing your plugin, you must use the name defined in `tools/my-plugin/package.json`.
In this example, we're using `@myorg/my-plugin` as the plugin name.
If your package.json has a different name, adjust the command accordingly.
{% /aside %}

{% aside type="caution" title="TsConfig" %}

Nx uses the paths from `tsconfig.base.json` when running plugins locally, but uses the recommended tsconfig for node 16 for other compiler options. See https://github.com/tsconfig/bases/blob/main/bases/node16.json

{% /aside %}

## Debugging generators

### With visual studio code

1. Open the Command Palette and choose `Debug: Create JavaScript Debug Terminal`.
   This will open a terminal with debugging enabled.
2. Set breakpoints in your code
3. Run `nx g my-generator` in the debug terminal.

![vscode-schematics-debug](../../../assets/nx-console/vscode-schematics-debug.png)

## Generator schema properties

Beyond the standard [JSON Schema](https://json-schema.org/) properties like `type`, `description`, `enum`, and `default`, Nx recognizes several custom properties in your `schema.json` that control CLI prompting behavior and how [Nx Console](/docs/getting-started/editor-setup) renders the generator form.

### `$default`

Provides a dynamic default value from a runtime source. Used to map positional CLI arguments and other context to schema properties.

```json
// schema.json
{
  "properties": {
    "name": {
      "type": "string",
      "$default": {
        "$source": "argv",
        "index": 0
      }
    }
  }
}
```

| Source                              | Description                                                                                 |
| ----------------------------------- | ------------------------------------------------------------------------------------------- |
| `{ "$source": "argv", "index": 0 }` | Uses the positional CLI argument at the given index                                         |
| `{ "$source": "projectName" }`      | Uses the current project name. Also triggers project autocomplete in the CLI and Nx Console |
| `{ "$source": "workingDirectory" }` | Uses the current working directory relative to the workspace root                           |
| `{ "$source": "unparsed" }`         | Collects any extra arguments not matched by other schema properties                         |

### `x-prompt`

Defines an interactive prompt shown when the option is not provided on the command line. Can be a simple string or a structured object for more control.

```json
// schema.json
{
  "properties": {
    "style": {
      "type": "string",
      "description": "The file extension to be used for style files.",
      "x-prompt": {
        "message": "Which stylesheet format would you like to use?",
        "type": "list",
        "items": [
          { "value": "css", "label": "CSS" },
          { "value": "scss", "label": "SASS (.scss)" },
          { "value": "less", "label": "LESS" }
        ]
      }
    }
  }
}
```

**Short form:** `"x-prompt": "What name would you like to use?"` — displays a simple text prompt.

**Long form object properties:**

| Property      | Type                                             | Description                                           |
| ------------- | ------------------------------------------------ | ----------------------------------------------------- |
| `message`     | `string`                                         | The prompt text displayed to the user                 |
| `type`        | `string`                                         | Prompt type: `"input"`, `"list"`, or `"confirmation"` |
| `multiselect` | `boolean`                                        | Allow selecting multiple items (for `"list"` type)    |
| `items`       | `(string \| { label: string, value: string })[]` | Choices for `"list"` type prompts                     |

In Nx Console, the `message` is shown as a tooltip on the field and `items` labels are shown as option descriptions.

### `x-priority`

Controls the visibility and ordering of an option in the Nx Console Generate form.

```json
// schema.json
{
  "properties": {
    "name": {
      "type": "string",
      "x-priority": "important"
    },
    "skipFormat": {
      "type": "boolean",
      "x-priority": "internal"
    }
  }
}
```

| Value         | Effect                                                        |
| ------------- | ------------------------------------------------------------- |
| `"important"` | Field appears near the top of the form, after required fields |
| `"internal"`  | Field is hidden from the form by default                      |

Options in the Nx Console form are sorted: **required** > **important** > **regular** > **deprecated** > **internal**.

### `x-deprecated`

Marks an option as deprecated. Deprecated options are sorted to the bottom of the form in Nx Console and display a warning.

```json
// schema.json
{
  "properties": {
    "oldOption": {
      "type": "string",
      "x-deprecated": "Use 'newOption' instead."
    }
  }
}
```

The value can be `true` (boolean) or a string with the deprecation reason/migration guidance.

### `x-dropdown`

Tells both the CLI and Nx Console to present a dropdown populated with workspace data.

```json
// schema.json
{
  "properties": {
    "projectName": {
      "type": "string",
      "x-dropdown": "projects"
    }
  }
}
```

Currently only `"projects"` is supported, which shows all projects in the workspace.

{% aside type="note" title="Automatic project autocomplete" %}
The CLI and Nx Console also automatically provide project autocomplete for any property named `project` or `projectName`, or that has `$default` set to `{ "$source": "projectName" }` — even without `x-dropdown`.
{% /aside %}

### `x-hint`

Displays a hint popover next to the field label in the Nx Console Generate form. Use this for brief contextual guidance that doesn't belong in the main `description`.

```json
// schema.json
{
  "properties": {
    "name": {
      "type": "string",
      "x-hint": "You can provide a nested path like my-dir/my-lib"
    }
  }
}
```

### `x-completion-type` and `x-completion-glob`

These properties are used by Nx Console's language server to provide autocomplete suggestions when editing configuration files like `project.json` or `nx.json`.

```json
// schema.json
{
  "properties": {
    "tsConfig": {
      "type": "string",
      "x-completion-type": "file",
      "x-completion-glob": "tsconfig*.json"
    }
  }
}
```

| `x-completion-type` value | Description                                                               |
| ------------------------- | ------------------------------------------------------------------------- |
| `"file"`                  | Autocomplete with file paths (optionally filtered by `x-completion-glob`) |
| `"directory"`             | Autocomplete with directory paths                                         |
| `"projects"`              | Autocomplete with workspace project names                                 |
| `"targets"`               | Autocomplete with available target names                                  |
| `"targetsWithDeps"`       | Autocomplete targets, including `^target` syntax for dependencies         |
| `"tags"`                  | Autocomplete with project tags                                            |
| `"projectTarget"`         | Autocomplete with `project:target` format                                 |

## Generator utilities

The [`@nx/devkit` package](/docs/reference/devkit) provides many utility functions that can be used in generators to help with modifying files, reading and updating configuration files, and working with an Abstract Syntax Tree (AST).

---
<!-- source: https://nx.dev/docs/extending-nx/migration-generators.md -->
## Migration Generators

When your plugin is being used in other repos, it is helpful to provide migration generators to automatically update configuration files when your plugin makes a breaking change.

A migration generator is a normal generator that is triggered when a developer runs the `nx migrate` command.

## Create a migration generator

For this example, we'll create a new migration generator that updates repos to use `newExecutorName` instead of `oldExecutorName` in their targets. This migration will be applied when the run `nx migrate` to move up past version `2.0.1` of our plugin.

### 1. Generate a migration

```shell
nx generate @nx/plugin:migration libs/pluginName/src/migrations/change-executor-name \
 --name='Change Executor Name' \
 --packageVersion=2.0.1 \
 --project=pluginName \
 --description='Changes the executor name from oldExecutorName to newExecutorName'
```

This command will update the following files:

```json
// package.json
{
  "nx-migrations": {
    "migrations": "./migrations.json"
  }
}
```

```json
// migrations.json
{
  "generators": {
    "change-executor-name": {
      "version": "2.0.1",
      "description": "Changes the executor name from oldExecutorName to newExecutorName",
      "cli": "nx",
      "implementation": "./src/migrations/change-executor-name/change-executor-name"
    }
  }
}
```

And it creates a blank generator under: `libs/pluginName/src/migrations/change-executor-name/change-executor-name.ts`

### 2. write the generator code

```ts
// change-executor-name.ts
import { getProjects, Tree, updateProjectConfiguration } from '@nx/devkit';

export function changeExecutorNameToNewName(tree: Tree) {
  const projects = getProjects(tree);

  for (const [name, project] of projects) {
    if (
      project.targets?.build?.executor === '@myorg/pluginName:oldExecutorName'
    ) {
      project.targets.build.executor = '@myorg/pluginName:newExecutorName';
      updateProjectConfiguration(tree, name, project);
    }
  }
}

export default changeExecutorNameToNewName;
```

## Update package.json dependencies

If you just need to change dependency versions, you can add some configuration options to the `migrations.json` file without making a full generator.

```json
// migrations.json
{
  "packageJsonUpdates": {
    // this can be any name
    "12.10.0": {
      // this is version at which the change will be applied
      "version": "12.10.0-beta.2",
      "packages": {
        // the name of the dependency to update
        "@testing-library/react": {
          // the version to set the dependency to
          "version": "11.2.6",
          // When true, the dependency will be added if it isn't there.  When false, the dependency is skipped if it isn't already present.
          "alwaysAddToPackageJson": false
        }
      }
    }
  }
}
```

---
<!-- source: https://nx.dev/docs/extending-nx/modifying-files.md -->
## Modifying Files with a Generator

Modifying existing files is an order of magnitude harder than creating new files, so care should be taken when trying to automate this process. When the situation merits it, automating a process can lead to tremendous benefits across the organization. Here are some approaches listed from simplest to most complex.

## Compose existing generators

If you can compose together existing generators to modify the files you need, you should take that approach. See [Composing Generators](/docs/extending-nx/composing-generators) for more information.

## Modify JSON files

JSON files are fairly simple to modify, given their predictable structure.

The following example adds a `package.json` script that issues a friendly greeting.

```typescript
import { updateJson } from '@nx/devkit';

export default async function (tree: Tree, schema: any) {
  updateJson(tree, 'package.json', (pkgJson) => {
    // if scripts is undefined, set it to an empty object
    pkgJson.scripts = pkgJson.scripts ?? {};
    // add greet script
    pkgJson.scripts.greet = 'echo "Hello!"';
    // return modified JSON object
    return pkgJson;
  });
}
```

## String replace

For files that are not as predictable as JSON files (like `.ts`, `.md` or `.css` files), modifying the contents can get tricky. One approach is to do a find and replace on the string contents of the file.

Let's say we want to replace any instance of `thomasEdison` with `nikolaTesla` in the `index.ts` file.

```typescript
export default async function (tree: Tree, schema: any) {
  const filePath = `path/to/index.ts`;
  const contents = tree.read(filePath).toString();
  const newContents = contents.replace('thomasEdison', 'nikolaTesla');
  tree.write(filePath, newContents);
}
```

This works, but only replaces the first instance of `thomasEdison`. To replace them all, you need to use regular expressions. (Regular expressions also give you a lot more flexibility in how you search for a string.)

```typescript
export default async function (tree: Tree, schema: any) {
  const filePath = `path/to/index.ts`;
  const contents = tree.read(filePath).toString();
  const newContents = contents.replace(/thomasEdison/g, 'nikolaTesla');
  tree.write(filePath, newContents);
}
```

## AST manipulation

ASTs (Abstract Syntax Trees) allow you to understand exactly the code you're modifying. Replacing a string value can accidentally modify text found in a comment rather than changing the name of a variable.

We'll write a generator that replaces all instances of the type `Array<something>` with `something[]`. To help accomplish this, we'll use the `@phenomnomnominal/tsquery` npm package and the [TSQuery Playground](https://tsquery-playground.firebaseapp.com/) site. TSQuery allows you to query and modify ASTs with a syntax similar to CSS selectors. The AST Explorer tool allows you to easily examine the AST for a given snippet of code.

First, go to [TSQuery Playground](https://tsquery-playground.firebaseapp.com/) and paste in a snippet of code that contains the input and desired output of our generator.

```typescript
// input
const arr: Array<string> = [];

// desired output
const arr: string[] = [];
```

When you place the cursor on the `Array` text, the right hand panel highlights the corresponding node of the AST. The AST node we're looking for looks like this:

```typescript
{ // TypeReference
  typeName: { // Identifier
    escapedText: "Array"
  },
  typeArguments: [/* this is where the generic type parameter is specified */]
}
```

Second, we need to choose a selector to target this node. Just like with CSS selectors, there is an art to choosing a selector that is specific enough to target the correct nodes, but not overly tied to a certain structure. For our simple example, we can use `TypeReference` to select the parent node and check to see if it has a `typeName` of `Array` before we perform the replacement. We'll then use the `typeArguments` to get the text inside the `<>` characters.

The finished code looks like this:

```typescript
import { readProjectConfiguration, Tree } from '@nx/devkit';
import { tsquery } from '@phenomnomnominal/tsquery';
import { TypeReferenceNode } from 'typescript';

/**
 * Run the callback on all files inside the specified path
 */
function visitAllFiles(
  tree: Tree,
  path: string,
  callback: (filePath: string) => void
) {
  tree.children(path).forEach((fileName) => {
    const filePath = `${path}/${fileName}`;
    if (!tree.isFile(filePath)) {
      visitAllFiles(tree, filePath, callback);
    } else {
      callback(filePath);
    }
  });
}

export default function (tree: Tree, schema: any) {
  const sourceRoot = readProjectConfiguration(tree, schema.name).sourceRoot;
  visitAllFiles(tree, sourceRoot, (filePath) => {
    const fileEntry = tree.read(filePath);
    const contents = fileEntry.toString();

    // Check each `TypeReference` node to see if we need to replace it
    const newContents = tsquery.replace(contents, 'TypeReference', (node) => {
      const trNode = node as TypeReferenceNode;
      if (trNode.typeName.getText() === 'Array') {
        const typeArgument = trNode.typeArguments[0];
        return `${typeArgument.getText()}[]`;
      }
      // return undefined does not replace anything
    });

    // only write the file if something has changed
    if (newContents !== contents) {
      tree.write(filePath, newContents);
    }
  });
}
```

---
<!-- source: https://nx.dev/docs/extending-nx/organization-specific-plugin.md -->
## Enforce Organizational Best Practices with a Local Plugin

Every repository has a unique set of conventions and best practices that developers need to learn in order to write code that integrates well with the rest of the code base. It is important to document those best practices, but developers don't always read the documentation and even if they have read the documentation, they don't consistently follow the documentation every time they perform a task. Nx allows you to encode these best practices in code generators that have been tailored to your specific repository.

We will create a generator that helps enforce the follow best practices:

- Every project in this repository should use Vitest for unit tests.
- Every project in this repository should be tagged with a `scope:*` tag that is chosen from the list of available scopes.
- Projects should be placed in folders that match the scope that they are assigned.
- Vitest should clear mocks before running tests.

## Get started

Let's first create a new workspace with the `create-nx-workspace` command:

```shell
npx create-nx-workspace myorg --preset=react-monorepo --ci=github
```

Then we , install the `@nx/plugin` package and generate a plugin:

```shell
npx nx add @nx/plugin
npx nx g @nx/plugin:plugin tools/recommended
```

This will create a `recommended` project that contains all your plugin code.

## Create a customized library generator

To create a new generator run:

```shell
npx nx generate @nx/plugin:generator tools/recommended/src/generators/library
```

The new generator is located in `tools/recommended/src/generators/library`. The `generator.ts` file contains the code that runs the generator. We can delete the `files` directory since we won't be using it and update the `generator.ts` file with the following code:

```ts
// tools/recommended/src/generators/library/generator.ts
import { Tree } from '@nx/devkit';
import { Linter } from '@nx/eslint';
import { libraryGenerator as reactLibraryGenerator } from '@nx/react';
import { LibraryGeneratorSchema } from './schema';

export async function libraryGenerator(
  tree: Tree,
  options: LibraryGeneratorSchema
) {
  const callbackAfterFilesUpdated = await reactLibraryGenerator(tree, {
    ...options,
    linter: 'eslint',
    style: 'css',
    unitTestRunner: 'vitest',
  });

  return callbackAfterFilesUpdated;
}

export default libraryGenerator;
```

Notice how this generator is calling the `@nx/react` plugin's `library` generator with a predetermined list of options. This helps developers to always create projects with the recommended settings.

We're returning the `callbackAfterFilesUpdated` function because the `@nx/react:library` generator sometimes needs to install packages from NPM after the file system has been updated by the generator. You can provide your own callback function instead, if you have tasks that rely on actual files being present.

To try out the generator in dry-run mode, use the following command:

```shell
npx nx g @myorg/recommended:library test-library --dry-run
```

{% aside type="caution" title="Use the package.json name" %}
When referencing your plugin, you must use the name defined in `tools/recommended/package.json`.
In this example, we're using `@myorg/recommended` as the plugin name.
If your package.json has a different name, adjust the command accordingly.
{% /aside %}

Remove the `--dry-run` flag to actually create a new project.

### Add generator options

The `schema.d.ts` file contains all the options that the generator supports. By default, it includes only a `name` option. Let's add a directory option to pass on to the `@nx/react` generator.

{% tabs syncKey="schema-file" %}
{% tabitem label="schema.d.ts" %}

```ts
// tools/recommended/src/generators/library/schema.d.ts
export interface LibraryGeneratorSchema {
  name: string;
  directory?: string;
}
```

{% /tabitem %}
{% tabitem label="schema.json" %}

```json
// tools/recommended/src/generators/library/schema.json
{
  "$schema": "https://json-schema.org/schema",
  "$id": "Library",
  "title": "",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "",
      "$default": {
        "$source": "argv",
        "index": 0
      },
      "x-prompt": "What name would you like to use?"
    },
    "directory": {
      "type": "string",
      "description": ""
    }
  },
  "required": ["name"]
}
```

{% /tabitem %}
{% /tabs %}

{% aside type="note" title="More details" %}
The `schema.d.ts` file is used for type checking inside the implementation file. It should match the properties in `schema.json`.
{% /aside %}

The schema files not only provide structure to the CLI, but also allow [Nx Console](/docs/getting-started/editor-setup) to show an accurate UI for the generator.

![Nx Console UI for the library generator](../../../assets/nx-console/generator-options-ui.png)

Notice how we made the `description` argument optional in both the JSON and type files. If we call the generator without passing a directory, the project will be created in a directory with same name as the project. We can test the changes to the generator with the following command:

```shell
npx nx g @myorg/recommended:library test-library --directory=nested/directory/test-library --dry-run
```

### Choose a scope

It can be helpful to tag a library with a scope that matches the application it should be associated with. With these tags in place, you can [set up rules](/docs/features/enforce-module-boundaries) for how projects can depend on each other. For our repository, let's say the scopes can be `store`, `api` or `shared` and the default directory structure should match the chosen scope. We can update the generator to encourage developers to maintain this structure.

{% tabs syncKey="schema-file" %}
{% tabitem label="schema.d.ts" %}

```ts
// tools/recommended/src/generators/library/schema.d.ts
export interface LibraryGeneratorSchema {
  name: string;
  scope: string;
  directory?: string;
}
```

{% /tabitem %}
{% tabitem label="schema.json" %}

```json
// tools/recommended/src/generators/library/schema.json
{
  "$schema": "https://json-schema.org/schema",
  "$id": "Library",
  "title": "",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "",
      "$default": {
        "$source": "argv",
        "index": 0
      },
      "x-prompt": "What name would you like to use?"
    },
    "scope": {
      "type": "string",
      "description": "The scope of your library.",
      "enum": ["api", "store", "shared"],
      "x-prompt": {
        "message": "What is the scope of this library?",
        "type": "list",
        "items": [
          {
            "value": "store",
            "label": "store"
          },
          {
            "value": "api",
            "label": "api"
          },
          {
            "value": "shared",
            "label": "shared"
          }
        ]
      }
    },
    "directory": {
      "type": "string",
      "description": ""
    }
  },
  "required": ["name"]
}
```

{% /tabitem %}
{% tabitem label="generator.ts" %}

```ts
// tools/recommended/src/generators/library/generator.ts
import { Tree } from '@nx/devkit';
import { Linter } from '@nx/eslint';
import { libraryGenerator as reactLibraryGenerator } from '@nx/react';
import { LibraryGeneratorSchema } from './schema';

export async function libraryGenerator(
  tree: Tree,
  options: LibraryGeneratorSchema
) {
  const callbackAfterFilesUpdated = await reactLibraryGenerator(tree, {
    ...options,
    tags: `scope:${options.scope}`,
    directory: options.directory || `${options.scope}/${options.name}`,
    linter: 'eslint',
    style: 'css',
    unitTestRunner: 'vitest',
  });

  return callbackAfterFilesUpdated;
}

export default libraryGenerator;
```

{% /tabitem %}
{% /tabs %}

We can check that the scope logic is being applied correctly by running the generator again and specifying a scope.

```shell
npx nx g @myorg/recommended:library test-library --scope=shared --dry-run
```

This should create the `test-library` in the `shared` folder.

## Configure tasks

You can also use your Nx plugin to configure how your tasks are run. Usually, organization focused plugins configure tasks by modifying the configuration files for each project. If you have developed your own tooling scripts for your organization, you may want to create an executor or infer tasks, but that process is covered in more detail in the tooling plugin tutorial.

Let's update our library generator to set the `clearMocks` property to `true` in the `vitest` configuration. First we'll run the `reactLibraryGenerator` and then we'll modify the created files.

```ts
// tools/recommended/src/generators/library/generator.ts
import { formatFiles, Tree, runTasksInSerial } from '@nx/devkit';
import { Linter } from '@nx/eslint';
import { libraryGenerator as reactLibraryGenerator } from '@nx/react';
import { LibraryGeneratorSchema } from './schema';

export async function libraryGenerator(
  tree: Tree,
  options: LibraryGeneratorSchema
) {
  const directory = options.directory || `${options.scope}/${options.name}`;

  const tasks = [];
  tasks.push(
    await reactLibraryGenerator(tree, {
      ...options,
      tags: `scope:${options.scope}`,
      directory,
      linter: 'eslint',
      style: 'css',
      unitTestRunner: 'vitest',
    })
  );

  updateViteConfiguration(tree, directory);
  await formatFiles(tree);

  return runTasksInSerial(...tasks);
}

function updateViteConfiguration(tree, directory) {
  // Read the vite configuration file
  let viteConfiguration =
    tree.read(`${directory}/vite.config.ts`)?.toString() || '';

  // Modify the configuration
  // This is done with a naive search and replace, but could be done in a more robust way using AST nodes.
  viteConfiguration = viteConfiguration.replace(
    `globals: true,`,
    `globals: true,\n  clearMocks:true,`
  );

  // Write the modified configuration back to the file
  tree.write(`${directory}/vite.config.ts`, viteConfiguration);
}

export default libraryGenerator;
```

We updated the generator to use some new helper functions from the Nx devkit. Here are a few functions you may find useful. See the [full API reference](/docs/reference/devkit) for all the options.

- [`runTasksInSerial`](/docs/reference/devkit/runTasksInSerial) - Allows you to collect many callbacks and return them all at the end of the generator.
- [`formatFiles`](/docs/reference/devkit/formatFiles) - Run Prettier on the repository
- [`readProjectConfiguration`](/docs/reference/devkit/readProjectConfiguration) - Get the calculated project configuration for a single project
- [`updateNxJson`](/docs/reference/devkit/updateNxJson) - Update the `nx.json` file

Now let's check to make sure that the `clearMocks` property is set correctly by the generator. First, we'll commit our changes so far. Then, we'll run the generator without the `--dry-run` flag so we can inspect the file contents.

```shell
git add .
git commit -am "library generator"
npx nx g @myorg/recommended:library store-test --scope=store
```

## Next steps

Now that we have a working library generator, here are some more topics you may want to investigate.

- [Generate files](/docs/extending-nx/creating-files) from EJS templates
- [Modify files](/docs/extending-nx/modifying-files) with string replacement or AST transformations

## Encourage adoption

Once you have a set of generators in place in your organization's plugin, the rest of the work is all communication. Let your developers know that the plugin is available and encourage them to use it. These are the most important points to communicate to your developers:

- Whenever there are multiple plugins that provide a generator with the same name, use the `recommended` version
- If there are repetitive or error prone processes that they identify, ask the plugin team to write a generator for that process

Now you can go through all the README files in the repository and replace any multiple step instructions with a single line calling a generator.

---
<!-- source: https://nx.dev/docs/extending-nx/project-graph-plugins.md -->
## Extending the Project Graph

The Project Graph is the representation of the source code in your repo. Projects can have files associated with them. Projects can have dependencies on each other.

One of the best features of Nx the ability to construct the project graph automatically by analyzing your source code. Currently, this works best within the JavaScript ecosystem, but it can be extended to other languages and technologies using plugins.

Project graph plugins are able to add new nodes or dependencies to the project graph. This allows you to extend the project graph with new projects and dependencies. The API is defined by two exported members, which are described below:

- [createNodesV2](#adding-new-nodes-to-the-project-graph): This tuple allows a plugin to tell Nx information about projects that are identified by a given file.
- [createDependencies](#adding-new-dependencies-to-the-project-graph): This function allows a plugin to tell Nx about dependencies between projects.

{% aside type="caution" title="Disable the Nx Daemon during development" %}
When developing project graph plugins, disable the [Nx Daemon](/docs/concepts/nx-daemon) by setting `NX_DAEMON=false`. The daemon caches your plugin code, so changes to your plugin won't be reflected until the daemon restarts.
{% /aside %}

## Adding plugins to workspace

You can register a plugin by adding it to the plugins array in `nx.json`:

```jsonc
// nx.json
{
  ...,
  "plugins": [
    "awesome-plugin"
  ]
}
```

## Adding new nodes to the project graph

You can add nodes to the project graph with [`createNodesV2`](/docs/reference/devkit/CreateNodesV2). This is the API that Nx uses under the hood to identify Nx projects coming from a `project.json` file or a `package.json` that's listed in a package manager's workspaces section.

{% aside type="note" title="CreateNodes API Versions" %}
Nx has evolved its plugin API over time. Different Nx versions call different `createNodes` exports (`createNodes` vs `createNodesV2`). If you need to support multiple Nx versions see the [CreateNodes Compatibility Guide](/docs/extending-nx/createnodes-compatibility).
{% /aside %}

### Identifying projects

Looking at the tuple, you can see that the first element is a file pattern. This is a glob pattern that Nx will use to find files in your workspace. The second element is a function that will be called for each file that matches the pattern. The function will be called with the path to the file and a context object. Your plugin can then return a set of projects and external nodes.

If a plugin identifies a project that is already in the project graph, it will be merged with the information that is already present. The builtin plugins that identify projects from `package.json` files and `project.json` files are ran after any plugins listed in `nx.json`, and as such will overwrite any configuration that was identified by them. In practice, this means that if a project has both a `project.json`, and a file that your plugin identified, the settings the plugin identified will be overwritten by the `project.json`'s contents.

Project nodes in the graph are considered to be the same if the project has the same root. If multiple plugins identify a project with the same root, the project will be merged. In doing so, the name that is already present in the graph is kept, and the properties below are shallowly merged. Any other properties are overwritten.

- `targets`
- `tags`
- `implicitDependencies`
- `generators`

Note: This is a shallow merge, so if you have a target with the same name in both plugins, the target from the second plugin will overwrite the target from the first plugin. Options, configurations, or any other properties within the target will be overwritten **_not_** merged.

#### Example (adding projects)

A simplified version of Nx built-in `project.json` plugin is shown below, which adds a new project to the project graph for each `project.json` file it finds. This should be exported from the entry point of your plugin, which is listed in `nx.json`

```typescript
// my-plugin/index.ts
import { createNodesFromFiles, readJsonFile } from '@nx/devkit';
import { dirname } from 'path';

export interface MyPluginOptions {}

export const createNodesV2: CreateNodesV2<MyPluginOptions> = [
  '**/project.json',
  async (configFiles, options, context) => {
    return await createNodesFromFiles(
      (configFile, options, context) =>
        createNodesInternal(configFile, options, context),
      configFiles,
      options,
      context
    );
  },
];

async function createNodesInternal(
  configFilePath: string,
  options: MyPluginOptions,
  context: CreateNodesContextV2
) {
  const projectConfiguration = readJsonFile(configFilePath);
  const root = dirname(configFilePath);

  // Project configuration to be merged into the rest of the Nx configuration
  return {
    projects: {
      [root]: projectConfiguration,
    },
  };
}
```

{% aside type="caution" title="Dynamic target configurations can't be migrated" %}

If you create targets for a project within a plugin's code, the Nx migration generators can not find that target configuration to update it. There are two ways to account for this:

1. Only create dynamic targets using executors that you own. This way you can update the configuration in both places when needed.
2. If you create a dynamic target for an executor you don't own, only define the `executor` property and instruct your users to define their options in the `targetDefaults` property of `nx.json`.

{% /aside %}

#### Example (extending projects / adding inferred targets)

When writing a plugin to add support for some tooling, it may need to add a target to an existing project. For example, our @nx/jest plugin adds a target to the project for running Jest tests. This is done by checking for the presence of a jest configuration file, and if it is present, adding a target to the project.

Most of Nx first party plugins are written to add a target to a given project based on the configuration files present for that project. The below example shows how a plugin could add a target to a project based on the presence of a `tsconfig.json` file.

```typescript
// my-plugin/index.ts
import { createNodesFromFiles, readJsonFile } from '@nx/devkit';
import { dirname } from 'path';

export interface MyPluginOptions {}

export const createNodesV2: CreateNodesV2<MyPluginOptions> = [
  '**/tsconfig.json',
  async (configFiles, options, context) => {
    return await createNodesFromFiles(
      (configFile, options, context) =>
        createNodesInternal(configFile, options, context),
      configFiles,
      options,
      context
    );
  },
];

async function createNodesInternal(
  configFilePath: string,
  options: MyPluginOptions,
  context: CreateNodesContextV2
) {
  const projectConfiguration = readJsonFile(configFilePath);
  const projectRoot = dirname(configFilePath);

  const isProject =
    existsSync(join(projectRoot, 'project.json')) ||
    existsSync(join(projectRoot, 'package.json'));
  if (!isProject) {
    return {};
  }

  return {
    projects: {
      [projectRoot]: {
        targets: {
          build: {
            command: `tsc -p ${fileName}`,
          },
        },
      },
    },
  };
}
```

By checking for the presence of a `project.json` or `package.json` file, the plugin can be more confident that the project it is modifying is an existing Nx project.

When extending an existing project, its important to consider how Nx will merge the returned project configurations. In general, plugins are run in the order they are listed in `nx.json`, and then Nx built-in plugins are run last. Plugins overwrite information that was identified by plugins that ran before them if a merge is not possible.

Nx considers two identified projects to be the same if and only if they have the same root. If two projects are identified with the same name, but different roots, there will be an error.

The logic for merging project declarations is as follows:

- `name`, `sourceRoot`, `projectType`, and any other top level properties which are a literal (e.g. not an array or object) are overwritten.
- `tags` are merged and deduplicated.
- `implicitDependencies` are merged, with dependencies from later plugins being appended to the end
- `targets` are merged, with special logic for the targets inside of them:
  - If the targets are deemed compatible (They use the same executor / command, or one of the two declarations does not specify an executor / command):
    - The `executor` or `command` remains the same
    - The `options` object is merged with the later plugin's options overwriting the earlier plugin's options. This is a shallow merge, so if a property is an object, the later plugin's object will overwrite the earlier plugin's object rather than merging the two.
    - The `configurations` object is merged, with the later plugin's configurations overwriting the earlier plugin's configurations. The options for each configuration are merged in the same way as the top level options.
    - `inputs` and `outputs` overwrite the earlier plugin's inputs and outputs.
  - If the targets are not deemed compatible, the later plugin's target will overwrite the earlier plugin's target.
- `generators` are merged. If both project configurations specify the same generator, those generators are merged.
- `namedInputs` are merged. If both project configurations specify the same named input, the later plugin's named input will overwrite the earlier plugin's named input. This is what allows overriding a named input from a plugin that ran earlier (e.g. in project.json).

### Adding external nodes

Additionally, plugins can add external nodes to the project graph. External nodes are nodes that are not part of the workspace, but are still part of the project graph. This is useful for things like npm packages, or other external dependencies that are not part of the workspace.

External nodes are identified by a unique name, and if plugins identify an external node with the same name, the external node will be **_overwritten_**. This is different from projects, where the properties are merged, but is handled this way as it should not be as common and there are less useful properties to merge.

## Adding new dependencies to the project graph

It's more common for plugins to create new dependencies. First-party code contained in the workspace is added to the project graph automatically. Whether your project contains TypeScript or say Java, both projects will be created in the same way. However, Nx does not know how to analyze Java sources, and that's what plugins can do.

The shape of the [`createDependencies`](/docs/reference/devkit/CreateDependencies) function follows:

```typescript
export type CreateDependencies<T> = (
  opts: T,
  context: CreateDependenciesContext
) => CandidateDependency[] | Promise<CandidateDependency[]>;
```

In the `createDependencies` function, you can analyze the files in the workspace and return a list of dependencies. It's up to the plugin to determine how to analyze the files. This should also be exported from the plugin's entry point, as listed in `nx.json`.

Within the `CreateDependenciesContext`, you have access to the graph's external nodes, the configuration of each project in the workspace, the `nx.json` configuration from the workspace, all files in the workspace, and files that have changed since the last invocation. It's important to utilize the `filesToProcess` parameter, as this will allow Nx to only reanalyze files that have changed since the last invocation, and reuse the information from the previous invocation for files that haven't changed.

`@nx/devkit` exports a function called `validateDependency` which can be used to validate a dependency. This function takes in a `CandidateDependency` and the `CreateDependenciesContext` and throws an error if the dependency is invalid. This function is called when the returned dependencies are merged with the existing project graph, but may be useful to call within your plugin to validate dependencies before returning them when debugging.

The dependencies can be of three types:

- Implicit
- Static
- Dynamic

### Implicit dependencies

An implicit dependency is not associated with any file, and can be created as follows:

```typescript
{
  source: 'existing-project',
  target: 'new-project',
  dependencyType: DependencyType.implicit,
}
```

Because an implicit dependency is not associated with any file, Nx doesn't know when it might change, so it will be recomputed every time.

### Static dependencies

Nx knows what files have changed since the last invocation. Only those files will be present in the provided `filesToProcess`. You can associate a dependency with a particular file (e.g., if that file contains an import).

```typescript
{
  source: 'existing-project',
  target: 'new-project',
  sourceFile: 'libs/existing-project/src/index.ts',
  dependencyType: DependencyType.static,
}
```

If a file hasn't changed since the last invocation, it doesn't need to be reanalyzed. Nx knows what dependencies are associated with what files, so it will reuse this information for the files that haven't changed.

### Dynamic dependencies

Dynamic dependencies are a special type of explicit dependencies. In contrast to standard `explicit` dependencies, they are only imported in the runtime under specific conditions.
A typical example would be lazy-loaded routes. Having separation between these two allows us to identify situations where static import breaks the lazy-loading.

```typescript
{
  source: 'existing-project',
  target: 'new-project',
  sourceFile: 'libs/existing-project/src/index.ts',
  dependencyType: DependencyType.dynamic,
}
```

### Example

{% aside type="note" title="More details" %}
Even though the plugin is written in JavaScript, resolving dependencies of different languages will probably be more easily written in their native language. Therefore, a common approach is to spawn a new process and communicate via IPC or `stdout`.
{% /aside %}

A small plugin that recognizes dependencies to projects in the current workspace which a referenced in another project's `package.json` file may look like so:

```typescript
// my-plugin/index.ts
export const createDependencies: CreateDependencies = (opts, ctx) => {
  const packageJsonProjectMap = new Map();
  const nxProjects = Object.values(ctx.projectsConfigurations);
  const results = [];
  for (const project of nxProjects) {
    const maybePackageJsonPath = join(project.root, 'package.json');
    if (existsSync(maybePackageJsonPath)) {
      const json = JSON.parse(maybePackageJsonPath);
      packageJsonProjectMap.set(json.name, project.name);
    }
  }
  for (const project of nxProjects) {
    const maybePackageJsonPath = join(project.root, 'package.json');
    if (existsSync(maybePackageJsonPath)) {
      const json = JSON.parse(maybePackageJsonPath);
      const deps = [...Object.keys(json.dependencies)];
      for (const dep of deps) {
        if (packageJsonProjectMap.has(dep)) {
          const newDependency = {
            source: project,
            target: packageJsonProjectMap.get(dep),
            sourceFile: maybePackageJsonPath,
            dependencyType: DependencyType.static,
          };
        }
        validateDependency(newDependency, ctx);
        results.push(newDependency);
      }
    }
  }
  return results;
};
```

Breaking down this example, we can see that it follows this flow:

1. Initializes an array to hold dependencies it locates
2. Builds a map of all projects in the workspace, mapping the name inside their package.json to their Nx project name.
3. Looks at the package.json files within the workspace and:
4. Checks if the dependency is another project
5. Builds a dependency from this information
6. Validates the dependency
7. Pushes it into the located dependency array
8. Returns the located dependencies

## Accepting plugin options

When looking at `createNodesV2`, and `createDependencies` you may notice a parameter called `options`. This is the first parameter for `createDependencies` or the second parameter for `createDependencies`.

By default, its typed as unknown. This is because it belongs to the plugin author. The `CreateNodes`, `CreateDependencies`, and `NxPluginV2` types all accept a generic parameter that allows you to specify the type of the options.

The options are read from `nx.json` when your plugin is specified as an object rather than just its module name.

As an example, the below `nx.json` file specifies a plugin called `my-plugin` and passes it an option called `tagName`.

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "my-plugin",
      "options": {
        "tagName": "plugin:my-plugin"
      }
    }
  ]
}
```

`my-plugin` could then consume these options to add a tag to each project it detected:

```typescript
// my-plugin/index.ts

import { createNodesFromFiles } from '@nx/devkit';
import { dirname } from 'path';

type MyPluginOptions = { tagName: string };

export const createNodesV2: CreateNodesV2<MyPluginOptions> = [
  '**/tsconfig.json',
  async (configFiles, options, context) => {
    return await createNodesFromFiles(
      (configFile, options, context) =>
        const root = dirname(configFile);

        return {
          projects: {
            [root]: {
              tags: options.tagName ? [options.tagName] : [],
            },
          },
        };
      configFiles,
      options,
      context
    );
  },
];
```

This functionality is available in Nx 17 or higher.

## Visualizing the project graph

You can then visualize the project graph as described [here](/docs/features/explore-graph). However, there is a cache that Nx uses to avoid recalculating the project graph as much as possible. As you develop your project graph plugin, it might be a good idea to set the following environment variable to disable the project graph cache: `NX_CACHE_PROJECT_GRAPH=false`.

<!-- TODO (@AgentEnder): update the nx-go-project-graph-plugin to v2 API and re-add this section -->
<!-- ## Example Project Graph Plugin

The [nrwl/nx-go-project-graph-plugin](https://github.com/nrwl/nx-go-project-graph-plugin) repo contains an example project graph plugin which adds [Go](https://golang.org/) dependencies to the Nx Project Graph! A similar approach can be used for other languages.

{% github-repository url="https://github.com/nrwl/nx-go-project-graph-plugin" /%} -->

---
<!-- source: https://nx.dev/docs/extending-nx/publish-plugin.md -->
## Publish Your Nx Plugin

In order to use your plugin in other workspaces or share it with the community, you will need to publish it to an npm registry. To publish your plugin follow these steps:

1. `nx nx-release-publish nx-cfonts`
2. Follow the prompts from npm.
3. That's it!

After that, you can then install your plugin like any other Nx plugin -

```shell
nx add nx-cfonts
```

## List your Nx plugin

Nx provides a utility (`nx list`) that lists both core and community plugins. You can submit your plugin to be added to this list, but it needs to meet a few criteria first:

- Run some kind of automated e2e tests in your repository
- Include `@nx/devkit` as a `dependency` in the plugin's `package.json`
- List a `repository.url` in the plugin's `package.json`

```jsonc
// package.json
{
  "repository": {
    "type": "git",
    "url": "https://github.com/nrwl/nx.git",
    "directory": "packages/web",
  },
}
```

{% aside type="caution" title="Unmaintained Plugins" %}
We reserve the right to remove unmaintained plugins from the registry. If the plugins become maintained again, they can be resubmitted to the registry.
{% /aside %}

Once those criteria are met, you can submit your plugin by following the steps below:

- Fork the [Nx repo](https://github.com/nrwl/nx/fork) (if you haven't already)
- Update the [`astro-docs/src/content/approved-community-plugins.json` file](https://github.com/nrwl/nx/blob/master/astro-docs/src/content/approved-community-plugins.json) with a new entry for your plugin that includes name, url and description
- Use the following commit message template: `chore(core): nx plugin submission [PLUGIN_NAME]`
- push your changes, and run `pnpm submit-plugin`

> The `pnpm submit-plugin` command automatically opens the GitHub pull request process with the correct template.

We will then verify the plugin, offer suggestions or merge the pull request!

---
<!-- source: https://nx.dev/docs/extending-nx/task-running-lifecycle.md -->
## Hook into the Task Running Lifecycle

Nx plugins can hook into the task running lifecycle to execute custom logic before and after tasks are run. This is useful for implementing custom analytics, environment validation, or any other pre/post processing that should happen when running tasks.

{% aside type="note" title="New API for deprecated custom task runners" %}
These task execution hooks are the new API that replaces the deprecated Custom Tasks Runners. This feature is available since Nx 20.4+. For information about migrating from Custom Tasks Runners to these hooks, see [Deprecating Custom Tasks Runner](/docs/reference/deprecated/custom-tasks-runner).
{% /aside %}

## Task execution hooks

Nx provides two hooks that plugins can register:

1. `preTasksExecution`: Runs before any tasks are executed
2. `postTasksExecution`: Runs after all tasks are executed

These hooks allow you to extend Nx functionality without affecting task execution or violating any invariants.

## Creating task execution hooks

To implement task execution hooks, create a plugin and export the `preTasksExecution` and/or `postTasksExecution` functions:

```typescript
// some-example-hooks.ts
// Example plugin with both pre and post execution hooks

// context contains workspaceRoot and nx.json configuration
export async function preTasksExecution(options: any, context) {
  // Run custom logic before tasks are executed
  console.log('About to run tasks!');

  // You can modify environment variables
  if (process.env.QA_ENV) {
    process.env.NX_SKIP_NX_CACHE = 'true';
  }

  // You can validate the environment
  if (!isEnvironmentValid()) {
    throw new Error('Environment is not set up correctly');
  }
}

// context contains workspaceRoot, nx.json configuration, and task results
export async function postTasksExecution(options: any, context) {
  // Run custom logic after tasks are executed
  console.log('All tasks have completed!');

  // You can access task results for analytics
  if (options.reportAnalytics) {
    await fetch(process.env.ANALYTICS_API, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(context.taskResults),
    });
  }
}

function isEnvironmentValid() {
  // Implement your validation logic
  return true;
}
```

## Configuring your plugin

Configure your plugin in `nx.json` by adding it to the `plugins` array:

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "my-nx-plugin",
      "options": {
        "reportAnalytics": true
      }
    }
  ]
}
```

The options you specify in the configuration will be passed to your hook functions.

## Maintaining state across command invocations

By default, every plugin initiates a long-running process, allowing you to maintain state across command invocations. This is particularly useful for gathering advanced analytics or providing cumulative feedback.

## Conditional execution

You can implement conditional logic in your hooks to control when they run:

```typescript
// some-example-hooks.ts
export async function preTasksExecution(options, context) {
  // Only run for specific environments
  if (process.env.RUNNER !== 'production') return;

  // Your pre-execution logic
}

export async function postTasksExecution(options, context) {
  // Only run for specific task types
  const hasAngularTasks = Object.keys(context.taskResults).some((taskId) =>
    taskId.includes('angular')
  );

  if (!hasAngularTasks) return;

  // Your post-execution logic
}
```

## Using `context.argv` to determine the command

The context object includes an `argv` property that contains the original CLI arguments used to invoke Nx. This allows you to distinguish between different execution modes and apply conditional logic.

### Context properties

Both `preTasksExecution` and `postTasksExecution` hooks receive a context object with the following properties:

```typescript
type PreTaskExecutionContext = {
  id: string;
  workspaceRoot: string;
  nxJsonConfiguration: NxJsonConfiguration;
  argv: string[]; // Original CLI arguments
};

type PostTasksExecutionContext = {
  id: string;
  workspaceRoot: string;
  nxJsonConfiguration: NxJsonConfiguration;
  taskResults: TaskResults;
  argv: string[]; // Original CLI arguments
  startTime: number;
  endTime: number;
};
```

### Example: Detecting command types

```typescript
export async function postTasksExecution(options, context) {
  // Check if running affected command
  if (context.argv.includes('affected')) {
    console.log('✅ Ran affected tasks');
  } else if (context.argv.includes('run-many')) {
    console.log('✅ Ran tasks for multiple projects');
  } else {
    console.log('✅ Ran task for specific project');
  }
}
```

### Example: conditional analytics based on command

```typescript
function isAffectedCommand(argv) {
  return argv.includes('affected');
}

function getTargetName(argv) {
  const targetIndex = argv.findIndex(
    (arg) => arg === '-t' || arg === '--target'
  );
  return targetIndex !== -1 ? argv[targetIndex + 1] : undefined;
}

export async function postTasksExecution(options, context) {
  const isAffected = isAffectedCommand(context.argv);
  const target = getTargetName(context.argv);

  // Send analytics with command context
  await sendAnalytics({
    executionId: context.id,
    commandType: isAffected ? 'affected' : 'direct',
    target: target,
    taskCount: Object.keys(context.taskResults).length,
    duration: context.endTime - context.startTime,
  });
}
```

### Common command patterns

- Direct execution: `nx build my-app` → `argv: ['node', '/path/to/nx', 'build', 'my-app']`
- Affected: `nx affected -t build test` → `argv: ['node', '/path/to/nx', 'affected', '-t', 'build', 'test']`
- Run many: `nx run-many -t build -p app1 app2` → `argv: ['node', '/path/to/nx', 'run-many', '-t', 'build', '-p', 'app1', 'app2']`

### Best practices for parsing argv

When working with `context.argv`, parse it defensively:

```typescript
// Bad - assumes structure
const target = context.argv[2];

// Good - searches for the flag
const targetIndex = context.argv.findIndex(
  (arg) => arg === '-t' || arg === '--target'
);
const target = targetIndex !== -1 ? context.argv[targetIndex + 1] : undefined;
```

## Best practices

1. **Keep hooks fast**: Hooks should execute quickly to avoid slowing down the task execution process
2. **Handle errors gracefully**: Ensure your hooks don't crash the entire execution pipeline
3. **Use environment variables** for configuration that needs to persist across tasks
4. **Leverage context data**: Use the context object to access relevant information about the workspace and task results
5. **Provide clear errors**: If throwing errors, make sure they are descriptive and actionable
6. **Parse argv defensively**: Don't assume the position of arguments; search for specific flags instead

---
<!-- source: https://nx.dev/docs/extending-nx/tooling-plugin.md -->
## Integrate a New Tool with a Tooling Plugin

Nx Plugins can be used to easily integrate a tool or framework into an Nx repository. If there is no plugin available for your favorite tool or framework, you can write your own.

We'll create a plugin that helps to integrate the _Astro_ framework. `Astro` is a JavaScript web framework optimized for building fast, content-driven websites. We'll call our plugin `nx-astro`.

To create a plugin in a brand new repository, use the `create-nx-plugin` command:

```shell
npx create-nx-plugin nx-astro
```

Skip the `create-*` package prompt, since we won't be creating a preset.

## Understand tooling configuration files

When integrating your tool into an Nx repository, you first need to have a clear understanding of how your tool works. Pay special attention to all the possible formats for configuration files, so that your plugin can process any valid configuration options.

For our `nx-astro` plugin, we'll read information from the `astro.config.mjs` or `astro.config.ts` file. We'll mainly be interested in the `srcDir`, `publicDir` and `outDir` properties specified in the `defineConfig` object. `srcDir` and `publicDir` define input files that are used in the build process and `outDir` defines what the build output will be created.

```js
// astro.config.mjs
import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({
  srcDir: './src',
  publicDir: './public',
  outDir: './dist',
});
```

## Create an inferred task

The easiest way for people integrate your tool into their repository is for them to use inferred tasks. When leveraging inferred tasks, all your users need to do is install your plugin and the tool configuration file to their projects. Your plugin will take care of registering tasks with Nx and setting up the correct caching settings.

Once the inferred task logic is written, we want to be able to automatically create a task for any project that has a `astro.config.*` file defined in the root of the project. We'll name the task based on our plugin configuration in the `nx.json` file:

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "nx-astro",
      "options": {
        "buildTargetName": "build",
        "devTargetName": "dev"
      }
    }
  ]
}
```

If the `astro.config.mjs` for a project looks like our example in the previous section, then the inferred configuration for the `build` task should look like this:

```json
{
  "command": "astro build",
  "cache": true,
  "inputs": [
    "{projectRoot}/astro.config.mjs",
    "{projectRoot}/src/**/*",
    "{projectRoot}/public/**/*",
    {
      "externalDependencies": ["astro"]
    }
  ],
  "outputs": ["{projectRoot}/dist"]
}
```

To create an inferred task, we need to export a `createNodesV2` function from the plugin's `index.ts` file. The entire file is shown below with inline comments to explain what is happening in each section.

{% aside type="note" title="Supporting Multiple Nx Versions" %}
Different Nx versions call different `createNodes` exports. If you need to support Nx versions before 21 see the [CreateNodes Compatibility Guide](/docs/extending-nx/createnodes-compatibility).
{% /aside %}

```ts
// src/index.ts
import {
  CreateNodesContextV2,
  CreateNodesV2,
  TargetConfiguration,
  createNodesFromFiles,
  joinPathFragments,
} from '@nx/devkit';
import { readdirSync, readFileSync } from 'fs';
import { dirname, join, resolve } from 'path';

// Expected format of the plugin options defined in nx.json
export interface AstroPluginOptions {
  buildTargetName?: string;
  devTargetName?: string;
}

// File glob to find all the configuration files for this plugin
const astroConfigGlob = '**/astro.config.{mjs,ts}';

// Entry function that Nx calls to modify the graph
export const createNodesV2: CreateNodesV2<AstroPluginOptions> = [
  astroConfigGlob,
  async (configFiles, options, context) => {
    return await createNodesFromFiles(
      (configFile, options, context) =>
        createNodesInternal(configFile, options, context),
      configFiles,
      options,
      context
    );
  },
];

async function createNodesInternal(
  configFilePath: string,
  options: AstroPluginOptions,
  context: CreateNodesContextV2
) {
  const projectRoot = dirname(configFilePath);

  // Do not create a project if package.json or project.json isn't there.
  const siblingFiles = readdirSync(join(context.workspaceRoot, projectRoot));
  if (
    !siblingFiles.includes('package.json') &&
    !siblingFiles.includes('project.json')
  ) {
    return {};
  }

  // Contents of the astro config file
  const astroConfigContent = readFileSync(
    resolve(context.workspaceRoot, configFilePath)
  ).toString();

  // Read config values using Regex.
  // There are better ways to read config values, but this works for the tutorial
  function getConfigValue(propertyName: string, defaultValue: string) {
    const result = new RegExp(`${propertyName}: '(.*)'`).exec(
      astroConfigContent
    );
    if (result && result[1]) {
      return result[1];
    }
    return defaultValue;
  }

  const srcDir = getConfigValue('srcDir', './src');
  const publicDir = getConfigValue('publicDir', './public');
  const outDir = getConfigValue('outDir', './dist');

  // Inferred task final output
  const buildTarget: TargetConfiguration = {
    command: `astro build`,
    options: { cwd: projectRoot },
    cache: true,
    inputs: [
      '{projectRoot}/astro.config.mjs',
      joinPathFragments('{projectRoot}', srcDir, '**', '*'),
      joinPathFragments('{projectRoot}', publicDir, '**', '*'),
      {
        externalDependencies: ['astro'],
      },
    ],
    outputs: [`{projectRoot}/${outDir}`],
  };
  const devTarget: TargetConfiguration = {
    command: `astro dev`,
    options: { cwd: projectRoot },
  };

  // Project configuration to be merged into the rest of the Nx configuration
  return {
    projects: {
      [projectRoot]: {
        targets: {
          [options.buildTargetName]: buildTarget,
          [options.devTargetName]: devTarget,
        },
      },
    },
  };
}
```

We'll test out this inferred task a little later in the tutorial.

Inferred tasks work well for getting users started using your tool quickly, but you can also provide users with [executors](/docs/extending-nx/local-executors), which are another way of encapsulating a task script for easy use in an Nx workspace. Without inferred tasks, executors must be explicitly configured for each task.

## Create an init generator

You'll want to create generators to automate the common coding tasks for developers that use your tool. The most obvious coding task is the initial setup of the plugin. We'll create an `init` generator to automatically register the `nx-astro` plugin and start inferring tasks.

If you create a generator named `init`, Nx will automatically run that generator when someone installs your plugin with the `nx add nx-astro` command. This generator should provide a good default set up for using your plugin. In our case, we need to register the plugin in the `nx.json` file.

To create the generator run the following command:

```shell
npx nx g generator src/generators/init
```

Then we can edit the `generator.ts` file to define the generator functionality:

```ts
// src/generators/init/generator.ts
import { formatFiles, readNxJson, Tree, updateNxJson } from '@nx/devkit';
import { InitGeneratorSchema } from './schema';

export async function initGenerator(tree: Tree, options: InitGeneratorSchema) {
  const nxJson = readNxJson(tree) || {};
  const hasPlugin = nxJson.plugins?.some((p) =>
    typeof p === 'string' ? p === 'nx-astro' : p.plugin === 'nx-astro'
  );
  if (!hasPlugin) {
    if (!nxJson.plugins) {
      nxJson.plugins = [];
    }
    nxJson.plugins = [
      ...nxJson.plugins,
      {
        plugin: 'nx-astro',
        options: {
          buildTargetName: 'build',
          devTargetName: 'dev',
        },
      },
    ];
  }
  updateNxJson(tree, nxJson);
  await formatFiles(tree);
}

export default initGenerator;
```

This will automatically add the plugin configuration to the `nx.json` file if the plugin is not already registered.

We need to remove the generated `name` option from the generator schema files so that the `init` generator can be executed without passing any arguments.

{% tabs syncKey="schema-file" %}
{% tabitem label="schema.d.ts" %}

```ts
// src/generators/init/schema.d.ts
export interface InitGeneratorSchema {}
```

{% /tabitem %}
{% tabitem label="schema.json" %}

```json
// src/generators/init/schema.json
{
  "$schema": "https://json-schema.org/schema",
  "$id": "Init",
  "title": "",
  "type": "object",
  "properties": {},
  "required": []
}
```

{% /tabitem %}
{% /tabs %}

## Create an application generator

Let's make one more generator to automatically create a simple Astro application. First we'll create the generator:

```shell
npx nx g generator src/generators/application
```

Then we'll update the `generator.ts` file to define the generator functionality:

```ts
// src/generators/application/generator.ts
import {
  addProjectConfiguration,
  formatFiles,
  generateFiles,
  Tree,
} from '@nx/devkit';
import * as path from 'path';
import { ApplicationGeneratorSchema } from './schema';

export async function applicationGenerator(
  tree: Tree,
  options: ApplicationGeneratorSchema
) {
  const projectRoot = `${options.name}`;
  addProjectConfiguration(tree, options.name, {
    root: projectRoot,
    projectType: 'application',
    sourceRoot: `${projectRoot}/src`,
    targets: {},
  });
  generateFiles(tree, path.join(__dirname, 'files'), projectRoot, options);
  await formatFiles(tree);
}

export default applicationGenerator;
```

The `generateFiles` function will use the template files in the `files` folder to add files to the generated project.

{% tabs %}
{% tabitem label="package.json__templ__" %}

```json
// src/generators/application/files/package.json__templ__
{
  "name": "<%= name %>",
  "dependencies": {}
}
```

{% /tabitem %}
{% tabitem label="astro.config.mjs" %}

```js
// src/generators/application/files/astro.config.mjs
import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({});
```

{% /tabitem %}
{% tabitem label="index.astro" %}

```astro
// src/generators/application/files/src/pages/index.astro
---
// Welcome to Astro! Everything between these triple-dash code fences
// is your "component frontmatter". It never runs in the browser.
console.log('This runs in your terminal, not the browser!');
---
<!-- Below is your "component template." It's just HTML, but with
    some magic sprinkled in to help you build great templates. -->
<html>
  <body>
    <h1>Hello, World!</h1>
  </body>
</html>
<style>
  h1 {
    color: orange;
  }
</style>
```

{% /tabitem %}
{% tabitem label="robots.txt" %}

```json
// src/generators/application/files/public/robots.txt
# Example: Allow all bots to scan and index your site.
# Full syntax: https://developers.google.com/search/docs/advanced/robots/create-robots-txt
User-agent: *
Allow: /
```

{% /tabitem %}
{% /tabs %}

The generator options in the schema files can be left unchanged.

## Test your plugin

The plugin is generated with a default e2e test (`e2e/src/nx-astro.spec.ts`) that:

1. Launches a local npm registry with Verdaccio
2. Publishes the current version of the `nx-astro` plugin to the local registry
3. Creates an empty Nx workspace
4. Installs `nx-astro` in the Nx workspace

Let's update the e2e tests to make sure that the inferred tasks are working correctly. We'll update the `beforeAll` function to use `nx add` to add the `nx-astro` plugin and call our `application` generator.

```ts
// e2e/src/nx-astro.spec.ts
beforeAll(() => {
  projectDirectory = createTestProject();

  // The plugin has been built and published to a local registry in the jest globalSetup
  // Install the plugin built with the latest source code into the test repo
  execSync('npx nx add nx-astro@e2e', {
    cwd: projectDirectory,
    stdio: 'inherit',
    env: process.env,
  });
  execSync('npx nx g nx-astro:application my-lib', {
    cwd: projectDirectory,
    stdio: 'inherit',
    env: process.env,
  });
});
```

Now we can add a new test that verifies the inferred task configuration:

```ts
// e2e/src/nx-astro.spec.ts
it('should infer tasks', () => {
  const projectDetails = JSON.parse(
    execSync('nx show project my-lib --json', {
      cwd: projectDirectory,
    }).toString()
  );

  expect(projectDetails).toMatchObject({
    name: 'my-lib',
    root: 'my-lib',
    sourceRoot: 'my-lib/src',
    targets: {
      build: {
        cache: true,
        executor: 'nx:run-commands',
        inputs: [
          '{projectRoot}/astro.config.mjs',
          '{projectRoot}/src/**/*',
          '{projectRoot}/public/**/*',
          {
            externalDependencies: ['astro'],
          },
        ],
        options: {
          command: 'astro build',
          cwd: 'my-lib',
        },
        outputs: ['{projectRoot}/./dist'],
      },
      dev: {
        executor: 'nx:run-commands',
        options: {
          command: 'astro dev',
          cwd: 'my-lib',
        },
      },
    },
  });
});
```

## Next steps

Now that you have a working plugin, here are a few other topics you may want to investigate:

- [Publish your Nx plugin](/docs/extending-nx/publish-plugin) to npm and the Nx plugin registry
- [Write migration generators](/docs/extending-nx/migration-generators) to automatically account for breaking changes
- [Create a preset](/docs/extending-nx/create-preset) to scaffold out an entire new repository


# Technologies

---
<!-- source: https://nx.dev/docs/technologies.md -->
## Technologies

Guides and API references for all supported technologies.

{% index_page_cards path="technologies" /%}

---
<!-- source: https://nx.dev/docs/technologies/angular.md -->
## Angular

{% index_page_cards path="technologies/angular" /%}

---
<!-- source: https://nx.dev/docs/technologies/angular/angular-rsbuild.md -->
## Angular with Rsbuild

{% index_page_cards path="technologies/angular/angular-rsbuild" /%}

---
<!-- source: https://nx.dev/docs/technologies/angular/angular-rsbuild/create-server.md -->
## createServer - @nx/angular-rsbuild/ssr

```shell
import { createServer } from '@nx/angular-rsbuild/ssr';
```

The `createServer` function is used to setup Angular `CommonEngine` using an `express` server. It takes the bootstrap function as an argument, which is the function that bootstraps the Angular server application. This is usually` main.server.ts`. It returns `RsbuildAngularServer` which contains the server instance to allow further modifications as well as the listen method to start the server.

```ts
function createServer(bootstrap: any): RsbuildAngularServer;
```

---

## Examples

{% tabs %}
{% tabitem label="Standard Express Server Usage" %}
The following example shows how to create a standard express server:

```ts
// myapp/src/server.ts
import { createServer } from '@nx/angular-rsbuild/ssr';
import bootstrap from './main.server';

const server = createServer(bootstrap);

/** Add your custom server logic here
 *
 * For example, you can add a custom static file server:
 *
 * server.app.use('/static', express.static(staticFolder));
 *
 * Or add additional api routes:
 *
 * server.app.get('/api/hello', (req, res) => {
 *   res.send('Hello World!');
 * });
 *
 * Or add additional middleware:
 *
 * server.app.use((req, res, next) => {
 *   res.send('Hello World!');
 * });
 */

server.listen();
```

{% /tabitem %}
{% /tabs %}

---

## RsbuildAngularServer

```ts
export interface RsbuildAngularServer {
  app: express.Express;
  listen: (port?: number) => void;
}
```

---

### `app`

`express.Express`
The express application instance.

### `listen`

`(port?: number) => void`
Starts the express application on the specified port. If no port is provided, the default port (4000) is used.

---
<!-- source: https://nx.dev/docs/technologies/angular/angular-rsbuild/introduction.md -->
## Angular Rsbuild Plugin for Nx

The `@nx/angular-rsbuild` package provides configuration utilities for building Angular applications with [Rsbuild](https://rsbuild.dev). Rsbuild is built on top of Rspack and offers a streamlined development experience with fast builds and hot module replacement.

## Requirements

The `@nx/angular-rsbuild` plugin supports the following package versions.

| Package         | Supported Versions                                                                        |
| --------------- | ----------------------------------------------------------------------------------------- |
| `@rsbuild/core` | ^1.1.0                                                                                    |
| `@angular/core` | See [Angular version matrix](/docs/technologies/angular/guides/angular-nx-version-matrix) |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

## Usage

```shell
import { createConfig } from '@nx/angular-rsbuild';
```

The `createConfig` function is used to create an Rsbuild configuration object setup for Angular applications.

It takes an optional `RsbuildConfig` object as an argument, which allows for customization of the Rsbuild configuration.

```ts
async function createConfig(
  defaultOptions: {
    options: PluginAngularOptions;
    rsbuildConfigOverrides?: Partial<RsbuildConfig>;
  },
  configurations: Record<
    string,
    {
      options: Partial<PluginAngularOptions>;
      rsbuildConfigOverrides?: Partial<RsbuildConfig>;
    }
  > = {},
  configEnvVar = 'NGRS_CONFIG'
);
```

---

## Examples

{% tabs %}

{% tabitem label="Server-Side Rendering (SSR)" %}
The following example shows how to create a configuration for a SSR application:

```ts
// myapp/rsbuild.config.ts
import { createConfig } from '@nx/angular-rsbuild';

export default createConfig({
  options: {
    browser: './src/main.ts',
    server: './src/main.server.ts',
    ssrEntry: './src/server.ts',
  },
});
```

{% /tabitem %}

{% tabitem label="Client-Side Rendering (CSR)" %}
The following example shows how to create a configuration for a CSR application:

```ts
// myapp/rsbuild.config.ts
import { createConfig } from '@nx/angular-rsbuild';

export default createConfig({
  options: {
    browser: './src/main.ts',
  },
});
```

{% /tabitem %}

{% tabitem label="Modify Rsbuild Configuration" %}
The following example shows how to modify the base Rsbuild configuration:

```ts
// myapp/rsbuild.config.ts
import { createConfig } from '@nx/angular-rsbuild';

export default createConfig({
  options: {
    browser: './src/main.ts',
    server: './src/main.server.ts',
    ssrEntry: './src/server.ts',
  },
  rsbuildConfigOverrides: {
    mode: 'development',
  },
});
```

{% /tabitem %}

{% tabitem label="File Replacements" %}
The following example shows how to use file replacements:

```ts
// myapp/rsbuild.config.ts
import { createConfig } from '@nx/angular-rsbuild';

export default createConfig({
  options: {
    browser: './src/main.ts',
    server: './src/main.server.ts',
    ssrEntry: './src/server.ts',
    fileReplacements: [
      {
        replace: './src/environments/environment.ts',
        with: './src/environments/environment.prod.ts',
      },
    ],
  },
});
```

{% /tabitem %}

{% /tabs %}

---

## PluginAngularOptions

The `PluginAngularOptions` object is an object that contains the following properties:

```ts
export interface PluginAngularOptions extends PluginUnsupportedOptions {
  aot?: boolean;
  assets?: AssetElement[];
  browser?: string;
  commonChunk?: boolean;
  devServer?: DevServerOptions;
  extractLicenses?: boolean;
  fileReplacements?: FileReplacement[];
  index?: IndexElement;
  inlineStyleLanguage?: InlineStyleLanguage;
  namedChunks?: boolean;
  optimization?: boolean | OptimizationOptions;
  outputHashing?: OutputHashing;
  outputPath?:
    | string
    | (Required<Pick<OutputPath, 'base'>> & Partial<OutputPath>);
  polyfills?: string[];
  root?: string;
  scripts?: ScriptOrStyleEntry[];
  server?: string;
  skipTypeChecking?: boolean;
  sourceMap?: boolean | Partial<SourceMap>;
  ssr?:
    | boolean
    | {
        entry: string;
        experimentalPlatform?: 'node' | 'neutral';
      };
  stylePreprocessorOptions?: StylePreprocessorOptions;
  styles?: ScriptOrStyleEntry[];
  tsConfig?: string;
  useTsProjectReferences?: boolean;
  vendorChunk?: boolean;
}

export interface DevServerOptions extends DevServerUnsupportedOptions {
  port?: number;
  ssl?: boolean;
  sslKey?: string;
  sslCert?: string;
  proxyConfig?: string;
}

export interface OptimizationOptions {
  scripts?: boolean;
  styles?: boolean;
  fonts?: boolean;
}

export type OutputHashing = 'none' | 'all' | 'media' | 'bundles';
export type HashFormat = {
  chunk: string;
  extract: string;
  file: string;
  script: string;
};

export interface OutputPath {
  base: string;
  browser: string;
  server: string;
  media: string;
}

export type AssetExpandedDefinition = {
  glob: string;
  input: string;
  ignore?: string[];
  output?: string;
};
export type AssetElement = AssetExpandedDefinition | string;
export type NormalizedAssetElement = AssetExpandedDefinition & {
  output: string;
};
export type ScriptOrStyleEntry =
  | string
  | {
      input: string;
      bundleName?: string;
      inject?: boolean;
    };
export type GlobalEntry = {
  name: string;
  files: string[];
  initial: boolean;
};
export type IndexExpandedDefinition = {
  input: string;
  output?: string;
  preloadInitial?: boolean;
};
export type IndexElement = IndexExpandedDefinition | string | false;
export type IndexHtmlTransform = (content: string) => Promise<string>;
export type NormalizedIndexElement =
  | (IndexExpandedDefinition & {
      insertionOrder: [string, boolean][];
      transformer: IndexHtmlTransform | undefined;
    })
  | false;

export interface SourceMap {
  scripts: boolean;
  styles: boolean;
  hidden: boolean;
  vendor: boolean;
}

export type InlineStyleExtension = 'css' | 'scss' | 'sass' | 'less';
export interface FileReplacement {
  replace: string;
  with: string;
}
export interface StylePreprocessorOptions {
  includePaths?: string[];
  sass?: Sass;
}
export interface Sass {
  fatalDeprecations?: DeprecationOrId[];
  futureDeprecations?: DeprecationOrId[];
  silenceDeprecations?: DeprecationOrId[];
}
```

---

### aot

`boolean` `default: true`
Enables or disables Ahead-of-Time compilation for Angular applications.

### assets

`AssetElement[]`
Array of static assets to include in the build output. Can be either a string path or an object with glob patterns.

### browser

`string`
The entry point file for the browser bundle (e.g., 'src/main.ts').

### commonChunk

`boolean` `default: true`
Controls whether to create a separate bundle containing shared code between multiple chunks.

### devServer

`DevServerOptions`
RsbuildConfig options for the development server including port, SSL settings, and proxy configuration.

### extractLicenses

`boolean` `default: false`
When true, extracts all license information from dependencies into a separate file.

### fileReplacements

`FileReplacement[]`
List of files to be replaced during the build process, typically used for environment-specific configurations.

### index

`IndexElement`
Configuration for the index.html file. Can be a string path, an object with specific settings, or false to disable.

### inlineStyleLanguage

`InlineStyleLanguage`
Specifies the default language to use for inline styles in components.

### namedChunks

`boolean` `default: true`
When true, generates named chunks instead of numerical IDs.

### optimization

`boolean | OptimizationOptions` `default: true`
Controls build optimization settings for scripts, styles, and fonts.

### outputHashing

`OutputHashing` `default: 'none'`
Defines the hashing strategy for output files. Can be 'none', 'all', 'media', or 'bundles'.

### outputPath

`string | OutputPath`
Specifies the output directory for built files. Can be a string or an object defining paths for browser, server, and media files.

### polyfills

`string[]`
Array of polyfill files to include in the build.

### root

`string`
The root directory of the project where the rsbuild.config.ts file is located.

### scripts

`ScriptOrStyleEntry[]`
Array of global scripts to include in the build, with options for bundling and injection.

### server

`string`
The entry point file for the server bundle in SSR applications.

### skipTypeChecking

`boolean` `default: false`
When true, skips TypeScript type checking during the build process.

### sourceMap

`boolean | Partial<SourceMap>` `default: true`
Controls generation of source maps for debugging. Can be boolean or detailed configuration object.

### ssr

`boolean | { entry: string; experimentalPlatform?: 'node' | 'neutral' }`
Configuration for Server-Side Rendering. Can be boolean or object with specific SSR settings.

### stylePreprocessorOptions

`StylePreprocessorOptions`
Options for style preprocessors, including include paths and Sass-specific configurations.

### styles

`ScriptOrStyleEntry[]`
Array of global styles to include in the build, with options for bundling and injection.

### tsConfig

`string`
Path to the TypeScript configuration file.

### useTsProjectReferences

`boolean` `default: false`
Enables usage of TypeScript project references.

### vendorChunk

`boolean` `default: true`
When true, creates a separate bundle for vendor (third-party) code.

---
<!-- source: https://nx.dev/docs/technologies/angular/angular-rspack.md -->
## Angular with Rspack

{% index_page_cards path="technologies/angular/angular-rspack" /%}

---
<!-- source: https://nx.dev/docs/technologies/angular/angular-rspack-compiler.md -->
## Angular Rspack Compiler

{% index_page_cards path="technologies/angular/angular-rspack-compiler" /%}

---
<!-- source: https://nx.dev/docs/technologies/angular/angular-rspack-compiler/introduction.md -->
## Angular Rspack Compiler

Compilation utilities for Angular with Rspack and Rsbuild.

---
<!-- source: https://nx.dev/docs/technologies/angular/angular-rspack/create-config.md -->
## createConfig - @nx/angular-rspack

```shell
import { createConfig } from '@nx/angular-rspack';
```

The `createConfig` function is used to create an Rspack configuration object setup for Angular applications.

It takes an optional `Configuration` object as an argument, which allows for customization of the Rspack configuration.

```ts
async function createConfig(
  defaultOptions: {
    options: AngularRspackPluginOptions;
    rspackConfigOverrides?: Partial<Configuration>;
  },
  configurations: Record<
    string,
    {
      options: Partial<AngularRspackPluginOptions>;
      rspackConfigOverrides?: Partial<Configuration>;
    }
  > = {},
  configEnvVar = 'NGRS_CONFIG'
);
```

---

## Examples

{% tabs %}

{% tabitem label="Server-Side Rendering (SSR)" %}
The following example shows how to create a configuration for a SSR application:

```ts
// myapp/rspack.config.ts
import { createConfig } from '@nx/angular-rspack';

export default createConfig({
  options: {
    browser: './src/main.ts',
    server: './src/main.server.ts',
    ssrEntry: './src/server.ts',
  },
});
```

{% /tabitem %}

{% tabitem label="Client-Side Rendering (CSR)" %}
The following example shows how to create a configuration for a CSR application:

```ts
// myapp/rspack.config.ts
import { createConfig } from '@nx/angular-rspack';

export default createConfig({
  options: {
    browser: './src/main.ts',
  },
});
```

{% /tabitem %}

{% tabitem label="Modify Rspack Configuration" %}
The following example shows how to modify the base Rspack configuration:

```ts
// myapp/rspack.config.ts
import { createConfig } from '@nx/angular-rspack';

export default createConfig({
  options: {
    browser: './src/main.ts',
    server: './src/main.server.ts',
    ssrEntry: './src/server.ts',
  },
  rspackConfigOverrides: {
    mode: 'development',
  },
});
```

{% /tabitem %}

{% tabitem label="File Replacements" %}
The following example shows how to use file replacements:

```ts
// myapp/rspack.config.ts
import { createConfig } from '@nx/angular-rspack';

export default createConfig({
  options: {
    browser: './src/main.ts',
    server: './src/main.server.ts',
    ssrEntry: './src/server.ts',
    fileReplacements: [
      {
        replace: './src/environments/environment.ts',
        with: './src/environments/environment.prod.ts',
      },
    ],
  },
});
```

{% /tabitem %}

{% /tabs %}

---

## AngularRspackPluginOptions

The `AngularRspackPluginOptions` object is an object that contains the following properties:

```ts
export interface AngularRspackPluginOptions extends PluginUnsupportedOptions {
  aot?: boolean;
  assets?: AssetElement[];
  browser?: string;
  commonChunk?: boolean;
  devServer?: DevServerOptions;
  extractLicenses?: boolean;
  fileReplacements?: FileReplacement[];
  index?: IndexElement;
  inlineStyleLanguage?: InlineStyleLanguage;
  namedChunks?: boolean;
  optimization?: boolean | OptimizationOptions;
  outputHashing?: OutputHashing;
  outputPath?:
    | string
    | (Required<Pick<OutputPath, 'base'>> & Partial<OutputPath>);
  polyfills?: string[];
  root?: string;
  scripts?: ScriptOrStyleEntry[];
  server?: string;
  skipTypeChecking?: boolean;
  sourceMap?: boolean | Partial<SourceMap>;
  ssr?:
    | boolean
    | {
        entry: string;
        experimentalPlatform?: 'node' | 'neutral';
      };
  stylePreprocessorOptions?: StylePreprocessorOptions;
  styles?: ScriptOrStyleEntry[];
  tsConfig?: string;
  useTsProjectReferences?: boolean;
  vendorChunk?: boolean;
}

export interface DevServerOptions extends DevServerUnsupportedOptions {
  port?: number;
  ssl?: boolean;
  sslKey?: string;
  sslCert?: string;
  proxyConfig?: string;
}

export interface OptimizationOptions {
  scripts?: boolean;
  styles?: boolean;
  fonts?: boolean;
}

export type OutputHashing = 'none' | 'all' | 'media' | 'bundles';
export type HashFormat = {
  chunk: string;
  extract: string;
  file: string;
  script: string;
};

export interface OutputPath {
  base: string;
  browser: string;
  server: string;
  media: string;
}

export type AssetExpandedDefinition = {
  glob: string;
  input: string;
  ignore?: string[];
  output?: string;
};
export type AssetElement = AssetExpandedDefinition | string;
export type NormalizedAssetElement = AssetExpandedDefinition & {
  output: string;
};
export type ScriptOrStyleEntry =
  | string
  | {
      input: string;
      bundleName?: string;
      inject?: boolean;
    };
export type GlobalEntry = {
  name: string;
  files: string[];
  initial: boolean;
};
export type IndexExpandedDefinition = {
  input: string;
  output?: string;
  preloadInitial?: boolean;
};
export type IndexElement = IndexExpandedDefinition | string | false;
export type IndexHtmlTransform = (content: string) => Promise<string>;
export type NormalizedIndexElement =
  | (IndexExpandedDefinition & {
      insertionOrder: [string, boolean][];
      transformer: IndexHtmlTransform | undefined;
    })
  | false;

export interface SourceMap {
  scripts: boolean;
  styles: boolean;
  hidden: boolean;
  vendor: boolean;
}

export type InlineStyleExtension = 'css' | 'scss' | 'sass' | 'less';
export interface FileReplacement {
  replace: string;
  with: string;
}
export interface StylePreprocessorOptions {
  includePaths?: string[];
  sass?: Sass;
}
export interface Sass {
  fatalDeprecations?: DeprecationOrId[];
  futureDeprecations?: DeprecationOrId[];
  silenceDeprecations?: DeprecationOrId[];
}
```

---

### aot

`boolean` `default: true`
Enables or disables Ahead-of-Time compilation for Angular applications.

### assets

`AssetElement[]`
Array of static assets to include in the build output. Can be either a string path or an object with glob patterns.

### browser

`string`
The entry point file for the browser bundle (e.g., 'src/main.ts').

### commonChunk

`boolean` `default: true`
Controls whether to create a separate bundle containing shared code between multiple chunks.

### devServer

`DevServerOptions`
Configuration options for the development server including port, SSL settings, and proxy configuration.

### extractLicenses

`boolean` `default: false`
When true, extracts all license information from dependencies into a separate file.

### fileReplacements

`FileReplacement[]`
List of files to be replaced during the build process, typically used for environment-specific configurations.

### index

`IndexElement`
Configuration for the index.html file. Can be a string path, an object with specific settings, or false to disable.

### inlineStyleLanguage

`InlineStyleLanguage`
Specifies the default language to use for inline styles in components.

### namedChunks

`boolean` `default: true`
When true, generates named chunks instead of numerical IDs.

### optimization

`boolean | OptimizationOptions` `default: true`
Controls build optimization settings for scripts, styles, and fonts.

### outputHashing

`OutputHashing` `default: 'none'`
Defines the hashing strategy for output files. Can be 'none', 'all', 'media', or 'bundles'.

### outputPath

`string | OutputPath`
Specifies the output directory for built files. Can be a string or an object defining paths for browser, server, and media files.

### polyfills

`string[]`
Array of polyfill files to include in the build.

### root

`string`
The root directory of the project where the rspack.config.ts file is located.

### scripts

`ScriptOrStyleEntry[]`
Array of global scripts to include in the build, with options for bundling and injection.

### server

`string`
The entry point file for the server bundle in SSR applications.

### skipTypeChecking

`boolean` `default: false`
When true, skips TypeScript type checking during the build process.

### sourceMap

`boolean | Partial<SourceMap>` `default: true`
Controls generation of source maps for debugging. Can be boolean or detailed configuration object.

### ssr

`boolean | { entry: string; experimentalPlatform?: 'node' | 'neutral' }`
Configuration for Server-Side Rendering. Can be boolean or object with specific SSR settings.

### stylePreprocessorOptions

`StylePreprocessorOptions`
Options for style preprocessors, including include paths and Sass-specific configurations.

### styles

`ScriptOrStyleEntry[]`
Array of global styles to include in the build, with options for bundling and injection.

### tsConfig

`string`
Path to the TypeScript configuration file.

### useTsProjectReferences

`boolean` `default: false`
Enables usage of TypeScript project references.

### vendorChunk

`boolean` `default: true`
When true, creates a separate bundle for vendor (third-party) code.

---
<!-- source: https://nx.dev/docs/technologies/angular/angular-rspack/create-server.md -->
## createServer - @nx/angular-rspack/ssr

```shell
import { createServer } from '@nx/angular-rspack/ssr';
```

The `createServer` function is used to setup Angular `CommonEngine` using an `express` server.
It takes the bootstrap function as an argument, which is the function that bootstraps the Angular server application.
This is usually `main.server.ts`. It returns `RsbuildAngularServer` which contains the server instance to allow further modifications as well as the listen method to start the server.

```ts
function createServer(
  bootstrap: any,
  opts?: RspackAngularServerOptions
): RspackAngularServer;
```

---

## Examples

{% tabs %}
{% tabitem label="Standard Express Server Usage" %}
The following example shows how to create a standard express server:

```ts
// myapp/src/server.ts
import { createServer } from '@nx/angular-rspack/ssr';
import bootstrap from './main.server';

const server = createServer(bootstrap);

/** Add your custom server logic here
 *
 * For example, you can add a custom static file server:
 *
 * server.app.use('/static', express.static(staticFolder));
 *
 * Or add additional api routes:
 *
 * server.app.get('/api/hello', (req, res) => {
 *   res.send('Hello World!');
 * });
 *
 * Or add additional middleware:
 *
 * server.app.use((req, res, next) => {
 *   res.send('Hello World!');
 * });
 */

server.listen();
```

{% /tabitem %}
{% /tabs %}

---

## RspackAngularServer

```ts
export interface RspackAngularServer {
  app: express.Express;
  listen: (port?: number) => void;
}
```

---

### `app`

`express.Express`
The express application instance.

### `listen`

`(port?: number) => void`
Starts the express application on the specified port. If no port is provided, the default port (4000) is used.

---

## RspackAngularServerOptions

```ts
export interface RspackAngularServerOptions {
  serverDistFolder?: string;
  browserDistFolder?: string;
  indexHtml?: string;
}
```

---

### `serverDistFolder`

`string`
The folder where the server bundle is located. Defaults to the `dist/server` folder.

### `browserDistFolder`

`string`
The folder where the browser bundle is located. Defaults to the `dist/browser` folder.

### `indexHtml`

`string`
The path to the index.html file. Defaults to the `index.html` file in the `browserDistFolder`.

---
<!-- source: https://nx.dev/docs/technologies/angular/angular-rspack/guides.md -->
## Guides

{% index_page_cards path="technologies/angular/angular-rspack/guides" /%}

---
<!-- source: https://nx.dev/docs/technologies/angular/angular-rspack/guides/getting-started.md -->
## Getting Started - Angular Rspack

Walk you through setting up a new Angular Rspack application in Nx. By the end of this guide, you will have a new Angular application with Rspack configured.

There are two paths you can follow to get started with Angular Rspack in Nx:

1. Create a new Nx Workspace with preconfigured Angular Rspack application
2. Add an existing Angular Rspack application to an Nx Workspace

## Create a new Nx Workspace with preconfigured Angular Rspack application

To create a new Nx Workspace with a preconfigured Angular Rspack application, run the following command:

{% tabs %}
{% tabitem label="Client-Side Rendering (CSR)" %}

```shell frame="terminal" title="npx create-nx-workspace myorg" meta="{ranges:''}"
// filename: ~/

NX   Let's create a new workspace [https://nx.dev/getting-started/intro]

✔ Which stack do you want to use? · angular
✔ Integrated monorepo, or standalone project? · integrated
✔ Application name · myorg
✔ Which bundler would you like to use? · rspack
✔ Default stylesheet format · css
✔ Do you want to enable Server-Side Rendering (SSR)? · No
✔ Which unit test runner would you like to use? · vitest
✔ Test runner to use for end to end (E2E) tests · playwright

NX   Creating your v20.8.0 workspace.
```

{% /tabitem %}
{% tabitem label="Server-Side Rendering (SSR)" %}

```shell frame="terminal" title="npx create-nx-workspace myorg" meta="{ranges:''}"
// filename: ~/

NX   Let's create a new workspace [https://nx.dev/getting-started/intro]

✔ Which stack do you want to use? · angular
✔ Integrated monorepo, or standalone project? · integrated
✔ Application name · myorg
✔ Which bundler would you like to use? · rspack
✔ Default stylesheet format · css
✔ Do you want to enable Server-Side Rendering (SSR)? · Yes
✔ Which unit test runner would you like to use? · vitest
✔ Test runner to use for end to end (E2E) tests · playwright

NX   Creating your v20.8.0 workspace.
```

{% /tabitem %}
{% /tabs %}

This command will create a new Nx Workspace with an Angular Rspack application in the `myorg` directory.

## Add an existing Angular Rspack application to an Nx Workspace

To add an existing Angular Rspack application to an Nx Workspace, run the following command:

{% aside type="tip" title="Minimum Nx Version" %}

The minimum Nx version required to add an Angular Rspack application to an Nx Workspace is `20.6.1`.
If you are using an older version of Nx, run `npx nx migrate` to migrate your workspace to the latest version.

You can learn more about Nx migrations [here](/docs/features/automate-updating-dependencies).

{% /aside %}

{% tabs %}
{% tabitem label="Client-Side Rendering (CSR)" %}

```shell
npx nx g @nx/angular:app myapp --bundler=rspack
```

{% /tabitem %}
{% tabitem label="Server-Side Rendering (SSR)" %}

```shell
npx nx g @nx/angular:app myapp --bundler=rspack --ssr
```

{% /tabitem %}
{% /tabs %}

This command will add an Angular Rspack application to the `myapp` directory.

## Working with the Angular Rspack application

After generating the application, you will notice the following:

- A `rspack.config.ts` file in the root of the project
- The `project.json` file does not have a `targets.build` or `targets.serve` target

The `rspack.config.ts` file is a configuration file for Rspack. It contains the configuration options for Rspack and for Angular Rspack a helper [createConfig](/docs/technologies/angular/angular-rspack/create-config)
function is used to map the options you would expect to set in the `project.json` or `angular.json` files to the Rspack configuration.

The `project.json` file does not contain the `targets.build` or `targets.serve` targets because Angular Rspack uses Nx [Inferred Tasks](/docs/concepts/inferred-tasks) to build and serve your application with Rspack.

## Building your Angular Rspack application

To build your Angular Rspack application, run the following command:

```shell
npx nx build myapp
```

This command will build your Angular Rspack application and output the results to the `dist/browser` directory.  
If you are using the Angular Rspack application with Server-Side Rendering (SSR), the `dist/server` directory will contain the server files. The same `nx build` command will build both the client and server files.

## Serving your Angular Rspack application

To serve your Angular Rspack application, run the following command:

```shell
npx nx serve myapp
```

This command will serve your Angular Rspack application.  
For Client-Side Rendering (CSR) applications, the default port is `4200`. You can visit the application by navigating to `http://localhost:4200` in your browser.

For Server-Side Rendering (SSR) applications, the default port is `4000`. You can visit the application by navigating to `http://localhost:4000` in your browser.

HMR is enabled by default so you can make changes to your application and see the changes in real-time.

---
<!-- source: https://nx.dev/docs/technologies/angular/angular-rspack/guides/handling-configurations.md -->
## Handling Configurations

Configurations are handled slightly differently compared to the Angular CLI. Rsbuild and Rspack use `mode` instead of configurations to handle different environments by default. This means that a different solution is needed to handle different build configurations you may have to match the behavior of Angular configuration handling.

The [`createConfig`](/docs/technologies/angular/angular-rspack/create-config) function helps you to handle this. It uses the `NGRS_CONFIG` environment variable to determine which configuration to use. The default configuration is `production`.

{% aside type="tip" title="Roll your own" %}
You can handle configurations by yourself if you prefer, all you need is some manner of detecting the environment and then merging the options passed to `createConfig`.
{% /aside %}

## Using `createConfig` for configurations

The `createConfig` function takes two arguments, the first is the default options, and the second is an object of configurations. The configurations object is keyed by the name of the configuration, and the value is an object with the options and `rspackConfigOverrides | rsbuildConfigOverrides` to be used for that configuration.

```ts
// myapp/rspack.config.ts
import { createConfig } from '@nx/angular-rspack';
export default createConfig(
  {
    options: {
      browser: './src/main.ts',
      server: './src/main.server.ts',
      ssrEntry: './src/server.ts',
    },
    rspackConfigOverrides: {
      mode: 'development',
    },
  },
  {
    production: {
      options: {
        fileReplacements: [
          {
            replace: './src/environments/environment.ts',
            with: './src/environments/environment.prod.ts',
          },
        ],
      },
    },
  }
);
```

The above example shows how to handle the `production` configuration. The `options` are the same as the default options but with the `fileReplacements` property added, and the `rspackConfigOverrides` are the same as the default `rspackConfigOverrides`.

The `NGRS_CONFIG` environment variable is used to determine which configuration to use. If the environment variable is not set, the `production` configuration is used by default.
If a production configuration is not provided, the default configuration is used.

To run the build with the `production` configuration:

```shell
NGRS_CONFIG=production npx myapp build
```

---
<!-- source: https://nx.dev/docs/technologies/angular/angular-rspack/guides/internationalization.md -->
## Build-time Internationalization (i18n) with Angular Rspack

Angular Rspack supports Angular [build-time i18n](https://angular.dev/guide/i18n) out of the box. walk you through how to use it.  
You can follow the steps completely, just make sure to place any changes to `angular.json` in your project's `project.json` file. Some of these changes may also need to be made to the `rspack.config` file.
The steps below indicate where to make these changes.

The process of building an Angular Rspack application with i18n is similar to building an Angular application with i18n and reuses most of the same steps and configuration.

## Prerequisites

- `@angular/localize` must be installed in your project.
- You must have an `i18n` configuration in your `project.json` file.

It is assumed you have an `i18n` property in your `project.json` file that looks like this:

```json meta="{3-10}"
{
  "name": "my-app",
  "i18n": {
    "sourceLocale": "en-GB",
    "locales": {
      "fr": {
        "translation": "src/locale/messages.fr.xlf"
      }
    }
  },
  "targets": {
    "extract-i18n": {}
  }
}
```

{% aside type="note" title="Extracting i18n messages" %}
The `extract-i18n` target found in Angular projects will still be used to extract the i18n messages into XLIFF (or chosen format) files.
You simply need to run `nx extract-i18n my-app` to extract the messages.
{% /aside %}

## Step 1: Configure the Rspack Configuration

To enable i18n, you need to add the following configuration to your `rspack.config` file:

```js meta="{7,15}"
export default createConfig(
  {
    options: {
      root: __dirname,
      polyfills: [
        'zone.js',
        '@angular/localize/init',
      ],
      ...,
    },
  },
  {
    production: {
        options: {
            localize: true,
        },
    },
  }
);
```

## Step 2: Run the build

After configuring the Rspack configuration, you can run the build with the following command:

```shell
npx nx build my-app
```

It will output bundles in the `dist` directory with the following structure:
{%filetree %}

- dist
  - browser
    - [localeCode]
    - main.js
    - main.js.map
    - index.html
    - styles.css

{% /filetree %}

---
<!-- source: https://nx.dev/docs/technologies/angular/angular-rspack/guides/migrate-from-webpack.md -->
## Migrate Angular with Webpack to Rspack

Until recently, Angular used Webpack to build applications. Based on this, some third-party builders emerged to allow users to use a custom Webpack configuration when building their Angular applications.
When Angular switched to Esbuild, this meant that it became difficult for applications that used custom Webpack configurations to migrate to the new build system. help you migrate from Angular with Webpack to Rspack.
By migrating to Rspack, you can gain an immediate build performance benefit while maintaining the your existing Webpack build toolchain.

## Step 1: Initialize Nx

{% aside type="caution" title="Optional Step" %}
If you are already using Nx with version 20.6.0 or greater, you can skip this step.
{% /aside %}

Nx provides a generator to convert existing Angular Webpack projects to use `@nx/angular-rspack`. This generator is currently available in Nx `20.6.0`.

At the root of your project, run the following command:

```shell
npx nx@latest init
```

## Step 2: run the convert to Rspack generator

With Nx now initialized, the `@nx/angular` plugin will have been installed providing access to a series of generators and executors that aid Angular development.
In particular, the `@nx/angular:convert-to-rspack` generator will convert an Angular project to use Rspack.
To use it, run the following command:

```shell
npx nx g convert-to-rspack
```

## Step 3: Run your application

After running the generator, you can run tasks such as `build` and `serve` to build and serve your application.

```shell
npx nx build yourProjectName
npx nx serve yourProjectName
```

---
<!-- source: https://nx.dev/docs/technologies/angular/angular-rspack/introduction.md -->
## Angular Rspack Plugin for Nx

## Requirements

The `@angular-rspack/nx` plugin supports the following package versions.

| Package         | Supported Versions                                                                        |
| --------------- | ----------------------------------------------------------------------------------------- |
| `@rspack/core`  | >=1.3.5 <1.7.0                                                                            |
| `@angular/core` | See [Angular version matrix](/docs/technologies/angular/guides/angular-nx-version-matrix) |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

Angular compilation has always been a black box hidden behind layers of abstraction and configuration, exposed via the Angular Builders from the Angular CLI packages.

Originally, the underlying tool that bundled the Angular application was [Webpack](https://webpack.js.org). This was great as teams were able to extend their builds by leveraging the vast Webpack ecosystem and plugins that are available.

Over time, it became clear that the inherit slowness with Webpack build speeds was becoming more and more of an issue for Angular developers.

The Angular Team decided to address this build speed issue by building out a new build pipeline that used [Esbuild](https://esbuild.github.io/).

This succeeded in reducing the build times for Angular applications, however, it made one crucial mistake. It left the existing Angular applications that relied on the Webpack ecosystem behind, with either a difficult migration path or none at all.

---

## Rspack

The solution to this problem was to create a new build pipeline that could use the existing Webpack ecosystem and plugins while also providing faster builds for Angular applications.

This is where [Rspack](https://rspack.dev) come into play.

Rspack is a high performance JavaScript bundler written in Rust. It offers strong compatibility with the Webpack ecosystem, and can serve as a near drop-in replacement for webpack with significantly faster build speeds.

Because it supports the existing Webpack ecosystem, it provides an answer to teams that maintain Angular applications using Webpack and want to migrate to a faster build pipeline.

This makes it a great solution for teams that want to migrate to a faster build pipeline, but still want the ability to extend their builds and use [Module Federation](https://module-federation.io).

{% aside type="caution" title="Angular Rspack Status" %}

Please note that Angular Rspack support is still experimental and is not yet considered production ready. We are actively working on improving the experience and stability of Angular Rspack, and we will continue to update this page as we make progress.

{% /aside %}

## Known limitations and missing features

The following are known limitations and missing features of Angular Rspack:

- Server Routing is not supported - still experimental in Angular currently.
- App Engine APIs are not supported - still experimental in Angular currently.

If you have any other missing features or limitations, please [let us know](https://github.com/nrwl/angular-rspack/issues/new).

## Benchmarks

![Benchmarks](../../../../../assets/guides/angular-rspack/bundler-build-times.png)

Below is a table of benchmarks for different bundlers, tested on an application with ~800 lazy-loaded routes and ~10 components per route—totaling ~8000 components.

**System Info**

- MacBook Pro (macOS 15.3.1)
- Processor: M2 Max
- Memory: 96 GB

| Build/Bundler | Prod SSR (s) | Prod (s) | Dev (s) |
| ------------- | ------------ | -------- | ------- |
| Webpack       | 198.614      | 154.339  | 159.436 |
| esbuild       | 23.701       | 19.569   | 15.358  |
| Rspack        | 30.589       | 19.269   | 19.940  |

You can find the benchmarks and run them yourself: [https://github.com/nrwl/ng-bundler-benchmark](https://github.com/nrwl/ng-bundler-benchmark)

---
<!-- source: https://nx.dev/docs/technologies/angular/executors.md -->
## @nx/angular Executors

The @nx/angular plugin provides various executors to help you create and configure angular projects within your Nx workspace.
Below is a complete reference for all available executors and their options.

### `application`
Builds an Angular application using [esbuild](https://esbuild.github.io/) with integrated SSR and prerendering capabilities.

This executor is a drop-in replacement for the `@angular-devkit/build-angular:application` builder provided by the Angular CLI. It builds an Angular application using [esbuild](https://esbuild.github.io/) with integrated SSR and prerendering capabilities.

In addition to the features provided by the Angular CLI builder, the `@nx/angular:application` executor also supports the following:

- Providing esbuild plugins
- Providing a function to transform the application's `index.html` file
- Incremental builds

:::tip[Dev Server]
The [`@nx/angular:dev-server` executor](/nx-api/angular/executors/dev-server) is required to serve your application when using the `@nx/angular:application` to build it. It is a drop-in replacement for the Angular CLI's `@angular-devkit/build-angular:dev-server` builder and ensures the application is correctly served with Vite when using the `@nx/angular:application` executor.
:::

### Examples

###### Providing esbuild plugins

The executor accepts a `plugins` option that allows you to provide esbuild plugins that will be used when building your application. It allows providing a path to a plugin file or an object with a `path` and `options` property to provide options to the plugin.

```json title="apps/my-app/project.json" {8-16}
{
  ...
  "targets": {
    "build": {
      "executor": "@nx/angular:application",
      "options": {
        ...
        "plugins": [
          "apps/my-app/plugins/plugin1.js",
          {
            "path": "apps/my-app/plugins/plugin2.js",
            "options": {
              "someOption": "some value"
            }
          }
        ]
      }
    }
    ...
  }
}
```

```ts title="apps/my-app/plugins/plugin1.js"
const plugin1 = {
  name: 'plugin1',
  setup(build) {
    const options = build.initialOptions;
    options.define.PLUGIN1_TEXT = '"Value was provided at build time"';
  },
};

module.exports = plugin1;
```

```ts title="apps/my-app/plugins/plugin2.js"
function plugin2({ someOption }) {
  return {
    name: 'plugin2',
    setup(build) {
      const options = build.initialOptions;
      options.define.PLUGIN2_TEXT = JSON.stringify(someOption);
    },
  };
}

module.exports = plugin2;
```

Additionally, we need to inform TypeScript of the defined variables to prevent type-checking errors during the build. We can achieve this by creating or updating a type definition file included in the TypeScript build process (e.g. `src/types.d.ts`) with the following content:

```ts title="apps/my-app/src/types.d.ts"
declare const PLUGIN1_TEXT: number;
declare const PLUGIN2_TEXT: string;
```

###### Transforming the 'index.html' file

The executor accepts an `indexHtmlTransformer` option to provide a path to a file with a default export for a function that receives the application's `index.html` file contents and outputs the updated contents.

```json title="apps/my-app/project.json" {8}
{
  ...
  "targets": {
    "build": {
      "executor": "@nx/angular:application",
      "options": {
        ...
        "indexHtmlTransformer": "apps/my-app/index-html.transformer.ts"
      }
    }
    ...
  }
}
```

```ts title="apps/my-app/index-html.transformer.ts"
export default function (indexContent: string) {
  return indexContent.replace(
    '<title>my-app</title>',
    '<title>my-app (transformed)</title>'
  );
}
```
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `outputPath` | string [**required**] | Specify the output path relative to workspace root. |  |
| `tsConfig` | string [**required**] | The full path for the TypeScript configuration file, relative to the current workspace. |  |
| `allowedCommonJsDependencies` | array | A list of CommonJS or AMD packages that are allowed to be used without a build time warning. Use `'*'` to allow all. | `[]` |
| `aot` | boolean | Build using Ahead of Time compilation. | `true` |
| `appShell` | boolean | Generates an application shell during build time. |  |
| `assets` | array | List of static application assets. | `[]` |
| `baseHref` | string | Base url for the application being built. |  |
| `browser` | string | The full path for the browser entry point to the application, relative to the current workspace. |  |
| `budgets` | array | Budget thresholds to ensure parts of your application stay within boundaries which you set. | `[]` |
| `buildLibsFromSource` | boolean | Read buildable libraries from source instead of building them separately. | `true` |
| `clearScreen` | boolean | Automatically clear the terminal screen during rebuilds. | `false` |
| `conditions` | array | Custom package resolution conditions used to resolve conditional exports/imports. Defaults to ['module', 'development'/'production']. The following special conditions are always present if the requirements are satisfied: 'default', 'import', 'require', 'browser', 'node'. _Note: this is only supported in Angular versions >= 20.0.0_. |  |
| `crossOrigin` | string | Define the crossorigin attribute setting of elements that provide CORS support. | `"none"` |
| `define` | object | Defines global identifiers that will be replaced with a specified constant value when found in any JavaScript or TypeScript code including libraries. The value will be used directly. String values must be put in quotes. Identifiers within Angular metadata such as Component Decorators will not be replaced. |  |
| `deleteOutputPath` | boolean | Delete the output path before building. | `true` |
| `deployUrl` | string | Customize the base path for the URLs of resources in 'index.html' and component stylesheets. This option is only necessary for specific deployment scenarios, such as with Angular Elements or when utilizing different CDN locations. |  |
| `externalDependencies` | array | Exclude the listed external dependencies from being bundled into the bundle. Instead, the created bundle relies on these dependencies to be available during runtime. | `[]` |
| `extractLicenses` | boolean | Extract all licenses in a separate file. | `true` |
| `fileReplacements` | array | Replace compilation source files with other compilation source files in the build. | `[]` |
| `i18nDuplicateTranslation` | string | How to handle duplicate translations for i18n. | `"warning"` |
| `i18nMissingTranslation` | string | How to handle missing translations for i18n. | `"warning"` |
| `index` | string | Configures the generation of the application's HTML index. |  |
| `indexHtmlTransformer` | string | Path to a file exposing a default function to transform the `index.html` file. |  |
| `inlineStyleLanguage` | string | The stylesheet language to use for the application's inline component styles. | `"css"` |
| `loader` | object | Defines the type of loader to use with a specified file extension when used with a JavaScript `import`. `text` inlines the content as a string; `binary` inlines the content as a Uint8Array; `file` emits the file and provides the runtime location of the file; `dataurl` inlines the content as a data URL with best guess of MIME type; `base64` inlines the content as a Base64-encoded string; `empty` considers the content to be empty and not include it in bundles. _Note: `dataurl` and `base64` are only supported in Angular versions >= 20.1.0_. |  |
| `localize` | string | Translate the bundles in one or more locales. |  |
| `namedChunks` | boolean | Use file name for lazy loaded chunks. | `false` |
| `optimization` | string | Enables optimization of the build output. Including minification of scripts and styles, tree-shaking, dead-code elimination, inlining of critical CSS and fonts inlining. For more information, see https://angular.dev/reference/configs/workspace-config#optimization-configuration. | `true` |
| `outputHashing` | string | Define the output filename cache-busting hashing mode. | `"none"` |
| `outputMode` | string | Defines the build output target. 'static': Generates a static site for deployment on any static hosting service. 'server': Produces an application designed for deployment on a server that supports server-side rendering (SSR). |  |
| `plugins` | array | A list of ESBuild plugins. |  |
| `poll` | number | Enable and define the file watching poll time period in milliseconds. |  |
| `polyfills` | array | A list of polyfills to include in the build. Can be a full path for a file, relative to the current workspace or module specifier. Example: 'zone.js'. | `[]` |
| `prerender` | string | Prerender (SSG) pages of your application during build time. |  |
| `preserveSymlinks` | boolean | Do not use the real path when resolving modules. If unset then will default to `true` if NodeJS option --preserve-symlinks is set. |  |
| `progress` | boolean | Log progress to the console while building. | `true` |
| `scripts` | array | Global scripts to be included in the build. | `[]` |
| `security` | object | Security features to protect against XSS and other common attacks |  |
| `server` | string | The full path for the server entry point to the application, relative to the current workspace. |  |
| `serviceWorker` | string | Generates a service worker configuration. | `false` |
| `sourceMap` | string | Output source maps for scripts and styles. For more information, see https://angular.dev/reference/configs/workspace-config#source-map-configuration. | `false` |
| `ssr` | string | Server side render (SSR) pages of your application during runtime. | `false` |
| `statsJson` | boolean | Generates a 'stats.json' file which can be analyzed with https://esbuild.github.io/analyze/. | `false` |
| `stylePreprocessorOptions` | object | Options to pass to style preprocessors. |  |
| `styles` | array | Global styles to be included in the build. | `[]` |
| `subresourceIntegrity` | boolean | Enables the use of subresource integrity validation. | `false` |
| `verbose` | boolean | Adds more details to output logging. | `false` |
| `watch` | boolean | Run build when files change. | `false` |
| `webWorkerTsConfig` | string | TypeScript configuration for Web Worker modules. |  |

### `browser-esbuild`
Builds an Angular application using [esbuild](https://esbuild.github.io/).

This executor is a drop-in replacement for the `@angular-devkit/build-angular:browser-esbuild` builder provided by the Angular CLI. It builds an Angular application using esbuild.

In addition to the features provided by the Angular CLI builder, the `@nx/angular:browser-esbuild` executor also supports the following:

- Providing esbuild plugins
- Incremental builds

:::tip[Dev Server]
The [`@nx/angular:dev-server` executor](/nx-api/angular/executors/dev-server) is required to serve your application when using the `@nx/angular:browser-esbuild` to build it. It is a drop-in replacement for the Angular CLI's `@angular-devkit/build-angular:dev-server` builder and ensures the application is correctly served with Vite when using the `@nx/angular:browser-esbuild` executor.
:::

### Examples

###### Providing esbuild plugins

The executor accepts a `plugins` option that allows you to provide esbuild plugins that will be used when building your application. It allows providing a path to a plugin file or an object with a `path` and `options` property to provide options to the plugin.

```json title="apps/my-app/project.json" {8-16}
{
  ...
  "targets": {
    "build": {
      "executor": "@nx/angular:browser-esbuild",
      "options": {
        ...
        "plugins": [
          "apps/my-app/plugins/plugin1.js",
          {
            "path": "apps/my-app/plugins/plugin2.js",
            "options": {
              "someOption": "some value"
            }
          }
        ]
      }
    }
    ...
  }
}
```

```ts title="apps/my-app/plugins/plugin1.js"
const plugin1 = {
  name: 'plugin1',
  setup(build) {
    const options = build.initialOptions;
    options.define.PLUGIN1_TEXT = '"Value was provided at build time"';
  },
};

module.exports = plugin1;
```

```ts title="apps/my-app/plugins/plugin2.js"
function plugin2({ someOption }) {
  return {
    name: 'plugin2',
    setup(build) {
      const options = build.initialOptions;
      options.define.PLUGIN2_TEXT = JSON.stringify(someOption);
    },
  };
}

module.exports = plugin2;
```

Additionally, we need to inform TypeScript of the defined variables to prevent type-checking errors during the build. We can achieve this by creating or updating a type definition file included in the TypeScript build process (e.g. `src/types.d.ts`) with the following content:

```ts title="apps/my-app/src/types.d.ts"
declare const PLUGIN1_TEXT: number;
declare const PLUGIN2_TEXT: string;
```
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `index` | string [**required**] | Configures the generation of the application's HTML index. |  |
| `main` | string [**required**] | The full path for the main entry point to the app, relative to the current workspace. |  |
| `outputPath` | string [**required**] | The full path for the new output directory, relative to the current workspace. |  |
| `tsConfig` | string [**required**] | The full path for the TypeScript configuration file, relative to the current workspace. |  |
| `allowedCommonJsDependencies` | array | A list of CommonJS or AMD packages that are allowed to be used without a build time warning. Use `'*'` to allow all. | `[]` |
| `aot` | boolean | Build using Ahead of Time compilation. | `true` |
| `assets` | array | List of static application assets. | `[]` |
| `baseHref` | string | Base url for the application being built. |  |
| `budgets` | array | Budget thresholds to ensure parts of your application stay within boundaries which you set. | `[]` |
| `buildLibsFromSource` | boolean | Read buildable libraries from source instead of building them separately. | `true` |
| `buildOptimizer` | boolean | Enables advanced build optimizations when using the 'aot' option. | `true` |
| `commonChunk` | boolean | Generate a separate bundle containing code used across multiple bundles. | `true` |
| `crossOrigin` | string | Define the crossorigin attribute setting of elements that provide CORS support. | `"none"` |
| `deleteOutputPath` | boolean | Delete the output path before building. | `true` |
| `deployUrl` | string | Customize the base path for the URLs of resources in 'index.html' and component stylesheets. This option is only necessary for specific deployment scenarios, such as with Angular Elements or when utilizing different CDN locations. |  |
| `externalDependencies` | array | Exclude the listed external dependencies from being bundled into the bundle. Instead, the created bundle relies on these dependencies to be available during runtime. | `[]` |
| `extractLicenses` | boolean | Extract all licenses in a separate file. | `true` |
| `fileReplacements` | array | Replace compilation source files with other compilation source files in the build. | `[]` |
| `i18nDuplicateTranslation` | string | How to handle duplicate translations for i18n. | `"warning"` |
| `i18nMissingTranslation` | string | How to handle missing translations for i18n. | `"warning"` |
| `inlineStyleLanguage` | string | The stylesheet language to use for the application's inline component styles. | `"css"` |
| `localize` | string | Translate the bundles in one or more locales. |  |
| `namedChunks` | boolean | Use file name for lazy loaded chunks. | `false` |
| `ngswConfigPath` | string | Path to ngsw-config.json. |  |
| `optimization` | string | Enables optimization of the build output. Including minification of scripts and styles, tree-shaking, dead-code elimination, inlining of critical CSS and fonts inlining. For more information, see https://angular.dev/reference/configs/workspace-config#optimization-configuration. | `true` |
| `outputHashing` | string | Define the output filename cache-busting hashing mode. | `"none"` |
| `plugins` | array | A list of ESBuild plugins. |  |
| `poll` | number | Enable and define the file watching poll time period in milliseconds. |  |
| `polyfills` | string | Polyfills to be included in the build. |  |
| `preserveSymlinks` | boolean | Do not use the real path when resolving modules. If unset then will default to `true` if NodeJS option --preserve-symlinks is set. |  |
| `progress` | boolean | Log progress to the console while building. | `true` |
| `resourcesOutputPath` | string | The path where style resources will be placed, relative to outputPath. |  |
| `scripts` | array | Global scripts to be included in the build. | `[]` |
| `serviceWorker` | boolean | Generates a service worker config for production builds. | `false` |
| `sourceMap` | string | Output source maps for scripts and styles. For more information, see https://angular.dev/reference/configs/workspace-config#source-map-configuration. | `false` |
| `statsJson` | boolean | Generates a 'stats.json' file which can be analyzed using tools such as 'webpack-bundle-analyzer'. | `false` |
| `stylePreprocessorOptions` | object | Options to pass to style preprocessors. |  |
| `styles` | array | Global styles to be included in the build. | `[]` |
| `subresourceIntegrity` | boolean | Enables the use of subresource integrity validation. | `false` |
| `vendorChunk` | boolean | Generate a separate bundle containing only vendor libraries. This option should only be used for development to reduce the incremental compilation time. | `false` |
| `verbose` | boolean | Adds more details to output logging. | `false` |
| `watch` | boolean | Run build when files change. | `false` |
| `webWorkerTsConfig` | string | TypeScript configuration for Web Worker modules. |  |

### `delegate-build`
Delegates the build to a different target while supporting incremental builds.

### Examples

###### Basic Usage

Delegate the build of the project to a different target.

```json
{
  "prod-build": {
    "executor": "@nx/angular:delegate-build",
    "options": {
      "buildTarget": "app:build:production",
      "outputPath": "dist/apps/app/production",
      "tsConfig": "apps/app/tsconfig.json",
      "watch": false
    }
  }
}
```

###### Watch for build changes

Delegate the build of the project to a different target.

```json
{
  "prod-build": {
    "executor": "@nx/angular:delegate-build",
    "options": {
      "buildTarget": "app:build:production",
      "outputPath": "dist/apps/app/production",
      "tsConfig": "apps/app/tsconfig.json",
      "watch": true
    }
  }
}
```
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `buildTarget` | string [**required**] | Build target used for building the application after its dependencies have been built. |  |
| `outputPath` | string [**required**] | The full path for the output directory, relative to the workspace root. |  |
| `tsConfig` | string [**required**] | The full path for the TypeScript configuration file, relative to the workspace root. |  |
| `watch` | boolean | Whether to run a build when any file changes. | `false` |

### `extract-i18n`
Extracts i18n messages from source code.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `buildTarget` | string [**required**] | A builder target to extract i18n messages in the format of `project:target[:configuration]`. You can also pass in more than one configuration name as a comma-separated list. Example: `project:target:production,staging`. |  |
| `format` | string | Output format for the generated file. | `"xlf"` |
| `i18nDuplicateTranslation` | string | How to handle duplicate translations. _Note: this is only available in Angular 20.0.0 and above._ |  |
| `outFile` | string | Name of the file to output. |  |
| `outputPath` | string | Path where output will be placed. |  |
| `progress` | boolean | Log progress to the console. | `true` |

### `module-federation-dev-server`
Serves host [Module Federation](https://module-federation.io/) applications ([webpack](https://webpack.js.org/)-based) allowing to specify which remote applications should be served with the host.

### Examples

###### Basic Usage

The Module Federation Dev Server will serve a host application and find the remote applications associated with the host and serve them statically also.  
See an example set up of it below:

```json
{
  "serve": {
    "executor": "@nx/angular:module-federation-dev-server",
    "configurations": {
      "production": {
        "buildTarget": "host:build:production"
      },
      "development": {
        "buildTarget": "host:build:development"
      }
    },
    "defaultConfiguration": "development",
    "options": {
      "port": 4200,
      "publicHost": "http://localhost:4200"
    }
  }
}
```

###### Serve host with remotes that can be live reloaded

The Module Federation Dev Server will serve a host application and find the remote applications associated with the host and serve a set selection with live reloading enabled also.  
See an example set up of it below:

```json
{
  "serve-with-hmr-remotes": {
    "executor": "@nx/angular:module-federation-dev-server",
    "configurations": {
      "production": {
        "buildTarget": "host:build:production"
      },
      "development": {
        "buildTarget": "host:build:development"
      }
    },
    "defaultConfiguration": "development",
    "options": {
      "port": 4200,
      "publicHost": "http://localhost:4200",
      "devRemotes": [
        "remote1",
        {
          "remoteName": "remote2",
          "configuration": "development"
        }
      ]
    }
  }
}
```
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `buildTarget` | string [**required**] | A build builder target to serve in the format of `project:target[:configuration]`. |  |
| `allowedHosts` | array | List of hosts that are allowed to access the dev server. | `[]` |
| `buildLibsFromSource` | boolean | Read buildable libraries from source instead of building them separately. If not set, it will take the value specified in the `buildTarget` options, or it will default to `true` if it's also not set in the `buildTarget` options. |  |
| `devRemotes` | array | List of remote applications to run in development mode (i.e. using serve target). |  |
| `disableHostCheck` | boolean | Don't verify connected clients are part of allowed hosts. | `false` |
| `headers` | object | Custom HTTP headers to be added to all responses. |  |
| `hmr` | boolean | Enable hot module replacement. | `false` |
| `host` | string | Host to listen on. | `"localhost"` |
| `isInitialHost` | boolean | Whether the host that is running this executor is the first in the project tree to do so. | `true` |
| `liveReload` | boolean | Whether to reload the page on change, using live-reload. | `true` |
| `open` | boolean | Opens the url in default browser. | `false` |
| `parallel` | number | Max number of parallel processes for building static remotes |  |
| `pathToManifestFile` | string | Path to a Module Federation manifest file (e.g. `my/path/to/module-federation.manifest.json`) containing the dynamic remote applications relative to the workspace root. |  |
| `poll` | number | Enable and define the file watching poll time period in milliseconds. |  |
| `port` | number | Port to listen on. | `4200` |
| `proxyConfig` | string | Proxy configuration file. For more information, see https://angular.dev/tools/cli/serve#proxying-to-a-backend-server. |  |
| `publicHost` | string | The URL that the browser client (or live-reload client, if enabled) should use to connect to the development server. Use for a complex dev server setup, such as one with reverse proxies. |  |
| `servePath` | string | The pathname where the app will be served. |  |
| `skipRemotes` | array | List of remote applications to not automatically serve, either statically or in development mode. This will not remove the remotes from the `module-federation.config` file, and therefore the application may still try to fetch these remotes.
This option is useful if you have other means for serving the `remote` application(s).
**NOTE:** Remotes that are not in the workspace will be skipped automatically. |  |
| `ssl` | boolean | Serve using HTTPS. | `false` |
| `sslCert` | string | SSL certificate to use for serving HTTPS. |  |
| `sslKey` | string | SSL key to use for serving HTTPS. |  |
| `static` | boolean | Whether to use a static file server instead of the webpack-dev-server. This should be used for remote applications that are also host applications. |  |
| `staticRemotesPort` | number | The port at which to serve the file-server for the static remotes. |  |
| `verbose` | boolean | Adds more details to output logging. |  |
| `watch` | boolean | Rebuild on change. | `true` |

### `module-federation-dev-ssr`
The module-federation-ssr-dev-server executor is reserved exclusively for use with host SSR Module Federation applications. It allows the user to specify which remote applications should be served with the host.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `browserTarget` | string [**required**] | Browser target to build. |  |
| `serverTarget` | string [**required**] | Server target to build. |  |
| `devRemotes` | array | List of remote applications to run in development mode (i.e. using serve target). |  |
| `host` | string | Host to listen on. | `"localhost"` |
| `inspect` | boolean | Launch the development server in inspector mode and listen on address and port '127.0.0.1:9229'. | `false` |
| `isInitialHost` | boolean | Whether the host that is running this executor is the first in the project tree to do so. | `true` |
| `open` | boolean | Opens the url in default browser. | `false` |
| `parallel` | number | Max number of parallel processes for building static remotes |  |
| `pathToManifestFile` | string | Path to a Module Federation manifest file (e.g. `my/path/to/module-federation.manifest.json`) containing the dynamic remote applications relative to the workspace root. |  |
| `port` | number | Port to start the development server at. Default is 4200. Pass 0 to get a dynamically assigned port. | `4200` |
| `progress` | boolean | Log progress to the console while building. |  |
| `proxyConfig` | string | Proxy configuration file. |  |
| `publicHost` | string | The URL that the browser client should use to connect to the development server. Use for a complex dev server setup, such as one with reverse proxies. |  |
| `skipRemotes` | array | List of remote applications to not automatically serve, either statically or in development mode. |  |
| `ssl` | boolean | Serve using HTTPS. | `false` |
| `sslCert` | string | SSL certificate to use for serving HTTPS. |  |
| `sslKey` | string | SSL key to use for serving HTTPS. |  |
| `staticRemotesPort` | number | The port at which to serve the file-server for the static remotes. |  |
| `verbose` | boolean | Adds more details to output logging. | `false` |

### `ng-packagr-lite`
Builds an Angular library with support for incremental builds.

This executor is meant to be used with buildable libraries in an incremental build scenario. It is similar to the `@nx/angular:package` executor but it only produces ESM2022 bundles.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `poll` | number | Enable and define the file watching poll time period in milliseconds. |  |
| `project` | string | The file path for the ng-packagr configuration file, relative to the workspace root. |  |
| `tsConfig` | string | The full path for the TypeScript configuration file, relative to the workspace root. |  |
| `watch` | boolean | Whether to run a build when any file changes. | `false` |

### `package`
Builds and packages an Angular library producing an output following the Angular Package Format (APF) to be distributed as an NPM package.

This executor is a drop-in replacement for the `@angular-devkit/build-angular:ng-packagr` and `@angular/build:ng-packagr` builders, with additional support for incremental builds.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `poll` | number | Enable and define the file watching poll time period in milliseconds. |  |
| `project` | string | The file path for the ng-packagr configuration file, relative to the workspace root. |  |
| `tsConfig` | string | The full path for the TypeScript configuration file, relative to the workspace root. |  |
| `watch` | boolean | Whether to run a build when any file changes. | `false` |

### `unit-test`
Run application unit tests. _Note: this is only supported in Angular versions >= 21.0.0_.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `browsers` | array | Specifies the browsers to use for test execution. When not specified, tests are run in a Node.js environment using jsdom. For both Vitest and Karma, browser names ending with 'Headless' (e.g., 'ChromeHeadless') will enable headless mode. |  |
| `browserViewport` | string | Specifies the browser viewport dimensions for browser-based tests in the format `widthxheight`. |  |
| `buildTarget` | string | Specifies the build target to use for the unit test build in the format `project:target[:configuration]`. This defaults to the `build` target of the current project with the `development` configuration. You can also pass a comma-separated list of configurations. Example: `project:target:production,staging`. |  |
| `coverage` | boolean | Enables coverage reporting for tests. | `false` |
| `coverageExclude` | array | Specifies glob patterns of files to exclude from the coverage report. |  |
| `coverageInclude` | array | Specifies glob patterns of files to include in the coverage report. |  |
| `coverageReporters` | array | Specifies the reporters to use for coverage results. Each reporter can be a string representing its name, or a tuple containing the name and an options object. Built-in reporters include 'html', 'lcov', 'lcovonly', 'text', 'text-summary', 'cobertura', 'json', and 'json-summary'. |  |
| `coverageThresholds` | object | Specifies minimum coverage thresholds that must be met. If thresholds are not met, the builder will exit with an error. |  |
| `coverageWatermarks` | object | Specifies coverage watermarks for the HTML reporter. These determine the color coding for high, medium, and low coverage. |  |
| `debug` | boolean | Enables debugging mode for tests, allowing the use of the Node Inspector. | `false` |
| `dumpVirtualFiles` | boolean | Dumps build output files to the `.angular/cache` directory for debugging purposes. | `false` |
| `exclude` | array | Specifies glob patterns of files to exclude from testing, relative to the project root. |  |
| `filter` | string | Specifies a regular expression pattern to match against test suite and test names. Only tests with a name matching the pattern will be executed. For example, `^App` will run only tests in suites beginning with 'App'. |  |
| `headless` | boolean | Forces all configured browsers to run in headless mode. When using the Vitest runner, this option is ignored if no browsers are configured. The Karma runner does not support this option. _Note: this is only supported in Angular versions >= 21.2.0_. |  |
| `include` | array | Specifies glob patterns of files to include for testing, relative to the project root. This option also has special handling for directory paths (includes all test files within) and file paths (includes the corresponding test file if one exists). | `["**/*.spec.ts","**/*.test.ts"]` |
| `indexHtmlTransformer` | string | Path to a file exposing a default function to transform the `index.html` file. |  |
| `listTests` | boolean | Lists all discovered test files and exits the process without building or executing the tests. | `false` |
| `outputFile` | string | Specifies a file path for the test report, applying only to the first reporter. To configure output files for multiple reporters, use the tuple format `['reporter-name', { outputFile: '...' }]` within the `reporters` option. When not provided, output is written to the console. |  |
| `plugins` | array | A list of ESBuild plugins. |  |
| `progress` | boolean | Shows build progress information in the console. Defaults to the `progress` setting of the specified `buildTarget`. |  |
| `providersFile` | string | Specifies the path to a TypeScript file that provides an array of Angular providers for the test environment. The file must contain a default export of the provider array. |  |
| `reporters` | array | Specifies the reporters to use during test execution. Each reporter can be a string representing its name, or a tuple containing the name and an options object. Built-in reporters include 'default', 'verbose', 'dots', 'json', 'junit', 'tap', 'tap-flat', and 'html'. You can also provide a path to a custom reporter. |  |
| `runner` | string | Specifies the test runner to use for test execution. | `"vitest"` |
| `runnerConfig` | string | boolean | Specifies the configuration file for the selected test runner. If a string is provided, it will be used as the path to the configuration file. If `true`, the builder will search for a default configuration file (e.g., `vitest.config.ts` or `karma.conf.js`). If `false`, no external configuration file will be used.\nFor Vitest, this enables advanced options and the use of custom plugins. Please note that while the file is loaded, the Angular team does not provide direct support for its specific contents or any third-party plugins used within it. | `false` |
| `setupFiles` | array | A list of paths to global setup files that are executed before the test files. The application's polyfills and the Angular TestBed are always initialized before these files. |  |
| `tsConfig` | string | The path to the TypeScript configuration file, relative to the workspace root. Defaults to `tsconfig.spec.json` in the project root if it exists. If not specified and the default does not exist, the `tsConfig` from the specified `buildTarget` will be used. |  |
| `ui` | boolean | Enables the Vitest UI for interactive test execution. This option is only available for the Vitest runner. |  |
| `watch` | boolean | Enables watch mode, which re-runs tests when source files change. Defaults to `true` in TTY environments and `false` otherwise. |  |

---
<!-- source: https://nx.dev/docs/technologies/angular/generators.md -->
## @nx/angular Generators

The @nx/angular plugin provides various generators to help you create and configure angular projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `application`
Creates an Angular application.

### Examples

###### Simple Application

Create an application named `my-app`:

```bash
nx g @nx/angular:application apps/my-app
```

###### Specify style extension

Create an application named `my-app` in the `my-dir` directory and use `scss` for styles:

```bash
nx g @nx/angular:app my-dir/my-app --style=scss
```

###### Single File Components application

Create an application with Single File Components (inline styles and inline templates):

```bash
nx g @nx/angular:app apps/my-app --inlineStyle --inlineTemplate
```

###### Set custom prefix and tags

Set the prefix to apply to generated selectors and add tags to the application (used for linting).

```bash
nx g @nx/angular:app apps/my-app --prefix=admin --tags=scope:admin,type:ui
```

**Usage:**
```bash
nx generate @nx/angular:application [options]
```

**Aliases:** `app`

**Arguments:**
```bash
nx generate @nx/angular:application <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--addTailwind` | boolean | Whether to configure Tailwind CSS for the application. | `false` |
| `--backendProject` | string | Backend project that provides data to this application. This sets up `proxy.config.json`. |  |
| `--bundler` | string | Bundler to use to build the application. | `"esbuild"` |
| `--e2eTestRunner` | string | Test runner to use for end to end (E2E) tests. | `"playwright"` |
| `--inlineStyle` | boolean | Specifies if the style will be in the ts file. | `false` |
| `--inlineTemplate` | boolean | Specifies if the template will be in the ts file. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"eslint"` |
| `--minimal` | boolean | Generate a Angular app with a minimal setup. | `false` |
| `--name` | string | The name of the application. |  |
| `--port` | number | The port at which the remote application should be served. |  |
| `--prefix` | string | The prefix to apply to generated selectors. | `"app"` |
| `--rootProject` | boolean | Create an application at the root of the workspace. | `false` |
| `--routing` | boolean | Enable routing for the application. | `true` |
| `--serverRouting` | boolean | Creates a server application using the Server Routing and App Engine APIs for application using the `application` builder (Developer Preview). _Note: this is only supported in Angular versions 19.x.x_. From Angular 20 onwards, SSR will always enable server routing when using the `application` builder. |  |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--skipTests` | boolean | Skip creating spec files. | `false` |
| `--ssr` | boolean | Creates an application with Server-Side Rendering (SSR) and Static Site Generation (SSG/Prerendering) enabled. | `false` |
| `--standalone` | boolean | Generate an application that is setup to use standalone components. | `true` |
| `--strict` | boolean | Create an application with stricter type checking and build optimization options. | `true` |
| `--style` | string | The file extension to be used for style files. | `"css"` |
| `--tags` | string | Add tags to the application (used for linting). |  |
| `--unitTestRunner` | string | Test runner to use for unit tests. `vitest-angular` uses the `@angular/build:unit-test` executor (requires Angular v21+ and the `esbuild` bundler). `vitest-analog` uses AnalogJS-based setup with `@nx/vitest`. It defaults to `vitest-angular` when using the `esbuild` bundler for Angular versions >= 21.0.0, `vitest-analog` when using other bundlers on Angular >= 21.0.0, otherwise `jest`. |  |
| `--viewEncapsulation` | string | Specifies the view encapsulation strategy. |  |
| `--zoneless` | boolean | Generate an application that does not use `zone.js`. It defaults to `true`. _Note: this is only supported in Angular versions >= 21.0.0_ |  |

## `component`
Creates a new Angular component.

### Examples

###### Simple Component

Generate a component named `Card` at `apps/my-app/src/lib/card/card.ts`:

```bash
nx g @nx/angular:component apps/my-app/src/lib/card/card.ts
```

###### Without Providing the File Extension

Generate a component named `Card` at `apps/my-app/src/lib/card/card.ts`:

```bash
nx g @nx/angular:component apps/my-app/src/lib/card/card
```

###### With Different Symbol Name

Generate a component named `Custom` at `apps/my-app/src/lib/card/card.ts`:

```bash
nx g @nx/angular:component apps/my-app/src/lib/card/card --name=custom
```

###### With a Component Type

Generate a component named `CardComponent` at `apps/my-app/src/lib/card/card.component.ts`:

```bash
nx g @nx/angular:component apps/my-app/src/lib/card/card --type=component
```

###### Single File Component

Create a component named `Card` with inline styles and inline template:

```bash
nx g @nx/angular:component apps/my-app/src/lib/card/card --inlineStyle --inlineTemplate
```

###### Component with OnPush Change Detection Strategy

Create a component named `Card` with `OnPush` Change Detection Strategy:

```bash
nx g @nx/angular:component apps/my-app/src/lib/card/card --changeDetection=OnPush
```

**Usage:**
```bash
nx generate @nx/angular:component [options]
```

**Aliases:** `c`

**Arguments:**
```bash
nx generate @nx/angular:component <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--changeDetection` | string | The change detection strategy to use in the new component. | `"Default"` |
| `--displayBlock` | boolean | Specifies if the style will contain `:host { display: block; }`. | `false` |
| `--export` | boolean | Specifies if the component should be exported in the declaring `NgModule`. Additionally, if the project is a library, the component will be exported from the project's entry point (normally `index.ts`) if the module it belongs to is also exported or if the component is standalone. | `false` |
| `--exportDefault` | boolean | Use default export for the component instead of a named export. | `false` |
| `--inlineStyle` | boolean | Include styles inline in the component.ts file. Only CSS styles can be included inline. By default, an external styles file is created and referenced in the component.ts file. | `false` |
| `--inlineTemplate` | boolean | Include template inline in the component.ts file. By default, an external template file is created and referenced in the component.ts file. | `false` |
| `--module` | string | The filename or path to the NgModule that will declare this component. |  |
| `--name` | string | The component symbol name. Defaults to the last segment of the file path. |  |
| `--ngHtml` | boolean | Generate component template files with an '.ng.html' file extension instead of '.html'. | `false` |
| `--prefix` | string | The prefix to apply to the generated component selector. |  |
| `--selector` | string | The HTML selector to use for this component. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipImport` | boolean | Do not import this component into the owning NgModule. | `false` |
| `--skipSelector` | boolean | Specifies if the component should have a selector or not. | `false` |
| `--skipTests` | boolean | Do not create `spec.ts` test files for the new component. | `false` |
| `--standalone` | boolean | Whether the generated component is standalone. | `true` |
| `--style` | string | The file extension or preprocessor to use for style files, or `none` to skip generating the style file. | `"css"` |
| `--type` | string | Append a custom type to the component's filename. It defaults to 'component' for Angular versions below v20. For Angular v20 and above, no type is appended unless specified. |  |
| `--viewEncapsulation` | string | The view encapsulation strategy to use in the new component. |  |

## `component-test`
Create a `*.cy.ts` file for Cypress component testing for an Angular component.

### Examples

:::caution[Can I use component testing?]
Angular component testing with Nx requires **Cypress version 10.7.0** and up.

You can migrate with to v11 via the [migrate-to-cypress-11 generator](/nx-api/cypress/generators/migrate-to-cypress-11).
:::

This generator is used to create a Cypress component test file for a given Angular component.

```shell
nx g @nx/angular:component-test --project=my-cool-angular-project --componentName=CoolBtnComponent --componentDir=src/cool-btn --componentFileName=cool-btn.component
```

Test file are generated with the `.cy.ts` suffix. this is to prevent colliding with any existing `.spec.` files contained in the project.

It's currently expected the generated `.cy.ts` file will live side by side with the component. It is also assumed the project is already setup for component testing. If it isn't, then you can run the [cypress-component-project generator](/nx-api/angular/generators/cypress-component-configuration) to set up the project for component testing.

**Usage:**
```bash
nx generate @nx/angular:component-test [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--componentDir` | string [**required**] | Relative path to the folder that contains the component from the project root. |  |
| `--componentFileName` | string [**required**] | File name that contains the component without the `.ts` extension. |  |
| `--componentName` | string [**required**] | Class name of the component to create a test for. |  |
| `--project` | string [**required**] | The name of the project where the component is located. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |

## `convert-to-application-executor`
Converts a project or all projects using one of the `@angular-devkit/build-angular:browser`, `@angular-devkit/build-angular:browser-esbuild`, `@nx/angular:browser` and `@nx/angular:browser-esbuild` executors to use the `@nx/angular:application` executor or the `@angular-devkit/build-angular:application` builder. If the converted target is using one of the `@nx/angular` executors, the `@nx/angular:application` executor will be used. Otherwise, the `@angular-devkit/build-angular:application` builder will be used.

**Usage:**
```bash
nx generate @nx/angular:convert-to-application-executor [options]
```

**Arguments:**
```bash
nx generate @nx/angular:convert-to-application-executor <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--skipFormat` | boolean | Skip formatting files. | `false` |

## `convert-to-rspack`
Creates an Angular application.

**Usage:**
```bash
nx generate @nx/angular:convert-to-rspack [options]
```

**Arguments:**
```bash
nx generate @nx/angular:convert-to-rspack <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipInstall` | boolean | Skip installing dependencies. | `false` |

## `convert-to-with-mf`
Converts an old micro frontend configuration to use the new withModuleFederation helper. It will run successfully if the following conditions are met: 
 - Is either a host or remote application 
 - Shared npm package configurations have not been modified 
 - Name used to identify the Micro Frontend application matches the project name 

{% callout type="warning" title="Overrides" %}This generator will overwrite your webpack config. If you have additional custom configuration in your config file, it will be lost!{% /callout %}.

**Usage:**
```bash
nx generate @nx/angular:convert-to-with-mf [options]
```

**Arguments:**
```bash
nx generate @nx/angular:convert-to-with-mf <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--skipFormat` | boolean | Skip formatting files. | `false` |

## `cypress-component-configuration`
Add a Cypress component testing configuration to an existing project. Cypress v10.7.0 or higher is required.

:::caution[Can I use component testing?]
Angular component testing with Nx requires **Cypress version 10.7.0** and up.

You can migrate with to v11 via the [migrate-to-cypress-11 generator](/nx-api/cypress/generators/migrate-to-cypress-11).

This generator is for Cypress based component testing.

If you want to test components via Storybook with Cypress, then check out the [storybook-configuration generator docs](/nx-api/angular/generators/storybook-configuration). However, this functionality is deprecated, and will be removed on Nx version 18.
:::

This generator is designed to get your Angular project up and running with Cypress Component Testing.

```shell
nx g @nx/angular:cypress-component-configuration --project=my-cool-angular-project
```

Running this generator, adds the required files to the specified project with a preconfigured `cypress.config.ts` designed for Nx workspaces.

```ts title="cypress.config.ts"
import { defineConfig } from 'cypress';
import { nxComponentTestingPreset } from '@nx/angular/plugins/component-testing';

export default defineConfig({
  component: nxComponentTestingPreset(__filename),
});
```

Here is an example on how to add custom options to the configuration

```ts title="cypress.config.ts"
import { defineConfig } from 'cypress';
import { nxComponentTestingPreset } from '@nx/angular/plugins/component-testing';

export default defineConfig({
  component: {
    ...nxComponentTestingPreset(__filename),
    // extra options here
  },
});
```

### Specifying a Build Target

Component testing requires a _build target_ to correctly run the component test dev server. This option can be manually specified with `--build-target=some-angular-app:build`, but Nx will infer this usage from the [project graph](/concepts/mental-model#the-project-graph) if one isn't provided.

For Angular projects, the build target needs to be using the `@nx/angular:webpack-browser` or
`@angular-devkit/build-angular:browser` executor.
The generator will throw an error if a build target can't be found and suggest passing one in manually.

Letting Nx infer the build target by default

```shell
nx g @nx/angular:cypress-component-configuration --project=my-cool-angular-project
```

Manually specifying the build target

```shell
nx g @nx/angular:cypress-component-configuration --project=my-cool-angular-project --build-target:some-angular-app:build --generate-tests
```

:::note[Build Target with Configuration]
If you're wanting to use a build target with a specific configuration. i.e. `my-app:build:production`,
then manually providing `--build-target=my-app:build:production` is the best way to do that.
:::

### Auto Generating Tests

You can optionally use the `--generate-tests` flag to generate a test file for each component in your project.

```shell
nx g @nx/angular:cypress-component-configuration --project=my-cool-angular-project --generate-tests
```

### Running Component Tests

A new `component-test` target will be added to the specified project to run your component tests.

```shell
nx g component-test my-cool-angular-project
```

Here is an example of the project configuration that is generated. The `--build-target` option is added as the `devServerTarget` which can be changed as needed.

```json title="project.json"
{
  "targets" {
    "component-test": {
      "executor": "@nx/cypress:cypress",
      "options": {
        "cypressConfig": "<path-to-project-root>/cypress.config.ts",
        "testingType": "component",
        "devServerTarget": "some-angular-app:build",
        "skipServe": true
      }
    }
  }
}
```

### What is bundled

When the project being tested is a dependent of the specified `--build-target`, then **assets, scripts, and styles** are applied to the component being tested. You can determine if the project is dependent by using the [project graph](/features/explore-graph). If there is no link between the two projects, then the **assets, scripts, and styles** won't be included in the build; therefore, they will not be applied to the component. To have a link between projects, you can import from the project being tested into the specified `--build-target` project, or set the `--build-target` project to [implicitly depend](/reference/project-configuration#implicitdependencies) on the project being tested.

Nx also supports [React component testing](/nx-api/react/generators/cypress-component-configuration).

**Usage:**
```bash
nx generate @nx/angular:cypress-component-configuration [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string [**required**] | The name of the project to add cypress component testing configuration to |  |
| `--buildTarget` | string | A build target used to configure Cypress component testing in the format of `project:target[:configuration]`. The build target should be an angular app. If not provided we will try to infer it from your projects usage. |  |
| `--generateTests` | boolean | Generate default component tests for existing components in the project | `false` |
| `--skipFormat` | boolean | Skip formatting files | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |

## `directive`
Creates a new Angular directive.

**Usage:**
```bash
nx generate @nx/angular:directive [options]
```

**Aliases:** `d`

**Arguments:**
```bash
nx generate @nx/angular:directive <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--export` | boolean | The declaring NgModule exports this directive. | `false` |
| `--module` | string | The filename of the declaring NgModule. |  |
| `--name` | string | The directive symbol name. Defaults to the last segment of the file path. |  |
| `--prefix` | string | A prefix to apply to generated selectors. |  |
| `--selector` | string | The HTML selector to use for this directive. |  |
| `--skipFormat` | boolean | Skip formatting of files. | `false` |
| `--skipImport` | boolean | Do not import this directive into the owning NgModule. | `false` |
| `--skipTests` | boolean | Do not create "spec.ts" test files for the new class. | `false` |
| `--standalone` | boolean | Whether the generated directive is standalone. | `true` |
| `--type` | string | Append a custom type to the directive's filename. It defaults to 'directive' for Angular versions below v20. For Angular v20 and above, no type is appended unless specified. |  |

## `federate-module`
Create a federated module, which is exposed by a Producer (remote) and can be subsequently loaded by a Consumer (host).

**Usage:**
```bash
nx generate @nx/angular:federate-module [options]
```

**Arguments:**
```bash
nx generate @nx/angular:federate-module <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--name` | string [**required**] | The name of the module. |  |
| `--remote` | string [**required**] | The name of the Producer (remote). |  |
| `--e2eTestRunner` | string | Test runner to use for end to end (e2e) tests of the Producer (remote) if it needs to be created. | `"cypress"` |
| `--host` | string | The Consumer (host) application for this Producer (remote). |  |
| `--remoteDirectory` | string | The directory of the new Producer (remote) application if one needs to be created. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--standalone` | boolean | Whether to generate the Producer (remote) application with standalone components if it needs to be created. | `true` |
| `--style` | string | The file extension to be used for style files for the Producer (remote) if one needs to be created. | `"css"` |
| `--unitTestRunner` | string | Test runner to use for unit tests of the Producer (remote) if it needs to be created. `vitest-analog` uses AnalogJS-based setup with `@nx/vitest`. It defaults to `vitest-analog` for Angular versions >= 21.0.0, otherwise `jest`. |  |

## `host`
Create an Angular Consumer (Host) Module Federation Application.

**Usage:**
```bash
nx generate @nx/angular:host [options]
```

**Aliases:** `consumer`

**Arguments:**
```bash
nx generate @nx/angular:host <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--addTailwind` | boolean | Whether to configure Tailwind CSS for the application. | `false` |
| `--backendProject` | string | Backend project that provides data to this application. This sets up `proxy.config.json`. |  |
| `--bundler` | string | The bundler to use for the host application. | `"webpack"` |
| `--dynamic` | boolean | Should the host application use dynamic federation? | `false` |
| `--e2eTestRunner` | string | Test runner to use for end to end (E2E) tests. | `"playwright"` |
| `--inlineStyle` | boolean | Specifies if the style will be in the ts file. | `false` |
| `--inlineTemplate` | boolean | Specifies if the template will be in the ts file. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"eslint"` |
| `--name` | string | The name to give to the Consumer (host) Angular application. |  |
| `--prefix` | string | The prefix to apply to generated selectors. |  |
| `--remotes` | array | The names of the Producers (remote) applications to add to the Consumer (host). |  |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--skipPostInstall` | boolean | Do not add or append `ngcc` to the `postinstall` script in `package.json`. | `false` |
| `--skipTests` | boolean | Skip creating spec files. | `false` |
| `--ssr` | boolean | Whether to configure SSR for the Consumer (host) application | `false` |
| `--standalone` | boolean | Whether to generate a Consumer (host) application that uses standalone components. | `true` |
| `--strict` | boolean | Create an application with stricter type checking and build optimization options. | `true` |
| `--style` | string | The file extension to be used for style files. | `"css"` |
| `--tags` | string | Add tags to the application (used for linting). |  |
| `--typescriptConfiguration` | boolean | Whether the module federation configuration and webpack configuration files should use TS. | `true` |
| `--unitTestRunner` | string | Test runner to use for unit tests. `vitest-analog` uses AnalogJS-based setup with `@nx/vitest`. It defaults to `vitest-analog` for Angular versions >= 21.0.0, otherwise `jest`. |  |
| `--viewEncapsulation` | string | Specifies the view encapsulation strategy. |  |
| `--zoneless` | boolean | Generate an application that does not use `zone.js`. It defaults to `true`. _Note: this is only supported in Angular versions >= 21.0.0_ |  |

## `library`
Creates an Angular library.

### Examples

###### Simple Library

Creates the `my-ui-lib` library with an `ui` tag:

```bash
nx g @nx/angular:library libs/my-ui-lib --tags=ui
```

###### Publishable Library

Creates the `my-lib` library that can be built producing an output following the Angular Package Format (APF) to be distributed as an NPM package:

```bash
nx g @nx/angular:library libs/my-lib --publishable --import-path=@my-org/my-lib
```

###### Buildable Library

Creates the `my-lib` library with support for incremental builds:

```bash
nx g @nx/angular:library libs/my-lib --buildable
```

###### Nested Folder & Import

Creates the `my-lib` library in the `nested` directory and sets the import path to `@myorg/nested/my-lib`:

```bash
nx g @nx/angular:library libs/nested/my-lib --importPath=@myorg/nested/my-lib
```

**Usage:**
```bash
nx generate @nx/angular:library [options]
```

**Aliases:** `lib`

**Arguments:**
```bash
nx generate @nx/angular:library <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--addModuleSpec` | boolean | Add a module spec file. | `false` |
| `--addTailwind` | boolean | Whether to configure Tailwind CSS for the application. It can only be used with buildable and publishable libraries. Non-buildable libraries will use the application's Tailwind configuration. | `false` |
| `--buildable` | boolean | Generate a buildable library. | `false` |
| `--changeDetection` | string | The change detection strategy to use in the new component. Disclaimer: This option is only valid when `--standalone` is set to `true`. | `"Default"` |
| `--compilationMode` | string | Specifies the compilation mode to use. If not specified, it will default to `partial` for publishable libraries and to `full` for buildable libraries. The `full` value can not be used for publishable libraries. |  |
| `--displayBlock` | boolean | Specifies if the component generated style will contain `:host { display: block; }`. Disclaimer: This option is only valid when `--standalone` is set to `true`. | `false` |
| `--flat` | boolean | Ensure the generated standalone component is not placed in a subdirectory. Disclaimer: This option is only valid when `--standalone` is set to `true`. | `false` |
| `--importPath` | string | The library name used to import it, like `@myorg/my-awesome-lib`. Must be a valid npm name. |  |
| `--inlineStyle` | boolean | Include styles inline in the component.ts file. Only CSS styles can be included inline. By default, an external styles file is created and referenced in the component.ts file. Disclaimer: This option is only valid when `--standalone` is set to `true`. | `false` |
| `--inlineTemplate` | boolean | Include template inline in the component.ts file. By default, an external template file is created and referenced in the component.ts file. Disclaimer: This option is only valid when `--standalone` is set to `true`. | `false` |
| `--lazy` | boolean | Add `RouterModule.forChild` when set to true, and a simple array of routes when set to false. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"eslint"` |
| `--name` | string | The name of the library. |  |
| `--parent` | string | Path to the parent route configuration using `loadChildren` or `children`, depending on what `lazy` is set to. |  |
| `--prefix` | string | The prefix to apply to generated selectors. |  |
| `--publishable` | boolean | Generate a publishable library. | `false` |
| `--routing` | boolean | Add router configuration. See `lazy` for more information. | `false` |
| `--selector` | string | The HTML selector to use for this component. Disclaimer: This option is only valid when `--standalone` is set to `true`. |  |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipModule` | boolean | Whether to skip the creation of a default module when generating the library. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--skipSelector` | boolean | Specifies if the component should have a selector or not. Disclaimer: This option is only valid when `--standalone` is set to `true`. | `false` |
| `--skipTests` | boolean | Do not create `spec.ts` test files for the new component. Disclaimer: This option is only valid when `--standalone` is set to `true`. | `false` |
| `--skipTsConfig` | boolean | Do not update `tsconfig.json` for development experience. | `false` |
| `--standalone` | boolean | Generate a library that uses a standalone component instead of a module as the entry point. | `true` |
| `--strict` | boolean | Create a library with stricter type checking and build optimization options. | `true` |
| `--style` | string | The file extension or preprocessor to use for style files, or `none` to skip generating the style file. Disclaimer: This option is only valid when `--standalone` is set to `true`. | `"css"` |
| `--tags` | string | Add tags to the library (used for linting). |  |
| `--unitTestRunner` | string | Test runner to use for unit tests. `vitest-angular` uses the `@nx/angular:unit-test` executor (requires Angular v21+ and a buildable/publishable library). `vitest-analog` uses AnalogJS-based setup with `@nx/vitest`. It defaults to `vitest-angular` for buildable/publishable libraries on Angular >= 21.0.0, `vitest-analog` for non-buildable libraries on Angular >= 21.0.0, otherwise `jest`. |  |
| `--viewEncapsulation` | string | The view encapsulation strategy to use in the new component. Disclaimer: This option is only valid when `--standalone` is set to `true`. |  |

## `library-secondary-entry-point`
Creates a secondary entry point for an Angular publishable library.

### Examples

###### Basic Usage

Create a secondary entrypoint named `button` in the `ui` library.

```bash
nx g @nx/angular:library-secondary-entry-point --library=ui --name=button
```

###### Skip generating module

Create a secondary entrypoint named `button` in the `ui` library but skip creating an NgModule.

```bash
nx g @nx/angular:library-secondary-entry-point --library=ui --name=button --skipModule
```

**Usage:**
```bash
nx generate @nx/angular:library-secondary-entry-point [options]
```

**Aliases:** `secondary-entry-point`, `entry-point`

**Arguments:**
```bash
nx generate @nx/angular:library-secondary-entry-point <name> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--library` | string [**required**] | The name of the library to create the secondary entry point for. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipModule` | boolean | Skip generating a module for the secondary entry point. | `false` |

## `move`
Move an Angular project to another folder in the workspace.

**Usage:**
```bash
nx generate @nx/angular:move [options]
```

**Aliases:** `mv`

**Arguments:**
```bash
nx generate @nx/angular:move <destination> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--projectName` | string [**required**] | The name of the Angular project to move. |  |
| `--importPath` | string | The new import path to use in the `tsconfig.base.json`. |  |
| `--newProjectName` | string | The new name of the project after the move. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--updateImportPath` | boolean | Update the import path to reflect the new location. | `true` |

## `ngrx`
Adds NgRx support to an application or library.

**Usage:**
```bash
nx generate @nx/angular:ngrx [options]
```

**Arguments:**
```bash
nx generate @nx/angular:ngrx <name> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--barrels` | boolean | Use barrels to re-export actions, state and selectors. | `false` |
| `--directory` | string | The name of the folder used to contain/group the generated NgRx files. | `"+state"` |
| `--facade` | boolean | Create a Facade class for the the feature. | `false` |
| `--minimal` | boolean | Only register the root state management setup or feature state. | `true` |
| `--module` | string | The path to the `NgModule` where the feature state will be registered. The host directory will create/use the new state directory. |  |
| `--parent` | string | The path to the file where the state will be registered. For NgModule usage, this will be your `app-module.ts` for your root state, or your Feature Module for feature state. For Standalone API usage, this will be your `app.config.ts` file for your root state, or the Routes definition file for your feature state. The host directory will create/use the new state directory. |  |
| `--root` | boolean | Setup root or feature state management with NgRx. | `false` |
| `--route` | string | The route that the Standalone NgRx Providers should be added to. | `"''"` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipImport` | boolean | Generate NgRx feature files without registering the feature in the NgModule. | `false` |
| `--skipPackageJson` | boolean | Do not update the `package.json` with NgRx dependencies. | `false` |

## `ngrx-feature-store`
Add an NgRx Feature Store to an application or library.

**Usage:**
```bash
nx generate @nx/angular:ngrx-feature-store [options]
```

**Arguments:**
```bash
nx generate @nx/angular:ngrx-feature-store <name> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--barrels` | boolean | Use barrels to re-export actions, state and selectors. | `false` |
| `--directory` | string | The name of the folder used to contain/group the generated NgRx files. | `"+state"` |
| `--facade` | boolean | Create a Facade class for the the feature. | `false` |
| `--minimal` | boolean | Only register the feature state. | `false` |
| `--parent` | string | The path to the file where the state will be registered. For NgModule usage, this will be your Feature Module. For Standalone API usage, this will be your Routes definition file for your feature state. The host directory will create/use the new state directory. |  |
| `--route` | string | The route that the Standalone NgRx Providers should be added to. | `"''"` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipImport` | boolean | Generate NgRx feature files without registering the feature in the NgModule. | `false` |
| `--skipPackageJson` | boolean | Do not update the `package.json` with NgRx dependencies. | `false` |

## `ngrx-root-store`
Adds NgRx support to an application.

**Usage:**
```bash
nx generate @nx/angular:ngrx-root-store [options]
```

**Arguments:**
```bash
nx generate @nx/angular:ngrx-root-store <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--addDevTools` | boolean | Instrument the Store Devtools. | `false` |
| `--directory` | string | The name of the folder used to contain/group the generated NgRx files. | `"+state"` |
| `--facade` | boolean | Create a Facade class for the the feature. | `false` |
| `--minimal` | boolean | Only register the root state management setup or also generate a global feature state. | `true` |
| `--name` | string | Name of the NgRx state, such as `products` or `users`. Recommended to use the plural form of the name. |  |
| `--route` | string | The route that the Standalone NgRx Providers should be added to. | `"''"` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipImport` | boolean | Generate NgRx feature files without registering the feature in the NgModule. | `false` |
| `--skipPackageJson` | boolean | Do not update the `package.json` with NgRx dependencies. | `false` |

## `pipe`
Creates an Angular pipe.

**Usage:**
```bash
nx generate @nx/angular:pipe [options]
```

**Aliases:** `p`

**Arguments:**
```bash
nx generate @nx/angular:pipe <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--export` | boolean | The declaring NgModule exports this pipe. | `false` |
| `--module` | string | The filename of the declaring NgModule. |  |
| `--name` | string | The pipe symbol name. Defaults to the last segment of the file path. |  |
| `--skipFormat` | boolean | Skip formatting of files. | `false` |
| `--skipImport` | boolean | Do not import this pipe into the owning NgModule. | `false` |
| `--skipTests` | boolean | Do not create "spec.ts" test files for the new pipe. | `false` |
| `--standalone` | boolean | Whether the generated pipe is standalone. | `true` |
| `--typeSeparator` | string | The separator character to use before the type within the generated file's name. For example, if you set the option to `.`, the file will be named `example.pipe.ts`. It defaults to '-' for Angular v20+. For versions below v20, it defaults to '.'. |  |

## `remote`
Create an Angular Producer (Remote) Module Federation Application.

**Usage:**
```bash
nx generate @nx/angular:remote [options]
```

**Aliases:** `producer`

**Arguments:**
```bash
nx generate @nx/angular:remote <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--addTailwind` | boolean | Whether to configure Tailwind CSS for the application. | `false` |
| `--backendProject` | string | Backend project that provides data to this application. This sets up `proxy.config.json`. |  |
| `--bundler` | string | The bundler to use for the remote application. | `"webpack"` |
| `--e2eTestRunner` | string | Test runner to use for end to end (E2E) tests. | `"playwright"` |
| `--host` | string | The name of the Consumer (host) app to attach this Producer (remote) app to. |  |
| `--inlineStyle` | boolean | Specifies if the style will be in the ts file. | `false` |
| `--inlineTemplate` | boolean | Specifies if the template will be in the ts file. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"eslint"` |
| `--name` | string | The name to give to the Producer (remote) Angular app. |  |
| `--port` | number | The port on which this app should be served. |  |
| `--prefix` | string | The prefix to apply to generated selectors. |  |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--skipTests` | boolean | Skip creating spec files. | `false` |
| `--ssr` | boolean | Whether to configure SSR for the Producer (remote) application to be consumed by a Consumer (host) application using SSR. | `false` |
| `--standalone` | boolean | Whether to generate a Producer (remote) application with standalone components. | `true` |
| `--strict` | boolean | Create an application with stricter type checking and build optimization options. | `true` |
| `--style` | string | The file extension to be used for style files. | `"css"` |
| `--tags` | string | Add tags to the application (used for linting). |  |
| `--typescriptConfiguration` | boolean | Whether the module federation configuration and webpack configuration files should use TS. | `true` |
| `--unitTestRunner` | string | Test runner to use for unit tests. `vitest-analog` uses AnalogJS-based setup with `@nx/vitest`. It defaults to `vitest-analog` for Angular versions >= 21.0.0, otherwise `jest`. |  |
| `--viewEncapsulation` | string | Specifies the view encapsulation strategy. |  |
| `--zoneless` | boolean | Generate an application that does not use `zone.js`. It defaults to `true`. _Note: this is only supported in Angular versions >= 21.0.0_ |  |

## `scam`
Creates a new Angular SCAM.

**Usage:**
```bash
nx generate @nx/angular:scam [options]
```

**Arguments:**
```bash
nx generate @nx/angular:scam <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--changeDetection` | string | The change detection strategy to use in the new component. | `"Default"` |
| `--displayBlock` | boolean | Specifies if the style will contain `:host { display: block; }`. | `false` |
| `--export` | boolean | Specifies if the SCAM should be exported from the project's entry point (normally `index.ts`). It only applies to libraries. | `true` |
| `--inlineScam` | boolean | Create the `NgModule` in the same file as the component. | `true` |
| `--inlineStyle` | boolean | Include styles inline in the `component.ts` file. Only CSS styles can be included inline. By default, an external styles file is created and referenced in the `component.ts` file. | `false` |
| `--inlineTemplate` | boolean | Include template inline in the `component.ts` file. By default, an external template file is created and referenced in the `component.ts` file. | `false` |
| `--name` | string | The component symbol name. Defaults to the last segment of the file path. |  |
| `--prefix` | string | The prefix to apply to the generated component selector. |  |
| `--selector` | string | The `HTML` selector to use for this component. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipSelector` | boolean | Specifies if the component should have a selector or not. | `false` |
| `--skipTests` | boolean | Do not create `spec.ts` test files for the new component. | `false` |
| `--style` | string | The file extension or preprocessor to use for style files, or 'none' to skip generating the style file. | `"css"` |
| `--type` | string | Append a custom type to the component's filename. It defaults to 'component' for Angular versions below v20. For Angular v20 and above, no type is appended unless specified. |  |
| `--viewEncapsulation` | string | The view encapsulation strategy to use in the new component. |  |

## `scam-directive`
Creates a new, generic Angular directive definition in the given or default project.

**Usage:**
```bash
nx generate @nx/angular:scam-directive [options]
```

**Arguments:**
```bash
nx generate @nx/angular:scam-directive <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--export` | boolean | Specifies if the SCAM should be exported from the project's entry point (normally `index.ts`). It only applies to libraries. | `true` |
| `--inlineScam` | boolean | Create the `NgModule` in the same file as the Directive. | `true` |
| `--name` | string | The directive symbol name. Defaults to the last segment of the file path. |  |
| `--prefix` | string | The prefix to apply to the generated directive selector. |  |
| `--selector` | string | The `HTML` selector to use for this directive. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipTests` | boolean | Do not create `spec.ts` test files for the new directive. | `false` |
| `--type` | string | Append a custom type to the directive's filename. It defaults to 'directive' for Angular versions below v20. For Angular v20 and above, no type is appended unless specified. |  |

## `scam-pipe`
Creates a new, generic Angular pipe definition in the given or default project.

**Usage:**
```bash
nx generate @nx/angular:scam-pipe [options]
```

**Arguments:**
```bash
nx generate @nx/angular:scam-pipe <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--export` | boolean | Specifies if the SCAM should be exported from the project's entry point (normally `index.ts`). It only applies to libraries. | `true` |
| `--inlineScam` | boolean | Create the NgModule in the same file as the Pipe. | `true` |
| `--name` | string | The pipe symbol name. Defaults to the last segment of the file path. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipTests` | boolean | Do not create `spec.ts` test files for the new pipe. | `false` |
| `--typeSeparator` | string | The separator character to use before the type within the generated file's name. For example, if you set the option to `.`, the file will be named `example.pipe.ts`. It defaults to '-' for Angular v20+. For versions below v20, it defaults to '.'. |  |

## `scam-to-standalone`
Convert an Inline SCAM to a Standalone Component.

### Examples

###### Basic Usage

This generator allows you to convert an Inline SCAM to a Standalone Component. It's important that the SCAM you wish to convert has it's NgModule within the same file for the generator to be able to correctly convert the component to Standalone.

```bash

nx g @nx/angular:scam-to-standalone --component=libs/mylib/src/lib/myscam/myscam.ts --project=mylib

```

**Usage:**
```bash
nx generate @nx/angular:scam-to-standalone [options]
```

**Arguments:**
```bash
nx generate @nx/angular:scam-to-standalone <component> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string | The project containing the SCAM. |  |
| `--skipFormat` | boolean | Skip formatting the workspace after the generator completes. |  |

## `setup-mf`
Create Module Federation configuration files for given Angular Application.

### Examples

The `setup-mf` generator is used to add Module Federation support to existing applications.

###### Convert to Host

To convert an existing application to a host application, run the following

```bash
nx g setup-mf myapp --mfType=host --routing=true
```

###### Convert to Remote

To convert an existing application to a remote application, run the following

```bash
nx g setup-mf myapp --mfType=remote --routing=true
```

###### Convert to Remote and attach to a host application

To convert an existing application to a remote application and attach it to an existing host application name `myhostapp`, run the following

```bash
nx g setup-mf myapp --mfType=remote --routing=true --host=myhostapp
```

###### Convert to Host and attach to existing remote applications

To convert an existing application to a host application and attaching existing remote applications named `remote1` and `remote2`, run the following

```bash
nx g setup-mf myapp --mfType=host --routing=true --remotes=remote1,remote2
```

**Usage:**
```bash
nx generate @nx/angular:setup-mf [options]
```

**Arguments:**
```bash
nx generate @nx/angular:setup-mf <appName> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--mfType` | string [**required**] | Type of application to generate the Module Federation configuration for. | `"remote"` |
| `--e2eProjectName` | string | The project name of the associated E2E project for the application. This is only required for Cypress E2E projects that do not follow the naming convention `<appName>-e2e`. |  |
| `--federationType` | string | Use either Static or Dynamic Module Federation pattern for the application. | `"static"` |
| `--host` | string | The name of the host application that the remote application will be consumed by. |  |
| `--port` | number | The port at which the remote application should be served. |  |
| `--prefix` | string | The prefix to use for any generated component. |  |
| `--remotes` | array | A list of remote application names that the Consumer (host) application should consume. |  |
| `--routing` | boolean | Generate a routing setup to allow a Consumer (host) application to route to the Producer (remote) application. |  |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons. | `false` |
| `--skipE2E` | boolean | Do not set up E2E related config. | `false` |
| `--skipFormat` | boolean | Skip formatting the workspace after the generator completes. |  |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--standalone` | boolean | Whether the application is a standalone application. | `true` |
| `--typescriptConfiguration` | boolean | Whether the module federation configuration and webpack configuration files should use TS. | `true` |

## `setup-ssr`
Create the additional configuration required to enable SSR via Angular Universal for an Angular application.

**Usage:**
```bash
nx generate @nx/angular:setup-ssr [options]
```

**Arguments:**
```bash
nx generate @nx/angular:setup-ssr <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--hydration` | boolean | Set up Hydration for the SSR application. | `true` |
| `--main` | string | The name of the main entry-point file. | `"main.server.ts"` |
| `--rootModuleClassName` | string | The name of the root module class. | `"AppServerModule"` |
| `--rootModuleFileName` | string | The name of the root module file | `"app.server.module.ts"` |
| `--serverFileName` | string | The name of the Express server file. | `"server.ts"` |
| `--serverPort` | number | The port for the Express server. | `4000` |
| `--serverRouting` | boolean | Creates a server application using the Server Routing and App Engine APIs for application using the `application` builder (Developer Preview). _Note: this is only supported in Angular versions 19.x.x_. From Angular 20 onwards, SSR will always enable server routing when using the `application` builder. |  |
| `--skipFormat` | boolean | Skip formatting the workspace after the generator completes. |  |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--standalone` | boolean | Use Standalone Components to bootstrap SSR. |  |

## `setup-tailwind`
Adds the Tailwind CSS configuration files for a given Angular project and installs, if needed, the packages required for Tailwind CSS to work.

### Examples

The `setup-tailwind` generator can be used to add [Tailwind](https://tailwindcss.com) configuration to apps and publishable libraries.

###### Standard Setup

To generate a standard Tailwind setup, just run the following command.

```bash
nx g @nx/angular:setup-tailwind myapp
```

###### Specifying the Styles Entrypoint

To specify the styles file that should be used as the entrypoint for Tailwind, simply pass the `--stylesEntryPoint` flag, relative to workspace root.

```bash
nx g @nx/angular:setup-tailwind myapp --stylesEntryPoint=apps/myapp/src/styles.css
```

**Usage:**
```bash
nx generate @nx/angular:setup-tailwind [options]
```

**Arguments:**
```bash
nx generate @nx/angular:setup-tailwind <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--buildTarget` | string | The name of the target used to build the project. This option only applies to buildable/publishable libraries. | `"build"` |
| `--skipFormat` | boolean | Skips formatting the workspace after the generator completes. |  |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--stylesEntryPoint` | string | Path to the styles entry point relative to the workspace root. If not provided the generator will do its best to find it and it will error if it can't. This option only applies to applications. |  |

## `stories`
Creates Storybook stories/specs for all Angular components declared in a project.

This generator will generate stories for all your components in your project. The stories will be generated using [Component Story Format 3 (CSF3)](https://storybook.js.org/blog/storybook-csf3-is-here/).

```bash
nx g @nx/angular:stories project-name
```

You can read more about how this generator works, in the [Storybook for Angular overview page](/recipes/storybook/overview-angular#auto-generate-stories).

When running this generator, you will be prompted to provide the following:

- The `name` of the project you want to generate the configuration for.
- Whether you want to set up [Storybook interaction tests](https://storybook.js.org/docs/angular/writing-tests/interaction-testing) (`interactionTests`). If you choose `yes`, a `play` function will be added to your stories, and all the necessary dependencies will be installed. You can read more about this in the [Nx Storybook interaction tests documentation page](/recipes/storybook/storybook-interaction-tests#setup-storybook-interaction-tests).

You must provide a `name` for the generator to work.

By default, this generator will also set up [Storybook interaction tests](https://storybook.js.org/docs/angular/writing-tests/interaction-testing). If you don't want to set up Storybook interaction tests, you can pass the `--interactionTests=false` option, but it's not recommended.

There are a number of other options available. Let's take a look at some examples.

### Examples

#### Ignore certain paths when generating stories

```bash
nx g @nx/angular:stories ui --ignorePaths=libs/ui/src/not-stories/**,**/**/src/**/*.other.*
```

This will generate stories for all the components in the `ui` project, except for the ones in the `libs/ui/src/not-stories` directory, and also for components that their file name is of the pattern `*.other.*`.

This is useful if you have a project that contains components that are not meant to be used in isolation, but rather as part of a larger component.

By default, Nx will ignore the following paths:

```text
*.stories.ts, *.stories.tsx, *.stories.js, *.stories.jsx, *.stories.mdx
```

but you can change this behaviour easily, as explained above.

**Usage:**
```bash
nx generate @nx/angular:stories [options]
```

**Arguments:**
```bash
nx generate @nx/angular:stories <name> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--ignorePaths` | array | Paths to ignore when looking for components. | `["*.stories.ts,*.stories.tsx,*.stories.js,*.stories.jsx,*.stories.mdx"]` |
| `--interactionTests` | boolean | Set up Storybook interaction tests. | `true` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |

## `storybook-configuration`
Adds Storybook configuration to a project to be able to use and create stories.

This generator will set up Storybook for your **Angular** project. By default, Storybook v10 is used.

```bash
nx g @nx/angular:storybook-configuration project-name
```

You can read more about how this generator works, in the [Storybook for Angular overview page](/recipes/storybook/overview-angular#generate-storybook-configuration-for-an-angular-project).

When running this generator, you will be prompted to provide the following:

- The `name` of the project you want to generate the configuration for.
- Whether you want to set up [Storybook interaction tests](https://storybook.js.org/docs/angular/writing-tests/interaction-testing) (`interactionTests`). If you choose `yes`, a `play` function will be added to your stories, and all the necessary dependencies will be installed. Also, a `test-storybook` target will be generated in your project's `project.json`, with a command to invoke the [Storybook `test-runner`](https://storybook.js.org/docs/angular/writing-tests/test-runner). You can read more about this in the [Nx Storybook interaction tests documentation page](/recipes/storybook/storybook-interaction-tests#setup-storybook-interaction-tests).
- Whether you want to `generateStories` for the components in your project. If you choose `yes`, a `.stories.ts` file will be generated next to each of your components in your project.

You must provide a `name` for the generator to work.

By default, this generator will also set up [Storybook interaction tests](https://storybook.js.org/docs/angular/writing-tests/interaction-testing). If you don't want to set up Storybook interaction tests, you can pass the `--interactionTests=false` option, but it's not recommended.

There are a number of other options available. Let's take a look at some examples.

### Examples

#### Generate Storybook configuration

```bash
nx g @nx/angular:storybook-configuration ui
```

This will generate Storybook configuration for the `ui` project using TypeScript for the Storybook configuration files (the files inside the `.storybook` directory, eg. `.storybook/main.ts`).

#### Ignore certain paths when generating stories

```bash
nx g @nx/angular:storybook-configuration ui --generateStories=true --ignorePaths=libs/ui/src/not-stories/**,**/**/src/**/*.other.*,apps/my-app/**/*.something.ts
```

This will generate a Storybook configuration for the `ui` project and generate stories for all components in the `libs/ui/src/lib` directory, except for the ones in the `libs/ui/src/not-stories` directory, and the ones in the `apps/my-app` directory that end with `.something.ts`, and also for components that their file name is of the pattern `*.other.*`.

This is useful if you have a project that contains components that are not meant to be used in isolation, but rather as part of a larger component.

By default, Nx will ignore the following paths:

```text
*.stories.ts, *.stories.tsx, *.stories.js, *.stories.jsx, *.stories.mdx
```

but you can change this behaviour easily, as explained above.

#### Generate Storybook configuration using JavaScript

```bash
nx g @nx/angular:storybook-configuration ui --tsConfiguration=false
```

By default, our generator generates TypeScript Storybook configuration files. You can choose to use JavaScript for the Storybook configuration files of your project (the files inside the `.storybook` directory, eg. `.storybook/main.js`).

**Usage:**
```bash
nx generate @nx/angular:storybook-configuration [options]
```

**Arguments:**
```bash
nx generate @nx/angular:storybook-configuration <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--configureStaticServe` | boolean | Specifies whether to configure a static file server target for serving storybook. Helpful for speeding up CI build/test times. | `true` |
| `--generateStories` | boolean | Specifies whether to automatically generate `*.stories.ts` files for components declared in this project or not. | `true` |
| `--ignorePaths` | array | Paths to ignore when looking for components. | `["*.stories.ts,*.stories.tsx,*.stories.js,*.stories.jsx,*.stories.mdx"]` |
| `--interactionTests` | boolean | Set up Storybook interaction tests. | `true` |
| `--linter` | string | The tool to use for running lint checks. | `"eslint"` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--tsConfiguration` | boolean | Configure your project with TypeScript. Generate main.ts and preview.ts files, instead of main.js and preview.js. | `true` |

## `web-worker`
Creates a new, generic web worker definition in the given or default project.

### Examples

###### Simple Usage

The basic usage of the `web-worker` generator is defined below. You must provide a name for the web worker and the project to assign it to.

```bash
nx g @nx/angular:web-worker myWebWorker --project=myapp
```

**Usage:**
```bash
nx generate @nx/angular:web-worker [options]
```

**Arguments:**
```bash
nx generate @nx/angular:web-worker <name> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string [**required**] | The name of the project. |  |
| `--path` | string | The path at which to create the worker file, relative to the current workspace. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--snippet` | boolean | Add a worker creation snippet in a sibling file of the same name. | `true` |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/angular:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/angular/guides.md -->
## Guides

{% index_page_cards path="technologies/angular/guides" /%}

---
<!-- source: https://nx.dev/docs/technologies/angular/guides/angular-nx-version-matrix.md -->
## Nx and Angular Versions

The latest version of Nx supports the [actively supported versions of Angular (current and LTS versions)](https://angular.dev/reference/releases#actively-supported-versions). Workspaces in any of those versions are recommended to use the latest version of Nx to benefit from all the new features and fixes.

{% aside type="note" title="Older Nx and Angular versions" %}
The support for multiple versions of Angular in the latest version of Nx was added in **v15.7.0** and started by supporting Angular v14 and v15. If your workspace is in an older version of Angular or you can't update to the latest version of Nx for some reason, please have a look at the next section to know which version of Nx to use.
{% /aside %}

## Nx and Angular version compatibility matrix

Below is a reference table that matches versions of Angular to the version of Nx that is compatible with it. The table shows the version of Angular, the recommended version of Nx to use and the range of Nx versions that support the version of Angular.

We provide a recommended version, and it is usually the latest minor version of Nx in the range provided because there will have been bug fixes added since the first release in the range.

| Angular Version | **Nx Version _(recommended)_** | Nx Version _(range)_                     |
| --------------- | ------------------------------ | ---------------------------------------- |
| ~21.2.0         | **latest**                     | >=22.6.0 <=latest                        |
| ~21.1.0         | **latest**                     | >=22.4.0 <=latest                        |
| ~21.0.0         | **latest**                     | >=22.3.0 <=latest                        |
| ~20.3.0         | **latest**                     | >=21.6.1 <=latest                        |
| ~20.2.0         | **latest**                     | >=21.5.1 <=latest                        |
| ~20.1.0         | **latest**                     | >=21.3.0 <=latest                        |
| ~20.0.0         | **latest**                     | >=21.2.0 <=latest                        |
| ~19.2.0         | **latest**                     | >=20.5.0 <=latest                        |
| ~19.1.0         | **latest**                     | >=20.4.0 <=latest                        |
| ~19.0.0         | **latest**                     | >=20.2.0 <=latest                        |
| ~18.2.0         | **~22.2.0**                    | >=19.6.0 <22.3.0                         |
| ~18.1.0         | **~22.2.0**                    | >=19.5.0 <22.3.0                         |
| ~18.0.0         | **~22.2.0**                    | >=19.1.0 <22.3.0                         |
| ~17.3.0         | **~21.1.0**                    | >=18.2.0 <21.2.0                         |
| ~17.2.0         | **~21.1.0**                    | >=18.1.1 <21.2.0                         |
| ~17.1.0         | **~21.1.0**                    | >=17.3.0 <21.2.0                         |
| ~17.0.0         | **~21.1.0**                    | >=17.1.0 <21.2.0                         |
| ~16.2.0         | **~20.1.0**                    | >=16.7.0 <20.2.0                         |
| ~16.1.0         | **~20.1.0**                    | >=16.4.0 <20.2.0                         |
| ~16.0.0         | **~20.1.0**                    | >=16.1.0 <20.2.0                         |
| ~15.2.0         | **~19.0.0**                    | >=15.8.0 <19.1.0                         |
| ~15.1.0         | **~19.0.0**                    | >=15.5.0 <19.1.0                         |
| ~15.0.0         | **~19.0.0**                    | >=15.2.0 <=15.4.8 \|\| >=15.7.0 <19.1.0  |
| ~14.2.0         | **~17.0.0**                    | >=14.6.0 <=15.1.1 \|\| >=15.7.0 <17.1.0  |
| ~14.1.0         | **~17.0.0**                    | >=14.5.0 <=14.5.10 \|\| >=15.7.0 <17.1.0 |
| ~14.0.0         | **~17.0.0**                    | >=14.2.1 <=14.4.3 \|\| >=15.7.0 <17.1.0  |
| ^13.0.0         | **14.1.9**                     | >=13.2.0 <=14.1.9                        |
| ^12.0.0         | **13.1.4**                     | >=12.3.0 <=13.1.4                        |
| ^11.0.0         | **12.2.0**                     | >=11.0.0 <=12.2.0                        |
| ^10.0.0         | **10.4.15**                    | >=9.7.0 <=10.4.15                        |
| ^9.0.0          | **9.6.0**                      | >=8.12.4 <=9.6.0                         |
| ^8.0.0          | **8.12.2**                     | >=8.7.0 <=8.12.2                         |

Additionally, you can check the supported versions of Node and Typescript for the version of Angular you are using in the [Angular docs](https://angular.dev/reference/versions#actively-supported-versions).

## Nx and Angular Rspack version compatibility matrix

Below is a reference table that matches versions of [Angular Rspack](/docs/technologies/angular/angular-rspack/introduction) to the versions of Angular (lower than 20.2.0) and Nx that is compatible with it.

{% aside type="note" title="Newer Angular versions" %}
The table below only shows the version of Angular Rspack that is compatible with Angular versions lower than 20.2.0. Starting with Angular 20.2.0, the Angular Rspack version to install is aligned with the Nx version, so refer to [the table above](#nx-and-angular-version-compatibility-matrix).
{% /aside %}

| Angular Version | Angular Rspack Version | Nx Version          |
| --------------- | ---------------------- | ------------------- |
| ~20.1.0         | **~21.2.0**            | >= 21.1.0 <= 21.5.0 |
| ~20.0.0         | **~21.1.0**            | >= 21.1.0 <= 21.5.0 |
| ~19.2.0         | **~20.8.0**            | >= 20.8.1 <= 21.1.0 |
| ~19.2.0         | **~20.7.0**            | >= 20.8.1 <= 21.1.0 |
| ~19.2.0         | **~20.6.0**            | >= 20.6.0 <= 21.1.0 |

---
<!-- source: https://nx.dev/docs/technologies/angular/guides/dynamic-module-federation-with-angular.md -->
## Advanced Angular Micro Frontends with Dynamic Module Federation

Dynamic Module Federation is a technique that allows an application to determine the location of its remote applications at runtime. It helps to achieve the use case of **"Build once, deploy everywhere"**.

"Build once, deploy everywhere" is the concept of being able to create a single build artifact of your application and deploy it to multiple environments such as staging and production.

The difficulty in achieving this with a Micro Frontend Architecture using Static Module Federation is that our Remote applications will have a different location (or URL) in each environment. Previously, to account for this, we would have had to specify the deployed location of the Remote applications and rebuild the application for the target environment.

Walk through how the concept of "Build once, deploy everywhere" can be easily achieved in a Micro Frontend Architecture that uses Dynamic Module Federation.

## Aim

The aim of this guide is three-fold. We want to be able to:

- Set up a Micro Frontend with Static Module Federation
- Transform an existing Static Module Federation setup to use Dynamic Federation
- Generate a new Micro Frontend application that uses Dynamic Federation

## What we'll build

To achieve the aims, we will do the following:

- Create a Static Federation Micro Frontend Architecture
- Change the **Dashboard** application to use Dynamic Federation
- Generate a new **Employee Dashboard** application that will use Dynamic Federation
  - It should use the existing **Login** application.
  - It should use a new **Todo** application.

## Final code

Here's the source code of the final result for this guide.

{% github_repository url="https://github.com/Coly010/nx-ng-dyn-fed" /%}

## First steps

### Create an Nx workspace

To start with, we need to create a new Nx Workspace and add the Nx Angular plugin. We can do this easily with:

{% tabs %}
{% tabitem label="npm" %}

```text {% title="npx create-nx-workspace@latest ng-mf --preset=apps" frame="terminal" %}
 NX   Let's create a new workspace [https://nx.dev/getting-started/intro]

✔ Which CI provider would you like to use? · skip
✔ Would you like remote caching to make your build faster? · skip

```

Next run:

```shell
cd ng-mf
npx nx add @nx/angular
```

{% /tabitem %}
{% tabitem label="yarn" %}

```text {% title="yarn create nx-workspace ng-mf --preset=apps" frame="terminal" %}
 NX   Let's create a new workspace [https://nx.dev/getting-started/intro]

✔ Which CI provider would you like to use? · skip
✔ Would you like remote caching to make your build faster? · skip

```

Next run:

```shell
cd ng-mf
yarn nx add @nx/angular
```

{% /tabitem %}
{% tabitem label="pnpm" %}

```text {% title="pnpx create-nx-workspace@latest ng-mf --preset=apps" frame="terminal" %}
 NX   Let's create a new workspace [https://nx.dev/getting-started/intro]

✔ Which CI provider would you like to use? · skip
✔ Would you like remote caching to make your build faster? · skip

```

Next run:

```shell
cd ng-mf
pnpx nx add @nx/angular
```

{% /tabitem %}
{% /tabs %}

### Creating our applications

We need to generate two applications that support Module Federation.

We'll start with the **Admin Dashboard** application which will act as a host application for the Micro-Frontends (_MFEs_):

```shell
nx g @nx/angular:host apps/dashboard --prefix=ng-mf
```

{% aside type="note" title="Running nx commands" %}
The terminal examples will show `nx` being run as if it is installed globally. If you have not installed Nx globally (not required), you can use your package manager to run the `nx` local binary:

- NPM: `npx nx ...`
- Yarn: `yarn nx ...`
- PNPM: `pnpm nx ...`

{% /aside %}

The `host` generator will create and modify the files needed to set up the Angular application.

Now, let's generate the **Login** application as a remote application that will be consumed by the **Dashboard** host application.

```shell
nx g @nx/angular:remote apps/login --prefix=ng-mf --host=dashboard
```

Note how we provided the `--host=dashboard` option. This tells the generator that this remote application will be consumed by the **Dashboard** application. The generator performed the following changes to automatically link these two applications together:

- Added the remote to the `apps/dashboard/module-federation.config.ts` file
- Added a TypeScript path mapping to the root tsconfig file
- Added a new route to the `apps/dashboard/src/app/app.routes.ts` file

## What was generated?

Let's take a closer look after generating each application.

For both applications, the generators did the following:

- Created the standard Angular application files
- Added a `module-federation.config.ts` file
- Added a `webpack.config.ts` and `webpack.prod.config.ts`
- Added a `src/bootstrap.ts` file
- Moved the code that is normally in `src/main.ts` to `src/bootstrap.ts`
- Changed `src/main.ts` to dynamically import `src/bootstrap.ts` _(this is required for the Module Federation to load versions of shared libraries correctly)_
- Updated the `build` target in the `project.json` to use the `@nx/angular:webpack-browser` executor _(this is required to support passing a custom Webpack configuration to the Angular compiler)_
- Updated the `serve` target to use `@nx/angular:dev-server` _(this is required as we first need Webpack to build the application with our custom Webpack configuration)_

The key differences reside within the configuration of the Module Federation Plugin within each application's `module-federation.config.ts`.

We can see the following in the **Login** micro frontend configuration:

```ts
// apps/login/module-federation.config.ts
import { ModuleFederationConfig } from '@nx/module-federation';

const config: ModuleFederationConfig = {
  name: 'login',
  exposes: {
    './Routes': 'apps/login/src/app/remote-entry/entry.routes.ts',
  },
};

export default config;
```

Taking a look at each property of the configuration in turn:

- `name` is the name that Webpack assigns to the remote application. It **must** match the name of the project.
- `exposes` is the list of source files that the remote application exposes to consuming shell applications for their own use.

This config is then used in the `webpack.config.ts` file:

```ts
// apps/login/webpack.config.ts
import { withModuleFederation } from '@nx/module-federation/angular';
import config from './module-federation.config';

export default withModuleFederation(config, { dts: false });
```

We can see the following in the **Dashboard** micro frontend configuration:

```ts
// apps/dashboard/module-federation.config.ts
import { ModuleFederationConfig } from '@nx/module-federation';

const config: ModuleFederationConfig = {
  name: 'dashboard',
  remotes: ['login'],
};

export default config;
```

The key difference to note with the **Dashboard** configuration is the `remotes` array. This is where you list the remote applications you want to consume in your host application.

You give it a name that you can reference in your code, in this case `login`. Nx will find where it is served.

Now that we have our applications generated, let's move on to building out some functionality for each.

## Adding functionality

We'll start by building the **Login** application, which will consist of a login form and some very basic and insecure authorization logic.

### User library

Let's create a user data-access library that will be shared between the host application and the remote application.
This will be used to determine if there is an authenticated user as well as providing logic for authenticating the user.

```shell
nx g @nx/angular:lib libs/shared/data-access-user
```

This will scaffold a new library for us to use.

We need an Angular Service that we will use to hold state:

```shell
nx g @nx/angular:service user --project=data-access-user
```

This will create the `libs/shared/data-access-user/src/lib/user-auth.ts` file. Change its contents to match:

```ts
// libs/shared/data-access-user/src/lib/user-auth.ts
import { Injectable } from '@angular/core';
import { BehaviorSubject } from 'rxjs';

@Injectable({ providedIn: 'root' })
export class UserAuth {
  private isUserLoggedIn = new BehaviorSubject(false);
  isUserLoggedIn$ = this.isUserLoggedIn.asObservable();

  checkCredentials(username: string, password: string) {
    if (username === 'demo' && password === 'demo') {
      this.isUserLoggedIn.next(true);
    }
  }

  logout() {
    this.isUserLoggedIn.next(false);
  }
}
```

Now, export the service in the library's entry point file:

```ts
// libs/shared/data-access-user/src/index.ts
...
export * from './lib/user.service';
```

### Login application

Let's set up our `entry.ts` file in the **Login** application so that it renders a login form. We'll import `FormsModule` and inject our `UserService` to allow us to sign the user in:

```ts
// apps/login/src/app/remote-entry/entry.ts
import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
import { FormsModule } from '@angular/forms';
import { UserService } from '@ng-mf/data-access-user';
import { inject } from '@angular/core';

@Component({
  standalone: true,
  imports: [CommonModule, FormsModule],
  selector: 'ng-mf-login-entry',
  template: `
    <div class="login-app">
      <form class="login-form" (ngSubmit)="login()">
        <label>
          Username:
          <input type="text" name="username" [(ngModel)]="username" />
        </label>
        <label>
          Password:
          <input type="password" name="password" [(ngModel)]="password" />
        </label>
        <button type="submit">Login</button>
      </form>
      <div *ngIf="isLoggedIn$ | async">User is logged in!</div>
    </div>
  `,
  styles: [
    `
      .login-app {
        width: 30vw;
        border: 2px dashed black;
        padding: 8px;
        margin: 0 auto;
      }
      .login-form {
        display: flex;
        align-items: center;
        flex-direction: column;
        margin: 0 auto;
        padding: 8px;
      }
      label {
        display: block;
      }
    `,
  ],
})
export class RemoteEntry {
  private userService = inject(UserService);
  username = '';
  password = '';
  isLoggedIn$ = this.userService.isUserLoggedIn$;

  login() {
    this.userService.checkCredentials(this.username, this.password);
  }
}
```

{% aside type="note" title="More details" %}
This could be improved with things like error handling, but for the purposes of this tutorial, we'll keep it simple.
{% /aside %}

Now let's serve the application and view it in a browser to check that the form renders correctly.

```shell
nx run login:serve
```

We can see if we navigate a browser to `http://localhost:4201` that we see the login form rendered.

If we type in the correct username and password _(demo, demo)_, then we can also see the user gets authenticated!

Perfect! Our **Login** application is complete.

### Dashboard application

Now let's update our **Dashboard** application. We'll hide some content if the user is not authenticated, and present them with the **Login** application where they can log in.

For this to work, the state within `UserService` must be shared across both applications. Usually, with Module Federation in Webpack, you have to specify the packages to share between all the applications in your Micro Frontend solution. However, by taking advantage of Nx project graph, Nx will automatically find and share the dependencies of your applications.

{% aside type="note" title="Single version policy" %}
This helps to enforce a single version policy and reduces the risk of [Micro Frontend Anarchy](https://www.thoughtworks.com/radar/techniques/micro-frontend-anarchy).
{% /aside %}

Start by deleting the `app.html`, `app.css`, and `nx-welcome.ts` files from the **Dashboard** application. They will not be needed for this tutorial.

Next, let's add our logic to the `app.ts` file. Change it to match the following:

```ts
// apps/dashboard/src/app/app.ts
import { CommonModule } from '@angular/common';
import { Component, inject, OnInit } from '@angular/core';
import { Router, RouterModule } from '@angular/router';
import { UserService } from '@ng-mf/data-access-user';
import { distinctUntilChanged } from 'rxjs/operators';

@Component({
  standalone: true,
  imports: [CommonModule, RouterModule],
  selector: 'ng-mf-root',
  template: `
    <div class="dashboard-nav">Admin Dashboard</div>
    <div *ngIf="isLoggedIn$ | async; else signIn">
      You are authenticated so you can see this content.
    </div>
    <ng-template #signIn><router-outlet></router-outlet></ng-template>
  `,
})
export class App implements OnInit {
  private router = inject(Router);
  private userService = inject(UserService);
  isLoggedIn$ = this.userService.isUserLoggedIn$;

  ngOnInit() {
    this.isLoggedIn$
      .pipe(distinctUntilChanged())
      .subscribe(async (loggedIn) => {
        // Queue the navigation after initialNavigation blocking is completed
        setTimeout(() => {
          if (!loggedIn) {
            this.router.navigateByUrl('login');
          } else {
            this.router.navigateByUrl('');
          }
        });
      });
  }
}
```

Finally, make sure the application routes are correctly set up:

```ts
// apps/dashboard/src/app/app.routes.ts
import { Route } from '@angular/router';
import { App } from './app';

export const appRoutes: Route[] = [
  {
    path: 'login',
    loadChildren: () => import('login/Routes').then((m) => m.remoteRoutes),
  },
  {
    path: '',
    component: App,
  },
];
```

We can now run both the **Dashboard** and **Login** applications:

```shell
nx serve dashboard --devRemotes=login
```

Navigating to `http://localhost:4200` should show the **Dashboard** application with the **Login** application embedded within it. If you log in, you should see the content change to show that you are authenticated.

This concludes the setup required for a Micro Frontend approach using Static Module Federation.

{% aside type="caution" title="Do not fret!" %}

When serving module federation apps locally in dev mode, there'll be an error output to the console: `import.meta cannot be used outside of a module`. You'll see the error originates from the `styles.js` script. It's a known error output, and as far as our testing has shown, it doesn't cause any breakages. It happens because the Angular compiler attaches the `styles.js` file to the `index.html` in a `<script>` tag with `defer`.

It needs to be attached with `type=module`, but Angular can't make that change because it breaks HMR. They also provide no way of hooking into that process for us to patch it ourselves.

The good news is that the error doesn't propagate to production because styles are compiled to a CSS file, so there's no erroneous JS to log an error.

It's worth stressing that no errors or breakages have been noted from our tests.

{% /aside %}

## Converting the dashboard application

The **Dashboard** application is a Host application that loads the Remote applications at runtime based on their deployed locations when the application was built using Static Module Federation.

We want to change this so that the **Dashboard** application can make a network request at runtime to find out the deployed locations of the Remote applications.

There are 3 steps involved with this:

- Make a network request to fetch the locations of the Remote applications _(the Remote Definitions)_.
- Set the Remote Definitions so that webpack is aware of how to find the Remote applications when requested.
- Change how we load the Remote applications so that webpack can fetch any required files correctly.

### Fetch and set the remote definitions

Perhaps one of the easiest methods of fetching the Remote Definitions at runtime is to store them in a JSON file that can be present in each environment. The Host application then only has to make a GET request to the JSON file.

We'll start by creating this file. Add a `module-federation.manifest.json` file to the `public/` folder in our **Dashboard** application with the following content:

```json
// apps/dashboard/public/module-federation.manifest.json
{
  "login": "http://localhost:4201/mf-manifest.json"
}
```

Next, open the `main.ts` file and replace it with the following:

```ts
// apps/dashboard/src/main.ts
import { registerRemotes } from '@module-federation/enhanced/runtime';

fetch('/module-federation.manifest.json')
  .then((res) => res.json())
  .then((remotes: Record<string, string>) =>
    Object.entries(remotes).map(([name, entry]) => ({ name, entry }))
  )
  .then((remotes) => registerRemotes(remotes))
  .then(() => import('./bootstrap').catch((err) => console.error(err)));
```

You'll notice that we fetch the JSON file, transform it into the format expected by `registerRemotes`, and register the remotes with the Module Federation runtime. This tells webpack where each of our remote applications has been deployed to!

### Change how Remotes are loaded

At the moment, webpack is statically building our application, telling it at build time where our Remotes are. That is because they are specified in the `module-federation.config.ts` file.

Open the `module-federation.config.ts` file at the root of our `apps/dashboard/` folder and set the `remotes` property to be an empty array. It should look like this:

```ts {% meta="{6}" %}
// apps/dashboard/module-federation.config.ts
import { ModuleFederationConfig } from '@nx/module-federation';

const config: ModuleFederationConfig = {
  name: 'dashboard',
  remotes: [],
};

export default config;
```

Next, we need to change how our application attempts to load the Remote when it is routed to. Open the `app.routes.ts` file under the `src/app/` folder and apply the following changes:

```ts {% meta="{3,9-10}" %}
// apps/dashboard/src/app/app.routes.ts
import { Route } from '@angular/router';
import { loadRemote } from '@module-federation/enhanced/runtime';
import { App } from './app';

export const appRoutes: Route[] = [
  {
    path: 'login',
    loadChildren: () =>
      loadRemote<typeof import('login/Routes')>('login/Routes').then(
        (m) => m!.remoteRoutes
      ),
  },
  {
    path: '',
    component: App,
  },
];
```

The `loadRemote` helper method simply hides some logic that will check if the Remote application has been loaded, and if not, load it, and then requests the correct exposed routes from it.

### Summary

That's all the changes required to replace Static Module Federation with Dynamic Module Federation.

Running:

```shell
nx serve dashboard --devRemotes=login
```

Should result in the same behaviour as before, except that our **Dashboard** application is waiting until runtime to find out the deployed location of our **Login** application.

In the next section, we will see how Nx generators can be used to automate a lot of this process for us!

---

## Creating a new dynamic host application

Nx provides generators that aim to streamline the process of setting up a Dynamic Micro Frontend architecture.

To showcase this, let's create a new Host application that will use our previous **Login** application as well as a new **Todo** Remote application.

### Generate the employee host application

Run the following command to generate a new Host application that is preconfigured for Dynamic Federation and add specify the **Login** Remote application we want to add:

```shell
nx g @nx/angular:host apps/employee --remotes=login --dynamic
```

This will generate:

- Angular application
- Webpack Configuration _(webpack.config.ts)_
- Module Federation Configuration _(module-federation.config.ts)_
- Micro Frontend Manifest File _(module-federation.manifest.json)_
- Changes to the bootstrap of application to fetch the Micro Frontend Manifest, set the Remote Definitions and load the **Login** application correctly

You should take a look at the files generated and see how the **Login** Remote application was added to the `module-federation.manifest.json` file and the slight changes to `main.ts` and `app.routes.ts` to load the Remotes dynamically.

### Generate the todo remote application

We're going to demonstrate how when specifying a dynamic Host when adding a new Remote application, the Remote application will be added to the Host's Micro Frontend Manifest file correctly.

```shell
nx g @nx/angular:remote apps/todo --host=employee
```

You'll note that this will generate the same output as the **Login** Remote application in the previous guide. There's one difference. Because the Host application is using Dynamic Federation, the new Remote will be added to the Host's `module-federation.manifest.json`.

### Summary

Dynamic Federation is the perfect way to solve the problem of **"Build once, deploy everywhere"**. It can be used in tandem with CD solutions that involve spinning up environments for different stages of the release process without having to rebuild the application at all. The CD pipeline only ever needs to replace a JSON file on that environment with one that contains the correct values for the deployed locations of the remote applications.

---
<!-- source: https://nx.dev/docs/technologies/angular/guides/module-federation-with-ssr.md -->
## Module Federation with Server-Side Rendering

Walk you through creating a Module Federated setup with Server Side Rendering (SSR) for Angular and React using Nx and its generators.

## Steps

### Create an empty workspace

Run the following command with the options listed to create an empty workspace.

```text {% title="npx create-nx-workspace@latest myorg --preset=apps" frame="terminal" %}

NX   Let's create a new workspace [https://nx.dev/getting-started/intro]

✔ Which CI provider would you like to use? · skip
✔ Would you like remote caching to make your build faster? · skip
```

{% linkcard title="Opting into Nx Cloud" description="You will also be prompted whether to add Nx Cloud to your workspace. We won't address this in this recipe, but you can see the introduction to Nx Cloud for more details." href="/docs/guides/nx-cloud/setup-ci" /%}

### Install your framework plugin

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/angular` or `@nx/react` versions that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
{% /aside %}

{% tabs syncKey="framework" %}

{% tabitem label="Angular" %}

```shell
nx add @nx/angular

```

{% /tabitem %}

{% tabitem label="React" %}

```shell
nx add @nx/react

```

{% /tabitem %}

{% /tabs %}

### Generating a host and multiple remotes with SSR

We will generate the apps required for a storefront application.  
We will need the following applications:

- Store - _host application_
- Product - _remote application_
- Checkout - _remote application_

Nx allows you to do this with a single command:

{% tabs syncKey="framework" %}

{% tabitem label="Angular" %}

```shell
npx nx g @nx/angular:host apps/store --ssr --remotes=product,checkout

```

{% /tabitem %}

{% tabitem label="React" %}

```shell
npx nx g @nx/react:host apps/store --ssr --remotes=product,checkout

```

{% /tabitem %}

{% /tabs %}

This will generate three applications, set up with SSR and Module Federation.

### Serving the store application

When using Module Federation, we want to serve the host application along with the remote applications so that everything works as expected.

To do this, run:

{% tabs syncKey="framework" %}

{% tabitem label="Angular" %}

```shell
npx nx serve-ssr store

```

{% /tabitem %}

{% tabitem label="React" %}

```shell
npx nx serve store

```

{% /tabitem %}

{% /tabs %}

This will run all three application servers but only the `store` will be watching for file changes. If you make a change to one of the remote applications (`checkout` or `product`) the changes will not be hot reloaded.

### Serving the store application with file watching for checkout

If working on a remote application, we can still serve it via the host application and have it watch for changes.

To serve the `store` application and watch for changes on the `checkout` application run:

{% tabs syncKey="framework" %}

{% tabitem label="Angular" %}

```shell
npx nx serve-ssr store --devRemotes=checkout

```

{% /tabitem %}

{% tabitem label="React" %}

```shell
npx nx serve store --devRemotes=checkout

```

{% /tabitem %}

{% /tabs %}

### Additional resources

To learn more about Module Federation, we have some resources you might find useful:

- [Concepts: Nx Module Federation Technical Overview](/docs/technologies/module-federation/concepts/nx-module-federation-technical-overview)
- [Guide: Faster Builds with Module Federation](/docs/technologies/module-federation/concepts/faster-builds-with-module-federation)
- [Video: Speed up your Angular serve and build times with Module Federation and Nx](https://www.youtube.com/watch?v=JkcaGzhRjkc)

---
<!-- source: https://nx.dev/docs/technologies/angular/guides/nx-and-angular.md -->
## Nx and the Angular CLI

{% youtube
src="https://www.youtube.com/embed/bwPkz4MrPDI?si=OLPUENWXLkQ9GRtR"
title="Nx vs Angular CLI - The Showdown"
width="100%" /%}

Nx evolved from being an extension of the Angular CLI to a [fully standalone CLI working with multiple frameworks](/docs/getting-started/intro#start-small-extend-as-you-grow). As a result, adopting Nx as an Angular user is relatively straightforward. This guide explores some of the similarities and in particular, added benefits of using Nx over the Angular CLI for your Angular project.

## TL;DR: Why should i use Nx for my Angular project?

Nx...

- helps define clear architectural guidelines and promotes best practices to organize and scale your codebase.
- helps integrate modern tooling by actively working with devtool authors to make sure they work well with Nx and your framework of choice.
- is adaptable: start small with a single-project setup and grow it to a monorepo when needed.
- has an active community of contributors and plugin authors.
- has been proven in large enterprise-level projects.

Note, the Nx team's focus is on building the best possible developer productivity tool.

### Quick overview comparison

Here's a quick side-by-side overview comparing the features between the Angular CLI and Nx. _(Kudos to [Daniel Glejzner](https://twitter.com/DanielGlejzner) for helping with this)_

| Feature/Tool                                                                                               | Angular CLI     | Nx            |
| ---------------------------------------------------------------------------------------------------------- | --------------- | ------------- |
| Create Angular Apps                                                                                        | ✅              | ✅            |
| Generate Angular Components, Services, etc.                                                                | ✅              | ✅            |
| Building & Bundling                                                                                        | ✅              | ✅            |
| Local Development Server                                                                                   | ✅              | ✅            |
| Code Schematics                                                                                            | ✅              | ✅            |
| Automated Update with Migrations                                                                           | ✅              | ✅ (Enhanced) |
| Generators                                                                                                 | ✅ (Schematics) | ✅            |
| Executors                                                                                                  | ✅ (Builders)   | ✅            |
| Advanced Generators (e.g. Module Federation, Tailwind,...)                                                 | ❌              | ✅            |
| Integrated Tooling (Jest, Cypress, Playwright etc.)                                                        | ❌              | ✅            |
| Support for single-project Workspaces                                                                      | ✅              | ✅            |
| First-Class [Monorepo Support](/docs/getting-started/tutorials/crafting-your-workspace)                    | ❌\*            | ✅            |
| [Enforced Module Boundaries](/docs/features/enforce-module-boundaries)                                     | ❌              | ✅            |
| Interactive [Project Graph](/docs/features/explore-graph)                                                  | ❌              | ✅            |
| Task Graph                                                                                                 | ❌              | ✅            |
| [Running Tasks in Parallel](/docs/guides/tasks--caching/run-tasks-in-parallel)                             | ❌              | ✅            |
| Building, Testing [Only What is Affected](/docs/features/run-tasks#run-tasks-on-projects-affected-by-a-pr) | ❌              | ✅            |
| [Local Caching](/docs/features/cache-task-results)                                                         | ❌\*\*          | ✅            |
| [Remote Caching](/docs/features/ci-features/remote-cache)                                                  | ❌              | ✅            |
| [Distributed Task Execution on CI](/docs/features/ci-features/distribute-task-execution)                   | ❌              | ✅            |
| Custom Hashers                                                                                             | ❌              | ✅            |
| [Extensible Plugin System](/docs/extending-nx/intro)                                                       | ❌              | ✅            |

{% aside type="note" title="Notes" %}

\* You can setup a monorepo with the Angular CLI creating buildable Angular ng-packagr projects, but the DX is not as optimized compared to what you'd get with Nx.

\*\* The Angular CLI has a [caching mechanism](https://angular.dev/cli/cache) which persists the Webpack/ESBuild/"TS incremental build info" cache to disk. Nx leverages that cache as well but in addition adds a more powerful process-level caching on top that is framework agnostic.

{% /aside %}

## Similarities and differences

Learn about the similarities between the Angular CLI and Nx which makes it easy to [migrate](#migrate-from-the-angular-cli) but also about how Nx goes beyond to further improve your developer productivity.

### Not just for monorepos: project setup & structure

Nx is not just exclusively for monorepos, but can create

- a single-project workspace (basically what the Angular CLI gives you)
- a monorepo workspace (multiple projects in a single repo)

### Generate a new project

You can create a new Nx single-project workspace using the following command:

```shell
npx create-nx-workspace myngapp --preset=angular-standalone
```

{% aside type="note" title="Want a monorepo instead?" %}
You can use the `--preset=angular-monorepo` to start with a monorepo structure. Note, however, that you can start simple and migrate to a monorepo later.
{% /aside %}

The single-project workspace setup follows a similar structure to what the Angular CLI generates.

```plaintext
└─ myngapp
   ├─ public
   │  └─ favicon.ico
   ├─ src
   │  ├─ app
   │  │  ├─ app.config.ts
   │  │  ├─ app.css
   │  │  ├─ app.html
   │  │  ├─ app.routes.ts
   │  │  ├─ app.spec.ts
   │  │  ├─ app.ts
   │  │  └─ nx-welcome.ts
   │  ├─ index.html
   │  ├─ main.ts
   │  ├─ styles.css
   │  └─ test-setup.ts
   ├─ nx.json
   ├─ package.json
   ├─ project.json
   ├─ tsconfig.app.json
   ├─ tsconfig.json
   └─ tsconfig.spec.json
```

### project.json vs angular.json

Nx configures projects and their targets in a format similar to `angular.json`. However, instead of storing the configuration for every project in a single large `angular.json` file at the root, the configuration is split into multiple `project.json` files, one for each project.

Smaller, focused config files allow you to quickly find the relevant configuration for the project you are working on, and editing a single project configuration does not cause the `nx affected` command to rerun all the tests in the repo. This conversion is done automatically when you run `nx init`.

Note that even though the configuration is split, everything works similarly. Migrations and schematics written with the Angular devkit that expect a single `angular.json` file will receive a single file. Nx is smart, so it merges all the files in memory to make those migrations and schematics work.

More details: Nx [project configuration](/docs/reference/project-configuration).

### Executors vs. builders, generators vs. schematics

Nx comes with slightly different terminology than the Angular CLI for some features.

**Angular Builders** are called [Executors](/docs/concepts/executors-and-configurations) in Nx but work very much similarly. You use them in your project configuration to define how to build, test, lint, and serve your project. You can use both Nx executors from [Nx Plugins](/docs/plugin-registry) or Angular Builders from the Angular Devkit.

```json
{
  "name": "myngapp",
  ...
  "targets": {
    "build": {
      "executor": "@angular-devkit/build-angular:browser",
      ...
    },
    ...
  }
}
```

**Angular Schematics** are called [Generators](/docs/features/generate-code) in Nx. You can invoke them in the same way as you would with the Angular CLI, but you use the `nx` command instead of `ng`:

```shell
npx nx g @nx/angular:component apps/my-app/src/lib/my-component/my-component
```

You can also run Angular Schematics through the Nx CLI. So something like this works as well:

```shell
npx nx g @schematics/angular:component my-component
```

{% aside type="tip" title="Important" %}
Support to run Angular Devkit builders and schematics is enabled by installing the [`@nx/angular` plugin](/docs/technologies/angular/introduction). This plugin is installed by default when creating a new Angular workspace with Nx or [migrate an existing Angular CLI workspace to Nx](#migrate-from-the-angular-cli).
{% /aside %}

### Running commands

Commands are run in the very same way as with the Angular CLI. You just switch `ng` with `nx`. For example:

```shell
npx nx serve
```

Nx has more abilities to run commands in parallel, just for specific projects etc. Find out more [in the docs](/docs/features/run-tasks).

### Integrating with modern tools

An Angular-based Nx Workspace already comes with a lot of batteries included:

- Prettier preconfigured
- ESLint
- e2e testing with [Cypress](https://www.cypress.io/) or [Playwright](https://playwright.dev/)
- unit testing with [Jest](https://jestjs.io/)

But Nx expands beyond just that, offering automated integration with a lot of modern tools such as [Storybook](https://storybook.js.org/) or [Tailwind](https://tailwindcss.com/) just to mention a few.

### 'ng update' vs. 'nx migrate'

Like the Angular CLI, Nx has a command that allows you to upgrade your existing workspace tools, packages, and source code to the next version. Instead of `ng update`, you run `nx migrate`:

```shell
npx nx migrate latest
```

What's the difference?

`nx migrate` is a much-improved version of `ng update`. It runs the same migrations but allows you to:

- Rerun the same migration multiple times.
- Reorder migrations.
- Skip migrations.
- Fix migrations that "almost work".
- Commit a partially migrated state.
- Change versions of packages to match org requirements.
- [Opt out of Angular updates when updating Nx versions](/docs/guides/tips-n-tricks/advanced-update#choosing-optional-package-updates-to-apply) as long as [the Angular version is still supported](/docs/technologies/angular/guides/angular-nx-version-matrix)

`nx migrate` does this by splitting the process into two steps. `nx migrate latest` creates a `migrations.json` file with a list of all the migrations needed by Nx, Angular, and other packages. You can then modify that file before running `nx migrate --run-migrations` to execute those migrations.

To reiterate: `nx migrate` runs the migrations written by the Angular team the same way `ng update` runs them. So everything should still work. You just get more control over how it works. You can learn more in our docs about [Automate Updating Dependencies](/docs/features/automate-updating-dependencies).

### 'nx add'

The [`nx add` command](/docs/reference/nx-commands#nx-add) is similar to the `ng add` command. It installs a given package specifier (e.g. `@nx/react`, `@nx/react@18.1.0`, `@nx/react@latest`) and it runs an `init` or `ng-add` generator if the installed package contains it.

```shell
nx add [package]
```

The command was introduced in **Nx 17.3.0**. If you're using an older version, you can instead run:

{% tabs %}
{% tabitem label="npm" %}

```shell
npm add [package]
nx g [package]:ng-add
```

{% /tabitem %}

{% tabitem label="yarn" %}

```shell
yarn add [package]
nx g [package]:ng-add
```

{% /tabitem %}

{% tabitem label="pnpm" %}

```shell
pnpm add [package]
nx g [package]:ng-add
```

{% /tabitem %}

{% tabitem label="bun" %}

```shell
bun add [package]
nx g [package]:ng-add
```

{% /tabitem %}
{% /tabs %}

Replace `[package]` with the package name you're trying to add.

### Speed

Nx is designed to be fast. The Angular CLI leverages Webpack caching, which Nx also does since it relies on the Angular Devkit when it comes to compiling or running apps. But Nx goes way beyond that, introducing features vital for a fast CI experience, mainly when you have a monorepo.

Features like

- only running tasks on [affected projects](/docs/features/ci-features/affected)
- running [tasks in parallel](/docs/features/run-tasks#run-tasks-for-multiple-projects)
- applying [computation caching](/docs/features/cache-task-results)
- offering [remote caching abilities](/docs/features/ci-features/remote-cache) on CI
- offering [task distribution across machines (Nx Agents)](/docs/features/ci-features/distribute-task-execution)

And, Nx already uses fast, modern tooling like [ESBuild](/docs/technologies/build-tools/esbuild/introduction), [Vite](/docs/technologies/build-tools/vite/introduction), Vitest and [Rspack](/docs/technologies/build-tools/rspack/introduction) for non-Angular stacks. So once Angular is ready to use these tools, Nx will also be ready.

### Editor integration

Nx goes beyond being just a CLI and comes with [Nx Console](/docs/getting-started/editor-setup), a VSCode and WebStorm extension allowing you to run commands, generate code and visualize your workspace.

![Nx Console screenshot](../../../../../assets/nx-console/nx-console-screenshot.webp)

### Scaling: start simple, grow to a monorepo

Nx is really made to scale with you. You can

- start small with a single-project workspace
- modularize your application into more fine-grained libraries for better maintainability as your application (and team) grows, including mechanisms to make sure [things stay within their boundaries](/docs/features/enforce-module-boundaries)
- you can then migrate to a monorepo when you are ready and need one ([more here](/docs/guides/tips-n-tricks/standalone-to-monorepo))
- or even [add Webpack Module Federation support](/docs/technologies/angular/guides/module-federation-with-ssr)

### Visualize your workspace

As you start modularizing your Angular workspace, Nx can visualize it using the `nx graph` command or via [Nx Console](/docs/getting-started/editor-setup) directly in your editor.

{% graph height="450px" %}

```json
{
  "hash": "58420bb4002bb9b6914bdeb7808c77a591a089fc82aaee11e656d73b2735e3fa",
  "projects": [
    {
      "name": "shared-product-state",
      "type": "lib",
      "data": {
        "tags": ["scope:shared", "type:state"]
      }
    },
    {
      "name": "shared-product-types",
      "type": "lib",
      "data": {
        "tags": ["type:types", "scope:shared"]
      }
    },
    {
      "name": "shared-product-data",
      "type": "lib",
      "data": {
        "tags": ["type:data", "scope:shared"]
      }
    },
    {
      "name": "cart-cart-page",
      "type": "lib",
      "data": {
        "tags": ["scope:cart", "type:feature"]
      }
    },
    {
      "name": "shared-styles",
      "type": "lib",
      "data": {
        "tags": ["scope:shared", "type:styles"]
      }
    },
    {
      "name": "cart-e2e",
      "type": "e2e",
      "data": {
        "tags": ["scope:cart", "type:e2e"]
      }
    },
    {
      "name": "cart",
      "type": "app",
      "data": {
        "tags": ["type:app", "scope:cart"]
      }
    }
  ],
  "dependencies": {
    "shared-product-state": [
      {
        "source": "shared-product-state",
        "target": "shared-product-data",
        "type": "static"
      },
      {
        "source": "shared-product-state",
        "target": "shared-product-types",
        "type": "static"
      }
    ],
    "shared-product-types": [],
    "shared-product-data": [
      {
        "source": "shared-product-data",
        "target": "shared-product-types",
        "type": "static"
      }
    ],
    "shared-e2e-utils": [],
    "cart-cart-page": [
      {
        "source": "cart-cart-page",
        "target": "shared-product-state",
        "type": "static"
      }
    ],
    "shared-styles": [],
    "cart-e2e": [
      { "source": "cart-e2e", "target": "cart", "type": "implicit" }
    ],
    "cart": [
      { "source": "cart", "target": "shared-styles", "type": "implicit" },
      { "source": "cart", "target": "cart-cart-page", "type": "static" }
    ]
  },
  "workspaceLayout": {
    "appsDir": "apps",
    "libsDir": "libs"
  },
  "affectedProjectIds": [],
  "focus": null,
  "groupByFolder": false,
  "exclude": [],
  "enableTooltips": true
}
```

{% /graph %}

Learn more about the [graph features here](/docs/features/explore-graph).

### Extensible and Customizable: Make it fit your own needs

Nx is [built to be extensible](/docs/getting-started/intro#start-small-extend-as-you-grow). Just like the [packages published by the Nx core team](/docs/plugin-registry) you can create your own Nx plugins by [extending Nx](/docs/extending-nx/intro). This can be as simple as using [run-commands](/docs/guides/tasks--caching/run-commands-executor) to integrate custom commands into the project configuration or as complex as [creating your own local executor](/docs/extending-nx/local-executors).

And if you ever need to expand beyond Angular or diversify your stack, you can still keep using Nx, which is [battle-tested with many different technologies](/docs/technologies).

## Migrate from the Angular CLI?

Migrating an Angular CLI project to Nx can be done by running

```shell
npx nx@latest init
```

or alternatively using the `--integrated` flag if you want to create an Nx monorepo right away. Learn more about all the details on the [dedicated docs page](/docs/technologies/angular/migration/angular).

You can also use [`nx import`](/docs/guides/adopting-nx/import-project) to bring multiple Angular CLI projects into a single Nx monorepo while preserving git history.

You can learn more about Angular & Nx by following our dedicated tutorials:

- [Tutorial: Learn Nx](/docs/getting-started/tutorials/crafting-your-workspace)

---
<!-- source: https://nx.dev/docs/technologies/angular/guides/nx-devkit-angular-devkit.md -->
## Nx Devkit and Angular Devkit

{% aside type="note" title="Nx & Angular" %}
The difference between Nx Devkit and Angular Devkit. See the [Nx Devkit](/docs/reference/devkit) guide for more in-depth details about Nx Devkit.
{% /aside %}

Nx comes with a devkit to write generators and executors, but you can also use Angular devkit (schematics and builders). In other words, you can use an Angular schematic to implement a generator, and you can use an Angular builder to implement an executor.

{% aside type="tip" title="Important" %}
Support to run Angular Devkit builders and schematics is enabled by installing the [`@nx/angular` plugin](/docs/technologies/angular/introduction). This plugin is installed by default when creating a new Angular workspace with Nx or [migrate an existing Angular CLI workspace to Nx](/docs/technologies/angular/migration/angular).
{% /aside %}

**What are the differences between Nx Devkit and Angular Devkit?**

## Generators

The following is a generator written using Nx Devkit:

```typescript
import { Tree, formatFiles, generateFiles } from '@nx/devkit';
import * as path from 'path';

interface Schema {
  name: string;
  skipFormat: boolean;
}

export default async function (tree: Tree, options: Schema) {
  generateFiles(
    tree,
    path.join(__dirname, 'files'),
    path.join('tools/generators', schema.name),
    options
  );
  if (!schema.skipFormat) {
    await formatFiles(tree);
  }
}
```

The following is an analogous generator written as an Angular Schematic.

```typescript
import {
  apply,
  branchAndMerge,
  chain,
  mergeWith,
  Rule,
  template,
  url,
  move,
} from '@angular-devkit/schematics';
import { formatFiles } from '@nx/workspace';
import { toFileName } from '@nx/workspace';

interface Schema {
  name: string;
  skipFormat: boolean;
}

export default function (options: Schema): Rule {
  const templateSource = apply(url('./files'), [
    template({
      dot: '.',
      tmpl: '',
      ...(options as any),
    }),
    move('tools/generators'),
  ]);
  return chain([
    branchAndMerge(chain([mergeWith(templateSource)])),
    formatFiles(options),
  ]);
}
```

### Notable differences

- Nx Devkit generators do not use partial application. An Angular Schematic returns a rule that is then invoked with a tree.
- Nx Devkit generators do not use RxJS observables. Instead, you invoke the helpers directly, which makes them more debuggable. As you step through the generator you can see the tree being updated.
- There are more affordances for commonly used operations. For instance, `chain([mergeWith(apply(url` is replaced with `generateFiles`)
- Nx Devkit generators return a function that performs side effects. Angular Schematics have to create a custom task runner and register a task using it.
- Nx Devkit generators are composed as any other JS function. You do need to go through a special resolution step (`externalSchematic`) that is required when using Angular Schematics.
- No special utilities are needed to test Nx Devkit generators. Special utilities are needed to test Angular Schematics.

### Conversions

The Nx CLI can invoke Nx Generator or Angular Schematics directly. When the user runs:

```shell
nx g mygenerator params
nx g myschematic params
```

The Nx CLI will identify whether it is running an Nx generator or an Angular schematic and will invoke it using the right machinery. The user doesn't have to know how the generator is implemented.

At times, however, it might be useful to use an Nx Devkit generator in an Angular Schematic or vice versa.

**Making an Angular Schematic out of Nx Devkit Generator:**

First, you need to

```typescript
export async function mygenerator(tree: Tree, options: Schema) {
  // ...
}
export const mygeneratorSchematic = convertNxGenerator(mygenerator);
```

Then, you might need to register it in the `collections.json`:

```json
{
  "name": "Nx React",
  "version": "0.1",
  "extends": ["@nx/workspace"],
  "schematics": {
    "mygenerator": {
      "factory": "./src/generators/mygenerator/mygenerator#mygeneratorSchematic",
      "schema": "./src/generators/mygenerator/schema.json"
    }
  },
  "generators": {
    "init": {
      "factory": "./src/generators/mygenerator/mygenerator#mygenerator",
      "schema": "./src/generators/mygenerator/schema.json"
    }
  }
}
```

**Making an Nx Devkit Generator out of Angular Schematic:**

```typescript
export const libraryGenerator = wrapAngularDevkitSchematic(
  '@schematics/angular',
  'library'
);

export async function mygenerator(tree: Tree, options: Schema) {
  await libraryGenerator(tree, options);
}
```

## Executors

The following is an executor written using Nx Devkit:

```typescript
interface Schema {
  message: string;
  allCaps: boolean;
}

export default async function (
  options: Schema,
  context: ExecutorContext
): Promise<{ success: true }> {
  if (options.allCaps) {
    console.log(options.message.toUpperCase());
  } else {
    console.log(options.message);
  }
  return { success: true };
}
```

The following is an analogous executor written as an Angular builder:

```typescript
interface Schema {
  message: string;
  allCaps: boolean;
}
export function run(
  options: Schema,
  context: BuilderContext
): Observable<{ success: true }> {
  if (options.allCaps) {
    console.log(options.message.toUpperCase());
  } else {
    console.log(options.message);
  }
  return of({ success: true });
}
export default createBuilder<NextBuildBuilderOptions>(run);
```

### Notable differences

- Nx Devkit executors return a Promise (or async iterable). If you want, you can always convert an observable to a promise or an async iterable.
- Nx Devkit executors do not have to be wrapped using `createBuilder`.

The schema files for both Nx Devkit executors and Angular Builders are the same. Nx can run both of them in the same way.

## When to use what

If you are writing an Nx plugin, use Nx Devkit. It's **much** easier to use and debug. It has better docs and more people supporting it.

Do you have to rewrite your Nx Plugin if it is written using Angular Devkit? No. Nx supports both and will always support both. And, most importantly, the end user might not even know what you used to write a generator or an executor.

---
<!-- source: https://nx.dev/docs/technologies/angular/guides/setup-incremental-builds-angular.md -->
## Setup Incremental Builds for Angular Applications

We'll specifically look into which changes need to be made to enable incremental builds for Angular
applications.

## Use buildable libraries

To enable incremental builds you need to use buildable libraries.

You can generate a new buildable library with:

```shell
nx g @nx/angular:lib libs/my-lib --buildable
```

The generated buildable library uses the `@nx/angular:ng-packagr-lite` executor which is optimized for the incremental
builds scenario:

```jsonc
{
  "projectType": "library",
  ...
  "targets": {
    "build": {
      "executor": "@nx/angular:ng-packagr-lite",
      "outputs": [
        "{workspaceRoot}/dist/libs/my-lib"
      ],
      "options": {
        ...
      },
      "configurations": {
        ...
      },
      "defaultConfiguration": "production"
    },
    ...
  },
  ...
},
```

{% aside type="caution" title="More details" %}
Please note that it is important to keep the `outputs` property in sync with the `dest` property in the file
`ng-package.json` located inside the library root. When a library is generated, this is configured correctly, but if the
path is later changed in `ng-package.json`, it needs to be updated as well in the project configuration.

The `@nx/angular:package` executor also supports incremental builds. It is used to build and package an Angular library
to be distributed as an NPM package following the Angular Package Format (APF) specification. It will be automatically
configured when generating a publishable library (`nx g @nx/angular:lib libs/my-lib --publishable --importPath my-lib`).
{% /aside %}

## Adjust the application executor

{% aside type="note" title="Angular Esbuild Performance" %}
From internal testing done at Nx, the build time saved from using incremental builds when using Esbuild with Angular is
not as effective as the time saved when using Webpack with Angular.
Angular build time with Esbuild already provides a great performance boost and therefore overall time saved may not
warrant using incremental builds with Esbuild for Angular
{% /aside %}

Change your Angular application's "build" target executor to Nx version of builder you're currently using and the "
serve" target executor to `@nx/angular:dev-server` as shown below.

- `@angular-devkit/build-angular:application` -> `@nx/angular:application`
- `@angular-devkit/build-angular:browser-esbuild` -> `@nx/angular:browser-esbuild`
- `@angular/build:browser` -> `@nx/angular:webpack-browser`

{% tabs %}
{% tabitem label="@angular-devkit/build-angular:application" %}

```jsonc
// project.json
{
  "projectType": "application",
  ...
  "targets": {
    "build": {
      "dependsOn": ["^build"],
      "executor": "@nx/angular:application",
      "outputs": [
        "{options.outputPath}"
      ],
      "options": {
        "buildLibsFromSource": false
        ...
      },
      "configurations": {
        ...
      },
      "defaultConfiguration": "production"
    },
    "serve": {
      "executor": "@nx/angular:dev-server",
      "options": {
        "buildTarget": "my-app:build",
        "buildLibsFromSource": false
      },
      "configurations": {
        "production": {
          "buildTarget": "my-app:build:production"
        }
      }
    },
    ...
  }
},
```

{% /tabitem %}
{% tabitem label="@angular-devkit/build-angular:browser-esbuild" %}

```jsonc
// project.json
{
  "projectType": "application",
  ...
  "targets": {
    "build": {
      "dependsOn": ["^build"],
      "executor": "@nx/angular:browser-esbuild",
      "outputs": [
        "{options.outputPath}"
      ],
      "options": {
        "buildLibsFromSource": false
        ...
      },
      "configurations": {
        ...
      },
      "defaultConfiguration": "production"
    },
    "serve": {
      "executor": "@nx/angular:dev-server",
      "options": {
        "buildTarget": "my-app:build",
        "buildLibsFromSource": false
      },
      "configurations": {
        "production": {
          "buildTarget": "my-app:build:production"
        }
      }
    },
    ...
  }
},
```

{% /tabitem %}
{% tabitem label="@angular-devkit/build-angular:browser" %}

```jsonc
// project.json
{
  "projectType": "application",
  ...
  "targets": {
    "build": {
      "dependsOn": ["^build"],
      "executor": "@nx/angular:webpack-browser",
      "outputs": [
        "{options.outputPath}"
      ],
      "options": {
        "buildLibsFromSource": false
        ...
      },
      "configurations": {
        ...
      },
      "defaultConfiguration": "production"
    },
    "serve": {
      "executor": "@nx/angular:dev-server",
      "options": {
        "buildTarget": "my-app:build",
        "buildLibsFromSource": false
      },
      "configurations": {
        "production": {
          "buildTarget": "my-app:build:production"
        }
      }
    },
    ...
  }
},
```

{% /tabitem %}
{% /tabs %}

### Add executor to target defaults

If you'd like to avoid adding `"dependsOn": ["^build"]` to every application in your workspace that uses one of the
required executors you can add it to the `targetDefaults` section of the `nx.json`:

{% tabs %}
{% tabitem label="@nx/angular:application" %}

```json
// nx.json
{
  "targetDefaults": {
    "@nx/angular:application": {
      "dependsOn": ["^build"]
    }
  }
}
```

{% /tabitem %}
{% tabitem label="@nx/angular:browser-esbuild" %}

```json
// nx.json
{
  "targetDefaults": {
    "@nx/angular:browser-esbuild": {
      "dependsOn": ["^build"]
    }
  }
}
```

{% /tabitem %}
{% tabitem label="@nx/angular:webpack-browser" %}

```json
// nx.json
{
  "targetDefaults": {
    "@nx/angular:webpack-browser": {
      "dependsOn": ["^build"]
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

## Running and serving incremental builds

To build an application incrementally use the following command:

```shell
nx build my-app --parallel
```

To serve an application incrementally use this command:

```shell
nx serve my-app
```

### Build target name

It is required to use the same target name for the build target (target using one of the executors that support
incremental builds: `@nx/angular:application`, `@nx/angular:browser-esbuild`, `@nx/angular:webpack-browser`,
`@nx/angular:package` and `@nx/angular:ng-packagr-lite`) in the
project being built and the buildable libraries it depends on. The executors that support incremental builds rely on the
build target name of the project to identify which of the libraries it depends on are buildable.

If you need to have a different build target name for an application (or library) build (e.g. when composing different
targets), you need to make sure the build target name of all the relevant projects is the same.

Say you have the same application above with a configuration as follows:

```jsonc
// project.json
{
  "projectType": "application",
  ...
  "targets": {
    "build-base": {
      "executor": "@nx/angular:webpack-browser",
      "outputs": [
        "{options.outputPath}"
      ],
      "options": {
        "buildLibsFromSource": false
        ...
      },
      "configurations": {
        ...
      }
    },
    "build": {
      "executor": "nx:run-commands",
      "outputs": [
        "{options.outputPath}"
      ],
      "options": {
        "commands": [
          "node ./tools/scripts/important-script.js",
          "node ./tools/scripts/another-important-script.js"
        ],
        ...
      },
      "configurations": {
        ...
      }
    },
    "serve": {
      "executor": "@nx/angular:dev-server",
      "options": {
        "buildTarget": "my-app:build-base",
        "buildLibsFromSource": false
      },
      "configurations": {
        "production": {
          "buildTarget": "my-app:build-base:production"
        }
      }
    },
    ...
  }
},
```

And the `targetDefaults` configured in the `nx.json` as:

```json
{
  "targetDefaults": {
    "build": {
      "dependsOn": ["build-base"]
    },
    "build-base": {
      "dependsOn": ["^build-base"]
    }
  }
}
```

The build target name of the application is `build-base`. Therefore, the build target name of the buildable libraries it
depends on must also be `build-base`:

```jsonc
{
  "projectType": "library",
  ...
  "targets": {
    "build-base": {
      "executor": "@nx/angular:ng-packagr-lite",
      "outputs": [
        "{workspaceRoot}/dist/libs/my-lib"
      ],
      "options": {
        ...
      },
      "configurations": {
        ...
      },
      "defaultConfiguration": "production"
    },
    ...
  },
  ...
},
```

## Example repository

Check out the [nx-incremental-large-repo](https://github.com/nrwl/nx-incremental-large-repo) for a live example.

{% github_repository url="https://github.com/nrwl/nx-incremental-large-repo" /%}

---
<!-- source: https://nx.dev/docs/technologies/angular/guides/use-environment-variables-in-angular.md -->
## Using Environment Variables in Angular Applications

## For Angular applications using ESBuild

### Setting the `define` option of the `application` executor

{% aside type="note" title="Required Angular version" %}
Support for the `define` option requires Angular **17.2.0** or later.
{% /aside %}

In Angular applications using the `@nx/angular:application` or `@angular-devkit/build-angular:application` executors, you can set the `define` option in the `build` target to define variables that will be available in your application code at build time:

```json {% meta="{6,9-11}" %}
// apps/my-app/project.json
{
  ...
  "targets": {
    "build": {
      "executor": "@nx/angular:application",
      "options": {
        ...
        "define": {
          "MY_API_URL": "http://localhost:3333"
        }
      }
    },
    ...
  }
}
```

{% aside type="note" title="Nx executors for Angular" %}
When you use one of the `@nx/angular` executors for building your applications, make sure to also change the `serve` executor to `@nx/angular:dev-server` to ensure the extra features provided by Nx are also available when serving the application.
{% /aside %}

Next, make sure to inform TypeScript of the defined variables to prevent type-checking errors during the build. We can achieve this in a number of ways. For example you could create or update a type definition file included in the TypeScript build process (e.g. `src/types.d.ts`) with `declare` statements for the defined variables:

```ts
// apps/my-app/src/types.d.ts
declare const MY_API_URL: string;
```

The above would allow you to use the `MY_API_URL` variable in your application code as in the following example:

```ts {% meta="{7}" %}
// apps/my-app/src/app/api-http-client.ts
import { Injectable } from '@angular/core';

@Injectable({ providedIn: 'root' })
export class ApiHttpClient {
  constructor() {
    console.log('API URL:', MY_API_URL);
  }
}
```

You can also define the variables in a way that allows you to consume them as you would do in Node.js applications:

```json {% meta="{6,9-11}" %}
// apps/my-app/project.json
{
  ...
  "targets": {
    "build": {
      "executor": "@nx/angular:application",
      "options": {
        ...
        "define": {
          "process.env.MY_API_URL": "http://localhost:3333"
        }
      }
    },
    ...
  }
}
```

Like the previous example, you must configure TypeScript to recognize the `process.env` object. You can do this by defining the `process.env` object in a type definition file:

```ts
// apps/my-app/src/types.d.ts
declare const process: {
  env: {
    API_URL: string;
  };
};
```

{% aside type="caution" title="Beware" %}
You could also add the Node.js types to your `tsconfig.json` file, but this would add many types that you don't need in a browser environment. This can be misleading since you'll see some types are available, but the runtime functionality won't be. It's better to define only the types you need in a type definition file.
{% /aside %}

And then use the variable in your application code:

```ts {% meta="{7}" %}
// apps/my-app/src/app/api-http-client.ts
import { Injectable } from '@angular/core';

@Injectable({ providedIn: 'root' })
export class ApiHttpClient {
  constructor() {
    console.log('API URL:', process.env.MY_API_URL);
  }
}
```

### Using a custom ESBuild plugin

{% aside type="note" title="Required Angular version" %}
Support for custom ESBuild plugins requires Angular **17.0.0** or later.
{% /aside %}

The previous method is useful to statically define variables in the project configuration that will be available at build time. However, if you need to dynamically collect and define the environment variables available at build time, you can create a custom ESBuild plugin.

You can provide a custom ESBuild plugin to the `@nx/angular:application` or `@nx/angular:browser-esbuild` executors:

```json {% meta="{6,9}" %}
// apps/my-app/project.json
{
  ...
  "targets": {
    "build": {
      "executor": "@nx/angular:application",
      "options": {
        ...
        "plugins": ["apps/my-app/plugins/env-var-plugin.js"]
      }
    },
    ...
  }
}
```

Next, create the custom ESBuild plugin:

```js
// apps/my-app/plugins/env-var-plugin.js
const myOrgEnvRegex = /^MY_ORG_/i;

const envVarPlugin = {
  name: 'env-var-plugin',
  setup(build) {
    const options = build.initialOptions;

    const envVars = {};
    for (const key in process.env) {
      if (myOrgEnvRegex.test(key)) {
        envVars[key] = process.env[key];
      }
    }

    options.define['process.env'] = JSON.stringify(envVars);
  },
};

module.exports = envVarPlugin;
```

The plugin collects all environment variables that start with `MY_ORG_` and defines them in the `process.env` object. You can adjust the plugin to your needs (e.g., use a different regular expression, use a whitelist, add all environment variables, etc.).

As shown in the previous section, add the defined variables to a type definition file to ensure TypeScript recognizes them.

Now, you can define variables in an `.env` file, such as:

```text
// apps/my-app/.env
MY_ORG_API_URL=http://localhost:3333
```

{% aside type="note" title="Set environment variables from the terminal" %}
Alternatively, you can also [set environment variables when running a terminal command](/docs/guides/tips-n-tricks/define-environment-variables#adhoc-variables).
{% /aside %}

Finally, you can use the environment variables in your application code:

```ts {% meta="{7}" %}
// apps/my-app/src/app/api-http-client.ts
import { Injectable } from '@angular/core';

@Injectable({ providedIn: 'root' })
export class ApiHttpClient {
  constructor() {
    console.log('API URL:', process.env.MY_ORG_API_URL);
  }
}
```

## For Angular applications using Webpack

Angular executors for Webpack (e.g. `@nx/angular:webpack-browser` and `@angular-devkit/build-angular:browser`) don't have built-in support for using environment variables when building applications.

To add support for environment variables we need to use the webpack `DefinePlugin` in our own custom webpack configuration. We'll see how to do so in the following sections.

### A note on `NODE_ENV`

The webpack-based Angular executors (e.g. `@nx/angular:webpack-browser` and `@angular-devkit/build-angular:browser`) set the webpack's `mode` configuration option based on the values for the following in the builder options:

- `optimization`
- `optimization.scripts`
- `optimization.styles`
- `optimization.styles.minify`

If any of the above is set to `true`, webpack's `mode` is set to `production`. Otherwise, it's set to `development`.

By default, webpack automatically sets the `NODE_ENV` variable to the value of the `mode` configuration option. Therefore, Angular applications code have access to that environment variable at build time, but we can't change the `NODE_ENV` variable value directly as we would do with other environment variables because Angular always set the `mode` configuration option based on the above.

To change the `NODE_ENV` variable we can do one of the following:

- Turn on the builder optimizations to set it to `production`
- Turn off the builder optimizations to set it to `development`
- Use a custom webpack configuration to override the webpack `mode` set by Angular executors

The first two options is a matter of changing your build target configuration or passing the specific flag in the command line. We'll see how to do the last in the following section.

### Use a custom webpack configuration to support environment variables

Update the `build` and `serve` targets to use the `@nx/angular` relevant executors and provide a custom Webpack configuration:

```json {% meta="{6,9-11,15}" %}
// apps/my-app/project.json
{
  ...
  "targets": {
    "build": {
      "executor": "@nx/angular:webpack-browser",
      "options": {
        ...
        "customWebpackConfig": {
          "path": "apps/my-app/webpack.config.js"
        }
      }
    },
    "serve": {
      "executor": "@nx/angular:dev-server"
      ...
    },
    ...
  }
}
```

Then, we can use `DefinePlugin` in our custom Webpack configuration:

```js
// apps/my-app/webpack.config.js
const webpack = require('webpack');

const myOrgEnvRegex = /^MY_ORG_/i;

function getClientEnvironment() {
  const envVars = {};
  for (const key in process.env) {
    if (myOrgEnvRegex.test(key)) {
      envVars[key] = process.env[key];
    }
  }

  return {
    'process.env': JSON.stringify(envVars),
  };
}

module.exports = (config, options, context) => {
  // Overwrite the mode set by Angular if the NODE_ENV is set
  config.mode = process.env.NODE_ENV || config.mode;
  config.plugins.push(new webpack.DefinePlugin(getClientEnvironment()));
  return config;
};
```

In our custom Webpack configuration we collect all environment variables that start with `MY_ORG_`, define the `process.env` object with them, and provide it to the `DefinePlugin`. You can adjust the configuration to your needs (e.g., use a different regular expression, use a whitelist, add all environment variables, etc.).

Next, make sure to inform TypeScript of the defined variables to prevent type-checking errors during the build. We can achieve this in a number of ways. For example you could create or update a type definition file included in the TypeScript build process (e.g. `src/types.d.ts`) with `declare` statements for the defined variables:

```ts
// apps/my-app/src/types.d.ts
declare const process: {
  env: {
    MY_ORG_API_URL: string;
  };
};
```

Now, we can define variables in our `.env` file, such as:

```text
// apps/my-app/.env
MY_ORG_API_URL=http://localhost:3333
```

{% aside type="note" title="Set environment variables from the terminal" %}
Alternatively, you can also [set environment variables when running a terminal command](/docs/guides/tips-n-tricks/define-environment-variables#adhoc-variables).
{% /aside %}

Finally, we can use environment variables in our code:

```ts {% meta="{7}" %}
// apps/my-app/src/app/api-http-client.ts
import { Injectable } from '@angular/core';

@Injectable({ providedIn: 'root' })
export class ApiHttpClient {
  constructor() {
    console.log('API URL:', process.env.MY_ORG_API_URL);
  }
}
```

### Using environment variables in `index.html`

While you cannot use environment variables in `index.html`, one workaround is to create different `index.*.html` files, such
as `index.prod.html`, then swap them in different environments.

For example, you can configure your `build` target in `project.json` as follows:

```json {% meta="{11-16}" %}
// project.json
{
  ...
  "targets": {
    "build": {
      "executor": "@angular-devkit/build-angular:browser",
      ...
      "configurations": {
        "production": {
          ...
          "fileReplacements": [
            {
              "replace": "apps/my-app/src/index.html",
              "with": "apps/my-app/src/index.prod.html"
            }
          ]
        }
      }
    }
  }
}
```

{% aside type="note" title="Optimize" %}
You can also customize your webpack configuration, similar to using `DefinePlugin` above. This approach will require post-processing the `index.html` file, and is out of scope for this guide.
{% /aside %}

---
<!-- source: https://nx.dev/docs/technologies/angular/guides/using-tailwind-css-with-angular-projects.md -->
## Using Tailwind CSS with Angular

This guide shows how to set up and configure [Tailwind CSS](https://tailwindcss.com/) with [Angular](https://angular.dev/) projects in an Nx workspace.

## Installation

For the most up-to-date installation instructions, refer to the official Tailwind CSS documentation:

- **Angular projects**: [Tailwind CSS with Angular](https://tailwindcss.com/docs/installation/framework-guides/angular)
- **Other setups**: [Tailwind CSS installation guide](https://tailwindcss.com/docs/installation)

## Configuring sources for monorepos

### Tailwind CSS v4

Tailwind CSS v4 [automatically detects classes from source files](https://tailwindcss.com/docs/detecting-classes-in-source-files). However, with Angular PostCSS plugin, scanning starts from the workspace root by default. This means classes from all libraries end up in your production CSS, even unused ones.

To avoid bloated CSS, restrict scanning to your app folder and explicitly add your library dependencies:

```css
// apps/myapp/src/styles.css
@import "tailwindcss" source("./app");

@source "../../../libs/ui";
@source "../../../libs/shared";
```

#### Automating @source directives

Manually maintaining `@source` directives is tedious and error-prone. Use [`@juristr/nx-tailwind-sync`](https://www.npmjs.com/package/@juristr/nx-tailwind-sync) to automate this based on your project's dependency graph.

Install the package:

```shell
npm install @juristr/nx-tailwind-sync
```

Register the sync generator for your application's `build` and `serve` targets:

{% tabs syncKey="project-config-file" %}
{% tabitem label="project.json" %}

```json
{
  "name": "myapp",
  "targets": {
    "build": {
      "executor": "@angular/build:application",
      "syncGenerators": ["@juristr/nx-tailwind-sync:source-directives"]
    },
    "serve": {
      "executor": "@angular/build:dev-server",
      "syncGenerators": ["@juristr/nx-tailwind-sync:source-directives"]
    }
  }
}
```

{% /tabitem %}
{% tabitem label="package.json" %}

```json
{
  "name": "myapp",
  "nx": {
    "targets": {
      "build": {
        "syncGenerators": ["@juristr/nx-tailwind-sync:source-directives"]
      },
      "serve": {
        "syncGenerators": ["@juristr/nx-tailwind-sync:source-directives"]
      }
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

When you run `nx build myapp` or `nx serve myapp`, the sync generator analyzes your dependency graph and updates your `styles.css` with the correct `@source` directives automatically.

For more details on why this is necessary and how Tailwind's scanning behavior differs between PostCSS and Vite, see [Tailwind v4 with Angular in an Nx Monorepo](/blog/setup-tailwind-4-angular-nx-workspace).

### Tailwind CSS v3

For Tailwind CSS v3, the [`content`](https://v3.tailwindcss.com/docs/content-configuration) property should be configured to include glob patterns that cover your project and its dependencies:

```javascript
// apps/my-app/tailwind.config.js
const { join } = require('path');

module.exports = {
  content: [
    join(__dirname, 'src/**/*.{ts,html}'),
    join(__dirname, '../../libs/**/*.{ts,html}'),
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};
```

You can adjust the glob patterns based on your workspace structure. For example, you can be more selective by targeting individual libraries such as `libs/my-lib` rather than all libraries (`libs`). To learn how to automatically sync library dependencies with Tailwind sources, watch our video [Never Update Tailwind Glob Patterns Manually Again](https://www.youtube.com/watch?v=huTmV-F8c0A).

---
<!-- source: https://nx.dev/docs/technologies/angular/introduction.md -->
## Angular Plugin for Nx

[Angular](https://angular.dev) is a framework for building web applications. Nx has first party support for Angular projects. If you're familiar with the Angular CLI, `ng`, then Nx CLI will feel very familiar.
The `@nx/angular` plugin adds [generators](#local-development), Angular CLI builder integration (executors) and migrations so you can run Angular tasks through Nx. With Nx, each project has its own configuration instead of a single `angular.json` file, making it more scalable for monorepos.
You can use Angular with Nx without the plugin and still get [task caching](/docs/features/cache-task-results), [task orchestration](/docs/features/run-tasks), and the [project graph](/docs/features/explore-graph).

## Requirements

The `@nx/angular` plugin supports the following package versions.

| Package         | Supported Versions |
| --------------- | ------------------ |
| `@angular/core` | >= 19.0.0 < 22.0.0 |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

For older Nx versions, see the full [Nx and Angular versions matrix](/docs/technologies/angular/guides/angular-nx-version-matrix).

## Setup

### Add to an existing workspace

{% aside type="note" title="Keep Nx package versions in sync" %}
Install the `@nx/angular` version that matches your `nx` version to avoid hard-to-debug errors. See [Keep Nx versions in sync](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
Using `nx add` helps ensure the correct version is installed and configured.
{% /aside %}

```shell
nx add @nx/angular
```

Verify the plugin is active by inspecting an Angular project:

```shell
nx show project <your-app-name>
```

Look for `build`, `serve`, `test`, `lint`, or `e2e` targets generated from `angular.json`.

### Create a new workspace

```shell
npx create-nx-workspace my-org --template=nrwl/angular-template
```

{% aside type="tip" title="Angular Tutorial" %}
For a guided walkthrough, follow the [Learn Nx Tutorial](/docs/getting-started/tutorials/crafting-your-workspace).
{% /aside %}

## Local development

### Generate an Angular application

```shell
nx g @nx/angular:app apps/my-app
```

By default, Nx configures ESLint for linting, Jest for unit tests, and Cypress for e2e tests. Read more of the options available for the application generator in the [Angular application generators reference](/docs/technologies/angular/generators#application).

```shell
nx serve my-app
nx build my-app
nx test my-app
nx lint my-app
nx e2e my-app
```

### Generate an Angular library

```shell
nx g @nx/angular:lib libs/my-lib
```

By default, Nx configures ESLint for linting, Jest for unit tests. Read more of the options available for the application generator in the [angular library generators reference](/docs/technologies/angular/generators#library).

There are also generators for setting up common items inside your projects, such as components and services:

```shell
nx g @nx/angular:component libs/my-lib/src/lib/my-component
nx g @nx/angular:service libs/my-lib/src/lib/my-service
```

```shell
nx test my-lib
nx lint my-lib
```

### Buildable and publishable libraries

If you need libraries that build or publish, generate them with build output enabled and an import path. This creates build targets you can cache and run in CI.
See [Set up incremental builds for Angular libraries](/docs/technologies/angular/guides/setup-incremental-builds-angular) for details.

```shell
nx g @nx/angular:lib libs/my-lib
```

### Set up Module Federation

Nx includes generators for scaffolding [Module Federation](/docs/technologies/module-federation/concepts/module-federation-and-nx) architectures with Angular. Generate a host application and its remotes in one command:

```shell
nx g @nx/angular:host apps/shell --remotes=products,checkout
```

> See all options in the [Angular host generators reference](/docs/technologies/angular/generators#host).

Add a remote to an existing host:

```shell
nx g @nx/angular:remote apps/login --host=shell
```

> See all options in the [Angular remote generators reference](/docs/technologies/angular/generators#remote).

Pass `--dynamic` for [dynamic federation](/docs/technologies/angular/guides/dynamic-module-federation-with-angular) (remotes resolved at runtime) or `--ssr` for [server-side rendering with Module Federation](/docs/technologies/angular/guides/module-federation-with-ssr).

## CI considerations

Run only what changed using the project graph:

```shell
nx affected -t build test lint e2e
```

Enable remote caching for faster CI runs:

```shell
nx connect
```

If you use Angular CLI configurations, define a `ci` configuration in `angular.json` and run tasks with `--configuration=ci` for CI-specific settings.

See [Set Up CI](/docs/guides/nx-cloud/setup-ci) for a sample CI setup.

## What's next

{% cardgrid %}
{% linkcard title="Learn Nx Tutorial" description="Build a monorepo step-by-step with Nx." href="/docs/getting-started/tutorials/crafting-your-workspace" /%}
{% linkcard title="Migrate from Angular CLI" description="Move an existing Angular CLI project into Nx." href="/docs/technologies/angular/migration/angular" /%}
{% linkcard title="Dynamic Module Federation" description="Load Angular remotes at runtime with dynamic federation." href="/docs/technologies/angular/guides/dynamic-module-federation-with-angular" /%}
{% linkcard title="Tailwind CSS with Angular" description="Add Tailwind CSS to Angular apps and libraries." href="/docs/technologies/angular/guides/using-tailwind-css-with-angular-projects" /%}
{% linkcard title="Angular Generators Reference" description="All @nx/angular generators." href="/docs/technologies/angular/generators" /%}
{% linkcard title="Angular Executors Reference" description="All @nx/angular executors." href="/docs/technologies/angular/executors" /%}
{% /cardgrid %}

---
<!-- source: https://nx.dev/docs/technologies/angular/migration.md -->
## Angular Migration

{% index_page_cards path="technologies/angular/migration" /%}

---
<!-- source: https://nx.dev/docs/technologies/angular/migration/angular.md -->
## Migrating an Angular CLI Project to Nx

Within an Nx workspace, you gain many capabilities that help you build applications and libraries. If you are currently using an Angular CLI workspace, you can transform it into an Nx workspace.

## Migrating to a standalone Angular app with Nx

You can migrate to a standalone Angular app with the command:

```shell
npx nx@latest init
```

This command will install the correct version of Nx based on your Angular version.

This will enable you to use the Nx CLI in your existing Angular CLI workspace while keeping your existing file structure in place. The following changes will be made in your repo to enable Nx:

- The `nx`, `@nx/workspace` and `prettier` packages will be installed.
- An `nx.json` file will be created in the root of your workspace.
- For an Angular 14+ repo, the `angular.json` file is split into separate `project.json` files for each project.

**Note:** The changes will be slightly different for Angular 13 and lower.

## Migrating to an Nx Monorepo

If you want to migrate your Angular CLI project to an Nx Monorepo, run the following command:

```shell
npx nx@latest init --integrated
```

The command applies the following changes to your workspace:

- Installs the `nx`, `@nx/angular` and `@nx/workspace` packages.
- Moves your applications into the `apps` folder, and updates the relevant file paths in your configuration files.
- Moves your e2e suites into the `apps/<app name>-e2e` folder, and updates the relevant file paths in your configuration files.
- Moves your libraries into the `libs` folder, and updates the relevant file paths in your configuration files.
- Updates your `package.json` scripts to use `nx` instead of `ng`.
- Splits your `angular.json` into `project.json` files for each project with updated paths.

### Importing additional Angular CLI projects

If you have multiple Angular CLI workspaces that you want to consolidate into a single Nx monorepo, you can use [`nx import`](/docs/guides/adopting-nx/import-project) to bring additional projects into an existing Nx workspace while preserving their git history.

After the changes are applied, your workspace file structure should look similar to the one below:

{% filetree %}

- <workspace_name>/
  - apps/
    - <app_name>/
      - src/
        - app/
        - assets/
        - favicon.ico
        - index.html
        - main.ts
        - styles.css
        - project.json
        - tsconfig.app.json
        - tsconfig.spec.json
  - libs/
    - <lib_name>/
      - src/
      - ng-package.json
      - package.json
      - project.json
      - README.md
      - tsconfig.lib.json
      - tsconfig.lib.prod.json
      - tsconfig.spec.json
  - tools/
  - .editorconfig
  - .gitignore
  - .prettierignore
  - .prettierrc
  - nx.json
  - package.json
  - README.md
  - tsconfig.base.json

{% /filetree %}

## After migration

Your workspace is now powered by Nx! You can verify that your application still runs as intended:

- To serve, run `nx serve <app name>`.
- To build, run `nx build <app name>`.
- To run unit tests, run `nx test <app name>`.
- To see your project graph, run `nx graph`.

> Your project graph will grow as you add and use more applications and libraries. You can add the `--watch` flag to `nx graph` to see the changes in-browser as you add them.

For guidance on setting up CI, see the [CI setup guide](/docs/guides/nx-cloud/setup-ci).

## Learn more

Learn more about the advantages of Nx in the following guides:

- [Using Cypress for e2e tests](/docs/technologies/test-tools/cypress/introduction)
- [Using Jest for unit tests](/docs/technologies/test-tools/jest/introduction)
- [Computation Caching](/docs/concepts/how-caching-works)
- [Rebuilding and Retesting What is Affected](/docs/features/ci-features/affected)
- [Integrate with Editors](/docs/getting-started/editor-setup)
- [Advanced Angular Micro Frontends with Dynamic Module Federation](/docs/technologies/angular/guides/dynamic-module-federation-with-angular)

{% linkcard title="Nx and the Angular CLI" description="Differences between Nx and the Angular CLI" href="/docs/technologies/angular/guides/nx-and-angular" /%}

---
<!-- source: https://nx.dev/docs/technologies/angular/migrations.md -->
## @nx/angular Migrations

The @nx/angular plugin provides various migrations to help you migrate to newer versions of angular projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 22.6.x

### 22.6.0-angular-eslint-package-updates
**Version**: 22.6.0-beta.6


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `angular-eslint` | `^21.2.0` | Updated only
| `@angular-eslint/eslint-plugin` | `^21.2.0` | Updated only
| `@angular-eslint/eslint-plugin-template` | `^21.2.0` | Updated only
| `@angular-eslint/template-parser` | `^21.2.0` | Updated only
| `@angular-eslint/utils` | `^21.2.0` | Updated only
| `@angular-eslint/schematics` | `^21.2.0` | Updated only
| `@angular-eslint/test-utils` | `^21.2.0` | Updated only
| `@angular-eslint/builder` | `^21.2.0` | Updated only
| `@angular-eslint/bundled-angular-compiler` | `^21.2.0` | Updated only


### 22.6.0-@angular-eslint-package-updates
**Version**: 22.6.0-beta.6


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular-eslint/eslint-plugin` | `^21.2.0` | Updated only
| `@angular-eslint/eslint-plugin-template` | `^21.2.0` | Updated only
| `@angular-eslint/template-parser` | `^21.2.0` | Updated only
| `@angular-eslint/utils` | `^21.2.0` | Updated only
| `@angular-eslint/schematics` | `^21.2.0` | Updated only
| `@angular-eslint/test-utils` | `^21.2.0` | Updated only
| `@angular-eslint/builder` | `^21.2.0` | Updated only
| `@angular-eslint/bundled-angular-compiler` | `^21.2.0` | Updated only


### 22.6.0-package-updates
**Version**: 22.6.0-beta.6


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular/cli` | `~21.2.0` | Updated only
| `@angular-devkit/build-angular` | `~21.2.0` | Updated only
| `@angular-devkit/core` | `~21.2.0` | Updated only
| `@angular-devkit/schematics` | `~21.2.0` | Updated only
| `@angular/build` | `~21.2.0` | Updated only
| `@angular/pwa` | `~21.2.0` | Updated only
| `@angular/ssr` | `~21.2.0` | Updated only
| `@schematics/angular` | `~21.2.0` | Updated only
| `@angular-devkit/architect` | `~0.2102.0` | Updated only
| `@angular-devkit/build-webpack` | `~0.2102.0` | Updated only
| `@angular/core` | `~21.2.0` | Added if not installed
| `@angular/material` | `~21.2.0` | Updated only
| `@angular/cdk` | `~21.2.0` | Updated only
| `@angular/google-maps` | `~21.2.0` | Updated only
| `ng-packagr` | `~21.2.0` | Updated only


### 22.6.0-module-federation-package-updates
**Version**: 22.6.0-beta.10


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@module-federation/enhanced` | `^2.1.0` | Updated only
| `@module-federation/node` | `^2.7.21` | Updated only



## 22.4.x

### 22.4.0-package-updates
**Version**: 22.4.0-beta.4


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular/cli` | `~21.1.0` | Updated only
| `@angular-devkit/build-angular` | `~21.1.0` | Updated only
| `@angular-devkit/core` | `~21.1.0` | Updated only
| `@angular-devkit/schematics` | `~21.1.0` | Updated only
| `@angular/build` | `~21.1.0` | Updated only
| `@angular/pwa` | `~21.1.0` | Updated only
| `@angular/ssr` | `~21.1.0` | Updated only
| `@schematics/angular` | `~21.1.0` | Updated only
| `@angular-devkit/architect` | `~0.2101.0` | Updated only
| `@angular-devkit/build-webpack` | `~0.2101.0` | Updated only
| `@angular/core` | `~21.1.0` | Added if not installed
| `@angular/material` | `~21.1.0` | Updated only
| `@angular/cdk` | `~21.1.0` | Updated only
| `@angular/google-maps` | `~21.1.0` | Updated only
| `ng-packagr` | `~21.1.0` | Updated only



## 22.3.x

### `update-ssr-webpack-config-22-2-0`
**Version**: 22.3.0-beta.0

Updates webpack-based SSR configuration to use preserve module format and bundler module resolution.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=21.0.0` |
#### Updates Webpack-Based SSR Configuration

Updates the TypeScript configuration and import syntax for webpack-based server-side rendering (SSR) projects. This migration sets `module: "preserve"` and `moduleResolution: "bundler"` in `tsconfig.server.json` to align with Angular's build requirements, and updates server file imports from namespace imports (`import * as express`) to default imports (`import express`) to work correctly with the new module format.

#### Examples

For webpack-based SSR projects (using `@nx/angular:webpack-server` or `@angular-devkit/build-angular:server`), the migration updates the `tsconfig.server.json` file:

##### Before

```jsonc {7-8}
// apps/my-app/tsconfig.server.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "../../dist/out-tsc",
    "target": "es2022",
    "module": "commonjs",
    "moduleResolution": "node",
    "types": ["node"],
  },
  "files": ["src/main.server.ts", "src/server.ts"],
}
```

##### After

```jsonc {7-8}
// apps/my-app/tsconfig.server.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "../../dist/out-tsc",
    "target": "es2022",
    "module": "preserve",
    "moduleResolution": "bundler",
    "types": ["node"],
  },
  "files": ["src/main.server.ts", "src/server.ts"],
}
```

The migration also updates import statements in the `server.ts` file to use default imports instead of namespace imports:

##### Before

```ts {2-4}
// apps/my-app/src/server.ts
import * as express from 'express';
import * as compression from 'compression';
import * as cors from 'cors';

const app = express();
app.use(compression());
app.use(cors());
```

##### After

```ts {2-4}
// apps/my-app/src/server.ts
import express from 'express';
import compression from 'compression';
import cors from 'cors';

const app = express();
app.use(compression());
app.use(cors());
```

Projects that already have the correct TypeScript configuration or projects without a `tsconfig.server.json` file are not modified by this migration.



### `update-module-resolution-22-2-0`
**Version**: 22.3.0-beta.0

Update 'module' to 'preserve' and 'moduleResolution' to 'bundler' in TypeScript configurations for Angular projects.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=21.0.0-rc.3` |
#### Update `module` to `preserve` and `moduleResolution` to `bundler` in TypeScript configurations

Updates the TypeScript `module` and `moduleResolution` compiler options to `'preserve'` and `'bundler'` respectively for Angular projects. These settings are required for Angular's build system to work correctly with modern module resolution algorithms used by bundlers like Webpack, Vite, and esbuild.

#### Examples

The migration updates TypeScript configuration files in Angular projects to set both compiler options:

##### Before

```jsonc {4-5}
// apps/my-app/tsconfig.app.json
{
  "compilerOptions": {
    "module": "es2020",
    "moduleResolution": "node",
  },
}
```

##### After

```jsonc {4-5}
// apps/my-app/tsconfig.app.json
{
  "compilerOptions": {
    "module": "preserve",
    "moduleResolution": "bundler",
  },
}
```

If both values are already set correctly and inherited from an extended tsconfig file, the migration will not modify the configuration:

##### Before

```jsonc {5-6}
// apps/my-app/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "module": "preserve",
    "moduleResolution": "bundler",
  },
}
```

```jsonc {4-6}
// apps/my-app/tsconfig.app.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "types": [],
  },
}
```

##### After

```jsonc {5-6}
// apps/my-app/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "module": "preserve",
    "moduleResolution": "bundler",
  },
}
```

```jsonc {4-6}
// apps/my-app/tsconfig.app.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "types": [],
  },
}
```

The migration only processes TypeScript configuration files that are referenced by Angular project build targets, ensuring that only Angular-specific configurations are updated.



### `update-typescript-lib-22-2-0`
**Version**: 22.3.0-beta.0

Updates the 'lib' property in tsconfig files to use 'es2022' or a more modern version.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=21.0.0` |
#### Update TypeScript `lib` compiler option to ES2022

Updates the TypeScript `lib` compiler option in Angular projects to ensure compatibility with Angular v21+, which requires ES2022 as the minimum ECMAScript version. The migration upgrades any ES versions older than ES2022 (such as ES2015, ES2020, etc.) to ES2022 while preserving other library entries like `'dom'`, `'webworker'`, etc.

#### Examples

The migration processes TypeScript configuration files referenced by Angular project build targets and updates the `lib` compiler option when outdated ES versions are detected:

##### Before

```jsonc {4}
// apps/my-app/tsconfig.app.json
{
  "compilerOptions": {
    "lib": ["es2020", "dom"],
  },
}
```

##### After

```jsonc {4}
// apps/my-app/tsconfig.app.json
{
  "compilerOptions": {
    "lib": ["dom", "es2022"],
  },
}
```

When the `lib` array contains only an ES version older than ES2022 without additional entries, it is upgraded:

##### Before

```jsonc {4}
// apps/my-app/tsconfig.app.json
{
  "compilerOptions": {
    "lib": ["es2020"],
  },
}
```

##### After

```jsonc {4}
// apps/my-app/tsconfig.app.json
{
  "compilerOptions": {
    "lib": ["es2022"],
  },
}
```

If the configuration already uses ES2022 or higher (e.g., `'es2023'`, `'esnext'`), no changes are made:

##### Before

```jsonc {4}
// apps/my-app/tsconfig.app.json
{
  "compilerOptions": {
    "lib": ["es2022", "dom"],
  },
}
```

##### After

```jsonc {4}
// apps/my-app/tsconfig.app.json
{
  "compilerOptions": {
    "lib": ["es2022", "dom"],
  },
}
```

When the `lib` array contains multiple library entries, only the ES version is upgraded while all other entries are preserved:

##### Before

```jsonc {4}
// apps/my-app/tsconfig.app.json
{
  "compilerOptions": {
    "lib": ["es2020", "dom", "webworker"],
  },
}
```

##### After

```jsonc {4}
// apps/my-app/tsconfig.app.json
{
  "compilerOptions": {
    "lib": ["dom", "webworker", "es2022"],
  },
}
```

The migration only processes TypeScript configuration files that are referenced by Angular project build targets, ensuring that only Angular-specific configurations are updated.



### `update-unit-test-runner-option`
**Version**: 22.3.0-beta.0

Update 'vitest' unit test runner option to 'vitest-analog' in generator defaults.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=21.0.0` |
#### Update `vitest` unit test runner option to `vitest-analog` in generator defaults

Updates the `unitTestRunner` generator default from `vitest` to `vitest-analog` in `nx.json`. The `vitest` option has been split into two explicit options: `vitest-angular` (uses `@angular/build:unit-test`) and `vitest-analog` (uses AnalogJS-based setup).

#### Examples

The migration updates generator defaults in `nx.json`:

##### Before

```jsonc {5}
// nx.json
{
  "generators": {
    "@nx/angular:application": {
      "unitTestRunner": "vitest",
    },
  },
}
```

##### After

```jsonc {5}
// nx.json
{
  "generators": {
    "@nx/angular:application": {
      "unitTestRunner": "vitest-analog",
    },
  },
}
```



### `set-isolated-modules-22-3-0`
**Version**: 22.3.0-beta.3

Set 'isolatedModules' to 'true' in TypeScript test configurations for Angular projects.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=21.0.0` |
#### Set `isolatedModules` to `true` in TypeScript test configurations

Sets the TypeScript `isolatedModules` compiler option to `true` in `tsconfig.spec.json` files for Angular projects using the Jest test runner.

#### Examples

The migration updates TypeScript test configuration files in Angular projects using the Jest test runner to set the `isolatedModules` compiler option:

##### Before

```jsonc {3-5}
// apps/my-app/tsconfig.spec.json
{
  "compilerOptions": {
    "outDir": "./out-tsc/spec",
  },
}
```

##### After

```jsonc {4-5}
// apps/my-app/tsconfig.spec.json
{
  "compilerOptions": {
    "outDir": "./out-tsc/spec",
    "isolatedModules": true,
  },
}
```

If the value is already set to `true` or inherited from an extended tsconfig file, the migration will not modify the configuration:

##### Before

```jsonc {4}
// tsconfig.json
{
  "compilerOptions": {
    "isolatedModules": true,
  },
}
```

```jsonc {4-6}
// apps/my-app/tsconfig.spec.json
{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "outDir": "./out-tsc/spec",
  },
}
```

##### After

```jsonc {4}
// tsconfig.json
{
  "compilerOptions": {
    "isolatedModules": true,
  },
}
```

```jsonc {4-6}
// apps/my-app/tsconfig.spec.json
{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "outDir": "./out-tsc/spec",
  },
}
```

The migration only processes TypeScript test configuration files (`tsconfig.spec.json` or custom test tsconfig files referenced by `@nx/jest:jest` tasks) in Angular projects.



### `update-jest-preset-angular-setup`
**Version**: 22.3.0-beta.3

Replace 'jest-preset-angular/setup-jest' imports with the new 'setupZoneTestEnv' function.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=21.0.0` |
#### Update Jest Preset Angular Setup

Replaces the removed `jest-preset-angular/setup-jest` import with the new `setupZoneTestEnv` function from `jest-preset-angular/setup-env/zone`.

Starting with `jest-preset-angular` v15, the `setup-jest` files have been removed and replaced with explicit setup functions. The old `setup-jest` import only supported zone-based testing (zoneless support was added in v14.3.0 with the new `setupZonelessTestEnv` function), so all projects using the removed import are migrated to use `setupZoneTestEnv`.

#### Examples

##### Before

```ts title="apps/my-app/src/test-setup.ts"
import 'jest-preset-angular/setup-jest';
```

##### After

```ts title="apps/my-app/src/test-setup.ts"
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';

setupZoneTestEnv();
```



### 22.3.0-package-updates
**Version**: 22.3.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular/cli` | `~21.0.0` | Updated only
| `@angular-devkit/build-angular` | `~21.0.0` | Updated only
| `@angular-devkit/core` | `~21.0.0` | Updated only
| `@angular-devkit/schematics` | `~21.0.0` | Updated only
| `@angular/build` | `~21.0.0` | Updated only
| `@angular/pwa` | `~21.0.0` | Updated only
| `@angular/ssr` | `~21.0.0` | Updated only
| `@schematics/angular` | `~21.0.0` | Updated only
| `@angular-devkit/architect` | `~0.2100.0` | Updated only
| `@angular-devkit/build-webpack` | `~0.2100.0` | Updated only
| `@angular/core` | `~21.0.0` | Added if not installed
| `@angular/material` | `~21.0.0` | Updated only
| `@angular/cdk` | `~21.0.0` | Updated only
| `@angular/google-maps` | `~21.0.0` | Updated only
| `ng-packagr` | `~21.0.0` | Updated only
| `zone.js` | `~0.16.0` | Updated only


### 22.3.0-angular-eslint-package-updates
**Version**: 22.3.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `angular-eslint` | `^21.0.1` | Updated only
| `@angular-eslint/eslint-plugin` | `^21.0.1` | Updated only
| `@angular-eslint/eslint-plugin-template` | `^21.0.1` | Updated only
| `@angular-eslint/template-parser` | `^21.0.1` | Updated only
| `@angular-eslint/utils` | `^21.0.1` | Updated only
| `@angular-eslint/schematics` | `^21.0.1` | Updated only
| `@angular-eslint/test-utils` | `^21.0.1` | Updated only
| `@angular-eslint/builder` | `^21.0.1` | Updated only
| `@angular-eslint/bundled-angular-compiler` | `^21.0.1` | Updated only


### 22.3.0-@angular-eslint-package-updates
**Version**: 22.3.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular-eslint/eslint-plugin` | `^21.0.1` | Updated only
| `@angular-eslint/eslint-plugin-template` | `^21.0.1` | Updated only
| `@angular-eslint/template-parser` | `^21.0.1` | Updated only
| `@angular-eslint/utils` | `^21.0.1` | Updated only
| `@angular-eslint/schematics` | `^21.0.1` | Updated only
| `@angular-eslint/test-utils` | `^21.0.1` | Updated only
| `@angular-eslint/builder` | `^21.0.1` | Updated only
| `@angular-eslint/bundled-angular-compiler` | `^21.0.1` | Updated only


### 22.3.2-ngrx-package-updates
**Version**: 22.3.2-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@ngrx/store` | `^21.0.0` | Updated only



## 22.2.x

### 22.2.0-package-updates
**Version**: 22.2.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@module-federation/enhanced` | `^0.21.2` | Updated only
| `@module-federation/runtime` | `^0.21.2` | Updated only
| `@module-federation/sdk` | `^0.21.2` | Updated only
| `@module-federation/node` | `^2.7.21` | Updated only



## 21.6.x

### `update-angular-cli-version-20-3-0`
**Version**: 21.6.1-beta.2

Update the @angular/cli package version to ~20.3.0.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=20.3.0` |
#### Sample Code Changes

Update the `@angular/cli` package version in the `package.json` file at the workspace root to **~20.3.0**.

##### Before

```json title="package.json"
{
  "devDependencies": {
    "@angular/cli": "~20.2.0"
  }
}
```

##### After

```json title="package.json" {3}
{
  "devDependencies": {
    "@angular/cli": "~20.3.0"
  }
}
```



### 21.6.1-package-updates
**Version**: 21.6.1-beta.2


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular-devkit/build-angular` | `~20.3.0` | Updated only
| `@angular-devkit/core` | `~20.3.0` | Updated only
| `@angular-devkit/schematics` | `~20.3.0` | Updated only
| `@angular/build` | `~20.3.0` | Updated only
| `@angular/pwa` | `~20.3.0` | Updated only
| `@angular/ssr` | `~20.3.0` | Updated only
| `@schematics/angular` | `~20.3.0` | Updated only
| `@angular-devkit/architect` | `~0.2003.0` | Updated only
| `@angular-devkit/build-webpack` | `~0.2003.0` | Updated only
| `@angular/core` | `~20.3.0` | Added if not installed
| `@angular/material` | `~20.2.3` | Updated only
| `@angular/cdk` | `~20.2.3` | Updated only
| `@angular/google-maps` | `~20.2.3` | Updated only
| `ng-packagr` | `~20.3.0` | Updated only


### 21.6.1-angular-eslint-package-updates
**Version**: 21.6.1-beta.2


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `angular-eslint` | `^20.3.0` | Updated only
| `@angular-eslint/eslint-plugin` | `^20.3.0` | Updated only
| `@angular-eslint/eslint-plugin-template` | `^20.3.0` | Updated only
| `@angular-eslint/template-parser` | `^20.3.0` | Updated only
| `@angular-eslint/utils` | `^20.3.0` | Updated only
| `@angular-eslint/schematics` | `^20.3.0` | Updated only
| `@angular-eslint/test-utils` | `^20.3.0` | Updated only
| `@angular-eslint/builder` | `^20.3.0` | Updated only
| `@angular-eslint/bundled-angular-compiler` | `^20.3.0` | Updated only


### 21.6.1-@angular-eslint-package-updates
**Version**: 21.6.1-beta.2


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular-eslint/eslint-plugin` | `^20.3.0` | Updated only
| `@angular-eslint/eslint-plugin-template` | `^20.3.0` | Updated only
| `@angular-eslint/template-parser` | `^20.3.0` | Updated only
| `@angular-eslint/utils` | `^20.3.0` | Updated only
| `@angular-eslint/schematics` | `^20.3.0` | Updated only
| `@angular-eslint/test-utils` | `^20.3.0` | Updated only
| `@angular-eslint/builder` | `^20.3.0` | Updated only
| `@angular-eslint/bundled-angular-compiler` | `^20.3.0` | Updated only



## 21.5.x

### `set-tsconfig-option`
**Version**: 21.5.0-beta.0

Set the 'tsConfig' option to build and test targets to help with Angular migration issues.

#### Set `tsConfig` option for build and test targets

- Set the `tsConfig` option in the target options for library build executors. It moves the value from the target `development` configuration and it doesn't set it if the option is already set.
- Set `tsconfig.spec.json` as the `tsConfig` option in the target options for the `@nx/jest:jest` executor. It only does it if the file exists and the options is not already set.

#### Examples

The migration will move the `tsConfig` option for library build executors (`@nx/angular:ng-packagr-lite` and `@nx/angular:package`) from the `development` configuration to the target options if it's not already set:

##### Before

```json title="libs/lib1/project.json" {7}
{
  "targets": {
    "build": {
      "executor": "@nx/angular:ng-packagr-lite",
      "configurations": {
        "development": {
          "tsConfig": "libs/lib1/tsconfig.lib.dev.json"
        }
      }
    }
  }
}
```

##### After

```json title="libs/lib1/project.json" {6,9}
{
  "targets": {
    "build": {
      "executor": "@nx/angular:ng-packagr-lite",
      "options": {
        "tsConfig": "libs/lib1/tsconfig.lib.dev.json"
      },
      "configurations": {
        "development": {}
      }
    }
  }
}
```

The migration will set the `tsConfig` option for the `@nx/jest:jest` executor when the `tsconfig.spec.json` file exists and the option is not already set:

##### Before

```json title="apps/app1/project.json"
{
  "targets": {
    "test": {
      "executor": "@nx/jest:jest"
    }
  }
}
```

##### After

```json title="apps/app1/project.json" {6}
{
  "targets": {
    "test": {
      "executor": "@nx/jest:jest",
      "options": {
        "tsConfig": "apps/app1/tsconfig.spec.json"
      }
    }
  }
}
```

If the `tsConfig` option is already set in the target options, the migration will not modify the configuration:

##### Before

```json title="libs/lib1/project.json" {6,10}
{
  "targets": {
    "build": {
      "executor": "@nx/angular:ng-packagr-lite",
      "options": {
        "tsConfig": "libs/lib1/tsconfig.lib.json"
      },
      "configurations": {
        "development": {
          "tsConfig": "libs/lib1/tsconfig.lib.dev.json"
        }
      }
    }
  }
}
```

##### After

```json title="libs/lib1/project.json" {6,10}
{
  "targets": {
    "build": {
      "executor": "@nx/angular:ng-packagr-lite",
      "options": {
        "tsConfig": "libs/lib1/tsconfig.lib.json"
      },
      "configurations": {
        "development": {
          "tsConfig": "libs/lib1/tsconfig.lib.dev.json"
        }
      }
    }
  }
}
```



### `update-angular-cli-version-20-2-0`
**Version**: 21.5.0-beta.2

Update the @angular/cli package version to ~20.2.0.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=20.2.0` |
#### Sample Code Changes

Update the `@angular/cli` package version in the `package.json` file at the workspace root to **~20.2.0**.

##### Before

```json title="package.json"
{
  "devDependencies": {
    "@angular/cli": "~20.1.0"
  }
}
```

##### After

```json title="package.json" {3}
{
  "devDependencies": {
    "@angular/cli": "~20.2.0"
  }
}
```



### `remove-default-karma-configuration-files`
**Version**: 21.5.0-beta.2

Remove any Karma configuration files that only contain the default content. The default configuration is automatically available without a specific project configurationfile.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=20.2.0` |
#### Remove the Default Karma Configuration Files

Removes Karma configuration files that match the default configuration generated by Angular CLI to reduce boilerplate code in the workspace. The migration also removes the `karmaConfig` option from project targets when the configuration file is removed.

#### Examples

The migration will remove `karma.conf.js` files that contain only default settings and update the project configuration:

##### Before

```javascript title="apps/my-app/karma.conf.js"
// Karma configuration file, see link for more information
// https://karma-runner.github.io/1.0/config/configuration-file.html

module.exports = function (config) {
  config.set({
    basePath: '',
    frameworks: ['jasmine', '@angular-devkit/build-angular'],
    plugins: [
      require('karma-jasmine'),
      require('karma-chrome-launcher'),
      require('karma-jasmine-html-reporter'),
      require('karma-coverage'),
      require('@angular-devkit/build-angular/plugins/karma'),
    ],
    client: {
      jasmine: {
        // you can add configuration options for Jasmine here
        // the possible options are listed at https://jasmine.github.io/api/edge/Configuration.html
        // for example, you can disable the random execution with `random: false`
        // or set a specific seed with `seed: 4321`
      },
    },
    jasmineHtmlReporter: {
      suppressAll: true, // removes the duplicated traces
    },
    coverageReporter: {
      dir: require('path').join(__dirname, '../../coverage/my-app'),
      subdir: '.',
      reporters: [{ type: 'html' }, { type: 'text-summary' }],
    },
    reporters: ['progress', 'kjhtml'],
    browsers: ['Chrome'],
    restartOnFileChange: true,
  });
};
```

```json title="apps/my-app/project.json" {7}
{
  "name": "my-app",
  "targets": {
    "test": {
      "executor": "@angular-devkit/build-angular:karma",
      "options": {
        "karmaConfig": "apps/my-app/karma.conf.js",
        "polyfills": ["zone.js", "zone.js/testing"]
      }
    }
  }
}
```

##### After

File `apps/my-app/karma.conf.js` is removed.

```json title="apps/my-app/project.json"
{
  "name": "my-app",
  "targets": {
    "test": {
      "executor": "@angular-devkit/build-angular:karma",
      "options": {
        "polyfills": ["zone.js", "zone.js/testing"]
      }
    }
  }
}
```

If the Karma configuration contains customizations, the migration will preserve the file and configuration:

##### Before

```javascript title="apps/custom-app/karma.conf.js"
module.exports = function (config) {
  config.set({
    basePath: '',
    frameworks: ['jasmine', '@angular-devkit/build-angular'],
    plugins: [
      require('karma-jasmine'),
      require('karma-chrome-launcher'),
      require('karma-jasmine-html-reporter'),
      require('karma-coverage'),
      require('@angular-devkit/build-angular/plugins/karma'),
    ],
    browsers: ['ChromeHeadless'], // Custom browser configuration
    restartOnFileChange: true,
  });
};
```

##### After

```javascript title="apps/custom-app/karma.conf.js"
module.exports = function (config) {
  config.set({
    basePath: '',
    frameworks: ['jasmine', '@angular-devkit/build-angular'],
    plugins: [
      require('karma-jasmine'),
      require('karma-chrome-launcher'),
      require('karma-jasmine-html-reporter'),
      require('karma-coverage'),
      require('@angular-devkit/build-angular/plugins/karma'),
    ],
    browsers: ['ChromeHeadless'], // Custom browser configuration
    restartOnFileChange: true,
  });
};
```



### 21.5.0-package-updates
**Version**: 21.5.0-beta.2


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular-devkit/build-angular` | `~20.2.0` | Updated only
| `@angular-devkit/core` | `~20.2.0` | Updated only
| `@angular-devkit/schematics` | `~20.2.0` | Updated only
| `@angular/build` | `~20.2.0` | Updated only
| `@angular/pwa` | `~20.2.0` | Updated only
| `@angular/ssr` | `~20.2.0` | Updated only
| `@schematics/angular` | `~20.2.0` | Updated only
| `@angular-devkit/architect` | `~0.2002.0` | Updated only
| `@angular-devkit/build-webpack` | `~0.2002.0` | Updated only
| `@angular/core` | `~20.2.0` | Added if not installed
| `@angular/material` | `~20.2.0` | Updated only
| `@angular/cdk` | `~20.2.0` | Updated only
| `@angular/google-maps` | `~20.2.0` | Updated only
| `ng-packagr` | `~20.2.0` | Updated only


### 21.5.0-angular-eslint-package-updates
**Version**: 21.5.0-beta.2


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `angular-eslint` | `^20.2.0` | Updated only
| `@angular-eslint/eslint-plugin` | `^20.2.0` | Updated only
| `@angular-eslint/eslint-plugin-template` | `^20.2.0` | Updated only
| `@angular-eslint/template-parser` | `^20.2.0` | Updated only
| `@angular-eslint/utils` | `^20.2.0` | Updated only
| `@angular-eslint/schematics` | `^20.2.0` | Updated only
| `@angular-eslint/test-utils` | `^20.2.0` | Updated only
| `@angular-eslint/builder` | `^20.2.0` | Updated only
| `@angular-eslint/bundled-angular-compiler` | `^20.2.0` | Updated only


### 21.5.0-@angular-eslint-package-updates
**Version**: 21.5.0-beta.2


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular-eslint/eslint-plugin` | `^20.2.0` | Updated only
| `@angular-eslint/eslint-plugin-template` | `^20.2.0` | Updated only
| `@angular-eslint/template-parser` | `^20.2.0` | Updated only
| `@angular-eslint/utils` | `^20.2.0` | Updated only
| `@angular-eslint/schematics` | `^20.2.0` | Updated only
| `@angular-eslint/test-utils` | `^20.2.0` | Updated only
| `@angular-eslint/builder` | `^20.2.0` | Updated only
| `@angular-eslint/bundled-angular-compiler` | `^20.2.0` | Updated only



## 21.4.x

### 21.4.0-ngrx-package-updates
**Version**: 21.4.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@ngrx/store` | `^20.0.0` | Updated only



## 21.3.x

### `update-angular-cli-version-20-1-0`
**Version**: 21.3.0-beta.4

Update the @angular/cli package version to ~20.1.0.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=20.1.0` |
#### Sample Code Changes

Update the `@angular/cli` package version in the `package.json` file at the workspace root to **~20.1.0**.

##### Before

```json title="package.json"
{
  "devDependencies": {
    "@angular/cli": "~20.0.0"
  }
}
```

##### After

```json title="package.json" {3}
{
  "devDependencies": {
    "@angular/cli": "~20.1.0"
  }
}
```



### 21.3.0-package-updates
**Version**: 21.3.0-beta.4


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular-devkit/build-angular` | `~20.1.0` | Updated only
| `@angular-devkit/core` | `~20.1.0` | Updated only
| `@angular-devkit/schematics` | `~20.1.0` | Updated only
| `@angular/build` | `~20.1.0` | Updated only
| `@angular/pwa` | `~20.1.0` | Updated only
| `@angular/ssr` | `~20.1.0` | Updated only
| `@schematics/angular` | `~20.1.0` | Updated only
| `@angular-devkit/architect` | `~0.2001.0` | Updated only
| `@angular-devkit/build-webpack` | `~0.2001.0` | Updated only
| `@angular/core` | `~20.1.0` | Added if not installed
| `@angular/material` | `~20.1.0` | Updated only
| `@angular/cdk` | `~20.1.0` | Updated only
| `@angular/google-maps` | `~20.1.0` | Updated only
| `ng-packagr` | `~20.1.0` | Updated only



## 21.2.x

### `update-angular-cli-version-20-0-0`
**Version**: 21.2.0-beta.3

Update the @angular/cli package version to ~20.0.0.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=20.0.0` |
#### Sample Code Changes

Update the `@angular/cli` package version in the `package.json` file at the workspace root to **~20.0.0**.

##### Before

```json title="package.json"
{
  "devDependencies": {
    "@angular/cli": "~19.2.0"
  }
}
```

##### After

```json title="package.json" {3}
{
  "devDependencies": {
    "@angular/cli": "~20.0.0"
  }
}
```



### `migrate-provide-server-rendering-import`
**Version**: 21.2.0-beta.3

Migrate imports of `provideServerRendering` from `@angular/platform-server` to `@angular/ssr`.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=20.0.0` |
#### Migrate Imports of `provideServerRendering` from `@angular/platform-server` to `@angular/ssr`

Migrate the imports of `provideServerRendering` from `@angular/platform-server` to `@angular/ssr`. This migration will also add the `@angular/ssr` package to your dependencies if needed.

#### Examples

Change the import of `provideServerRendering` from `@angular/platform-server` to `@angular/ssr`:

##### Before

```ts title="app/app.config.server.ts" {2}
import { ApplicationConfig } from '@angular/core';
import { provideServerRendering } from '@angular/platform-server';

const serverConfig: ApplicationConfig = {
  providers: [provideServerRendering()],
};
```

##### After

```ts title="app/app.config.server.ts" {2}
import { ApplicationConfig } from '@angular/core';
import { provideServerRendering } from '@angular/ssr';

const serverConfig: ApplicationConfig = {
  providers: [provideServerRendering()],
};
```

If you already have imports from `@angular/ssr`, the migration will add `provideServerRendering` to the existing import:

##### Before

```ts title="app/app.config.server.ts" {2-3}
import { ApplicationConfig } from '@angular/core';
import { provideServerRendering } from '@angular/platform-server';
import { provideServerRouting } from '@angular/ssr';
import { serverRoutes } from './app.routes.server';

const serverConfig: ApplicationConfig = {
  providers: [provideServerRendering(), provideServerRouting(serverRoutes)],
};
```

##### After

```ts title="app/app.config.server.ts" {2}
import { ApplicationConfig } from '@angular/core';
import { provideServerRouting, provideServerRendering } from '@angular/ssr';
import { serverRoutes } from './app.routes.server';

const serverConfig: ApplicationConfig = {
  providers: [provideServerRendering(), provideServerRouting(serverRoutes)],
};
```



### `replace-provide-server-routing`
**Version**: 21.2.0-beta.3

Replace `provideServerRouting` and `provideServerRoutesConfig` with `provideServerRendering` using `withRoutes`.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=20.0.0` |
#### Replace `provideServerRouting` and `provideServerRoutesConfig` with `provideServerRendering`

Replace `provideServerRouting` and `provideServerRoutesConfig` calls with `provideServerRendering` using `withRoutes`.

#### Examples

Remove `provideServerRouting` from your providers array and update the `provideServerRendering` call to use `withRoutes`:

##### Before

```ts title="app/app.config.server.ts" {2,6}
import { ApplicationConfig } from '@angular/core';
import { provideServerRendering, provideServerRouting } from '@angular/ssr';
import { serverRoutes } from './app.routes.server';

const serverConfig: ApplicationConfig = {
  providers: [provideServerRendering(), provideServerRouting(serverRoutes)],
};
```

##### After

```ts title="app/app.config.server.ts" {2,6}
import { ApplicationConfig } from '@angular/core';
import { provideServerRendering, withRoutes } from '@angular/ssr';
import { serverRoutes } from './app.routes.server';

const serverConfig: ApplicationConfig = {
  providers: [provideServerRendering(withRoutes(serverRoutes))],
};
```

If you have `provideServerRouting` with additional arguments, the migration will preserve them:

##### Before

```ts title="app/app.config.server.ts" {4,11,12}
import { ApplicationConfig } from '@angular/core';
import {
  provideServerRendering,
  provideServerRouting,
  withAppShell,
} from '@angular/ssr';
import { serverRoutes } from './app.routes.server';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(),
    provideServerRouting(serverRoutes, withAppShell(AppShellComponent)),
  ],
};
```

##### After

```ts title="app/app.config.server.ts" {2,7-10}
import { ApplicationConfig } from '@angular/core';
import { provideServerRendering, withAppShell, withRoutes } from '@angular/ssr';
import { serverRoutes } from './app.routes.server';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(
      withRoutes(serverRoutes),
      withAppShell(AppShellComponent)
    ),
  ],
};
```

Remove `provideServerRoutesConfig` from your providers array and update the `provideServerRendering` call to use `withRoutes`:

##### Before

```ts title="app/app.config.server.ts" {4,11,12}
import { ApplicationConfig } from '@angular/core';
import {
  provideServerRendering,
  provideServerRoutesConfig,
  withAppShell,
} from '@angular/ssr';
import { serverRoutes } from './app.routes.server';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(),
    provideServerRoutesConfig(serverRoutes, withAppShell(AppShellComponent)),
  ],
};
```

##### After

```ts title="app/app.config.server.ts" {2,7-10}
import { ApplicationConfig } from '@angular/core';
import { provideServerRendering, withAppShell, withRoutes } from '@angular/ssr';
import { serverRoutes } from './app.routes.server';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(
      withRoutes(serverRoutes),
      withAppShell(AppShellComponent)
    ),
  ],
};
```



### `set-generator-defaults-for-previous-style-guide`
**Version**: 21.2.0-beta.3

Update the generator defaults to maintain the previous style guide behavior.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=20.0.0` |
#### Set Generator Defaults for Previous Style Guide

Updates the generator defaults in the `nx.json` file to maintain the previous Angular Style Guide behavior. This ensures that newly generated code in existing workspaces follows the same conventions as the existing codebase.

#### Examples

The migration will add default configurations for the relevant Angular generators in the workspace's `nx.json` file:

##### Before

```json title="nx.json"
{
  "generators": {}
}
```

##### After

```json title="nx.json"
{
  "generators": {
    "@nx/angular:component": {
      "type": "component"
    },
    "@nx/angular:directive": {
      "type": "directive"
    },
    "@nx/angular:service": {
      "type": "service"
    },
    "@nx/angular:scam": {
      "type": "component"
    },
    "@nx/angular:scam-directive": {
      "type": "directive"
    },
    "@nx/angular:guard": {
      "typeSeparator": "."
    },
    "@nx/angular:interceptor": {
      "typeSeparator": "."
    },
    "@nx/angular:module": {
      "typeSeparator": "."
    },
    "@nx/angular:pipe": {
      "typeSeparator": "."
    },
    "@nx/angular:resolver": {
      "typeSeparator": "."
    },
    "@schematics/angular:component": {
      "type": "component"
    },
    "@schematics/angular:directive": {
      "type": "directive"
    },
    "@schematics/angular:service": {
      "type": "service"
    },
    "@schematics/angular:guard": {
      "typeSeparator": "."
    },
    "@schematics/angular:interceptor": {
      "typeSeparator": "."
    },
    "@schematics/angular:module": {
      "typeSeparator": "."
    },
    "@schematics/angular:pipe": {
      "typeSeparator": "."
    },
    "@schematics/angular:resolver": {
      "typeSeparator": "."
    }
  }
}
```

If some of the generator defaults are already set, the migration will not override them:

##### Before

```json title="nx.json" {3-14}
{
  "generators": {
    "@nx/angular:component": {
      "type": "cmp"
    },
    "@schematics/angular:component": {
      "type": "cmp"
    },
    "@nx/angular:interceptor": {
      "typeSeparator": "-"
    },
    "@schematics/angular:interceptor": {
      "typeSeparator": "-"
    }
  }
}
```

##### After

```json title="nx.json" {3-14}
{
  "generators": {
    "@nx/angular:component": {
      "type": "cmp"
    },
    "@schematics/angular:component": {
      "type": "cmp"
    },
    "@nx/angular:interceptor": {
      "typeSeparator": "-"
    },
    "@schematics/angular:interceptor": {
      "typeSeparator": "-"
    },
    "@nx/angular:directive": {
      "type": "directive"
    },
    "@nx/angular:service": {
      "type": "service"
    },
    "@nx/angular:scam": {
      "type": "component"
    },
    "@nx/angular:scam-directive": {
      "type": "directive"
    },
    "@nx/angular:guard": {
      "typeSeparator": "."
    },
    "@nx/angular:module": {
      "typeSeparator": "."
    },
    "@nx/angular:pipe": {
      "typeSeparator": "."
    },
    "@nx/angular:resolver": {
      "typeSeparator": "."
    },
    "@schematics/angular:directive": {
      "type": "directive"
    },
    "@schematics/angular:service": {
      "type": "service"
    },
    "@schematics/angular:guard": {
      "typeSeparator": "."
    },
    "@schematics/angular:module": {
      "typeSeparator": "."
    },
    "@schematics/angular:pipe": {
      "typeSeparator": "."
    },
    "@schematics/angular:resolver": {
      "typeSeparator": "."
    }
  }
}
```



### `update-module-resolution`
**Version**: 21.2.0-beta.3

Update 'moduleResolution' to 'bundler' in TypeScript configurations. You can read more about this here: https://www.typescriptlang.org/tsconfig/#moduleResolution.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=20.0.0` |
#### Update `moduleResolution` to `bundler` in TypeScript configurations

Updates the TypeScript `moduleResolution` option to `'bundler'` for improved compatibility with modern package resolution algorithms used by bundlers like Webpack, Vite, and esbuild.

#### Examples

The migration will update TypeScript configuration files in your workspace to use the `'bundler'` module resolution strategy:

##### Before

```json title="apps/app1/tsconfig.app.json" {4}
{
  "compilerOptions": {
    "module": "es2020",
    "moduleResolution": "node"
  }
}
```

##### After

```json title="apps/app1/tsconfig.app.json" {4}
{
  "compilerOptions": {
    "module": "es2020",
    "moduleResolution": "bundler"
  }
}
```

If the `moduleResolution` is already set to `'bundler'` or the `module` is set to `'preserve'`, the migration will not modify the configuration:

##### Before

```json title="apps/app1/tsconfig.app.json" {3-4}
{
  "compilerOptions": {
    "module": "preserve",
    "moduleResolution": "node"
  }
}
```

##### After

```json title="apps/app1/tsconfig.app.json" {3-4}
{
  "compilerOptions": {
    "module": "preserve",
    "moduleResolution": "node"
  }
}
```



### 21.2.0-package-updates
**Version**: 21.2.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular-devkit/build-angular` | `~20.0.0` | Updated only
| `@angular-devkit/core` | `~20.0.0` | Updated only
| `@angular-devkit/schematics` | `~20.0.0` | Updated only
| `@angular/build` | `~20.0.0` | Updated only
| `@angular/pwa` | `~20.0.0` | Updated only
| `@angular/ssr` | `~20.0.0` | Updated only
| `@schematics/angular` | `~20.0.0` | Updated only
| `@angular-devkit/architect` | `~0.2000.0` | Updated only
| `@angular-devkit/build-webpack` | `~0.2000.0` | Updated only
| `@angular/core` | `~20.0.0` | Added if not installed
| `@angular/material` | `~20.0.0` | Updated only
| `@angular/cdk` | `~20.0.0` | Updated only
| `@angular/google-maps` | `~20.0.0` | Updated only
| `ng-packagr` | `~20.0.0` | Updated only


### 21.2.0-angular-eslint-package-updates
**Version**: 21.2.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `angular-eslint` | `^20.0.0` | Updated only


### 21.2.0-@angular-eslint-package-updates
**Version**: 21.2.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular-eslint/eslint-plugin` | `^20.0.0` | Updated only
| `@angular-eslint/eslint-plugin-template` | `^20.0.0` | Updated only
| `@angular-eslint/template-parser` | `^20.0.0` | Updated only
| `@angular-eslint/utils` | `^20.0.0` | Updated only
| `@angular-eslint/schematics` | `^20.0.0` | Updated only
| `@angular-eslint/test-utils` | `^20.0.0` | Updated only
| `@angular-eslint/builder` | `^20.0.0` | Updated only
| `@angular-eslint/bundled-angular-compiler` | `^20.0.0` | Updated only


### 21.2.0-angular-rspack-package-updates
**Version**: 21.2.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@nx/angular-rspack` | `^21.1.0` | Updated only


### 21.2.0-jest-package-updates
**Version**: 21.2.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `jest-preset-angular` | `~14.6.0` | Updated only



## 21.1.x

### 21.1.0-package-updates
**Version**: 21.1.0-beta.1


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@nx/angular-rspack` | `^21.0.1` | Updated only



## 21.0.x

### `set-continuous-option`
**Version**: 21.0.0-beta.3

Set the `continuous` option to `true` for continuous tasks.

#### Set `continuous` Option for Continuous Tasks

This migration sets the `continuous` option to `true` for tasks that are known to run continuously, and only if the option is not already explicitly set.

Specifically, it updates Angular targets using the following executors:

- `@angular-devkit/build-angular:dev-server`
- `@angular-devkit/build-angular:ssr-dev-server`
- `@nx/angular:dev-server`
- `@nx/angular:module-federation-dev-server`
- `@nx/angular:module-federation-dev-ssr`

#### Examples

##### Before

```json title="apps/app1/project.json"
{
  // ...
  "targets": {
    // ...
    "serve": {
      "executor": "@angular-devkit/build-angular:dev-server",
      "options": {
        "buildTarget": "my-app:build",
        "port": 4200
      }
    }
  }
}
```

##### After

```json title="apps/app1/project.json" {6}
{
  // ...
  "targets": {
    // ...
    "serve": {
      "continuous": true,
      "executor": "@angular-devkit/build-angular:dev-server",
      "options": {
        "buildTarget": "my-app:build",
        "port": 4200
      }
    }
  }
}
```

When a target is already explicitly configured with a `continuous` option, the migration will not modify it:

##### Before

```json title="apps/app1/project.json" {6}
{
  // ...
  "targets": {
    // ...
    "serve": {
      "continuous": false,
      "executor": "@nx/angular:dev-server",
      "options": {
        "buildTarget": "my-app:build",
        "port": 4200
      }
    }
  }
}
```

##### After

```json title="apps/app1/project.json" {6}
{
  // ...
  "targets": {
    // ...
    "serve": {
      "continuous": false,
      "executor": "@nx/angular:dev-server",
      "options": {
        "buildTarget": "my-app:build",
        "port": 4200
      }
    }
  }
}
```



### `change-data-persistence-operators-imports-to-ngrx-router-store-data-persistence`
**Version**: 21.0.0-beta.5

Change the data persistence operator imports to '@ngrx/router-store/data-persistence'.

#### Requires

| Name | Version |
|------|---------|
 `@ngrx/store` | `>=16.0.0` |
#### Change the Data Persistence Operator Imports from `@nx/angular` to `@ngrx/router-store/data-persistence`

The data persistence operators (`fetch`, `navigation`, `optimisticUpdate`, and `pessimisticUpdate`) have been deprecated for a while and are now removed from the `@nx/angular` package. This migration automatically updates your import statements to use the `@ngrx/router-store/data-persistence` module and adds `@ngrx/router-store` to your dependencies if needed.

#### Examples

If you import only data persistence operators from `@nx/angular`, the migration will update the import path to `@ngrx/router-store/data-persistence`.

##### Before

```ts title="apps/app1/src/app/users/users.effects.ts" {2}
import { Actions, createEffect, ofType } from '@ngrx/effects';
import { fetch } from '@nx/angular';

@Injectable()
export class UsersEffects {
  // ...
}
```

##### After

```ts title="apps/app1/src/app/users/users.effects.ts" {2}
import { Injectable } from '@angular/core';
import { fetch } from '@ngrx/router-store/data-persistence';

@Injectable()
export class UsersEffects {
  // ...
}
```

If you import multiple data persistence operators from `@nx/angular`, the migration will update the import path for all of them.

##### Before

```ts title="apps/app1/src/app/users/users.effects.ts" {2}
import { Injectable } from '@angular/core';
import { fetch, navigation } from '@nx/angular';

@Injectable()
export class UsersEffects {
  // ...
}
```

##### After

```ts title="apps/app1/src/app/users/users.effects.ts" {2}
import { Injectable } from '@angular/core';
import { fetch, navigation } from '@ngrx/router-store/data-persistence';

@Injectable()
export class UsersEffects {
  // ...
}
```

If your imports mix data persistence operators with other utilities from `@nx/angular`, the migration will split them into separate import statements.

##### Before

```ts title="apps/app1/src/app/users/users.effects.ts" {2}
import { Injectable } from '@angular/core';
import { fetch, someExtraUtility, navigation } from '@nx/angular';

@Injectable()
export class UsersEffects {
  // ...
}
```

##### After

```ts title="apps/app1/src/app/users/users.effects.ts" {2-3}
import { Injectable } from '@angular/core';
import { fetch, navigation } from '@ngrx/router-store/data-persistence';
import { someExtraUtility } from '@nx/angular';

@Injectable()
export class UsersEffects {
  // ...
}
```

If you don't already have `@ngrx/router-store` in your dependencies, the migration will add it to your package.json.

##### Before

```jsonc title="package.json"
{
  "dependencies": {
    "@nx/angular": "^21.0.0",
    "@ngrx/store": "^19.1.0",
    "@ngrx/effects": "^19.1.0",
    // ...
  },
}
```

##### After

```jsonc title="package.json" {6}
{
  "dependencies": {
    "@nx/angular": "^21.0.0",
    "@ngrx/store": "^19.1.0",
    "@ngrx/effects": "^19.1.0",
    "@ngrx/router-store": "^19.1.0",
    // ...
  },
}
```




## 20.8.x

### 20.8.1-package-updates
**Version**: 20.8.1-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@nx/angular-rspack` | `^20.7.0` | Updated only



## 20.5.x

### `update-angular-cli-version-19-2-0`
**Version**: 20.5.0-beta.5

Update the @angular/cli package version to ~19.2.0.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=19.2.0` |
#### Sample Code Changes

Update the `@angular/cli` package version in the `package.json` file at the workspace root to **~19.2.0**.

##### Before

```json title="package.json"
{
  "devDependencies": {
    "@angular/cli": "~19.1.0"
  }
}
```

##### After

```json title="package.json" {3}
{
  "devDependencies": {
    "@angular/cli": "~19.2.0"
  }
}
```



### 20.5.0-package-updates
**Version**: 20.5.0-beta.5


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular-devkit/build-angular` | `~19.2.0` | Updated only
| `@angular-devkit/core` | `~19.2.0` | Updated only
| `@angular-devkit/schematics` | `~19.2.0` | Updated only
| `@angular/build` | `~19.2.0` | Updated only
| `@angular/pwa` | `~19.2.0` | Updated only
| `@angular/ssr` | `~19.2.0` | Updated only
| `@schematics/angular` | `~19.2.0` | Updated only
| `@angular-devkit/architect` | `~0.1902.0` | Updated only
| `@angular-devkit/build-webpack` | `~0.1902.0` | Updated only
| `@angular/core` | `~19.2.0` | Added if not installed
| `@angular/material` | `~19.2.1` | Updated only
| `@angular/cdk` | `~19.2.1` | Updated only
| `@angular/google-maps` | `~19.2.1` | Updated only
| `ng-packagr` | `~19.2.0` | Updated only


### 20.5.0-angular-eslint-package-updates
**Version**: 20.5.0-rc.1


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `angular-eslint` | `^19.2.0` | Updated only
| `@angular-eslint/eslint-plugin` | `^19.2.0` | Updated only
| `@angular-eslint/eslint-plugin-template` | `^19.2.0` | Updated only
| `@angular-eslint/template-parser` | `^19.2.0` | Updated only
| `@angular-eslint/utils` | `^19.2.0` | Updated only
| `@angular-eslint/schematics` | `^19.2.0` | Updated only
| `@angular-eslint/test-utils` | `^19.2.0` | Updated only
| `@angular-eslint/builder` | `^19.2.0` | Updated only
| `@angular-eslint/bundled-angular-compiler` | `^19.2.0` | Updated only



## 20.4.x

### `update-angular-cli-version-19-1-0`
**Version**: 20.4.0-beta.1

Update the @angular/cli package version to ~19.1.0.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=19.1.0` |
#### Update `@angular/cli` to `~19.1.0`

Update the version of the Angular CLI if it is specified in `package.json`

#### Sample Code Changes

Update in `devDependencies`:

##### Before

```json title="package.json"
{
  "devDependencies": {
    "@angular/cli": "~13.3.0"
  }
}
```

##### After

```json title="package.json"
{
  "devDependencies": {
    "@angular/cli": "~19.1.0"
  }
}
```

Update in `dependencies`:

##### Before

```json title="package.json"
{
  "dependencies": {
    "@angular/cli": "~13.3.0"
  }
}
```

##### After

```json title="package.json"
{
  "dependencies": {
    "@angular/cli": "~19.1.0"
  }
}
```



### 20.4.0-package-updates
**Version**: 20.4.0-beta.1


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular-devkit/build-angular` | `~19.1.0` | Updated only
| `@angular-devkit/core` | `~19.1.0` | Updated only
| `@angular-devkit/schematics` | `~19.1.0` | Updated only
| `@angular/build` | `~19.1.0` | Updated only
| `@angular/pwa` | `~19.1.0` | Updated only
| `@angular/ssr` | `~19.1.0` | Updated only
| `@schematics/angular` | `~19.1.0` | Updated only
| `@angular-devkit/architect` | `~0.1901.0` | Updated only
| `@angular-devkit/build-webpack` | `~0.1901.0` | Updated only
| `@angular/core` | `~19.1.0` | Added if not installed
| `@angular/material` | `~19.1.0` | Updated only
| `@angular/cdk` | `~19.1.0` | Updated only
| `@angular/google-maps` | `~19.1.0` | Updated only
| `ng-packagr` | `~19.1.0` | Updated only



## 20.3.x

### `ensure-nx-module-federation-package`
**Version**: 20.3.0-beta.2

If workspace includes Module Federation projects, ensure the new @nx/module-federation package is installed.

#### Ensure the @nx/module-federation Package is Installed

If workspace includes Module Federation projects, ensure the new `@nx/module-federation` package is installed.

#### Sample Code Changes

##### Before

```json title="package.json"
{
  "dependencies": {}
}
```

##### After

```json title="package.json"
{
  "dependencies": {
    "@nx/module-federation": "20.3.0"
  }
}
```



### 20.2.3-ngrx-package-updates
**Version**: 20.3.0-beta.2


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@ngrx/store` | `^19.0.0` | Updated only



## 20.2.x

### `update-20-2-0-update-module-federation-config-import`
**Version**: 20.2.0-beta.2

Update the ModuleFederationConfig import use @nx/module-federation.

#### Migrate Module Federation Imports to New Package

Update the ModuleFederationConfig imports to use @nx/module-federation.

#### Sample Code Changes

Update import paths for ModuleFederationConfig.

##### Before

```js title="apps/shell/webpack.config.js"
import { ModuleFederationConfig } from '@nx/webpack';
```

##### After

```js title="apps/shell/webpack.config.js"
import { ModuleFederationConfig } from '@nx/module-federation';
```



### `update-20-2-0-update-with-module-federation-import`
**Version**: 20.2.0-beta.2

Update the withModuleFederation import use @nx/module-federation/angular.

#### Migrate withModuleFederation Import to New Package

Update the withModuleFederation import to use @nx/module-federation/webpack.

#### Sample Code Changes

Update import paths for `withModuleFederation` and `withModuleFederationForSSR`.

##### Before

```ts title="apps/shell/webpack.config.ts"
import {
  withModuleFederation,
  withModuleFederationForSSR,
} from '@nx/angular/module-federation';
```

##### After

```ts title="apps/shell/webpack.config.ts"
import {
  withModuleFederation,
  withModuleFederationForSSR,
} from '@nx/module-federation/angular';
```



### `update-angular-cli-version-19-0-0`
**Version**: 20.2.0-beta.5

Update the @angular/cli package version to ~19.0.0.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=19.0.0` |
#### Update `@angular/cli` to `~19.0.0`

Update the version of the Angular CLI if it is specified in `package.json`

#### Sample Code Changes

Update in `devDependencies`:

##### Before

```json title="package.json"
{
  "devDependencies": {
    "@angular/cli": "~13.3.0"
  }
}
```

##### After

```json title="package.json"
{
  "devDependencies": {
    "@angular/cli": "~19.0.0"
  }
}
```

Update in `dependencies`:

##### Before

```json title="package.json"
{
  "dependencies": {
    "@angular/cli": "~13.3.0"
  }
}
```

##### After

```json title="package.json"
{
  "dependencies": {
    "@angular/cli": "~19.0.0"
  }
}
```



### `add-localize-polyfill-to-targets`
**Version**: 20.2.0-beta.5

Add the '@angular/localize/init' polyfill to the 'polyfills' option of targets using esbuild-based executors.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=19.0.0` |
#### Add Localize Polyfill to Targets

Add the '@angular/localize/init' polyfill to the 'polyfills' option of targets using esbuild-based executors.

#### Sample Code Changes

Add the `@angular/localize/init` polyfill to any of these executors:

- `@angular/build:application`
- `@angular-devkit/build-angular:application`
- `@nx/angular:application`
- `@angular-devkit/build-angular:browser-esbuild`
- `@nx/angular:browser-esbuild`

##### Before

```json title="apps/app1/project.json"
{
  "targets": {
    "build": {
      "executor": "@angular/build:application",
      "options": {
        "localize": true
      }
    }
  }
}
```

##### After

```json title="apps/app1/project.json"
{
  "targets": {
    "build": {
      "executor": "@angular/build:application",
      "options": {
        "localize": true,
        "polyfills": ["@angular/localize/init"]
      }
    }
  }
}
```



### `update-angular-ssr-imports-to-use-node-entry-point`
**Version**: 20.2.0-beta.5

Update '@angular/ssr' import paths to use the new '/node' entry point when 'CommonEngine' is detected.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=19.0.0` |
#### Update Angular SSR Imports to Use Node Entry Point

Update '@angular/ssr' import paths to use the new '/node' entry point when 'CommonEngine' is detected.

#### Sample Code Changes

Update import paths for SSR CommonEngine properties to use `@angular/ssr/node`.

##### Before

```ts title="apps/app1/server.ts"
import { CommonEngine } from '@angular/ssr';
import type {
  CommonEngineOptions,
  CommonEngineRenderOptions,
} from '@angular/ssr';
```

##### After

```ts title="apps/app1/server.ts"
import { CommonEngine } from '@angular/ssr/node';
import type {
  CommonEngineOptions,
  CommonEngineRenderOptions,
} from '@angular/ssr/node';
```



### `disable-angular-eslint-prefer-standalone`
**Version**: 20.2.0-beta.6

Disable the Angular ESLint prefer-standalone rule if not set.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=19.0.0` |
#### Disable Angular ESLint Prefer Standalone

Disable the Angular ESLint prefer-standalone rule if not set.

#### Sample Code Changes

Update import paths for `withModuleFederation` and `withModuleFederationForSSR`.

##### Before

```json title="apps/app1/.eslintrc.json"
{
  "overrides": [
    {
      "files": ["*.html"],
      "rules": {
        "some-rule-for-html": "error"
      }
    }
  ]
}
```

##### After

```json title="apps/app1/.eslintrc.json"
{
  "overrides": [
    {
      "files": ["*.html"],
      "rules": {
        "some-rule-for-html": "error"
      }
    },
    {
      "files": ["*.ts"],
      "rules": {
        "@angular-eslint/prefer-standalone": "off"
      }
    }
  ]
}
```

import {
addProjectConfiguration,
writeJson,
type ProjectConfiguration,
type ProjectGraph,
type Tree,
} from '@nx/devkit';
import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
import migration from './disable-angular-eslint-prefer-standalone';

let projectGraph: ProjectGraph;
jest.mock('@nx/devkit', () => ({
...jest.requireActual('@nx/devkit'),
createProjectGraphAsync: () => Promise.resolve(projectGraph),
}));

describe('disable-angular-eslint-prefer-standalone', () => {
let tree: Tree;

beforeEach(() => {
tree = createTreeWithEmptyWorkspace();

    const projectConfig: ProjectConfiguration = {
      name: 'app1',
      root: 'apps/app1',
    };
    projectGraph = {
      dependencies: {
        app1: [
          {
            source: 'app1',
            target: 'npm:@angular/core',
            type: 'static',
          },
        ],
      },
      nodes: {
        app1: {
          data: projectConfig,
          name: 'app1',
          type: 'app',
        },
      },
    };
    addProjectConfiguration(tree, projectConfig.name, projectConfig);

});

describe('.eslintrc.json', () => {
it('should not disable @angular-eslint/prefer-standalone when it is set', async () => {
writeJson(tree, 'apps/app1/.eslintrc.json', {
overrides: [
{
files: ['*.ts'],
rules: { '@angular-eslint/prefer-standalone': ['error'] },
},
],
});

      await migration(tree);

      expect(tree.read('apps/app1/.eslintrc.json', 'utf8'))
        .toMatchInlineSnapshot(`
        "{
          "overrides": [
            {
              "files": ["*.ts"],
              "rules": {
                "@angular-eslint/prefer-standalone": ["error"]
              }
            }
          ]
        }
        "
      `);
    });

    it('should not disable @angular-eslint/prefer-standalone when there are multiple overrides for angular eslint and the rule is set in one of them', async () => {
      writeJson(tree, 'apps/app1/.eslintrc.json', {
        overrides: [
          {
            files: ['*.ts'],
            rules: {
              '@angular-eslint/directive-selector': [
                'error',
                { type: 'attribute', prefix: 'app', style: 'camelCase' },
              ],
            },
          },
          {
            files: ['*.ts'],
            rules: { '@angular-eslint/prefer-standalone': ['error'] },
          },
        ],
      });

      await migration(tree);

      expect(tree.read('apps/app1/.eslintrc.json', 'utf8'))
        .toMatchInlineSnapshot(`
        "{
          "overrides": [
            {
              "files": ["*.ts"],
              "rules": {
                "@angular-eslint/directive-selector": [
                  "error",
                  {
                    "type": "attribute",
                    "prefix": "app",
                    "style": "camelCase"
                  }
                ]
              }
            },
            {
              "files": ["*.ts"],
              "rules": {
                "@angular-eslint/prefer-standalone": ["error"]
              }
            }
          ]
        }
        "
      `);
    });

    it('should disable @angular-eslint/prefer-standalone in an existing override for angular eslint', async () => {
      writeJson(tree, 'apps/app1/.eslintrc.json', {
        overrides: [
          {
            files: ['*.ts'],
            rules: { 'no-unused-vars': 'error' },
          },
          {
            files: ['*.ts'],
            rules: {
              '@angular-eslint/directive-selector': [
                'error',
                { type: 'attribute', prefix: 'app', style: 'camelCase' },
              ],
            },
          },
        ],
      });

      await migration(tree);

      expect(tree.read('apps/app1/.eslintrc.json', 'utf8'))
        .toMatchInlineSnapshot(`
        "{
          "overrides": [
            {
              "files": ["*.ts"],
              "rules": {
                "no-unused-vars": "error"
              }
            },
            {
              "files": ["*.ts"],
              "rules": {
                "@angular-eslint/directive-selector": [
                  "error",
                  {
                    "type": "attribute",
                    "prefix": "app",
                    "style": "camelCase"
                  }
                ],
                "@angular-eslint/prefer-standalone": "off"
              }
            }
          ]
        }
        "
      `);
    });

    it('should disable @angular-eslint/prefer-standalone in an existing override for ts files', async () => {
      writeJson(tree, 'apps/app1/.eslintrc.json', {
        overrides: [
          {
            files: ['*.ts'],
            rules: { 'no-unused-vars': 'error' },
          },
        ],
      });

      await migration(tree);

      expect(tree.read('apps/app1/.eslintrc.json', 'utf8'))
        .toMatchInlineSnapshot(`
        "{
          "overrides": [
            {
              "files": ["*.ts"],
              "rules": {
                "no-unused-vars": "error",
                "@angular-eslint/prefer-standalone": "off"
              }
            }
          ]
        }
        "
      `);
    });

    it('should disable @angular-eslint/prefer-standalone in a new override', async () => {
      writeJson(tree, 'apps/app1/.eslintrc.json', {
        overrides: [
          {
            files: ['*.html'],
            rules: { 'some-rule-for-html': 'error' },
          },
        ],
      });

      await migration(tree);

      expect(tree.read('apps/app1/.eslintrc.json', 'utf8'))
        .toMatchInlineSnapshot(`
        "{
          "overrides": [
            {
              "files": ["*.html"],
              "rules": {
                "some-rule-for-html": "error"
              }
            },
            {
              "files": ["*.ts"],
              "rules": {
                "@angular-eslint/prefer-standalone": "off"
              }
            }
          ]
        }
        "
      `);
    });

});

describe('flat config', () => {
it('should not disable @angular-eslint/prefer-standalone when it is set', async () => {
tree.write('eslint.config.js', 'module.exports = [];');
tree.write(
'apps/app1/eslint.config.js',
`module.exports = [
          {
            files: ['*.ts'],
            rules: { '@angular-eslint/prefer-standalone': ['error'] },
          },
        ];
        `
);

      await migration(tree);

      expect(tree.read('apps/app1/eslint.config.js', 'utf8'))
        .toMatchInlineSnapshot(`
        "module.exports = [
          {
            files: ['*.ts'],
            rules: { '@angular-eslint/prefer-standalone': ['error'] },
          },
        ];
        "
      `);
    });

    it('should not disable @angular-eslint/prefer-standalone when there are multiple overrides for angular eslint and the rule is set in one of them', async () => {
      tree.write('eslint.config.js', 'module.exports = [];');
      tree.write(
        'apps/app1/eslint.config.js',
        `module.exports = [
          {
            files: ['*.ts'],
            rules: {
              '@angular-eslint/directive-selector': [
                'error',
                { type: 'attribute', prefix: 'app', style: 'camelCase' },
              ],
            },
          },
          {
            files: ['*.ts'],
            rules: { '@angular-eslint/prefer-standalone': ['error'] },
          },
        ];
        `
      );

      await migration(tree);

      expect(tree.read('apps/app1/eslint.config.js', 'utf8'))
        .toMatchInlineSnapshot(`
        "module.exports = [
          {
            files: ['*.ts'],
            rules: {
              '@angular-eslint/directive-selector': [
                'error',
                { type: 'attribute', prefix: 'app', style: 'camelCase' },
              ],
            },
          },
          {
            files: ['*.ts'],
            rules: { '@angular-eslint/prefer-standalone': ['error'] },
          },
        ];
        "
      `);
    });

    it('should disable @angular-eslint/prefer-standalone in an existing override for angular eslint', async () => {
      tree.write('eslint.config.js', 'module.exports = [];');
      tree.write(
        'apps/app1/eslint.config.js',
        `module.exports = [
          {
            files: ['*.ts'],
            rules: { 'no-unused-vars': 'error' },
          },
          {
            files: ['*.ts'],
            rules: {
              '@angular-eslint/directive-selector': [
                'error',
                { type: 'attribute', prefix: 'app', style: 'camelCase' },
              ],
            },
          },
        ];
        `
      );

      await migration(tree);

      expect(tree.read('apps/app1/eslint.config.js', 'utf8'))
        .toMatchInlineSnapshot(`
        "module.exports = [
          {
            files: ['*.ts'],
            rules: { 'no-unused-vars': 'error' },
          },
          {
            files: ['**/*.ts'],
            rules: {
              '@angular-eslint/directive-selector': [
                'error',
                {
                  type: 'attribute',
                  prefix: 'app',
                  style: 'camelCase',
                },
              ],
              '@angular-eslint/prefer-standalone': 'off',
            },
          },
        ];
        "
      `);
    });

    it('should disable @angular-eslint/prefer-standalone in an existing override for ts files', async () => {
      tree.write('eslint.config.js', 'module.exports = [];');
      tree.write(
        'apps/app1/eslint.config.js',
        `module.exports = [
          {
            files: ['*.ts'],
            rules: { 'no-unused-vars': 'error' },
          },
        ];
        `
      );

      await migration(tree);

      expect(tree.read('apps/app1/eslint.config.js', 'utf8'))
        .toMatchInlineSnapshot(`
        "module.exports = [
          {
            files: ['**/*.ts'],
            rules: {
              'no-unused-vars': 'error',
              '@angular-eslint/prefer-standalone': 'off',
            },
          },
        ];
        "
      `);
    });

    it('should disable @angular-eslint/prefer-standalone in a new override', async () => {
      tree.write('eslint.config.js', 'module.exports = [];');
      tree.write(
        'apps/app1/eslint.config.js',
        `module.exports = [
          {
            files: ['*.html'],
            rules: { 'some-rule-for-html': 'error' },
          },
        ];
        `
      );

      await migration(tree);

      expect(tree.read('apps/app1/eslint.config.js', 'utf8'))
        .toMatchInlineSnapshot(`
        "module.exports = [
          {
            files: ['*.html'],
            rules: { 'some-rule-for-html': 'error' },
          },
          {
            files: ['**/*.ts'],
            rules: {
              '@angular-eslint/prefer-standalone': 'off',
            },
          },
        ];
        "
      `);
    });

});
});



### `remove-angular-eslint-rules`
**Version**: 20.2.0-beta.8

Remove Angular ESLint rules that were removed in v19.0.0.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=19.0.0` |
#### Remove Angular ESLint Rules

Remove Angular ESLint rules that were removed in v19.0.0.

#### Sample Code Changes

Removes `@angular-eslint/no-host-metadata-property`, `@angular-eslint/sort-ngmodule-metadata-arrays` and `@angular-eslint/prefer-standalone-component` from any ESLint config file. Files to be searched include `.eslintrc.json`, `.eslintrc.base.json`, `.eslint.config.js` and `.eslint.config.base.js`.

##### Before

```json title="apps/app1/.eslintrc.json"
{
  "overrides": [
    {
      "files": ["*.ts"],
      "rules": {
        "@angular-eslint/no-host-metadata-property": ["error"],
        "@angular-eslint/sort-ngmodule-metadata-arrays": ["error"],
        "@angular-eslint/prefer-standalone-component": ["error"]
      }
    }
  ]
}
```

##### After

```json title="apps/app1/.eslintrc.json"
{
  "overrides": [
    {
      "files": ["*.ts"],
      "rules": {}
    }
  ]
}
```



### `remove-tailwind-config-from-ng-packagr-executors`
**Version**: 20.2.0-beta.8

Remove the deprecated 'tailwindConfig' option from ng-packagr executors. Tailwind CSS configurations located at the project or workspace root will be picked up automatically.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=19.0.0` |
#### Remove tailwindConfig from ng-packagr Executors

Remove the deprecated 'tailwindConfig' option from ng-packagr executors. Tailwind CSS configurations located at the project or workspace root will be picked up automatically.

#### Sample Code Changes

Remove `tailwindConfig` from the `@nx/angular:ng-packagr-lite` or `@nx/angular:package` executor options in project configuration.

##### Before

```json title="libs/my-lib/project.json"
{
  "targets": {
    "build": {
      "executor": "@nx/angular:ng-packagr-lite",
      "options": {
        "project": "libs/lib1/ng-package.json",
        "tailwindConfig": "libs/lib1/tailwind.config.js"
      }
    }
  }
}
```

##### After

```json title="libs/my-lib/project.json"
{
  "targets": {
    "build": {
      "executor": "@nx/angular:ng-packagr-lite",
      "options": {
        "project": "libs/lib1/ng-package.json"
      }
    }
  }
}
```

Remove `tailwindConfig` from the `@nx/angular:ng-packagr-lite` or `@nx/angular:package` executor target defaults in `nx.json`.

##### Before

```json title="nx.json"
{
  "targetDefaults": {
    "@nx/angular:ng-packagr-lite": {
      "options": {
        "project": "{projectRoot}/ng-package.json",
        "tailwindConfig": "{projectRoot}/tailwind.config.js"
      }
    }
  }
}
```

##### After

```json title="nx.json"
{
  "targetDefaults": {
    "@nx/angular:ng-packagr-lite": {
      "options": {
        "project": "{projectRoot}/ng-package.json"
      }
    }
  }
}
```



### 20.2.0-module-federation-package-updates
**Version**: 20.2.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@module-federation/enhanced` | `0.7.6` | Updated only
| `@module-federation/runtime` | `0.7.6` | Updated only
| `@module-federation/sdk` | `0.7.6` | Updated only
| `@module-federation/node` | `2.6.11` | Updated only


### 20.2.0-package-updates
**Version**: 20.2.0-beta.5


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular-devkit/build-angular` | `~19.0.0` | Updated only
| `@angular-devkit/core` | `~19.0.0` | Updated only
| `@angular-devkit/schematics` | `~19.0.0` | Updated only
| `@angular/build` | `~19.0.0` | Updated only
| `@angular/pwa` | `~19.0.0` | Updated only
| `@angular/ssr` | `~19.0.0` | Updated only
| `@schematics/angular` | `~19.0.0` | Updated only
| `@angular-devkit/architect` | `~0.1900.0` | Updated only
| `@angular-devkit/build-webpack` | `~0.1900.0` | Updated only
| `@angular/core` | `~19.0.0` | Added if not installed
| `@angular/material` | `~19.0.0` | Updated only
| `@angular/cdk` | `~19.0.0` | Updated only
| `@angular/google-maps` | `~19.0.0` | Updated only
| `ng-packagr` | `~19.0.0` | Updated only
| `zone.js` | `~0.15.0` | Updated only


### 20.2.0-jest-package-updates
**Version**: 20.2.0-beta.5


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `jest-preset-angular` | `~14.4.0` | Updated only


### 20.2.0-angular-eslint-package-updates
**Version**: 20.2.0-beta.5


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `angular-eslint` | `^19.0.0` | Updated only
| `@angular-eslint/eslint-plugin` | `^19.0.0` | Updated only
| `@angular-eslint/eslint-plugin-template` | `^19.0.0` | Updated only
| `@angular-eslint/template-parser` | `^19.0.0` | Updated only
| `@angular-eslint/utils` | `^19.0.0` | Updated only
| `@angular-eslint/schematics` | `^19.0.0` | Updated only
| `@angular-eslint/test-utils` | `^19.0.0` | Updated only
| `@angular-eslint/builder` | `^19.0.0` | Updated only
| `@angular-eslint/bundled-angular-compiler` | `^19.0.0` | Updated only


### 20.2.0-analog-package-updates
**Version**: 20.2.0-beta.7


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@analogjs/vitest-angular` | `~1.10.0` | Updated only
| `@analogjs/vite-plugin-angular` | `~1.10.0` | Updated only


### 20.2.2-angular-eslint-package-updates
**Version**: 20.2.2-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `angular-eslint` | `^19.0.2` | Updated only
| `@angular-eslint/eslint-plugin` | `^19.0.2` | Updated only
| `@angular-eslint/eslint-plugin-template` | `^19.0.2` | Updated only
| `@angular-eslint/template-parser` | `^19.0.2` | Updated only
| `@angular-eslint/utils` | `^19.0.2` | Updated only
| `@angular-eslint/schematics` | `^19.0.2` | Updated only
| `@angular-eslint/test-utils` | `^19.0.2` | Updated only
| `@angular-eslint/builder` | `^19.0.2` | Updated only
| `@angular-eslint/bundled-angular-compiler` | `^19.0.2` | Updated only



## 19.7.x

### 19.7.0-package-updates
**Version**: 19.7.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@module-federation/enhanced` | `~0.6.0` | Updated only
| `@module-federation/node` | `~2.5.0` | Updated only



## 19.6.x

### `update-19-6-0`
**Version**: 19.6.0-beta.4

Ensure Module Federation DTS is turned off by default.


### `update-angular-cli-version-18-2-0`
**Version**: 19.6.0-beta.7

Update the @angular/cli package version to ~18.2.0.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=18.2.0` |

### `update-19-6-1-ensure-module-federation-target-defaults`
**Version**: 19.6.1-beta.0

Ensure Target Defaults are set correctly for Module Federation.


### 19.6.0-package-updates
**Version**: 19.6.0-beta.7


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular-devkit/build-angular` | `~18.2.0` | Updated only
| `@angular-devkit/core` | `~18.2.0` | Updated only
| `@angular-devkit/schematics` | `~18.2.0` | Updated only
| `@angular/build` | `~18.2.0` | Updated only
| `@angular/pwa` | `~18.2.0` | Updated only
| `@angular/ssr` | `~18.2.0` | Updated only
| `@schematics/angular` | `~18.2.0` | Updated only
| `@angular-devkit/architect` | `~0.1802.0` | Updated only
| `@angular-devkit/build-webpack` | `~0.1802.0` | Updated only
| `@angular/core` | `~18.2.0` | Added if not installed
| `@angular/material` | `~18.2.0` | Updated only
| `@angular/cdk` | `~18.2.0` | Updated only
| `ng-packagr` | `~18.2.0` | Updated only
| `zone.js` | `~0.14.10` | Updated only


### 19.6.1-ngrx-package-updates
**Version**: 19.6.1-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@ngrx/store` | `^18.0.2` | Updated only



## 19.5.x

### `update-angular-cli-version-18-1-0`
**Version**: 19.5.0-beta.1

Update the @angular/cli package version to ~18.1.0.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=18.1.0` |

### 19.5.0-module-federation-package-updates
**Version**: 19.5.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@module-federation/node` | `^2.3.0` | Updated only


### 19.5.0-package-updates
**Version**: 19.5.0-beta.1


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular-devkit/build-angular` | `~18.1.0` | Updated only
| `@angular-devkit/core` | `~18.1.0` | Updated only
| `@angular-devkit/schematics` | `~18.1.0` | Updated only
| `@angular/build` | `~18.1.0` | Updated only
| `@angular/pwa` | `~18.1.0` | Updated only
| `@angular/ssr` | `~18.1.0` | Updated only
| `@schematics/angular` | `~18.1.0` | Updated only
| `@angular-devkit/architect` | `~0.1801.0` | Updated only
| `@angular-devkit/build-webpack` | `~0.1801.0` | Updated only
| `@angular/core` | `~18.1.0` | Added if not installed
| `@angular/material` | `~18.1.0` | Updated only
| `@angular/cdk` | `~18.1.0` | Updated only
| `ng-packagr` | `~18.1.0` | Updated only


### 19.5.4-ngrx-package-updates
**Version**: 19.5.4-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@ngrx/store` | `^18.0.1` | Updated only
| `@ngrx/operators` | `^18.0.1` | Updated only



## 19.4.x

### 19.4.0-ngrx-package-updates
**Version**: 19.4.0-beta.1


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@ngrx/store` | `^18.0.0` | Updated only



## 19.2.x

### `add-typescript-eslint-utils`
**Version**: 19.2.1-beta.0

Installs the '@typescript-eslint/utils' package when having installed '@angular-eslint/eslint-plugin' or '@angular-eslint/eslint-plugin-template' with version >=18.0.0.

#### Requires

| Name | Version |
|------|---------|
 `@angular-eslint/eslint-plugin` | `>=18.0.0` |


## 19.1.x

### `update-angular-cli-version-18-0-0`
**Version**: 19.1.0-beta.2

Update the @angular/cli package version to ~18.0.0.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=18.0.0` |

### 19.1.0-package-updates
**Version**: 19.1.0-beta.2


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular-devkit/build-angular` | `~18.0.0` | Updated only
| `@angular-devkit/core` | `~18.0.0` | Updated only
| `@angular-devkit/schematics` | `~18.0.0` | Updated only
| `@angular/pwa` | `~18.0.0` | Updated only
| `@angular/ssr` | `~18.0.0` | Updated only
| `@schematics/angular` | `~18.0.0` | Updated only
| `@angular-devkit/architect` | `~0.1800.0` | Updated only
| `@angular-devkit/build-webpack` | `~0.1800.0` | Updated only
| `@angular/core` | `~18.0.0` | Added if not installed
| `@angular/material` | `~18.0.0` | Updated only
| `@angular/cdk` | `~18.0.0` | Updated only
| `ng-packagr` | `~18.0.0` | Updated only


### 19.1.0-jest-package-updates
**Version**: 19.1.0-beta.2


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `jest-preset-angular` | `~14.1.0` | Updated only


### 19.1.2-package-updates
**Version**: 19.1.2-beta.1


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular-eslint/eslint-plugin` | `^18.0.1` | Updated only
| `@angular-eslint/eslint-plugin-template` | `^18.0.1` | Updated only
| `@angular-eslint/template-parser` | `^18.0.1` | Updated only
| `@angular-eslint/utils` | `^18.0.1` | Updated only
| `@angular-eslint/schematics` | `^18.0.1` | Updated only
| `@angular-eslint/test-utils` | `^18.0.1` | Updated only
| `@angular-eslint/builder` | `^18.0.1` | Updated only
| `@angular-eslint/bundled-angular-compiler` | `^18.0.1` | Updated only



## 18.2.x

### `update-angular-cli-version-17-3-0`
**Version**: 18.2.0-beta.0

Update the @angular/cli package version to ~17.3.0.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=17.3.0` |

### 18.2.0-package-updates
**Version**: 18.2.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular-devkit/build-angular` | `~17.3.0` | Updated only
| `@angular-devkit/core` | `~17.3.0` | Updated only
| `@angular-devkit/schematics` | `~17.3.0` | Updated only
| `@angular/pwa` | `~17.3.0` | Updated only
| `@angular/ssr` | `~17.3.0` | Updated only
| `@schematics/angular` | `~17.3.0` | Updated only
| `@angular-devkit/architect` | `~0.1703.0` | Updated only
| `@angular-devkit/build-webpack` | `~0.1703.0` | Updated only
| `@angular/core` | `~17.3.0` | Added if not installed
| `@angular/material` | `~17.3.0` | Updated only
| `@angular/cdk` | `~17.3.0` | Updated only
| `ng-packagr` | `~17.3.0` | Updated only


### 18.2.0-angular-eslint-package-updates
**Version**: 18.2.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular-eslint/eslint-plugin` | `~17.3.0` | Updated only
| `@angular-eslint/eslint-plugin-template` | `~17.3.0` | Updated only
| `@angular-eslint/template-parser` | `~17.3.0` | Updated only



## 18.1.x

### `update-angular-cli-version-17-2-0`
**Version**: 18.1.0-beta.1

Update the @angular/cli package version to ~17.2.0.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=17.2.0` |

### `fix-target-defaults-for-webpack-browser`
**Version**: 18.1.1-beta.0

Ensure targetDefaults inputs for task hashing when '@nx/angular:webpack-browser' is used are correct for Module Federation.


### 18.1.0-jest-package-updates
**Version**: 18.1.0-beta.2


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `jest-preset-angular` | `~14.0.3` | Updated only


### 18.1.0-package-updates
**Version**: 18.1.0-beta.1


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular-devkit/build-angular` | `~17.2.0` | Updated only
| `@angular-devkit/core` | `~17.2.0` | Updated only
| `@angular-devkit/schematics` | `~17.2.0` | Updated only
| `@angular/pwa` | `~17.2.0` | Updated only
| `@angular/ssr` | `~17.2.0` | Updated only
| `@schematics/angular` | `~17.2.0` | Updated only
| `@angular-devkit/architect` | `~0.1702.0` | Updated only
| `@angular-devkit/build-webpack` | `~0.1702.0` | Updated only
| `@angular/core` | `~17.2.0` | Added if not installed
| `@angular/material` | `~17.2.0` | Updated only
| `@angular/cdk` | `~17.2.0` | Updated only
| `ng-packagr` | `~17.2.0` | Updated only



## 18.0.x

### `add-module-federation-env-var-to-target-defaults`
**Version**: 18.0.0-beta.0

Add NX_MF_DEV_SERVER_STATIC_REMOTES to inputs for task hashing when '@nx/angular:webpack-browser' is used for Module Federation.



## 17.3.x

### `update-angular-cli-version-17-1-0`
**Version**: 17.3.0-beta.10

Update the @angular/cli package version to ~17.1.0.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=17.1.0` |

### `add-browser-sync-dependency`
**Version**: 17.3.0-beta.10

Add 'browser-sync' as dev dependency when '@angular-devkit/build-angular:ssr-dev-server' or '@nx/angular:module-federation-dev-ssr' is used.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=17.1.0` |

### `add-autoprefixer-dependency`
**Version**: 17.3.0-beta.10

Add 'autoprefixer' as dev dependency when '@nx/angular:ng-packagr-lite' or '@nx/angular:package` is used.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=17.1.0` |

### 17.3.0-types-node-package-updates
**Version**: 17.3.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@types/node` | `^18.16.9` | Updated only


### 17.3.0-package-updates
**Version**: 17.3.0-beta.10


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular-devkit/build-angular` | `~17.1.0` | Updated only
| `@angular-devkit/core` | `~17.1.0` | Updated only
| `@angular-devkit/schematics` | `~17.1.0` | Updated only
| `@angular/pwa` | `~17.1.0` | Updated only
| `@angular/ssr` | `~17.1.0` | Updated only
| `@schematics/angular` | `~17.1.0` | Updated only
| `@angular-devkit/architect` | `~0.1701.0` | Updated only
| `@angular-devkit/build-webpack` | `~0.1701.0` | Updated only
| `@angular/core` | `~17.1.0` | Added if not installed
| `@angular/material` | `~17.1.0` | Updated only
| `@angular/cdk` | `~17.1.0` | Updated only
| `ng-packagr` | `~17.1.0` | Updated only
| `zone.js` | `~0.14.3` | Updated only



## 17.2.x

### `rename-webpack-dev-server-executor`
**Version**: 17.2.0-beta.2

Rename '@nx/angular:webpack-dev-server' executor to '@nx/angular:dev-server'


### 17.2.0-ngrx-package-updates
**Version**: 17.2.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@ngrx/store` | `~17.0.0` | Updated only



## 17.1.x

### `update-angular-cli-version-17-0-0`
**Version**: 17.1.0-beta.5

Update the @angular/cli package version to ~17.0.0.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=17.0.0` |

### `rename-browser-target-to-build-target`
**Version**: 17.1.0-beta.5

Rename 'browserTarget' to 'buildTarget'.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=17.0.0` |

### `replace-nguniversal-builders`
**Version**: 17.1.0-beta.5

Replace usages of '@nguniversal/builders' with '@angular-devkit/build-angular'.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=17.0.0` |

### `replace-nguniversal-engines`
**Version**: 17.1.0-beta.5

Replace usages of '@nguniversal/' packages with '@angular/ssr'.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=17.0.0` |

### `update-zone-js-deep-import`
**Version**: 17.1.0-beta.5

Replace the deep imports from 'zone.js/dist/zone' and 'zone.js/dist/zone-testing' with 'zone.js' and 'zone.js/testing'.

#### Requires

| Name | Version |
|------|---------|
 `@angular/core` | `>=17.0.0` |

### 17.1.0-package-updates
**Version**: 17.1.0-beta.5


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular-devkit/architect` | `~0.1700.0` | Updated only
| `@angular-devkit/build-angular` | `~17.0.0` | Updated only
| `@angular-devkit/build-webpack` | `~0.1700.0` | Updated only
| `@angular-devkit/core` | `~17.0.0` | Updated only
| `@angular-devkit/schematics` | `~17.0.0` | Updated only
| `@angular/pwa` | `~17.0.0` | Updated only
| `@angular/core` | `~17.0.0` | Added if not installed
| `@angular/material` | `~17.0.0` | Updated only
| `@angular/cdk` | `~17.0.0` | Updated only
| `@schematics/angular` | `~17.0.0` | Updated only
| `ng-packagr` | `~17.0.0` | Updated only
| `zone.js` | `~0.14.0` | Updated only


### 17.1.0-jest-package-updates
**Version**: 17.1.0-beta.5


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `jest-preset-angular` | `~13.1.3` | Updated only


### 17.1.0-angular-eslint-package-updates
**Version**: 17.1.0-beta.5


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@angular-eslint/eslint-plugin` | `~17.0.0` | Updated only
| `@angular-eslint/eslint-plugin-template` | `~17.0.0` | Updated only
| `@angular-eslint/template-parser` | `~17.0.0` | Updated only


### 17.1.3-jest-package-updates
**Version**: 17.1.3-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `jest-preset-angular` | `~13.1.4` | Updated only

---
<!-- source: https://nx.dev/docs/technologies/build-tools.md -->
## Build Tools

{% index_page_cards path="technologies/build-tools" /%}

---
<!-- source: https://nx.dev/docs/technologies/build-tools/docker.md -->
## Docker

{% index_page_cards path="technologies/build-tools/docker" /%}

---
<!-- source: https://nx.dev/docs/technologies/build-tools/docker/introduction.md -->
## Docker Plugin for Nx

The Nx Plugin for Docker contains executors and utilities for building and publishing docker images within an Nx workspace.
Using the `@nx/docker` [Inference Plugin](/docs/concepts/inferred-tasks), Nx will automatically detect `Dockerfile`'s in your workspace and provide a `docker:build` and `docker:run` target for each.
It will also provide a `nx-release-publish` target for publishing docker images to a registry.

## Installation

In any Nx workspace, you can install `@nx/docker` by running the following command:

```shell
nx add @nx/docker
```

This will install the correct version of `@nx/docker` to match the version of Nx you are using.

{% aside title="Minimum Nx Version" type="caution" %}
The `@nx/docker` plugin only became available in Nx 21.4.0-beta.9. Your Nx Workspace will need to be on this version or higher to use it.
{% /aside %}

### How @nx/docker infers tasks

The `@nx/docker` plugin will create a task for any project that has a Dockerfile present. It will infer the following tasks:

- `docker:build`
- `docker:run`
- `nx-release-publish`

### View inferred tasks

To view inferred tasks for a project, open the [project details view](/docs/concepts/inferred-tasks) in Nx Console or run `nx show project my-project` in the command line.

### @nx/docker configuration

The `@nx/docker` plugin is configured in the `plugins` array in `nx.json`.

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/docker",
      "options": {
        "buildTarget": "docker:build",
        "runTarget": "docker:run"
      }
    }
  ]
}
```

The `buildTarget` and `runTarget` options control the names of the inferred Docker tasks. The default names are `docker:build` and `docker:run`.

### Advanced plugin configuration

The `buildTarget` and `runTarget` options can be configured as objects to provide additional customization beyond just naming the targets. This allows you to pass custom arguments, set environment variables, and use pattern interpolation.

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/docker",
      "options": {
        "buildTarget": {
          "name": "docker:build",
          "args": [
            "--platform",
            "linux/amd64,linux/arm64",
            "--label",
            "project={projectName}"
          ],
          "env": {
            "DOCKER_BUILDKIT": "1"
          },
          "envFile": ".env.docker",
          "cwd": "{projectRoot}/docker"
        },
        "runTarget": {
          "name": "docker:run",
          "args": ["--rm"],
          "env": {
            "NODE_ENV": "production"
          }
        }
      }
    }
  ]
}
```

#### Configuration properties

When using the object format, the following properties are available:

- **`name`** (string, required): The name of the inferred target
- **`args`** (string[], optional): Additional arguments to pass to the Docker command. Supports pattern interpolation.
- **`env`** (object, optional): Environment variables to set when running the Docker command. Values support pattern interpolation.
- **`envFile`** (string, optional): Path to an environment file to load
- **`cwd`** (string, optional): Working directory for the command. Supports pattern interpolation.

#### Pattern interpolation

All string values in the configuration support pattern interpolation using the following tokens:

- **`{projectName}`** - The name of the project from `project.json` or `package.json`
- **`{projectRoot}`** - The root directory of the project (e.g., `apps/api`)
- **`{imageRef}`** - The default image reference derived from the project root (e.g., `apps-api`)
- **`{currentDate}`** - Current date in ISO format (e.g., `2025-01-30T14:30:00.000Z`)
- **`{currentDate|FORMAT}`** - Current date with custom formatting (e.g., `{currentDate|YYYY.MM.DD}` → `2025.01.30`)
- **`{commitSha}`** - Full Git commit SHA
- **`{shortCommitSha}`** - First 7 characters of the commit SHA
- **`{env.VAR_NAME}`** - Environment variable values (e.g., `{env.BUILD_NUMBER}`)

Date formatting supports these tokens: `YYYY` (year), `YY` (2-digit year), `MM` (month), `DD` (day), `HH` (hours), `mm` (minutes), `ss` (seconds).

#### Example: multi-Platform build with metadata

Here's a practical example that builds Docker images for multiple platforms and includes build metadata:

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/docker",
      "options": {
        "buildTarget": {
          "name": "build",
          "args": [
            "--platform",
            "linux/amd64,linux/arm64",
            "--label",
            "org.opencontainers.image.title={projectName}",
            "--label",
            "org.opencontainers.image.source={projectRoot}",
            "--label",
            "org.opencontainers.image.revision={commitSha}",
            "--label",
            "org.opencontainers.image.created={currentDate}",
            "--build-arg",
            "BUILD_DATE={currentDate|YYYY-MM-DD}",
            "--build-arg",
            "VERSION={env.VERSION}",
            "--tag",
            "{imageRef}:{currentDate|YYMMDD}.{shortCommitSha}"
          ],
          "env": {
            "DOCKER_BUILDKIT": "1",
            "IMAGE_NAME": "{imageRef}"
          }
        },
        "runTarget": {
          "name": "run",
          "args": [
            "--rm",
            "--publish",
            "3000:3000",
            "--env",
            "NODE_ENV=production"
          ]
        }
      }
    }
  ]
}
```

This configuration:

- Builds for both AMD64 and ARM64 architectures
- Adds OpenContainers metadata labels with project information
- Tags images with a calendar version and commit SHA (e.g., `my-app:250130.abc1234`)
- Enables Docker BuildKit for improved build performance
- Injects build arguments and environment variables from the CI/CD pipeline

## Using Nx release to publish Docker images

The `@nx/docker` plugin provides a `nx-release-publish` target for publishing docker images to a registry.
[Nx Release](/docs/features/manage-releases) was also updated to support versioning docker images, generating changelogs, and publishing docker images to a registry through a single command.

You can learn more about how to manage releases for Docker Images in the [Release Docker Images](/docs/guides/nx-release/release-docker-images) guide.

---
<!-- source: https://nx.dev/docs/technologies/build-tools/docker/migrations.md -->
## @nx/docker Migrations

No migrations found for `@nx/docker`.
Nx only retains migrations for the last 2 major versions of Nx.
It's possible migrations existed in previous versions of `@nx/docker`.

You can check the previous docs for [Nx v21](https://21.nx.dev/docs) or [Nx v20](https://20.nx.dev/docs).

---
<!-- source: https://nx.dev/docs/technologies/build-tools/esbuild.md -->
## ESBuild

{% index_page_cards path="technologies/build-tools/esbuild" /%}

---
<!-- source: https://nx.dev/docs/technologies/build-tools/esbuild/executors.md -->
## @nx/esbuild Executors

The @nx/esbuild plugin provides various executors to help you create and configure esbuild projects within your Nx workspace.
Below is a complete reference for all available executors and their options.

### `esbuild`
Bundle a package for different platforms.

`<app-root>/project.json`:

```jsonc
{
  //...
  "targets": {
    //...
    "build": {
      "executor": "@nx/esbuild:esbuild",
      "options": {
        "main": "<app-root>",
        "tsConfig": "<app-root>/tsconfig.app.json",
        "outputPath": "dist/<app-root>",
      },
    },
  },
}
```

```bash
nx build <app-name>
```

### Examples

###### CommonJS output

The CommonJS format is required in some environments, such as Electron applications. By default, `esbuild` will use the ESM format, which is recommended for Web and Node applications. You may also output to multiple formats.

```bash
nx build <app-name> --format=cjs
nx build <app-name> --format=esm,cjs
nx build <app-name> # defaults to es# defaults to esm
```

```json
"build": {
  "executor": "@nx/esbuild:esbuild",
  "options": {
    "main": "<app-root>",
    "tsConfig": "<app-root>/tsconfig.app.json",
    "outputPath": "dist/<app-root>",
      "format": ["esm", "cjs"]
  }
}
```

###### External packages

External packages are not bundled by default. To include them in the bundle you can use either the `thirdParty` option to include all third-party dependencies, or use `excludeFromExternal` option to include specific dependencies in the bundle.

To mark additional packages or assets as external, you may use the `external` option, which supports the `*` wildcard to match assets.

For example, this configuration includes all third-party dependencies such as `lodash` or `date-fns` in the bundle. It also marks all `*.png` files as external assets.

```json
"build": {
  "executor": "@nx/esbuild:esbuild",
  "options": {
    "main": "<app-root>",
    "tsConfig": "<app-root>/tsconfig.app.json",
    "outputPath": "dist/<app-root>",
    "thirdParty": true,
    "external": ["*.png"]
  }
}
```

And this configuration includes only `lodash` in the bundle, while keeping `*.png` files as external assets.

```json
"build": {
  "executor": "@nx/esbuild:esbuild",
  "options": {
    "main": "<app-root>",
    "tsConfig": "<app-root>/tsconfig.app.json",
    "outputPath": "dist/<app-root>",
    "excludeFromExternal": ["lodash"],
    "external": ["*.png"]
  }
}
```

###### Skip type checking

Type checking is the slowest part of the build. You may want to skip type checking during build and run it as another job in CI.

```json
"build": {
  "executor": "@nx/esbuild:esbuild",
  "options": {
    "main": "<app-root>",
    "tsConfig": "<app-root>/tsconfig.app.json",
    "outputPath": "dist/<app-root>",
    "skipTypeCheck": true
  }
}
```

###### Additional esbuild options

Additional [esbuild options](https://esbuild.github.io/api/) can be passed using `esbuildOptions` in your project configuration.

```json
"build": {
  "executor": "@nx/esbuild:esbuild",
  "options": {
    "main": "<app-root>",
    "tsConfig": "<app-root>/tsconfig.app.json",
    "outputPath": "dist/<app-root>",
    "esbuildOptions": {
      "legalComments": "inline",
      "banner": {
        ".js": "// banner"
      },
      "footer": {
        ".js": "// footer"
      }
    }
  }
}
```
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `main` | string [**required**] | The path to the entry file, relative to project. |  |
| `outputPath` | string [**required**] | The output path of the generated files. |  |
| `tsConfig` | string [**required**] | The path to tsconfig file. |  |
| `additionalEntryPoints` | array | List of additional entry points. | `[]` |
| `assets` | array | List of static assets. | `[]` |
| `bundle` | boolean | Whether to bundle the main entry point and additional entry points. Set to false to keep individual output files. | `true` |
| `declaration` | boolean | Generate declaration (*.d.ts) files for every TypeScript or JavaScript file inside your project. Should be used for libraries that are published to an npm repository. |  |
| `declarationRootDir` | string | Sets the rootDir for the declaration (*.d.ts) files. |  |
| `deleteOutputPath` | boolean | Remove previous output before build. | `true` |
| `esbuildConfig` | string | Path to a esbuild configuration file. See https://esbuild.github.io/api/. Cannot be used with 'esbuildOptions' option. |  |
| `esbuildOptions` | object | Additional options to pass to esbuild. See https://esbuild.github.io/api/. Cannot be used with 'esbuildConfig' option. |  |
| `excludeFromExternal` | array | List of dependencies that should be excluded from the external list. This is useful when Nx automatically marks certain packages as external, but you want to bundle them instead. |  |
| `external` | array | Mark one or more module as external. Can use * wildcards, such as '*.png'. |  |
| `format` | array | List of module formats to output. Defaults to matching format from tsconfig (e.g. CJS for CommonJS, and ESM otherwise). | `["esm"]` |
| `generatePackageJson` | boolean | Generates a `package.json` and pruned lock file with the project's `node_module` dependencies populated for installing in a container. If a `package.json` exists in the project's directory, it will be reused with dependencies populated. | `false` |
| `metafile` | boolean | Generate a meta.json file in the output folder that includes metadata about the build. This file can be analyzed by other tools. | `false` |
| `minify` | boolean | Minifies outputs. | `false` |
| `outputFileName` | string | Name of the main output file. Defaults same basename as 'main' file. |  |
| `outputHashing` | string | Define the output filename cache-busting hashing mode. | `"none"` |
| `platform` | string | Platform target for outputs. | `"node"` |
| `skipTypeCheck` | boolean | Skip type-checking via TypeScript. Skipping type-checking speeds up the build but type errors are not caught. | `false` |
| `sourcemap` | string | Generate sourcemap. |  |
| `target` | string | The environment target for outputs. | `"esnext"` |
| `thirdParty` | boolean | Includes third-party packages in the bundle (i.e. npm packages). |  |
| `watch` | boolean | Enable re-building when files change. | `false` |

---
<!-- source: https://nx.dev/docs/technologies/build-tools/esbuild/generators.md -->
## @nx/esbuild Generators

The @nx/esbuild plugin provides various generators to help you create and configure esbuild projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `configuration`
Add esbuild configuration to a project.

### Examples

```bash
nx g @nx/esbuild:configuration my-package
```

:::note[Overwriting existing build option]
The `configuration` generator validates that an existing `build` target isn't already defined for the project. If you are adding esbuild to a project with an existing `build` target, pass the `--skipValidation` option.
:::

You may also provide a custom main entry file, or a custom tsconfig file if the defaults don't work. By default, the generator will look for a main file matching `src/index.ts` or `src/main.ts`, and a tsconfig file matching `tsconfig.app.json` or `tsconfig.lib.json`.

```bash
nx g @nx/esbuild:configuration my-package \
--main=packages/my-package/src/entry.ts \
--tsConfig=packages/my-package/tsconfig.custom.json
```

**Usage:**
```bash
nx generate @nx/esbuild:configuration [options]
```

**Aliases:** `esbuild-project`

**Arguments:**
```bash
nx generate @nx/esbuild:configuration <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--buildTarget` | string | The build target to add. | `"build"` |
| `--format` | array | The format to build the library (esm or cjs). | `["esm"]` |
| `--importPath` | string | The library name used to import it, like `@myorg/my-awesome-lib`. |  |
| `--main` | string | Path relative to the workspace root for the main entry file. Defaults to `<project-root>/src/main.ts` or `<project-root>src/index.ts`, whichever is found. |  |
| `--platform` | string | Platform target for outputs. | `"node"` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--skipValidation` | boolean | Do not perform any validation on existing project. | `false` |
| `--tsConfig` | string | Path relative to the workspace root for the tsconfig file to build with. Defaults to `<project-root>/tsconfig.app.json` or `<project-root>/tsconfig.lib.json`, whichever is found. |  |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/esbuild:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/build-tools/esbuild/introduction.md -->
## esbuild Plugin for Nx

The Nx Plugin for [esbuild](https://esbuild.github.io/api/), an extremely fast JavaScript bundler.

## Requirements

The `@nx/esbuild` plugin supports the following package versions.

| Package   | Supported Versions |
| --------- | ------------------ |
| `esbuild` | >=0.19.2 <1.0.0    |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

Why should you use this plugin?

- _Fast_ builds using esbuild.
- Type-checking using TypeScript, which esbuild does not handle.
- Intelligent `package.json` output.
- Additional [assets](/docs/technologies/build-tools/esbuild/executors#esbuild) for the output.

## Setting up @nx/esbuild

### Installation

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/esbuild` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
{% /aside %}

In any Nx workspace, you can install `@nx/esbuild` by running the following command:

```shell
nx add @nx/esbuild
```

This will install the correct version of `@nx/esbuild`.

## Using the @nx/esbuild plugin

### Creating a new JS library

You can add a new library that builds using esbuild with:

```shell
nx g @nx/js:lib libs/mylib --bundler=esbuild
```

This command will install the esbuild plugin if needed, and set `@nx/esbuild:esbuild` executor for the `build` target.

### Adding esbuild target to existing libraries

If you already have a JS project that you want to use esbuild for, run this command:

```shell
nx g @nx/esbuild:configuration mylib
```

This generator validates there isn't an existing `build` target. If you want to overwrite the existing target you can pass the `--skipValidation` option.

```shell
nx g @nx/esbuild:configuration mylib --skipValidation
```

## Using esbuild

You can run builds with:

```shell
nx build mylib
```

Replace `mylib` with the name or your project. This command works for both applications and libraries.

### Copying assets

Assets are non-JS and non-TS files, such as images, CSS, etc. You can add them to the project configuration as follows.

```jsonc
"build": {
 "executor": "@nx/esbuild:esbuild",
  "options": {
    //...
    "assets": [
      { "input": "libs/mylib", "glob": "README.md", "output": "/" },
      { "input": "libs/mylib", "glob": "logo.png", "output": "/" },
      { "input": "libs/mylib", "glob": "docs/**/*.md", "output": "/docs" },
      //...
    ]
 }
}
```

Running `nx build mylib` outputs something like this.

```text
dist/libs/mylib/
├── README.md
├── docs
│   ├── CONTRIBUTING.md
│   └── TESTING.md
├── index.js
├── logo.png
└── package.json
```

### Generating a metafile

A metafile can be generated by passing the `--metafile` option. This file contains information about the build that can be analyzed by other tools, such as [bundle buddy](https://www.bundle-buddy.com/esbuild).

```shell
nx build mylib --metafile
```

This command will generate a `meta.json` file in the output directory.

```text
dist/libs/mylib/
├── README.md
├── index.js
├── meta.json
└── package.json
```

### Custom esbuild options

Extra API options for esbuild can be passed in the `esbuildOptions` object for your project configuration.

```jsonc
"build": {
  "executor": "@nx/esbuild:esbuild",
  "options": {
    //...
    "esbuildOptions": {
      "banner": { ".js": "// banner" },
      "footer": { ".js": "// footer" }
    }
  }
}
```

## More documentation

- [Using JS](/docs/technologies/typescript/introduction)

---
<!-- source: https://nx.dev/docs/technologies/build-tools/esbuild/migrations.md -->
## @nx/esbuild Migrations

No migrations found for `@nx/esbuild`.
Nx only retains migrations for the last 2 major versions of Nx.
It's possible migrations existed in previous versions of `@nx/esbuild`.

You can check the previous docs for [Nx v21](https://21.nx.dev/docs) or [Nx v20](https://20.nx.dev/docs).

---
<!-- source: https://nx.dev/docs/technologies/build-tools/rollup.md -->
## Rollup

{% index_page_cards path="technologies/build-tools/rollup" /%}

---
<!-- source: https://nx.dev/docs/technologies/build-tools/rollup/executors.md -->
## @nx/rollup Executors

The @nx/rollup plugin provides various executors to help you create and configure rollup projects within your Nx workspace.
Below is a complete reference for all available executors and their options.

### `rollup`
Packages a library for different web usages (ESM, CommonJS).

###### Including Dependencies

To include dependencies in the output `package.json`, the dependencies must be installed as a **dependencies** in the root `package.json`

```json title="package.json"
{
  "dependencies": {
    "some-dependency": "^1.0.0"
  }
}
```

###### Using `babelUpwardRootMode`

Copying from the [Babel documentation](https://babeljs.io/docs/config-files#root-babelconfigjson-file):

> [...] if you are running your Babel compilation process from within a subpackage, you need to tell Babel where to look for the config. There are a few ways to do that, but the recommended way is the "rootMode" option with "upward", which will make Babel search from the working directory upward looking for your babel.config.json file, and will use its location as the "root" value.

Setting `babelUpwardRootMode` to `true` in your `project.json` will set `rootMode` option to `upward` in the Babel config. You may want the `upward` mode in a monorepo when projects must apply their individual `.babelrc` file. We recommend that you don't set it at all, so it will use the default to `false` as the `upward` mode brings additional complexity to the build process.

```json
//...
"my-app": {
  "targets": {
    "build": {
      "executor": "@nx/rollup:rollup",
      "options": {
          "babelUpwardRootMode": true,
          //...
      },
      //...
    },
    //...
  },
  //...
}
```

When `babelUpwardRootMode` is `true`, Babel will look for a root `babel.config.json` at the root of the workspace, which should look something like this to include all packages:

```json
{ "babelrcRoots": ["*"] }
```

Then for each package, you must have a `.babelrc` file that will be applied to that package. For example:

```json
{
  "presets": ["@babel/preset-env", "@babel/preset-typescript"]
}
```

All packages will use its own `.babelrc` file, thus you must ensure the right presets and plugins are set in each config file. This behavior can lead to build discrepancies between packages, so we recommend that you don't set `babelUpwardRootMode` at all.

```text
├── packages
│   ├── a
│   │   └── .babelrc
│   └── b
│       └── .babelrc
└── babel.config.json
```

In workspace above, if `a` imports `b`, it will apply the config `packages/b/.babelrc` and not apply its own `packages/a/.babelrc` to `b`. Anything in `babel.config.json` will apply to all packages.
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `main` | string [**required**] | The path to the entry file, relative to project. |  |
| `outputPath` | string [**required**] | The output path of the generated files. |  |
| `tsConfig` | string [**required**] | The path to tsconfig file. |  |
| `additionalEntryPoints` | array | Additional entry-points to add to exports field in the package.json file. |  |
| `allowJs` | boolean | Allow JavaScript files to be compiled. | `false` |
| `assets` | array | List of static assets. | `[]` |
| `babelUpwardRootMode` | boolean | Whether to set rootmode to upward. See https://babeljs.io/docs/en/options#rootmode | `false` |
| `buildLibsFromSource` | boolean | Read buildable libraries from source instead of building them separately. | `true` |
| `compiler` | string | Which compiler to use. | `"babel"` |
| `deleteOutputPath` | boolean | Delete the output path before building. | `true` |
| `external` | array | A list of external modules that will not be bundled (`react`, `react-dom`, etc.). Can also be set to `all` (bundle nothing) or `none` (bundle everything). |  |
| `extractCss` | boolean | string | CSS files will be extracted to the output folder. Alternatively custom filename can be provided (e.g. styles.css) | `true` |
| `format` | array | List of module formats to output. Defaults to matching format from tsconfig (e.g. CJS for CommonJS, and ESM otherwise). |  |
| `generateExportsField` | boolean | Update the output package.json file's 'exports' field. This field is used by Node and bundles. | `false` |
| `javascriptEnabled` | boolean | Sets `javascriptEnabled` option for less loader | `false` |
| `outputFileName` | string | Name of the main output file. Defaults same basename as 'main' file. |  |
| `project` | string | The path to package.json file. |  |
| `rollupConfig` | string | Path to a function which takes a rollup config and returns an updated rollup config. |  |
| `skipTypeCheck` | boolean | Whether to skip TypeScript type checking. | `false` |
| `skipTypeField` | boolean | Prevents 'type' field from being added to compiled package.json file. Use this if you are having an issue with this field. | `false` |
| `sourceMap` | boolean | Output sourcemaps. |  |
| `useLegacyTypescriptPlugin` | boolean | Use rollup-plugin-typescript2 instead of @rollup/plugin-typescript. | `false` |
| `watch` | boolean | Enable re-building when files change. | `false` |

---
<!-- source: https://nx.dev/docs/technologies/build-tools/rollup/generators.md -->
## @nx/rollup Generators

The @nx/rollup plugin provides various generators to help you create and configure rollup projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `configuration`
Add Rollup Configuration to a project.

**Usage:**
```bash
nx generate @nx/rollup:configuration [options]
```

**Aliases:** `rollup-project`

**Arguments:**
```bash
nx generate @nx/rollup:configuration <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--buildTarget` | string | The build target to add. | `"build"` |
| `--compiler` | string | The compiler to use to build source. | `"babel"` |
| `--external` | array | A list of external modules that will not be bundled (`react`, `react-dom`, etc.). |  |
| `--format` | array | The format to build the library (esm or cjs). | `["esm"]` |
| `--importPath` | string | The library name used to import it, like `@myorg/my-awesome-lib`. |  |
| `--main` | string | Path relative to the workspace root for the main entry file. Defaults to '<projectRoot>/src/index.ts'. |  |
| `--rollupConfig` | string | Path relative to workspace root to a custom rollup file that takes a config object and returns an updated config. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--skipValidation` | boolean | Do not perform any validation on existing project. | `false` |
| `--tsConfig` | string | Path relative to the workspace root for the tsconfig file to build with. Defaults to '<projectRoot>/tsconfig.lib.json'. |  |

## `convert-to-inferred`
Convert existing Rollup project(s) using `@nx/rollup:rollup` executor to use `@nx/rollup/plugin`. Defaults to migrating all projects. Pass '--project' to migrate only one target.

**Usage:**
```bash
nx generate @nx/rollup:convert-to-inferred [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string | The project to convert from using the `@nx/rollup:rollup` executor to use `@nx/rollup/plugin`. |  |
| `--skipFormat` | boolean | Whether to format files at the end of the migration. | `false` |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/rollup:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/build-tools/rollup/introduction.md -->
## Rollup Plugin for Nx

The Nx Plugin for Rollup contains executors and generators that support building applications using Rollup.

## Requirements

The `@nx/rollup` plugin supports the following package versions.

| Package  | Supported Versions |
| -------- | ------------------ |
| `rollup` | ^4.14.0            |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

## Setting up @nx/rollup

### Installation

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/rollup` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
{% /aside %}

In any Nx workspace, you can install `@nx/rollup` by running the following command:

```shell
nx add @nx/rollup
```

This will install the correct version of `@nx/rollup`.

## Using @nx/rollup

### Generate a new project using Rollup

You can generate a new library that uses Rollup with the following command:

```bash frame="none"
nx g @nx/js:lib mylib --bundler=rollup
```

This will create a new library configured to use Rollup for building.

---
<!-- source: https://nx.dev/docs/technologies/build-tools/rollup/migrations.md -->
## @nx/rollup Migrations

No migrations found for `@nx/rollup`.
Nx only retains migrations for the last 2 major versions of Nx.
It's possible migrations existed in previous versions of `@nx/rollup`.

You can check the previous docs for [Nx v21](https://21.nx.dev/docs) or [Nx v20](https://20.nx.dev/docs).

---
<!-- source: https://nx.dev/docs/technologies/build-tools/rsbuild.md -->
## Rsbuild

{% index_page_cards path="technologies/build-tools/rsbuild" /%}

---
<!-- source: https://nx.dev/docs/technologies/build-tools/rsbuild/generators.md -->
## @nx/rsbuild Generators

The @nx/rsbuild plugin provides various generators to help you create and configure rsbuild projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `configuration`
Rsbuild configuration generator.

**Usage:**
```bash
nx generate @nx/rsbuild:configuration [options]
```

**Arguments:**
```bash
nx generate @nx/rsbuild:configuration <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--devServerPort` | number | The port for the dev server to listen on. | `4200` |
| `--entry` | string | Path relative to the workspace root for the entry file. Defaults to '<projectRoot>/src/index.ts'. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--target` | string | Target platform for the build, same as the Rsbuild output.target config option. | `"web"` |
| `--tsConfig` | string | Path relative to the workspace root for the tsconfig file to build with. Defaults to '<projectRoot>/tsconfig.app.json'. |  |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/rsbuild:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/build-tools/rsbuild/introduction.md -->
## Rsbuild Plugin for Nx

The Nx Plugin for Rsbuild contains executors and generators that support building applications using Rsbuild.

## Requirements

The `@nx/rsbuild` plugin supports the following package versions.

| Package         | Supported Versions |
| --------------- | ------------------ |
| `@rsbuild/core` | ^1.1.0             |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

## Setting up @nx/rsbuild

### Installation

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/rsbuild` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
{% /aside %}

In any Nx workspace, you can install `@nx/rsbuild` by running the following command:

```shell
nx add @nx/rsbuild
```

This will install the correct version of `@nx/rsbuild`.

## Using @nx/rsbuild

### Generate a new project using Rsbuild

You can generate a new application that uses Rsbuild with the following command:

```bash frame="none"
nx g @nx/react:app myapp --bundler=rsbuild
```

This will create a new application configured to use Rsbuild for building.

---
<!-- source: https://nx.dev/docs/technologies/build-tools/rsbuild/migrations.md -->
## @nx/rsbuild Migrations

No migrations found for `@nx/rsbuild`.
Nx only retains migrations for the last 2 major versions of Nx.
It's possible migrations existed in previous versions of `@nx/rsbuild`.

You can check the previous docs for [Nx v21](https://21.nx.dev/docs) or [Nx v20](https://20.nx.dev/docs).

---
<!-- source: https://nx.dev/docs/technologies/build-tools/rspack.md -->
## Rspack

{% index_page_cards path="technologies/build-tools/rspack" /%}

---
<!-- source: https://nx.dev/docs/technologies/build-tools/rspack/executors.md -->
## @nx/rspack Executors

The @nx/rspack plugin provides various executors to help you create and configure rspack projects within your Nx workspace.
Below is a complete reference for all available executors and their options.

### `dev-server`
Run @rspack/dev-server to serve a project.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `buildTarget` | string [**required**] | The build target for rspack. |  |
| `host` | string | Host to listen on. | `"localhost"` |
| `mode` | string | Mode to run the server in. |  |
| `port` | number | The port to for the dev-server to listen on. |  |
| `proxyConfig` | string | Path to proxy configuration file. For more information, see https://rspack.rs/config/dev-server#devserverproxy. |  |
| `publicHost` | string | Public URL where the application will be served. |  |
| `ssl` | boolean | Serve using `HTTPS`. | `false` |
| `sslCert` | string | SSL certificate to use for serving `HTTPS`. |  |
| `sslKey` | string | SSL key to use for serving `HTTPS`. |  |

### `module-federation-dev-server`
Serve a module federation application.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `buildTarget` | string | Target which builds the application. |  |
| `devRemotes` | array | List of Producer (remote) applications to run in development mode (i.e. using serve target). |  |
| `host` | string | Host to listen on. | `"localhost"` |
| `isInitialHost` | boolean | Whether the Consumer (host) that is running this executor is the first in the project tree to do so. | `true` |
| `parallel` | number | Max number of parallel processes for building static Producers (remotes). |  |
| `pathToManifestFile` | string | Path to a Module Federation manifest file (e.g. `my/path/to/module-federation.manifest.json`) containing the dynamic Producer (remote) applications relative to the workspace root. |  |
| `port` | number | Port to listen on. | `4200` |
| `publicHost` | string | Public URL where the application will be served. |  |
| `skipRemotes` | array | List of Producer (remote) applications to not automatically serve, either statically or in development mode. This will not remove the Producers (remotes) from the `module-federation.config` file, and therefore the application may still try to fetch these Producers (remotes).
This option is useful if you have other means for serving the Producer (remote) application(s).
**NOTE:** Producers (remotes) that are not in the workspace will be skipped automatically. |  |
| `ssl` | boolean | Serve using `HTTPS`. | `false` |
| `sslCert` | string | SSL certificate to use for serving `HTTPS`. |  |
| `sslKey` | string | SSL key to use for serving `HTTPS`. |  |
| `static` | boolean | Whether to use a static file server instead of the rspack-dev-server. This should be used for Producer (remote) applications that are also Consumer (host) applications. |  |
| `staticRemotesPort` | number | The port at which to serve the file-server for the static Producers (remotes). |  |

### `module-federation-ssr-dev-server`
Serve a SSR Consumer (host) application along with its known Producers (remotes).


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `browserTarget` | string [**required**] | Target which builds the browser application. |  |
| `serverTarget` | string [**required**] | Target which builds the server application. |  |
| `devRemotes` | array | List of Producers (remote) applications to run in development mode (i.e. using serve target). |  |
| `host` | string | Host to listen on. | `"localhost"` |
| `isInitialHost` | boolean | Whether the Consumer (host) that is running this executor is the first in the project tree to do so. | `true` |
| `pathToManifestFile` | string | Path to a Module Federation manifest file (e.g. `my/path/to/module-federation.manifest.json`) containing the dynamic Producers (remote) applications relative to the workspace root. |  |
| `port` | number | The port to be set on `process.env.PORT` for use in the server. | `4200` |
| `publicHost` | string | Public URL where the application will be served. |  |
| `skipRemotes` | array | List of Producers (remote) applications to not automatically serve, either statically or in development mode. |  |
| `ssl` | boolean | Serve using HTTPS. | `false` |
| `sslCert` | string | SSL certificate to use for serving HTTPS. |  |
| `sslKey` | string | SSL key to use for serving HTTPS. |  |
| `staticRemotesPort` | number | The port at which to serve the file-server for the static Producers (remotes). |  |

### `module-federation-static-server`
Serve a Consumer (host) application statically along with it's Producers (remotes).


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `serveTarget` | string [**required**] |  |  |

### `rspack`
Run Rspack via an executor for a project.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `rspackConfig` | string [**required**] | The path to the rspack config file. |  |
| `additionalEntryPoints` | array |  |  |
| `assets` | array | List of static application assets. | `[]` |
| `baseHref` | string | Base url for the application being built. |  |
| `buildLibsFromSource` | boolean | Read buildable libraries from source instead of building them separately. If set to `false`, the `tsConfig` option must also be set to remap paths. | `true` |
| `cache` | boolean | Configure rspack caching behavior. When not specified, defaults to `true` for Node targets in watch mode, and `undefined` otherwise. |  |
| `deployUrl` | string | URL where the application will be deployed. |  |
| `externalDependencies` | string | Dependencies to keep external to the bundle. (`all` (default), `none`, or an array of module names) |  |
| `extractCss` | boolean | Extract CSS into a `.css` file. |  |
| `extractLicenses` | boolean | Extract all licenses in a separate file. | `false` |
| `fileReplacements` | array | Replace files with other files in the build. | `[]` |
| `generateIndexHtml` | boolean | Generates `index.html` file to the output path. This can be turned off if using a webpack plugin to generate HTML such as `html-webpack-plugin`. |  |
| `generatePackageJson` | boolean | Generates a `package.json` and pruned lock file with the project's `node_module` dependencies populated for installing in a container. If a `package.json` exists in the project's directory, it will be reused with dependencies populated. |  |
| `index` | string | HTML File which will be contain the application. |  |
| `main` | string | The main entry file. |  |
| `memoryLimit` | number | Memory limit for type checking service process in `MB`. |  |
| `mode` | string | Mode to run the build in. |  |
| `namedChunks` | boolean | Names the produced bundles according to their entry file. |  |
| `optimization` | string | Enables optimization of the build output. |  |
| `outputFileName` | string | The main output entry file |  |
| `outputHashing` | string | Define the output filename cache-busting hashing mode. |  |
| `outputPath` | string | The output path for the bundle. |  |
| `poll` | number | Enable and define the file watching poll time period. |  |
| `polyfills` | string | Polyfills to load before application |  |
| `postcssConfig` | string | Set a path to PostCSS config that applies to the app and all libs. Defaults to `undefined`, which auto-detects postcss.config.js files in each `app`/`lib` directory. |  |
| `progress` | boolean | Log progress to the console while building. |  |
| `publicPath` | string | Set a public path for assets resources with absolute paths. |  |
| `rebaseRootRelative` | boolean | Whether to rebase absolute path for assets in postcss cli resources. |  |
| `runtimeChunk` | boolean | Use a separate bundle containing the runtime. |  |
| `runtimeDependencies` | array | Add runtime dependencies to the generated `package.json` file. Useful for Docker installs. Only works in conjunction with `generatePackageJson` option. |  |
| `scripts` | array | External Scripts which will be included before the main application entry. |  |
| `skipTypeChecking` | boolean | Skip the type checking. Default is `false`. |  |
| `sourceMap` | string | Output sourcemaps. Use 'hidden' for use with error reporting tools without generating sourcemap comment. | `true` |
| `standardRspackConfigFunction` | boolean | Set to true if the rspack config exports a standard rspack function, not an Nx-specific one. See: https://rspack.dev/config/ | `false` |
| `statsJson` | boolean | Generates a 'stats.json' file which can be analyzed using tools such as: 'webpack-bundle-analyzer' See: https://rspack.dev/guide/optimization/analysis |  |
| `stylePreprocessorOptions` | object | Options to pass to style preprocessors. |  |
| `styles` | array | External Styles which will be included with the application |  |
| `target` | string | The platform to target (e.g. web, node). |  |
| `transformers` | array | List of TypeScript Compiler Transfomers Plugins. |  |
| `tsConfig` | string | The tsconfig file to build the project. |  |
| `typeCheckOptions` | string | Configure type checking during the build. Set to `true` to enable with defaults (async: true). Set to `false` to disable type checking entirely. Use `{ async: true }` to run type checking in a separate process without blocking the build. Default is `{ async: true }`. |  |
| `vendorChunk` | boolean | Use a separate bundle containing only vendor libraries. |  |

### `ssr-dev-server`
Serve a SSR application using rspack.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `browserTarget` | string [**required**] | Target which builds the browser application. |  |
| `serverTarget` | string [**required**] | Target which builds the server application. |  |
| `browserTargetOptions` | object | Additional options to pass into the browser build target. | `{}` |
| `port` | number | The port to be set on `process.env.PORT` for use in the server. | `4200` |
| `serverTargetOptions` | object | Additional options to pass into the server build target. | `{}` |

---
<!-- source: https://nx.dev/docs/technologies/build-tools/rspack/generators.md -->
## @nx/rspack Generators

The @nx/rspack plugin provides various generators to help you create and configure rspack projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `configuration`
Rspack configuration generator.

**Usage:**
```bash
nx generate @nx/rspack:configuration [options]
```

**Arguments:**
```bash
nx generate @nx/rspack:configuration <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--buildTarget` | string | The build target of the project to be transformed to use the @nx/vite:build executor. |  |
| `--devServer` | boolean | Add a serve target to run a local rspack dev-server | `false` |
| `--framework` | string | The framework used by the project. |  |
| `--main` | string | Path relative to the workspace root for the main entry file. Defaults to '<projectRoot>/src/main.ts'. |  |
| `--newProject` | boolean | Is this a new project? | `false` |
| `--rootProject` | boolean |  |  |
| `--serveTarget` | string | The serve target of the project to be transformed to use the @nx/vite:dev-server and @nx/vite:preview-server executors. |  |
| `--style` | string | The style solution to use. |  |
| `--target` | string | Target platform for the build, same as the rspack config option. | `"web"` |
| `--tsConfig` | string | Path relative to the workspace root for the tsconfig file to build with. Defaults to '<projectRoot>/tsconfig.app.json'. |  |

## `convert-config-to-rspack-plugin`
Convert existing Rspack project(s) using `@nx/rspack:rspack` executor that uses `withNx` to use `NxAppRspackPlugin`. Defaults to migrating all projects. Pass '--project' to migrate only one target.

**Usage:**
```bash
nx generate @nx/rspack:convert-config-to-rspack-plugin [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string | The project to convert from using the `@nx/rspack:rspack` executor and `withNx` plugin to use `NxAppRspackPlugin`. |  |
| `--skipFormat` | boolean | Whether to format files at the end of the migration. | `false` |

## `convert-to-inferred`
Convert existing Rspack project(s) using `@nx/rspack:rspack` executor to use `@nx/rspack/plugin`.

**Usage:**
```bash
nx generate @nx/rspack:convert-to-inferred [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string | The project to convert from using the `@nx/rspack:rspack` executor to use `@nx/rspack/plugin`. If not provided, all projects using the `@nx/rspack:rspack` executor will be converted. |  |
| `--skipFormat` | boolean | Whether to format files. | `false` |

## `convert-webpack`
Convert a Webpack project to Rspack.

**Usage:**
```bash
nx generate @nx/rspack:convert-webpack [options]
```

**Aliases:** `convert-to-rspack`

**Arguments:**
```bash
nx generate @nx/rspack:convert-webpack <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--skipFormat` | boolean | Skip formatting files. | `false` |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/rspack:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/build-tools/rspack/introduction.md -->
## Rspack Plugin for Nx

The Nx Plugin for Rspack contains executors, generators, and utilities for managing Rspack projects in an Nx Workspace.

## Requirements

The `@nx/rspack` plugin supports the following package versions.

| Package        | Supported Versions |
| -------------- | ------------------ |
| `@rspack/core` | ^1.6.0             |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

## Setting up @nx/rspack

### Installation

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/rspack` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
{% /aside %}

In any Nx workspace, you can install `@nx/rspack` by running the following command:

```shell
nx add @nx/rspack
```

This will install the correct version of `@nx/rspack`.

### How @nx/rspack infers tasks

The `@nx/rspack` plugin will create a task for any project that has a Rspack configuration file present. Any of the following files will be recognized as a Rspack configuration file:

- `rspack.config.js`
- `rspack.config.ts`
- `rspack.config.mjs`
- `rspack.config.mts`
- `rspack.config.cjs`
- `rspack.config.cts`

### View inferred tasks

To view inferred tasks for a project, open the [project details view](/docs/concepts/inferred-tasks) in Nx Console or run `nx show project my-project --web` in the command line.

### @nx/rspack configuration

The `@nx/rspack/plugin` is configured in the `plugins` array in `nx.json`.

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/rspack/plugin",
      "options": {
        "buildTargetName": "build",
        "previewTargetName": "preview",
        "serveTargetName": "serve",
        "serveStaticTargetName": "serve-static"
      }
    }
  ]
}
```

The `buildTargetName`, `previewTargetName`, `serveTargetName` and `serveStaticTargetName` options control the names of the inferred Rspack tasks. The default names are `build`, `preview`, `serve` and `serve-static`.

## Using @nx/rspack

### Generate a new project using Rspack

You can generate a [React](/docs/technologies/react/introduction) application that uses Rspack. The [`@nx/react:app`](/docs/technologies/react/generators#application) generator accepts the `bundler` option, where you can pass `rspack`. This will generate a new application configured to use Rspack, and it will also install all the necessary dependencies, including the `@nx/rspack` plugin.

To generate a React application using Rspack, run the following:

```bash frame="none"
nx g @nx/react:app my-app --bundler=rspack
```

### Modify an existing React project to use Rspack

You can use the `@nx/rspack:configuration` generator to change your React to use Rspack. This generator will modify your project's configuration to use Rspack, and it will also install all the necessary dependencies, including the `@nx/rspack` plugin.

You can read more about this generator on the [`@nx/rspack:configuration`](/docs/technologies/build-tools/rspack/generators#configuration) generator page.

---
<!-- source: https://nx.dev/docs/technologies/build-tools/rspack/migrations.md -->
## @nx/rspack Migrations

The @nx/rspack plugin provides various migrations to help you migrate to newer versions of rspack projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 22.2.x

### 22.2.0-package-updates
**Version**: 22.2.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@module-federation/enhanced` | `^0.21.2` | Updated only
| `@module-federation/runtime` | `^0.21.2` | Updated only
| `@module-federation/sdk` | `^0.21.2` | Updated only
| `@module-federation/node` | `^2.7.21` | Updated only



## 22.0.x

### `remove-deprecated-rspack-options`
**Version**: 22.0.0-beta.1

Remove deprecated deleteOutputPath and sassImplementation options from rspack configurations.



## 21.5.x

### 21.5.0-package-updates
**Version**: 21.5.0-beta.2


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@rspack/core` | `^1.5.0` | Updated only
| `@rspack/dev-server` | `^1.1.4` | Updated only



## 21.4.x

### 21.4.0-package-updates
**Version**: 21.4.0-beta.8


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `http-proxy-middleware` | `^3.0.5` | Updated only



## 21.3.x

### 21.3.0-package-updates
**Version**: 21.3.0-beta.8


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@module-federation/enhanced` | `^0.17.0` | Updated only
| `@module-federation/node` | `^2.7.9` | Updated only



## 21.0.x

### 21.0.1-package-updates
**Version**: 21.0.1-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@rspack/core` | `^1.3.8` | Updated only
| `@rspack/dev-server` | `^1.1.1` | Updated only



## 20.5.x

### 20.5.0-package-updates
**Version**: 20.5.0-beta.4


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `sass-loader` | `^16.0.4` | Updated only
| `@rspack/core` | `^1.2.2` | Updated only



## 20.3.x

### `ensure-nx-module-federation-package`
**Version**: 20.3.0-beta.2

If workspace includes Module Federation projects, ensure the new @nx/module-federation package is installed.

#### Ensure the @nx/module-federation Package is Installed

If workspace includes Module Federation projects, ensure the new `@nx/module-federation` package is installed.

#### Sample Code Changes

##### Before

```json title="package.json"
{
  "dependencies": {}
}
```

##### After

```json title="package.json"
{
  "dependencies": {
    "@nx/module-federation": "20.3.0"
  }
}
```




## 20.2.x

### `update-20-2-0-update-with-module-federation-import`
**Version**: 20.2.0-beta.3

Update the withModuleFederation import use @nx/module-federation/rspack.

#### Migrate withModuleFederation Import to New Package

Update the withModuleFederation import to use @nx/module-federation/rspack.

#### Sample Code Changes

Update import paths for `withModuleFederation` and `withModuleFederationForSSR`.

##### Before

```ts title="apps/shell/rspack.config.ts"
import {
  withModuleFederation,
  withModuleFederationForSSR,
} from '@nx/rspack/module-federation';
```

##### After

```ts title="apps/shell/rspack.config.ts"
import {
  withModuleFederation,
  withModuleFederationForSSR,
} from '@nx/module-federation/rspack';
```



### 20.2.0-package-updates
**Version**: 20.2.0-beta.7


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@rspack/core` | `^1.1.5` | Updated only
| `@rspack/dev-server` | `^1.0.9` | Updated only

---
<!-- source: https://nx.dev/docs/technologies/build-tools/vite.md -->
## Vite

{% index_page_cards path="technologies/build-tools/vite" /%}

---
<!-- source: https://nx.dev/docs/technologies/build-tools/vite/executors.md -->
## @nx/vite Executors

The @nx/vite plugin provides various executors to help you create and configure vite projects within your Nx workspace.
Below is a complete reference for all available executors and their options.

### `build`
Builds a Vite application for production.

`project.json`:

```json
//...
"my-app": {
    "targets": {
        //...
        "build": {
            "executor": "@nx/vite:build",
            //...
            //...
            "options": {
                "outputPath": "dist/apps/my-app"
            },
                //...
            }
        },
    }
}
```

```bash
nx serve my-app
```

### Examples

###### Set a custom path for vite.config.ts

Nx will automatically look in the root of your application for a `vite.config.ts` (or a `vite.config.js`) file. If you want to use a different path, you can set it in your `project.json` file, in the `build` target options:

```json
//...
"my-app": {
    "targets": {
        //...
        "build": {
            "executor": "@nx/vite:build",
            //...
            "options": {
                "outputPath": "dist/apps/my-app",
                "configFile": "apps/my-app/vite.config.other-path.ts"
            },
            "configurations": {
                ...
            }
        },
    }
}
```

or even

```json
//...
"my-app": {
    "targets": {
        //...
        "build": {
            "executor": "@nx/vite:build",
            //...
            "options": {
                "outputPath": "dist/apps/my-app",
                "configFile": "vite.config.base.ts"
            },
            "configurations": {
                ...
            }
        },
    }
}
```
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `buildLibsFromSource` | boolean | Read buildable libraries from source instead of building them separately. | `true` |
| `configFile` | string | The name of the Vite configuration file. |  |
| `generatePackageJson` | boolean | Generate a package.json for the build output. |  |
| `includeDevDependenciesInPackageJson` | boolean | Include devDependencies in the generated package.json. |  |
| `outputPath` | string | The output path of the generated files. |  |
| `skipOverrides` | boolean | Do not add a `overrides` and `resolutions` entries to the generated package.json file. Only works in conjunction with `generatePackageJson` option. |  |
| `skipPackageManager` | boolean | Do not add a `packageManager` entry to the generated package.json file. Only works in conjunction with `generatePackageJson` option. |  |
| `skipTypeCheck` | boolean | Skip type-checking via TypeScript. Skipping type-checking speeds up the build but type errors are not caught. | `false` |
| `tsConfig` | string | The path to custom tsconfig file for type-checking when skipTypeCheck is false. Required when tsconfig file is not at the projectRoot level. |  |
| `useEnvironmentsApi` | boolean | Use the new Environments API for building multiple environments at once. Only works with Vite 6.0.0 or higher. | `false` |
| `watch` | string | Enable re-building when files change. | `false` |

### `dev-server`
Starts a dev server using Vite.

`project.json`:

```json
//...
"my-app": {
    "targets": {
        //...
        "serve": {
            "executor": "@nx/vite:dev-server",
            "defaultConfiguration": "development",
            "options": {
                "buildTarget": "my-app:build",
            },
            "configurations": {
                ...
            }
        },
    }
}
```

```bash
nx serve my-app
```

### Examples

###### Set up a custom port

You can always set the port in your `vite.config.ts` file. However, you can also set it directly in your `project.json` file, in the `serve` target options:

```json
//...
"my-app": {
    "targets": {
        //...
        "serve": {
            "executor": "@nx/vite:dev-server",
            "defaultConfiguration": "development",
            "options": {
                "buildTarget": "my-app:build",
                "port": 4200,
            },
            "configurations": {
                ...
            }
        },
    }
}
```

###### Specify a proxyConfig

You can specify a proxy config by pointing to the path of your proxy configuration file:

```json
//...
"my-app": {
    "targets": {
        //...
        "serve": {
            "executor": "@nx/vite:dev-server",
            "defaultConfiguration": "development",
            "options": {
                "buildTarget": "my-app:build",
                "proxyConfig": "apps/my-app/proxy.conf.json"
            },
            "configurations": {
                ...
            }
        },
    }
}
```
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `buildTarget` | string [**required**] | Target which builds the application. Only used to retrieve the configuration as the dev-server does not build the code. |  |
| `buildLibsFromSource` | boolean | Read buildable libraries from source instead of building them separately. | `true` |
| `proxyConfig` | string | Path to the proxy configuration file. |  |

### `preview-server`
Preview Server for Vite.

`project.json`:

```json
//...
"my-app": {
    "targets": {
        //...
        "preview": {
            "executor": "@nx/vite:preview-server",
            "defaultConfiguration": "development",
            "options": {
                "buildTarget": "my-app:build",
            },
            "configurations": {
                ...
            }
        },
    }
}
```

```bash
nx preview my-app
```

### Examples

###### Set up a custom port

You can always set the port in your `vite.config.ts` file. However, you can also set it directly in your `project.json` file, in the `preview` target options:

```json
//...
"my-app": {
    "targets": {
        //...
        "preview": {
            "executor": "@nx/vite:preview-server",
            "defaultConfiguration": "development",
            "options": {
                "buildTarget": "my-app:build",
                "port": 4200,
            },
            "configurations": {
                ...
            }
        },
    }
}
```

###### Specify a proxyConfig

You can specify a proxy config by pointing to the path of your proxy configuration file:

```json
//...
"my-app": {
    "targets": {
        //...
        "preview": {
            "executor": "@nx/vite:preview-server",
            "defaultConfiguration": "development",
            "options": {
                "buildTarget": "my-app:build",
                "proxyConfig": "apps/my-app/proxy.conf.json"
            },
            "configurations": {
                ...
            }
        },
    }
}
```
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `buildTarget` | string [**required**] | Target which builds the application. |  |
| `proxyConfig` | string | Path to the proxy configuration file. |  |
| `staticFilePath` | string | Path where the build artifacts are located. If not provided then it will be infered from the buildTarget executor options as outputPath |  |
| `watch` | boolean | Enable re-building when files change. If not specified, watch mode will be enabled by default. | `true` |

### `test`
Test using Vitest.

:::danger[Deprecated]
The `@nx/vite:test` executor is deprecated. Please use `@nx/vitest:test` instead. This executor will be removed in Nx 23.

See the [migration guide](/docs/technologies/test-tools/vitest/guides/migrating-from-nx-vite) for more information.
:::

`project.json`:

```json
//...
"my-app": {
    "targets": {
        //...
        "test": {
            "executor": "@nx/vite:test",
            //...
            //...
            "options": {
                "config": "apps/my-app/vite.config.ts"
            }
            //...
        }
    }
}
```

```bash
nx test my-app
```

### Examples

###### Running in watch mode

To run testing in watch mode, you can create a new configuration within your test target, and have watch set to true. For example:

```json
"my-app": {
    "targets": {
        //...
        "test": {
            "executor": "@nx/vite:test",
            //...
            //...
            "options": {
                "config": "apps/my-app/vite.config.ts"
            },
            "configurations": {
                "watch": {
                    "watch": true
                }
            }
        }
    }
}
```

And then run `nx run my-app:test:watch`.

Alternatively, you can just run the default test target with the `--watch` flag preset, like so:

```bash
nx run my-app:test --watch
```

###### Updating snapshots

Whenever a test fails because of an outdated snapshot, you can tell vitest to update them with the following:

```bash
nx run my-app:test -u
```
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `configFile` | string | The path to the local vitest config, relative to the workspace root. |  |
| `mode` | string | Mode for Vite. |  |
| `reportsDirectory` | string | Directory to write coverage report to. |  |
| `testFiles` | array |  |  |
| `watch` | boolean | Watch files for changes and rerun tests related to changed files. |  |

---
<!-- source: https://nx.dev/docs/technologies/build-tools/vite/generators.md -->
## @nx/vite Generators

The @nx/vite plugin provides various generators to help you create and configure vite projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `configuration`
Configure a project to use Vite.

This generator is used for converting an existing React or Web project to use [Vite](https://vite.dev/).

It will create a `vite.config.ts` file at the root of your project with the correct settings, or if there's already a `vite.config.ts` file, it will modify it to include the correct settings.

:::caution[Your code will be modified!]
This generator will modify your code, so make sure to commit your changes before running it.
:::

```bash
nx g @nx/vite:configuration
```

When running this generator, you will be prompted to provide the following:

- The `project`, as the name of the project you want to generate the configuration for.
- The `uiFramework` you want to use. Supported values are: `react` and `none`.

You must provide a `project` and a `uiFramework` for the generator to work.

You may also pass the `includeVitest` flag. This will also configure your project for testing with [Vitest](https://vitest.dev/), by adding the `test` configuration in your `vite.config.ts` file.

:::note[Vitest-only configuration]
If you only need to add Vitest to a project (without Vite build configuration), use the `@nx/vitest:configuration` generator instead. See the [@nx/vitest package](/packages/vitest) for more information.
:::

### How to use

If you have an existing project that does not use Vite, you may want to convert it to use Vite. This can be a `webpack` project, a buildable JS library that uses the `@nx/js:babel`, the `@nx/js:swc` or the `@nx/rollup:rollup` executor, or even a non-buildable library.
By default, the `@nx/vite:configuration` generator will search your project to find the relevant configuration (either a `webpack.config.ts` file for example, or the `@nx/js` executors). If it determines that your project can be converted, then Nx will generate the configuration for you. If it cannot determine that your project can be converted, it will ask you if you want to convert it anyway or throw an error if it determines that it cannot be converted.

You can then test on your own if the result works or not, and modify the configuration as needed. It's suggested that you commit your changes before running the generator, so you can revert the changes if needed.

### Projects that can be converted to use the `@nx/vite` executors

Usually, React and Web projects generated with the `@nx/react` and the `@nx/web` generators can be converted to use the `@nx/vite` executors without any issues.

The list of executors for building, testing and serving that can be converted to use the `@nx/vite` executors is:

#### Supported `build` executors

- `@nxext/vite:build`
- `@nx/js:babel`
- `@nx/js:swc`
- `@nx/rollup:rollup`
- `@nx/webpack:webpack`
- `@nx/web:rollup`

#### Unsupported executors

- `@nx/angular:ng-packagr-lite`
- `@nx/angular:package`
- `@nx/angular:webpack-browser`
- `@angular-devkit/build-angular:browser`
- `@angular-devkit/build-angular:dev-server`
- `@nx/esbuild:esbuild`
- `@nx/react-native:start`
- `@nx/next:build`
- `@nx/next:server`
- `@nx/js:tsc`
- any executor _not_ listed in the lists of "supported executors"
- any project that does _not_ have a target for building, serving or testing

We **cannot** guarantee that projects using unsupported executors - _or any executor that is NOT listed in the list of "supported executors"_ - for either building, testing or serving will work correctly when converted to use Vite.

You can read more in the [Vite package overview page](/nx-api/vite).

### Examples

#### Convert a React app to use Vite

```bash
nx g @nx/vite:configuration --project=my-react-app --uiFramework=react --includeVitest
```

This will configure the `my-react-app` project to use Vite.

#### Convert a Web app to use Vite

```bash
nx g @nx/vite:configuration --project=my-web-app --uiFramework=none --includeVitest
```

This will configure the `my-web-app` project to use Vite.

**Usage:**
```bash
nx generate @nx/vite:configuration [options]
```

**Aliases:** `config`

**Arguments:**
```bash
nx generate @nx/vite:configuration <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--compiler` | string | Compiler to use for Vite when UI Framework is React. | `"babel"` |
| `--includeLib` | boolean | Add a library build option and skip the server option. |  |
| `--includeVitest` | boolean | Use vitest for the test suite. |  |
| `--newProject` | boolean | Is this a new project? | `false` |
| `--port` | number | The port to use for the development server |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--testEnvironment` | string | The vitest environment to use. See https://vitest.dev/config/#environment. | `"jsdom"` |
| `--uiFramework` | string | UI Framework to use for Vite. | `"none"` |

## `convert-to-inferred`
Convert existing Vite project(s) using `@nx/vite:*` executors to use `@nx/vite/plugin`. Defaults to migrating all projects. Pass '--project' to migrate only one target.

**Usage:**
```bash
nx generate @nx/vite:convert-to-inferred [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string | The project to convert from using the `@nx/vite:*` executors to use `@nx/vite/plugin`. |  |
| `--skipFormat` | boolean | Whether to format files at the end of the migration. | `false` |

## `setup-paths-plugin`
Updates vite config files to enable support for workspace libraries via the nxViteTsPaths plugin.

**Usage:**
```bash
nx generate @nx/vite:setup-paths-plugin [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--skipFormat` | boolean | Skip formatting files. | `false` |

## `vitest`
Generate a Vitest setup for a project.

**Usage:**
```bash
nx generate @nx/vite:vitest [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string [**required**] | The name of the project to test. |  |
| `--compiler` | string | The compiler to use | `"babel"` |
| `--coverageProvider` | string | Coverage provider to use. | `"v8"` |
| `--inSourceTests` | boolean | Do not generate separate spec files and set up in-source testing. | `false` |
| `--runtimeTsconfigFileName` | string | The name of the project's tsconfig file that includes the runtime source files. If not provided, it will default to `tsconfig.lib.json` for libraries and `tsconfig.app.json` for applications. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipViteConfig` | boolean | Skip generating a vite config file. | `false` |
| `--testEnvironment` | string | The vitest environment to use. See https://vitest.dev/config/#environment. |  |
| `--testTarget` | string | The test target of the project to be transformed to use the @nx/vite:test executor. |  |
| `--uiFramework` | string | UI framework to use with vitest. |  |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/vite:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/build-tools/vite/guides.md -->
## Guides

{% index_page_cards path="technologies/build-tools/vite/guides" /%}

---
<!-- source: https://nx.dev/docs/technologies/build-tools/vite/guides/configure-vite.md -->
## Configure Vite on your Nx workspace

{% aside type="note" title="Use our generator!" %}
It is recommended that you use the [`@nx/vite:configuration`](/docs/technologies/build-tools/vite/generators#configuration) generator to set up [Vite](https://vite.dev/) for your new or existing projects.
{% /aside %}

The `@nx/vite` plugin generators take care of configuring Vite for you. However, you may need to set up Vite manually in some cases. This guide explains how you can configure Vite in your Nx workspace.

## TypeScript paths

You need to use the `nxViteTsPaths()` plugin to make sure that your TypeScript paths are resolved correctly in your monorepo.

## Framework plugins

If you are using React, you need to use the [`@vitejs/plugin-react` plugin](https://www.npmjs.com/package/@vitejs/plugin-react). If you're using Vue, you need to use the [`@vitejs/plugin-vue` plugin](https://www.npmjs.com/package/@vitejs/plugin-vue).

## Set the `root` path

Make sure to set the `root: __dirname,` property on your config object. This is necessary to make sure that the paths are resolved correctly in your monorepo.

## Set the build `outDir` path

Make sure you set the `outDir` property on your `build` object. Set the path as relative to the workspace root, so for example if your project is located in `apps/my-app`, set the `outDir` to `../../dist/apps/my-app`. If your project is located in `my-app`, set the `outDir` to `../dist/my-app`, etc.

## DTS plugin

If you are building a library, you need to use the [`vite-plugin-dts` plugin](https://www.npmjs.com/package/vite-plugin-dts) to generate the `.d.ts` files for your library.

### Skip diagnostics

If you are building a library, you can set the `skipDiagnostics` option to `true` to speed up the build. This means that type diagnostic will be skipped during the build process. However, if there are some files with type errors which interrupt the build process, these files will not be emitted and `.d.ts` declaration files will not be generated.

If you choose to skip diagnostics, here is what your `'vite-plugin-dts'` plugin setup will look like:

```ts
// libs/my-lib/vite.config.ts
...
import dts from 'vite-plugin-dts';
import { join } from 'path';
...
...
export default defineConfig({
  plugins: [
    ...,
    dts({
      entryRoot: 'src',
      tsConfigFilePath: join(__dirname, 'tsconfig.lib.json'),
      skipDiagnostics: true,
    }),
```

### Do not skip diagnostics

If you are building a library, and you want to make sure that all the files are type checked, you can set the `skipDiagnostics` option to `false` to make sure that all the files are type checked. This means that type diagnostic will be run during the build process.

If you choose to enable diagnostics, here is what your `'vite-plugin-dts'` plugin setup will look like:

```ts
// libs/my-lib/vite.config.ts
...
import dts from 'vite-plugin-dts';
...
...
export default defineConfig({
  plugins: [
    ...,
    dts({
      root: '../../',
      entryRoot: 'libs/my-lib/src',
      tsConfigFilePath: 'libs/my-lib/tsconfig.lib.json',
      include: ['libs/my-lib/src/**/*.ts'],
      outputDir: 'dist/libs/my-lib',
      skipDiagnostics: false,
    }),
```

You can read more about the configuration options in the [`vite-plugin-dts` plugin documentation](https://www.npmjs.com/package/vite-plugin-dts).

## Copying assets

If you have assets outside of [`publicDir`](https://vite.dev/config/shared-options.html#publicdir) that need to be copied the output folder, then you can use `nxCopyAssetsPlugin` from `@nx/vite`.

```ts
// vite.config.ts
/// <reference types='vitest' />
import { defineConfig } from 'vite';
// ...
import { nxCopyAssetsPlugin } from '@nx/vite/plugins/nx-copy-assets.plugin';

export default defineConfig({
  root: __dirname,
  cacheDir: '../../node_modules/.vite/libs/testlib',

  plugins: [
    nxViteTsPaths(),
    nxCopyAssetsPlugin(['*.md']),
    dts({
      entryRoot: 'src',
      tsconfigPath: path.join(__dirname, 'tsconfig.lib.json'),
    }),
  ],
  // ...
});
```

## For testing

If you're using `vitest`, make sure your `test` object in your `vite.config.ts` file looks like this:

```ts
...
  test: {
    globals: true,
    cache: {
      dir: '../node_modules/.vitest/<project-root>',
    },
    environment: 'jsdom',
    include: ['src/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
    reporters: ['default'],
    coverage: {
      reportsDirectory: '../coverage/<project-root>',
      provider: 'v8',
    },
  },
...
```

Note how we're specifying `reporters` and `environment`.

## What your `vite.config.ts` looks like

### For applications

Add a `vite.config.ts` file to the root of your project. If you are not using React, you can skip adding the `react` plugin, of course.

```ts
// apps/my-app/vite.config.ts
/// <reference types='vitest' />
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';

export default defineConfig({
  root: __dirname,
  build: {
    outDir: '../../dist/apps/my-app',
    reportCompressedSize: true,
    commonjsOptions: {
      transformMixedEsModules: true,
    },
  },
  cacheDir: '../../node_modules/.vite/apps/my-app',
  server: {
    port: 4200,
    host: 'localhost',
  },

  preview: {
    port: 4300,
    host: 'localhost',
  },

  plugins: [react(), nxViteTsPaths()],

  test: {
    reporters: ['default'],
    coverage: {
      reportsDirectory: '../../coverage/apps/my-app',
      provider: 'v8',
    },
    globals: true,
    cache: {
      dir: '../../node_modules/.vitest/apps/my-app',
    },
    environment: 'jsdom',
    include: ['src/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
  },
});
```

### For libraries

If you are setting up a library (rather than an application) to use Vite, your `vite.config.ts` file should look like this:

```ts
// libs/my-lib/vite.config.ts
/// <reference types='vitest' />
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import dts from 'vite-plugin-dts';
import * as path from 'path';
import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';

export default defineConfig({
  root: __dirname,
  cacheDir: '../node_modules/.vite/my-lib',
  plugins: [
    react(),
    nxViteTsPaths(),
    dts({
      entryRoot: 'src',
      tsConfigFilePath: path.join(__dirname, 'tsconfig.lib.json'),
      skipDiagnostics: true,
    }),
  ],
  // Configuration for building your library.
  // See: https://vite.dev/guide/build.html#library-mode
  build: {
    outDir: '../dist/libs/my-lib',
    reportCompressedSize: true,
    commonjsOptions: {
      transformMixedEsModules: true,
    },
    lib: {
      // Could also be a dictionary or array of multiple entry points.
      entry: 'src/index.ts',
      name: 'my-lib',
      fileName: 'index',
      // Change this to the formats you want to support.
      // Don't forget to update your package.json as well.
      formats: ['es'],
    },
    rollupOptions: {
      // External packages that should not be bundled into your library.
      external: ['react', 'react-dom', 'react/jsx-runtime'],
    },
  },
  test: {
    globals: true,
    cache: {
      dir: '../node_modules/.vitest/libs/my-lib',
    },
    environment: 'jsdom',
    include: ['src/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
    reporters: ['default'],
    coverage: {
      reportsDirectory: '../coverage/libs/my-lib',
      provider: 'v8',
    },
  },
});
```

In that config file, you can configure Vite as you would normally do. For more information, see the [Vite documentation](https://vite.dev/config/).

## Set up file replacements

You can use the `replaceFiles()` plugin (`@nx/vite/plugins/rollup-replace-files.plugin`) to replace files in your build. You can import the plugin from `@nx/vite/plugins/rollup-replace-files.plugin`. And you can set it up like this:

```ts
// apps/my-app/vite.config.ts
...
import { replaceFiles } from '@nx/vite/plugins/rollup-replace-files.plugin';

export default defineConfig({
  ...

  plugins: [
    ...
    replaceFiles([
      {
        replace: 'apps/my-app/src/environments/environment.ts',
        with: 'apps/my-app/src/environments/environment.prod.ts',
      },
    ]),
  ],

  ...
});
```

---
<!-- source: https://nx.dev/docs/technologies/build-tools/vite/introduction.md -->
## Vite Plugin for Nx

[Vite](https://vite.dev/) is a fast build tool and dev server for modern web apps.

The `@nx/vite` plugin adds [inferred targets](#configuration) and [project configuration generators](#setup).

{% aside type="note" title="Vitest is now in @nx/vitest" %}
Starting with Nx v22, Vitest support has moved to the dedicated [`@nx/vitest` plugin](/docs/technologies/test-tools/vitest/introduction). In Nx v21 and prior, `@nx/vite` contained what is now in `@nx/vitest`. If you are upgrading, see the [migration guide](/docs/technologies/test-tools/vitest/guides/migrating-from-nx-vite).
{% /aside %}

You can use Vite with Nx without the plugin and still get [task caching](/docs/features/cache-task-results), [task orchestration](/docs/features/run-tasks), and the [project graph](/docs/features/explore-graph).

## Requirements

The `@nx/vite` plugin supports the following package versions.

| Package | Supported Versions                         |
| ------- | ------------------------------------------ |
| `vite`  | ^5.0.0 \|\| ^6.0.0 \|\| ^7.0.0 \|\| ^8.0.0 |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

## Setup

### Add to an existing workspace

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/vite` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
Using `nx add` helps ensure the correct version is installed and configured.
{% /aside %}

Install the plugin:

```shell
nx add @nx/vite
```

Configure an existing project to use Vite:

```shell
nx g @nx/vite:configuration --project=my-app
```

Verify inferred tasks in the project details view:

```shell
nx show project my-app --web
```

Replace `my-app` with your project name.

### Create a new workspace

Use a framework preset and keep the setup minimal:

{% tabs syncKey="framework" %}
{% tabitem label="React" %}

```shell
npx create-nx-workspace@latest --preset=react-standalone --bundler=vite
```

{% /tabitem %}
{% tabitem label="Web" %}

```shell
npx create-nx-workspace@latest --preset=web-components --bundler=vite
```

{% /tabitem %}
{% /tabs %}

For the full framework workflows, see the [React introduction](/docs/technologies/react/introduction) or [Web app reference](/docs/reference/web).

## Local development

- `nx dev my-app` starts the Vite dev server for the project (same as the deprecated `serve` target).
- `nx build my-app` creates a production build in `dist/` (controlled by `build.outDir` in `vite.config.*`) and registers the outputs for Nx caching.
- `nx preview my-app` serves the production build using Vite preview (runs after `build`).
- `nx serve-static my-app` serves the built assets from `dist/` for quick smoke tests.
- `nx typecheck my-app` runs TypeScript typechecking when a `tsconfig*.json` exists in the project.

Replace `my-app` with your project name.

## Configuration

### Configure task inference

The `@nx/vite` plugin infers tasks by reading Vite config files. Any of the following config files will be picked up:

- `vite.config.js`
- `vite.config.ts`
- `vite.config.mjs`
- `vite.config.mts`
- `vite.config.cjs`
- `vite.config.cts`

Build targets are only created when the project is buildable. A project is treated as buildable when any of the following are true:

- `build.lib` is set in `vite.config.*`
- `build.rollupOptions.input` or `build.rolldownOptions.input` is set (Vite 8 uses `rolldownOptions`)
- `builder.buildApp` is set
- an `index.html` file exists at the project root

Dev, preview, and serve-static targets are created for buildable projects. If you are in library mode (`build.lib`), these targets are skipped unless you explicitly configure a dev server (e.g. `server.host` or `server.port`).

Typecheck targets are created when a `tsconfig*.json` file exists in the project.

### Plugin options

Configure `@nx/vite/plugin` in the `plugins` array in `nx.json`:

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/vite/plugin",
      "options": {
        "buildTargetName": "build",
        "previewTargetName": "preview",
        "serveTargetName": "serve",
        "devTargetName": "dev",
        "serveStaticTargetName": "serve-static",
        "typecheckTargetName": "typecheck",
        "buildDepsTargetName": "build-deps",
        "watchDepsTargetName": "watch-deps"
      }
    }
  ]
}
```

`serveTargetName` is deprecated; use `devTargetName` instead. `buildDepsTargetName` and `watchDepsTargetName` create targets that build or watch project dependencies.

| Option                  | Description                                          | Default        |
| ----------------------- | ---------------------------------------------------- | -------------- |
| `buildTargetName`       | Name of the Vite build target                        | `build`        |
| `previewTargetName`     | Name of the Vite preview target                      | `preview`      |
| `serveTargetName`       | Name of the deprecated Vite serve target             | `serve`        |
| `devTargetName`         | Name of the Vite dev server target                   | `dev`          |
| `serveStaticTargetName` | Name of the static file server target                | `serve-static` |
| `typecheckTargetName`   | Name of the typecheck target                         | `typecheck`    |
| `buildDepsTargetName`   | Name of the build-deps target for dependency builds  | none           |
| `watchDepsTargetName`   | Name of the watch-deps target for dependency watches | none           |

### Disable or scope inference

To stop inference for a specific project, exclude its config file with `include`/`exclude` filters in `nx.json`:

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/vite/plugin",
      "exclude": ["apps/legacy/**"]
    }
  ]
}
```

To avoid specific targets, adjust the config files that trigger them. For example, remove `tsconfig*.json` to stop `typecheck`, or use library mode (`build.lib`) to skip `dev`, `preview`, and `serve-static` unless you set dev server options.

### View inferred tasks

To see what tasks Nx inferred for a project, open the [project details view](/docs/concepts/inferred-tasks) in Nx Console or run:

```shell
nx show project my-app --web
```

## CI and scale

Use Nx to keep CI fast in large monorepos:

- Run only affected Vite projects: `nx affected -t build,typecheck`.
- Enable remote caching with [Nx Cloud](/docs/guides/nx-cloud/setup-ci) using `nx connect`.
- Follow the [CI setup guide](/docs/guides/nx-cloud/setup-ci) for a full pipeline.

## What's next

{% cardgrid %}
{% linkcard title="Configure Vite" description="Set up Vite config, Nx-specific plugins, and recommended defaults." href="/docs/technologies/build-tools/vite/guides/configure-vite" /%}
{% linkcard title="React with Nx" description="Learn the React workflow in an Nx monorepo and how Vite fits." href="/docs/technologies/react/introduction" /%}
{% linkcard title="Vue with Nx" description="See the Vue workflow in Nx and where Vite is used." href="/docs/technologies/vue/introduction" /%}
{% linkcard title="Vitest with Nx" description="Add and run Vitest tests, including CI-friendly patterns." href="/docs/technologies/test-tools/vitest/introduction" /%}
{% linkcard title="Vite Generators" description="Browse all Vite generator options for configuration and testing." href="/docs/technologies/build-tools/vite/generators" /%}
{% linkcard title="Vite Executors" description="Browse all Vite executor options for dev and build." href="/docs/technologies/build-tools/vite/executors" /%}
{% /cardgrid %}

---
<!-- source: https://nx.dev/docs/technologies/build-tools/vite/migrations.md -->
## @nx/vite Migrations

The @nx/vite plugin provides various migrations to help you migrate to newer versions of vite projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 22.2.x

### `update-22-2-0`
**Version**: 22.2.0-beta.1

Create AI Instructions to help migrate users workspaces past breaking changes for Vitest 4.

#### Requires

| Name | Version |
|------|---------|
 `vitest` | `>=4.0.0` |

### `migrate-vitest-to-vitest-package`
**Version**: 22.2.0-beta.2

Migrate Vitest usage from @nx/vite to @nx/vitest package.


### 22.2.0-package-updates
**Version**: 22.2.0-beta.1


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `vitest` | `^4.0.0` | Updated only
| `@vitest/coverage-v8` | `^4.0.0` | Updated only
| `@vitest/coverage-istanbul` | `^4.0.0` | Updated only
| `@vitest/ui` | `^4.0.0` | Updated only


### 22.2.0-analog-package-updates
**Version**: 22.2.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@analogjs/vite-plugin-angular` | `~2.1.2` | Updated only
| `@analogjs/vitest-angular` | `~2.1.2` | Updated only



## 21.5.x

### 21.5.0-package-updates
**Version**: 21.5.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `vite` | `^7.1.3` | Updated only



## 21.3.x

### 21.3.0-package-updates
**Version**: 21.3.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@analogjs/vite-plugin-angular` | `~1.19.1` | Updated only
| `@analogjs/vitest-angular` | `~1.19.1` | Updated only



## 21.2.x

### 21.2.0-package-updates
**Version**: 21.2.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@analogjs/vite-plugin-angular` | `~1.17.1` | Updated only
| `@analogjs/vitest-angular` | `~1.17.1` | Updated only



## 21.1.x

### 21.1.2-package-updates
**Version**: 21.1.2-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@analogjs/vitest-angular` | `~1.16.1` | Updated only



## 20.7.x

### 20.7.1-package-updates
**Version**: 20.7.1-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@analogjs/vite-plugin-angular` | `~1.14.1` | Updated only
| `@analogjs/vitest-angular` | `~1.14.1` | Updated only



## 20.5.x

### `update-20-5-0-install-jiti`
**Version**: 20.5.0-beta.2

Install jiti as a devDependency to allow vite to parse TS postcss files.

#### Installs the `jiti` package

This migration ensures that the [`jiti`](https://github.com/unjs/jiti) package is installed.  
This is a requirement for Vite to parse `postcss` configuration files that use TypeScript.

Learn more: [https://vite.dev/guide/migration#postcss-load-config](https://vite.dev/guide/migration#postcss-load-config)



### `update-20-5-0-update-resolve-conditions`
**Version**: 20.5.0-beta.3

Update resolve.conditions to include defaults that are no longer provided by Vite.

#### Update `resolve.conditions` to include defaults

In previous Vite versions, the `resolve.conditions` option had defaults that were added internally (i.e. `['module', 'browser', 'development|production']`).  
This default was removed in Vite 6, so this migration adds it to your existing configuration to ensure that the behavior remains intact.

Learn more: [https://vite.dev/guide/migration#default-value-for-resolve-conditions](https://vite.dev/guide/migration#default-value-for-resolve-conditions)

:::note[Remix]
Remix does not currently support Vite 6 and therefore any `vite.config` file for Remix will not be migrated.
:::

#### Sample Code Changes

##### Before

```typescript title="vite.config.ts"
import { defineConfig } from 'vite';

export default defineConfig({
  resolve: {
    conditions: ['require'],
  },
  build: {
    outDir: 'dist',
  },
});
```

##### After

```typescript title="vite.config.ts" {4-6}
import { defineConfig } from 'vite';

export default defineConfig({
  resolve: {
    conditions: ['require', 'module', 'browser', 'development|production'],
  },
  build: {
    outDir: 'dist',
  },
});
```



### `eslint-ignore-vite-temp-files`
**Version**: 20.5.0-beta.3

Add vite config temporary files to the ESLint configuration ignore patterns if ESLint is used.

#### Sample Code Changes

Add `vite.config.*.timestamp*` and `vitest.config.*.timestamp*` to the root `eslint.config.mjs` file (using **ESLint Flat Config**).

##### Before

```js title="eslint.config.mjs"
export default [
  {
    ignores: ['dist'],
  },
];
```

##### After

```js title="eslint.config.mjs" {3}
export default [
  {
    ignores: ['dist', 'vite.config.*.timestamp*', 'vitest.config.*.timestamp*'],
  },
];
```

Add `vite.config.*.timestamp*` and `vitest.config.*.timestamp*` to the project's `.eslintrc.json` file (using **eslintrc** format config).

##### Before

```json title="apps/app1/eslintrc.json"
{
  "ignorePatterns": ["!**/*"]
}
```

##### After

```json title="apps/app1/eslintrc.json" {4-5}
{
  "ignorePatterns": [
    "!**/*",
    "vite.config.*.timestamp*",
    "vitest.config.*.timestamp*"
  ]
}
```



### 20.5.0-package-updates
**Version**: 20.5.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `vite` | `^6.0.0` | Updated only
| `vite-plugin-dts` | `~4.5.0` | Updated only



## 20.0.x

### `update-20-0-4`
**Version**: 20.0.4-beta.0

Add gitignore entry for temporary vite config files.

#### Add Vite Temp Files to Git Ignore

Add gitignore entry for temporary vite config files.

#### Sample Code Changes

Adds the following entries to the `.gitignore` file.

```text title=".gitignore"
vite.config.*.timestamp*
vitest.config.*.timestamp*
```



### `update-20-0-6`
**Version**: 20.0.6-beta.0

Add gitignore entry for temporary vite config files and remove previous incorrect glob.

#### Add Vite Temp Files to Git Ignore

Add gitignore entry for temporary vite config files.

#### Sample Code Changes

Adds the following entries to the `.gitignore` file.

```text title=".gitignore"
vite.config.*.timestamp*
vitest.config.*.timestamp*
```

---
<!-- source: https://nx.dev/docs/technologies/build-tools/webpack.md -->
## Webpack

{% index_page_cards path="technologies/build-tools/webpack" /%}

---
<!-- source: https://nx.dev/docs/technologies/build-tools/webpack/executors.md -->
## @nx/webpack Executors

The @nx/webpack plugin provides various executors to help you create and configure webpack projects within your Nx workspace.
Below is a complete reference for all available executors and their options.

### `dev-server`
Serve an application using webpack.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `allowedHosts` | string | This option allows you to whitelist services that are allowed to access the dev server. |  |
| `baseHref` | string | Base url for the application being built. |  |
| `buildTarget` | string | Target which builds the application. |  |
| `hmr` | boolean | Enable hot module replacement. | `false` |
| `host` | string | Host to listen on. | `"localhost"` |
| `liveReload` | boolean | Whether to reload the page on change, using live-reload. | `true` |
| `memoryLimit` | number | Memory limit for type checking service process in `MB`. |  |
| `open` | boolean | Open the application in the browser. | `false` |
| `port` | number | Port to listen on. | `4200` |
| `publicHost` | string | Public URL where the application will be served. |  |
| `ssl` | boolean | Serve using `HTTPS`. | `false` |
| `sslCert` | string | SSL certificate to use for serving `HTTPS`. |  |
| `sslKey` | string | SSL key to use for serving `HTTPS`. |  |
| `watch` | boolean | Watches for changes and rebuilds application. | `true` |

### `ssr-dev-server`
Serve a SSR application using webpack.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `browserTarget` | string [**required**] | Target which builds the browser application. |  |
| `serverTarget` | string [**required**] | Target which builds the server application. |  |
| `browserTargetOptions` | object | Additional options to pass into the browser build target. | `{}` |
| `port` | number | The port to be set on `process.env.PORT` for use in the server. | `4200` |
| `serverTargetOptions` | object | Additional options to pass into the server build target. | `{}` |

### `webpack`
Build a project using webpack.

`project.json`:

```json5
//...
"my-app": {
  "targets": {
    "build": {
      "executor": "@nx/webpack:webpack",
      "options": {
        "webpackConfig": "apps/my-app/webpack.config.js"
      }
    },
    //...
  }
}
```

```bash
nx build my-app
```

### Examples

###### Using `babelUpwardRootMode`

Copying from the [Babel documentation](https://babeljs.io/docs/config-files#root-babelconfigjson-file):

> [...] if you are running your Babel compilation process from within a subpackage, you need to tell Babel where to look for the config. There are a few ways to do that, but the recommended way is the "rootMode" option with "upward", which will make Babel search from the working directory upward looking for your babel.config.json file, and will use its location as the "root" value.

Setting `babelUpwardRootMode` to `true` in your `project.json` will set `rootMode` option to `upward` in the Babel config. You may want the `upward` mode in a monorepo when projects must apply their individual `.babelrc` file. We recommend that you don't set it at all, so it will use the default to `false` as the `upward` mode brings additional complexity to the build process.

```json5
//...
"my-app": {
  "targets": {
    "build": {
      "executor": "@nx/webpack:webpack",
      "options": {
        "webpackConfig": "apps/my-app/webpack.config.js",
        "babelUpwardRootMode": true
      }
    },
    //...
  }
}
```

When `babelUpwardRootMode` is `true`, Babel will look for a root `babel.config.json` at the root of the workspace, which should look something like this to include all packages:

```json
{ "babelrcRoots": ["*"] }
```

Then for each package, you must have a `.babelrc` file that will be applied to that package. For example:

```json
{
  "presets": ["@babel/preset-env", "@babel/preset-typescript"]
}
```

All packages will use its own `.babelrc` file, thus you must ensure the right presets and plugins are set in each config file. This behavior can lead to build discrepancies between packages, so we recommend that you don't set `babelUpwardRootMode` at all.

```text
├── apps
│   └── demo
│       └── .babelrc
├── libs
│   ├── a
│   │   └── .babelrc
│   └── b
│       └── .babelrc
└── babel.config.json
```

In workspace above, if `demo` imports `a` and `b`, it will apply the config `libs/a/.babelrc` and `libs/b/.babelrc` to the respective packages and not apply its own `apps/demo/.babelrc` to `a` and `b`. Anything in `babel.config.json` will apply to all packages.

###### Specify a custom Babel config file

If you have a custom Babel config file (i.e. not `.babelrc`), you can use the `configFile` option as follows:

```json5
//...
"my-app": {
  "targets": {
    "build": {
      "executor": "@nx/webpack:webpack",
      "options": {
        "webpackConfig": "apps/my-app/webpack.config.js",
        "babelConfig": "apps/my-app/.babelrc.custom.json",
      }
    },
    // ...
  }
}
```

If you do not set the path to the `.babelrc` file, Nx will look for a `.babelrc` file in the root of your application.

Note that this option does not work if `babelUpwardRootMode` is set to `true`.

###### Run webpack with `isolatedConfig`

Setting `isolatedConfig` to `true` in your `project.json` file means that Nx will not apply the Nx webpack plugins automatically. In that case, the Nx plugins need to be applied in the project's `webpack.config.js` file (e.g. `withNx`, `withReact`, etc.). So don't forget to also specify the path to your webpack config file (using the `webpackConfig` option).

Read more on how to configure Webpack in our [Nx Webpack config guide](/recipes/webpack/webpack-config-setup) an in our [Webpack Plugins guide](/recipes/webpack/webpack-plugins).

Note that this is the new default setup for webpack in the latest version of Nx.

Set `isolatedConfig` to `true` in your `project.json` file in the `build` target options like this:

```json
//...
"my-app": {
  "targets": {
    "build": {
      "executor": "@nx/webpack:webpack",
      "options": {
        "webpackConfig": "apps/my-app/webpack.config.js",
        "isolatedConfig": true
      }
    },
  }
}
```

###### Configuring type checking

You can configure type checking behavior using the `typeCheckOptions` option. By default, type checking runs asynchronously (non-blocking).

```json5
//...
"my-app": {
  "targets": {
    "build": {
      "executor": "@nx/webpack:webpack",
      "options": {
        "webpackConfig": "apps/my-app/webpack.config.js",
        // Run type checking asynchronously (non-blocking)
        "typeCheckOptions": { "async": true }
      }
    },
    //...
  }
}
```

To disable type checking entirely:

```json5
//...
"my-app": {
  "targets": {
    "build": {
      "executor": "@nx/webpack:webpack",
      "options": {
        "webpackConfig": "apps/my-app/webpack.config.js",
        "typeCheckOptions": false
      }
    },
    //...
  }
}
```

###### Adding runtime dependencies to generated package.json

When using `generatePackageJson`, you can add additional runtime dependencies that should be included in the generated `package.json` file. This is useful for Docker installs where you need dependencies that aren't detected automatically:

```json5
//...
"my-app": {
  "targets": {
    "build": {
      "executor": "@nx/webpack:webpack",
      "options": {
        "webpackConfig": "apps/my-app/webpack.config.js",
        "generatePackageJson": true,
        "runtimeDependencies": ["pg", "redis"]
      }
    },
    //...
  }
}
```
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `additionalEntryPoints` | array |  |  |
| `assets` | array | List of static application assets. |  |
| `babelConfig` | string | Path to the babel configuration file of your project. If not provided, Nx will default to the .babelrc file at the root of your project. See https://babeljs.io/docs/en/config-files |  |
| `babelUpwardRootMode` | boolean | Whether to set rootmode to upward. See https://babeljs.io/docs/en/options#rootmode |  |
| `baseHref` | string | Base url for the application being built. |  |
| `buildLibsFromSource` | boolean | Read buildable libraries from source instead of building them separately. If set to `false`, the `tsConfig` option must also be set to remap paths. | `true` |
| `cache` | string | Configure webpack caching behavior. When not specified, defaults to `{ type: 'memory' }` for Node targets in watch mode, and `undefined` otherwise. |  |
| `commonChunk` | boolean | Use a separate bundle containing code used across multiple bundles. |  |
| `compiler` | string | The compiler to use. |  |
| `crossOrigin` | string | The `crossorigin` attribute to use for generated javascript script tags.  One of 'none' | 'anonymous' | 'use-credentials'. |  |
| `deployUrl` | string | URL where the application will be deployed. |  |
| `externalDependencies` | string | Dependencies to keep external to the bundle. (`all` (default), `none`, or an array of module names) |  |
| `extractCss` | boolean | Extract CSS into a `.css` file. |  |
| `extractLicenses` | boolean | Extract all licenses in a separate file, in the case of production builds only. |  |
| `fileReplacements` | array | Replace files with other files in the build. |  |
| `generateIndexHtml` | boolean | Generates `index.html` file to the output path. This can be turned off if using a webpack plugin to generate HTML such as `html-webpack-plugin`. |  |
| `generatePackageJson` | boolean | Generates a `package.json` and pruned lock file with the project's `node_module` dependencies populated for installing in a container. If a `package.json` exists in the project's directory, it will be reused with dependencies populated. |  |
| `index` | string | HTML File which will be contain the application. |  |
| `main` | string | The name of the main entry-point file. |  |
| `memoryLimit` | number | Memory limit for type checking service process in `MB`. |  |
| `namedChunks` | boolean | Names the produced bundles according to their entry file. |  |
| `optimization` | string | Enables optimization of the build output. |  |
| `outputFileName` | string | Name of the main output file. | `"main.js"` |
| `outputHashing` | string | Define the output filename cache-busting hashing mode. |  |
| `outputPath` | string | The output path of the generated files. |  |
| `poll` | number | Enable and define the file watching poll time period. |  |
| `polyfills` | string | Polyfills to load before application |  |
| `postcssConfig` | string | Set a path to PostCSS config that applies to the app and all libs. Defaults to `undefined`, which auto-detects postcss.config.js files in each `app`/`lib` directory. |  |
| `progress` | boolean | Log progress to the console while building. |  |
| `publicPath` | string | Set a public path for assets resources with absolute paths. |  |
| `rebaseRootRelative` | boolean | Whether to rebase absolute path for assets in postcss cli resources. |  |
| `runtimeChunk` | boolean | Use a separate bundle containing the runtime. |  |
| `runtimeDependencies` | array | Add runtime dependencies to the generated `package.json` file. Useful for Docker install. |  |
| `scripts` | array | External Scripts which will be included before the main application entry. |  |
| `skipOverrides` | boolean | Do not add a `overrides` and `resolutions` entries to the generated package.json file. Only works in conjunction with `generatePackageJson` option. |  |
| `skipPackageManager` | boolean | Do not add a `packageManager` entry to the generated package.json file. Only works in conjunction with `generatePackageJson` option. |  |
| `skipTypeChecking` | boolean | Skip the type checking. Default is `false`. |  |
| `sourceMap` | string | Output sourcemaps. Use 'hidden' for use with error reporting tools without generating sourcemap comment. |  |
| `standardWebpackConfigFunction` | boolean | Set to true if the webpack config exports a standard webpack function, not an Nx-specific one. See: https://webpack.js.org/configuration/configuration-types/#exporting-a-function | `false` |
| `statsJson` | boolean | Generates a 'stats.json' file which can be analyzed using tools such as: 'webpack-bundle-analyzer' or `<https://webpack.github.io/analyse>`. |  |
| `stylePreprocessorOptions` | object | Options to pass to style preprocessors. |  |
| `styles` | array | External Styles which will be included with the application |  |
| `subresourceIntegrity` | boolean | Enables the use of subresource integrity validation. |  |
| `target` | string | Target platform for the build, same as the Webpack target option. |  |
| `transformers` | array | List of TypeScript Compiler Transfomers Plugins. |  |
| `tsConfig` | string | The name of the Typescript configuration file. |  |
| `typeCheckOptions` | string | Configure type checking during the build. Set to `true` to enable with defaults (async: true). Set to `false` to disable type checking entirely. Use `{ async: true }` to run type checking in a separate process without blocking the build. Default is `{ async: true }`. |  |
| `vendorChunk` | boolean | Use a separate bundle containing only vendor libraries. |  |
| `verbose` | boolean | Emits verbose output |  |
| `watch` | boolean | Enable re-building when files change. |  |
| `webpackConfig` | string | Path to a function which takes a webpack config, some context and returns the resulting webpack config. See https://nx.dev/guides/customize-webpack |  |

---
<!-- source: https://nx.dev/docs/technologies/build-tools/webpack/generators.md -->
## @nx/webpack Generators

The @nx/webpack plugin provides various generators to help you create and configure webpack projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `convert-config-to-webpack-plugin`
Convert existing Webpack project(s) using `@nx/webpack:webpack` executor that uses `withNx` to use `NxAppWebpackPlugin`. Defaults to migrating all projects. Pass '--project' to migrate only one target.

**Usage:**
```bash
nx generate @nx/webpack:convert-config-to-webpack-plugin [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string | The project to convert from using the `@nx/webpack:webpack` executor and `withNx` plugin to use `NxAppWebpackPlugin`. |  |
| `--skipFormat` | boolean | Whether to format files at the end of the migration. | `false` |

## `convert-to-inferred`
Convert existing Webpack project(s) using `@nx/webpack:wepack` executor to use `@nx/webpack/plugin`.

**Usage:**
```bash
nx generate @nx/webpack:convert-to-inferred [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string | The project to convert from using the `@nx/webpack:webpack` executor to use `@nx/webpack/plugin`. If not provided, all projects using the `@nx/webpack:webpack` executor will be converted. |  |
| `--skipFormat` | boolean | Whether to format files. | `false` |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/webpack:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/build-tools/webpack/guides.md -->
## Guides

{% index_page_cards path="technologies/build-tools/webpack/guides" /%}

---
<!-- source: https://nx.dev/docs/technologies/build-tools/webpack/guides/webpack-config-setup.md -->
## Configure Webpack in your Nx workspace

You can configure Webpack using a [`webpack.config.js`](https://webpack.js.org/concepts/configuration/) file in your project. Nx infers the `build` and `serve` targets from your webpack configuration as long as you have `@nx/webpack/plugin` added to your `nx.json`.

```json5
// nx.json
"plugins": [
  {
    "plugin": "@nx/webpack/plugin",
    "options": {
      "buildTargetName": "build",
      "serveTargetName": "serve"
    }
  }
]
```

If you are using the [`@nx/webpack:webpack`](/docs/technologies/build-tools/webpack/executors#webpack) executor, the path to your webpack config is set in the `webpackConfig` option in your `project.json` file.

```json5 {% meta="{6}" %}
// project.json
"my-app": {
  "targets": {
    //...
    "build": {
      "executor": "@nx/webpack:webpack",
      "options": {
        "webpackConfig": "apps/my-app/webpack.config.js",
        //...
      },
      // ...
    },
  }
}
```

In the webpack config file, you can add the necessary configuration for Webpack. Read more on how to configure Webpack in the [Webpack documentation](https://webpack.js.org/concepts/configuration/).

## Basic and Nx-enhanced configuration files

Nx supports two flavors of Webpack configuration files:

1. [_Basic_](#basic-configuration-for-nx) (or standard) Webpack configuration. The file exports a Webpack config object, or one of the [standard configuration types](https://webpack.js.org/configuration/configuration-types).
2. [_Nx-enhanced_](#nxenhanced-configuration-with-composable-plugins) Webpack configuration. The file exports a function that takes in a Webpack configuration object, plus the [`@nx/webpack:webpack`](/docs/technologies/build-tools/webpack/executors#webpack) options and context, and returns an updated Webpack configuration object.

The basic configuration works with Webpack CLI, whereas the Nx-enhanced configuration requires the use of the `@nx/webpack:webpack` executor.

### Basic configuration for Nx

{% aside type="tip" title="Module federation support" %}
Currently, Nx module federation requires an enhanced Webpack configuration file and the use of the `withModuleFederation` plugin. See the next section for more details.
{% /aside %}

A basic Webpack configuration looks like this:

```js
// apps/demo/webpack.config.js
const { NxAppWebpackPlugin } = require('@nx/webpack/app-plugin');
const { join } = require('path');

module.exports = {
  output: {
    path: join(__dirname, '../../dist/apps/demo'),
  },
  devServer: {
    port: 4200,
  },
  plugins: [
    new NxAppWebpackPlugin({
      main: './src/main.ts',
      tsConfig: './tsconfig.app.json',
      index: './src/index.html',
      styles: ['./src/styles.css'],
      outputHashing: process.env['NODE_ENV'] === 'production' ? 'all' : 'none',
      optimization: process.env['NODE_ENV'] === 'production',
    }),
  ],
};
```

The [`NxAppWebpackPlugin`](/docs/technologies/build-tools/webpack/guides/webpack-plugins#nxappwebpackplugin) plugin takes a `main` entry file and produces a bundle in the output directory as defined in `output.path`. You can also pass the `index` option if it is a webapp, which will handle outputting scripts and stylesheets in the output file. `NxWebpackPlugin` is optional, and you can bring your own Webpack configuration without using it or any plugins from `@nx/webpack`.

For more information, see the [Webpack plugins guide](/docs/technologies/build-tools/webpack/guides/webpack-plugins).

### Nx-enhanced configuration with composable plugins

{% aside type="tip" title="Non-standard webpack config" %}
Nx-enhanced configuration, via `composePlugins` and [`withNx`](/docs/technologies/build-tools/webpack/guides/webpack-plugins#withnx) functions, requires the usage of `@nx/webpack:webpack` executor in your `project.json` file. This flavor of configuration does not work with the Webpack CLI.
{% /aside %}

Nx supports a function to be returned from the Webpack configuration file. This function is a composable plugin that is understood by the `@nx/webpack:webpack` executor. The enhanced configuration looks something like this:

```js
// apps/demo/webpack.config.js
const { composePlugins, withNx } = require('@nx/webpack');

module.exports = composePlugins(
  // Default Nx composable plugin
  withNx(),
  // Custom composable plugin
  (config, { options, context }) => {
    // `config` is the Webpack configuration object
    // `options` is the options passed to the `@nx/webpack:webpack` executor
    // `context` is the context passed to the `@nx/webpack:webpack` executor
    // customize configuration here
    return config;
  }
);
```

There are two advantages of this approach:

1. You can chain multiple plugins together using the `composePlugins` function. Each plugin can update the webpack configuration as needed.
2. You gain access to the target options and executor context within the webpack configuration file.

This gives you the ability to customize the Webpack configuration as needed, and make use of the options and context passed to the executor, as well.

#### Additional composable plugins for Nx

In addition to the `withNx` composable plugin, Nx provides other composable plugins such as `withWeb`, `withReact`, and `withModuleFederation`. You can read more about how these plugins work and how to use them in our [Webpack plugins guide](/docs/technologies/build-tools/webpack/guides/webpack-plugins).

## Customize your Webpack configuration

For most apps, the default configuration of Webpack is sufficient, but sometimes you need to tweak a setting in your Webpack config. The following sections show how to make a small change without taking on the maintenance burden of the entire webpack config.

### Configure Webpack for React projects

React projects use the `@nx/react` package to build their apps. This package provides `NxReactWebpackPlugin` and a `withReact` composable plugin that adds the necessary configuration for React to work with Webpack. The `NxReactWebpackPlugin` is used in a basic Webpack configuration file, whereas `withReact` is requires a Nx-enhanced Webpack configuration file.

{% tabs %}
{% tabitem label="Basic Webpack configuration" %}

```js
// apps/demo/app/webpack.config.js
const { NxAppWebpackPlugin } = require('@nx/webpack/app-plugin');
const { NxReactWebpackPlugin } = require('@nx/react/webpack-plugin');
const { join } = require('path');

module.exports = {
  output: {
    path: join(__dirname, '../../dist/apps/demo'),
  },
  devServer: {
    port: 4200,
  },
  plugins: [
    new NxAppWebpackPlugin({
      tsConfig: './tsconfig.app.json',
      compiler: 'swc',
      main: './src/main.tsx',
      index: '.src/index.html',
      styles: ['./src/styles.css'],
      outputHashing: process.env['NODE_ENV'] === 'production' ? 'all' : 'none',
      optimization: process.env['NODE_ENV'] === 'production',
    }),
    new NxReactWebpackPlugin({
      // Uncomment this line if you don't want to use SVGR
      // See: https://react-svgr.com/
      // svgr: false
    }),
  ],
};
```

{% /tabitem %}
{% tabitem label="Nx-enhanced Webpack configuration" %}

```js
// apps/demo/app/webpack.config.js
const { composePlugins, withNx } = require('@nx/webpack');
const { withReact } = require('@nx/react');

// Nx composable plugins for webpack.
module.exports = composePlugins(
  withNx(),
  withReact(),
  (config, { options, context }) => {
    // Update the webpack configuration as needed here.
    // e.g. config.plugins.push(new MyPlugin())
    return config;
  }
);
```

{% /tabitem %}

{% /tabs %}

### Configure Webpack for Module Federation

{% aside type="tip" title="Non-standard webpack config" %}
`composePlugins`, `withNx`, and `withModuleFederation` do not work with the Webpack CLI and requires the use of the `@nx/webpack:webpack` executor.
{% /aside %}

If you use the [Module Federation](/docs/technologies/module-federation/concepts/faster-builds-with-module-federation) support
from `@nx/angular` or `@nx/react` then
you can customize your Webpack configuration as follows.

```js
// apps/my-app/webpack.config.js
const { composePlugins, withNx } = require('@nx/webpack');
const { merge } = require('webpack-merge');
const withModuleFederation = require('@nx/react/module-federation');
// or `const withModuleFederation = require('@nx/angular/module-federation');`

module.exports = composePlugins(
  withNx(),
  async (config, { options, context }) => {
    const federatedModules = await withModuleFederation({
      // your options here
    });

    return merge(federatedModules(config, { options, context }), {
      // overwrite values here
    });
  }
);
```

Reference the [Webpack documentation](https://webpack.js.org/configuration/) for details on the structure of the Webpack
configuration object.

### Configure Webpack for Next.js Applications

Next.js supports Webpack customization in the `next.config.js` file.

```js
// next.config.js
const { withNx } = require('@nx/next/plugins/with-nx');

const nextConfig = {
  webpack: (
    config,
    { buildId, dev, isServer, defaultLoaders, nextRuntime, webpack }
  ) => {
    // Important: return the modified config
    return config;
  },
};

return withNx(nextConfig);
```

Read the [official documentation](https://nextjs.org/docs/api-reference/next.config.js/custom-webpack-config) for more details.

---
<!-- source: https://nx.dev/docs/technologies/build-tools/webpack/guides/webpack-plugins.md -->
## Webpack plugins

Nx provides two types of Webpack plugins:

1. [_Basic_](#basic-plugins) plugins that work in a
   standard [webpack configuration](https://webpack.js.org/configuration/) file.
2. [_Nx-enhanced_](#nxenhanced-plugins) plugins that work with
   the [`@nx/webpack:webpack`](/docs/technologies/build-tools/webpack/executors#webpack) executor.

The basic plugins integrate directly with the Webpack CLI.

For more information on webpack configuration and the
difference between basic and Nx-enhanced configuration, see
the [Webpack configuration guide](/docs/technologies/build-tools/webpack/guides/webpack-config-setup).

## Basic plugins

The basic plugins work with a standard webpack configuration file by adding them to the `plugins` option.

### NxAppWebpackPlugin

The `NxAppWebpackPlugin` plugin provides common configuration for the build, including TypeScript support and linking
workspace libraries (via tsconfig paths).

#### Options

##### tsConfig

Type: `string`

The tsconfig file for the project. e.g. `tsconfig.json`.

##### main

Type: `string`

The entry point for the bundle. e.g. `src/main.ts`.

##### additionalEntryPoints

Type: `Array<{ entryName: string; entryPath: string; }>`

Secondary entry points for the bundle.

#### assets

Type: `string[]`

Assets to be copied over to the output path.

##### babelConfig

Type: `string`

Babel configuration file if compiler is babel.

##### babelUpwardRootMode

Type: `boolean`
If true, Babel will look for a babel.config.json up the directory tree.

##### baseHref

Type: `string`

Set `<base href>` for the resulting index.html.

##### buildLibsFromSource

Type: `boolean`

Build the libraries from source. Default is `true`.

##### compiler

Type: `'babel' | 'swc' | 'tsc'`

The compiler to use. Default is `babel` and requires a `.babelrc` file.

##### crossOrigin

Type: `'none' | 'anonymous' | 'use-credentials'`

Set `crossorigin` attribute on the `script` and `link` tags.

##### deleteOutputPath

Type: `boolean`

Delete the output path before building.

**`Deprecated`**

Use [`output.clean`](https://webpack.js.org/guides/output-management/#cleaning-up-the-dist-folder) instead.

##### deployUrl

Type: `string`

The deploy path for the application. e.g. `/my-app/`

##### externalDependencies

Type: `'all' | 'none' | string[]`

Define external packages that will not be bundled. Use `all` to exclude all 3rd party packages, and `none` to bundle all
packages. Use an array to exclude specific packages from the bundle. Default is `none`.

##### extractCss

Type: `boolean`

Extract CSS as an external file. Default is `true`.

##### extractLicenses

Type: `boolean`
Extract licenses from 3rd party modules and add them to the output.

##### fileReplacements

Type: `FileReplacement[]`

Replace files at build time. e.g. `[{ "replace": "src/a.dev.ts", "with": "src/a.prod.ts" }]`

##### generateIndexHtml

Type: `boolean`

Generate an `index.html` file if `index.html` is passed. Default is `true`

##### generatePackageJson

Type: `boolean`

Generate a `package.json` file for the bundle. Useful for Node applications.

##### runtimeDependencies

Type: `string[]`

Add runtime dependencies to the generated `package.json` file. Useful for Docker installs. Only works in conjunction with `generatePackageJson` option.

##### index

Type: `string`

Path to the `index.html`.

##### memoryLimit

Type: `number`

Set the memory limit for the type-checking process. Default is `2048`.

##### namedChunks

Type: `boolean`

Use the source file name in output chunks. Useful for development or for Node.

##### optimization

Type: `boolean`

Optimize the bundle using Terser.

##### outputFileName

Type: `string`

Specify the output filename for the bundle. Useful for Node applications that use `@nx/js:node` to serve.

##### outputHashing

Type: `'none' | 'all'`

Use file hashes in the output filenames. Recommended for production web applications.

##### outputPath

Type: `string`

Override `output.path` in webpack configuration. This setting is not recommended and exists for backwards compatibility.

##### poll

Type: `number`

Override `watchOptions.poll` in webpack configuration. This setting is not recommended and exists for backwards
compatibility.

##### polyfills

Type: `string`

The polyfill file to use. Useful for supporting legacy browsers. e.g. `src/polyfills.ts`

##### postcssConfig

Type: `string`
Manually set the PostCSS configuration file. By default, PostCSS will look for `postcss.config.js` in the directory.

##### progress

Type: `boolean`

Display build progress in the terminal.

##### runtimeChunk

Type: `boolean`

Add an additional chunk for the Webpack runtime. Defaults to `true` when `target === 'web'`.

##### scripts

Type: `string[]`

External scripts that will be included before the main application entry.

##### skipOverrides

Type: `boolean`

Do not add a `overrides` and `resolutions` entries to the generated package.json file. Only works in conjunction with `generatePackageJson` option.

##### skipPackageManager

Type: `boolean`

Do not add a `packageManager` entry to the generated package.json file. Only works in conjunction with `generatePackageJson` option.

##### skipTypeChecking

Type: `boolean`

Skip type checking. Default is `false`.

**`Deprecated`**

Use [`typeCheckOptions`](#typecheckoptions) instead. This option will be removed in Nx 24.

##### typeCheckOptions

Type: `boolean | { async: boolean }`

Configure type checking during the build. Set to `true` to enable type checking with default options (async: true). Set to `false` to disable type checking entirely. Use `{ async: true }` to run type checking in a separate process without blocking the build. Use `{ async: false }` to run type checking synchronously. Default is `{ async: true }`.

##### sourceMap

Type: `boolean | 'hidden'`

Generate source maps.

##### ssr

Type: `boolean`

When `true`, `process.env.NODE_ENV` will be excluded from the bundle. Useful for building a web application to run in a
Node environment.

##### statsJson

Type: `boolean`

Generate a `stats.json` file which can be analyzed using tools such as `webpack-bundle-analyzer`.

##### stylePreprocessorOptions

Type: `object`

Options for the style preprocessor. e.g. `{ "includePaths": [] }` for SASS.

##### styles

Type: `string[]`

External stylesheets that will be included with the application.

##### subresourceIntegrity

Type: `boolean`

Enables the use of subresource integrity validation.

##### target

Type: `string | string[]`

Override the `target` option in webpack configuration. This setting is not recommended and exists for backwards
compatibility.

##### transformers

Type: `TransformerEntry[]`

List of TypeScript Compiler Transformers Plugins.

##### vendorChunk

Type: `boolean`

Generate a separate vendor chunk for 3rd party packages.

##### verbose

Type: `boolean`

Log additional information for debugging purposes.

##### watch

Type: `boolean`

Watch for file changes.

##### watchDependencies

Type: `boolean`

Watch for buildable dependencies and rebuild when they change. Default is `true`.

#### Example

```js
const { NxAppWebpackPlugin } = require('@nx/webpack/app-plugin');
const { join } = require('path');

module.exports = {
  output: {
    path: join(__dirname, '../../dist/apps/demo'),
  },
  devServer: {
    port: 4200,
  },
  plugins: [
    new NxAppWebpackPlugin({
      main: './src/main.ts',
      tsConfig: './tsconfig.app.json',
      index: './src/index.html',
      styles: ['./src/styles.css'],
      outputHashing: process.env['NODE_ENV'] === 'production' ? 'all' : 'none',
      optimization: process.env['NODE_ENV'] === 'production',
    }),
  ],
};
```

### NxReactWebpackPlugin

#### Options

##### svgr

Type: `boolean`

Enables or disables [React SVGR](https://react-svgr.com/). Default is `true`.

**Deprecated:** Add SVGR support in your Webpack configuration without relying on Nx. This option will be removed in Nx 22. See https://react-svgr.com/docs/webpack/

#### Example

```js
const { NxReactWebpackPlugin } = require('@nx/react/webpack-plugin');
const { join } = require('path');

module.exports = {
  // ...
  plugins: [
    new NxReactWebpackPlugin({
      svgr: false,
    }),
  ],
};
```

## Nx-enhanced plugins

The Nx-enhanced plugins work with `@nx/webpack:webpack` executor and receive the target options and context from the
executor. These are used when using [Module Federation](/docs/technologies/module-federation/concepts/module-federation-and-nx).

The plugins are used in conjunction with `composePlugins` utility to generate a final Webpack configuration object, once all of the plugins have applied their changes.

```js
// webpack.config.js
const { composePlugins } = require('@nx/webpack');

function myCustomPlugin() {
  // `options` and `context` are the target options and
  // `@nx/webpack:webpack` executor context respectively.
  return (webpackConfig, { options, context }) => {
    // Do something with the config.
    return webpackConfig;
  };
}

module.export = composePlugins(withNx(), withReact(), myCustomPlugin());
```

### withNx

The `withNx` plugin provides common configuration for the build, including TypeScript support and linking workspace
libraries (via tsconfig paths).

#### Options

##### skipTypeChecking

Type: `boolean`

Disable type checks (useful to speed up builds).

**`Deprecated`**

Use [`typeCheckOptions`](#typecheckoptions-1) instead. This option will be removed in Nx 24.

##### typeCheckOptions

Type: `boolean | { async: boolean }`

Configure type checking during the build. Set to `true` to enable type checking with default options (async: true). Set to `false` to disable type checking entirely. Use `{ async: true }` to run type checking in a separate process without blocking the build. Use `{ async: false }` to run type checking synchronously. Default is `{ async: true }`.

#### Example

```js
const { composePlugins, withNx } = require('@nx/webpack');

module.exports = composePlugins(withNx(), (config) => {
  // Further customize webpack config
  return config;
});
```

### withWeb

The `withWeb` plugin adds support for CSS/SASS/Less stylesheets, assets (such as images and fonts), and `index.html`
processing.

#### Options

##### baseHref

Type: `string`

Base URL for the application being built.

##### crossOrigin

Type: `'none' | 'anonymous' | 'use-credentials'`

"The `crossorigin` attribute to use for generated javascript script tags. One of 'none' | 'anonymous' | '
use-credentials'."

##### deployUrl

Type: `string`

URL where the application will be deployed.

##### extractCss

Type: `boolean`

Extract CSS into a `.css` file.

#### generateIndexHtml

Type: `boolean`

Generates `index.html` file to the output path. This can be turned off if using a webpack plugin to generate HTML such
as `html-webpack-plugin`.

##### index

Type: `string`

HTML File which will be contain the application.

##### postcssConfig

Type: `string`

Set a path (relative to workspace root) to a PostCSS config that applies to the app and all libs. Defaults
to `undefined`, which auto-detects postcss.config.js files in each `app`.

##### scripts

Type: `string[]`

Paths to scripts (relative to workspace root) which will be included before the main application entry.

##### stylePreprocessorOptions

Type: `{ includePaths: string[] }`

Options to pass to style preprocessors. `includePaths` is a list of paths that are included (e.g. workspace libs with
stylesheets).

##### styles

Type: `string[]`

Paths to stylesheets (relative to workspace root) which will be included with the application.

##### subresourceIntegrity

Type: `boolean`

Enables the use of subresource integrity validation.

### Example

```js
const { composePlugins, withNx, withWeb } = require('@nx/webpack');

module.exports = composePlugins(
  // always pass withNx() first
  withNx(),
  // add web functionality
  withWeb({
    styles: ['my-app/src/styles.css'],
  }),
  (config) => {
    // Further customize webpack config
    return config;
  }
);
```

### withReact

The `withReact` plugin adds support for React JSX, [SVGR](https://react-svgr.com/),
and [Fast Refresh](https://github.com/pmmmwh/react-refresh-webpack-plugin)

#### Options

The options are the same as [`withWeb`](#withweb) plus the following.

##### svgr

Type: `undefined|false`

SVGR allows SVG files to be imported as React components. Set this to `false` to disable this behavior.

#### Example

```js
const { composePlugins, withNx } = require('@nx/webpack');
const { withReact } = require('@nx/react');

module.exports = composePlugins(
  withNx(), // always pass withNx() first
  withReact({
    styles: ['my-app/src/styles.css'],
    svgr: false,
    postcssConfig: 'my-app/postcss',
  }),
  (config) => {
    // Further customize webpack config
    return config;
  }
);
```

### withModuleFederation and withModuleFederationForSSR

The `withModuleFederation` and `withModuleFederationForSSR` plugins add module federation support to the webpack build.
These plugins use
[`ModuleFederationPlugin`](https://webpack.js.org/technologies/module-federation/concepts/) and provide a simpler API through Nx.

For more information, refer to
the [Module Federation recipe](/docs/technologies/module-federation/concepts/faster-builds-with-module-federation).

#### Options

Both `withModuleFederation` and `withModuleFederationForSSR` share the same options. The `withModuleFederation` plugin
is for the browser, and the `withModuleFederationForSSR` plugin is used on the server-side (Node).

##### name

Type: `string`

The name of the host/remote application.

##### remotes

Type: `Aray<string[] | [remoteName: string, remoteUrl: string]>`

For _host_ to specify all _remote_ applications. If a string is used, Nx will match it with a matching remote in the
workspace.

Use `[<name>, <url>]` to specify the exact URL of the remote, rather than what's in the remote's `project.json` file.

##### library

Type: `{ type: string; name: string }`

##### exposes

Type: `Record<string, string>`

Entry points that are exposed from a _remote_ application.

e.g.

```js
exposes: {
  './Module': '<app-root>/src/remote-entry.ts',
},
```

##### shared

Type: `Function`

Takes a library name and the current [share configuration](https://webpack.js.org/plugins/module-federation-plugin/#sharing-hints), and returns one
of

- `false` - Exclude this library from shared.
- `undefined` - Keep Nx sharing defaults.
- `SharedLibraryConfig` - Override Nx sharing defaults
  with [custom configuration](https://webpack.js.org/plugins/module-federation-plugin/#sharing-hints).

##### additionalShared

Type: `Array<string |{ libraryName: string; sharedConfig: SharedLibraryConfig }>`

Shared libraries in addition to the ones that Nx detects automatically. Items
match [`ModuleFederationPlugin`'s sharing configuration](https://webpack.js.org/plugins/module-federation-plugin/#sharing-hints).

{% tabs %}
{% tabitem label="React Module Federation" %}

```js
const { composePlugins, withNx } = require('@nx/webpack');
const { withReact, withModuleFederation } = require('@nx/react');

// Host config
// e.g. { remotes: ['about', 'dashboard'] }
const moduleFederationConfig = require('./module-federation.config');

module.exports = composePlugins(
  withNx(),
  withReact(),
  withModuleFederation(moduleFederationConfig),
  (config) => {
    // Further customize webpack config
    return config;
  }
);
```

{% /tabitem %}
{% tabitem label="Angular Module Federation" %}

```js
const {
  composePlugins,
  withModuleFederation,
} = require('@nx/angular/module-federation');

// Host config
// e.g. { remotes: ['about', 'dashboard'] }
const moduleFederationConfig = require('./module-federation.config');

module.exports = composePlugins(
  withModuleFederation(moduleFederationConfig),
  (config) => {
    // Further customize webpack config
    return config;
  }
);
```

{% /tabitem %}
{% tabitem label="React Module Federation for SSR " %}

```js
const { composePlugins, withNx } = require('@nx/webpack');
const { withReact, withModuleFederatioForSSRn } = require('@nx/react');

// Host config
// e.g. { remotes: ['about', 'dashboard'] }
const moduleFederationConfig = require('./module-federation.config');

module.exports = composePlugins(
  withNx(),
  withReact(),
  withModuleFederationForSSR(moduleFederationConfig),
  (config) => {
    // Further customize webpack config
    return config;
  }
);
```

{% /tabitem %}
{% tabitem label="Angular Module Federation for SSR" %}

```js
const {
  composePlugins,
  withModuleFederationForSSR,
} = require('@nx/angular/module-federation');

// Host config
// e.g. { remotes: ['about', 'dashboard'] }
const moduleFederationConfig = require('./module-federation.config');

module.exports = composePlugins(
  withModuleFederationForSSR(moduleFederationConfig),
  (config) => {
    // Further customize webpack config
    return config;
  }
);
```

{% /tabitem %}
{% /tabs %}

---
<!-- source: https://nx.dev/docs/technologies/build-tools/webpack/introduction.md -->
## Webpack Plugin for Nx

The Nx plugin for [webpack](https://webpack.js.org/).

[Webpack](https://webpack.js.org/) is a static module bundler for modern JavaScript applications. The `@nx/webpack` plugin provides executors that allow you to build and serve your projects using webpack, plus an executor for SSR.

You can [customize your webpack configuration](/docs/technologies/build-tools/webpack/guides/webpack-config-setup) for your projects. Nx also provides [a number of webpack plugins](/docs/technologies/build-tools/webpack/guides/webpack-plugins) for supporting Nx and other frameworks.

## Requirements

The `@nx/webpack` plugin supports the following package versions.

| Package   | Supported Versions |
| --------- | ------------------ |
| `webpack` | >=5.0.0            |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

## Setting up a new Nx workspace with Webpack

You can create a new workspace that uses Webpack with one of the following commands:

- Generate a new standalone React app set up with Webpack

```shell
npx create-nx-workspace@latest --preset=react-standalone --bundler=webpack
```

- Generate a new React monorepo set up with Webpack

```shell
npx create-nx-workspace@latest --preset=react-monorepo --bundler=webpack
```

### Installation

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/webpack` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
{% /aside %}

In any Nx workspace, you can install `@nx/webpack` by running the following command:

```shell
nx add @nx/webpack
```

This will install the correct version of `@nx/webpack`.

### How @nx/webpack infers tasks

The `@nx/webpack` plugin will create a task for any project that has a Webpack configuration file present. Any of the following files will be recognized as a Webpack configuration file:

- `webpack.config.js`
- `webpack.config.ts`
- `webpack.config.mjs`
- `webpack.config.cjs`

### View inferred tasks

To view inferred tasks for a project, open the [project details view](/docs/concepts/inferred-tasks) in Nx Console or run `nx show project my-project --web` in the command line.

### @nx/webpack configuration

The `@nx/webpack/plugin` is configured in the `plugins` array in `nx.json`.

```json {% meta="{2-10}" %}
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/webpack/plugin",
      "options": {
        "buildTargetName": "build",
        "previewTargetName": "preview",
        "serveTargetName": "serve",
        "serveStaticTargetName": "serve-static"
      }
    }
  ]
}
```

The `buildTargetName`, `previewTargetName`, `serveTargetName` and `serveStaticTargetName` options control the names of the inferred Webpack tasks. The default names are `build`, `preview`, `serve` and `serve-static`.

## Generate a new project using Webpack

You can generate a [React](/docs/technologies/react/introduction) application or a [Web](/docs/reference/web) application that uses Webpack in an existing Nx workspace. The [`@nx/react:app`](/docs/technologies/react/generators#application), [`@nx/node:app`](/docs/technologies/node/generators#application) and [`@nx/web:app`](/docs/reference/web/generators#application) generators accept the `bundler` option, where you can pass `webpack`. This will generate a new application configured to use Webpack, and it will also install all the necessary dependencies, including the `@nx/webpack` plugin.

To generate a React application using Webpack, run the following:

```bash {% frame="none" %}
nx g @nx/react:app apps/my-app --bundler=webpack
```

To generate a Node application using Webpack, run the following:

```bash {% frame="none" %}
nx g @nx/node:app apps/my-app --bundler=webpack
```

To generate a Web application using Webpack, run the following:

```bash {% frame="none" %}
nx g @nx/web:app apps/my-app --bundler=webpack
```

---
<!-- source: https://nx.dev/docs/technologies/build-tools/webpack/migrations.md -->
## @nx/webpack Migrations

The @nx/webpack plugin provides various migrations to help you migrate to newer versions of webpack projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 22.0.x

### `update-22-0-0-remove-deprecated-options`
**Version**: 22.0.0-beta.0

Remove deprecated deleteOutputPath and sassImplementation options from @nx/webpack:webpack



## 21.5.x

### 21.5.0-package-updates
**Version**: 21.5.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `webpack` | `5.101.3` | Updated only



## 21.0.x

### `update-21-0-0-remove-isolated-config`
**Version**: 21.0.0-beta.11

Remove isolatedConfig option for @nx/webpack:webpack

#### Remove `isolatedConfig` option

The `isolatedConfig` option is no longer supported by the `@nx/webpack:webpack` executor. Previously, setting `isolatedConfig: false` allowed you to use the executor's built-in Webpack configuration.

If this option is set in `project.json`, then it will be removed in favor of an explicit `webpackConfig` file. The Webpack configuration file matches the previous built-in configuration of the `@nx/webpack:webpack` executor.

#### Sample Code Changes

##### Before

```json title="project.json"
{
  "targets": {
    "build": {
      "executor": "@nx/webpack:webpack",
      "options": {
        "isolatedConfig": false
      }
    }
  }
}
```

##### After

```json title="project.json" {6}
{
  "targets": {
    "build": {
      "executor": "@nx/webpack:webpack",
      "options": {
        "webpackConfig": "apps/myapp/webpack.config.js"
      }
    }
  }
}
```




## 20.7.x

### 20.7.1-package-updates
**Version**: 20.7.1-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `webpack` | `5.98.0` | Updated only
| `webpack-dev-server` | `^5.2.1` | Updated only



## 20.5.x

### 20.5.0-package-updates
**Version**: 20.5.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `sass-loader` | `^16.0.4` | Updated only

---
<!-- source: https://nx.dev/docs/technologies/dotnet.md -->
## .NET

{% index_page_cards path="technologies/dotnet" /%}

---
<!-- source: https://nx.dev/docs/technologies/dotnet/generators.md -->
## @nx/dotnet Generators

The @nx/dotnet plugin provides various generators to help you create and configure dotnet projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `init`
Initializes a .NET project in the current workspace.

**Usage:**
```bash
nx generate @nx/dotnet:init [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--keepExistingVersions` | boolean | Keep existing dependencies versions | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--updatePackageScripts` | boolean | Update `package.json` scripts with inferred targets | `false` |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/dotnet:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/dotnet/guides.md -->
## Guides

{% index_page_cards path="technologies/dotnet/guides" /%}

---
<!-- source: https://nx.dev/docs/technologies/dotnet/guides/incremental-builds.md -->
## Incremental Builds for .NET Projects

The `@nx/dotnet` plugin automatically configures projects to use the `--no-dependencies` flag when executing .NET build commands. This optimization allows Nx to manage build orchestration through its task graph, preventing duplicate compilations and maximizing cache efficiency.

## How it works

When building outside of Nx, the .NET CLI typically handles dependency resolution and builds all project references automatically. However, this approach conflicts with Nx task orchestration and caching mechanisms. By using `--no-dependencies`, the plugin delegates dependency management to Nx, which has full visibility into the project graph and can optimize build execution.

### Target dependencies

All .NET build targets generated by the plugin include a `dependsOn` configuration that ensures dependencies are built in the correct order:

```json
{
  "targets": {
    "build": {
      "command": "dotnet build",
      "dependsOn": ["^build"]
    }
  }
}
```

The `^build` dependency tells Nx to build all upstream dependencies before building the current project. This replaces the .NET CLI's built-in dependency resolution with Nx more sophisticated task orchestration.

{% aside type="note" title="Why restore is not in dependsOn" %}
The `restore` target is not included in the `dependsOn` array because Nx requires NuGet package restoration to be completed before running any tasks. Running `restore` through Nx task graph would create a circular dependency since Nx needs restoration completed to analyze project structure and dependencies.
{% /aside %}

## Avoiding duplicate builds

Consider a workspace with the following structure:

- apps/WebApi
- libs/ClassLib

If `WebApi` depends on `ClassLib`, running commands **without** `--no-dependencies` would result in:

### Without `--no-dependencies`

```shell
nx build WebApi
```

1. Nx analyzes the dependency graph and schedules `nx build ClassLib`
2. Nx executes `dotnet build libs/ClassLib/ClassLib.csproj`
   - .NET CLI builds ClassLib
3. Nx executes `dotnet build apps/WebApi/WebApi.csproj`
   - .NET CLI detects the ClassLib project reference
   - .NET CLI builds ClassLib **again** (duplicate build)
   - .NET CLI builds WebApi

```shell
nx affected -t build
```

1. Nx determines both WebApi and ClassLib need to be built
2. Nx runs `nx build ClassLib` first (due to dependency graph)
   - .NET CLI builds ClassLib
3. Nx runs `nx build WebApi`
   - .NET CLI builds ClassLib **again** (duplicate build)
   - .NET CLI builds WebApi

This means ClassLib is compiled **twice** during affected builds, and the duplication scales with the number of project references.

### With `--no-dependencies` (default)

The `@nx/dotnet` plugin automatically adds `--no-dependencies` to build commands, eliminating duplicate builds:

```shell
nx build WebApi
```

1. Nx analyzes the dependency graph and schedules `nx build ClassLib`
2. Nx executes `dotnet build libs/ClassLib/ClassLib.csproj --no-dependencies`
   - .NET CLI builds ClassLib
3. Nx executes `dotnet build apps/WebApi/WebApi.csproj --no-dependencies`
   - .NET CLI builds **only** WebApi (skips ClassLib)

```shell
nx affected -t build
```

1. Nx determines both WebApi and ClassLib need to be built
2. Nx runs `nx build ClassLib` first
   - .NET CLI builds ClassLib
3. Nx runs `nx build WebApi`
   - .NET CLI builds **only** WebApi (no duplicate compilation)

## Optimizing cache hits

The benefits extend beyond avoiding duplicate builds—`--no-dependencies` also maximizes cache effectiveness.

Consider a scenario where you modify only `WebApi`, leaving `ClassLib` unchanged:

### Without `--no-dependencies`

```shell
nx affected -t build
```

1. Nx determines only WebApi needs rebuilding
2. Since ClassLib hasn't changed, Nx restores it from cache
3. Nx runs `nx build WebApi`
   - .NET CLI detects the ClassLib project reference
   - .NET CLI rebuilds ClassLib **from source** (ignoring the cache)
   - .NET CLI builds WebApi

The cached ClassLib output is effectively wasted because the .NET CLI rebuilds it anyway.

### With `--no-dependencies` (default)

```shell
nx affected -t build
```

1. Nx determines only WebApi needs rebuilding
2. Since ClassLib hasn't changed, Nx restores it from cache
3. Nx runs `nx build WebApi --no-dependencies`
   - .NET CLI builds **only** WebApi, using the cached ClassLib output

The cache is fully utilized, dramatically improving build performance in incremental scenarios.

## Target configuration

The plugin automatically configures all .NET projects with appropriate target dependencies. For example, a typical library project configuration looks like:

```json
{
  "name": "ClassLib",
  "targets": {
    "build": {
      "command": "dotnet build",
      "options": {
        "cwd": "{projectRoot}",
        "args": ["--no-restore", "--no-dependencies"]
      },
      "dependsOn": ["^build"],
      "cache": true,
      "inputs": ["default", "^production"],
      "outputs": ["{projectRoot}/bin", "{projectRoot}/obj"]
    },
    "restore": {
      "command": "dotnet restore",
      "options": {
        "cwd": "{projectRoot}",
        "args": ["--no-dependencies"]
      },
      "dependsOn": ["^restore"],
      "cache": true
    }
  }
}
```

### Key configuration points

- **`--no-dependencies`**: Prevents .NET from building project references
- **`dependsOn: ["^build"]`**: Ensures dependencies are built first through Nx
- **`cache: true`**: Enables Nx computation caching for the target

## Build commands

### Build a single project

```shell
nx build my-project
```

Builds the specified project and all its dependencies in the correct order.

### Build all affected projects

```shell
nx affected -t build
```

Builds only projects affected by recent changes, along with their dependencies.

### Build with parallelization

```shell
nx run-many -t build --parallel=3
```

Builds multiple projects in parallel when possible, respecting dependency constraints.

## Best practices

### Use the default configuration

The plugin automatically configures `--no-dependencies` for all targets. Avoid overriding this unless you have a specific reason.

### Verify target dependencies

Ensure all build targets include `"dependsOn": ["^build"]` so Nx knows to build dependencies first. The plugin handles this automatically during project detection.

### Leverage Nx cache

Enable [Nx Cloud](https://nx.app) to share build cache across your team and CI/CD pipelines, maximizing the performance benefits of incremental builds.

### Monitor build performance

Use the Nx graph visualization to understand your project dependencies:

```shell
nx graph
```

This helps identify opportunities to further optimize your build graph.

## Troubleshooting

### Build errors referencing missing dependencies

If you see errors like "Could not find project reference", ensure:

1. The referenced project exists in the workspace
2. The `dependsOn: ["^build"]` configuration is present
3. Run `nx reset` to clear the cache if stale

---
<!-- source: https://nx.dev/docs/technologies/dotnet/guides/migrate-from-nx-dotnet-core.md -->
## Migrate from @nx-dotnet/core to @nx/dotnet

This guide provides a streamlined migration path from the community `@nx-dotnet/core` plugin to Nx official `@nx/dotnet` plugin.

{% aside type="note" title="Plugin Status" %}
The `@nx-dotnet/core` plugin is deprecated in favor of the official `@nx/dotnet` plugin (available in Nx 22+), which is maintained by the Nx team and integrated directly into the Nx repository.
{% /aside %}

## Why migrate?

The official `@nx/dotnet` plugin represents a natural evolution, building on lessons learned from the community plugin while embracing native .NET workflows:

- **Project inference**: Automatic detection of .NET projects without configuration with [Nx inferred targets](/docs/guides/tasks--caching/convert-to-inferred)
- **MSBuild integration**: Direct use of Microsoft's APIs for accurate dependency analysis
- **Native CLI first**: Uses `dotnet` commands directly instead of custom wrappers
- **Minimal abstraction**: Simpler implementation with fewer dependencies

This results in a faster, and more reliable .NET plugin.

## Prerequisites

Before starting the migration:

- [ ] Upgrade to **.NET SDK 8.0 or later** (required)
- [ ] Locate your current @nx-dotnet/core configuration (see below)
- [ ] Review any custom generators and executors you're using
- [ ] Ensure your projects build successfully with current setup

### Locating your configuration

The @nx-dotnet/core plugin configuration can be in one of two places:

{% tabs %}
{% tabitem label="nx.json" %}

```json
{
  "plugins": [
    {
      "plugin": "@nx-dotnet/core",
      "options": {
        "inferredTargets": { ... },
        "solutionFile": "...",
        // ... other options
      }
    }
  ]
}
```

{% /tabitem %}
{% tabitem label=".nx-dotnet.rc.json" %}

```json
{
  "inferredTargets": { ... },
  "solutionFile": "...",
  // ... other options
}
```

{% /tabitem %}
{% /tabs %}

{% aside type="note" title="No Configuration?" %}
If you don't have custom configuration in either location, that's fine! The plugin works with defaults, and migration will be even simpler.
{% /aside %}

## Migration steps

### 1. Install @nx/dotnet

```shell
nx add @nx/dotnet
```

This automatically:

- Adds `@nx/dotnet` as a dependency
- Registers the plugin in `nx.json`
- Configures target inputs
- Updates `.gitignore`

### 2. Remove @nx-dotnet/core

```shell
npm uninstall @nx-dotnet/core @nx-dotnet/utils @nx-dotnet/dotnet
```

Clean up the relevant workspace configurations:

- Remove `@nx-dotnet/core` from the `plugins` array in `nx.json` (if present)
- Delete `.nx-dotnet.rc.json` (if it exists)

### 3. Migrate plugin configuration

Move any customized target configurations from your @nx-dotnet/core config to the new @nx/dotnet plugin options.

**Before** (in `nx.json` or `.nx-dotnet.rc.json`):

```json
{
  "inferredTargets": {
    "build": "build",
    "test": {
      "targetName": "test:dotnet",
      "cache": false
    }
  }
}
```

**After** (in `nx.json`):

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/dotnet",
      "options": {
        "build": {
          "targetName": "build"
        },
        "test": {
          "targetName": "test:dotnet"
        }
      }
    }
  ]
}
```

### 4. clear cache and verify

```shell
nx reset
nx graph
```

The `nx graph` command should show all your .NET projects with their dependencies correctly detected. If you encounter any issues, see the [Troubleshooting](#troubleshooting) section below.

## Key workflow changes

Here's what changes in your day-to-day usage with the new `@nx/dotnet` plugin:

| Task                      | Old (@nx-dotnet/core)                                          | New (@nx/dotnet)                                |
| ------------------------- | -------------------------------------------------------------- | ----------------------------------------------- |
| **Create application**    | `nx g @nx-dotnet/core:app my-api`                              | `dotnet new webapi -n MyApi`                    |
| **Create library**        | `nx g @nx-dotnet/core:lib my-lib`                              | `dotnet new classlib -n MyLib`                  |
| **Add project reference** | `nx g @nx-dotnet/core:project-reference --source A --target B` | `dotnet add reference ../B/B.csproj`            |
| **Add NuGet package**     | `nx g @nx-dotnet/core:nuget-reference`                         | `dotnet add package PackageName`                |
| **Build project**         | `nx build my-api`                                              | `nx build my-api` ✅ (same)                     |
| **Run tests**             | `nx test my-api`                                               | `nx test my-api` ✅ (same)                      |
| **Serve/watch**           | `nx serve my-api`                                              | `dotnet watch run` (or configure custom target) |

### Default targets generated

The plugin automatically creates these targets for .NET projects:

| Target    | When Created        | Command                                       |
| --------- | ------------------- | --------------------------------------------- |
| `build`   | All projects        | `dotnet build --no-restore --no-dependencies` |
| `test`    | Test projects only  | `dotnet test --no-build --no-restore`         |
| `restore` | All projects        | `dotnet restore`                              |
| `clean`   | All projects        | `dotnet clean`                                |
| `publish` | Executable projects | `dotnet publish`                              |
| `pack`    | Library projects    | `dotnet pack`                                 |

### Adding back missing targets

The `serve` and `format` targets are not automatically created. `serve` defaults to a target named `watch` now. To run it, you'd need to run `nx run my-api:watch run`. To configure the watch target to act like `serve`, you could set the following in `nx.json`:

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/dotnet",
      "options": {
        "watch": {
          "targetName": "serve",
          "args": ["run"]
        }
      }
    }
  ]
}
```

The `format` target is not present by default. You should add it as a custom target if desired.

## Advanced migration scenarios

### Migrating from explicit executor configurations

If you have `project.json` files that explicitly configure @nx-dotnet/core executors, you'll need to update them to use command targets.

**Before** (`project.json`):

```json
// project.json
{
  "name": "my-api",
  "targets": {
    "build": {
      "executor": "@nx-dotnet/core:build",
      "options": {
        "configuration": "Release",
        "noDependencies": true
      }
    },
    "test": {
      "executor": "@nx-dotnet/core:test",
      "options": {
        "testProject": "MyApi.Tests.csproj"
      }
    },
    "serve": {
      "executor": "@nx-dotnet/core:serve",
      "options": {
        "project": "MyApi.csproj"
      }
    }
  }
}
```

**After** (`project.json`):

```json
// project.json
{
  "name": "my-api",
  "targets": {
    "build": {
      "command": "dotnet build",
      "options": {
        "cwd": "{projectRoot}",
        "args": ["--configuration", "Release", "--no-dependencies"]
      }
    },
    "test": {
      "command": "dotnet test MyApi.Tests.csproj",
      "options": {
        "cwd": "{projectRoot}"
      }
    },
    "serve": {
      "command": "dotnet watch run",
      "options": {
        "cwd": "{projectRoot}"
      }
    }
  }
}
```

{% aside type="tip" title="Automatic Target Inference" %}
In most cases, you can delete these `project.json` files entirely. The @nx/dotnet plugin will [automatically infer](/docs/guides/tasks--caching/convert-to-inferred) the correct targets based on your `.csproj` files. Only keep custom `project.json` configurations if you need non-standard options.
{% /aside %}

### Migrating from `inferProjects: false`

If you previously set `inferProjects: false` in your @nx-dotnet/core config, this option no longer exists in @nx/dotnet. The new plugin **always** infers projects automatically.

**Why this changed:**

- Project inference is a core feature of how Nx plugins work
- Manual project management doesn't align with Nx preferred automatic detection model
- Maintaining explicit project configurations is error-prone

**Migration path:**

1. **If you disabled inference to exclude certain projects:**
   - Use the `exclude` property in the plugin configuration:
     ```json
     // nx.json
     {
       "plugins": [
         {
           "plugin": "@nx/dotnet",
           "exclude": ["legacy-projects/**", "temp-projects/**"]
         }
       ]
     }
     ```

2. **If you disabled inference to use explicit project.json files:**
   - The new plugin will still detect your projects via `.csproj` files
   - You can keep `project.json` files to customize targets, but they're optional
   - Consider removing them to use the automatically inferred targets

## Configuration changes

### Module boundaries → Nx conformance

If you used `moduleBoundaries` in your @nx-dotnet/core config, you may want to migrate to [Nx Conformance rules](/docs/enterprise/conformance)

The script used to evaluate module boundaries is missing several features from the eslint and conformance implementations, and is not present in the new plugin. If you wish to continue using it, you'll need to inline the implementation in your repository and update the path in `Directory.build.targets`. Otherwise, you should remove the target from `Directory.build.targets`.

### NuGet package management

Replace the `sync` generator with MSBuild's [Central Package Management](https://learn.microsoft.com/nuget/consume-packages/central-package-management).

Create `Directory.Packages.props` at workspace root:

```xml
// Directory.Packages.props
<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>
  <ItemGroup>
    <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
    <PackageVersion Include="Microsoft.Extensions.Logging" Version="8.0.0" />
  </ItemGroup>
</Project>
```

Update project files to remove version attributes:

```diff {% meta="lang='xml'" %}
- <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
+ <PackageReference Include="Newtonsoft.Json" />
```

## Testing the migration

Run these commands to verify everything works:

```shell
# Clear cache
nx reset

# Verify project detection
nx show projects

# Test builds
nx run-many -t build

# Test affected builds
nx affected -t build

# Run tests
nx run-many -t test
```

## Troubleshooting

### Projects not detected after migration

**Symptom**: Some .NET projects don't appear in `nx show projects`

**Solution**:

- Ensure project files have `.csproj`, `.fsproj`, or `.vbproj` extensions
- Check that the plugin is registered in `nx.json`
- Run `nx reset` to clear the cache

### "Could not find project reference" build error

**Symptom**: Build fails with "Could not find project reference"

**Solution**:

- Verify the referenced project exists in the workspace
- Ensure build targets have `"dependsOn": ["^build"]` (plugin adds this automatically)
- Check that project references in `.csproj` files use correct relative paths
- Run `nx reset` to clear stale cache

### Missing Targets (test, pack, publish)

**Symptom**: Expected targets like `test` or `pack` don't show up

**Solution**:

- `test`: Only created for projects with `IsTestProject` property or `Microsoft.NET.Test.Sdk` package
- `pack`: Only created for library projects (not executables)
- `publish`: Only created for executable projects (`OutputType="Exe"`)
- Use `nx show project my-project` to see all available targets

### Project name mismatch after migration

**Symptom**: Project names don't match expectations

**Solution**:
Add a `Name` property to your `.csproj` file under the `Nx` property group:

```xml
<PropertyGroup>
  <Nx>
    <Name>my-custom-name</Name>
  </Nx>
</PropertyGroup>
```

## Next steps

After completing the migration:

- Review the [incremental builds guide](/docs/technologies/dotnet/guides/incremental-builds) to understand how `--no-dependencies` optimizes builds
- Configure [Nx Cloud](https://nx.dev/nx-cloud?utm_source=nx.dev&utm_medium=dotnet-migration) for improved repo experience for your team and CI
- Set up custom targets for `serve`, `lint`, or other specialized tasks as needed
- Update CI/CD pipelines to ensure .NET SDK 8.0+ is installed

## Additional resources

- [Nx .NET Plugin Documentation](/docs/technologies/dotnet/introduction)
- [Nx Conformance](/docs/enterprise/conformance)
- [Central Package Management](https://learn.microsoft.com/nuget/consume-packages/central-package-management)

---
<!-- source: https://nx.dev/docs/technologies/dotnet/introduction.md -->
## .NET Plugin for Nx

{% aside type="caution" title="Experimental Plugin" %}
The `@nx/dotnet` plugin is currently experimental. Features and APIs may change.
{% /aside %}

[.NET](https://dotnet.microsoft.com/) is a free, cross-platform, open-source developer platform for building many different types of applications. With .NET, you can use multiple languages, editors, and libraries to build for web, mobile, desktop, games, IoT, and more.

The Nx plugin for .NET registers .NET projects in your Nx workspace. It allows MSBuild tasks to be run through Nx. Nx effortlessly makes your [CI faster](/docs/guides/nx-cloud/setup-ci).

Nx adds the following features to your workspace:

- [Cache task results](/docs/features/cache-task-results)
- [Distribute task execution](/docs/features/ci-features/distribute-task-execution)
- [Run only tasks affected by a PR](/docs/features/ci-features/affected)
- [Interactively explore your workspace](/docs/features/explore-graph)

{% aside type="note" title=".NET SDK Compatibility" %}
This plugin requires .NET SDK 8.0 or newer. Older versions of .NET core may work, but are unsupported and may lead to issues. If you need support for an older version, please create an issue on [Github](https://github.com/nrwl/nx)!
{% /aside %}

## Setup @nx/dotnet

### Install Nx

You can install Nx globally. Depending on your package manager, use one of the following commands:

{% tabs syncKey="package-manager" %}
{% tabitem label="npm" %}

```shell
npm add --global nx@latest
```

{% /tabitem %}
{% tabitem label="Homebrew (macOS, Linux)" %}

```shell
brew install nx
```

{% /tabitem %}
{% tabitem label="Chocolatey (Windows)" %}

```shell
choco install nx
```

{% /tabitem %}
{% tabitem label="apt (Ubuntu)" %}

```shell
sudo add-apt-repository ppa:nrwl/nx
sudo apt update
sudo apt install nx
```

{% /tabitem %}
{% /tabs %}

### Add Nx to a .NET workspace

In any .NET workspace, run the following command to add Nx and the `@nx/dotnet` plugin:

```shell
nx init
```

Then, you can run .NET tasks using Nx. For example:

```shell
nx build <your dotnet project>
```

### Add .NET to an existing Nx workspace

If you already have an Nx workspace set up, you can add the `@nx/dotnet` plugin by running the following command:

```shell
nx add @nx/dotnet
```

{% aside title="Minimum Nx Version" type="caution" %}
The `@nx/dotnet` plugin only became available in Nx 22.0.0. Your Nx Workspace will need to be on this version or higher to use it.
{% /aside %}

New projects can be created with the `dotnet new` CLI command, or any other method you may be familiar with. For example:

```shell
dotnet new webapi -o ./apps/my-api
```

Full project creation docs can be found here [on the official Microsoft documentation](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-new).

## How @nx/dotnet infers tasks

The `@nx/dotnet` plugin uses MSBuild to analyze your .NET solution and project structure. When using `nx add`, the plugin is automatically configured in your `nx.json` file.

The plugin automatically detects .NET projects by scanning for the following project file patterns:

- `**/*.csproj` (C# projects)
- `**/*.fsproj` (F# projects)
- `**/*.vbproj` (Visual Basic projects)

The plugin analyzes your MSBuild project files to determine:

- Project dependencies (via `<ProjectReference>` elements)
- Available build targets (build, test, clean, etc.)
- Project outputs and configuration

## View inferred tasks

To view inferred tasks for a project, open the [project details view](/docs/features/explore-graph#explore-projects-in-your-workspace) in Nx Console or run `nx show project my-project` in the command line.

## @nx/dotnet configuration

The `@nx/dotnet` is configured in the `plugins` array in `nx.json`.

Each target type can be configured with:

- `targetName` - Rename the target if needed (e.g., change "build" to "compile")
- Additional target configuration properties (options, configurations, dependsOn, cache, inputs, outputs)
- Set to `false` to disable a target

For example:

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/dotnet",
      "options": {
        "build": {
          "targetName": "compile",
          "configurations": {
            "production": {
              "optimization": true
            }
          }
        },
        "test": {
          "targetName": "unit-test",
          "dependsOn": ["build"]
        },
        "pack": false
      }
    }
  ]
}
```

Once a .NET project file has been identified, the targets are created with the configuration you specify in the `nx.json` `plugins` array. The default names for the inferred targets are:

- `build` - Compiles the project
- `test` - Runs unit tests (for test projects)
- `clean` - Removes build outputs
- `restore` - Restores NuGet package dependencies
- `publish` - Publishes the application (for executable projects)
- `pack` - Creates a NuGet package (for library projects)
- `watch` - Watches the project for changes and rebuilds (automatically marked as continuous)
- `run` - Runs the application (for executable projects)

### Target availability

Not all targets are available for every project type. The plugin intelligently determines which targets to create based on the project type:

- **Console Applications & Web Projects**: build, clean, restore, publish, watch, run
- **Class Libraries**: build, clean, restore, pack, watch
- **Test Projects**: build, clean, restore, test, watch

### Continuous tasks

The `@nx/dotnet` plugin automatically marks the `watch` target as [continuous](/docs/reference/project-configuration#continuous), ensuring Nx handles it correctly during development. Unlike watch, `run` is not automatically marked as continuous as it may exit depending on the type of application. To mark `run` as continuous, you can configure it manually in `project.json` or `nx.json`.

{% tabs %}
{% tabitem label="nx.json" %}

In the `nx.json`, you can specify that run should be continuous like so:

```json {% meta="{5}" %}
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/dotnet",
      "options": {
        "run": {
          "continuous": true
        }
      }
    }
  ]
}
```

{% /tabitem %}
{% tabitem label="project.json" %}

Alternatively, you can create a new `project.json` file in the root of your project (next to the `.csproj` file) and configure the `run` target as continuous like so:

```json {% meta="{4}" %}
// project.json
{
  "run": {
    "continuous": true
  }
}
```

{% /tabitem %}
{% /tabs %}

## Working with configurations

The `@nx/dotnet` plugin supports MSBuild configurations (Debug, Release, etc.) through Nx configuration system. You can run tasks with specific configurations:

```shell
# Build with Release configuration
nx build my-app --configuration release

# Build with Debug configuration (usually the default)
nx build my-app --configuration debug
```

---
<!-- source: https://nx.dev/docs/technologies/dotnet/migrations.md -->
## @nx/dotnet Migrations

No migrations found for `@nx/dotnet`.
Nx only retains migrations for the last 2 major versions of Nx.
It's possible migrations existed in previous versions of `@nx/dotnet`.

You can check the previous docs for [Nx v21](https://21.nx.dev/docs) or [Nx v20](https://20.nx.dev/docs).

---
<!-- source: https://nx.dev/docs/technologies/eslint.md -->
## ESLint

{% index_page_cards path="technologies/eslint" /%}

---
<!-- source: https://nx.dev/docs/technologies/eslint/eslint-plugin.md -->
## ESLint Plugin

{% index_page_cards path="technologies/eslint/eslint-plugin" /%}

---
<!-- source: https://nx.dev/docs/technologies/eslint/eslint-plugin/guides.md -->
## Guides

{% index_page_cards path="technologies/eslint/eslint-plugin/guides" /%}

---
<!-- source: https://nx.dev/docs/technologies/eslint/eslint-plugin/guides/dependency-checks.md -->
## Dependency Checks ESLint Rule

The `@nx/dependency-checks` ESLint rule enables you to discover mismatches between dependencies specified in a project's `package.json` and the dependencies that your project depends on. If your project is using, for example, the `axios`, but the `package.json` does not specify it as a dependency, your library might not work correctly. This rule helps catch these problems before your users do.

The rule uses the project graph to collect all the dependencies of your project, based on the input of your `build` target. It will filter out all the dependencies marked as `devDependencies` in your root `package.json` to ensure dependencies of your compilation pipelines (e.g. dependencies of `webpack.config` or `vite.config`) or test setups are not included in the expected list.

We use the version numbers of the installed packages when checking whether the version specifier in `package.json` is correct. We do this because this is the only version for which we can "guarantee" that things work and were tested. If you specify a range outside of that version, that would mean that you are shipping potentially untested code.

{% aside type="tip" title="Keep the Package Manager Lock File Up-to-Date" %}
The `@nx/dependency-checks` rule requires the presence of an up-to-date lock file in the workspace root to detect installed packages and their versions correctly. If the `package.json` file has changes that are not reflected in the lock file, make sure to perform a package installation.
{% /aside %}

## Usage

Library generators from `@nx` packages will configure this rule automatically when you opt-in for bundler/build setup. This rule is intended for publishable/buildable libraries, so it will only run if a `build` target is detected in the configuration (this name can be modified - see [options](#options)).

### Manual setup

To set it up manually for existing libraries, you need to add the `dependency-checks` rule to your project's ESLint configuration:

{% tabs syncKey="eslint-config-preference" %}
{% tabitem label="Flat Config" %}

```javascript
// <your-project-root>/eslint.config.mjs
import nxPlugin from '@nx/eslint-plugin';
import jsoncParser from 'jsonc-eslint-parser';

export default [
  ...nxPlugin.configs['flat/base'],
  ...nxPlugin.configs['flat/typescript'],
  ...nxPlugin.configs['flat/javascript'],
  {
    files: ['**/*.json'],
    languageOptions: {
      parser: jsoncParser,
    },
    rules: {
      '@nx/dependency-checks': 'error',
    },
  },
  // ... more ESLint config here
];
```

{% /tabitem %}
{% tabitem label="Legacy (.eslintrc.json)" %}

```jsonc
// <your-project-root>/.eslintrc.json
{
  // ... more ESLint config here
  "overrides": [
    {
      "files": ["*.json"],
      "parser": "jsonc-eslint-parser",
      "rules": {
        "@nx/dependency-checks": "error",
      },
    },
    // ... more ESLint overrides here
  ],
}
```

{% /tabitem %}
{% /tabs %}

Additionally, you need to adjust your `lintFilePatterns` to include the project's `package.json` file::

```jsonc {% meta="{8}" %}
// <your-project-root>/project.json
{
  // ... project.json config
  "targets": {
    // ... more targets
    "lint": {
      "executor": "@nx/eslint:lint",
      "outputs": ["{options.outputFile}"],
      "options": {
        "lintFilePatterns": [
          "libs/my-lib/**/*.{ts,tsx,js,jsx}",
          "libs/my-lib/package.json", // add this line
        ],
      },
    },
  },
}
```

### Overriding defaults

Sometimes we intentionally want to add or remove a dependency from our `package.json` despite what the rule suggests. We can use the rule's options to override default behavior:

{% tabs syncKey="eslint-config-preference" %}
{% tabitem label="Flat Config" %}

```javascript
// eslint.config.mjs
export default [
  // ... other config
  {
    files: ['**/*.json'],
    rules: {
      '@nx/dependency-checks': [
        'error',
        {
          buildTargets: ['build', 'custom-build'], // add non standard build target names
          checkMissingDependencies: true, // toggle to disable
          checkObsoleteDependencies: true, // toggle to disable
          checkVersionMismatches: true, // toggle to disable
          ignoredDependencies: ['lodash'], // these libs will be omitted from checks
          ignoredFiles: ['webpack.config.js', 'eslint.config.mjs'], // list of files that should be skipped for check
          includeTransitiveDependencies: true, // collect dependencies transitively from children
          useLocalPathsForWorkspaceDependencies: true, // toggle to disable
          peerDepsVersionStrategy: 'installed', // or 'workspace' to use workspace:* for peer dependencies
        },
      ],
    },
  },
];
```

{% /tabitem %}
{% tabitem label="Legacy (.eslintrc.json)" %}

```jsonc
// .eslintrc.json
{
  "@nx/dependency-checks": [
    "error",
    {
      "buildTargets": ["build", "custom-build"], // add non standard build target names
      "checkMissingDependencies": true, // toggle to disable
      "checkObsoleteDependencies": true, // toggle to disable
      "checkVersionMismatches": true, // toggle to disable
      "ignoredDependencies": ["lodash"], // these libs will be omitted from checks
      "ignoredFiles": ["webpack.config.js", "eslint.config.mjs"], // list of files that should be skipped for check
      "includeTransitiveDependencies": true, // collect dependencies transitively from children
      "useLocalPathsForWorkspaceDependencies": true, // toggle to disable
      "peerDepsVersionStrategy": "installed", // or 'workspace' to use workspace:* for peer dependencies
    },
  ],
}
```

{% /tabitem %}
{% /tabs %}

## Options

| Property                              | Type                         | Default       | Description                                                                                                                                                                                                                                                      |
| ------------------------------------- | ---------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| buildTargets                          | _Array<string>_              | _["build"]_   | List of build target names                                                                                                                                                                                                                                       |
| checkMissingDependencies              | _boolean_                    | _true_        | Disable to skip checking for missing dependencies                                                                                                                                                                                                                |
| checkObsoleteDependencies             | _boolean_                    | _true_        | Disable to skip checking for unused dependencies                                                                                                                                                                                                                 |
| checkVersionMismatches                | _boolean_                    | _true_        | Disable to skip checking if version specifier matches installed version                                                                                                                                                                                          |
| ignoredDependencies                   | _Array<string>_              | _[]_          | List of dependencies to ignore for checks                                                                                                                                                                                                                        |
| ignoredFiles                          | _Array<string>_              | N/A           | List of files to ignore when collecting dependencies. The default value will be set based on the selected executor during the generation.                                                                                                                        |
| includeTransitiveDependencies         | _boolean_                    | _false_       | Enable to collect dependencies of children projects                                                                                                                                                                                                              |
| useLocalPathsForWorkspaceDependencies | _boolean_                    | _false_       | Set workspace dependencies as relative file:// paths. Useful for monorepos that link via file:// in package.json files.                                                                                                                                          |
| peerDepsVersionStrategy               | _"installed" \| "workspace"_ | _"installed"_ | Strategy for version specifiers in peer dependencies. Use `"installed"` to use the installed version, or `"workspace"` to use `workspace:*` protocol for monorepo packages.                                                                                      |
| runtimeHelpers                        | _Array<string>_              | _[]_          | List of helper packages used by the built output (e.g. `tslib` when using `tsc` and `importHelpers` is set to `true`). The rule already detects some of them in some scenarios, but this option can be used to detect them when it doesn't happen automatically. |

---
<!-- source: https://nx.dev/docs/technologies/eslint/eslint-plugin/guides/enforce-module-boundaries.md -->
## Enforce Module Boundaries ESLint Rule

The `@nx/enforce-module-boundaries` ESLint rule enables you to define strict rules for accessing resources between
different projects in the repository. Enforcing strict boundaries helps to prevent unplanned cross-dependencies.

{% aside type="note" %}
This rule requires ESLint and only works for JavaScript/TypeScript projects. For language-agnostic boundary enforcement across all project dependencies, see the [Conformance plugin's Enforce Project Boundaries rule](/docs/enterprise/conformance).
{% /aside %}

## Usage

You can use the `enforce-module-boundaries` rule by adding it to your ESLint rules configuration:

{% tabs syncKey="eslint-config-preference" %}
{% tabitem label="Flat Config" %}

```javascript
// eslint.config.mjs
import nxPlugin from '@nx/eslint-plugin';

export default [
  ...nxPlugin.configs['flat/base'],
  ...nxPlugin.configs['flat/typescript'],
  ...nxPlugin.configs['flat/javascript'],
  {
    files: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
    rules: {
      '@nx/enforce-module-boundaries': [
        'error',
        {
          // ...rule specific configuration
        },
      ],
    },
  },
];
```

{% /tabitem %}
{% tabitem label="Legacy (.eslintrc.json)" %}

```jsonc
// .eslintrc.json
{
  // ... more ESLint config here
  "overrides": [
    {
      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
      "rules": {
        "@nx/enforce-module-boundaries": [
          "error",
          {
            // ...rule specific configuration
          },
        ],
      },
    },
    // ... more ESLint overrides here
  ],
}
```

{% /tabitem %}
{% /tabs %}

## Options

| Property                           | Type                      | Default | Description                                                                                                                                                                                                                                    |
| ---------------------------------- | ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| allow                              | _Array<string>_           | _[]_    | List of imports that should be allowed without any checks                                                                                                                                                                                      |
| allowCircularSelfDependency        | _boolean_                 | _false_ | Disable check for self circular dependency when project imports from itself via alias path                                                                                                                                                     |
| banTransitiveDependencies          | _boolean_                 | _false_ | Ban import of dependencies that were not specified in the root or project's `package.json`                                                                                                                                                     |
| ignoredCircularDependencies        | _Array<[string, string]>_ | _[]_    | List of project pairs that should be skipped from `Circular dependencies` checks, including the self-circular dependency check. E.g. `['feature-project-a', 'myapp']`. Project name can be replaced by catch all `*` for more generic matches. |
| checkDynamicDependenciesExceptions | _Array<string>_           | _[]_    | List of imports that should be skipped for `Imports of lazy-loaded libraries forbidden` checks. E.g. `['@myorg/lazy-project/component/*', '@myorg/other-project']`                                                                             |
| checkNestedExternalImports         | _boolean_                 | _false_ | Enable to enforce the check for banned external imports in the nested packages. Check [Dependency constraints](#dependency-constraints) for more information                                                                                   |
| enforceBuildableLibDependency      | _boolean_                 | _false_ | Enable to restrict the buildable libs from importing non-buildable libraries                                                                                                                                                                   |
| depConstraints                     | _Array<object>_           | _[]_    | List of dependency constraints between projects                                                                                                                                                                                                |

### Dependency constraints

The `depConstraints` is an array of objects representing the constraints defined between source and target projects. A
constraint must include `sourceTag` or `allSourceTags`. The constraints are applied with **AND** logical operation - for
a given `source` project the resulting constraints would be **all** that match its tags.

| Property                 | Type            | Description                                                                        |
| ------------------------ | --------------- | ---------------------------------------------------------------------------------- |
| sourceTag                | _string_        | Tag that source project must contain to match the constraint                       |
| allSourceTags            | _Array<string>_ | List of tags the source project must contain to match the constraint               |
| onlyDependOnLibsWithTags | _Array<string>_ | The source **can depend only** on projects that contain at least one of these tags |
| notDependOnLibsWithTags  | _Array<string>_ | The source **can not depend** on projects that contain at least one of these tags  |
| allowedExternalImports   | _Array<string>_ | Exclusive list of external (npm) packages that are allowed to be imported          |
| bannedExternalImports    | _Array<string>_ | List of external (npm) packages that are banned from importing                     |

Read more about the proper usage of this rule:

- [Enforce Module Boundaries](/docs/features/enforce-module-boundaries)
- [Ban Dependencies with Certain Tags](/docs/guides/enforce-module-boundaries/ban-dependencies-with-tags)
- [Tag in Multiple Dimensions](/docs/guides/enforce-module-boundaries/tag-multiple-dimensions)
- [Ban External Imports](/docs/guides/enforce-module-boundaries/ban-external-imports)
- [Tags Allow List](/docs/guides/enforce-module-boundaries/tags-allow-list)
- [Taming Code Organization with Module Boundaries in Nx](https://nx.dev/blog/mastering-the-project-boundaries-in-nx)

---
<!-- source: https://nx.dev/docs/technologies/eslint/eslint-plugin/introduction.md -->
## ESLint Plugin

{% index_page_cards path="technologies/eslint/eslint-plugin" /%}

---
<!-- source: https://nx.dev/docs/technologies/eslint/eslint-plugin/migrations.md -->
## @nx/eslint-plugin Migrations

No migrations found for `@nx/eslint-plugin`.
Nx only retains migrations for the last 2 major versions of Nx.
It's possible migrations existed in previous versions of `@nx/eslint-plugin`.

You can check the previous docs for [Nx v21](https://21.nx.dev/docs) or [Nx v20](https://20.nx.dev/docs).

---
<!-- source: https://nx.dev/docs/technologies/eslint/executors.md -->
## @nx/eslint Executors

The @nx/eslint plugin provides various executors to help you create and configure eslint projects within your Nx workspace.
Below is a complete reference for all available executors and their options.

### `lint`
ESLint Lint Target.

Linter can be configured in multiple ways. The basic way is to provide only `lintFilePatterns`, which tells us where to look for files to lint. If not specified, it defaults to `['{projectRoot}']`.

`project.json`:

```json
"lint": {
  "executor": "@nx/eslint:lint",
  "options": {
    "lintFilePatterns": ["apps/frontend/**/*.ts"]
  }
}
```

### Examples

###### Fixing linter issues

Linter provides an automated way of fixing known issues. To ensure that those changes are properly cached, we need to add an `outputs` property to the `lint` target. Omitting the `outputs` property would produce an invalid cache record. Both of these properties are set by default when scaffolding a new project.

```json
"lint": {
  "executor": "@nx/eslint:lint",
  "outputs": ["{options.outputFile}"],
  "options": {
    "lintFilePatterns": ["apps/frontend/**/*.ts"]
  }
}
```

With these settings, we can run the command with a `--fix` flag:

```bash
nx run frontend:lint --fix
```

We can also set this flag via project configuration to always fix files when running lint:

```json
"lint": {
  "executor": "@nx/eslint:lint",
  "outputs": ["{options.outputFile}"],
  "options": {
    "lintFilePatterns": ["apps/frontend/**/*.ts"],
    "fix": true
  }
}
```

###### Custom output format

ESLint executor uses the `stylish` output format by default. You can change this by specifying the `format` property:

```json
"lint": {
  "executor": "@nx/eslint:lint",
  "outputs": ["{options.outputFile}"],
  "options": {
    "lintFilePatterns": ["apps/frontend/**/*.ts"],
    "format": "compact"
  }
}
```

###### Silence warnings

Migrated or legacy projects tend to have an overwhelming amount of lint errors. We might want to change those temporarily to be warnings so they don't block the development. But they would still clutter the report. We can run the command with `--quiet` to hide warning (errors would still break the lint):

```bash
nx run frontend:lint --quiet
```

We can also set this via project configuration as a default option.

```json
"lint": {
  "executor": "@nx/eslint:lint",
  "outputs": ["{options.outputFile}"],
  "options": {
    "lintFilePatterns": ["apps/frontend/**/*.ts"],
    "quiet": true
  }
}
```

###### Flat Config file

`ESLint` provides several ways of specifying the configuration. The default one is using `.eslintrc.json` but you can override it by setting the `eslintConfig` flag. The new `Flat Config` is now also supported:

```json
"lint": {
  "executor": "@nx/eslint:lint",
  "outputs": ["{options.outputFile}"],
  "options": {
    "lintFilePatterns": ["apps/frontend/**/*.ts"],
    "eslintConfig": "eslint.config.cjs"
  }
}
```

**Note:** In contrast to other configuration formats, the `Flat Config` requires that all configuration files are converted to `eslint.config.cjs`. Built-in migrations and generators support only `.eslintrc.json` at the moment.

###### Bulk Suppression

ESLint v9.24.0 introduced bulk suppression features that allow you to suppress existing violations while only new violations trigger errors. This is particularly useful when migrating to stricter lint rules in existing codebases.

**Suppress all existing violations:**

```json
"lint": {
  "executor": "@nx/eslint:lint",
  "outputs": ["{options.outputFile}"],
  "options": {
    "lintFilePatterns": ["apps/frontend/**/*.ts"],
    "suppressAll": true
  }
}
```

**Suppress specific rules:**

```json
"lint": {
  "executor": "@nx/eslint:lint",
  "outputs": ["{options.outputFile}"],
  "options": {
    "lintFilePatterns": ["apps/frontend/**/*.ts"],
    "suppressRule": ["no-console", "no-unused-vars"]
  }
}
```

**Specify custom suppressions file location:**

```json
"lint": {
  "executor": "@nx/eslint:lint",
  "outputs": ["{options.outputFile}"],
  "options": {
    "lintFilePatterns": ["apps/frontend/**/*.ts"],
    "suppressAll": true,
    "suppressionsLocation": "./custom-suppressions.json"
  }
}
```

**Note:** Bulk suppression options require ESLint v9.24.0 or higher. When using these options with older ESLint versions, the executor will throw an error.

---
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `cache` | boolean | Only check changed files. | `false` |
| `cacheLocation` | string | Path to the cache file or directory. |  |
| `cacheStrategy` | string | Strategy to use for detecting changed files in the cache. | `"metadata"` |
| `errorOnUnmatchedPattern` | boolean | When set to false, equivalent of the `--no-error-on-unmatched-pattern` flag on the ESLint CLI. | `true` |
| `eslintConfig` | string | The name of the ESLint configuration file. |  |
| `fix` | boolean | Fixes linting errors (may overwrite linted files). | `false` |
| `force` | boolean | Succeeds even if there was linting errors. | `false` |
| `format` | string | ESLint Output formatter (https://eslint.org/docs/user-guide/formatters). | `"stylish"` |
| `hasTypeAwareRules` | boolean | When set to `true`, the linter will invalidate its cache when any of its dependencies changes. |  |
| `ignorePath` | string | The path of the `.eslintignore` file. Not supported for Flat Config. |  |
| `lintFilePatterns` | array | One or more files/dirs/globs to pass directly to ESLint's `lintFiles()` method. | `["{projectRoot}"]` |
| `maxWarnings` | number | Number of warnings to trigger nonzero exit code - default: `-1`. | `-1` |
| `noEslintrc` | boolean | The equivalent of the `--no-eslintrc` flag on the ESLint CLI, it is `false` by default. | `false` |
| `outputFile` | string | File to write report to. |  |
| `printConfig` | string | The equivalent of the `--print-config` flag on the ESLint CLI. |  |
| `quiet` | boolean | Report errors only - default: `false`. | `false` |
| `reportUnusedDisableDirectives` | string | The equivalent of the `--report-unused-disable-directives` flag on the ESLint CLI. |  |
| `resolvePluginsRelativeTo` | string | The equivalent of the `--resolve-plugins-relative-to` flag on the ESLint CLI. Not supported for Flat Config. |  |
| `rulesdir` | array | The equivalent of the `--rulesdir` flag on the ESLint CLI. | `[]` |
| `silent` | boolean | Hide output text. | `false` |
| `suppressAll` | boolean | Suppress all existing violations. This is equivalent to the `--suppress-all` flag on the ESLint CLI. Requires ESLint v9.24.0 or higher. | `false` |
| `suppressionsLocation` | string | Specify the location of the suppressions file. This is equivalent to the `--suppressions-location` flag on the ESLint CLI. Defaults to 'eslint-suppressions.json' in the project root. Requires ESLint v9.24.0 or higher. |  |
| `suppressRule` | array | Suppress violations for specific rules. This is equivalent to the `--suppress-rule` flag on the ESLint CLI. Requires ESLint v9.24.0 or higher. | `[]` |

---
<!-- source: https://nx.dev/docs/technologies/eslint/generators.md -->
## @nx/eslint Generators

The @nx/eslint plugin provides various generators to help you create and configure eslint projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `convert-to-flat-config`
Convert an Nx workspace's ESLint configs to use Flat Config.

**Usage:**
```bash
nx generate @nx/eslint:convert-to-flat-config [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--skipFormat` | boolean | Skip formatting files. | `false` |

## `convert-to-inferred`
Convert existing Eslint project(s) using `@nx/eslint:lint` executor to use `@nx/eslint/plugin`. Defaults to migrating all projects. Pass '--project' to migrate only one target.

**Usage:**
```bash
nx generate @nx/eslint:convert-to-inferred [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string | The project to convert from using the `@nx/eslint:lint` executor to use `@nx/eslint/plugin`. |  |
| `--skipFormat` | boolean | Whether to format files at the end of the migration. | `false` |

## `workspace-rule`
Create a new Workspace Lint Rule.

###### Create rule

This command will generate a new workspace lint rule called `my-custom-rule`. The new rule will be generated in `tools/eslint-rules/rules` folder:

```shell
nx g @nx/eslint:workspace-rule my-custom-rule
```

###### Custom sub-folder

We can change the default sub-folder from `rules` and specify a custom one:

```shell
nx g @nx/eslint:workspace-rule --name=my-custom-rule --directory=my/custom/path
```

The command above will generate the rule in `tools/eslint-rules/my/custom/path` folder.

---

**Usage:**
```bash
nx generate @nx/eslint:workspace-rule [options]
```

**Arguments:**
```bash
nx generate @nx/eslint:workspace-rule <name> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--directory` | string [**required**] | Create the rule under this directory within `tools/eslint-rules/` (can be nested). | `"rules"` |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/eslint:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/eslint/guides.md -->
## Guides

{% index_page_cards path="technologies/eslint/guides" /%}

---
<!-- source: https://nx.dev/docs/technologies/eslint/guides/custom-workspace-rules.md -->
## Custom Workspace ESLint Rules

Custom ESLint rules allow you to enforce team-specific conventions, project architectural patterns, and codebase-specific best practices that aren't covered by existing ESLint plugins. Nx provides two main approaches for creating and using custom ESLint rules in your workspace.

<!-- TODO: Add "Quick Start with the Generator" section once @nx/eslint:workspace-rule supports ESLint v9 -->

## Understanding the two approaches

There are two main approaches for custom ESLint rules in Nx workspaces:

1. **Package Manager Workspaces (npm/yarn/pnpm/bun)**: Create a dedicated ESLint plugin package (e.g., `nx g @nx/js:lib packages/eslint-rules`) that's symlinked via your package manager. Import rules as you would any npm package.

2. **`loadWorkspaceRules` Utility**: Use the `@nx/eslint-plugin` utility to load rules from any directory. This works whether or not you use package manager workspaces.

Choose the approach that fits your workspace setup:

| Scenario                             | Recommended Approach       |
| ------------------------------------ | -------------------------- |
| Using npm/yarn/pnpm/bun workspaces   | Package Manager Workspaces |
| Not using package manager workspaces | `loadWorkspaceRules`       |
| Want rules as a publishable package  | Package Manager Workspaces |
| TypeScript rules with minimal config | `loadWorkspaceRules`       |

## Approach 1: package manager workspaces

If your workspace uses npm, yarn, pnpm, or bun workspaces, you can create custom ESLint rules as a regular package. This approach treats your custom rules like any other internal dependency.

### Step 1: create the ESLint plugin package

Create a new library for your ESLint plugin:

```shell
nx g @nx/js:lib packages/eslint-rules
```

{% aside type="note" %}
If you don't use `nx g @nx/js:lib` to create your package, make sure your package is included in your workspace configuration (e.g., `packages/*` in `pnpm-workspace.yaml` or the `workspaces` field in `package.json`).
{% /aside %}

### Step 2: Structure the Plugin

Your plugin package should export rules following the ESLint plugin format:

```typescript
// packages/eslint-rules/src/index.ts
import { noFooConst, RULE_NAME as noFooConstName } from './rules/no-foo-const';

export default {
  rules: {
    [noFooConstName]: noFooConst,
  },
};
```

### Step 3: Create a Rule

Each rule should follow the ESLint rule structure. Using `@typescript-eslint/utils` provides excellent TypeScript support:

```typescript
// packages/eslint-rules/src/rules/no-foo-const.ts
import { ESLintUtils } from '@typescript-eslint/utils';

export const RULE_NAME = 'no-foo-const';

export const noFooConst = ESLintUtils.RuleCreator(() => __filename)({
  name: RULE_NAME,
  meta: {
    type: 'problem',
    docs: {
      description: 'Disallow variables named "foo"',
    },
    schema: [],
    messages: {
      noFoo: 'Variables named "foo" are not allowed.',
    },
  },
  defaultOptions: [],
  create(context) {
    return {
      VariableDeclarator(node) {
        if (node.id.type === 'Identifier' && node.id.name === 'foo') {
          context.report({
            node: node.id,
            messageId: 'noFoo',
          });
        }
      },
    };
  },
});
```

### Step 4: install and use the plugin

After creating your plugin package, install dependencies to ensure it's symlinked:

```shell
npm install
# or: yarn install
# or: pnpm install
# or: bun install
```

Then use the plugin in your ESLint configuration:

{% tabs syncKey="eslint-config-preference" %}
{% tabitem label="Flat Config" %}

```javascript
// eslint.config.mjs
import eslintRules from '@acme/eslint-rules';

export default [
  {
    plugins: {
      '@acme/eslint-rules': eslintRules,
    },
    rules: {
      '@acme/eslint-rules/no-foo-const': 'error',
    },
  },
];
```

{% /tabitem %}
{% tabitem label="Legacy (.eslintrc.json)" %}

```json
{
  "plugins": ["@acme/eslint-rules"],
  "rules": {
    "@acme/eslint-rules/no-foo-const": "error"
  }
}
```

{% /tabitem %}
{% /tabs %}

### Running TypeScript rules

When using TypeScript for your ESLint rules, the TypeScript code must be transpiled or interpreted before ESLint can use it. There are several options:

Node.js 22.6+ supports TypeScript natively through type stripping. As of Node 22.18.0 and Node 24, this is enabled by default.

For older versions in the 22.x series, enable it with:

```shell
NODE_OPTIONS="--experimental-strip-types" nx lint myproject
```

<!-- TODO(v23): Remove Node 20 since it will be out of LTS -->

Alternatively, if you are on Node 20 or do not want to use Node.js strip-types feature, the `tsx` package provides fast TypeScript execution with ESM support:

```shell
npm install -D tsx
```

Then you can register `tsx` in your `eslint.config.mjs` file prior to importing the custom rules.

```js
import { register } from 'tsx/esm/api';

const unregister = register();

const eslintRules = await import('@acme/eslint-rules');

export default [
  {
    plugins: {
      '@acme/eslint-rules': eslintRules,
    },
    rules: {
      '@acme/eslint-rules/no-foo-const': 'error',
    },
  },
];

// cleanup
unregister();
```

See the [ESM Register API](https://tsx.is/dev-api/register-esm) docs for `tsx` for more information.

## Approach 2: Using loadWorkspaceRules

The `loadWorkspaceRules` utility from `@nx/eslint-plugin` lets you load ESLint rules from any directory in your workspace. This is particularly useful when:

- You're not using package manager workspaces
- You want rules in a non-standard location
- You need automatic TypeScript transpilation

### Basic usage

```javascript
// eslint.config.mjs
import baseConfig from './eslint.base.config.mjs';
import { loadWorkspaceRules } from '@nx/eslint-plugin';

// Load rules from a directory relative to workspace root
const customRules = await loadWorkspaceRules('tools/my-eslint-rules');

export default [
  ...baseConfig,
  {
    files: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
    plugins: {
      custom: { rules: customRules },
    },
    rules: {
      'custom/my-custom-rule': 'error',
    },
  },
];
```

### How `loadWorkspaceRules` works

The utility:

1. Accepts a directory path (relative to workspace root or absolute)
2. Looks for an `index.ts`, `index.mts`, `index.cts`, `index.js`, `index.mjs`, or `index.cjs` file
3. Automatically finds and uses a `tsconfig.json` for TypeScript transpilation
4. Returns the exported rules object

### Specifying a custom `tsconfig`

You can provide a specific `tsconfig.json` path:

```javascript
const customRules = await loadWorkspaceRules(
  'tools/my-eslint-rules',
  'tools/my-eslint-rules/tsconfig.lib.json'
);
```

If not provided, `loadWorkspaceRules` searches for `tsconfig.json` starting from the rules directory and traversing up to the workspace root.

### Example: Project-specific rules

You can load rules from within a project:

```javascript
// apps/my-app/eslint.config.mjs
import baseConfig from '../../eslint.base.config.mjs';
import { loadWorkspaceRules } from '@nx/eslint-plugin';

// Load rules specific to this project
const projectRules = await loadWorkspaceRules('apps/my-app/eslint-rules');

export default [
  ...baseConfig,
  {
    files: ['**/*.ts'],
    plugins: {
      project: { rules: projectRules },
    },
    rules: {
      'project/component-naming': 'error',
    },
  },
];
```

<!-- TODO: Add section for @nx/eslint:workspace-rule once it supports ESLint v9 -->

## Related resources

- [ESLint Developer Guide](https://eslint.org/docs/developer-guide/working-with-rules)
- [TypeScript ESLint Custom Rules](https://typescript-eslint.io/developers/custom-rules)

---
<!-- source: https://nx.dev/docs/technologies/eslint/guides/eslint.md -->
## Configuring ESLint with TypeScript

ESLint is powerful linter by itself, able to work on the syntax of your source files and assert things about based on the rules you configure. It gets even more powerful, however, when TypeScript type-checker is layered on top of it when analyzing TypeScript files, which is something that `@typescript-eslint` allows us to do.

By default, Nx sets up your ESLint configs with performance in mind - we want your linting to run as fast as possible. Because creating the necessary so called TypeScript `Program`s required to create the type-checker behind the scenes is relatively expensive compared to pure syntax analysis, you should only configure the `parserOptions.project` option in your project's `.eslintrc.json` when you need to use rules requiring type information (and you should not configure `parserOptions.project` in your workspace's root `.eslintrc.json`).

Let's take an example of an ESLint config that Nx might generate for you out of the box for a Next.js project called `tuskdesk`:

{% tabs syncKey="eslint-config-preference" %}
{% tabitem label="Flat Config" %}

```javascript
// apps/tuskdesk/eslint.config.mjs
import { FlatCompat } from '@eslint/eslintrc';
import js from '@eslint/js';
import nxPlugin from '@nx/eslint-plugin';
import reactPlugin from '@nx/react/eslint-plugin';

const compat = new FlatCompat({
  baseDirectory: __dirname,
  recommendedConfig: js.configs.recommended,
});

export default [
  ...reactPlugin,
  ...compat.config({ extends: ['../../eslint.config.mjs'] }),
  { ignores: ['!**/*'] },
  {
    files: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
    rules: {},
  },
  {
    files: ['**/*.ts', '**/*.tsx'],
    rules: {},
  },
  {
    files: ['**/*.js', '**/*.jsx'],
    rules: {},
  },
];
```

{% /tabitem %}
{% tabitem label="Legacy (.eslintrc.json)" %}

```jsonc
// apps/tuskdesk/.eslintrc.json
{
  "extends": ["plugin:@nx/react", "../../.eslintrc.json"],
  "ignorePatterns": ["!**/*"],
  "overrides": [
    {
      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
      "rules": {},
    },
    {
      "files": ["*.ts", "*.tsx"],
      "rules": {},
    },
    {
      "files": ["*.js", "*.jsx"],
      "rules": {},
    },
  ],
}
```

{% /tabitem %}
{% /tabs %}

Here we do _not_ have `parserOptions.project`, which is appropriate because we are not leveraging any rules which require type information.

If we now come in and add a rule which does require type information, for example `@typescript-eslint/await-thenable`, our config will look as follows:

{% tabs syncKey="eslint-config-preference" %}
{% tabitem label="Flat Config" %}

```javascript
// apps/tuskdesk/eslint.config.mjs
import { FlatCompat } from '@eslint/eslintrc';
import js from '@eslint/js';
import nxPlugin from '@nx/eslint-plugin';
import reactPlugin from '@nx/react/eslint-plugin';

const compat = new FlatCompat({
  baseDirectory: __dirname,
  recommendedConfig: js.configs.recommended,
});

export default [
  ...reactPlugin,
  ...compat.config({ extends: ['../../eslint.config.mjs'] }),
  { ignores: ['!**/*'] },
  {
    files: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
    rules: {
      // This rule requires the TypeScript type checker to be present when it runs
      '@typescript-eslint/await-thenable': 'error',
    },
  },
  {
    files: ['**/*.ts', '**/*.tsx'],
    rules: {},
  },
  {
    files: ['**/*.js', '**/*.jsx'],
    rules: {},
  },
];
```

{% /tabitem %}
{% tabitem label="Legacy (.eslintrc.json)" %}

```jsonc
// apps/tuskdesk/.eslintrc.json
{
  "extends": ["plugin:@nx/react", "../../.eslintrc.json"],
  "ignorePatterns": ["!**/*"],
  "overrides": [
    {
      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
      "rules": {
        // This rule requires the TypeScript type checker to be present when it runs
        "@typescript-eslint/await-thenable": "error",
      },
    },
    {
      "files": ["*.ts", "*.tsx"],
      "rules": {},
    },
    {
      "files": ["*.js", "*.jsx"],
      "rules": {},
    },
  ],
}
```

{% /tabitem %}
{% /tabs %}

Now if we try and run `nx lint tuskdesk` we will get an error

```text {% title="nx lint tuskdesk" frame="terminal" %}
> nx run tuskdesk:lint

Linting "tuskdesk"...

    Error: You have attempted to use a lint rule which requires the full
    TypeScript type-checker to be available, but you do not have
    `parserOptions.project` configured to point at your project
    tsconfig.json files in the relevant TypeScript file "overrides"
    block of your project ESLint config `apps/tuskdesk/.eslintrc.json`

```

The solution is to update our config once more, this time to set `parserOptions.project` to appropriately point at our various tsconfig.json files which belong to our project:

{% tabs syncKey="eslint-config-preference" %}
{% tabitem label="Flat Config" %}

```javascript
// apps/tuskdesk/eslint.config.mjs
import { FlatCompat } from '@eslint/eslintrc';
import js from '@eslint/js';
import nxPlugin from '@nx/eslint-plugin';
import reactPlugin from '@nx/react/eslint-plugin';
import tseslint from 'typescript-eslint';

const compat = new FlatCompat({
  baseDirectory: __dirname,
  recommendedConfig: js.configs.recommended,
});

export default [
  ...reactPlugin,
  ...compat.config({ extends: ['../../eslint.config.mjs'] }),
  { ignores: ['!**/*'] },
  {
    files: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
    languageOptions: {
      // We set parserOptions.project for the project to allow TypeScript to create the type-checker behind the scenes when we run linting
      parserOptions: {
        project: ['apps/tuskdesk/tsconfig.*?.json'],
      },
    },
    rules: {
      '@typescript-eslint/await-thenable': 'error',
    },
  },
  {
    files: ['**/*.ts', '**/*.tsx'],
    rules: {},
  },
  {
    files: ['**/*.js', '**/*.jsx'],
    rules: {},
  },
];
```

{% /tabitem %}
{% tabitem label="Legacy (.eslintrc.json)" %}

```jsonc
// apps/tuskdesk/.eslintrc.json
{
  "extends": ["plugin:@nx/react", "../../.eslintrc.json"],
  "ignorePatterns": ["!**/*"],
  "overrides": [
    {
      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
      // We set parserOptions.project for the project to allow TypeScript to create the type-checker behind the scenes when we run linting
      "parserOptions": {
        "project": ["apps/tuskdesk/tsconfig.*?.json"],
      },
      "rules": {
        "@typescript-eslint/await-thenable": "error",
      },
    },
    {
      "files": ["*.ts", "*.tsx"],
      "rules": {},
    },
    {
      "files": ["*.js", "*.jsx"],
      "rules": {},
    },
  ],
}
```

{% /tabitem %}
{% /tabs %}

And that's it! Now any rules requiring type information will run correctly when we run `nx lint tuskdesk`.

{% aside type="caution" title="Using Next.js" %}
As well as adapting the path to match your project's real path, please be aware that if you apply the above to a **Next.js** application, you should change the glob pattern at the end to be `tsconfig(.*)?.json`.

E.g. if `tuskdesk` had been a Next.js app, we would have written: `"project": ["apps/tuskdesk/tsconfig(.*)?.json"]`
{% /aside %}

---
<!-- source: https://nx.dev/docs/technologies/eslint/guides/flat-config.md -->
## Switching to ESLint's Flat Config Format

Version 8 of ESLint introduced a new configuration format called [Flat Config](https://eslint.org/docs/latest/use/configure/configuration-files-new). The next major version will use this config format by default. The purpose of this format is to:

- push towards a single configuration format (in contrast to the existing `JSON`, `Yaml` and `JS`-based configs)
- enforce explicit native loading (instead of the implicit imports in `JSON` and `Yaml`)
- use a flat cascading of rules (instead of a mix of rules and overrides)

See below a direct comparison between `JSON`, `JS` and `Flat` config:
{% tabs %}
{% tabitem label="Flat" %}

```js
// eslint.config.cjs
// the older versions were magically interpreting all the imports
// in flat config we do it explicitly
const nxPlugin = require('@nx/eslint-plugin');
const js = require('@eslint/js');
const baseConfig = require('./eslint.base.config.cjs');
const globals = require('globals');
const jsoncParser = require('jsonc-eslint-parser');
const tsParser = require('@typescript-eslint/parser');

module.exports = [
  js.configs.recommended,
  // this will spread the export blocks from the base config
  ...baseConfig,
  { plugins: { '@nx': nxPlugin } },
  {
    languageOptions: {
      parser: tsParser,
      globals: {
        ...globals.node,
      },
    },
    rules: {
      '@typescript-eslint/explicit-module-boundary-types': ['error'],
    },
  },
  // there are no overrides, all the config blocks are "flat"
  {
    files: ['*.json'],
    languageOptions: {
      parser: jsoncParser,
    },
    rules: {},
  },
  {
    files: ['*.ts', '*.tsx', '*.js', '*.jsx'],
    rules: {
      '@nx/enforce-module-boundaries': [
        'error',
        {
          enforceBuildableLibDependency: true,
          allow: [],
          depConstraints: [
            {
              sourceTag: '*',
              onlyDependOnLibsWithTags: ['*'],
            },
          ],
        },
      ],
    },
  },
];
```

{% /tabitem %}
{% tabitem label="JSON" %}

```json
// .eslintrc.json
{
  "root": true,
  "parser": "@typescript-eslint/parser",
  "env": {
    "node": true
  },
  "extends": ["eslint:recommended", "./.eslintrc.base.json"],
  "plugins": ["@nx"],
  "rules": {
    "@typescript-eslint/explicit-module-boundary-types": "error"
  },
  "overrides": [
    {
      "files": ["*.json"],
      "parser": "jsonc-eslint-parser",
      "rules": {}
    },
    {
      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
      "rules": {
        "@nx/enforce-module-boundaries": [
          "error",
          {
            "enforceBuildableLibDependency": true,
            "allow": [],
            "depConstraints": [
              {
                "sourceTag": "*",
                "onlyDependOnLibsWithTags": ["*"]
              }
            ]
          }
        ]
      }
    }
  ]
}
```

{% /tabitem %}
{% tabitem label="JS" %}

```js
// .eslintrc.js
module.exports = {
  root: true,
  env: {
    node: true,
  },
  parser: '@typescript-eslint/parser',
  extends: ['eslint:recommended', './.eslintrc.base.js'],
  plugins: ['@nx'],
  rules: {
    '@typescript-eslint/explicit-module-boundary-types': ['error'],
  },
  overrides: [
    {
      files: ['*.json'],
      parser: 'jsonc-eslint-parser',
      rules: {},
    },
    {
      files: ['*.ts', '*.tsx', '*.js', '*.jsx'],
      rules: {
        '@nx/enforce-module-boundaries': [
          'error',
          {
            enforceBuildableLibDependency: true,
            allow: [],
            depConstraints: [
              {
                sourceTag: '*',
                onlyDependOnLibsWithTags: ['*'],
              },
            ],
          },
        ],
      },
    },
  ],
};
```

{% /tabitem %}
{% /tabs %}

For additional details, head over to [ESLint's official blog post](https://eslint.org/blog/2022/08/new-config-system-part-2/).

Since version 16.8.0, Nx supports the usage of flat config in the [@nx/eslint:lint](/docs/technologies/eslint/executors#lint) executor and `@nx/*` generators, and provides an automated config conversion from `.eslintrc.json` config files.

## Converting workspace from .eslintrc.json to flat config

To convert workspace ESLint configurations from the default `.eslintrc.json` to the new flat config you need to run:

```shell
 nx g @nx/eslint:convert-to-flat-config
```

The generator will go through all the projects and convert their configurations to the new format. It will also convert the base `.eslintrc.json` and `.eslintignore`.

## Correctness and best practices

The purpose of this generator is to create a flat config that works the same way as the original `JSON` config did. Depending on the complexity of your original config, it may be using the `FlatCompat` utility to provide a compatibility wrapper around parts of the original config. You can improve those by following the [official migration guide](https://eslint.org/docs/latest/use/configure/migration-guide).

---
<!-- source: https://nx.dev/docs/technologies/eslint/introduction.md -->
## ESLint Plugin for Nx

The ESLint plugin integrates [ESLint](https://eslint.org/) with Nx. Run ESLint through Nx with caching enabled, and use the included code generators to set up ESLint in your workspace.

## Requirements

The `@nx/eslint` plugin supports the following package versions.

| Package  | Supported Versions |
| -------- | ------------------ |
| `eslint` | ^8.0.0 \|\| ^9.0.0 |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

## Setting up @nx/eslint

### Installation

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/eslint` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
{% /aside %}

In any Nx workspace, you can install `@nx/eslint` by running the following command:

```shell
nx add @nx/eslint
```

This will install the correct version of `@nx/eslint`.

### How @nx/eslint infers tasks

The `@nx/eslint` plugin will create a task for any project that has an ESLint configuration file present and files to lint. Any of the following files will be recognized as an ESLint configuration file:

- `.eslintrc`
- `.eslintrc.js`
- `.eslintrc.mjs`
- `.eslintrc.cjs`
- `.eslintrc.yaml`
- `.eslintrc.yml`
- `.eslintrc.json`
- `eslint.config.js`
- `eslint.config.mjs`
- `eslint.config.cjs`

Because ESLint applies configuration files to all subdirectories, the `@nx/eslint` plugin will also infer tasks for projects in subdirectories. So, if there is an ESLint configuration file in the root of the repository, every project will have an inferred ESLint task.

Even if a project has an ESLint configuration file, it will only have an inferred ESLint task if there are files to lint. Otherwise, the task will not be created. Therefore, if you don't want an ESLint task to be inferred for a particular project, make sure the project files are properly excluded from ESLint.

### View inferred tasks

To view inferred tasks for a project, open the [project details view](/docs/concepts/inferred-tasks) in Nx Console or run `nx show project my-project --web` in the command line.

### @nx/eslint configuration

The `@nx/eslint/plugin` is configured in the `plugins` array in `nx.json`.

```json {% meta="{2-9}" %}
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/eslint/plugin",
      "options": {
        "targetName": "lint"
      }
    }
  ]
}
```

- The `targetName` option controls the name of the inferred ESLint tasks. The default name is `lint`.

## Lint

You can lint an application or a library with the following command:

```shell
nx lint my-project
```

## Utils

- [convert-to-flat-config](/docs/technologies/eslint/generators#convert-to-flat-config) - Converts the workspace's [ESLint](https://eslint.org/) configs to the new [Flat Config](https://eslint.org/blog/2022/08/new-config-system-part-2)

## ESLint plugin

Read about our dedicated ESLint plugin - [eslint-plugin-nx](/docs/technologies/eslint/eslint-plugin).

---
<!-- source: https://nx.dev/docs/technologies/eslint/migrations.md -->
## @nx/eslint Migrations

The @nx/eslint plugin provides various migrations to help you migrate to newer versions of eslint projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 21.5.x

### 21.5.0-typescript-eslint-package-updates
**Version**: 21.5.0-beta.2


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `typescript-eslint` | `^8.40.0` | Updated only
| `@typescript-eslint/eslint-plugin` | `^8.40.0` | Updated only
| `@typescript-eslint/parser` | `^8.40.0` | Updated only
| `@typescript-eslint/utils` | `^8.40.0` | Updated only
| `@typescript-eslint/rule-tester` | `^8.40.0` | Updated only
| `@typescript-eslint/scope-manager` | `^8.40.0` | Updated only
| `@typescript-eslint/typescript-estree` | `^8.40.0` | Updated only


### 21.5.0-@typescript-eslint-package-updates
**Version**: 21.5.0-beta.2


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `typescript-eslint` | `^8.40.0` | Updated only
| `@typescript-eslint/eslint-plugin` | `^8.40.0` | Updated only
| `@typescript-eslint/parser` | `^8.40.0` | Updated only
| `@typescript-eslint/utils` | `^8.40.0` | Updated only
| `@typescript-eslint/rule-tester` | `^8.40.0` | Updated only
| `@typescript-eslint/scope-manager` | `^8.40.0` | Updated only
| `@typescript-eslint/typescript-estree` | `^8.40.0` | Updated only



## 21.2.x

### 21.2.0-typescript-eslint-package-updates
**Version**: 21.2.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `typescript-eslint` | `^8.29.0` | Updated only
| `@typescript-eslint/eslint-plugin` | `^8.29.0` | Updated only
| `@typescript-eslint/parser` | `^8.29.0` | Updated only
| `@typescript-eslint/utils` | `^8.29.0` | Updated only
| `@typescript-eslint/rule-tester` | `^8.29.0` | Updated only
| `@typescript-eslint/scope-manager` | `^8.29.0` | Updated only
| `@typescript-eslint/typescript-estree` | `^8.29.0` | Updated only


### 21.2.0-@typescript-eslint-package-updates
**Version**: 21.2.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `typescript-eslint` | `^8.29.0` | Updated only
| `@typescript-eslint/eslint-plugin` | `^8.29.0` | Updated only
| `@typescript-eslint/parser` | `^8.29.0` | Updated only
| `@typescript-eslint/utils` | `^8.29.0` | Updated only
| `@typescript-eslint/rule-tester` | `^8.29.0` | Updated only
| `@typescript-eslint/scope-manager` | `^8.29.0` | Updated only
| `@typescript-eslint/typescript-estree` | `^8.29.0` | Updated only



## 20.7.x

### 20.7.0-package-updates
**Version**: 20.7.0-beta.4


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `eslint-config-prettier` | `^10.0.0` | Updated only



## 20.4.x

### 20.4.0-typescript-eslint-package-updates
**Version**: 20.4.0-beta.1


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `typescript-eslint` | `^8.19.0` | Updated only
| `@typescript-eslint/eslint-plugin` | `^8.19.0` | Updated only
| `@typescript-eslint/parser` | `^8.19.0` | Updated only
| `@typescript-eslint/utils` | `^8.19.0` | Updated only
| `@typescript-eslint/rule-tester` | `^8.19.0` | Updated only
| `@typescript-eslint/scope-manager` | `^8.19.0` | Updated only
| `@typescript-eslint/typescript-estree` | `^8.19.0` | Updated only


### 20.4.0-@typescript-eslint-package-updates
**Version**: 20.4.0-beta.1


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `typescript-eslint` | `^8.19.0` | Updated only
| `@typescript-eslint/eslint-plugin` | `^8.19.0` | Updated only
| `@typescript-eslint/parser` | `^8.19.0` | Updated only
| `@typescript-eslint/utils` | `^8.19.0` | Updated only
| `@typescript-eslint/rule-tester` | `^8.19.0` | Updated only
| `@typescript-eslint/scope-manager` | `^8.19.0` | Updated only
| `@typescript-eslint/typescript-estree` | `^8.19.0` | Updated only



## 20.3.x

### `add-file-extensions-to-overrides`
**Version**: 20.3.0-beta.1

Update ESLint flat config to include .cjs, .mjs, .cts, and .mts files in overrides (if needed)

#### Update ESLint Config File Extensions in Overrides

Update ESLint flat config to include .cjs, .mjs, .cts, and .mts files in overrides (if needed)

#### Sample Code Changes

Add `.cjs`, `.mjs`, `.cts`, `.mts` file extensions to overrides converted using `convert-to-flat-config`

##### Before

```js title="eslint.config.js"
const { FlatCompat } = require('@eslint/eslintrc');
const js = require('@eslint/js');
const nxEslintPlugin = require('@nx/eslint-plugin');

const compat = new FlatCompat({
  baseDirectory: __dirname,
  recommendedConfig: js.configs.recommended,
});

module.exports = [
  ...compat
    .config({
      extends: ['plugin:@nx/typescript'],
    })
    .map((config) => ({
      ...config,
      files: ['**/*.ts', '**/*.tsx'],
      rules: {
        ...config.rules,
      },
    })),
  ...compat
    .config({
      extends: ['plugin:@nx/javascript'],
    })
    .map((config) => ({
      ...config,
      files: ['**/*.js', '**/*.jsx'],
      rules: {
        ...config.rules,
      },
    })),
];
```

##### After

```js title="eslint.config.js" {17,28}
const { FlatCompat } = require('@eslint/eslintrc');
const js = require('@eslint/js');
const nxEslintPlugin = require('@nx/eslint-plugin');

const compat = new FlatCompat({
  baseDirectory: __dirname,
  recommendedConfig: js.configs.recommended,
});

module.exports = [
  ...compat
    .config({
      extends: ['plugin:@nx/typescript'],
    })
    .map((config) => ({
      ...config,
      files: ['**/*.ts', '**/*.tsx', '**/*.cts', '**/*.mts'],
      rules: {
        ...config.rules,
      },
    })),
  ...compat
    .config({
      extends: ['plugin:@nx/javascript'],
    })
    .map((config) => ({
      ...config,
      files: ['**/*.js', '**/*.jsx', '**/*.cjs', '**/*.mjs'],
      rules: {
        ...config.rules,
      },
    })),
];
```




## 20.2.x

### `update-typescript-eslint-v8.13.0`
**Version**: 20.2.0-beta.5

Update TypeScript ESLint packages to v8.13.0 if they are already on v8

#### Update TypeScript ESLint to v8.13.0

Update TypeScript ESLint packages to v8.13.0 if they are already on v8

#### Sample Code Changes

This migration will update `typescript-eslint`, `@typescript-eslint/eslint-plugin`, `@typescript-eslint/parser` and `@typescript-eslint/utils` to `8.13.0` if they are between version `8.0.0` and `8.13.0`.

##### Before

```json title="package.json"
{
  "devDependencies": {
    "typescript-eslint": "^8.0.0",
    "@typescript-eslint/eslint-plugin": "^8.0.0",
    "@typescript-eslint/parser": "^8.0.0",
    "@typescript-eslint/utils": "^8.0.0"
  }
}
```

##### After

```json title="package.json"
{
  "devDependencies": {
    "typescript-eslint": "^8.13.0",
    "@typescript-eslint/eslint-plugin": "^8.13.0",
    "@typescript-eslint/parser": "^8.13.0",
    "@typescript-eslint/utils": "^8.13.0"
  }
}
```

---
<!-- source: https://nx.dev/docs/technologies/java.md -->
## Java

{% index_page_cards path="technologies/java" /%}

---
<!-- source: https://nx.dev/docs/technologies/java/gradle.md -->
## Gradle

{% index_page_cards path="technologies/java/gradle" /%}

---
<!-- source: https://nx.dev/docs/technologies/java/gradle/executors.md -->
## @nx/gradle Executors

The @nx/gradle plugin provides various executors to help you create and configure gradle projects within your Nx workspace.
Below is a complete reference for all available executors and their options.

### `gradle`
The Gradle Impl executor is used to run Gradle tasks.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `taskName` | string [**required**] | The name of the Gradle task to run. |  |
| `__unparsed__` | array | Additional arguments to pass to the gradle command (automatically populated by Nx). |  |
| `args` | string | The arguments to pass to the Gradle task. |  |
| `excludeDependsOn` | boolean | If true, the tasks will not execute its dependsOn tasks (e.g. pass --exclude-task args to gradle command). If false, the task will execute its dependsOn tasks. | `true` |
| `includeDependsOnTasks` | array | List of Gradle task paths that should be included (not excluded) even when excludeDependsOn is true. These are typically provider-based dependencies that Gradle must resolve. |  |
| `testClassName` | string | The full test name to run for test task (package name and class name). |  |

---
<!-- source: https://nx.dev/docs/technologies/java/gradle/generators.md -->
## @nx/gradle Generators

The @nx/gradle plugin provides various generators to help you create and configure gradle projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `ci-workflow`
Setup a CI Workflow to run Nx in CI.

**Usage:**
```bash
nx generate @nx/gradle:ci-workflow [options]
```

**Arguments:**
```bash
nx generate @nx/gradle:ci-workflow <name> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--ci` | string [**required**] | CI provider. |  |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/gradle:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/java/gradle/introduction.md -->
## Gradle Plugin for Nx

[Gradle](https://gradle.org/) is a build automation tool for JVM-based projects.

The `@nx/gradle` plugin registers Gradle projects in the Nx graph so you can [set up Gradle in Nx](#setup), [run local tasks](#local-development), [configure task inference](#configuration), and [scale in CI](#ci-considerations).

You can use Gradle with Nx without the plugin and still get [task caching](/docs/features/cache-task-results), [task orchestration](/docs/features/run-tasks), and the [project graph](/docs/features/explore-graph).

## Requirements

| Dependency | Supported Versions |
| ---------- | ------------------ |
| Java       | >= 17              |
| Gradle     | >= 8.0             |

Using older Java versions is unsupported and may lead to issues. If you need support for an older version, please create an issue on [GitHub](https://github.com/nrwl/nx).

## Setup

### Install Nx

Install Nx with your preferred package manager:

{% tabs syncKey="package-manager" %}
{% tabitem label="npm" %}

```shell
npm install --global nx@latest
```

You can use `pnpm`, `yarn`, or `bun` if you prefer as well.

{% /tabitem %}
{% tabitem label="Homebrew (macOS, Linux)" %}

```shell
brew install nx
```

{% /tabitem %}
{% tabitem label="Chocolatey (Windows)" %}

```shell
choco install nx
```

{% /tabitem %}
{% tabitem label="apt (Ubuntu)" %}

```shell
sudo add-apt-repository ppa:nrwl/nx
sudo apt update
sudo apt install nx
```

{% /tabitem %}
{% /tabs %}

### Add Nx to a Gradle Workspace

From the root of your Gradle workspace, run:

```shell
nx init
```

Nx will add the `@nx/gradle` plugin and configure the Gradle companion plugin `dev.nx.gradle.project-graph` in your build files.

{% aside type="note" title="Gradle Companion Plugin" %}
The `dev.nx.gradle.project-graph` plugin is added to your `build.gradle` or `build.gradle.kts` so Nx can read your Gradle project graph directly from source.
{% /aside %}

### Verify the setup

List the projects Nx inferred from Gradle:

```shell
nx show projects
```

Open the project details view for a specific project.

```shell
nx show project my-app
```

## Local development

Run Gradle tasks through Nx using inferred targets:

```shell
nx build my-gradle-lib
nx test my-gradle-lib
```

Nx maps these targets back to the Gradle tasks (for example `build` or `test`) and executes them using the Gradle wrapper. If a task should run in watch or server mode, mark it as continuous so Nx treats it correctly.

## Configuration

### How @nx/gradle infers tasks

Nx relies on the `dev.nx.gradle.project-graph` Gradle plugin to report your Gradle projects and tasks. The plugin adds an `nxProjectGraph` task that outputs JSON, which Nx uses to build the project graph. Nx also scans your Gradle build files to locate project roots and inputs so it can infer targets accurately.

The `nx init` workflow adds this plugin to your Gradle build files. If you ever need to add it manually, configure it in `build.gradle` or `build.gradle.kts` and apply it to all projects.

### View inferred tasks

To view inferred tasks for a project, open the project details view in Nx Console or run:

```shell
nx show project my-app
```

Replace `my-app` with your project name.

### @nx/gradle configuration

Configure the plugin in the `plugins` array of `nx.json`:

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/gradle",
      "options": {
        "testTargetName": "test",
        "ciTestTargetName": "test-ci",
        "targetNamePrefix": "gradle-",
        "gradleExecutableDirectory": "./gradle-projects"
      }
    }
  ]
}
```

### How options work

Nx passes the plugin options to the Gradle `nxProjectGraph` task as Gradle properties. Any option that ends with `TargetName` overrides the inferred Nx target name for that Gradle task. Use this to avoid name clashes or to introduce CI-specific targets.

### Options

| Option                      | Type   | Default | Description                                                                |
| --------------------------- | ------ | ------- | -------------------------------------------------------------------------- |
| `testTargetName`            | string | `test`  | Nx target name to map the Gradle `test` task.                              |
| `ciTestTargetName`          | string | none    | Enables CI test atomization and defines the base name for CI test targets. |
| `targetNamePrefix`          | string | none    | Prefix for all inferred Gradle targets (useful in polyglot workspaces).    |
| `gradleExecutableDirectory` | string | none    | Directory containing the Gradle wrapper to use.                            |
| `<taskName>TargetName`      | string | none    | Override for any Gradle task name (for example `assembleTargetName`).      |

### Exclude or include specific projects

Use `include`/`exclude` glob patterns to scope the plugin to specific projects:

```json {% meta="{5-6}" %}
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/gradle",
      "include": ["apps/**/*"],
      "exclude": ["apps/legacy-app/**/*"],
      "options": { ... }
    }
  ]
}
```

Individual Gradle projects can also configure Nx-specific settings using the `nx { }` DSL in `build.gradle` or `build.gradle.kts`.

## CI considerations

Only run what changed in CI:

```shell
nx affected -t build test
```

Enable remote caching with Nx Cloud:

```shell
nx connect
```

See [Set Up CI](/docs/guides/nx-cloud/setup-ci) for provider-specific workflows. If you set `ciTestTargetName`, Nx will create CI variants that use atomized test targets.

### Batch mode

Batch mode runs multiple Gradle tasks in a single invocation. Enable it by setting `NX_BATCH_MODE=true`:

```shell
NX_BATCH_MODE=true nx run-many -t build test
```

If your Gradle builds require specific CI flags (for example `--no-daemon` or custom JVM args), add them to `gradle.properties` so Nx runs consistent settings locally and in CI.

## What's next

{% cardgrid %}
{% linkcard title="Gradle Tutorial" description="Add Nx to an existing Gradle workspace step-by-step." href="/docs/getting-started/tutorials/gradle-tutorial" /%}
{% linkcard title="Java with Nx" description="Overview of Java support across Gradle and Maven." href="/docs/technologies/java/introduction" /%}
{% linkcard title="CI Workflow Generator" description="Generate CI workflows that run affected tasks." href="/docs/reference/workspace/generators#ci-workflow" /%}
{% linkcard title="Gradle Generators Reference" description="Full reference for @nx/gradle generators." href="/docs/technologies/java/gradle/generators" /%}
{% linkcard title="Gradle Executors Reference" description="Full reference for @nx/gradle executors." href="/docs/technologies/java/gradle/executors" /%}
{% /cardgrid %}

---
<!-- source: https://nx.dev/docs/technologies/java/gradle/migrations.md -->
## @nx/gradle Migrations

The @nx/gradle plugin provides various migrations to help you migrate to newer versions of gradle projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 22.6.x

### `change-plugin-version-0-1-14`
**Version**: 22.6.0-beta.11

Change dev.nx.gradle.project-graph to version 0.1.14 in build file

#### Change dev.nx.gradle.project-graph to version 0.1.14

Change dev.nx.gradle.project-graph to version 0.1.14 in build file

#### Sample Code Changes

##### Before

```text title="build.gradle"
plugins {
	id "dev.nx.gradle.project-graph" version "0.1.13"
}
```

##### After

```text title="build.gradle"
plugins {
    id "dev.nx.gradle.project-graph" version "0.1.14"
}
```



### `change-plugin-version-0-1-15`
**Version**: 22.6.0-beta.13

Change dev.nx.gradle.project-graph to version 0.1.15 in build file

#### Change dev.nx.gradle.project-graph to version 0.1.15

Change dev.nx.gradle.project-graph to version 0.1.15 in build file

#### Sample Code Changes

##### Before

```text title="build.gradle"
plugins {
	id "dev.nx.gradle.project-graph" version "0.1.14"
}
```

##### After

```text title="build.gradle"
plugins {
    id "dev.nx.gradle.project-graph" version "0.1.15"
}
```




## 22.5.x

### `change-plugin-version-0-1-12`
**Version**: 22.5.0-beta.5

Change dev.nx.gradle.project-graph to version 0.1.12 in build file

#### Change dev.nx.gradle.project-graph to version 0.1.12

Change dev.nx.gradle.project-graph to version 0.1.12 in build file

#### Sample Code Changes

##### Before

```text title="build.gradle"
plugins {
	id "dev.nx.gradle.project-graph" version "0.1.11"
}
```

##### After

```text title="build.gradle"
plugins {
    id "dev.nx.gradle.project-graph" version "0.1.12"
}
```



### `change-plugin-version-0-1-13`
**Version**: 22.5.3

Change dev.nx.gradle.project-graph to version 0.1.13 in build file

#### Change dev.nx.gradle.project-graph to version 0.1.13

Change dev.nx.gradle.project-graph to version 0.1.13 in build file

#### Sample Code Changes

##### Before

```text title="build.gradle"
plugins {
	id "dev.nx.gradle.project-graph" version "0.1.12"
}
```

##### After

```text title="build.gradle"
plugins {
    id "dev.nx.gradle.project-graph" version "0.1.13"
}
```




## 22.4.x

### `change-plugin-version-0-1-11`
**Version**: 22.4.0-beta.2

Change dev.nx.gradle.project-graph to version 0.1.11 in build file

#### Change dev.nx.gradle.project-graph to version 0.1.11

Change dev.nx.gradle.project-graph to version 0.1.11 in build file

#### Sample Code Changes

##### Before

```text title="build.gradle"
plugins {
	id "dev.nx.gradle.project-graph" version "0.1.10"
}
```

##### After

```text title="build.gradle"
plugins {
    id "dev.nx.gradle.project-graph" version "0.1.11"
}
```




## 22.2.x

### `change-plugin-version-0-1-10`
**Version**: 22.2.0-beta.4

Change dev.nx.gradle.project-graph to version 0.1.10 in build file

#### Change dev.nx.gradle.project-graph to version 0.1.10

Change dev.nx.gradle.project-graph to version 0.1.10 in build file

#### Sample Code Changes

##### Before

```text title="build.gradle"
plugins {
	id "dev.nx.gradle.project-graph" version "0.1.0"
}
```

##### After

```text title="build.gradle"
plugins {
    id "dev.nx.gradle.project-graph" version "0.1.10"
}
```




## 22.1.x

### `change-plugin-version-0-1-9`
**Version**: 22.1.0-rc.3

Change dev.nx.gradle.project-graph to version 0.1.9 in build file

#### Change dev.nx.gradle.project-graph to version 0.1.9

Change dev.nx.gradle.project-graph to version 0.1.9 in build file

#### Sample Code Changes

##### Before

```text title="build.gradle"
plugins {
	id "dev.nx.gradle.project-graph" version "0.1.0"
}
```

##### After

```text title="build.gradle"
plugins {
    id "dev.nx.gradle.project-graph" version "0.1.9"
}
```




## 21.6.x

### `change-plugin-version-0-1-8`
**Version**: 21.6.1-beta.2

Change dev.nx.gradle.project-graph to version 0.1.8 in build file

#### Change dev.nx.gradle.project-graph to version 0.1.8

Change dev.nx.gradle.project-graph to version 0.1.8 in build file

#### Sample Code Changes

##### Before

```text title="build.gradle"
plugins {
	id "dev.nx.gradle.project-graph" version "0.1.0"
}
```

##### After

```text title="build.gradle"
plugins {
    id "dev.nx.gradle.project-graph" version "0.1.8"
}
```




## 21.5.x

### `change-plugin-version-0-1-7`
**Version**: 21.5.1-beta.5

Change dev.nx.gradle.project-graph to version 0.1.7 in build file

#### Change dev.nx.gradle.project-graph to version 0.1.7

Change dev.nx.gradle.project-graph to version 0.1.7 in build file

#### Sample Code Changes

##### Before

```text title="build.gradle"
plugins {
	id "dev.nx.gradle.project-graph" version "0.1.0"
}
```

##### After

```text title="build.gradle"
plugins {
    id "dev.nx.gradle.project-graph" version "0.1.7"
}
```




## 21.4.x

### `change-plugin-version-0-1-5`
**Version**: 21.4.0-beta.12

Change dev.nx.gradle.project-graph to version 0.1.5 in build file

#### Change dev.nx.gradle.project-graph to version 0.1.5

Change dev.nx.gradle.project-graph to version 0.1.5 in build file

#### Sample Code Changes

##### Before

```text title="build.gradle"
plugins {
	id "dev.nx.gradle.project-graph" version "0.1.0"
}
```

##### After

```text title="build.gradle"
plugins {
    id "dev.nx.gradle.project-graph" version "0.1.5"
}
```



### `change-plugin-version-0-1-6`
**Version**: 21.4.1-beta.1

Change dev.nx.gradle.project-graph to version 0.1.6 in build file

#### Change dev.nx.gradle.project-graph to version 0.1.6

Change dev.nx.gradle.project-graph to version 0.1.6 in build file

#### Sample Code Changes

##### Before

```text title="build.gradle"
plugins {
	id "dev.nx.gradle.project-graph" version "0.1.0"
}
```

##### After

```text title="build.gradle"
plugins {
    id "dev.nx.gradle.project-graph" version "0.1.6"
}
```




## 21.3.x

### `change-plugin-version-0-1-2`
**Version**: 21.3.0-beta.0

Change dev.nx.gradle.project-graph to version 0.1.2 in build file

#### Change dev.nx.gradle.project-graph to version 0.1.2

Change dev.nx.gradle.project-graph to version 0.1.2 in build file

#### Sample Code Changes

##### Before

```text title="build.gradle"
plugins {
	id "dev.nx.gradle.project-graph" version "0.1.0"
}
```

##### After

```text title="build.gradle"
plugins {
    id "dev.nx.gradle.project-graph" version "0.1.2"
}
```



### `change-plugin-version-0-1-4`
**Version**: 21.3.11-beta.0

Change dev.nx.gradle.project-graph to version 0.1.4 in build file

#### Change dev.nx.gradle.project-graph to version 0.1.4

Change dev.nx.gradle.project-graph to version 0.1.4 in build file

#### Sample Code Changes

##### Before

```text title="build.gradle"
plugins {
	id "dev.nx.gradle.project-graph" version "0.1.2"
}
```

##### After

```text title="build.gradle"
plugins {
    id "dev.nx.gradle.project-graph" version "0.1.4"
}
```




## 21.1.x

### `change-plugin-version-0-1-0`
**Version**: 21.1.2-beta.1

Change dev.nx.gradle.project-graph to version 0.1.0 in build file

#### Change dev.nx.gradle.project-graph to version 0.1.0

Change dev.nx.gradle.project-graph to version 0.1.0 in build file

#### Sample Code Changes

##### Before

```text title="build.gradle"
plugins {
	id "dev.nx.gradle.project-graph" version "0.0.5"
}
```

##### After

```text title="build.gradle"
plugins {
    id "dev.nx.gradle.project-graph" version "0.1.0"
}
```




## 21.0.x

### `change-plugin-to-v1`
**Version**: 21.0.0-beta.5

Change @nx/gradle plugin to version 1

#### Change @nx/gradle plugin to @nx/gradle/plugin-v1

Change @nx/gradle plugin to version 1 in nx.json

#### Sample Code Changes

##### Before

```json title="nx.json"
{
  "plugins": ["@nx/gradle"]
}
```

##### After

```json title="nx.json" {5}
{
  "plugins": ["@nx/gradle/plugin-v1"]
}
```



### `change-ciTargetName-to-ciTestTargetName`
**Version**: 21.0.0-beta.13

Change @nx/gradle option from ciTargetName to ciTestTargetName

#### Change @nx/gradle plugin option ciTargetName to ciTestTargetName

Change @nx/gradle plugin option ciTargetName to ciTestTargetName in nx.json

#### Sample Code Changes

##### Before

```json title="nx.json"
{
  "plugins": [
    "plugin": "@nx/gradle",
    "options": {
      "ciTargetName": "ci"
    }
  ]
}
```

##### After

```json title="nx.json" {5}
{
  "plugins": [
    "plugin": "@nx/gradle",
    "options": {
      "ciTestTargetName": "ci"
    }
  ]
}
```




## 20.2.x

### `add-include-subprojects-tasks`
**Version**: 20.2.0-beta.4

Add includeSubprojectsTasks to build.gradle file

#### Add includeSubprojectsTasks to @nx/gradle Plugin Options

Add includeSubprojectsTasks to @nx/gradle plugin options in nx.json file

#### Sample Code Changes

##### Before

```json title="nx.json"
{
  "plugins": ["@nx/gradle"]
}
```

##### After

```json title="nx.json" {5}
{
  "plugins": [
    {
      "options": {
        "includeSubprojectsTasks": true
      },
      "plugin": "@nx/gradle"
    }
  ]
}
```

---
<!-- source: https://nx.dev/docs/technologies/java/introduction.md -->
## Java with Nx

Nx provides powerful tooling for Java projects, supporting both Gradle and Maven build systems. Whether you're working with Spring Boot, Micronaut, Quarkus, or any other Java framework, Nx helps you build faster and more efficiently.

## Requirements

| Dependency | Supported Versions |
| ---------- | ------------------ |
| Java       | >= 17              |

Using older Java versions is unsupported and may lead to issues. If you need support for an older version, please create an issue on [GitHub](https://github.com/nrwl/nx).

## Quick start

### Install Nx

You can install Nx globally. Depending on your package manager, use one of the following commands:

{% tabs syncKey="package-manager" %}
{% tabitem label="npm" %}

```shell
npm add --global nx@latest
```

{% /tabitem %}
{% tabitem label="Homebrew (macOS, Linux)" %}

```shell
brew install nx
```

{% /tabitem %}
{% tabitem label="Chocolatey (Windows)" %}

```shell
choco install nx
```

{% /tabitem %}
{% tabitem label="apt (Ubuntu)" %}

```shell
sudo add-apt-repository ppa:nrwl/nx
sudo apt update
sudo apt install nx
```

{% /tabitem %}
{% /tabs %}

### Add Nx to your Java project

In any Gradle or Maven project, run the following command to add Nx:

```shell
nx init
```

Nx will automatically detect your build tool and you can then add the appropriate plugin (see Build System Support below).

## Build system support

Nx offers dedicated plugins for the two most popular Java build tools:

- **[@nx/gradle](/docs/technologies/java/gradle/introduction)** - For projects using Gradle
- **[@nx/maven](/docs/technologies/java/maven/introduction)** - For projects using Maven (experimental, requires Nx 22+)

Add the plugin for your build system:

```shell
nx add @nx/gradle
# or
nx add @nx/maven
```

These Nx plugins for Gradle and Maven register your Gradle or Maven projects in your Nx workspace, and allow their tasks to be run through Nx. Nx effortlessly makes your [CI faster](/docs/guides/nx-cloud/setup-ci).

For a hands-on tutorial, check out the [Gradle tutorial](/docs/getting-started/tutorials/gradle-tutorial).

## What Nx adds to your Java workspace

Nx enhances your Java development workflow with:

- **[Smart Caching](/docs/features/cache-task-results)** - Cache build and test results to avoid redundant work
- **[Distributed Task Execution](/docs/features/ci-features/distribute-task-execution)** - Run tasks in parallel across multiple machines in CI
- **[Affected Commands](/docs/features/ci-features/affected)** - Only build and test what changed
- **[Interactive Graph](/docs/features/explore-graph)** - Visualize your project dependencies
- **[CI Optimization](/docs/guides/nx-cloud/setup-ci)** - Make your CI pipeline dramatically faster

---
<!-- source: https://nx.dev/docs/technologies/java/maven.md -->
## Maven

{% index_page_cards path="technologies/java/maven" /%}

---
<!-- source: https://nx.dev/docs/technologies/java/maven/executors.md -->
## @nx/maven Executors

The @nx/maven plugin provides various executors to help you create and configure maven projects within your Nx workspace.
Below is a complete reference for all available executors and their options.

### `maven`
The Maven executor is used to run Maven phases and goals.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `__unparsed__` | array | Additional arguments to pass to the Maven command (automatically populated by Nx). |  |
| `args` | string | The arguments to pass to the Maven command. |  |
| `goals` | string | The Maven goals to execute (e.g., 'clean:clean', 'compiler:compile'). |  |
| `phase` | string | The Maven lifecycle phase to execute (e.g., 'compile', 'test', 'package', 'install'). |  |

---
<!-- source: https://nx.dev/docs/technologies/java/maven/generators.md -->
## @nx/maven Generators

The @nx/maven plugin provides various generators to help you create and configure maven projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `ci-workflow`
Setup a CI Workflow to run Nx in CI.

**Usage:**
```bash
nx generate @nx/maven:ci-workflow [options]
```

**Arguments:**
```bash
nx generate @nx/maven:ci-workflow <name> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--ci` | string [**required**] | CI provider. |  |

## `init`
Initializes @nx/maven in the workspace.

**Usage:**
```bash
nx generate @nx/maven:init [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--skipFormat` | boolean | Skip formatting files | `false` |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/maven:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/java/maven/introduction.md -->
## Maven Plugin for Nx

{% aside type="caution" title="Experimental Plugin" %}
The `@nx/maven` plugin is currently experimental. Features and APIs may change.
{% /aside %}

[Apache Maven](https://maven.apache.org/) is a build tool for Java projects that uses a project object model (POM) to manage builds.

The `@nx/maven` plugin registers Maven modules as Nx projects so you can [set up Maven with Nx](#setup), [run daily Maven tasks](#local-development), [configure task inference](#configuration), and [run in CI](#ci-considerations).

You can use Maven with Nx without the plugin and still get [task caching](/docs/features/cache-task-results), [task orchestration](/docs/features/run-tasks), and the [project graph](/docs/features/explore-graph).

## Requirements

| Dependency | Supported Versions |
| ---------- | ------------------ |
| Java       | >= 17              |
| Maven      | >= 3.6.0           |

Using older Java versions is unsupported and may lead to issues. If you need support for an older version, please create an issue on [GitHub](https://github.com/nrwl/nx).

## Setup

### Install Nx

You can install Nx globally. Depending on your package manager, use one of the following commands:

{% tabs syncKey="package-manager" %}
{% tabitem label="Homebrew (macOS, Linux)" %}

```shell
brew install nx
```

{% /tabitem %}
{% tabitem label="Chocolatey (Windows)" %}

```shell
choco install nx
```

{% /tabitem %}
{% tabitem label="apt (Ubuntu)" %}

```shell
sudo add-apt-repository ppa:nrwl/nx
sudo apt update
sudo apt install nx
```

{% /tabitem %}
{% tabitem label="npm" %}

```shell
npm install --global nx@latest
```

> You can use `pnpm`, `yarn`, or `bun` if you prefer as well.

{% /tabitem %}
{% /tabs %}

### Add Nx to a Maven Workspace

If you are in a Maven workspace without Nx, start here. This command adds Nx and configures `@nx/maven`:

```shell
nx init
```

Verify that Nx discovered your Maven modules:

```shell
nx show projects
```

```shell
nx show project my-app --web
```

Replace `my-app` with a module name from your workspace.

### Add @nx/maven to an existing Nx workspace

If you already have an Nx workspace, add the Maven plugin:

```shell
nx add @nx/maven
```

Verify the plugin is active by inspecting a module:

```shell
nx show project my-app --web
```

Replace `my-app` with a module name from your workspace.

## Local development

The plugin infers targets from Maven phases and plugin goals defined in your `pom.xml` files. By default, the target names are the Maven phase names:

```shell
nx compile my-module
nx test my-module
nx package my-module
nx verify my-module
```

If you configure a `targetNamePrefix` (for example `mvn-`), use the prefixed targets instead:

```shell
nx mvn-test my-module
```

## Configuration

### How @nx/maven infers tasks

The plugin scans your workspace for `pom.xml` files and analyzes the Maven build to create Nx targets for phases and plugin goals. A root `pom.xml` at the workspace root is required so the analyzer can resolve the Maven project tree.

To view the inferred tasks for a module, open the [project details view](/docs/features/explore-graph#explore-projects-in-your-workspace) in Nx Console or run:

```shell
nx show project my-module --web
```

### @nx/maven configuration

Configure the plugin in the `plugins` array of `nx.json`.

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/maven",
      "options": {
        "targetNamePrefix": "mvn-",
        "verbose": false
      }
    }
  ]
}
```

| Option             | Type    | Default     | Description                                                                                 |
| ------------------ | ------- | ----------- | ------------------------------------------------------------------------------------------- |
| `targetNamePrefix` | string  | `undefined` | Prefix all inferred Maven targets to avoid name collisions in polyglot workspaces.          |
| `verbose`          | boolean | `false`     | Enable verbose logging for the Maven analyzer. Also settable via `NX_VERBOSE_LOGGING=true`. |

### Exclude or include specific projects

Use `include`/`exclude` glob patterns to scope the plugin to specific projects:

```json {% meta="{5-6}" %}
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/maven",
      "include": ["apps/**/*"],
      "exclude": ["apps/legacy-app/**/*"],
      "options": { ... }
    }
  ]
}
```

There is no per-project disable for `@nx/maven`. To stop inference entirely, remove `@nx/maven` from the `plugins` array in `nx.json`.

## CI considerations

Build and test only what changed using the project graph:

```shell
nx affected -t test package
```

Connect Nx Cloud to share cache results and speed up Maven builds in CI:

```shell
nx connect
```

### Batch mode

Batch mode runs multiple Maven tasks in a single invocation. Enable it by setting `NX_BATCH_MODE=true`:

```shell
NX_BATCH_MODE=true nx run-many -t build test
```

See [Set Up CI](/docs/guides/nx-cloud/setup-ci) for a complete configuration guide.

If you use Maven profiles or parallel builds in CI, define them in `.mvn/maven.config` (for example `-Pci` or `-T1C`) so Nx runs the same settings consistently.

## What's next

{% cardgrid %}
{% linkcard title="Java with Nx" description="Learn how Nx supports Maven and Gradle together." href="/docs/technologies/java/introduction" /%}
{% linkcard title="Gradle Plugin" description="See the Nx plugin for Gradle." href="/docs/technologies/java/gradle/introduction" /%}
{% linkcard title="Set Up CI" description="Configure fast, reliable CI for Nx workspaces." href="/docs/guides/nx-cloud/setup-ci" /%}
{% linkcard title="Maven Generators Reference" description="Full reference for @nx/maven generators." href="/docs/technologies/java/maven/generators" /%}
{% linkcard title="Maven Executors Reference" description="Full reference for @nx/maven executors." href="/docs/technologies/java/maven/executors" /%}
{% /cardgrid %}

---
<!-- source: https://nx.dev/docs/technologies/java/maven/migrations.md -->
## @nx/maven Migrations

The @nx/maven plugin provides various migrations to help you migrate to newer versions of maven projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 22.6.x

### `update-0-0-14`
**Version**: 22.6.0-beta.1

Update Maven plugin version from 0.0.13 to 0.0.14 in pom.xml files


### `update-0-0-15`
**Version**: 22.6.0-beta.12

Update Maven plugin version from 0.0.14 to 0.0.15 in pom.xml files


### `update-0-0-16`
**Version**: 22.6.0-beta.14

Update Maven plugin version from 0.0.15 to 0.0.16 in pom.xml files



## 22.5.x

### `update-0-0-13`
**Version**: 22.5.0-beta.4

Update Maven plugin version from 0.0.12 to 0.0.13 in pom.xml files



## 22.4.x

### `update-0-0-12`
**Version**: 22.4.0-beta.0

Update Maven plugin version from 0.0.11 to 0.0.12 in pom.xml files



## 22.2.x

### `update-0-0-11`
**Version**: 22.2.0-beta.4

Update Maven plugin version from 0.0.10 to 0.0.11 in pom.xml files



## 22.1.x

### `update-0.0.8`
**Version**: 22.1.0-beta.4

Update Maven plugin version from 0.0.7 to 0.0.8 in pom.xml files


### `update-0.0.9`
**Version**: 22.1.0-beta.6

Update Maven plugin version from 0.0.8 to 0.0.9 in pom.xml files


### `update-0-0-10`
**Version**: 22.1.0-rc.3

Update Maven plugin version from 0.0.9 to 0.0.10 in pom.xml files

---
<!-- source: https://nx.dev/docs/technologies/module-federation.md -->
## Module Federation

{% index_page_cards path="technologies/module-federation" /%}

---
<!-- source: https://nx.dev/docs/technologies/module-federation/concepts.md -->
## Concepts

{% index_page_cards path="technologies/module-federation/concepts" /%}

---
<!-- source: https://nx.dev/docs/technologies/module-federation/concepts/faster-builds-with-module-federation.md -->
## Faster Builds with Module Federation

As applications grow, builds can become unacceptably slow, which leads to slow CI/CD pipelines and long dev-server
startup times. This slowness
decreases team productivity due to long waits for local compilation, and clogged up CI/CD pipelines.

Module Federation provides a solution to the scaling problem by allowing a Single Page Application (SPA) to be sliced
into multiple smaller
remote applications that are built independently. There are some costs to slicing an application through Module
Federation:

- Cognitive overhead of developing multiple applications versus a SPA.
- Coordinating build and deployment across many applications is a huge headache, especially in a multi-repo setup.
- Version-Mismatch-Hell where different applications are deployed with different versions of shared libraries can lead
  to unexpected errors.

Nx provides the best experience for teams that want faster builds, but want to also minimize the downsides that come
with Module Federation. Nx provides specialized generators, executors, and utilities that make Module Federation easy to set up and work with.

## When should I use Module Federation?

Whether Module Federation makes sense for your team depends on the size of your application. Although Nx hides most of
the complexity around Module Federation, it still comes with some downsides:

- Developers need to think about which remotes they are working on, since it is a waste of CPU and memory to run _all_
  remotes in development mode. In practice this may not be a problem if the teams are already divided by domain or
  feature.
- Increased orchestration since remotes are independent of each other, shared state may require the host application to
  coordinate it between remotes. For example, sharing Redux state across remotes is more complicated versus a SPA.

{% aside type="note" title="Nx Saves Machine Resources" %}
As Nx knows the remote applications that your host application depends on, it will serve your remote applications automatically when you serve your host.
To prevent dev machines from running out of resources, and allowing for a smoother DX, a technique is employed to build your remote applications first, then
they will all be served by a single file server (`http-server`).

We have tested this in a workspace that contains 100 remote applications and found that it allows for scaling the DX very well, without causing resource issues.
{% /aside %}

## Architectural overview

With Module Federation, a large application is split into:

1. A single **Host** application that references external...
2. **Remote** applications, which handle a single domain or feature.

In the next section, we will see an example with a host app (`host`) and three remotes (`shop`, `cart`, `about`).
Although all the applications are independently built, thus have no dependency between them, conceptually you can think
of them in the following hierarchy.

![Host with implicit dependencies to remotes](../../../../../assets/concepts/module-federation/dep-graph-2.png)

## Creating an example workspace

The best way to understand the setup is through an example. we will create a `host` application with
three remotes under these routes:

1. `/shop`
1. `/cart`
1. `/about`

Before you begin, check out the example repos (React and Angular) if you want to skip ahead.

{% github_repository url="https://github.com/nrwl/ng-module-federation" /%}

{% github_repository url="https://github.com/nrwl/react-module-federation" /%}

These examples have fully
functioning [CI](https://github.com/nrwl/react-module-federation/blob/main/.github/workflows/ci.yml) [workflows](https://github.com/nrwl/ng-module-federation/blob/main/.github/workflows/ci.yml)
that are simple to set up. You can see what the CI does by viewing the sample pull requests in each repo. Also notice
the [Nx Cloud](https://nx.app) integration, which gives you insight into each pipeline. We'll touch on
This [later ](#remote-computation-caching-with-nx-cloud).

![Nx Cloud integration for GitHub](../../../../../assets/concepts/module-federation/pull-request.png)

Now, let's continue by creating an empty Nx workspace.

```shell
# Replace acme with desired scope
npx create-nx-workspace acme --preset=apps
cd acme
```

{% aside type="tip" title="Enabling remote caching" %}
You will be prompted to enable Nx Cloud in the workspace. For the best experience, we highly recommend using Nx Cloud to
take advantage of remote caching and other features it provides.
{% /aside %}

Then, for React users, install the `@nx/react` plugin; and for Angular users, install the `@nx/angular` plugin.

```shell
# If you use React
nx add @nx/react

# If you use Angular
nx add @nx/angular
```

Next, generate the host and remote applications.

{% tabs %}
{% tabitem label="React" %}

```shell
nx g @nx/react:host apps/host --remotes=shop,cart,about
```

{% /tabitem %}
{% tabitem label="Angular" %}

```shell
nx g @nx/angular:host apps/host --remotes=shop,cart,about
```

{% /tabitem %}
{% /tabs %}

{% aside type="note" title="More details" %}
You can leave off the `--remotes` option and add them later with `nx g @nx/react:remote apps/shop --host=host`
or `nx g @nx/angular:remote apps/shop --host=host`.
{% /aside %}

Now, serve `host` to view it in your browser.

```shell
nx serve host --open
```

The above command serves `host` in development mode, whereas the remotes are built and served statically. That is,
changes to `host` will update its bundle, but changes to remotes will not update.

To run one or more remotes in development mode, use the `--devRemotes` option or `run-many`.

```shell
## React
nx run-many -t serve -p "shop,cart"

## Angular
nx serve host --devRemotes="shop,cart"
```

The above command starts the `shop` and `cart` remotes in development mode, but `about` will remain static.

{% aside type="note" title="More details" %}
Note the difference in commands between React and Angular. React uses Continuous Tasks allowing remotes' `serve` target to depend on the host's `serve` target. Angular uses a single `serve` target that serves all the remotes.

Both commands serve the whole system. By passing `--devRemotes`, you configure what parts of it you will be changing.
For instance, in the example above, you can go to the about page and back. This is different from having different
versions of the app for every team.
{% /aside %}

## What was generated?

To understand how Module Federation works with Nx, let's take a look at three files that control this feature.

### `apps/host/project.json`

For React, the `build` target will be inferred by the `@nx/rspack/plugin`. It will evaluate to `rspack build`, whereas for Angular the `@nx/angular:webpack-browser` executor is used. This is the same
as a normal SPA that uses custom webpack configuration (`webpackConfig`), but difference is in the webpack configuration
file.

If you use Module Federation to speed up your CI and improve your local development, and not to deploy different remotes
independently, you need to create implicit dependencies from the host to all the remotes. Semantically, the host and the
remotes comprise one application, so you cannot build the host without the remotes. Adding implicit dependencies also
makes distributed builds possible ([see below](#production-build-and-deployment)). To create these dependencies, add
the `implicitDependencies` configuration.

```jsonc
// apps/host/project.json
{
  //...
  "implicitDependencies": ["about", "shop", "cart"],
}
```

In the future, Nx may automatically handle this for you.

### React: `apps/host/rspack.config.js`

With React, we use Rspack by default and generate a compliant Rspack configuration file:

```javascript
// apps/host/rspack.config.js
import { NxAppRspackPlugin } from '@nx/rspack/app-plugin.js';
import { NxReactRspackPlugin } from '@nx/rspack/react-plugin.js';
import {
  NxModuleFederationPlugin,
  NxModuleFederationDevServerPlugin,
} from '@nx/module-federation/rspack.js';
import { join } from 'path';

import config from './module-federation.config.js';

export default {
  output: {
    path: join(__dirname, '../../dist/apps/host'),
    publicPath: 'auto',
  },
  devServer: {
    port: 4200,
    historyApiFallback: {
      index: '/index.html',
      disableDotRule: true,
      htmlAcceptHeaders: ['text/html', 'application/xhtml+xml'],
    },
  },
  plugins: [
    new NxAppRspackPlugin({
      tsConfig: './tsconfig.app.json',
      main: './src/main.ts',
      index: './src/index.html',
      baseHref: '/',
      assets: ['./src/favicon.ico', './src/assets'],
      styles: ['./src/styles.css'],
      outputHashing: process.env['NODE_ENV'] === 'production' ? 'all' : 'none',
      optimization: process.env['NODE_ENV'] === 'production',
    }),
    new NxReactRspackPlugin({
      // Uncomment this line if you don't want to use SVGR
      // See: https://react-svgr.com/
      // svgr: false
    }),
    new NxModuleFederationPlugin({ config }, { dts: false }),
    new NxModuleFederationDevServerPlugin({ config }),
  ],
};
```

### Angular: `apps/host/webpack.config.ts`

The webpack configuration uses an utility function that Nx provides: `withModuleFederation`.

```javascript
// apps/host/webpack.config.ts
import { withModuleFederation } from '@nx/module-federation/angular';
import moduleFederationConfig from './module-federation.config';

export default withModuleFederation({
  ...moduleFederationConfig,
});
```

We'll talk about [what `withModuleFederation` does](#what-does-withmodulefederation-do) in a bit, but for now the
important part of the configuration is the use of `module-federation.config.ts` which we will examine next.

{% aside type="note" title="Extending the Webpack Config" %}
If you find yourself needing to add additional webpack plugins to your config, you can do so by following the pattern
below. This example shows how you could use it to add the `LicenseWebpackPlugin` but you can use this method to apply
any webpack plugins you need.

```js
import { withModuleFederation } from '@nx/module-federation/angular';
import config from './module-federation.config';
import { LicenseWebpackPlugin } from 'license-webpack-plugin';
import { resolve } from 'path';

export default async function (wco) {
  const wmf = await withModuleFederation(config);
  return wmf({
    ...wco,
    plugins: [
      ...(wco.plugins ?? []),
      new LicenseWebpackPlugin({
        stats: {
          warnings: false,
          errors: false,
        },
        perChunkOutput: false,
        outputFilename: '3rdpartylicenses.txt',
        skipChildCompilers: true,
        modulesDirectories: [resolve(__dirname, '../../node_modules')],
      }),
    ],
  });
}
```

{% /aside %}

### `apps/host/module-federation.config.ts`

This file is the main configuration for the `host`, and you'll see `module-federation.config.ts` for the generated
remotes as well.

```javascript
import { ModuleFederationConfig } from '@nx/module-federation';

export const config: ModuleFederationConfig = {
  name: 'host',
  remotes: ['shop', 'cart', 'about'],
};

export default config;
```

The required `name` property is the magic to link the host and remotes together. The `host` application references the
three remotes by their names.

{% aside type="note" title="More details" %}
The values in the `remotes` property must match the `name` property of the remote applications. Otherwise,
webpack will throw an error. Nx handles this automatically, so this is only a concern if you modify it manually.
{% /aside %}

## What does `withModuleFederation` do?

In the previous section, we saw `withModuleFederation` used in the webpack config. This function is an abstraction on
top of `@module-federation/enhanced` with some Nx-specific behavior.

- All libraries (npm and workspace) are shared singletons by default, so you don't manually configure them.
- Remotes are referenced by name only, since Nx knows which ports each remote is running on (in development mode).
- Access to the latest features of Module Federation (such as RuntimePlugins). Learn more at [module-federation.io](https://module-federation.io).

With Nx, the developer experience (DX) when working with Module Federation matches more closely to development on a SPA.
You don't have to worry about managing a bunch of configuration, and most things just work out of the box.

### Excluding or overriding shared libraries

There are cases where excluding or changing the shared configuration is required. For example, shared libraries are not
tree shaken, so to enable this behavior you must exclude them from being shared.

To exclude a library or change its configuration, you can provide
the `shared: (libraryName, sharedConfig) => sharedConfig` function in your configuration file.

```javascript
// module-federation.config.ts
import { ModuleFederationConfig } from '@nx/module-federation';

export const config: ModuleFederationConfig = {
  name: 'host',
  remotes: ['shop', 'cart', 'about'],
  shared: (name, config) => {
    // We want lodash to be tree shaken, and bundled into each host/remote separately.
    if (name === 'lodash') {
      return false;
    }
  },
};
```

The `shared` function can return an `undefined` to use Nx default value, `false` to exclude it from being shared, or
a [shared config](https://webpack.js.org/plugins/module-federation-plugin/#sharing-hints) that webpack supports.

{% aside type="note" title="Analysis" %}
The default configuration, without overrides, should work well for most workspaces, and we encourage you to analyze your
bundles before optimizing the shared behavior.

To analyze the size of your bundles, run build with `--statsJson` and use a tool
like [`webpack-bundle-analyzer`](https://www.npmjs.com/package/webpack-bundle-analyzer).

If you have any feedback regarding this feature, let us know on [our community page](https://nx.dev/community).
{% /aside %}

## Remote computation caching with Nx Cloud

To use Module Federation well, we recommend that you enable [Nx Cloud](https://nx.app). If you haven't enabled it yet
when using `create-nx-workspace`, create an account at [https://cloud.nx.app](https://cloud.nx.app) and connect to your repository.

With Nx Cloud enabled, a large set of builds can be skipped entirely when running the application locally (and in
CI/CD). When you run builds through Nx + Nx Cloud, the artifacts are stored in the remote cache, so as long as the
source of a given remote hasn't changed, it will be served from cache.

You can see this behavior locally if you serve the `host` twice.

```shell
nx serve host

# (kill server)

nx serve host
```

The second serve starts up much faster, because the three remotes (`shop`, `cart`, `about`) are read from cache. Not
only that, any other copy of the workspace will also benefit from the cache if they haven't changed a particular remote.
If, say, someone is working on `shop`, they will get the `cart` and `about` builds from the cache.

If you inspect the terminal output, you'll see something like this, even if you are on different machines.

```shell
> nx run about:build:development  [existing outputs match the cache, left as is]

(snip)

NX   Successfully ran target build for project about

Nx read the output from the cache instead of running the command for 1 out of 1 tasks.

```

{% aside type="note" title="More details" %}
This caching behavior is _crucial_. If you don't have a build system supporting remote computation caching, using
Module Federation will be slower. It takes longer to build `shop`, `cart` and `about` separately than building all of
them together as part of the same process.

**When using Nx, you rarely have to build all of them because most of the time you work on one remote, other remotes
will be retrieved from cache.**
{% /aside %}

This also helps things like end-to-end (E2E) testing because testing against a static server is much more efficient than
starting many servers in development mode. When the CI pipeline runs E2E tests, all the remotes should be served
statically from cache.

In addition to computation caching, Nx Cloud also comes with:

- Distributed task execution, which simplifies your CI/CD setup, and speeds up your builds.
- GitHub integration, so you can easily access important information without digging through a bunch of CI/CD logs.
- Actionable insights, which improve caching and task distribution.

![Nx Cloud run details](../../../../../assets/concepts/module-federation/nx-cloud.png)

## Production build and deployment with Nx Cloud

We'll examine how to set up your production build and simulate a deployment to `http://localhost:3000`.

First, make sure you have implicit dependencies from `host` to each remote. In case you didn't already set this up, add
the following line to the `host`'s project configuration.

```jsonc title="apps/host/project.json"
{
  //...
  "implicitDependencies": ["about", "shop", "cart"],
}
```

Next, open up the production webpack configuration file and update the remote URLs to their own sub-folder
under `http://localhost:3000`.

```javascript
// apps/host/webpack.config.prod.js
import { withModuleFederation } from '@nx/module-federation/angular';
import moduleFederationConfig from './module-federation.config';

export default withModuleFederation({
  ...moduleFederationConfig,
  remotes: [
    ['shop', 'http://localhost:3000/shop'],
    ['cart', 'http://localhost:3000/cart'],
    ['about', 'http://localhost:3000/about'],
  ],
});
```

Now you can run `nx build host` to build all the `host` and all the implicit dependencies in production mode.

{% aside type="note" title="Remote caching" %}
Again, if you don't use [Nx Cloud's Distributed Tasks Execution](/docs/features/ci-features/distribute-task-execution) using Module Federation will be slower
than building everything in a single process. It's only if you enable Distributed Tasks Execution, your CI will be able
to build each remote on a separate machine, in parallel, (or not build it at all and retrieve it from cache), which will
reduce the CI time.
{% /aside %}

After running that command you'll see the following artifacts in `dist` folder.

```text
dist/apps
├── about
├── cart
├── host
└── shop
```

Now, we can add a simple deploy command to simulate deploying this folder to production.

```shell
nx g @nx/workspace:run-commands \
deploy \
--project=host \
--command="rm -rf production && mkdir production && cp -r dist/apps/host/* production && cp -r dist/apps/{shop,cart,about} production && http-server -p 3000 -a localhost production"
```

You can then run `nx deploy host` to see the application running on `http://localhost:3000`. If you inspect
the `production` folder you'll see the following files.

```text
production/
├── about
│   ├── remoteEntry.js
│   └── (snip)
├── cart
│   ├── remoteEntry.js
│   └── (snip)
├── shop
│   ├── remoteEntry.js
│   └── (snip)
├── index.html
└── (snip)
```

The above command is just an example. You'll need to use what makes sense for your team and workspace.

For examples of how CI/CD pipelines can be configured using Nx Cloud and GitHub, see
our [React](https://github.com/nrwl/react-module-federation)
and [Angular](https://github.com/nrwl/ng-module-federation) examples.

{% github_repository url="https://github.com/nrwl/ng-module-federation" /%}

{% github_repository url="https://github.com/nrwl/react-module-federation" /%}

## Using buildable libs

By using Module Federation you essentially split your application build process vertically. You can also split it
horizontally by making some libraries buildable.

Making all libraries in your workspace buildable is not recommended. It will make some things faster but many other
things slower. But in some scenarios making a few large libraries at the bottom of your graph buildable can speed up
your CI.

Because Nx Cloud's Distributed Tasks Execution works with any task graph, having buildable libraries is handled
automatically. If you have a buildable `components` library that all remotes depend on, Nx Cloud will build the library
first before building the remotes.

## Summary

You could use Module Federation to implement [micro frontends](/docs/technologies/module-federation/concepts/micro-frontend-architecture),
but this
guide showed how to use it to speed up your builds.

Module Federation allows you to split a single build process into multiple processes which can run in parallel or even
on multiple machines. The result of each build process can be cached independently. For this to work well in practice
you need to have a build system supporting remote computation caching and distributed tasks execution (e.g., Nx +
Nx Cloud).

When a developer runs say `nx serve host --devRemotes=cart`, they still run the whole application, but `shop`
and `about` are served statically, from cache. As a result, the serve time and the time it takes to see the changes on
the screen go down, often by an order of magnitude.

When a CI machine runs say `nx build host --configuration=production`, the `shop`, `about` and `cart` remotes will
either be build on separate machines or retrieved from cache. Once all of them are built, the build process for `host`
will combine the file artifacts from all the remotes. Nx Cloud takes care of distributing the tasks and moving file
artifacts across machines. As a result, the worst case scenario build time (when nothing is cached) goes from building
all the code to building the largest remote, which is often an order of magnitude faster.

## Resources

- [React Module Federation example](https://github.com/nrwl/react-module-federation)
- [Angular Module Federation example](https://github.com/nrwl/ng-module-federation)

---
<!-- source: https://nx.dev/docs/technologies/module-federation/concepts/manage-library-versions-with-module-federation.md -->
## Manage Library Versions with Module Federation

Federated modules are bundled and packaged independently with all the dependencies they need to run smoothly in federated applications called _remotes_. This means that if you have a federated module that depends on a library, the library will be bundled with the federated module within a remote. This independence provides much flexibility, allowing individual federated modules to function without relying on external resources.

A challenge arises when these federated modules are integrated into a _host_ or other _remotes_. Given that each federated module carries its own dependencies, the host application may have inadvertently downloaded multiple copies of the same dependency. This redundancy does two things:

1. Multiple copies of the same dependency can create bottlenecks and conflicts, resulting in unexpected behaviour.
2. With redundant dependencies, the host application can become bloated, increasing the bandwidth and consuming more memory and resources on the user's device.

To mitigate these issues, Module Federation has a shared API. Its primary function is to act as a gatekeeper, ensuring that only one copy of a dependency is downloaded, regardless of how many federated modules request it.

### How it works

The Shared API maintains a registry of all the downloaded dependencies. When a federated module requests a dependency, the Shared API checks the registry. If the dependency already exists, the module is directed to use the existing copy. If not, the dependency is downloaded and added to the registry.

![How Shared API works](../../../../../assets/concepts/module-federation/shared-api.png)

{% aside type="note" title="Lost?" %}
If you are not familiar with the concepts of federated modules, remotes, and hosts, please read the [Faster builds with module federation](/docs/technologies/module-federation/concepts/faster-builds-with-module-federation) for an introduction.
{% /aside %}

## Our approach

Although the Shared API is a powerful tool, it can be challenging to manage. The Shared API is configured in the Module Federation Config File, which is a JavaScript or TypeScript file. This file is not part of the build process, so should you want to use a different version of a workspace dependency, you would have to manually record the change outside of the build process which can be tedious and error-prone.

**Nx** recommends the Single Version Policy (SVP) for managing library versions. The SVP is a simple concept: a library should have only one version in a given application. This means that if you have a workspace library used by multiple remotes and hosts, it should only have one version across all of them. The SVP becomes essential in this context for a variety of reasons:

### 1. Consistency

Ensuring that all federated modules rely on the same version of a shared dependency provides consistent behaviour across the entire application. Different library versions can have varying behaviour or bugs, leading to unexpected or inconsistent results.

### 2. Conflicts

Mixing multiple versions of a library or module in the same runtime can lead to conflicts. This is especially problematic with libraries that maintain internal state or have side effects.

### 3. API compatibility

As a library evolves, functions and methods get added, removed or changed. By ensuring a single version, you eliminate the risk of using incompatible APIs in one version but not another.

### 4. Singleton libraries

Some libraries are designed to be singletons (React, Angular, Redux, etc.). These libraries are intended to be instantiated once and shared across the entire application. Multiple versions of such libraries can break the intended behaviour or even cause runtime errors.

For these reasons, we **recommend** using the SVP to manage shared workspace libraries when using Module Federation. However, we understand that there are cases where you may want to use different versions of a library. For example, you may use a different library version in a remote than in a host. In these cases, you can opt out as described below.

## How are library versions managed?

With **Nx** there are two ways to manage how library versions are shared / managed with Module Federation:

### 1. Opt in to sharing library versions

This is the default behaviour for **Nx**. All dependencies are **singletons** and will be shared between remotes and hosts.

### 2. Opt out from sharing library versions

This means that the library will not be shared between remotes and hosts. Each remote and host will load its own version of the library.
A common use-case for this is if you want to enable tree-shaking for a library like _lodash_. If you share this library, it will be bundled with the remote and host, and tree-shaking will not be possible.

## How are library versions determined?

**Nx** determines the version of a library by looking at a `package.json`. If the library is an npm package, the version is determined by the version declared in the workspace `package.json`. If the library is a workspace library, the version is determined by the version in the `package.json` of the project that consumes the shared library. RemoteA consumes Counter, which is a workspace library exposed and shared by RemoteB. The version of Counter is determined by the version in RemoteB's `package.json`. If the `package.json` does not exist or the library is not declared, Nx will use the version in the `package.json` of the workspace library.

![How Nx determines library versions](../../../../../assets/concepts/module-federation/nx-library-version.png)

There are twos ways to manage library versions with **Nx**:

{% tabs %}
{% tabitem label="Opt out from sharing library" %}

```ts
// remote/module-federation.config.ts
import { ModuleFederationConfig } from '@nx/webpack';

const config: ModuleFederationConfig = {
  name: 'remote',
  exposes: {
    './Module': './src/remote-entry.ts',
  },
  // Determine which libraries to share
  shared: (packageName: string) {
    // I do not want to share this package and I will load my own version
    if(packageName === '@acme/utils') return false;
  }
};
export default config;
```

This would result in the following webpack config:

```js
// webpack.config.js
module.exports = {
  plugins: [
    new ModuleFederationPlugin({
      // additional config
      name: 'remote',
      shared: {
        react: { singleton: true, eager: true },
        // acme/utils will not be shared
      },
    }),
  ],
};
```

{% /tabitem %}
{% tabitem label="Opt in to sharing library versions" %}

```ts
// remote/module-federation.config.ts
import { ModuleFederationConfig } from '@nx/webpack';

const config: ModuleFederationConfig = {
  name: 'remote',
  exposes: {
    './Module': './src/remote-entry.ts',
  },
  // By not declaring a shared function, all dependencies will be shared
};
export default config;
```

This would result in the following webpack config:

```js
// webpack.config.js
module.exports = {
  // Additional config ignored for brevity
  plugins: [
    new ModuleFederationPlugin({
      // ...
      name: 'remote',
      shared: {
        react: { singleton: true, eager: true, version: '18.2.0' },
        'acme/utils': { singleton: true, eager: true, version: '1.0.0' }, // <--- This version is determined by the logic discussed earlier
      },
    }),
  ],
};
```

{% /tabitem %}
{% /tabs %}

### Github repository example

Here is a working example of how to opt in and out of sharing library versions:

{% github_repository url="https://github.com/jaysoo/module-federation-example" /%}

## Benefits

By taking advantage of **Nx**'s approach to managing library versions, you can:

- Streamline the process of updating a library version behind a versoning scheme like SemVer.
- Opt-in or out of sharing library versions with Module Federation based on your needs.
- Reduce the download size of your application by sharing workspace libraries between remotes and hosts.

---
<!-- source: https://nx.dev/docs/technologies/module-federation/concepts/micro-frontend-architecture.md -->
## Micro Frontend Architecture

Nx provides out-of-the-box [Module Federation](/docs/technologies/module-federation/concepts/faster-builds-with-module-federation) support to both
React and Angular. The Micro Frontend (MFE) architecture builds on top of Module Federation by providing _independent
deployability_.

If you have not read the [Module Federation guide](/docs/technologies/module-federation/concepts/faster-builds-with-module-federation)
yet, we recommend that you read it
before continuing with this MFE guide.

## When should I use micro frontend architecture?

We recommend MFE for teams that require applications to be deployed independently. It is important to consider the cost
of MFEs and decide whether it makes sense for your own teams.

- Version mismatches where applications are deployed with different versions of shared libraries, which can lead to
  incompatibility issues.
- Independent deployments can lead to unexpected errors, such as any host-level changes to orchestration/coordination
  logic that breaks compatibility with remotes.

If you are looking at optimizing builds and do not need independent deployments, we recommend reading our guide on
[Faster Builds with Module Federation](/docs/technologies/module-federation/concepts/faster-builds-with-module-federation).

If you need to use MFEs, keep reading, and we'll examine the architecture and strategies to deal with shared libraries
and
deployments.

## Architectural overview

With MFE architecture, a large application is split into:

1. A single **Host** application that references external...
2. **Remote** applications, which handle a single domain or feature.

In a normal Module Federation setup,
we [recommend setting up implicit dependencies](/docs/technologies/module-federation/concepts/faster-builds-with-module-federation#architectural-overview)
from the host application to remote applications. However, in an MFE architecture you _do not_ want these dependencies
to exist between host and remotes.

For example, if you have a `shell` host application, with three remotes -- `about`, `cart`, `shop` -- and a shared
`ui-button` library, then your project graph might look something like this.

![MFE setup with independent projects](../../../../../assets/concepts/module-federation/mfe-dep-graph.png)

Keeping the applications independent allows them to be deployed on different cadences, which is the whole point of MFEs.

## Generating applications

The generator for MFEs is the same as with basic Module Federation. You can use `nx g host` to create a new host
application, and `nx g remote` for remote applications.

{% tabs %}
{% tabitem label="React" %}

```shell
nx g @nx/react:host apps/shell --remotes=shop,cart
nx g @nx/react:remote apps/about --host=shell
```

{% /tabitem %}
{% tabitem label="Angular" %}

```shell
nx g @nx/angular:host apps/shell --remotes=shop,cart
nx g @nx/angular:remote apps/about --host=shell
```

{% /tabitem %}
{% /tabs %}

That is! You can now run `nx serve shell` to develop on the `shell` application, while keeping all remotes static. To
develop on one or more remote applications, you can run `nx serve shop` or `nx run-many -t serve -p shop,cart` to start
both remotes. The remotes' `serve` target depends on the `shell:serve` target, and therefore shell will be started automatically.

## Deployment strategies

How applications are deployed depends on the teams and organizational requirements. There are two approaches:

1. À la carte deployments - Each application is deployed according to a release schedule, and can have different cadences.
2. Affected deployments - When changes are merged, use Nx to test and deploy the affected applications automatically.

Often times, teams mix both approaches so deployments to staging (or other shared environments) are automatic. Then,
promotion from staging to production occurs on a set cadence (e.g. weekly releases). It is also recommended to agree on
a process to handle changes to core libraries (i.e. ones that are shared between applications). Since the core changes
affect all applications, it also blocks all other releases, thus should not occur too frequently.

You may also choose to fully automate deployments, even to production. This type of pipeline requires good end-to-end
testing to provide higher confidence that the applications behave correctly. You will also need good rollback mechanisms
in case of a bad deployment.

## Shared libraries

Since deployments with MFEs are not atomic, there is a chance that shared libraries -- both external (npm) and workspace --
between the host and remotes are mismatched. The default Nx setup configures all libraries as singletons, which requires
that all affected applications be deployed for any given changeset, and makes à la carte deployments riskier.

There are mitigation strategies that can minimize mismatch errors. One such strategy is to share as little as possible
between applications.

For example, you can create a base configuration file that only shares core libraries that _have_ to be shared.

```javascript
// module-federation.config.ts
import { ModuleFederationConfig } from '@nx/module-federation';
// Core libraries such as react, angular, redux, ngrx, etc. must be
// singletons. Otherwise the applications will not work together.
const coreLibraries = new Set([
  'react',
  'react-dom',
  'react-router-dom',
  // A workspace library for a publish/subscribe
  // system of communication.
  '@acme/pub-sub',
]);

export const config: ModuleFederationConfig = {
  // Share core libraries, and avoid everything else
  shared: (libraryName, defaultConfig) => {
    if (coreLibraries.has(libraryName)) {
      return defaultConfig;
    }

    // Returning false means the library is not shared.
    return false;
  },
};

export default config;
```

Then, in the `shell` and remote applications, you can extend from the base configuration.

```javascript
// apps/shell/module-federation.config.ts
import { ModuleFederationConfig } from '@nx/module-federation';
import baseConfig from '../../module-federation.config';

export const config: ModuleFederationConfig = {
  ...baseConfig,
  name: 'shell',
  remotes: ['shop', 'cart', 'about'],
};

export default config;
```

{% aside type="note" title="More details" %}
You can return any configuration [object that webpack/rspack's Module Federation supports](https://webpack.js.org/plugins/module-federation-plugin/#sharing-hints).
{% /aside %}

There are downsides to not sharing a library (such as increasing network traffic due to duplication), so consider what
you share carefully. If you are not sure, then start with a small set of core libraries, and expand it as needed.

## Strategic collaboration over micro frontend anarchy

[Micro frontend anarchy](https://www.thoughtworks.com/en-ca/radar/techniques/micro-frontend-anarchy) refers to an MFE
setup that mixes a range of competing technologies together. For example, using Angular in some applications, and React
in another. Although it is possible to do this mixing with MFEs, we recommend choosing strategic collaboration instead.

Teams should agree upon a set of adopted technologies, such as UI/backend framework, styling solutions (CSS vs CSS-in-JS),
etc. Standardizing technologies enable developers to collaborate across teams more easily, since there is consistency
in each vertical. The only time mixing competing technologies make sense is as a part of a deliberate transition strategy,
such as migrating from React to Vue, for example.

## Summary

While Module Federation enables faster builds by vertically slicing your application into smaller ones, the
MFE architecture layers _independent deployments_ on top of federation. Teams should only choose MFEs
if they want to deploy their host and remotes on different cadences.

Teams should consider a process for changes to core libraries that require deploying all applications. These types of
changes should occur infrequently as to not disrupt other releases for bug fixes or new features.

Since deployments are not atomic, there can be cases of mismatched libraries between the host and remotes. We recommend
that teams deploy their applications whenever changes to a shared library affects them. You can further mitigate mismatch
issues by minimizing the amount of libraries you share (using the `shared` configuration option in
`module-federation.config.ts`).

Teams should also avoid MFE anarchy, where competing technologies are mixed together. Instead, teams should agree upon
the adopted technologies, which allows easier collaboration across teams.

---
<!-- source: https://nx.dev/docs/technologies/module-federation/concepts/module-federation-and-nx.md -->
## Module Federation and Nx

Module Federation is a technique that allows developers to share code and resources across multiple applications. It has become more popular in recent years since the addition of the [ModuleFederationPlugin](https://webpack.js.org/plugins/module-federation-plugin/) in [Webpack](https://webpack.js.org).

{% aside type="note" title="Nx uses @module-federation/enhanced" %}
As of Nx 19.5, our Module Federation support is provided by the [@module-federation/enhanced](https://npmjs.com/@module-federation/enhanced) package.
This package is owned and maintained by [Zack Jackson](https://x.com/ScriptedAlchemy), the creator of Module Federation, and the [ByteDance](https://x.com/ByteDanceTalk) team.

Using this package for Nx Module Federation support keeps our support aligned with the latest improvements, features and bug fixes for Module Federation.

You can learn more about Module Federation Enhanced on their [docs](https://module-federation.io/).
{% /aside %}

An increasing number of enterprise applications have started to adopt Module Federation to help them develop and scale their applications quickly, while reducing some overhead in sharing code between teams.

Nx added out-of-the-box support for Module Federation with Webpack to make it more approachable, less complex and leverage some unique benefits that can only be realised in a monorepo.

## What is Module Federation?

Module Federation is a method in which code can be split into smaller deployable modules that can be shared and consumed at runtime between applications.  
This method allows for the development of Micro Frontends which can reduce coordination between teams and allow for a faster development cycle with each team adhering to its own release cadence.

{% aside type="caution" title="Release Cadences" %}
Although teams can adhere to their own release cadence, some changes should still be coordinated with teams, such as package upgrades, as this can lead to an incompatibility and unexpected behaviour between the applications within the Module Federation Architecture.

For example, upgrading Angular or React to the latest version should be coordinated to prevent any issues where different versions are loaded at runtime, causing unexpected behaviour.
{% /aside %}

In order to achieve this, Module Federation introduces three terms for the applications that make up the Module Federation architecture; `host`, `remote` and `federated modules`.

### What is a remote?

A `remote` is an application that exposes a federated module that can be fetched over the network at runtime. The federated module can be any valid JavaScript module, and therefore grows to include things such as a React Component, an Angular Routing File, a plain old JavaScript object (POJO) and more.

{% aside type="note" title="Creating a Remote" %}

Follow our [How to Create a Remote Application Recipe](/docs/technologies/module-federation/guides/create-a-remote) to learn more.

{% /aside %}

### What is a host?

A `host` is an application that consumes federated modules from `remote` applications at runtime.

When you write your host application, you import the module from your remote as though it was part of the build, but at build time, Webpack is aware that this module will only exist at runtime, and only after it has made a network request to the corresponding remote application to fetch the JS bundle.

The federated module will then be executed as though it was always part of the `host` application.

{% aside type="note" title="Creating a Host" %}

Follow our [How to Create a Host Application Recipe](/docs/technologies/module-federation/guides/create-a-host) to learn more.

{% /aside %}

### What is a federated module?

A `federated module` is any valid JavaScript module that is exposed by a `remote` application with the aim that it will be consumed by a `host` application.

This means that React Components, Angular Components, Services, Application State, Functions, UI Components and more can be shared between applications and updated without the need to redeploy everything.

{% aside type="note" title="Federating a Module" %}

Follow our [How to Federate a Module Recipe](/docs/technologies/module-federation/guides/federate-a-module) to learn more.

{% /aside %}

### Common pitfalls

Module Federation is not without its complexity, especially if you choose to use it to enable independent deployments where independent `remotes` are deployed on different release cadences. Some of the pitfalls you might encounter are listed below:

#### Increased bundle size

Module Federation allows you to share third-party packages across `remotes` and `hosts`, which can be essential in cases such as `react`, `react-dom` and `@angular/*` packages. This means that when you load a `federated module` from a `remote`, Webpack does not need to re-download a copy of these packages. Instead, the `federated module` uses the already loaded packages.

However, when third-party packages are shared between `remotes` and `hosts`, Webpack is unable to perform efficient tree-shaking on those packages as it is unaware of exactly what code will be used by any of the remotes. This can lead to an increased bundle size for some third-party packages.

A solution to help mitigate the impact of this is to only share exactly what is necessary between `remotes` and `hosts`.

#### Managing versions

Module Federation also supports the ability to manage the versions of third-party packages that are compatible across `remotes` and `hosts`. This support ensures that each `federated module` works with a version of the package it was intended to use, but it can also add some overhead on ensuring that the package versions remain up to date.

Versioned packages and libraries can cause further issues if they store internal state or use a Singleton to manage a single instance across your application. If a `remote` is deployed with a new version of the package or library, there is the possibility that your `federated module` will download a new copy of that package if your `host` does not have the same version it is expecting.

Having multiple versions of a package would then break the package's Singleton nature as there will now be multiple instances of it running.

{% aside type="note" title="Managing Versions" %}

Follow our [Manage Library Versions Guide](/docs/technologies/module-federation/concepts/manage-library-versions-with-module-federation) to learn more.

{% /aside %}

## Nx support for Module federation

Nx offers out-of-the-box support for Module Federation with React and Angular. There are a number of features that can assist you when developing a Module Federation architecture for your application, such as:

- Generators - to aid in scaffolding `remotes`, `hosts` and `federated modules`
- Executors - to aid in building your applications with Module Federation and for great DX when developing locally
- Type Safety - allowing for type-safety between `hosts` and `remotes` to catch issues early and to take advantage of autocompletion in IDEs
- Versioning of Libraries - to aid in preventing some common issues regarding incompatible package versions being used by `federated modules`
- Scaling DX - techniques to ensure a smooth DX regardless of the number of remotes in the workspace

### Develop as a user

For both the best DX (Development Experience) and most accurate development of a Module Federation architecture we recommend viewing it as a single application. In other words, the `host` and all the `remotes` are composed to form a single application.

The `host` is the entry point and the `remotes` are modules used by the application. It just happens that the `remotes` are fetched over-the-wire at runtime rather than being bundled into the application.

To support this, as well as to ensure a great local DX, we built our Module Federation support in such a way that when developing locally you should always run `serve` on your `host` application. This will start up your full Module Federation architecture; serving your `host` with `webpack-dev-server` and each `remote` via a single `http-server`. You can learn more about this on our [Nx Module Federation Technical Overview](/docs/technologies/module-federation/concepts/nx-module-federation-technical-overview).

With the introduction of Continuous Tasks in Nx 21 when you're working on a specific `remote` application, you now only need to run `nx serve remote` and it will serve the application along with your `host` application.

{% aside type="note" title="Continuous Tasks Support in Module Federation" %}
This is currently only supported for Rspack Module Federation using the `@nx/rspack/plugin` Inference Plugin.
{% /aside %}

If you are using Webpack Module Federation, or are not using [Inferred Tasks](/docs/concepts/inferred-tasks), you should use the `--devRemotes` option to specify the `remote` you are currently developing; e.g. `nx serve host --devRemotes=remote1`. This ensures that the `remote` is served via `webpack-dev-server` allowing for HMR and live reloading.

## Use cases

Nx has identified some common use cases that have made developers reach for Module Federation. They are Faster Builds and Independent Deployability.

### Faster builds

As Module Federation allows you to split your application into smaller deployable chunks that are only required at runtime, you can take advantage of this to reduce the build times of your application.

You can run the builds of multiple smaller applications in parallel and deploy all of them together, maintaining a single release cadence and coordination across teams but benefiting with reduced build times locally for developers and in CI.

If you add [Nx Cloud](https://nx.app) to your Nx Workspace, then you can even get cache hits from some of the builds from other team members and CI, reducing the build time further.

{% aside type="note" title="Faster Builds with Module Federation" %}

Follow our [Faster Builds with Module Federation Guide](/docs/technologies/module-federation/concepts/faster-builds-with-module-federation) to learn more.

{% /aside %}

### Independent deployability

Independent Deployability is the concept where individual teams within an organization deploy their work on their own release cadence, regardless of other teams, allowing for more team autonomy. This can be achieved with Module Federation and becomes more and more appealing as the organization and application grows.

With Module Federation, each team can own a `remote` that can be deployed when needed, and it will be consumed by the `host` application as expected, allowing for updates to that `remote` to be made without the need to redeploy everything.  
This lends itself to more of a Micro Frontend approach.

{% aside type="note" title="Micro Frontend Architecture" %}

Follow our [Micro Frontend Architecture Guide](/docs/technologies/module-federation/concepts/micro-frontend-architecture) to learn more.

{% /aside %}

You can also check out our example repository for Independent Deployability with Module Federation and Nx below:

{% github_repository url="https://github.com/jaysoo/module-federation-example/tree/main" /%}

---
<!-- source: https://nx.dev/docs/technologies/module-federation/concepts/nx-module-federation-technical-overview.md -->
## Nx Module Federation Technical Overview

Nx Module Federation support is provided through a mixture of `executors` and the `withModuleFederation()` util that is used in your `webpack.config` or `rspack.config` file. Understanding what is happening under the hood can help when developing applications that use Module Federation as well as debugging any potential issues you run into.
With Rspack, Module Federation support can also be provided through the [`NxModuleFederationPlugin`](/docs/technologies/module-federation/guides/nx-module-federation-plugin) and [`NxModuleFederationDevServerPlugin`](/docs/technologies/module-federation/guides/nx-module-federation-dev-server-plugin) plugins that can be used in the `rspack.config` file when utilizing [Inferred Tasks](/docs/concepts/inferred-tasks).

## What happens when you serve your host?

When you serve your host application via `nx serve host`, the Nx `module-federation-dev-server` executor or `NxModuleFederationDevServerPlugin` is invoked. These do a few things that aim to provide a more holistic local development while ensuring a great DX (development experience).

{% aside type="note" title="Using Module Federation with SSR?" %}
The same technique outlined below also applies to the `module-federation-ssr-dev-server` and the `NxModuleFederationSSRDevServerPlugin`.
This is important to know when it comes to deploying your SSR Module Federation application as it indicates that you can place the build artifacts from the `remotes` onto something like an Amazon S3 Bucket and your `host` will be able to find these files correctly.
{% /aside %}

The executor does the following:

1. Finds all the `remotes` that the `host` depends on.
2. Determines which `remotes` need to be served statically and which need to be served via `webpack-dev-server`.
3. For the `static remotes`, it will invoke `nx run-many -t build --projects={listOfStaticRemotes}`.
4. If required, it will move the built artifacts of each `remote` to a common directory.
5. It will run `http-server` at the common directory such that those files are available on the network from a single port.
6. It will create proxy servers via `express` listening on the ports where each `remote` _should_ be located (as configured in the host's `module-federation.config.ts` or `module-federation.manifest.json` file).
   - These proxy servers will proxy requests from the server to the `http-server` to fetch the correct files as requested by Module Federation.
7. **Only Applicable for Executor Usage**: If the `--devRemotes` option has been passed, it will serve each `dev remote` via `webpack-dev-server` allowing for HMR and live reloading when working on those remotes.
8. It will serve the `host` via `webpack-dev-server`.

If you prefer diagrams, the one below outlines the above steps.

![Nx Module Federation Host Serve Flow](../../../../../assets/concepts/module-federation/module-federation-host-serve-light.png)

## Using Module federation with continuous tasks

Continuous Tasks are a new feature in Nx 21. Using Rspack Module Federation, you can now use Continuous Tasks to serve your `remotes` and `host` application.

Thanks to the benefits of Continuous Tasks, you no longer need to run `nx serve host --devRemotes=remote` to serve your `host` application with HMR enabled for your remote applications.  
Instead, you can run `nx serve remote` and it will serve the `remote` along with your `host` application with HMR enabled.

This is a great way to develop your application locally and have a great DX. It also makes it easier to explain to your team how to work with Module Federation as there is no longer any special command required to serve their application.

{% aside type="note" title="Using Continuous Tasks with Webpack Module Federation?" %}
Webpack Module Federation does not support Continuous Tasks. If you are using Webpack Module Federation, you should use the `--devRemotes` option to specify the `remote` you are currently developing; e.g. `npx nx serve host --devRemotes=remote`.
{% /aside %}

## The `NxRuntimeLibraryControlPlugin`

Previously, when using shared workspace libraries as part of your Module Federation application, there was a chance that the workspace library would be provided by one of the `static remotes`. This would cause issues where changes to those shared libraries would not be reflected in the locally served application.

To combat this issue, we developed the `NxRuntimeLibraryControlPlugin`. This is a _Runtime Plugin_ that will ensure that workspace libraries are only shared via any active `dev remote`. This means that any changes to the shared library will be picked up by `webpack-dev-server` and, as such, reflected in the locally served application.

This plugin is enabled by default, however, you can turn it off in your `module-federation.config` file:

```ts
export const config: ModuleFederationConfig = {
  ...,
  disableNxRuntimeLibraryControlPlugin: true
}
```

---
<!-- source: https://nx.dev/docs/technologies/module-federation/guides.md -->
## Guides

{% index_page_cards path="technologies/module-federation/guides" /%}

---
<!-- source: https://nx.dev/docs/technologies/module-federation/guides/create-a-host.md -->
## Creating a Module Federation Host

A `host` is the term within [Module Federation](https://module-federation.io/docs/en/mf-docs/0.2/getting-started/) given
to an application that loads and consumes federated modules
from `remotes`. At build time, these modules do not exist and are instead fetched via a network request and executed at
runtime. It can be likened to a modern-day approach to iframes.  
A host can be configured to know the location of the federated modules at build time _(called Static Federation)_ or it
can employ a mechanism to discover the location of the federated modules at runtime, usually on startup _(called Dynamic
Federation)_.

**Nx** includes first-class support for helping you to scaffold a Module Federation Architecture for your React and
Angular application(s).

## Generating a host

To generate only a host application in your workspace, run the following command:

{% tabs %}
{% tabitem label="React" %}

```shell
nx g @nx/react:host apps/react/shell
```

{% /tabitem %}
{% tabitem label="Angular" %}

```shell
nx g @nx/angular:host apps/angular/shell
```

{% /tabitem %}
{% /tabs %}

### Scaffold a host with remotes

To scaffold a host application along with remote applications in your workspace, run the following command:

{% tabs %}
{% tabitem label="React" %}

```shell
nx g @nx/react:host apps/react/with-remotes/shell --remotes=remote1,remote2
```

{% /tabitem %}
{% tabitem label="Angular" %}

```shell
nx g @nx/angular:host apps/angular/with-remotes/shell --remotes=remote1,remote2
```

{% /tabitem %}
{% /tabs %}

## Serving your host

Your `host` application acts like any other application in the context of Nx, and therefore serving it locally is as
simple as running:

```shell
nx serve shell
```

When you serve your `host`, Nx will discover any dependent remote applications that are also in the workspace and serve them statically. To learn more about check out our in-depth breakdown of [what happens when you serve your host](/docs/technologies/module-federation/concepts/nx-module-federation-technical-overview#what-happens-when-you-serve-your-host).

## Building your host

In the same vein, you can build your host by running:

```shell
nx build shell
```

To support [Independent Deployability](/docs/technologies/module-federation/concepts/module-federation-and-nx#independent-deployability) `host` applications do not have `implicitDependencies` set in their `project.json`. If you want to build all your `remotes` when you build your `host`, add `implicitDependencies` to your `host`'s `project.json` with each `remote` listed:

```json
{
  ...,
  "implicitDependencies": ["remote1", "remote2"]
}
```

---
<!-- source: https://nx.dev/docs/technologies/module-federation/guides/create-a-remote.md -->
## Creating a Module Federation Remote

In the concept of Module Federation a `remote` is the term given to an application that exposes modules that can be
shared to and consumed by host applications.  
This is the key difference between a `remote` and `host`.

- A `remote` exposes modules that can be consumed
- A `host` consumes exposed modules

**Nx** includes first-class support for helping you to scaffold a Module Federation Architecture for your React and
Angular application(s).

## Generating a remote

To generate a remote application in your workspace, cd into the right folder and run the following command:

{% tabs %}
{% tabitem label="React" %}

```text {% title="nx g @nx/react:remote --name=myremote" frame="terminal" %}
NX  Generating @nx/react:remote

CREATE apps/react/myremote/src/app/app.spec.tsx
CREATE apps/react/myremote/src/assets/.gitkeep
CREATE apps/react/myremote/src/environments/environment.prod.ts
CREATE apps/react/myremote/src/environments/environment.ts
CREATE apps/react/myremote/src/favicon.ico
CREATE apps/react/myremote/src/index.html
CREATE apps/react/myremote/tsconfig.app.json
CREATE apps/react/myremote/rspack.config.ts
CREATE apps/react/myremote/.babelrc
CREATE apps/react/myremote/src/app/nx-welcome.tsx
CREATE apps/react/myremote/src/app/app.module.css
CREATE apps/react/myremote/src/app/app.tsx
CREATE apps/react/myremote/src/styles.css
CREATE apps/react/myremote/tsconfig.json
CREATE apps/react/myremote/project.json
CREATE apps/react/myremote/.eslintrc.json
CREATE apps/react/myremote/jest.config.ts
CREATE apps/react/myremote/tsconfig.spec.json
CREATE apps/react/myremote/src/bootstrap.tsx
CREATE apps/react/myremote/module-federation.config.ts
CREATE apps/react/myremote/src/main.ts
CREATE apps/react/myremote/src/remote-entry.ts
UPDATE tsconfig.base.json
```

{% /tabitem %}
{% tabitem label="Angular" %}

```text {% title="nx g @nx/angular:remote apps/angular/myremote" frame="terminal" %}
NX Generating @nx/angular:host

CREATE apps/angular/myremote/project.json
CREATE apps/angular/myremote/src/assets/.gitkeep
CREATE apps/angular/myremote/src/favicon.ico
CREATE apps/angular/myremote/src/index.html
CREATE apps/angular/myremote/src/styles.css
CREATE apps/angular/myremote/tsconfig.app.json
CREATE apps/angular/myremote/tsconfig.json
CREATE apps/angular/myremote/src/app/app.ts
CREATE apps/angular/myremote/src/app/app.routes.ts
CREATE apps/angular/myremote/src/main.ts
CREATE apps/angular/myremote/.eslintrc.json
CREATE apps/angular/myremote/jest.config.ts
CREATE apps/angular/myremote/src/test-setup.ts
CREATE apps/angular/myremote/tsconfig.spec.json
CREATE apps/angular/myremote/src/app/remote-entry/entry.ts
CREATE apps/angular/myremote/src/app/remote-entry/entry.routes.ts
CREATE apps/angular/myremote/src/app/remote-entry/nx-welcome.ts
CREATE apps/angular/myremote/module-federation.config.ts
CREATE apps/angular/myremote/webpack.config.ts
CREATE apps/angular/myremote/webpack.prod.config.ts
CREATE apps/angular/myremote/src/bootstrap.ts
UPDATE tsconfig.base.json
```

{% /tabitem %}
{% /tabs %}

After the `remote` application is generated, you can then update your host application's Module Federation Config File
to specify that it can consume federated modules from this remote.

{% tabs %}
{% tabitem label="TypeScript Config File" %}

```typescript
// apps/react/shell/module-federation.config.ts
import { ModuleFederationConfig } from '@nx/module-federation';

const config: ModuleFederationConfig = {
  name: 'shell',
  remotes: ['myremote'], // <-- add the name of your remote to the remotes array
};
export default config;
```

{% /tabitem %}

{% tabitem label="JavaScript Config File" %}

```typescript
// apps/react/shell/module-federation.config.js
module.exports = {
  name: 'shell',
  remotes: ['myremote'], // <-- add the name of your remote to the remotes array
};
```

{% /tabitem %}
{% /tabs %}

{% aside type="note" title="Creating a Host" %}
If you do not already have a host application in your workspace, look at
the [create a host guide](/docs/technologies/module-federation/guides/create-a-host) for more information on how to achieve
this.
{% /aside %}

### Let Nx add your remote to your host

The `remote` generators also allow you to specify a `--host` option, which will allow the generator to add your remote
to your host automatically. This can save you time by skipping the manual step above.  
The command would look like the following:

{% tabs %}
{% tabitem label="React" %}

```text {% title="nx g @nx/react:remote apps/react/myremote --host=shell" frame="terminal" %}
NX  Generating @nx/react:remote

CREATE apps/react/myremote/src/app/app.spec.tsx
CREATE apps/react/myremote/src/assets/.gitkeep
CREATE apps/react/myremote/src/environments/environment.prod.ts
CREATE apps/react/myremote/src/environments/environment.ts
CREATE apps/react/myremote/src/favicon.ico
CREATE apps/react/myremote/src/index.html
CREATE apps/react/myremote/tsconfig.app.json
CREATE apps/react/myremote/rspack.config.ts
CREATE apps/react/myremote/.babelrc
CREATE apps/react/myremote/src/app/nx-welcome.tsx
CREATE apps/react/myremote/src/app/app.module.css
CREATE apps/react/myremote/src/app/app.tsx
CREATE apps/react/myremote/src/styles.css
CREATE apps/react/myremote/tsconfig.json
CREATE apps/react/myremote/project.json
CREATE apps/react/myremote/.eslintrc.json
CREATE apps/react/myremote/jest.config.ts
CREATE apps/react/myremote/tsconfig.spec.json
CREATE apps/react/myremote/src/bootstrap.tsx
CREATE apps/react/myremote/module-federation.config.ts
CREATE apps/react/myremote/src/main.ts
CREATE apps/react/myremote/src/remote-entry.ts
UPDATE apps/react/shell/module-federation.config.ts
UPDATE tsconfig.base.json
```

{% /tabitem %}
{% tabitem label="Angular" %}

```text {% title="nx g @nx/angular:remote apps/angular/myremote --host=shell" frame="terminal" %}
> NX Generating @nx/angular:host

CREATE apps/angular/myremote/project.json
CREATE apps/angular/myremote/src/assets/.gitkeep
CREATE apps/angular/myremote/src/favicon.ico
CREATE apps/angular/myremote/src/index.html
CREATE apps/angular/myremote/src/styles.css
CREATE apps/angular/myremote/tsconfig.app.json
CREATE apps/angular/myremote/tsconfig.json
CREATE apps/angular/myremote/src/app/app.ts
CREATE apps/angular/myremote/src/app/app.routes.ts
CREATE apps/angular/myremote/src/main.ts
CREATE apps/angular/myremote/.eslintrc.json
CREATE apps/angular/myremote/jest.config.ts
CREATE apps/angular/myremote/src/test-setup.ts
CREATE apps/angular/myremote/tsconfig.spec.json
CREATE apps/angular/myremote/src/app/remote-entry/entry.ts
CREATE apps/angular/myremote/src/app/remote-entry/entry.routes.ts
CREATE apps/angular/myremote/src/app/remote-entry/nx-welcome.ts
CREATE apps/angular/myremote/module-federation.config.ts
CREATE apps/angular/myremote/webpack.config.ts
CREATE apps/angular/myremote/webpack.prod.config.ts
CREATE apps/angular/myremote/src/bootstrap.ts
UPDATE apps/angular/shell/module-federation.config.ts
UPDATE tsconfig.base.json
```

{% /tabitem %}
{% /tabs %}

## Building your remote

Your `remote` application acts like any other application in the context of Nx, and therefore building it as simple as
running:

```shell
nx build myremote
```

## Serving your remote

The `remote` application is generated with two serve-like targets. These are:

- serve
- serve-static

They can be run as usual with Nx:

```shell
nx serve myremote
nx serve-static myremote
```

### Serve target

The `serve` target will use `webpack-dev-server` to serve your application, allowing for HMR and Live Reload. This is
useful when you're working locally on that specific remote application.

### Serve-static target

The `serve-static` target will first build your application, storing the build artifact in the defined output directory
_(usually `dist/path/to/remote`)_. It will then use `http-server` to serve the built application locally.  
This is less memory and CPU intensive than `webpack-dev-server` but it does not support HMR or Live Reload.

The purpose of the `serve-static` target is to allow you to serve your `host` application, along with all of
the `remote` applications it depends on without being too resource intensive.

This has been further expanded upon. When you serve the `host` application, Nx will build (or pull from cache) your
`remote` applications and serve them all via a single file server, to further reduce resource consumption.

### Serving your remote via your host

Generally, your `host` is the main application that you deploy and that users visit. It consumes modules from `remote`
applications, but those `remote` applications are usually never visited directly by a user.  
Therefore, to support developing your application in a manner that replicates how users use the application, when
serving a `host` application, Nx will serve all the dependent remotes automatically.

By default, the dependent `remote` applications will be served via the `serve-static` command. However, if you are
working on a specific remote application, you can tell Nx to serve the `host` application and any number of `remote`
applications via the `webpack-dev-server` allowing those remote applications to take advantage of HMR and Live Reloading
as you work on them.

To do this, run the command:

```shell
## React
nx serve myremote

## Angular
```

This informs Nx to run the `serve` command of `myremote`, rather than the `serve-static` command.

---
<!-- source: https://nx.dev/docs/technologies/module-federation/guides/federate-a-module.md -->
## Federate a Module

Module Federation is a concept that allows developers to share code between applications at run-time. It is a way of doing micro-frontends, but it can also be used to share code between applications that are not micro-frontends.

In the context of Module Federation, a _module_ can be thought as any piece of code, functionally independent, that can be reused in different applications. It can be a component, a service, a library, a utility, etc.

In order to share a module, it must be _federated_. This means that the module must be configured to be shared, and the application that wants to use it must be configured to use it.

**Nx** includes first-class support for Module Federation for React and Angular applications. This means that you can federate modules in your workspace with a few simple commands.

{% aside type="note" title="Assumption" %}
With this recipe we assume that you have already created a workspace with at least one React or Angular Module Federation host application.
If you haven't, you can follow the [Create a Host Recipe](/docs/technologies/module-federation/guides/create-a-host).
{% /aside %}

## Step 1: Create the module

We will create a module that exports a hello function.
Since we are using Nx, we will create a library for this module.

**Create a library**

```shell
nx generate @nx/js:library hello --unitTestRunner=jest
```

Update the `hello.ts` file with the following code:

```typescript
// hello/src/lib/hello.ts
export default function hello(): string {
  return 'Hello from Nx';
}
```

Update `hello/` barrel file `index.ts` with the following code:

```typescript
// hello/src/index.ts
export { default } from './lib/hello';
```

## Step 2: Federate the module

Now that we have created the module, we need to configure it to be federated.

{% tabs %}
{% tabitem label="React" %}

```shell
nx generate @nx/react:federate-module hello/src/index.ts --name=hello --remote=greeting
```

{% /tabitem %}
{% tabitem label="Angular" %}

```shell
nx generate @nx/angular:federate-module hello/src/index.ts --name=hello --remote=greeting
```

{% /tabitem %}
{% /tabs %}

{% aside type="note" title="Remote does not exist" %}
If the remote provided does not exist (in this instance _greeting_), Nx will create it for you.
{% /aside %}

This command will:

- Adds a module entry to the `greeting` remote module federation config file.

{% tabs %}
{% tabitem label="Typescript Config File" %}

```typescript
// greeting/module-federation.config.ts
import { ModuleFederationConfig } from '@nx/module-federation';

const config: ModuleFederationConfig = {
  name: 'greeting',
  exposes: {
    './Module': './src/remote-entry.ts',
    './Hello': 'hello/src/index.ts', // <-- this line was added,
  },
};
export default config;
```

{% /tabitem %}
{% tabitem label="Javascript Config File" %}

```javascript
// greeting/module-federation.config.js
module.exports = {
  name: 'greeting',
  exposes: {
    './Module': './src/remote-entry.ts',
    './Hello': 'hello/src/index.ts', // <-- this line was added
  },
};
```

{% /tabitem %}
{% /tabs %}

- Adds a Typescript path mapping to the `greeting/Hello` module in your root TSConfig file.

```json
// /tsconfig.base.json
{
  "paths": {
    "greeting/Module": ["greeting/src/remote-entry.ts"],
    "greeting/Hello": ["hello/src/index.ts"] // <-- this line was added
  }
}
```

## Step 3: Use the module

Update the host application to use the federated module.

{% tabs %}
{% tabitem label="Typescript Config File" %}

```ts
// host/module-federation.config.ts
import { ModuleFederationConfig } from '@nx/module-federation';

const config: ModuleFederationConfig = {
  name: 'host',
  remotes: ['greeting'], //  <-- Ensure that greeting remote is listed here
};

export default config;
```

{% /tabitem %}
{% tabitem label="Javascript Config File" %}

```javascript
// host/module-federation.config.js
module.exports = {
  name: 'host',
  remotes: ['greeting'], //  <-- Ensure that greeting remote is listed here
};
```

{% /tabitem %}
{% /tabs %}

```tsx
// host/src/app/app.tsx
import hello from 'greeting/Hello';

export function App() {
  return <div>{hello()}</div>;
}

export default App;
```

If you are using Angular, you would update the application in a similar fashion to use the federated module.

## Step 4: Run the application

Just run the application as usual.

```shell
nx serve host
```

To start the application, use the following address: [http://localhost:4200](http://localhost:4200). Once opened, you'll see the message **"Hello from Nx"**. This message is loaded from the greeting remote, which runs on port 4201.

---
<!-- source: https://nx.dev/docs/technologies/module-federation/guides/nx-module-federation-dev-server-plugin.md -->
## NxModuleFederationDevServerPlugin

The `NxModuleFederationDevServerPlugin` and `NxModuleFederationSSRDevServerPlugin` are [Rspack](https://rspack.dev) plugins that handle the development server for module federation in Nx Workspaces. They aim to provide the same Developer Experience(DX) that you would normally receive from using Nx `module-federation-dev-server` executors in a non-executor ([Inferred Tasks](/docs/concepts/inferred-tasks)) project.

## Usage

To use the plugin, you need to add it to your `rspack.config.ts` file. You can do this by adding the following to your config.

### Client side rendering

```ts
// rspack.config.ts
import { NxModuleFederationDevServerPlugin } from '@nx/module-federation/rspack';
import config from './module-federation.config';

export default {
  ...otherRspackConfigOptions,
  plugins: [
    new NxModuleFederationDevServerPlugin({
      config,
    }),
  ],
};
```

### Server side rendering

```ts
// rspack.config.ts
import { NxModuleFederationSSRDevServerPlugin } from '@nx/module-federation/rspack';
import config from './module-federation.config';

export default {
  ...otherRspackConfigOptions,
  plugins: [
    new NxModuleFederationSSRDevServerPlugin({
      config,
    }),
  ],
};
```

## How it works

The `NxModuleFederationDevServerPlugin` and `NxModuleFederationSSRDevServerPlugin` will serve the remote applications in via a single file server (using `http-server`) and proxy requests to the remote applications to the correct port. This allows for a more streamlined development experience when working with module federation.
You can learn more about this experience in the [Module Federation Technical Overview](/docs/technologies/module-federation/concepts/nx-module-federation-technical-overview).

The key difference between `NxModuleFederationDevServerPlugin` and `NxModuleFederationSSRDevServerPlugin` is that the latter will handle both `browser` and `server` bundles to support Server Side Rendering (SSR). It will also serve the host/consumer application by forking ([child_process.fork](https://nodejs.org/api/child_process.html#child_processforkmodulepath-args-options)) the `server.js` output from the `server` bundle of the host application.

## Deployment

How applications are deployed depends on the teams and organizational requirements. There are two approaches:

1. À la carte deployments - Each application is deployed according to a release schedule, and can have different cadences.
2. Affected deployments - When changes are merged, use Nx to test and deploy the affected applications automatically.

Often times, teams mix both approaches so deployments to staging (or other shared environments) are automatic. Then,
promotion from staging to production occurs on a set cadence (e.g. weekly releases). It is also recommended to agree on
a process to handle changes to core libraries (i.e. ones that are shared between applications). Since the core changes
affect all applications, it also blocks all other releases, thus should not occur too frequently.

You may also choose to fully automate deployments, even to production. This type of pipeline requires good end-to-end
testing to provide higher confidence that the applications behave correctly. You will also need good rollback mechanisms
in case of a bad deployment.

When figuring out the best deployment strategy, or even how to achieve it with Module Federation and Nx, it is worth understanding what is happening under-the-hood.
Each host and remote in your Module Federation system is treated like a separate application. However, when a remote is loaded into a host via Module Federation, Module Federation itself does not make any kind of distinguishment.
It only cares that the JS file it is trying to load is available at the pre-specified URL, such that it can make a network request to fetch the JS file.

When working locally, Nx parses the configuration in `module-federation.config.ts` to identify the local federated projects. Nx then examines the project graph to determine the port on which each project will be served. This information is used to create a URL informing Module Federation where to locate the remote JS files.
You'll commonly see the following configuration in your `module-federation.config.ts`:

```javascript
// module-federation.config.ts
export default {
  remotes: ['shop', 'cart'],
};
```

These names match the names of the projects in the workspace. Therefore, Nx can find them in the project graph and determine the information it needs.
This usually amounts to Nx creating the following URLs:

```shell
shop@localhost:4201
cart@localhost:4202
```

When it comes deployment to a real server, you'll need to configure the URLs to point to their real location. For example, if you deploy the host and the remotes to three servers, each with their own domain, you'd need to configure that:

```shell
shop@https://shop.example.com
cart@https://cart.example.com
```

The `remotes` option in the `module-federation.config.ts` file allows you to do this:

```javascript
// module-federation.config.ts
export default {
  remotes: [
    ['shop', 'https://shop.example.com'],
    ['cart', 'https://cart.example.com'],
  ],
};
```

However, once you make this change, it will no longer work locally.
You need some mechanism to change the URLs when you're building for a production environment.

A simple way to achieve this could be to use an environment variable:

```javascript
// module-federation.config.ts
const remotes = process.env.PRODUCTION_DEPLOY
  ? [
      ['shop', 'https://shop.example.com'],
      ['cart', 'https://cart.example.com'],
    ]
  : ['shop', 'cart'];

export default {
  remotes,
};
```

In your CI/CD pipeline, you can set the `PRODUCTION_DEPLOY` environment variable to `true` and then build for production, and the remotes will be configured to point to their real location.

## API reference

### NxModuleFederationDevServerPlugin

```ts
export class NxModuleFederationDevServerPlugin {
  constructor(
    private _options: {
      config: ModuleFederationConfig;
      devServerConfig?: NxModuleFederationDevServerConfig;
    }
  ) {
    this._options.devServerConfig ??= {
      host: 'localhost',
    };
  }
}
```

### NxModuleFederationSSRDevServerPlugin

```ts
export class NxModuleFederationSSRDevServerPlugin {
  constructor(
    private _options: {
      config: ModuleFederationConfig;
      devServerConfig?: NxModuleFederationDevServerConfig;
    }
  ) {
    this._options.devServerConfig ??= {
      host: 'localhost',
    };
  }
}
```

### NxModuleFederationDevServerConfig

```ts
export interface NxModuleFederationDevServerConfig {
  /**
   * The URL hostname to use for the dev server.
   */
  host?: string;
  /**
   * The port to use for the static remotes.
   */
  staticRemotesPort?: number;
  /**
   * The path to the module federation manifest file when using Dynamic Module Federation.
   */
  pathToManifestFile?: string;
  /**
   * Whether to use SSL for the remote applications.
   */
  ssl?: boolean;
  /**
   * The path to the SSL certificate file.
   */
  sslCert?: string;
  /**
   * The path to the SSL key file.
   */
  sslKey?: string;
  /**
   * The number of parallel processes to use when building the static remotes.
   */
  parallel?: number;
  /**
   * Options to proivde fine-grained control over how the dev server finds the remote applications.
   */
  devRemoteFindOptions?: DevRemoteFindOptions;
}

export interface DevRemoteFindOptions {
  retries?: number;
  retryDelay?: number;
}
```

---
<!-- source: https://nx.dev/docs/technologies/module-federation/guides/nx-module-federation-plugin.md -->
## NxModuleFederationPlugin

The `NxModuleFederationPlugin` is a [Rspack](https://rspack.dev) plugin that handles module federation in Nx Workspaces. It aims to provide the same Developer Experience(DX) that you would normally receive from using Nx `withModuleFederation` function.

## Usage

To use the plugin, you need to add it to your `rspack.config.ts` file. You can do this by adding the following to your config.

### Client side rendering

```ts
// rspack.config.ts
import {
  NxModuleFederationPlugin,
  NxModuleFederationDevServerPlugin,
} from '@nx/module-federation/rspack';
import config from './module-federation.config';

export default {
  ...otherRspackConfigOptions,
  plugins: [
    new NxModuleFederationPlugin({
      config,
    }),
    new NxModuleFederationDevServerPlugin({
      config,
    }),
  ],
};
```

### Server side rendering

```ts
// rspack.config.ts
import {
  NxModuleFederationPlugin,
  NxModuleFederationSSRDevServerPlugin,
} from '@nx/module-federation/rspack';
import config from './module-federation.config';

export default {
  ...otherRspackConfigOptions,
  plugins: [
    new NxModuleFederationPlugin({
      config,
      isServer: true,
    }),
    new NxModuleFederationSSRDevServerPlugin({
      config,
    }),
  ],
};
```

## How it works

The NxModuleFederationPlugin wraps and configures the Module Federation plugin from `@module-federation/enhanced` to provide a streamlined experience in Nx workspaces. Here's what the plugin does:

1. **Base Configuration**: It sets up essential Rspack configurations:
   - Disables runtime chunking (`runtimeChunk: false`)
   - Sets a unique name for the output
   - Configures specific settings for server-side rendering when needed

2. **Module Federation Setup**: The plugin automatically:
   - Configures the remote entry filename (`remoteEntry.js`)
   - Sets up exposed modules based on your configuration
   - Manages remote module connections
   - Handles shared dependencies and libraries

3. **Runtime Plugins**: It supports additional runtime plugins, including special handling for Node.js environments when running in server mode.

4. **Shared Libraries**: The plugin includes a dedicated system for managing shared libraries across federated modules, helping to avoid duplicate code and ensure consistent versions.

You can learn more about how Nx handles Module Federation in the [Module Federation and Nx Guide](/docs/technologies/module-federation/concepts/module-federation-and-nx#develop-as-a-user).

## Deployment

How applications are deployed depends on the teams and organizational requirements. There are two approaches:

1. À la carte deployments - Each application is deployed according to a release schedule, and can have different cadences.
2. Affected deployments - When changes are merged, use Nx to test and deploy the affected applications automatically.

Often times, teams mix both approaches so deployments to staging (or other shared environments) are automatic. Then,
promotion from staging to production occurs on a set cadence (e.g. weekly releases). It is also recommended to agree on
a process to handle changes to core libraries (i.e. ones that are shared between applications). Since the core changes
affect all applications, it also blocks all other releases, thus should not occur too frequently.

You may also choose to fully automate deployments, even to production. This type of pipeline requires good end-to-end
testing to provide higher confidence that the applications behave correctly. You will also need good rollback mechanisms
in case of a bad deployment.

When figuring out the best deployment strategy, or even how to achieve it with Module Federation and Nx, it is worth understanding what is happening under-the-hood.
Each host and remote in your Module Federation system is treated like a separate application. However, when a remote is loaded into a host via Module Federation, Module Federation itself does not make any kind of distinguishment.
It only cares that the JS file it is trying to load is available at the pre-specified URL, such that it can make a network request to fetch the JS file.

When working locally, Nx parses the config in `module-federation.config.ts` to determine what projects in the workspace are federated. It then reads the project graph for these projects to determine what port they will be served on and uses this information to form a URL to tell Module Federation where it will find the remote JS files.
You'll commonly see the following configuration in your `module-federation.config.ts`:

```javascript
// module-federation.config.ts
export default {
  remotes: ['shop', 'cart'],
};
```

These names match the names of the projects in the workspace. Therefore, Nx can find them in the project graph and determine the information it needs.
This usually amounts to Nx creating the following URLs:

```shell
shop@localhost:4201
cart@localhost:4202
```

When it comes deployment to a real server, you'll need to configure the URLs to point to their real location. For example, if you deploy the host and the remotes to three servers, each with their own domain, you'd need to configure that:

```shell
shop@https://shop.example.com
cart@https://cart.example.com
```

The `remotes` option in the `module-federation.config.ts` file allows you to do this:

```javascript
// module-federation.config.ts
export default {
  remotes: [
    ['shop', 'https://shop.example.com'],
    ['cart', 'https://cart.example.com'],
  ],
};
```

However, once you make this change, it will no longer work locally.
You need some mechanism to change the URLs when you're building for a production environment.

A simple way to achieve this could be to use an environment variable:

```javascript
// module-federation.config.ts
const remotes = process.env.PRODUCTION_DEPLOY
  ? [
      ['shop', 'https://shop.example.com'],
      ['cart', 'https://cart.example.com'],
    ]
  : ['shop', 'cart'];

export default {
  remotes,
};
```

In your CI/CD pipeline, you can set the `PRODUCTION_DEPLOY` environment variable to `true` and then build for production, and the remotes will be configured to point to their real location.

## API reference

### NxModuleFederationPlugin

```ts
export class NxModuleFederationPlugin {
  constructor(
    private _options: {
      config: ModuleFederationConfig;
      isServer?: boolean;
    },
    private configOverride?: NxModuleFederationConfigOverride
  ) {}
}
```

### ModuleFederationConfig

```ts
export interface ModuleFederationConfig {
  /**
   * The name of the module federation application.
   */
  name: string;
  /**
   * The remotes that the module federation application uses.
   */
  remotes?: Remotes;
  /**
   * The library type and name the ModuleFederationPlugin uses to expose and load the federated modules.
   */
  library?: ModuleFederationLibrary;
  /**
   * The federated modules to expose for consumption by host/consumer applications.
   */
  exposes?: Record<string, string>;
  /**
   * A function that allows you to configure shared libraries.
   * This function is called for each shared library that is used by the module federation application.
   * The function is passed the library name and the shared library configuration.
   * If the function returns `undefined` the default shared library configuration is used.
   * If the function returns `false` the shared library is not shared.
   * If the function returns a shared library configuration object, that configuration is used.
   */
  shared?: SharedFunction;
  /**
   * Additional shared libraries that are shared by the module federation application.
   * This is useful when you want to share a library that is not found as part of the direct dependencies of the application found in the Nx Graph.
   */
  additionalShared?: AdditionalSharedConfig;
  /**
   * `nxRuntimeLibraryControlPlugin` is a runtime module federation plugin to ensure
   * that shared libraries are resolved from a remote with live reload capabilities.
   * If you run into any issues with loading shared libraries, try disabling this option.
   */
  disableNxRuntimeLibraryControlPlugin?: boolean;
}

export type Remotes = Array<string | [remoteName: string, remoteUrl: string]>;
export type ModuleFederationLibrary = { type: string; name: string };
export type SharedFunction = (
  libraryName: string,
  sharedConfig: SharedLibraryConfig
) => undefined | false | SharedLibraryConfig;
export interface SharedLibraryConfig {
  singleton?: boolean;
  strictVersion?: boolean;
  requiredVersion?: false | string;
  eager?: boolean;
}
export type AdditionalSharedConfig = Array<
  | string
  | [libraryName: string, sharedConfig: SharedLibraryConfig]
  | { libraryName: string; sharedConfig: SharedLibraryConfig }
>;
```

### NxModuleFederationConfigOverride

```ts
/**
 * Used to override the options passed to the ModuleFederationPlugin.
 */
export type NxModuleFederationConfigOverride = Omit<
  moduleFederationPlugin.ModuleFederationPluginOptions,
  'exposes' | 'remotes' | 'name' | 'shared' | 'filename'
>;
```

---
<!-- source: https://nx.dev/docs/technologies/module-federation/guides/using-tailwind-css-with-module-federation.md -->
## Using Tailwind CSS with Module Federation

When using [Tailwind CSS](https://tailwindcss.com/) with Module Federation, you may encounter an issue where Tailwind classes used in your remote applications don't render correctly. This guide explains why this happens and how to configure your workspace to resolve it.

## Understanding the problem

Tailwind CSS uses a content scanning mechanism to determine which CSS classes to include in your final stylesheet. During the build process, Tailwind scans the files specified in your configuration and only generates CSS for the classes it finds. This is how Tailwind keeps your CSS bundle small by eliminating unused styles.

In a Module Federation architecture, the host and remote applications are built independently. When the host application builds, Tailwind only scans the host's source files—it has no knowledge of the classes used in remote applications. As a result, when remotes are loaded at runtime, any Tailwind classes they use that aren't also used in the host will be missing from the stylesheet.

{% aside type="note" title="This is expected behavior" %}
This is not a bug in Nx or Module Federation. It's a fundamental aspect of how Tailwind's content scanning works combined with Module Federation's independent build model.
{% /aside %}

## Configuring the host application

The solution is to configure your host application's Tailwind setup to include the source files from your remote applications. This ensures all Tailwind classes used across your federated application are compiled into the host's stylesheet.

### Tailwind CSS v4

For Tailwind CSS v4, use the [`@source` directive](https://tailwindcss.com/docs/detecting-classes-in-source-files) in your stylesheet to include remote application paths:

{% tabs %}
{% tabitem label="React" %}

```css
/* apps/shell/src/styles.css */
@import 'tailwindcss';

/* Include shared libraries */
@source "../../../libs";

/* Include remote applications */
@source "../remote1/src";
@source "../remote2/src";
```

{% /tabitem %}
{% tabitem label="Angular" %}

```css
/* apps/shell/src/styles.css */
@import 'tailwindcss';

/* Include shared libraries */
@source "../../../libs";

/* Include remote applications */
@source "../remote1/src";
@source "../remote2/src";
```

{% /tabitem %}
{% /tabs %}

### Tailwind CSS v3

For Tailwind CSS v3, configure the [`content`](https://v3.tailwindcss.com/docs/content-configuration) array in your host's `tailwind.config.js` to include glob patterns for your remote applications:

{% tabs %}
{% tabitem label="React" %}

```javascript
// apps/shell/tailwind.config.js
const { join } = require('path');

module.exports = {
  content: [
    join(__dirname, '{src,pages,components,app}/**/*.{ts,tsx,js,jsx}'),
    // Include shared libraries
    join(__dirname, '../../libs/**/*.{ts,tsx,js,jsx}'),
    // Include remote applications
    join(__dirname, '../remote1/src/**/*.{ts,tsx,js,jsx}'),
    join(__dirname, '../remote2/src/**/*.{ts,tsx,js,jsx}'),
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};
```

{% /tabitem %}
{% tabitem label="Angular" %}

```javascript
// apps/shell/tailwind.config.js
const { join } = require('path');

module.exports = {
  content: [
    join(__dirname, 'src/**/*.{ts,html}'),
    // Include shared libraries
    join(__dirname, '../../libs/**/*.{ts,html}'),
    // Include remote applications
    join(__dirname, '../remote1/src/**/*.{ts,html}'),
    join(__dirname, '../remote2/src/**/*.{ts,html}'),
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};
```

{% /tabitem %}
{% /tabs %}

Adjust the paths based on your workspace structure. If your remotes are in different directories, update the glob patterns accordingly.

## Shared theme extensions

If your remote applications use custom Tailwind theme extensions (such as custom colors, fonts, or spacing values), you need to ensure these are also defined in the host's Tailwind configuration. Otherwise, classes like `bg-brand-primary` or `text-custom-lg` won't generate any CSS.

Consider creating a shared Tailwind preset that all applications can extend:

```javascript
// libs/shared/tailwind-preset/src/index.js
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          primary: '#3b82f6',
          secondary: '#10b981',
        },
      },
    },
  },
};
```

Then use this preset in both your host and remote configurations:

```javascript
// apps/shell/tailwind.config.js
const sharedPreset = require('../../libs/shared/tailwind-preset/src');

module.exports = {
  presets: [sharedPreset],
  content: [
    // ... your content configuration
  ],
};
```

## Further reading

- [Using Tailwind CSS with Angular](/docs/technologies/angular/guides/using-tailwind-css-with-angular-projects)
- [Using Tailwind CSS with React](/docs/technologies/react/guides/using-tailwind-css-in-react)
- [Tailwind CSS v4 Source Detection](https://tailwindcss.com/docs/detecting-classes-in-source-files)
- [Tailwind CSS v3 Content Configuration](https://v3.tailwindcss.com/docs/content-configuration)

---
<!-- source: https://nx.dev/docs/technologies/module-federation/introduction.md -->
## Module Federation Plugin for Nx

The `NxModuleFederationPlugin` is a [Rspack](https://rspack.dev) plugin that handles module federation in Nx Workspaces. It aims to provide the same Developer Experience (DX) that you would normally get from using the Nx `withModuleFederation` function.

## Requirements

The `@nx/module-federation` plugin supports the following package versions.

| Package        | Supported Versions |
| -------------- | ------------------ |
| `webpack`      | ^5.0.0             |
| `@rspack/core` | ^1.6.0             |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

## Usage

To use the plugin, you need to add it to your `rspack.config.ts` file. You can do this by adding the following to your config.

### Client side rendering

```ts
// rspack.config.ts
import {
  NxModuleFederationPlugin,
  NxModuleFederationDevServerPlugin,
} from '@nx/module-federation/rspack';
import config from './module-federation.config';

export default {
  ...otherRspackConfigOptions,
  plugins: [
    new NxModuleFederationPlugin({
      config,
    }),
    new NxModuleFederationDevServerPlugin({
      config,
    }),
  ],
};
```

### Server side rendering

```ts
// rspack.config.ts
import {
  NxModuleFederationPlugin,
  NxModuleFederationSSRDevServerPlugin,
} from '@nx/module-federation/rspack';
import config from './module-federation.config';

export default {
  ...otherRspackConfigOptions,
  plugins: [
    new NxModuleFederationPlugin({
      config,
      isServer: true,
    }),
    new NxModuleFederationSSRDevServerPlugin({
      config,
    }),
  ],
};
```

## How it works

The NxModuleFederationPlugin wraps and configures the Module Federation plugin from `@module-federation/enhanced` to provide a streamlined experience in Nx workspaces. Here's what the plugin does:

1. **Base Configuration**: It sets up essential Rspack configurations:
   - Disables runtime chunking (`runtimeChunk: false`)
   - Sets a unique name for the output
   - Configures specific settings for server-side rendering when needed

2. **Module Federation Setup**: The plugin automatically:
   - Configures the remote entry filename (`remoteEntry.js`)
   - Sets up exposed modules based on your configuration
   - Manages remote module connections
   - Handles shared dependencies and libraries

3. **Runtime Plugins**: It supports additional runtime plugins, including special handling for Node.js environments when running in server mode.

4. **Shared Libraries**: The plugin includes a dedicated system for managing shared libraries across federated modules, helping to avoid duplicate code and ensure consistent versions.

You can learn more about how Nx handles Module Federation in the [Module Federation and Nx Guide](/docs/technologies/module-federation/concepts/module-federation-and-nx#nx-support-for-module-federation).

## API reference

### NxModuleFederationPlugin

```ts
export class NxModuleFederationPlugin {
  constructor(
    private _options: {
      config: ModuleFederationConfig;
      isServer?: boolean;
    },
    private configOverride?: NxModuleFederationConfigOverride
  ) {}
}
```

### ModuleFederationConfig

```ts
export interface ModuleFederationConfig {
  /**
   * The name of the module federation application.
   */
  name: string;
  /**
   * The remotes that the module federation application uses.
   */
  remotes?: Remotes;
  /**
   * The library type and name the ModuleFederationPlugin uses to expose and load the federated modules.
   */
  library?: ModuleFederationLibrary;
  /**
   * The federated modules to expose for consumption by host/consumer applications.
   */
  exposes?: Record<string, string>;
  /**
   * A function that allows you to configure shared libraries.
   * This function is called for each shared library that is used by the module federation application.
   * The function is passed the library name and the shared library configuration.
   * If the function returns `undefined` the default shared library configuration is used.
   * If the function returns `false` the shared library is not shared.
   * If the function returns a shared library configuration object, that configuration is used.
   */
  shared?: SharedFunction;
  /**
   * Additional shared libraries that are shared by the module federation application.
   * This is useful when you want to share a library that is not found as part of the direct dependencies of the application found in the Nx Graph.
   */
  additionalShared?: AdditionalSharedConfig;
  /**
   * `nxRuntimeLibraryControlPlugin` is a runtime module federation plugin to ensure
   * that shared libraries are resolved from a remote with live reload capabilities.
   * If you run into any issues with loading shared libraries, try disabling this option.
   */
  disableNxRuntimeLibraryControlPlugin?: boolean;
}

export type Remotes = Array<string | [remoteName: string, remoteUrl: string]>;
export type ModuleFederationLibrary = { type: string; name: string };
export type SharedFunction = (
  libraryName: string,
  sharedConfig: SharedLibraryConfig
) => undefined | false | SharedLibraryConfig;
export interface SharedLibraryConfig {
  singleton?: boolean;
  strictVersion?: boolean;
  requiredVersion?: false | string;
  eager?: boolean;
}
export type AdditionalSharedConfig = Array<
  | string
  | [libraryName: string, sharedConfig: SharedLibraryConfig]
  | { libraryName: string; sharedConfig: SharedLibraryConfig }
>;
```

### NxModuleFederationConfigOverride

```ts
/**
 * Used to override the options passed to the ModuleFederationPlugin.
 */
export type NxModuleFederationConfigOverride = Omit<
  moduleFederationPlugin.ModuleFederationPluginOptions,
  'exposes' | 'remotes' | 'name' | 'shared' | 'filename'
>;
```

---
<!-- source: https://nx.dev/docs/technologies/module-federation/migrations.md -->
## @nx/module-federation Migrations

The @nx/module-federation plugin provides various migrations to help you migrate to newer versions of module-federation projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 22.6.x

### 22.6.0-package-updates
**Version**: 22.6.0-beta.10


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@module-federation/enhanced` | `^2.1.0` | Updated only
| `@module-federation/runtime` | `^2.1.0` | Updated only
| `@module-federation/sdk` | `^2.1.0` | Updated only
| `@module-federation/node` | `^2.7.21` | Updated only



## 22.2.x

### 22.2.0-package-updates
**Version**: 22.2.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@module-federation/enhanced` | `^0.21.2` | Updated only
| `@module-federation/runtime` | `^0.21.2` | Updated only
| `@module-federation/sdk` | `^0.21.2` | Updated only
| `@module-federation/node` | `^2.7.21` | Updated only



## 21.4.x

### 21.4.0-package-updates
**Version**: 21.4.0-beta.8


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `http-proxy-middleware` | `^3.0.5` | Updated only
| `@module-federation/sdk` | `^0.18.0` | Updated only
| `@module-federation/enhanced` | `^0.18.0` | Updated only
| `@module-federation/runtime` | `^0.18.0` | Updated only
| `@module-federation/node` | `^2.7.11` | Updated only



## 21.3.x

### 21.3.0-package-updates
**Version**: 21.3.0-beta.8


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@module-federation/enhanced` | `^0.17.0` | Updated only
| `@module-federation/node` | `^2.7.9` | Updated only
| `@module-federation/sdk` | `^0.17.0` | Updated only



## 21.2.x

### 21.2.0-package-updates
**Version**: 21.2.0-beta.6


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@module-federation/enhanced` | `^0.15.0` | Updated only
| `@module-federation/runtime` | `^0.15.0` | Updated only
| `@module-federation/sdk` | `^0.15.0` | Updated only



## 20.5.x

### 20.5.0-package-updates
**Version**: 20.5.0-beta.5


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@module-federation/enhanced` | `^0.9.0` | Updated only
| `@module-federation/runtime` | `^0.9.0` | Updated only
| `@module-federation/sdk` | `^0.9.0` | Updated only
| `@module-federation/node` | `^2.6.26` | Updated only



## 20.4.x

### 20.4.0-package-updates
**Version**: 20.4.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@module-federation/enhanced` | `^0.8.8` | Updated only
| `@module-federation/runtime` | `^0.8.8` | Updated only
| `@module-federation/sdk` | `^0.8.8` | Updated only
| `@module-federation/node` | `^2.6.21` | Updated only

---
<!-- source: https://nx.dev/docs/technologies/node.md -->
## Node.js

{% index_page_cards path="technologies/node" /%}

---
<!-- source: https://nx.dev/docs/technologies/node/express.md -->
## Express

{% index_page_cards path="technologies/node/express" /%}

---
<!-- source: https://nx.dev/docs/technologies/node/express/generators.md -->
## @nx/express Generators

The @nx/express plugin provides various generators to help you create and configure express projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `application`
Nx Application Options Schema.

**Usage:**
```bash
nx generate @nx/express:application [options]
```

**Aliases:** `app`

**Arguments:**
```bash
nx generate @nx/express:application <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--babelJest` | boolean | Use `babel` instead `ts-jest`. | `false` |
| `--frontendProject` | string | Frontend project that needs to access this application. This sets up proxy configuration. |  |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"none"` |
| `--name` | string | The name of the application. |  |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--swcJest` | boolean | Use `@swc/jest` instead `ts-jest` for faster test compilation. | `false` |
| `--tags` | string | Add tags to the application (used for linting). |  |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"none"` |
| `--useProjectJson` | boolean | Use a `project.json` configuration file instead of inlining the Nx configuration in the `package.json` file. |  |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/express:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/node/express/introduction.md -->
## Express Plugin for Nx

[Express](https://expressjs.com/) is a mature, minimal, and an open source web framework for making web applications and
apis.

## Requirements

The `@nx/express` plugin supports the following package versions.

| Package   | Supported Versions |
| --------- | ------------------ |
| `express` | ^4.21.2            |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

## Create a new workspace

To create a new workspace with a pre-created Express app, run the following command:

```shell
 npx create-nx-workspace --preset=express
```

## Setting up @nx/express

### Installation

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/express` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
{% /aside %}

In any Nx workspace, you can install `@nx/express` by running the following command:

```shell
nx add @nx/express
```

This will install the correct version of `@nx/express`.

## Guides

- [Set Up Application Proxies](/docs/technologies/node/guides/application-proxies)
- [Wait For Tasks To Finish](/docs/technologies/node/guides/wait-for-tasks)

---
<!-- source: https://nx.dev/docs/technologies/node/express/migrations.md -->
## @nx/express Migrations

No migrations found for `@nx/express`.
Nx only retains migrations for the last 2 major versions of Nx.
It's possible migrations existed in previous versions of `@nx/express`.

You can check the previous docs for [Nx v21](https://21.nx.dev/docs) or [Nx v20](https://20.nx.dev/docs).

---
<!-- source: https://nx.dev/docs/technologies/node/generators.md -->
## @nx/node Generators

The @nx/node plugin provides various generators to help you create and configure node projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `application`
Nx Application Options Schema.

**Usage:**
```bash
nx generate @nx/node:application [options]
```

**Aliases:** `app`

**Arguments:**
```bash
nx generate @nx/node:application <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--babelJest` | boolean | Use `babel` instead `ts-jest`. | `false` |
| `--bundler` | string | Bundler which is used to package the application | `"esbuild"` |
| `--docker` | boolean | Add a docker build target |  |
| `--e2eTestRunner` | string | Test runner to use for end-to-end tests | `"none"` |
| `--framework` | string | Generate the node application using a framework | `"none"` |
| `--frontendProject` | string | Frontend project that needs to access this application. This sets up proxy configuration. |  |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"none"` |
| `--name` | string | The name of the application. |  |
| `--port` | number | The port which the server will be run on | `3000` |
| `--rootProject` | boolean | Create node application at the root of the workspace | `false` |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons. | `false` |
| `--skipDockerPlugin` | boolean | Skip the @nx/docker plugin and use the legacy docker build target instead. | `false` |
| `--skipFormat` | boolean | Skip formatting files | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--standaloneConfig` | boolean | Split the project configuration into `<projectRoot>/project.json` rather than including it inside `workspace.json`. | `true` |
| `--swcJest` | boolean | Use `@swc/jest` instead `ts-jest` for faster test compilation. |  |
| `--tags` | string | Add tags to the application (used for linting). |  |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"none"` |
| `--useProjectJson` | boolean | Use a `project.json` configuration file instead of inlining the Nx configuration in the `package.json` file. |  |

## `library`
Create a Node Library for an Nx workspace.

**Usage:**
```bash
nx generate @nx/node:library [options]
```

**Aliases:** `lib`

**Arguments:**
```bash
nx generate @nx/node:library <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--babelJest` | boolean | Use `babel` instead of `ts-jest`. | `false` |
| `--buildable` | boolean | Generate a buildable library. | `true` |
| `--compiler` | string | The compiler used by the build and test targets. | `"tsc"` |
| `--importPath` | string | The library name used to import it, like `@myorg/my-awesome-lib`. Must be a valid npm name. |  |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"none"` |
| `--name` | string | Library name |  |
| `--publishable` | boolean | Create a publishable library. |  |
| `--rootDir` | string | Sets the `rootDir` for TypeScript compilation. When not defined, it uses the project's root property, or `srcRootForCompilationRoot` if it is defined. |  |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint `parserOptions.project`. We do not do this by default for lint performance reasons. | `false` |
| `--simpleModuleName` | boolean | Keep the module name simple. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipTsConfig` | boolean | Do not update `tsconfig.base.json` for development experience. | `false` |
| `--standaloneConfig` | boolean | Split the project configuration into `<projectRoot>/project.json` rather than including it inside `workspace.json`. | `true` |
| `--strict` | boolean | Whether to enable tsconfig strict mode or not. | `false` |
| `--tags` | string | Add tags to the library (used for linting). |  |
| `--testEnvironment` | string | The test environment to use if `unitTestRunner` is set to `jest`. | `"jsdom"` |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"none"` |
| `--useProjectJson` | boolean | Use a `project.json` configuration file instead of inlining the Nx configuration in the `package.json` file. |  |

## `setup-docker`
Nx Node Docker Options Schema.

**Usage:**
```bash
nx generate @nx/node:setup-docker [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--buildTargetName` | string | The name of the build target | `"build"` |
| `--outputPath` | string | The output path for the node application |  |
| `--project` | string | The name of the project |  |
| `--skipDockerPlugin` | boolean | Skip the @nx/docker plugin and use the legacy docker build target instead. | `false` |
| `--targetName` | string | The name of the target to create | `"docker:build"` |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/node:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/node/guides.md -->
## Guides

{% index_page_cards path="technologies/node/guides" /%}

---
<!-- source: https://nx.dev/docs/technologies/node/guides/application-proxies.md -->
## Set Up Application Proxies

It is useful to set up frontend proxies to your backend app during local development. By proxying requests, you won't need to set up [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) when communicating with the backend.

## Webpack dev-server

Webpack dev-server has built-in support for [proxies](https://webpack.js.org/configuration/dev-server/#devserverproxy).

For example, if you want to proxy all requests to `/api` to `http://localhost:3000`, then you would use this configuration:

```js
// webpack.config.js
// ...
module.exports = {
  //...
  devServer: {
    proxy: [
      {
        context: ['/api'],
        target: 'http://localhost:3000',
      },
    ],
  },
};
```

Say that your frontend app is at port `4200`, then requests to `http://localhost:4200/api` will proxy to the backend app at port `3000`.

If you don't want `/api` to be passed along, then use `pathRewrite`.

```js
// webpack.config.js
// ...
module.exports = {
  //...
  devServer: {
    proxy: [
      {
        context: ['/api'],
        target: 'http://localhost:3000',
        pathRewrite: { '^/api': '' },
      },
    ],
  },
};
```

## Vite server

Vite server has built-in support for [proxies](https://vite.dev/config/server-options#server-proxy).

For example, if you want to proxy all requests to `/api` to `http://localhost:3000`, then you would use this configuration:

```js
// vite.config.ts
// ...
export default defineConfig({
  // ...
  server: {
    proxy: {
      '/api': 'http://localhost:3000',
    },
  },
});
```

Say that your frontend app is at port `4200`, then requests to `http://localhost:4200/api` will proxy to the backend app at port `3000`.

If you don't want `/api` to be passed along, then use `rewrite`.

```js
// vite.config.ts
// ...
export default defineConfig({
  // ...
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:3000',
        rewrite: (path) => path.replace(/^\/api/, ''),
      },
    },
  },
});
```

## Automatically configure frontend executors

{% aside type="caution" title="Not recommended for new projects" %}
We recommend configuring proxies using support from existing tooling. Webpack and Vite both come with proxy support out of the box, as do most modern tools. Using `--frontendProject` is meant for Nx prior to version 18.
{% /aside %}

Prior to Nx version 18, projects use [executors](/docs/concepts/executors-and-configurations) to run tasks. If your frontend project is
using executors, then the Node, Nest and Express app generators have an option to configure proxy API requests. This
can be done by passing the `--frontendProject` with the project name you wish to enable proxy support for.

```shell
nx g @nx/node:app apps/<node-app> --frontendProject my-react-app
nx g @nx/nest:app apps/<nest-app> --frontendProject my-react-app
nx g @nx/express:app apps/<express-app> --frontendProject my-react-app
```

This command will generate and configure a `proxy.conf.json` file that will be used by the frontend project's `serve` target to redirect calls to `/api` to instead go to `http://localhost:3000/api`.

```json
// /apps/my-react-app/proxy.conf.json
{
  "/api": {
    "target": "http://localhost:3000",
    "secure": false
  }
}
```

---
<!-- source: https://nx.dev/docs/technologies/node/guides/bundling-node-projects.md -->
## Bundling Projects for Deployment

Bundling compiles your code and all its dependencies into a single file (e.g. `main.js`).
The output is self-contained, so you don't need `node_modules` or an install step at deploy time.

If your app has native dependencies or you want Docker layer caching for `node_modules`,
see [pruning projects for deployment](/docs/technologies/node/guides/deploying-node-projects) instead.

## When to bundle instead of prune

| Approach                                                          | Best for                                | Trade-off                                     |
| ----------------------------------------------------------------- | --------------------------------------- | --------------------------------------------- |
| Bundling                                                          | Serverless functions, simple APIs       | Single file output, no `node_modules` needed  |
| [Pruning](/docs/technologies/node/guides/deploying-node-projects) | Docker deployments, native dependencies | Keeps `node_modules` but only production deps |

Use bundling when:

- Your app has no native dependencies that require OS-level installation
- You want a single deployable artifact with no install step
- You're targeting serverless platforms or lightweight containers

{% aside type="note" title="Lazy loaded chunks" %}
If you use lazy loaded chunks, bundling produces more than a single file.
You'll have one file per chunk entrypoint.
Make sure all files are handled correctly for your deployment needs.
{% /aside %}

## Bundling Node.js applications

{% tabs syncKey="bundler" %}

{% tabitem label="Webpack" %}

Webpack provides full control over the bundling process. Configure your `webpack.config.js` to bundle all dependencies.

- `generatePackageJson: false` - Skips generating a `package.json` since all dependencies are bundled
- `externalDependencies: 'none'` - Bundles all dependencies instead of treating them as external

```js {% meta="{16-17}" %}
// webpack.config.js
const { NxAppWebpackPlugin } = require('@nx/webpack/app-plugin');
const { join } = require('path');

module.exports = {
  output: {
    path: join(__dirname, 'dist'),
  },
  plugins: [
    new NxAppWebpackPlugin({
      target: 'node',
      compiler: 'tsc',
      main: './src/main.ts',
      tsConfig: './tsconfig.app.json',
      outputHashing: 'none',
      generatePackageJson: false,
      externalDependencies: 'none',
    }),
  ],
};
```

{% /tabitem %}

{% tabitem label="esbuild" %}

esbuild offers faster builds than Webpack. Configure bundling in your `project.json`:

The `bundle: true` option tells esbuild to include all dependencies in the output.

```json {% meta="{11}" %}
// project.json
{
  "name": "my-app",
  "targets": {
    "build": {
      "executor": "@nx/esbuild:esbuild",
      "options": {
        "platform": "node",
        "outputPath": "dist/my-app",
        "format": ["cjs"],
        "bundle": true,
        "main": "apps/my-app/src/main.ts",
        "tsConfig": "apps/my-app/tsconfig.app.json",
        "generatePackageJson": false,
        "esbuildOptions": {
          "outfile": "dist/my-app/main.js"
        }
      }
    }
  }
}
```

{% /tabitem %}

{% tabitem label="Vite" %}

Vite can also bundle Node.js applications with vite by using the `build.rollupOptions.external`.
Set `external: []` to bundle all dependencies into the output.

```ts {% meta="{15}"%}
// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    target: 'node18',
    outDir: 'dist',
    lib: {
      entry: 'src/main.ts',
      formats: ['cjs'],
      fileName: 'main',
    },
    rollupOptions: {
      // Bundle all dependencies
      external: [],
    },
  },
});
```

{% /tabitem %}

{% /tabs %}

To build and deploy:

```shell
nx build my-app
# Deploy dist/my-app/main.js - no node_modules needed
```

## When not to bundle

If you're publishing a library package to npm, avoid bundling dependencies.
Declare them in `package.json` so package managers can handle versioning and deduplication.

For Docker-based deployments, non-bundled builds can improve build times through layer caching.
When dependencies don't change, Docker reuses the cached `node_modules` layer and only rebuilds your application code.

Instead of running `build`, use the `prune` target to prepare your application for deployment with its dependencies:

```shell
nx prune my-app
```

For the full setup, see [pruning projects for deployment](/docs/technologies/node/guides/deploying-node-projects).

This creates a deployment-ready structure:

```text
dist/my-app/
├── main.js           # Your application code
├── package.json      # Dependencies manifest
└── node_modules/     # Production dependencies
```

In your Dockerfile, copy these files and run with Node.js:

```dockerfile
COPY dist/my-app /app
WORKDIR /app
CMD ["node", "main.js"]
```

## Bundling libraries

Publish workspace dependencies as separate packages rather than bundling them into a single library.
This gives better versioning control and lets consumers manage their own dependency trees.

Bundling workspace libraries makes sense when:

- The library contains only types that should be inlined
- You want to distribute an internal library as part of your package

{% tabs syncKey="bundler" %}

{% tabitem label="esbuild" %}

Configure the `external` option to control which dependencies get bundled:

```json
// project.json
{
  "name": "my-lib",
  "targets": {
    "build": {
      "executor": "@nx/esbuild:esbuild",
      "options": {
        "platform": "node",
        "outputPath": "dist/libs/my-lib",
        "format": ["cjs", "esm"],
        "bundle": true,
        "main": "libs/my-lib/src/index.ts",
        "tsConfig": "libs/my-lib/tsconfig.lib.json",
        "external": ["^[^./].*$", "!@my-org/utils"]
      }
    }
  }
}
```

The `external` patterns work as follows:

- `"^[^./].*$"` - Externalizes all npm packages (paths not starting with `.` or `/`)
- `"!@my-org/utils"` - Exception: bundles `@my-org/utils` despite matching the first pattern

See esbuild [documentation if using an esbuild configuration file directly](https://esbuild.github.io/api/#external)

{% /tabitem %}

{% tabitem label="Vite" %}

For Vite-based builds, configure the `external` function in `rollupOptions`:

```ts
// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    lib: {
      entry: 'src/index.ts',
      formats: ['es', 'cjs'],
    },
    rollupOptions: {
      external: (id) => {
        // Bundle workspace libraries
        if (id.startsWith('@my-org/')) {
          return false;
        }
        // Externalize npm packages
        if (!id.startsWith('.') && !id.startsWith('/')) {
          return true;
        }
        return false;
      },
    },
  },
});
```

The `external` function receives each import and returns:

- `false` to bundle the dependency
- `true` to keep it as an external import

See `rollupOptions` from [vite documentation for more information](https://vite.dev/config/build-options#build-rollupoptions)
{% /tabitem %}

{% /tabs %}

## Managing workspace dependencies

When building libraries that consume other workspace libraries, define the dependency relationship in `package.json`:

```json
// libs/my-lib/package.json
{
  "name": "@my-org/my-lib",
  "dependencies": {
    "@my-org/utils": "workspace:*"
  }
}
```

The `workspace:*` syntax:

- During development: resolves to the local workspace package
- During publish: gets replaced with the actual version number

This ensures your library correctly declares its dependencies regardless of whether they're bundled.

## Quick reference

| Scenario                                | Tool    | Key Settings                                                 |
| --------------------------------------- | ------- | ------------------------------------------------------------ |
| Bundled Node app                        | Webpack | `generatePackageJson: false`, `externalDependencies: 'none'` |
| Bundled Node app                        | esbuild | `bundle: true`, `generatePackageJson: false`                 |
| Bundled Node app                        | Vite    | `external: []` in `rollupOptions`                            |
| Non-bundled Node app                    | Any     | Run `prune` target, deploy with `node_modules`               |
| Publishable lib (bundle workspace deps) | esbuild | `bundle: true`, `external: ["^[^./].*$", "!@org/lib"]`       |
| Publishable lib (bundle workspace deps) | Vite    | Custom `external` function in `rollupOptions`                |

---
<!-- source: https://nx.dev/docs/technologies/node/guides/deploying-node-projects.md -->
## Pruning Projects for Deployment

When deploying Node.js applications to containers, you typically need only production dependencies, not your entire workspace `node_modules`.
Pruning generates a standalone `package.json`, a pruned lockfile, and copies any workspace libraries your app depends on.
The result is everything you need to run `npm ci` inside a Docker image with only the packages your application uses.

To bundle your app into a single file instead (no `node_modules` needed),
see [Bundling projects for deployment](/docs/technologies/node/guides/bundling-node-projects).

## When to prune instead of bundle

| Approach                                                          | Best for                                | Trade-off                                     |
| ----------------------------------------------------------------- | --------------------------------------- | --------------------------------------------- |
| [Bundling](/docs/technologies/node/guides/bundling-node-projects) | Serverless functions, simple APIs       | Single file output, no `node_modules` needed  |
| Pruning                                                           | Docker deployments, native dependencies | Keeps `node_modules` but only production deps |

Use pruning when:

- Your app has native dependencies (e.g. `bcrypt`, `sharp`) that can't be bundled
- You want Docker layer caching, where dependency layers rebuild only when `package.json` changes
- You consume workspace libraries as packages rather than bundling them

{% aside type="tip" %}
New Node applications include prune targets by default.
Pass `--docker` to also generate an example Dockerfile: `nx g @nx/node:app --docker`.
{% /aside %}

## How pruning works

Pruning uses four Nx targets that run in sequence:

1. `build` compiles your application (esbuild, webpack, tsc, etc.).
1. `prune-lockfile` (`@nx/js:prune-lockfile`) reads your project `package.json`, generates a minimal `package.json`, and creates a pruned lockfile containing only production dependencies.
1. `copy-workspace-modules` (`@nx/js:copy-workspace-modules`) copies workspace libraries referenced via `workspace:*` into a `workspace_modules/` directory and rewrites their dependency references to `file:` paths.
1. `prune` (`nx:noop`) depends on both `prune-lockfile` and `copy-workspace-modules`, giving you a single command to run.

After running `nx prune my-app`, the build output directory contains:

```text
apps/my-app/dist/
├── main.js                          # Compiled application
├── package.json                     # Pruned production dependencies
├── package-lock.json                # Pruned lockfile (or yarn.lock / pnpm-lock.yaml)
└── workspace_modules/               # Only present if you have workspace deps
    └── @my-org/
        └── my-lib/
            ├── package.json
            └── ...
```

## Set up prune targets

Add the following targets to your project's `package.json` or `project.json`:

{% tabs syncKey="config" %}

{% tabitem label="package.json" %}

```json
// apps/my-app/package.json
{
  "name": "@my-org/my-app",
  "nx": {
    "targets": {
      "prune-lockfile": {
        "dependsOn": ["build"],
        "cache": true,
        "executor": "@nx/js:prune-lockfile",
        "outputs": [
          "{workspaceRoot}/apps/my-app/dist/package.json",
          "{workspaceRoot}/apps/my-app/dist/package-lock.json"
        ],
        "options": {
          "buildTarget": "build"
        }
      },
      "copy-workspace-modules": {
        "dependsOn": ["build"],
        "cache": true,
        "outputs": ["{workspaceRoot}/apps/my-app/dist/workspace_modules"],
        "executor": "@nx/js:copy-workspace-modules",
        "options": {
          "buildTarget": "build"
        }
      },
      "prune": {
        "dependsOn": ["prune-lockfile", "copy-workspace-modules"],
        "executor": "nx:noop"
      }
    }
  }
}
```

{% /tabitem %}

{% tabitem label="project.json" %}

```json
// apps/my-app/project.json
{
  "name": "@my-org/my-app",
  "targets": {
    "prune-lockfile": {
      "dependsOn": ["build"],
      "cache": true,
      "executor": "@nx/js:prune-lockfile",
      "outputs": [
        "{workspaceRoot}/apps/my-app/dist/package.json",
        "{workspaceRoot}/apps/my-app/dist/package-lock.json"
      ],
      "options": {
        "buildTarget": "build"
      }
    },
    "copy-workspace-modules": {
      "dependsOn": ["build"],
      "cache": true,
      "outputs": ["{workspaceRoot}/apps/my-app/dist/workspace_modules"],
      "executor": "@nx/js:copy-workspace-modules",
      "options": {
        "buildTarget": "build"
      }
    },
    "prune": {
      "dependsOn": ["prune-lockfile", "copy-workspace-modules"],
      "executor": "nx:noop"
    }
  }
}
```

{% /tabitem %}

{% /tabs %}

Replace `package-lock.json` in the `outputs` array with `yarn.lock` or `pnpm-lock.yaml` if needed.

Then run:

```shell
nx prune my-app
```

Both `prune-lockfile` and `copy-workspace-modules` set `cache: true`,
so subsequent runs are instant when nothing changes.

## Use pruned output in Docker

The generated Dockerfile copies the build output and runs `npm install`:

```dockerfile
# apps/my-app/Dockerfile
FROM docker.io/node:lts-alpine

ENV HOST=0.0.0.0
ENV PORT=3000

WORKDIR /app

COPY dist .

# You can remove this install step if you build with `--bundle` option.
# The bundled output will include external dependencies.
RUN npm --omit=dev -f install

CMD ["node", "main.js"]
```

The `COPY dist .` line works because the Dockerfile lives inside the project directory (`apps/my-app/`),
and the build output goes to `apps/my-app/dist/`.
The pruned `package.json`, lockfile, and `workspace_modules/` are all inside `dist/`.

Build and run:

```shell
# Build the app and prune dependencies
nx prune my-app

# Build the Docker image
npx nx docker:build my-app

# Run the container
nx docker:run my-app -p 3000:3000
```

## Migrate from `generatePackageJson`

If you're upgrading to Nx 20+ with TS Solution Setup (the default for new workspaces),
the `generatePackageJson` option is no longer supported.
You'll see this error:

{% aside type="caution" title="Error: generatePackageJson not supported" %}
`Setting 'generatePackageJson: true' is not supported with the current TypeScript setup. Update the 'package.json' file at the project root as needed and unset the 'generatePackageJson' option.`
{% /aside %}

Follow these steps to migrate to the prune workflow:

### Step 1: Move dependencies to your project package.json

With TS Solution Setup, each project has its own `package.json`.
List all runtime dependencies there:

```json
// apps/my-app/package.json
{
  "name": "@my-org/my-app",
  "dependencies": {
    "express": "^4.18.0",
    "@my-org/shared-utils": "workspace:*"
  }
}
```

Use the `workspace:*` protocol for workspace libraries.

### Step 2: Remove `generatePackageJson` from your build configuration

{% tabs syncKey="bundler" %}

{% tabitem label="esbuild" %}

Remove `generatePackageJson` from your esbuild target options:

```json
// apps/my-app/package.json
{
  "nx": {
    "targets": {
      "build": {
        "executor": "@nx/esbuild:esbuild",
        "options": {
          "platform": "node",
          "outputPath": "dist/apps/my-app",
          "format": ["cjs"],
          "main": "apps/my-app/src/main.ts",
          "tsConfig": "apps/my-app/tsconfig.app.json"
        }
      }
    }
  }
}
```

{% /tabitem %}

{% tabitem label="Webpack" %}

Remove `generatePackageJson` from your webpack config:

```js
// apps/my-app/webpack.config.js
const { NxAppWebpackPlugin } = require('@nx/webpack/app-plugin');
const { join } = require('path');

module.exports = {
  output: {
    path: join(__dirname, '../../dist/apps/my-app'),
  },
  plugins: [
    new NxAppWebpackPlugin({
      target: 'node',
      compiler: 'tsc',
      main: './src/main.ts',
      tsConfig: './tsconfig.app.json',
    }),
  ],
};
```

{% /tabitem %}

{% tabitem label="Rollup / Vite" %}

Remove `generatePackageJson` from your rollup or vite build options.
With TS Solution Setup, the project `package.json` is used directly.

{% /tabitem %}

{% /tabs %}

### Step 3: Add prune targets

Add the `prune-lockfile`, `copy-workspace-modules`, and `prune` targets
to your project `package.json` as shown in the [set up prune targets](#set-up-prune-targets) section.

### Step 4: Update your Dockerfile

Replace references to the old generated `package.json` with the pruned output.
See the [use pruned output in Docker](#use-pruned-output-in-docker) section for a recommended Dockerfile structure.

---
<!-- source: https://nx.dev/docs/technologies/node/guides/node-aws-lambda.md -->
## Deploying AWS Lambda Functions in Node.js

{% aside type="danger" title="deprecated" %}
The @nx/aws-lambda plugin is deprecated and unmaintained.
We are committed to providing high-quality tooling to community, and we no longer have the capacity to keep this plugin updated.
{% /aside %}

This recipe guides you through setting up AWS Lambda functions with Nx.

## Getting set up

Depending on your current situation, you can either

- create a new project with the goal of primarily developing and publishing AWS Lambda functions
- add AWS Lambda functions to an existing Node.js project in an Nx workspace

### Starting a new project

To create a new project, run

```shell
npx create-nx-workspace@latest my-functions --preset=@nx/aws-lambda
```

### Configure existing projects

First, make sure you have `@nx/aws-lambda` installed.

```shell
nx add @nx/aws-lambda
```

Next, use the corresponding Nx generator to add the AWS Lambda configuration to an existing project:

```shell
nx generate @nx/aws-lambda:setup-functions
```

This will setup your project to use AWS Lambda functions:

1. Creates a new AWS lambda function in directory `functions/hello-world`.
2. Adds `samconfig.toml` and `template.yaml` in the root of the project.
3. Updates your `project.json` to have 2 new targets `serve-functions` & `deploy-functions`.

## Serve and develop your functions locally

The `project.json` should have a new target `serve-functions`:

```json
// project.json
{
  "name": "my-functions",
  ...
  "targets": {
    ...
    "serve-functions": {
      "command": "sam build && sam local start-api"
    },
    ...
  }
}
```

This allows to just run `nx serve-functions` to start a local server that serves your functions. As you can see it leverages the [SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-command-reference.html) underneath.

## Configure your AWS Lambda deploy settings

{% aside type="note" title="Prerequiste" %}
You need to configure your AWS credentials inside AWS before attempting to deploy.

{% /aside %}

## Deployment

The following requirements need to be met in order to run the AWS Lambda function deployment:

- [SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html#install-sam-cli-instructions) installed on your machine
- [esbuild](https://esbuild.github.io/getting-started/) available in your PATH (SAM need this). Example: `npm install -g esbuild`.

Your `samconfig.toml` stores default parameters for the SAM CLI. On the other hand, if you want to configure your lambda function settings such as the AWS region, runtime, and handler function, update your `template.yaml`.

The Nx `project.json` already contains a `deploy-functions` target we can invoke to trigger the deployment:

```json
// project.json
{
  "name": "my-functions",
  ...
  "targets": {
    ...
    "deploy-functions": {
      "command": "sam build && sam deploy --guided"
    }
  }
}
```

Just run:

```shell
nx deploy-functions
```

That's it! For monitoring or further permission settings, please refer to the AWS Lambda console.

---
<!-- source: https://nx.dev/docs/technologies/node/guides/node-server-fly-io.md -->
## Deploying a Node App to Fly.io

This recipe guides you through deploying your Nx based Node backend application to [Fly.io](https://fly.io/).

If you don't have an Nx powered Node project already, you can create a new one

```bash {% frame="none" %}
npx create-nx-workspace@latest my-api \
  --preset=node-standalone \
  --framework=fastify \
  --docker
```

This example uses [Fastify](https://www.fastify.dev/) but you can equally use [Express](https://expressjs.com/), [Koa](https://koajs.com/) or [NestJS](https://nestjs.com/) by selecting those frameworks during project creation.

You can also install the `@nx/node` package into an existing Nx monorepo and generate a new Node application.

{% cardgrid %}
{% linkcard title="Build Node backends - The Easy Way!" description="Starting with Nx 15.7 we now have first-class support for building Node backend applications" href="https://youtu.be/K4f-fMuAoRY" /%}
{% linkcard title="Easy, Modular Node Applications!" description="In this video, we're going to explore how to modularize a Node backend application"  href="https://youtu.be/LHLW0b4fr2w" /%}
{% /cardgrid %}

## Setup Docker

If you don't have a Docker setup already, you can leverage the `setup-docker` generator from the `@nx/node` package to create one:

```shell
npx nx g @nx/node:setup-docker
```

## Deploying the server to fly.io

Now, all we need to do is set up Fly.io and deploy! If you haven't used Fly.io before, you need to install the CLI and create an account. It'll only take a couple of minutes.

1. [Install flyctl](https://fly.io/docs/hands-on/install-flyctl/) - This is the Fly.io CLI.
2. Create an account with `fly auth signup` or `fly auth login`.

If you run into any issues, please refer to their [getting started guide](https://fly.io/docs/speedrun/).

Once you have authenticated using `fly`, we are ready to launch our project.

```bash {% frame="none" %}
fly launch --generate-name --no-deploy
```

{% aside type="caution" title="Dockerignore" %}

The setup process of Fly asks about creating a `.dockerignore` file based on the current `.gitignore`. If you confirm that step, make sure to remove `**/dist` from the `.dockerignore` file, otherwise the build will fail because the `Dockerfile` copies the build output from the `dist/` folder.

{% /aside %}

Once the setup completes, update the `fly.toml` file and make sure it uses the correct port:

```toml
// fly.toml
[[services]]
http_checks = []
internal_port = 3000 # Make sure this matches the port in Dockerfile
```

Now we can build and deploy the server.

```bash {% frame="none" %}
nx build
fly deploy
```

Fly.io will log out the monitoring link when the server is successfully deployed. You can open the server in a browser using the `fly open` command.

That's is! Our server is now deployed for the world to use.

## Optional: adding a deploy target

You can also automate the deployment by adding a target to your project. In addition, that allows us to leverage the Nx [task pipeline](/docs/concepts/task-pipeline-configuration) to make sure we first run the `build` and then the `deploy`.

By using [Nx run-commands](/docs/guides/tasks--caching/run-commands-executor), you can add a `deploy` target to the project. Go to the project's `project.json` file (under `targets`) and add the following:

```json
// project.json
"deploy": {
  "dependsOn": [
    "build"
  ],
  "command": "fly deploy"
}
```

Then you can run `nx deploy`, which will run the build (if necessary) before deploying. If the build ran before, **it would be cached**.

---
<!-- source: https://nx.dev/docs/technologies/node/guides/node-serverless-functions-netlify.md -->
## Add and Deploy Netlify Edge Functions with Node

Deploying Node.js serverless functions to Netlify involves a few steps.

## Getting set up

Depending on your current situation, you can either

- create a brand new project with the intention of solely hosting and deploying Netlify functions
- adding Netlify functions to an existing project

Let's walk through both scenarios.

### Starting a new project

For new workspaces you can create a Nx workspace with serverless function with one command:

```shell
npx create-nx-workspace@latest my-functions --preset=@nx/netlify --site=my-site
```

### Configure existing projects

You will need to install `@nx/netlify` if you haven't already.

```shell
nx add @nx/netlify
```

Next add the Netlify serverless configuration by running the following command:

```shell
nx g @nx/netlify:setup-functions
```

This will do a few things:

1. Create a new serverless function in `src/functions`.
2. Add the `netlify.toml` in the root of the project
3. Update your `project.json` to have 2 new targets `serve-functions` & `deploy-functions`.

## Serve your functions locally

To serve your functions locally, run:

```shell
nx serve-functions
```

## Configure your Netlify deploy settings

Make sure you have a site configured on Netlify (skip if you have already). You have mostly two options:

- either go to [app.netlify.com](https://app.netlify.com) and create a new site
- use the Netlify CLI and run `npx netlify deploy` which will walk you through the process

If you run `npx netlify deploy` in the workspace, the site ID will be automatically saved in the `.netlify/state.json` file. Alternatively adjust the `deploy-functions` in your `project.json` to include the `--site` flag:

```json
// project.json
{
  "targets": {
    ...
    "deploy-functions": {
      "dependsOn": ["lint"],
      "command": "npx netlify deploy --site=YOUR_SITE_ID",
      "configurations": {
        "production": {
          "command": "npx netlify deploy --site=YOUR_SITE_ID --prod"
        }
      }
    }
  }
}
```

## Deployment

To deploy them to Netlify, run:

```shell
nx deploy-functions
```

This creates a "draft deployment" to a temporary URL. If you want to do a production deployment, pass the `--prod` flag:

```shell
nx deploy-functions --prod
```

This invokes the "production" configuration of the `deploy-functions` target and passes the `--prod` flag to the Netlify CLI.

{% aside type="tip" title="Configure your CI for automated deployments" %}

Note that for a more stable and automated setup you might want to configure your CI to automatically deploy your functions.

{% /aside %}

---
<!-- source: https://nx.dev/docs/technologies/node/guides/wait-for-tasks.md -->
## Wait for Tasks

There are a couple ways to ensure that a set up task has been run before you run a particular task.

The most common solution is to use the [`dependsOn` property](/docs/reference/project-configuration#dependson). This works regardless of what executor the task is using. Once the dependent tasks have completed, the primary task will start. Reference the [project configuration documentation](/docs/reference/project-configuration#dependson) for more information.

If you are using the `@nx/js:node` executor, you can also use the [`waitUntilTargets` option](/docs/technologies/typescript/executors#node) of that executor. Once the dependent tasks emit something to the console, the primary task will start.

## waitUntilTargets

If you have a Node api called `api` and a database project called `db`, you may want to run `nx serve db` any time you run `nx serve api`.

To set that up, edit the `api` app's `project.json` file:

```json
// /apps/api/project.json
{
  "targets": {
    "serve": {
      "executor": "@nx/js:node",
      "options": {
        "waitUntilTargets": ["db:serve"]
      }
    }
  }
}
```

With this configuration in place, if you run `nx serve api`, Nx will first run `nx serve db`. The `nx serve api` process will not be launched until `nx serve db` outputs something to the console. Then both processes will continue executing in parallel. When you kill the main process, both the `db` and `api` processes will be stopped.

---
<!-- source: https://nx.dev/docs/technologies/node/introduction.md -->
## Node.js Plugin for Nx

The Node Plugin contains generators and executors to manage Node applications within an Nx workspace. It provides:

## Requirements

Below is a reference table that matches the most recent major versions of Nx to the versions of Node.js that they officially support, and are tested against.

The Nx policy is to support the LTS versions (i.e. actively maintained even numbered versions) of Node.js, but we will only remove support for older versions in a major version of Nx to avoid unexpected disruption. We may add support for newer LTS versions in a minor version of Nx as long as it would not break existing projects.

{% aside type="note" title="Other Node.js versions" %}
Other versions of Node.js **may** still work without issue for these versions of Nx. Those include versions which are already EOL, or odd version numbers (e.g. 23), which Node.js actively discourages using in production.
{% /aside %}

| Nx Version     | Node Version             |
| -------------- | ------------------------ |
| 22.x (current) | 24.x, ^22.12.0, ^20.19.0 |
| 21.x           | 24.x, ^22.12.0, ^20.19.0 |
| 20.x           | 22.x, 20.x, 18.x         |

We intentionally do not include an `"engines"` field in the `package.json` file for Nx in order to allow for user flexibility, but this table should be considered the official compatibility matrix.

This table will be updated from time to time to reflect the latest versions of Node.js that are supported. If you encounter issues with Nx, please make sure you are using a supported version of Node.js before filing an issue.

## Setting up @nx/node

### Installation

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/node` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
{% /aside %}

In any Nx workspace, you can install `@nx/node` by running the following command:

```shell
nx add @nx/node
```

This will install the correct version of `@nx/node`.

## Using the @nx/node plugin

### Creating applications

You can add a new application with the following:

```shell
nx g @nx/node:application apps/my-new-app
```

You can run your application with `nx serve my-new-app`, which starts it in watch mode.

### Creating libraries

Node libraries are a good way to separate features within your organization. To create a Node library run the following command:

```shell
nx g @nx/node:lib libs/my-new-lib

# If you want the library to be buildable or publishable to npm
nx g @nx/node:lib libs/my-new-lib --buildable
nx g @nx/node:lib libs/my-new-lib \
--publishable \
--importPath=@myorg/my-new-lib
```

## Using node

### Testing projects

You can run unit tests with:

```shell
nx test my-new-app
nx test my-new-lib
```

Replace `my-new-app` with the name or your project. This command works for both applications and libraries.

### Building projects

Node applications can be build with:

```shell
nx build my-new-app
```

And if you generated a library with `--buildable`, then you can build a library as well:

```shell
nx build my-new-lib
```

The output is in the `dist` folder. You can customize the output folder by setting `outputPath` in the project's `project.json` file.

### Application proxies

Generating Node applications has an option to configure other projects in the workspace to proxy API requests. This can be done by passing the `--frontendProject` with the project name you wish to enable proxy support for.

```shell
nx g @nx/node:application apps/my-new-app \
--frontendProject my-react-app
```

### Debugging

#### VSCode integration

When generating Node applications, Nx automatically creates a VSCode debugging configuration:

- **Automatic setup**: A `.vscode/launch.json` file is created with pre-configured debugging settings.
- **Smart port allocation**: Debug ports are automatically assigned starting from 9229, preventing conflicts between multiple applications.
- **Source map support**: Webpack configurations include `devtoolModuleFilenameTemplate` for accurate source mapping.
- **Multi-format support**: Supports debugging `.js`, `.mjs`, and `.cjs` output files.

To debug your Node application in VSCode:

1. Open your workspace in VSCode.
2. Set breakpoints in your TypeScript source files.
3. Go to the Debug panel `(Ctrl+Shift+D)`.
4. Select "Debug `{your-app-name}` with Nx" from the dropdown.
5. Click the play button or press `F5`.

The debugger will automatically:

- Start your application with `nx serve`.
- Attach to the Node.js debugger on the allocated port.
- Map compiled JavaScript back to your TypeScript source files.

#### Manual debugging

For advanced debugging scenarios, you can manually configure the debug port by setting the port option in the `serve` target in the project.json, or by running the serve command with `--port <number>`.

For additional information on Node.js debugging, see the [Node.js debugging getting started guide](https://nodejs.org/en/docs/guides/debugging-getting-started/#inspector-clients).

## More documentation

- [Using Cypress](/docs/technologies/test-tools/cypress/introduction)
- [Using Jest](/docs/technologies/test-tools/jest/introduction)

---
<!-- source: https://nx.dev/docs/technologies/node/migrations.md -->
## @nx/node Migrations

The @nx/node plugin provides various migrations to help you migrate to newer versions of node projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 22.6.x

### 22.6.0-package-updates
**Version**: 22.6.0-beta.10


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `koa` | `^3.1.2` | Updated only



## 22.0.x

### 22.0.2-package-updates
**Version**: 22.0.2-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `koa` | `^3.0.3` | Updated only
| `@types/koa` | `^3.0.0` | Updated only



## 20.4.x

### 20.4.0-package-updates
**Version**: 20.4.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `fastify` | `~5.2.1` | Updated only
| `fastify-plugin` | `~5.0.1` | Updated only
| `@fastify/autoload` | `~6.0.3` | Updated only
| `@fastify/sensible` | `~6.0.2` | Updated only
| `express` | `^4.21.2` | Updated only
| `@types/express` | `^4.17.21` | Updated only

---
<!-- source: https://nx.dev/docs/technologies/node/nest.md -->
## NestJS

{% index_page_cards path="technologies/node/nest" /%}

---
<!-- source: https://nx.dev/docs/technologies/node/nest/generators.md -->
## @nx/nest Generators

The @nx/nest plugin provides various generators to help you create and configure nest projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `application`
Nx Application Options Schema.

**Usage:**
```bash
nx generate @nx/nest:application [options]
```

**Aliases:** `app`

**Arguments:**
```bash
nx generate @nx/nest:application <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--e2eTestRunner` | string | Test runner to use for end to end (e2e) tests | `"jest"` |
| `--frontendProject` | string | Frontend project that needs to access this application. This sets up proxy configuration. |  |
| `--linter` | string | The tool to use for running lint checks. | `"none"` |
| `--name` | string | The name of the application. |  |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--standaloneConfig` | boolean | Split the project configuration into `<projectRoot>/project.json` rather than including it inside `workspace.json`. | `true` |
| `--strict` | boolean | Adds strictNullChecks, noImplicitAny, strictBindCallApply, forceConsistentCasingInFileNames and noFallthroughCasesInSwitch to tsconfig. | `false` |
| `--tags` | string | Add tags to the application (used for linting). |  |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"none"` |
| `--useProjectJson` | boolean | Use a `project.json` configuration file instead of inlining the Nx configuration in the `package.json` file. |  |

## `class`
Nest Class Options Schema.

**Usage:**
```bash
nx generate @nx/nest:class [options]
```

**Arguments:**
```bash
nx generate @nx/nest:class <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--language` | string | Nest class language. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"jest"` |

## `controller`
Nest Controller Options Schema.

**Usage:**
```bash
nx generate @nx/nest:controller [options]
```

**Arguments:**
```bash
nx generate @nx/nest:controller <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--language` | string | Nest controller language. |  |
| `--module` | string | Allows specification of the declaring module. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipImport` | boolean | Flag to skip the module import. | `false` |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"jest"` |

## `decorator`
Nest Decorator Options Schema.

**Usage:**
```bash
nx generate @nx/nest:decorator [options]
```

**Arguments:**
```bash
nx generate @nx/nest:decorator <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--language` | string | Nest decorator language. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |

## `filter`
Nest Filter Options Schema.

**Usage:**
```bash
nx generate @nx/nest:filter [options]
```

**Arguments:**
```bash
nx generate @nx/nest:filter <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--language` | string | Nest filter language. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"jest"` |

## `gateway`
Nest Gateway Options Schema.

**Usage:**
```bash
nx generate @nx/nest:gateway [options]
```

**Arguments:**
```bash
nx generate @nx/nest:gateway <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--language` | string | Nest gateway language. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"jest"` |

## `guard`
Nest Guard Options Schema.

**Usage:**
```bash
nx generate @nx/nest:guard [options]
```

**Arguments:**
```bash
nx generate @nx/nest:guard <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--language` | string | Nest guard language. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"jest"` |

## `interceptor`
Nest Interceptor Options Schema.

**Usage:**
```bash
nx generate @nx/nest:interceptor [options]
```

**Arguments:**
```bash
nx generate @nx/nest:interceptor <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--language` | string | Nest interceptor language. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"jest"` |

## `interface`
Nest Interface Options Schema.

**Usage:**
```bash
nx generate @nx/nest:interface [options]
```

**Arguments:**
```bash
nx generate @nx/nest:interface <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--skipFormat` | boolean | Skip formatting files. | `false` |

## `library`
Create a NestJS Library for Nx.

**Usage:**
```bash
nx generate @nx/nest:library [options]
```

**Aliases:** `lib`

**Arguments:**
```bash
nx generate @nx/nest:library <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--buildable` | boolean | Generate a buildable library. | `false` |
| `--controller` | boolean | Include a controller with the library. | `false` |
| `--global` | boolean | Add the Global decorator to the generated module. | `false` |
| `--importPath` | string | The library name used to import it, like @myorg/my-awesome-lib. Must be a valid npm name. |  |
| `--linter` | string | The tool to use for running lint checks. | `"none"` |
| `--name` | string | Library name. |  |
| `--publishable` | boolean | Create a publishable library. |  |
| `--service` | boolean | Include a service with the library. | `false` |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint "parserOptions.project" option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--skipTsConfig` | boolean | Do not update tsconfig.base.json for development experience. | `false` |
| `--strict` | boolean | Whether to enable tsconfig strict mode or not. | `true` |
| `--tags` | string | Add tags to the library (used for linting). |  |
| `--target` | string | The ES target, Nest suggest using es2021 or higher. | `"es2021"` |
| `--testEnvironment` | string | The test environment for jest, for node applications this should stay as node unless doing DOM testing. | `"node"` |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"none"` |
| `--useProjectJson` | boolean | Use a `project.json` configuration file instead of inlining the Nx configuration in the `package.json` file. |  |

## `middleware`
Nest Middleware Options Schema.

**Usage:**
```bash
nx generate @nx/nest:middleware [options]
```

**Arguments:**
```bash
nx generate @nx/nest:middleware <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--language` | string | Nest middleware language. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"jest"` |

## `module`
Nest Module Options Schema.

**Usage:**
```bash
nx generate @nx/nest:module [options]
```

**Arguments:**
```bash
nx generate @nx/nest:module <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--language` | string | Nest module language. |  |
| `--module` | string | The path to import the module. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipImport` | boolean | Flag to skip the module import. | `false` |

## `pipe`
Nest Pipe Options Schema.

**Usage:**
```bash
nx generate @nx/nest:pipe [options]
```

**Arguments:**
```bash
nx generate @nx/nest:pipe <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--language` | string | Nest pipe language. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"jest"` |

## `provider`
Nest Provider Options Schema.

**Usage:**
```bash
nx generate @nx/nest:provider [options]
```

**Arguments:**
```bash
nx generate @nx/nest:provider <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--language` | string | Nest provider language. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"jest"` |

## `resolver`
Nest Resolver Options Schema.

**Usage:**
```bash
nx generate @nx/nest:resolver [options]
```

**Arguments:**
```bash
nx generate @nx/nest:resolver <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--language` | string | Nest resolver language. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"jest"` |

## `resource`
Nest Resource Options Schema.

**Usage:**
```bash
nx generate @nx/nest:resource [options]
```

**Arguments:**
```bash
nx generate @nx/nest:resource <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--crud` | boolean | When true, CRUD entry points are generated. | `true` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipImport` | boolean | Flag to skip the module import. | `false` |
| `--type` | string | The transport layer. | `"rest"` |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"jest"` |

## `service`
Nest Service Options Schema.

**Usage:**
```bash
nx generate @nx/nest:service [options]
```

**Arguments:**
```bash
nx generate @nx/nest:service <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--language` | string | Nest service language. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"jest"` |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/nest:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/node/nest/introduction.md -->
## Nest.js Plugin for Nx

Nest.js is a framework designed for building scalable server-side applications. In many ways, Nest is familiar to Angular developers:

- It has excellent TypeScript support.
- Its dependency injection system is similar to the one in Angular.
- It emphasises testability.
- Its configuration APIs are similar to Angular as well.

Many conventions and best practices used in Angular applications can be also be used in Nest.

## Requirements

The `@nx/nest` plugin depends on `@nestjs/schematics` for code generation, which pins the supported NestJS major version.

| Nx Version     | NestJS Version |
| -------------- | -------------- |
| 22.x (current) | ^11.0.0        |
| 21.x           | ^11.0.0        |
| 20.x           | ^10.0.0        |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

## Setting up @nx/nest

### Generating a new workspace

To create a new workspace with Nest, run the following command:

```shell
npx create-nx-workspace my-workspace --preset=nest
```

Yarn users can use the following command instead:

```shell
yarn create nx-workspace my-workspace --preset=nest
```

### Installation

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/nest` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
{% /aside %}

In any Nx workspace, you can install `@nx/nest` by running the following command:

```shell
nx add @nx/nest
```

This will install the correct version of `@nx/nest`.

### Create applications

You can add a new Nest application with the following command:

```shell
nx g @nx/nest:app apps/my-nest-app
```

#### Application proxies

Generating Nest applications has an option to configure other projects in the workspace to proxy API requests. This can be done by passing the `--frontendProject` with the project name you wish to enable proxy support for.

```shell
nx g @nx/nest:app apps/my-nest-app --frontendProject my-angular-app
```

### Create libraries

You can add a new Nest library with the following command:

```shell
nx g @nx/nest:lib libs/my-nest-lib
```

To make the library `buildable`, use the following command:

```shell
nx g @nx/nest:lib libs/my-nest-lib --buildable
```

To make the library `publishable`, use the following command:

```shell
nx g @nx/nest:lib libs/my-nest-lib --publishable --importPath=@my-workspace/my-nest-lib
```

> Read more about [building and publishing libraries here](/docs/concepts/buildable-and-publishable-libraries).

### Nest generators

The Nest plugin for Nx extends the generators provided by Nest. Any commands that can be used with the Nest CLI can also be used with the `nx` command. The `--project` flag should be used for all Nest generators.

> `--project` is used to infer the root of the project where the generators will generate the files.

## Using nest

### Build

You can build an application with the following command:

```shell
nx build my-nest-app
```

This applies to `buildable` libraries as well

```shell
nx build my-nest-lib
```

#### Waiting for other builds

Setting the `waitUntilTargets` option with an array of projects (with the following format: `"project:target"`) will execute those commands before serving the Nest application.

### Serve

You can serve an application with the following command:

```shell
nx serve my-nest-app
```

The `serve` command runs the `build` target, and executes the application.

By default, the serve command will run in `watch` mode. This allows code to be changed, and the Nest application to be rebuilt automatically.

#### Debugging

Nest applications also have the `inspect` flag set, so you can attach your debugger to the running instance.

##### VSCode integration

When generating Nest applications, Nx automatically creates a VSCode debugging configuration:

- **Automatic setup**: A `.vscode/launch.json` file is created with pre-configured debugging settings.
- **Smart port allocation**: Debug ports are automatically assigned starting from 9229, preventing conflicts between multiple applications.
- **Source map support**: Webpack configurations include `devtoolModuleFilenameTemplate` for accurate source mapping.
- **Multi-format support**: Supports debugging `.js`, `.mjs`, and `.cjs` output files.

To debug your Nest application in VSCode:

1. Open your workspace in VSCode.
2. Set breakpoints in your TypeScript source files.
3. Go to the Debug panel `(Ctrl+Shift+D)`.
4. Select "Debug `{your-app-name}` with Nx" from the dropdown.
5. Click the play button or press `F5`.

The debugger will automatically:

- Start your application with `nx serve`.
- Attach to the Node.js debugger on the allocated port.
- Map compiled JavaScript back to your TypeScript source files.

##### Manual debugging

For advanced debugging scenarios, you can manually configure the debug port by setting the port option in the `serve` target in the `project.json`, or by running the serve command with `--port <number>`.

For additional information on Node.js debugging, see the [Node.js debugging getting started guide](https://nodejs.org/en/docs/guides/debugging-getting-started/#inspector-clients).

### Lint

You can lint an application with the following command:

```shell
nx lint my-nest-app
```

You can lint a library with the following command:

```shell
nx lint my-nest-lib
```

### Unit test

You can run unit test for an application with the following command:

```shell
nx test my-nest-app
```

You can run unit test for a library with the following command:

```shell
nx test my-nest-lib
```

## Using CLI plugins

Nest supports the use of various CLI plugins to enhance the development experience. Plugins can be configured via **transformers** property in NxWebpackPlugin.
As an example, to set up a [Swagger plugin](https://docs.nestjs.com/openapi/cli-plugin), modify the Nest application's Webpack configuration as follows:

```javascript
const { NxWebpackPlugin } = require('@nx/webpack');

module.exports = {
  // ...
  plugins: [
    new NxWebpackPlugin({
      // ...
      transformers: [
        {
          name: '@nestjs/swagger/plugin',
          options: {
            dtoFileNameSuffix: ['.dto.ts', '.entity.ts'],
          },
        },
      ],
    }),
  ],
};
```

## Deployment

Ensuring a smooth and reliable deployment of a Nest.js application in a production environment requires careful planning and the right strategy. Depending on your specific needs and infrastructure, you can choose from several deployment approaches. Below are four commonly used methods:

1. **Using Docker:**
   Create a Dockerfile that specifies the application's environment and dependencies. Build a Docker image and optionally push it to a container registry. Deploy and run the Docker container on the server. Use the `@nx/node:setup-docker` generator to set up Docker for your project.

2. **Installing Dependencies on the Server:**
   Transfer the build artifacts to the server, install all dependencies using the package manager of your choice, and start the application. Ensure that [NxAppWebpackPlugin](/docs/technologies/build-tools/webpack/guides/webpack-plugins#nxappwebpackplugin) is configured with `generatePackageJson: true` so that the build artifacts directory includes `package.json` and `package-lock.json` (or the equivalent files for other package managers).

3. **Transferring Pre-installed Dependencies:**
   Install dependencies during the build process, and transfer the build artifacts along with the `node_modules` directory to the server. Typically, the artifacts are archived for faster transfer and then unarchived on the server.

4. **Bundling Dependencies:**
   By default, Nx/Nest creates a setup that externalizes all dependencies, meaning they are not included in the bundle. This behavior can be adjusted using the `externalDependencies` parameter in the webpack configuration with [NxAppWebpackPlugin](/docs/technologies/build-tools/webpack/guides/webpack-plugins#nxappwebpackplugin). After bundling, transfer the package to the server and start the application.

{% aside type="note" title="Bundling Dependencies" %}
Bundling dependencies is typically not recommended for Node applications.
{% /aside %}

## More documentation

- [Using Jest](/docs/technologies/test-tools/jest/introduction)

---
<!-- source: https://nx.dev/docs/technologies/node/nest/migrations.md -->
## @nx/nest Migrations

The @nx/nest plugin provides various migrations to help you migrate to newer versions of nest projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 21.2.x

### 21.2.0-beta.2-package-updates
**Version**: 21.2.0-beta.2


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `nest` | `^11.0.0` | Updated only
| `@nestjs/schematics` | `^11.0.0` | Updated only

---
<!-- source: https://nx.dev/docs/technologies/react.md -->
## React

{% index_page_cards path="technologies/react" /%}

---
<!-- source: https://nx.dev/docs/technologies/react/executors.md -->
## @nx/react Executors

The @nx/react plugin provides various executors to help you create and configure react projects within your Nx workspace.
Below is a complete reference for all available executors and their options.

### `module-federation-dev-server`
Serve a web application.

### Examples

###### Basic Usage

The Module Federation Dev Server will serve a host application and find the remote applications associated with the host and serve them statically also.  
See an example set up of it below:

```json
{
  "serve": {
    "executor": "@nx/react:module-federation-dev-server",
    "configurations": {
      "production": {
        "buildTarget": "host:build:production"
      },
      "development": {
        "buildTarget": "host:build:development"
      }
    },
    "defaultConfiguration": "development",
    "options": {
      "port": 4200,
      "publicHost": "http://localhost:4200"
    }
  }
}
```

###### Serve host with remotes that can be live reloaded

The Module Federation Dev Server will serve a host application and find the remote applications associated with the host and serve a set selection with live reloading enabled also.  
See an example set up of it below:

```json
{
  "serve-with-hmr-remotes": {
    "executor": "@nx/react:module-federation-dev-server",
    "configurations": {
      "production": {
        "buildTarget": "host:build:production"
      },
      "development": {
        "buildTarget": "host:build:development"
      }
    },
    "defaultConfiguration": "development",
    "options": {
      "port": 4200,
      "publicHost": "http://localhost:4200",
      "devRemotes": [
        "remote1",
        {
          "remoteName": "remote2",
          "configuration": "development"
        }
      ]
    }
  }
}
```
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `allowedHosts` | string | This option allows you to whitelist services that are allowed to access the dev server. |  |
| `baseHref` | string | Base url for the application being built. |  |
| `buildTarget` | string | Target which builds the application. |  |
| `devRemotes` | array | List of Producer (remote) applications to run in development mode (i.e. using serve target). |  |
| `hmr` | boolean | Enable hot module replacement. | `false` |
| `host` | string | Host to listen on. | `"localhost"` |
| `isInitialHost` | boolean | Whether the Consumer (host) that is running this executor is the first in the project tree to do so. | `true` |
| `liveReload` | boolean | Whether to reload the page on change, using live-reload. | `true` |
| `maxWorkers` | number | Number of workers to use for type checking. |  |
| `memoryLimit` | number | Memory limit for type checking service process in `MB`. |  |
| `open` | boolean | Open the application in the browser. | `false` |
| `parallel` | number | Max number of parallel processes for building static Producers (remotes) |  |
| `pathToManifestFile` | string | Path to a Module Federation manifest file (e.g. `my/path/to/module-federation.manifest.json`) containing the dynamic Producer (remote) applications relative to the workspace root. |  |
| `port` | number | Port to listen on. | `4200` |
| `publicHost` | string | Public URL where the application will be served. |  |
| `skipRemotes` | array | List of Producer (remote) applications to not automatically serve, either statically or in development mode. This will not remove the Producers (remotes) from the `module-federation.config` file, and therefore the application may still try to fetch these Producers (remotes).
This option is useful if you have other means for serving the Producer (remote) application(s).
**NOTE:** Producers (remotes) that are not in the workspace will be skipped automatically. |  |
| `ssl` | boolean | Serve using `HTTPS`. | `false` |
| `sslCert` | string | SSL certificate to use for serving `HTTPS`. |  |
| `sslKey` | string | SSL key to use for serving `HTTPS`. |  |
| `static` | boolean | Whether to use a static file server instead of the webpack-dev-server. This should be used for Producer (remote) applications that are also Consumer (host) applications. |  |
| `staticRemotesPort` | number | The port at which to serve the file-server for the static Producers (remotes). |  |
| `watch` | boolean | Watches for changes and rebuilds application. | `true` |

### `module-federation-ssr-dev-server`
Serve a SSR Consumer (host) application along with its known Producers (remotes).


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `browserTarget` | string [**required**] | Target which builds the browser application. |  |
| `serverTarget` | string [**required**] | Target which builds the server application. |  |
| `devRemotes` | array | List of Producer (remote) applications to run in development mode (i.e. using serve target). |  |
| `host` | string | Host to listen on. | `"localhost"` |
| `isInitialHost` | boolean | Whether the Consumer (host) that is running this executor is the first in the project tree to do so. | `true` |
| `pathToManifestFile` | string | Path to a Module Federation manifest file (e.g. `my/path/to/module-federation.manifest.json`) containing the dynamic Producer (remote) applications relative to the workspace root. |  |
| `port` | number | The port to be set on `process.env.PORT` for use in the server. | `4200` |
| `skipRemotes` | array | List of Producer (remote) applications to not automatically serve, either statically or in development mode. |  |
| `ssl` | boolean | Serve using HTTPS. | `false` |
| `sslCert` | string | SSL certificate to use for serving HTTPS. |  |
| `sslKey` | string | SSL key to use for serving HTTPS. |  |
| `staticRemotesPort` | number | The port at which to serve the file-server for the static Producers (remotes). |  |

### `module-federation-static-server`
Serve a Consumer (host) application statically along with its Producers (remotes).


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `serveTarget` | string [**required**] |  |  |

---
<!-- source: https://nx.dev/docs/technologies/react/expo.md -->
## Expo

{% index_page_cards path="technologies/react/expo" /%}

---
<!-- source: https://nx.dev/docs/technologies/react/expo/executors.md -->
## @nx/expo Executors

The @nx/expo plugin provides various executors to help you create and configure expo projects within your Nx workspace.
Below is a complete reference for all available executors and their options.

### `build`
Start an EAS build for your expo project.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `autoSubmit` | boolean | Submit on build complete using the submit profile with the same name as the build profile | `false` |
| `autoSubmitWithProfile` | string | Submit on build complete using the submit profile with provided name |  |
| `buildLoggerLevel` | string | The level of logs to output during the build process. | `"info"` |
| `clearCache` | boolean | Clear cache before the build | `false` |
| `freezeCredentials` | boolean | Prevent the build from updating credentials in non-interactive mode | `false` |
| `interactive` | boolean | Run command in interactive mode | `true` |
| `json` | boolean | Enable JSON output, non-JSON messages will be printed to stderr | `false` |
| `local` | boolean | Run build locally [experimental] | `false` |
| `message` | string | A short message describing the build |  |
| `output` | string | Output path for local build |  |
| `platform` | any | The platform to build the app, exaple values: ios, android, all. |  |
| `profile` | string | Name of the build profile from eas.json. Defaults to "production" if defined in eas.json. |  |
| `wait` | boolean | Wait for build(s) to complete | `true` |

### `build-list`
List all Expo Application Services (EAS) builds for your Expo project.

The `build-list` command allows to check the details of your Expo Application Services (EAS) build status.

`project.json`:

```json
{
  "name": "mobile",
  //...
  "targets": {
    //...
    "build-list": {
      "executor": "@nx/expo:build-list",
      "options": {}
    }
    //...
  }
}
```

```shell
nx run mobile:build-list
```

### Examples

###### Get Status of Different Platforms

The `platform` option allows you to check build status of different platform (e.g. android, ios, all):

```json
    "build-list": {
      "executor": "@nx/expo:build-list",
      "options": {
        "platform": "ios"
      }
    }
```

###### Get Status Interactively

The `interactive` option allows you to specify whether to use interactive mode:

```json
    "build-list": {
      "executor": "@nx/expo:build-list",
      "options": {
        "interactive": true
      }
    }
```

###### Get Status in JSON Format

The `json` option allows you to print the output in JSON format:

```json
    "build-list": {
      "executor": "@nx/expo:build-list",
      "options": {
        "interactive": false,
        "json": true
      }
    }
```

---
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `appBuildVersion` | string | App build version of EAS build |  |
| `appIdentifier` | string | App identifier of EAS build |  |
| `appVersion` | string | App version of EAS build |  |
| `buildProfile` | string | Build profile of EAS build |  |
| `channel` | string | Channel of EAS build |  |
| `distribution` | any | Distribution of EAS build |  |
| `gitCommitHash` | string | Git commit hash of EAS build |  |
| `interactive` | boolean | Run the command in interactive mode. |  |
| `json` | boolean | Enable JSON output, non-JSON messages will be printed to stderr |  |
| `limit` | number | Limit of numbers to list EAS builds |  |
| `platform` | any | The platform to build the app. |  |
| `runtimeVersion` | string | Runtime version of EAS build |  |
| `sdkVersion` | string | SDK version of EAS build |  |
| `status` | any | Status of EAS build |  |

### `ensure-symlink`
Ensure workspace node_modules is symlink under app's node_modules folder.


### `export`
Export the JavaScript and assets for your app using Metro/webpack bundler.

`project.json`:

```json
{
  "name": "mobile",
  //...
  "targets": {
    //...
    "export": {
      "executor": "@nx/expo:export",
      "options": {
        "outputs": ["{options.outputDir}"],
        "platform": "all",
        "outputDir": "dist/apps/mobile"
      },
      "dependsOn": ["sync-deps"]
    }
    //...
  }
}
```

```shell
nx run mobile:export
```

### Examples

###### Specify outputDir

The `outputDir` option allows you to specify the output directory of your bundle:

```json
    "export": {
      "executor": "@nx/expo:export",
      "outputs": ["{options.outputDir}"],
      "options": {
        "platform": "all",
        "bundler": "metro",
        "outputDir": "dist/apps/mobile"
      },
      "dependsOn": ["sync-deps"]
    },
```

or run command: `nx run mobile:export --outputDir=dist/apps/mobile`.

###### Specify the platform

The `platform` option allows you to specify the platform to compile with metro bundler: "ios", "android", "all", and "web".

For example, to bundle for web:

```json
    "export": {
      "executor": "@nx/expo:export",
      "outputs": ["{options.outputDir}"],
      "options": {
        "platform": "web",
        "bundler": "metro",
        "outputDir": "dist/apps/dogs"
      },
      "dependsOn": ["sync-deps"]
    },
```

or run command `nx export mobile --platform=web`.

###### Bundle for development

The `dev` option allows you to bundle for development environments.

```json
    "export": {
      "executor": "@nx/expo:export",
      "outputs": ["{options.outputDir}"],
      "options": {
        "platform": "web",
        "bundler": "metro",
        "outputDir": "dist/apps/dogs",
        "dev": true
      },
      "dependsOn": ["sync-deps"]
    },
```

or run command `nx export mobile --dev`.

###### Clear bundle cache

The `clear` option allows you to clear bundle cache.

```json
    "export": {
      "executor": "@nx/expo:export",
      "outputs": ["{options.outputDir}"],
      "options": {
        "platform": "web",
        "bundler": "metro",
        "outputDir": "dist/apps/dogs",
        "clear": true
      },
      "dependsOn": ["sync-deps"]
    },
```

or run command `nx export mobile --clear`.
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `platform` | any [**required**] | Choose the platform to compile for | `"all"` |
| `clear` | boolean | Clear the bundler cache before exporting |  |
| `dev` | boolean | Configure static files for developing locally using a non-https server |  |
| `dumpAssetmap` | boolean | When bundler is metro, whether to dump the asset map for further processing |  |
| `maxWorkers` | number | When bundler is metro, the maximum number of tasks to allow the bundler to spawn |  |
| `minify` | boolean | Minify source |  |
| `outputDir` | string | Relative to workspace root, the directory to export the static files to. Default: dist |  |
| `sourceMaps` | boolean | When bundler is metro, whether to emit JavaScript source maps |  |

### `install`
Install a module or other package to a project.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `check` | boolean | Check which installed packages need to be updated | `false` |
| `fix` | boolean | Automatically update any invalid package versions | `false` |
| `force` | boolean | Force the installation of a package, even if it is already installed | `false` |
| `packages` | array | The names of packages to install | `[]` |

### `prebuild`
Create native iOS and Android project files for building natively.

The `prebuild` command generates native code before a native app can compile.

`project.json`:

```json
{
  "name": "mobile",
  //...
  "targets": {
    //...
    "prebuild": {
      "executor": "@nx/expo:prebuild",
      "options": {}
    }
    //...
  }
}
```

```shell
nx run mobile:prebuild
```

### Examples

###### Generate Native Code for Different Platforms

The `platform` option allows you to specify the platform to generate native code for (e.g. android, ios, all).

```json
    "prebuild": {
      "executor": "@nx/expo:prebuild",
      "options": {
        "platform": "android"
      }
    }
```

###### Regenerate Native Code

The `clean` option allows you to delete the native folders and regenerate them before apply changes.

```json
    "prebuild": {
      "executor": "@nx/expo:prebuild",
      "options": {
        "clean": true
      }
    }
```

###### Install NPM Packages and CocoaPods

The `install` option allows you to install NPM Packages and CocoaPods.

```json
    "prebuild": {
      "executor": "@nx/expo:prebuild",
      "options": {
        "install": true
      }
    }
```

---
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `platform` | any [**required**] | Platforms to sync | `"all"` |
| `clean` | boolean | Delete the native folders and regenerate them before applying changes | `false` |
| `install` | boolean | Installing npm packages and CocoaPods. | `true` |
| `template` | string | Project template to clone from. File path pointing to a local tar file or a github repo |  |

### `run`
Run Expo target options.

The `run` command allows you to compile your app locally.

`project.json`:

```json
{
  "name": "mobile",
  //...
  "targets": {
    //...
    "run-ios": {
      "executor": "@nx/expo:run",
      "options": {
        "platform": "ios"
      }
    },
    "run-android": {
      "executor": "@nx/expo:run",
      "options": {
        "platform": "android"
      }
    }
    //...
  }
}
```

```shell
nx run mobile:run-ios
nx run mobile:run-android
```

### Examples

###### Compile Android with Different Variants

The `variant` option allows you to specify the compile Android app with variants defined in `build.gradle` file (e.g. debug, release).

```json
    "run-android": {
      "executor": "@nx/expo:run",
      "options": {
        "platform": "android",
        "variant": "release"
      }
    }
```

###### Compile iOS with Different Configurations

The `xcodeConfiguration` option allows you to specify Xcode configuration to use (e.g. Debug or Release).

```json
    "run-ios": {
      "executor": "@nx/expo:run",
      "options": {
        "platform": "ios",
        "xcodeConfiguration": "Release"
      }
    }
```

###### Run on a device

The `device` option allows you to launch your app in a specific device name or UDID.
To see all your iOS simulators: run `xcrun simctl list devices available`.
To see all your Android emulators, run: `emulator -list-avds`.

```json
    "run-ios": {
      "executor": "@nx/expo:run",
      "options": {
        "platform": "ios",
        "device": "iPhone 14"
      }
    },
    "run-android": {
      "executor": "@nx/expo:run",
      "options": {
        "platform": "android",
        "device": "Pixel_XL_API_Tiramisu"
      }
    }
```

---
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `platform` | any [**required**] | Platform to run for (ios, android). | `"ios"` |
| `buildCache` | boolean | Should use derived data for builds. |  |
| `bundler` | boolean | Whether to skip starting the Metro bundler. True to start it, false to skip it. |  |
| `clean` | boolean | Delete the native folders and regenerate them before applying changes | `false` |
| `device` | string | Device name or UDID to build the app on. The value is not required if you have a single device connected. |  |
| `install` | boolean | Installing npm packages and CocoaPods before building. | `true` |
| `port` | number | Port to start the Metro bundler on | `8081` |
| `scheme` | string | (iOS) Explicitly set the Xcode scheme to use |  |
| `variant` | string | (Android) Specify your app's build variant (e.g. debug, release). | `"debug"` |
| `xcodeConfiguration` | string | (iOS) Xcode configuration to use. Debug or Release | `"Debug"` |

### `serve`
Packager Server target options.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `clear` | boolean | Clear the Metro bundler cache |  |
| `dev` | boolean | Turn development mode on or off |  |
| `maxWorkers` | number | Maximum number of tasks to allow Metro to spawn |  |
| `minify` | boolean | Whether or not to minify code |  |
| `port` | number | Port to start the native Metro bundler on (does not apply to web or tunnel) | `4200` |

### `start`
Packager Server target options.

`project.json`:

```json
{
  "name": "mobile",
  //...
  "targets": {
    //...
    "start": {
      "executor": "@nx/expo:start",
      "options": {
        "port": 8081
      }
    }
    //...
  }
}
```

```shell
nx run mobile:start
```

### Examples

###### Specify starting on platform

The `ios`, `android` and `web` option allows you to start the server on different platforms.

Opens your app in Expo Go in a currently running iOS simulator on your computer:

```json
    "start": {
      "executor": "@nx/expo:start",
      "options": {
        "port": 8081,
        "ios": true
      }
    }
```

or run command `nx start <your app name> --ios`.

Opens your app in Expo Go on a connected Android device

```json
    "start": {
      "executor": "@nx/expo:start",
      "options": {
        "port": 8081,
        "android": true
      }
    }
```

or run command `nx start <your app name> --android`.

Opens your app in a web browser:

```json
    "start": {
      "executor": "@nx/expo:start",
      "options": {
        "port": 8081,
        "web": true
      }
    }
```

or run command `nx start <your app name> --web`.

###### Specify the host

The `host` option allows you to specify the type of host to use. `lan` uses the local network; `tunnel` ues any network by tunnel through ngrok; `localhost` connects to the dev server over localhost.

```json
    "start": {
      "executor": "@nx/expo:start",
      "options": {
        "port": 8081,
        "host": "localhost"
      }
    }
```

###### Starts the server with cache reset

The `clear` option allows you to remove Metro bundler cache.

```json
    "start": {
      "executor": "@nx/expo:start",
      "options": {
        "port": 8081,
        "clear": true
      }
    }
```

---
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `android` | boolean | Opens your app in Expo Go on a connected Android device |  |
| `clear` | boolean | Clear the Metro bundler cache |  |
| `dev` | boolean | Turn development mode on or off |  |
| `devClient` | boolean | Experimental: Starts the bundler for use with the expo-development-client |  |
| `forceManifestType` | string | Override auto detection of manifest type. |  |
| `host` | string | lan (default), tunnel, localhost. Type of host to use. lan uses the local network; tunnel ues any network by tunnel through ngrok; localhost connects to the dev server over localhost. |  |
| `https` | boolean | To start webpack with https or http protocol |  |
| `ios` | boolean | Opens your app in Expo Go in a currently running iOS simulator on your computer |  |
| `lan` | boolean | Same as --host lan |  |
| `localhost` | boolean | Same as --host localhost |  |
| `maxWorkers` | number | Maximum number of tasks to allow Metro to spawn |  |
| `minify` | boolean | Whether or not to minify code |  |
| `offline` | boolean | Allows this command to run while offline |  |
| `port` | number | Port to start the native Metro bundler on (does not apply to web or tunnel) | `19000` |
| `privateKeyPath` | string | Path to private key for code signing. Default: 'private-key.pem' in the same directory as the certificate specified by the expo-updates configuration in app.json. |  |
| `scheme` | string | Custom URI protocol to use with a development build |  |
| `tunnel` | boolean | Same as --host tunnel |  |
| `web` | boolean |  Opens your app in a web browser |  |

### `submit`
Submit app binary to App Store and/or Play Store.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `id` | string | Build ID to submit |  |
| `interactive` | boolean | Run command in interactive mode | `true` |
| `latest` | boolean | Submit the latest build for specified platform |  |
| `path` | string | Path to the .apk/.aab/.ipa file |  |
| `platform` | any | The platform to build the app, example values: ios, android, all. |  |
| `profile` | string | Name of the build profile from eas.json. Defaults to "production" if defined in eas.json. |  |
| `url` | string | URL to the .apk/.aab/.ipa file, app archive url |  |
| `wait` | boolean | Wait for build(s) to complete | `true` |

### `sync-deps`
Updates package.json with project dependencies.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `all` | boolean | Copy all dependencies and devDependencies from the workspace root package.json. | `false` |
| `exclude` | array | An array of npm packages to exclude. | `[]` |
| `excludeImplicit` | boolean | This will ignore npm packages from projects listed in implicitDependencies (e.g. backend API projects) | `false` |
| `include` | array | An array of additional npm packages to include. | `[]` |

### `update`
Start an EAS update for your expo project.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `auto` | boolean | Use the current git branch and commit message for the EAS branch and update message | `false` |
| `branch` | string | Branch to publish the update group on |  |
| `group` | string | Update group to republish |  |
| `inputDir` | string | Location of the bundle |  |
| `interactive` | boolean | Run command in interactive mode | `true` |
| `json` | boolean | Enable JSON output, non-JSON messages will be printed to stderr | `false` |
| `message` | string | A short message describing the update |  |
| `platform` | any | The platform to build the app, example values: ios, android, all. | `"all"` |
| `privateKeyPath` | string | File containing the PEM-encoded private key corresponding to the certificate in expo-updates' configuration. Defaults to a file named "private-key.pem" in the certificate's directory. |  |
| `republish` | boolean | Republish a previous update within a branch | `false` |
| `skipBundler` | boolean | Skip running Expo CLI to bundle the app before publishing | `false` |

---
<!-- source: https://nx.dev/docs/technologies/react/expo/generators.md -->
## @nx/expo Generators

The @nx/expo plugin provides various generators to help you create and configure expo projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `application`
Create an Expo Application for Nx.

**Usage:**
```bash
nx generate @nx/expo:application [options]
```

**Aliases:** `app`

**Arguments:**
```bash
nx generate @nx/expo:application <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--displayName` | string | The display name to show in the application. Defaults to name. |  |
| `--e2eTestRunner` | string | Adds the specified e2e test runner | `"none"` |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"none"` |
| `--name` | string | The name of the application. |  |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint "parserOptions.project" option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--standaloneConfig` | boolean | Split the project configuration into `<projectRoot>/project.json` rather than including it inside `workspace.json`. | `true` |
| `--tags` | string | Add tags to the application (used for linting) |  |
| `--unitTestRunner` | string | Test runner to use for unit tests | `"none"` |
| `--useProjectJson` | boolean | Use a `project.json` configuration file instead of inlining the Nx configuration in the `package.json` file. |  |

## `component`
Create a Expo Component for Nx.

**Usage:**
```bash
nx generate @nx/expo:component [options]
```

**Aliases:** `c`

**Arguments:**
```bash
nx generate @nx/expo:component <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--classComponent` | boolean | Use class components instead of functional component. | `false` |
| `--export` | boolean | When true, the component is exported from the project index.ts (if it exists). | `false` |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. |  |
| `--name` | string | The component symbol name. Defaults to the last segment of the file path. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipTests` | boolean | When true, does not create "spec.ts" test files for the new component. | `false` |

## `convert-to-inferred`
Convert existing Expo project(s) using `@nx/expo:*` executors to use `@nx/expo/plugin`. Defaults to migrating all projects. Pass '--project' to migrate only one target.

**Usage:**
```bash
nx generate @nx/expo:convert-to-inferred [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string | The project to convert from using the `@nx/expo:*` executors to use `@nx/expo/plugin`. |  |
| `--skipFormat` | boolean | Whether to format files at the end of the migration. | `false` |

## `library`
Create a Expo Library for Nx.

**Usage:**
```bash
nx generate @nx/expo:library [options]
```

**Aliases:** `lib`

**Arguments:**
```bash
nx generate @nx/expo:library <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--buildable` | boolean | Generate a buildable library. | `false` |
| `--importPath` | string | The library name used to import it, like @myorg/my-awesome-lib |  |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"none"` |
| `--name` | string | Library name |  |
| `--publishable` | boolean | Create a publishable library. |  |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint "parserOptions.project" option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--skipTsConfig` | boolean | Do not update tsconfig.json for development experience. | `false` |
| `--strict` | boolean | Whether to enable tsconfig strict mode or not. | `true` |
| `--tags` | string | Add tags to the library (used for linting). |  |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"none"` |
| `--useProjectJson` | boolean | Use a `project.json` configuration file instead of inlining the Nx configuration in the `package.json` file. |  |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/expo:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/react/expo/introduction.md -->
## Expo Plugin for Nx

Expo is an open-source framework for apps that run natively on Android, iOS, and the web. Expo brings together the best of mobile and the web and enables many important features for building and scaling an app.

Expo is a set of tools built on top of React Native. The Nx Plugin for Expo contains generators for managing Expo applications and libraries within an Nx workspace.

## Requirements

The `@nx/expo` plugin supports the following package versions.

| Package        | Supported Versions   |
| -------------- | -------------------- |
| `metro-config` | >= 0.82.0            |
| `expo`         | ~53.0.0 \|\| ~54.0.0 |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

## Setting up Expo

To create a new workspace with Expo, run the following command:

```shell
 npx create-nx-workspace@latest --preset=expo --appName=your-app-name
```

### Installation

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/expo` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
{% /aside %}

In any Nx workspace, you can install `@nx/expo` by running the following command:

```shell
nx add @nx/expo
```

This will install the correct version of `@nx/expo`.

### How @nx/expo infers tasks

The `@nx/expo` plugin will create a task for any project that has an app configuration file present. Any of the following files will be recognized as an app configuration file:

- `app.config.js`
- `app.json`

In the app config file, it needs to have key `expo`:

```json
// app.json
{
  "expo": {
    "name": "MyProject",
    "slug": "my-project"
  }
}
```

### View inferred tasks

To view inferred tasks for a project, open the [project details view](/docs/concepts/inferred-tasks) in Nx Console or run `nx show project my-project --web` in the command line.

### @nx/expo configuration

The `@nx/expo/plugin` is configured in the `plugins` array in `nx.json`.

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/expo/plugin",
      "options": {
        "startTargetName": "start",
        "serveTargetName": "serve",
        "runIosTargetName": "run-ios",
        "runAndroidTargetName": "run-android",
        "exportTargetName": "export",
        "prebuildTargetName": "prebuild",
        "installTargetName": "install",
        "buildTargetName": "build",
        "submitTargetName": "submit"
      }
    }
  ]
}
```

Once a Expo configuration file has been identified, the targets are created with the name you specify under `startTargetName`, `serveTargetName`, `runIosTargetName`, `runAndroidTargetname`, `exportTargetName`, `prebuildTargetName`, `installTargetName`, `buildTargetName` or `submitTargetName` in the `nx.json` `plugins` array. The default names for the inferred targets are `start`, `serve`, `run-ios`, `run-anroid`, `export`, `prebuild`, `install`, `build` and `submit`.

### Creating applications

Add a new application to your workspace with the following command:

```shell
nx g @nx/expo:app apps/my-app
```

Start the application by running:

```shell
nx start my-app
```

### Generating libraries

To generate a new library run:

```shell
npx nx g @nx/expo:lib libs/your-lib-name
```

### Generating components

To generate a new component inside library run:

```shell
npx nx g @nx/expo:component libs/your-lib-name/src/your-component-name --export
```

Replace `your-lib-name` with the app's name as defined in your `tsconfig.base.json` file or the `name` property of your `package.json`

## Using Expo

### Start a development server

You can start a development server by running:

```shell
nx start <app-name>
```

### Compile app locally

You can compile your app locally with `run-ios` and `run-android` commands:

{% tabs syncKey="platform" %}
{% tabitem label="iOS" %}

Compile for iOS:

```shell
nx run-ios <app-name>
```

{% /tabitem %}
{% tabitem label="Android" %}

Compile for Android:

```shell
nx run-android <app-name>
```

{% /tabitem %}
{% /tabs %}

To run these commands, you need to have your development environment setup. To run an iOS app,it can only be run on a Mac, and Xcode must be installed. Similarly, to run an Android app, it requires Android Studio and Java to be installed and configured on your computer. Setup steps: https://reactnative.dev/docs/environment-setup.

### Compile web assets

You can build your JavaScript bundle using Metro bundler by running:

```shell
nx export <app-name>
```

{% tabs syncKey="platform" %}
{% tabitem label="All Platforms" %}

Compile for all platforms:

```shell
nx export <app-name> --platform=all
```

{% /tabitem %}
{% tabitem label="iOS" %}

Compile for iOS:

```shell
nx export <app-name> --platform=ios
```

{% /tabitem %}
{% tabitem label="Android" %}

Compile for Android:

```shell
nx export <app-name> --platform=android
```

{% /tabitem %}
{% tabitem label="Web" %}

Compile for Web:

```shell
nx export <app-name> --platform=web
```

{% /tabitem %}
{% /tabs %}

### Generate native code

To generate native code, run:

```shell
nx prebuild <app-name>
```

{% tabs syncKey="platform" %}
{% tabitem label="All Platforms" %}

Generate for all platforms:

```shell
nx prebuild <app-name> --platform=all
```

{% /tabitem %}
{% tabitem label="iOS" %}

Generate for iOS:

```shell
nx prebuild <app-name> --platform=ios
```

{% /tabitem %}
{% tabitem label="Android" %}

Generate for Android:

```shell
nx prebuild <app-name> --platform=android
```

{% /tabitem %}
{% /tabs %}

### Install compatible npm packages

To install packages that is compatible with current version of Expo, run:

```shell
nx install <app-name>
```

Unlike npm's `install` command, this `install` command will install the exact right version for currently installed copy of Expo.

To install a specify NPM package, run:

```shell
nx install <app-name> --packages=<packpage-name>
nx install <app-name> --packages=<packpage-name-1>,<packpage-name-2>,<packpage-name-3>
```

To check and fix package versions, run:

{% tabs %}
{% tabitem label="check" %}

Check which packages needed to be updated:

```shell
nx install <app-name> --check
```

{% /tabitem %}
{% tabitem label="fix" %}

Automatically update invalid packages versions:

```shell
nx install <app-name> --fix
```

{% /tabitem %}
{% /tabs %}

### Run an EAS build

Expo Application Services (EAS) are deeply integrated cloud services for Expo and React Native apps. EAS Build is a hosted service for building app binaries for your Expo and React Native projects.

To run an EAS build:

```shell
nx build <app-name>
```

If you are not signed into an EAS account, run the following command to log in:

```shell
npx eas login
```

To check the details of your build status, run:

```shell
nx build-list  <app-name>
```

### Submit an EAS build

EAS Submit is a hosted service for uploading and submitting your app binaries to the app stores. Since it's a hosted service, you can submit your app to both stores as long as you can run EAS CLI on your machine.

To submit an EAS build:

```shell
nx submit <app-name>
```

### Update an EAS build

EAS Update is a hosted service that serves updates for projects using the `expo-updates` library.

EAS Update makes fixing small bugs and pushing quick fixes a snap in between app store submissions. It accomplishes this by allowing an end-user's app to swap out the non-native parts of their app (for example, JS, styling, and image changes) with a new update that contains bug fixes and other updates.

To update an EAS build:

```shell
nx update <app-name>
```

### Testing projects

You can run unit tests with:

```shell
nx test <project-name>
```

## Expo commands

Below table is a map between expo commands and Nx commands:

| Expo Commands      | Nx Commands                 |
| ------------------ | --------------------------- |
| `expo start`       | `nx start <app-name>`       |
| `expo run:ios`     | `nx run-ios <app-name>`     |
| `expo run:android` | `nx run-android <app-name>` |
| `expo export`      | `nx export <app-name>`      |
| `expo prebuild`    | `nx prebuild <app-name>`    |
| `expo install`     | `nx install <app-name>`     |
| `eas build`        | `nx build <app-name>`       |
| `eas build:list`   | `nx build-list <app-name>`  |
| `eas update`       | `nx update <app-name>`      |
| `eas submit`       | `nx submit <app-name>`      |

## More documentation

- [Using Detox](/docs/technologies/test-tools/detox/introduction)
- [Using Jest](/docs/technologies/test-tools/jest/introduction)

---
<!-- source: https://nx.dev/docs/technologies/react/expo/migrations.md -->
## @nx/expo Migrations

The @nx/expo plugin provides various migrations to help you migrate to newer versions of expo projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 22.2.x

### `update-22-2-0-create-ai-instructions-for-expo-54`
**Version**: 22.2.0-beta.3

Create AI migration instructions for Expo SDK 54 upgrade


### `update-22-2-0-add-expo-system-ui`
**Version**: 22.2.0-beta.3

Add expo-system-ui dependency for Expo SDK 54


### `update-22-2-0-update-jest-for-expo-54`
**Version**: 22.2.0-beta.3

Update Jest configuration for Expo SDK 54

#### Requires

| Name | Version |
|------|---------|
 `expo` | `>= 54.0.0` |

### 22.2.0-package-updates
**Version**: 22.2.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `expo` | `~54.0.0` | Updated only
| `expo-splash-screen` | `~31.0.11` | Updated only
| `expo-status-bar` | `~3.0.8` | Updated only
| `expo-system-ui` | `~6.0.8` | Updated only
| `@expo/cli` | `~54.0.16` | Updated only
| `babel-preset-expo` | `~54.0.7` | Updated only
| `react` | `^19.1.0` | Updated only
| `react-dom` | `^19.1.0` | Updated only
| `@types/react` | `^19.1.0` | Updated only
| `react-native` | `~0.81.5` | Updated only
| `react-native-web` | `~0.21.0` | Updated only
| `@expo/metro-config` | `~54.0.9` | Updated only
| `@expo/metro-runtime` | `~6.1.2` | Updated only
| `react-native-svg-transformer` | `~1.5.1` | Updated only
| `react-native-svg` | `15.12.1` | Updated only
| `@testing-library/react-native` | `~13.2.0` | Updated only
| `jest-expo` | `~54.0.13` | Updated only
| `@babel/runtime` | `~7.27.6` | Updated only
| `metro-config` | `~0.83.0` | Updated only
| `metro-resolver` | `~0.83.0` | Updated only



## 21.4.x

### `update-21-4-0-remove-deprecated-deps`
**Version**: 21.4.0-beta.0

Remove deprecated dependencies from package.json


### `update-21-4-0-update-splash-screen-config`
**Version**: 21.4.0-beta.0

Update Expo splash screen configuration to use the new format


### `update-21-4-0-add-jest-resolver`
**Version**: 21.4.0-beta.0

Add custom Jest resolver to handle Expo winter runtime issues


### 21.4.0-package-updates
**Version**: 21.4.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `expo` | `~53.0.10` | Updated only
| `expo-splash-screen` | `~0.30.9` | Updated only
| `expo-status-bar` | `~2.2.3` | Updated only
| `@expo/cli` | `~0.24.14` | Updated only
| `babel-preset-expo` | `~13.2.0` | Updated only
| `react` | `19.0.0` | Updated only
| `react-dom` | `19.0.0` | Updated only
| `@types/react` | `~19.0.10` | Updated only
| `react-native` | `~0.79.3` | Updated only
| `react-native-web` | `~0.20.0` | Updated only
| `@expo/metro-config` | `~0.20.14` | Updated only
| `@expo/metro-runtime` | `~5.0.4` | Updated only
| `react-native-svg-transformer` | `~1.5.1` | Updated only
| `react-native-svg` | `~15.11.2` | Updated only
| `@testing-library/react-native` | `~13.2.0` | Updated only
| `jest-expo` | `~53.0.7` | Updated only
| `@babel/runtime` | `~7.27.6` | Updated only



## 20.3.x

### 20.3.0-package-updates
**Version**: 20.3.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `expo` | `~52.0.11` | Updated only
| `expo-splash-screen` | `~0.29.13` | Updated only
| `expo-status-bar` | `~2.0.0` | Updated only
| `@expo/cli` | `~0.21.8` | Updated only
| `babel-preset-expo` | `~12.0.1` | Updated only
| `react` | `~18.3.1` | Updated only
| `react-dom` | `~18.3.1` | Updated only
| `react-test-renderer` | `~18.3.1` | Updated only
| `@types/react` | `~18.3.12` | Updated only
| `react-native` | `~0.76.3` | Updated only
| `react-native-web` | `~0.19.13` | Updated only
| `@expo/metro-config` | `~0.19.4` | Updated only
| `@expo/metro-runtime` | `~4.0.0` | Updated only
| `react-native-svg-transformer` | `~1.5.0` | Updated only
| `react-native-svg` | `~15.8.0` | Updated only
| `@testing-library/react-native` | `~12.9.0` | Updated only
| `jest-expo` | `~52.0.2` | Updated only
| `@babel/runtime` | `7.26.0` | Updated only

---
<!-- source: https://nx.dev/docs/technologies/react/generators.md -->
## @nx/react Generators

The @nx/react plugin provides various generators to help you create and configure react projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `application`
Create a React application for Nx.

### Examples

###### Simple Application

Create an application named `my-app`:

```bash
nx g @nx/react:application apps/my-app
```

###### Application using Vite as bundler

Create an application named `my-app`:

```bash
nx g @nx/react:app apps/my-app --bundler=vite
```

When choosing `vite` as the bundler, your unit tests will be set up with `vitest`, unless you choose `none` for `unitTestRunner`.

###### Specify style extension

Create an application named `my-app` in the `my-dir` directory and use `scss` for styles:

```bash
nx g @nx/react:app apps/my-dir/my-app --style=scss
```

###### Add tags

Add tags to the application (used for linting).

```bash
nx g @nx/react:app apps/my-app --tags=scope:admin,type:ui
```

**Usage:**
```bash
nx generate @nx/react:application [options]
```

**Aliases:** `app`

**Arguments:**
```bash
nx generate @nx/react:application <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--bundler` | string | The bundler to use. | `"vite"` |
| `--classComponent` | boolean | Use class components instead of functional component. | `false` |
| `--compiler` | string | The compiler to use. | `"babel"` |
| `--e2eTestRunner` | string | Test runner to use for end to end (E2E) tests. | `"playwright"` |
| `--globalCss` | boolean | Default is `false`. When `true`, the component is generated with `*.css`/`*.scss` instead of `*.module.css`/`*.module.scss`. | `false` |
| `--inSourceTests` | boolean | When using Vitest, separate spec files will not be generated and instead will be included within the source files. Read more on the Vitest docs site: https://vitest.dev/guide/in-source.html | `false` |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"none"` |
| `--minimal` | boolean | Generate a React app with a minimal setup, no separate test files. | `false` |
| `--name` | string | The name of the application. |  |
| `--port` | number | The port to use for the development server | `4200` |
| `--rootProject` | boolean | Create a application at the root of the workspace | `false` |
| `--routing` | boolean | Generate application with routes. | `false` |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipNxJson` | boolean | Skip updating `nx.json` with default options based on values provided to this app. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--strict` | boolean | Creates an application with strict mode and strict type checking. | `true` |
| `--style` | string | The file extension to be used for style files. | `"css"` |
| `--tags` | string | Add tags to the application (used for linting). |  |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"none"` |
| `--useProjectJson` | boolean | Use a `project.json` configuration file instead of inlining the Nx configuration in the `package.json` file. |  |
| `--useReactRouter` | boolean | Use React Router for routing. | `false` |

## `component`
Create a React Component for Nx.

### Examples

###### Simple Component

Create a component named `MyComponent` at `libs/ui/src/my-component.tsx`:

```shell
nx g @nx/react:component libs/ui/src/my-component.tsx
```

###### With a Different Symbol Name

Create a component named `Custom` at `libs/ui/src/my-component.tsx`:

```shell
nx g @nx/react:component libs/ui/src/my-component.tsx --name=custom
```

###### Omitting the File Extension

Create a component named `MyComponent` at `libs/ui/src/my-component.tsx` without specifying the file extension:

```shell
nx g @nx/react:component libs/ui/src/my-component
```

###### Class Component

Create a class component named `MyComponent` at `libs/ui/src/my-component.tsx`:

```shell
nx g @nx/react:component libs/ui/src/my-component --classComponent
```

**Usage:**
```bash
nx generate @nx/react:component [options]
```

**Aliases:** `c`

**Arguments:**
```bash
nx generate @nx/react:component <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--classComponent` | boolean | Use class components instead of functional component. | `false` |
| `--export` | boolean | When true, the component is exported from the project `index.ts` (if it exists). | `false` |
| `--globalCss` | boolean | Default is `false`. When `true`, the component is generated with `*.css`/`*.scss` instead of `*.module.css`/`*.module.scss`. | `false` |
| `--inSourceTests` | boolean | When using Vitest, separate spec files will not be generated and instead will be included within the source files. Read more on the Vitest docs site: https://vitest.dev/guide/in-source.html | `false` |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. |  |
| `--name` | string | The component symbol name. Defaults to the last segment of the file path. |  |
| `--routing` | boolean | Generate a library with routes. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipTests` | boolean | When true, does not create `spec.ts` test files for the new component. | `false` |
| `--style` | string | The file extension to be used for style files. | `"css"` |

## `component-story`
Generate storybook story for a react component.

**Usage:**
```bash
nx generate @nx/react:component-story [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--componentPath` | string [**required**] | Relative path to the component file from the library root. |  |
| `--project` | string [**required**] | The project where to add the components. |  |
| `--interactionTests` | boolean | Set up Storybook interaction tests. | `true` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |

## `component-test`
Add a Cypress component test for a component.

### Examples

:::caution[Can I use component testing?]
React component testing with Nx requires **Cypress version 10** and up.

You can migrate with to v11 via the [migrate-to-cypress-11 generator](/nx-api/cypress/generators/migrate-to-cypress-11).

This generator is for Cypress based component testing.

If you're wanting to create Storybook stories for a component, then check out the [stories generator docs](/nx-api/react/generators/stories)
:::

This generator is used to create a Cypress component test file for a given React component.

```shell
nx g @nx/react:component-test --project=my-cool-react-project --componentPath=src/my-fancy-button.tsx
```

Test file are generated with the `.cy.` suffix. this is to prevent colliding with any existing `.spec.` files contained in the project.

It's currently expected the generated `.cy.` file will live side by side with the component. It is also assumed the project is already setup for component testing. If it isn't, then you can run the [cypress-component-project generator](/nx-api/react/generators/cypress-component-configuration) to set up the project for component testing.

**Usage:**
```bash
nx generate @nx/react:component-test [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--componentPath` | string [**required**] | Path to component, from the project source root |  |
| `--project` | string [**required**] | The name of the project the component is apart of |  |

## `cypress-component-configuration`
Add a Cypress component testing configuration to an existing project.

:::caution[Can I use component testing?]
React component testing with Nx requires **Cypress version 10.7.0** and up.

You can migrate with to v11 via the [migrate-to-cypress-11 generator](/nx-api/cypress/generators/migrate-to-cypress-11).

This generator is for Cypress based component testing.

If you want to test components via Storybook with Cypress, then check out the [storybook-configuration generator docs](/nx-api/react/generators/storybook-configuration). However, this functionality is deprecated, and will be removed on Nx version 19.
:::

This generator is designed to get your React project up and running with Cypress Component Testing.

```shell
nx g @nx/react:cypress-component-configuration --project=my-cool-react-project
```

Running this generator, adds the required files to the specified project with a preconfigured `cypress.config.ts` designed for Nx workspaces.

The following file will be added to projects where the Component Testing build target is using `webpack` for bundling:

```ts title="cypress.config.ts"
import { defineConfig } from 'cypress';
import { nxComponentTestingPreset } from '@nx/react/plugins/component-testing';

export default defineConfig({
  component: nxComponentTestingPreset(__filename, {
    bundler: 'webpack',
  }),
});
```

The following file will be added to projects where the Component Testing build target is using `vite` for bundling:

```ts title="cypress.config.ts"
import { defineConfig } from 'cypress';
import { nxComponentTestingPreset } from '@nx/react/plugins/component-testing';

export default defineConfig({
  component: nxComponentTestingPreset(__filename, {
    bundler: 'vite',
  }),
});
```

Here is an example on how to add custom options to the configuration

```ts title="cypress.config.ts"
import { defineConfig } from 'cypress';
import { nxComponentTestingPreset } from '@nx/react/plugins/component-testing';

export default defineConfig({
  component: {
    ...nxComponentTestingPreset(__filename, {
      bundler: 'webpack',
    }),
    // extra options here
  },
});
```

### The `bundler` option

Component testing supports two different bundlers: `webpack` and `vite`. The Nx generator will pick up the bundler used in the specified project's build target. If the build target is using `@nx/webpack:webpack`, then the generator will use `webpack` as the bundler. If the build target is using `@nx/vite:build`, then the generator will use `vite` as the bundler.

You can manually set the bundler by passing `--bundler=webpack` or `--bundler=vite` to the generator, but that is not needed since the generator will pick up the correct bundler for you. However, if you want to use a different bundler than the one that is used in the build target, then you can manually set it using that flag.

### Specifying a Build Target

Component testing requires a _build target_ to correctly run the component test dev server. This option can be manually specified with `--build-target=some-react-app:build`, but Nx will infer this usage from the [project graph](/concepts/mental-model#the-project-graph) if one isn't provided.

For React projects, the build target needs to be using the `@nx/webpack:webpack` executor.
The generator will throw an error if a build target can't be found and suggest passing one in manually.

Letting Nx infer the build target by default

```shell
nx g @nx/react:cypress-component-configuration --project=my-cool-react-project
```

Manually specifying the build target

```shell
nx g @nx/react:cypress-component-configuration --project=my-cool-react-project --build-target:some-react-app:build --generate-tests
```

:::note[Build Target with Configuration]
If you're wanting to use a build target with a specific configuration. i.e. `my-app:build:production`,
then manually providing `--build-target=my-app:build:production` is the best way to do that.
:::

### Auto Generating Tests

You can optionally use the `--generate-tests` flag to generate a test file for each component in your project.

```shell
nx g @nx/react:cypress-component-configuration --project=my-cool-react-project --generate-tests
```

### Running Component Tests

A new `component-test` target will be added to the specified project to run your component tests.

```shell
nx g component-test my-cool-react-project
```

Here is an example of the project configuration that is generated. The `--build-target` option is added as the `devServerTarget` which can be changed as needed.

```json title="project.json"
{
  "targets" {
    "component-test": {
      "executor": "@nx/cypress:cypress",
      "options": {
        "cypressConfig": "<path-to-project-root>/cypress.config.ts",
        "testingType": "component",
        "devServerTarget": "some-react-app:build",
        "skipServe": true
      }
    }
  }
}
```

Nx also supports [Angular component testing](/nx-api/angular/generators/cypress-component-configuration).

**Usage:**
```bash
nx generate @nx/react:cypress-component-configuration [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string [**required**] | The name of the project to add cypress component testing configuration to |  |
| `--buildTarget` | string | A build target used to configure Cypress component testing in the format of `project:target[:configuration]`. The build target should be from a React app. If not provided we will try to infer it from your projects usage. |  |
| `--bundler` | string | The bundler to use for Cypress Component Testing. |  |
| `--generateTests` | boolean | Generate default component tests for existing components in the project | `false` |
| `--skipFormat` | boolean | Skip formatting files | `false` |

## `federate-module`
Create a federated module, which can be loaded by a Consumer (host) via a Producer (remote).

**Usage:**
```bash
nx generate @nx/react:federate-module [options]
```

**Arguments:**
```bash
nx generate @nx/react:federate-module <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--name` | string [**required**] | The name of the module. |  |
| `--remote` | string [**required**] | The name of the Producer (remote). |  |
| `--bundler` | string | The bundler to use. | `"rspack"` |
| `--e2eTestRunner` | string | Test runner to use for end to end (E2E) tests. | `"cypress"` |
| `--host` | string | The Consumer (host) application for this Producer (remote). |  |
| `--linter` | string | The tool to use for running lint checks. | `"eslint"` |
| `--remoteDirectory` | string | The directory of the new Producer (remote) application if one needs to be created. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--style` | string | The file extension to be used for style files. | `"none"` |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"jest"` |

## `hook`
Create a React component using Hooks in a dedicated React project.

**Usage:**
```bash
nx generate @nx/react:hook [options]
```

**Aliases:** `c`

**Arguments:**
```bash
nx generate @nx/react:hook <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--export` | boolean | When true, the hook is exported from the project `index.ts` (if it exists). | `false` |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. |  |
| `--name` | string | The hook symbol name. Defaults to the last segment of the file path. |  |
| `--skipTests` | boolean | When true, does not create `spec.ts` test files for the new hook. | `false` |

## `host`
Create Module Federation configuration files for given React Consumer (Host) Application.

**Usage:**
```bash
nx generate @nx/react:host [options]
```

**Aliases:** `consumer`

**Arguments:**
```bash
nx generate @nx/react:host <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--bundler` | string | The bundler to use. | `"rspack"` |
| `--classComponent` | boolean | Use class components instead of functional component. | `false` |
| `--compiler` | string | The compiler to use | `"babel"` |
| `--devServerPort` | number | The port for the dev server of the Producer (remote) app. | `4200` |
| `--dynamic` | boolean | Should the Consumer (host) application use dynamic federation? | `false` |
| `--e2eTestRunner` | string | Test runner to use for end to end (E2E) tests. | `"playwright"` |
| `--globalCss` | boolean | Default is false. When true, the component is generated with *.css/*.scss instead of *.module.css/*.module.scss | `false` |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"eslint"` |
| `--minimal` | boolean | Generate a React app with a minimal setup. No nx starter template. | `false` |
| `--name` | string | The name of the Consumer (host) application to generate the Module Federation configuration |  |
| `--remotes` | array | A list of Producer (remote) application names that the Consumer (host) application should consume. | `[]` |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint "parserOptions.project" option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipNxJson` | boolean | Skip updating nx.json with default options based on values provided to this app (e.g. babel, style). | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--ssr` | boolean | Whether to configure SSR for the Consumer (host) application | `false` |
| `--strict` | boolean | Creates an application with strict mode and strict type checking | `true` |
| `--style` | string | The file extension to be used for style files. | `"css"` |
| `--tags` | string | Add tags to the application (used for linting). |  |
| `--typescriptConfiguration` | boolean | Whether the module federation configuration and webpack configuration files should use TS. When --js is used, this flag is ignored. | `true` |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"jest"` |

## `library`
Create a React Library for an Nx workspace.

**Usage:**
```bash
nx generate @nx/react:library [options]
```

**Aliases:** `lib`

**Arguments:**
```bash
nx generate @nx/react:library <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--appProject` | string | The application project to add the library route to. |  |
| `--buildable` | boolean | Generate a buildable library that uses rollup to bundle. | `false` |
| `--bundler` | string | The bundler to use. Choosing 'none' means this library is not buildable. | `"none"` |
| `--compiler` | string | Which compiler to use. | `"babel"` |
| `--component` | boolean | Generate a default component. | `true` |
| `--globalCss` | boolean | When `true`, the stylesheet is generated using global CSS instead of CSS modules (e.g. file is `*.css` rather than `*.module.css`). | `false` |
| `--importPath` | string | The library name used to import it, like `@myorg/my-awesome-lib`. |  |
| `--inSourceTests` | boolean | When using Vitest, separate spec files will not be generated and instead will be included within the source files. | `false` |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"none"` |
| `--minimal` | boolean | Create a React library with a minimal setup, no separate test files. | `false` |
| `--name` | string | Library name |  |
| `--publishable` | boolean | Create a publishable library. |  |
| `--routing` | boolean | Generate library with routes. |  |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--skipTsConfig` | boolean | Do not update `tsconfig.json` for development experience. | `false` |
| `--strict` | boolean | Whether to enable tsconfig strict mode or not. | `true` |
| `--style` | string | The file extension to be used for style files. | `"css"` |
| `--tags` | string | Add tags to the library (used for linting). |  |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"none"` |
| `--useProjectJson` | boolean | Use a `project.json` configuration file instead of inlining the Nx configuration in the `package.json` file. |  |

## `redux`
Create a Redux state slice for a React project.

**Usage:**
```bash
nx generate @nx/react:redux [options]
```

**Aliases:** `slice`

**Arguments:**
```bash
nx generate @nx/react:redux <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--appProject` | string | The application project to add the slice to. |  |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. |  |
| `--name` | string | The Redux state slice symbol name. Defaults to the last segment of the file path. |  |

## `remote`
Create Module Federation configuration files for given React Producer (Remote) Application.

**Usage:**
```bash
nx generate @nx/react:remote [options]
```

**Aliases:** `producer`

**Arguments:**
```bash
nx generate @nx/react:remote <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--bundler` | string | The bundler to use. | `"rspack"` |
| `--classComponent` | boolean | Use class components instead of functional component. | `false` |
| `--compiler` | string | The compiler to use. | `"babel"` |
| `--devServerPort` | number | The port for the dev server of the Producer (remote) app. |  |
| `--dynamic` | boolean | Should the Consumer (host) application use dynamic federation? | `false` |
| `--e2eTestRunner` | string | Test runner to use for end to end (E2E) tests. | `"playwright"` |
| `--globalCss` | boolean | Default is false. When true, the component is generated with *.css/*.scss instead of *.module.css/*.module.scss. | `false` |
| `--host` | string | The Consumer (host) application for this Producer (remote). |  |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"eslint"` |
| `--name` | string | The name of the Producer (remote) application to generate the Module Federation configuration |  |
| `--routing` | boolean | Generate application with routes. | `false` |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint "parserOptions.project" option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipNxJson` | boolean | Skip updating nx.json with default options based on values provided to this app (e.g. babel, style). | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--ssr` | boolean | Whether to configure SSR for the Consumer (host) application | `false` |
| `--strict` | boolean | Creates an application with strict mode and strict type checking. | `true` |
| `--style` | string | The file extension to be used for style files. | `"css"` |
| `--tags` | string | Add tags to the application (used for linting). |  |
| `--typescriptConfiguration` | boolean | Whether the module federation configuration and webpack configuration files should use TS. When --js is used, this flag is ignored. | `true` |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"jest"` |

## `setup-ssr`
Create the additional configuration required to enable SSR via Express for a React application.

**Usage:**
```bash
nx generate @nx/react:setup-ssr [options]
```

**Arguments:**
```bash
nx generate @nx/react:setup-ssr <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--appComponentImportPath` | string | The import path of the <App/ > component, relative to project sourceRoot. | `"app/app"` |
| `--bundler` | string | The bundler to use. | `"webpack"` |
| `--extraInclude` | array | Extra include entries in tsconfig. | `[]` |
| `--serverPort` | number | The port for the Express server. | `4200` |
| `--skipFormat` | boolean | Skip formatting the workspace after the generator completes. |  |

## `setup-tailwind`
Adds the Tailwind CSS configuration files for a given React project and installs, if needed, the packages required for Tailwind CSS to work.

**Usage:**
```bash
nx generate @nx/react:setup-tailwind [options]
```

**Arguments:**
```bash
nx generate @nx/react:setup-tailwind <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--buildTarget` | string | The name of the target used to build the project. This option is not needed in most cases. | `"build"` |
| `--skipFormat` | boolean | Skips formatting the workspace after the generator completes. |  |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |

## `stories`
Generate stories/specs for all components declared in a project.

This generator will generate stories for all your components in your project. The stories will be generated using [Component Story Format 3 (CSF3)](https://storybook.js.org/blog/storybook-csf3-is-here/).

```bash
nx g @nx/react:stories project-name
```

You can read more about how this generator works, in the [Storybook for React overview page](/recipes/storybook/overview-react#auto-generate-stories).

When running this generator, you will be prompted to provide the following:

- The `name` of the project you want to generate the configuration for.
- Whether you want to set up [Storybook interaction tests](https://storybook.js.org/docs/angular/writing-tests/interaction-testing) (`interactionTests`). If you choose `yes`, a `play` function will be added to your stories, and all the necessary dependencies will be installed. You can read more about this in the [Nx Storybook interaction tests documentation page](/recipes/storybook/storybook-interaction-tests#setup-storybook-interaction-tests)..

You must provide a `name` for the generator to work.

By default, this generator will also set up [Storybook interaction tests](https://storybook.js.org/docs/angular/writing-tests/interaction-testing). If you don't want to set up Storybook interaction tests, you can pass the `--interactionTests=false` option, but it's not recommended.

There are a number of other options available. Let's take a look at some examples.

### Examples

#### Ignore certain paths when generating stories

```bash
nx g @nx/react:stories --name=ui --ignorePaths=libs/ui/src/not-stories/**,**/**/src/**/*.other.*
```

This will generate stories for all the components in the `ui` project, except for the ones in the `libs/ui/src/not-stories` directory, and also for components that their file name is of the pattern `*.other.*`.

This is useful if you have a project that contains components that are not meant to be used in isolation, but rather as part of a larger component.

By default, Nx will ignore the following paths:

```text
*.stories.ts, *.stories.tsx, *.stories.js, *.stories.jsx, *.stories.mdx
```

but you can change this behaviour easily, as explained above.

#### Generate stories using JavaScript instead of TypeScript

```bash
nx g @nx/react:stories --name=ui --js=true
```

This will generate stories for all the components in the `ui` project using JavaScript instead of TypeScript. So, you will have `.stories.js` files next to your components.

**Usage:**
```bash
nx generate @nx/react:stories [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string [**required**] | Project for which to generate stories. |  |
| `--ignorePaths` | array | Paths to ignore when looking for components. | `["*.stories.ts,*.stories.tsx,*.stories.js,*.stories.jsx,*.stories.mdx"]` |
| `--interactionTests` | boolean | Set up Storybook interaction tests. | `true` |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |

## `storybook-configuration`
Set up Storybook for a React app or library.

This generator will set up Storybook for your **React** project. You can also use this generator to generate Storybook configuration for your **Next.js** project. By default, Storybook v10 is used.

```bash
nx g @nx/react:storybook-configuration project-name
```

You can read more about how this generator works, in the [Storybook for React overview page](/recipes/storybook/overview-react#generate-storybook-configuration-for-an-react-project).

When running this generator, you will be prompted to provide the following:

- The `name` of the project you want to generate the configuration for.
- Whether you want to set up [Storybook interaction tests](https://storybook.js.org/docs/react/writing-tests/interaction-testing) (`interactionTests`). If you choose `yes`, a `play` function will be added to your stories, and all the necessary dependencies will be installed. Also, a `test-storybook` target will be generated in your project's `project.json`, with a command to invoke the [Storybook `test-runner`](https://storybook.js.org/docs/react/writing-tests/test-runner). You can read more about this in the [Nx Storybook interaction tests documentation page](/recipes/storybook/storybook-interaction-tests#setup-storybook-interaction-tests)..
- Whether you want to `generateStories` for the components in your project. If you choose `yes`, a `.stories.ts` file will be generated next to each of your components in your project.

You must provide a `name` for the generator to work.

By default, this generator will also set up [Storybook interaction tests](https://storybook.js.org/docs/react/writing-tests/interaction-testing). If you don't want to set up Storybook interaction tests, you can pass the `--interactionTests=false` option, but it's not recommended.

There are a number of other options available. Let's take a look at some examples.

### Examples

#### Generate Storybook configuration

```bash
nx g @nx/react:storybook-configuration ui
```

This will generate Storybook configuration for the `ui` project using TypeScript for the Storybook configuration files (the files inside the `.storybook` directory, eg. `.storybook/main.ts`).

#### Ignore certain paths when generating stories

```bash
nx g @nx/react:storybook-configuration ui --generateStories=true --ignorePaths=libs/ui/src/not-stories/**,**/**/src/**/*.other.*,apps/my-app/**/*.something.ts
```

This will generate a Storybook configuration for the `ui` project and generate stories for all components in the `libs/ui/src/lib` directory, except for the ones in the `libs/ui/src/not-stories` directory, and the ones in the `apps/my-app` directory that end with `.something.ts`, and also for components that their file name is of the pattern `*.other.*`.

This is useful if you have a project that contains components that are not meant to be used in isolation, but rather as part of a larger component.

By default, Nx will ignore the following paths:

```text
*.stories.ts, *.stories.tsx, *.stories.js, *.stories.jsx, *.stories.mdx
```

but you can change this behaviour easily, as explained above.

#### Generate stories using JavaScript instead of TypeScript

```bash
nx g @nx/react:storybook-configuration ui --generateStories=true --js=true
```

This will generate stories for all the components in the `ui` project using JavaScript instead of TypeScript. So, you will have `.stories.js` files next to your components.

#### Generate Storybook configuration using JavaScript

```bash
nx g @nx/react:storybook-configuration ui --tsConfiguration=false
```

By default, our generator generates TypeScript Storybook configuration files. You can choose to use JavaScript for the Storybook configuration files of your project (the files inside the `.storybook` directory, eg. `.storybook/main.js`).

**Usage:**
```bash
nx generate @nx/react:storybook-configuration [options]
```

**Arguments:**
```bash
nx generate @nx/react:storybook-configuration <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--configureStaticServe` | boolean | Specifies whether to configure a static file server target for serving storybook. Helpful for speeding up CI build/test times. | `true` |
| `--generateStories` | boolean | Automatically generate `*.stories.ts` files for components declared in this project? | `true` |
| `--ignorePaths` | array | Paths to ignore when looking for components. | `["*.stories.ts,*.stories.tsx,*.stories.js,*.stories.jsx,*.stories.mdx"]` |
| `--interactionTests` | boolean | Set up Storybook interaction tests. | `true` |
| `--js` | boolean | Generate JavaScript story files rather than TypeScript story files. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"eslint"` |
| `--tsConfiguration` | boolean | Configure your project with TypeScript. Generate main.ts and preview.ts files, instead of main.js and preview.js. | `true` |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/react:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/react/guides.md -->
## Guides

{% index_page_cards path="technologies/react/guides" /%}

---
<!-- source: https://nx.dev/docs/technologies/react/guides/adding-assets-react.md -->
## Adding Images, Fonts, and Files

With Nx, you can **`import` assets directly from your TypeScript/JavaScript code**.

```typescript frame="none"
import React from 'react';
import logo from './logo.png';

const Header = () => <img src={logo} alt="Logo" />;

export default Header;
```

This import will be replaced by a string of the image path when the application builds. To reduce the number of network requests, if the image file size is less than 10 kB, then the image will be inlined using [data URI](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs) instead of a path.

This works in CSS files as well.

```css frame="none"
.logo {
  background-image: url(./logo.png);
}
```

## Adding SVGs

SVG images can be imported using the method described previously.

Alternatively, you can import SVG images as React components using [SVGR](https://react-svgr.com/).

```typescript frame="none"
import React from 'react';
import { ReactComponent as Logo } from './logo.svg';

const Header = () => <Logo title="Logo" />;

export default Header;
```

This method of import allow you to work with the SVG the same way you would with any other React component. You can style it using CSS, [styled-components](https://styled-components.com/), [TailwindCSS](https://tailwindcss.com/), etc. The SVG component accepts a `title` prop, as well as any other props that the `svg` element accepts.

{% aside type="caution" title="Manual Configuration Required" %}
As of Nx 22, SVGR is removed for Webpack and Next.js, and deprecated for Rspack (will be removed in Nx 23). Manual configuration is required—see the sections below.
{% /aside %}

### SVGR for Webpack and Rspack

To import SVGs as React components with Webpack or Rspack, you need to install the `@svgr/webpack` package and configure it manually. For detailed configuration options, refer to the [official SVGR webpack documentation](https://react-svgr.com/docs/webpack/).

First, install the required dependencies:

{% tabs %}
{% tabitem label="npm" %}

```shell
npm add -D @svgr/webpack file-loader
```

{% /tabitem %}
{% tabitem label="yarn" %}

```shell
yarn add -D @svgr/webpack file-loader
```

{% /tabitem %}
{% tabitem label="pnpm" %}

```shell
pnpm add -D @svgr/webpack file-loader
```

{% /tabitem %}

{% tabitem label="bun" %}

```shell
bun add -D @svgr/webpack file-loader
```

{% /tabitem %}
{% /tabs %}

Then, configure your webpack config:

```javascript frame="none"
// filename: webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.svg$/,
        issuer: /\.(js|ts|md)x?$/,
        use: [
          {
            loader: '@svgr/webpack',
            options: {
              svgo: false,
              titleProp: true,
              ref: true,
            },
          },
          'file-loader',
        ],
      },
    ],
  },
};
```

If you're using `composePlugins` with `withNx`, you can create a `withSvgr` helper function:

```javascript frame="none"
// filename: webpack.config.js
const { composePlugins, withNx } = require('@nx/webpack');

function withSvgr(svgrOptions = {}) {
  const defaultOptions = {
    svgo: false,
    titleProp: true,
    ref: true,
  };

  const options = { ...defaultOptions, ...svgrOptions };

  return function configure(config) {
    // Remove existing SVG loader if present
    const svgLoaderIdx = config.module.rules.findIndex(
      (rule) =>
        typeof rule === 'object' &&
        typeof rule.test !== 'undefined' &&
        rule.test.toString().includes('svg')
    );

    if (svgLoaderIdx !== -1) {
      config.module.rules.splice(svgLoaderIdx, 1);
    }

    // Add SVGR loader
    config.module.rules.push({
      test: /\.svg$/,
      issuer: /\.(js|ts|md)x?$/,
      use: [
        {
          loader: require.resolve('@svgr/webpack'),
          options,
        },
        {
          loader: require.resolve('file-loader'),
          options: {
            name: '[name].[hash].[ext]',
          },
        },
      ],
    });

    return config;
  };
}

module.exports = composePlugins(withNx(), withSvgr());
```

### SVGR for Next.js

As of Nx 22, SVGR support for Next.js is no longer included by default. You can configure it manually using the same approach as Webpack. For detailed information, refer to the [official SVGR documentation](https://react-svgr.com/docs/webpack/).

First, install the required dependencies:

{% tabs %}
{% tabitem label="npm" %}

```shell
npm add -D @svgr/webpack file-loader
```

{% /tabitem %}
{% tabitem label="yarn" %}

```shell
yarn add -D @svgr/webpack file-loader
```

{% /tabitem %}
{% tabitem label="pnpm" %}

```shell
pnpm add -D @svgr/webpack file-loader
```

{% /tabitem %}

{% tabitem label="bun" %}

```shell
bun add -D @svgr/webpack file-loader
```

{% /tabitem %}
{% /tabs %}

Then, update your `next.config.js`:

```javascript frame="none"
// filename: next.config.js
module.exports = {
  webpack(config) {
    // Grab the existing rule that handles SVG imports
    const fileLoaderRule = config.module.rules.find((rule) =>
      rule.test?.test?.('.svg')
    );

    config.module.rules.push(
      // Reapply the existing rule, but only for svg imports ending in ?url
      {
        ...fileLoaderRule,
        test: /\.svg$/i,
        resourceQuery: /url/, // *.svg?url
      },
      // Convert all other *.svg imports to React components
      {
        test: /\.svg$/i,
        issuer: fileLoaderRule.issuer,
        resourceQuery: { not: [...fileLoaderRule.resourceQuery.not, /url/] }, // exclude if *.svg?url
        use: ['@svgr/webpack'],
      }
    );

    // Modify the file loader rule to ignore *.svg, since we have it handled now.
    fileLoaderRule.exclude = /\.svg$/i;

    return config;
  },

  // ...other config
};
```

If you're using `composePlugins` with `withNx`, you can update your `next.config.js` to use a `withSvgr` helper function:

```javascript frame="none"
// filename: next.config.js
const { composePlugins, withNx } = require('@nx/next');

function withSvgr(svgrOptions = {}) {
  const defaultOptions = {
    svgo: false,
    titleProp: true,
    ref: true,
  };

  const options = { ...defaultOptions, ...svgrOptions };

  return function configure(config) {
    // Remove existing SVG loader if present
    const svgLoaderIdx = config.module.rules.findIndex(
      (rule) =>
        typeof rule === 'object' &&
        typeof rule.test !== 'undefined' &&
        rule.test.toString().includes('svg')
    );

    if (svgLoaderIdx !== -1) {
      config.module.rules.splice(svgLoaderIdx, 1);
    }

    // Add SVGR loader
    config.module.rules.push({
      test: /\.svg$/,
      issuer: /\.(js|ts|md)x?$/,
      use: [
        {
          loader: require.resolve('@svgr/webpack'),
          options,
        },
        {
          loader: require.resolve('file-loader'),
          options: {
            name: '[name].[hash].[ext]',
          },
        },
      ],
    });

    return config;
  };
}

const nextConfig = {
  // your Next.js config here
};

module.exports = composePlugins(withNx(), withSvgr())(nextConfig);
```

### SVGR for Vite

To import SVGs as React components with Vite, you need to install the `vite-plugin-svgr` package.

{% tabs %}
{% tabitem label="npm" %}

```shell
npm add -D vite-plugin-svgr
```

{% /tabitem %}
{% tabitem label="yarn" %}

```shell
yarn add -D vite-plugin-svgr
```

{% /tabitem %}
{% tabitem label="pnpm" %}

```shell
pnpm add -D vite-plugin-svgr
```

{% /tabitem %}

{% tabitem label="bun" %}

```shell
bun add -D vite-plugin-svgr
```

{% /tabitem %}
{% /tabs %}

Then, configure Vite as follows:

```javascript frame="none" meta="{ranges: '5,10-18'}"
// filename: vite.config.ts
/// <reference types='vitest' />
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
import svgr from 'vite-plugin-svgr';

export default defineConfig({
  // ...
  plugins: [
    svgr({
      svgrOptions: {
        exportType: 'named',
        ref: true,
        svgo: false,
        titleProp: true,
      },
      include: '**/*.svg',
    }),
    react(),
    nxViteTsPaths(),
    // ...
  ],
  //...
});
```

---
<!-- source: https://nx.dev/docs/technologies/react/guides/deploy-nextjs-to-vercel.md -->
## Deploying Next.js Applications to Vercel

Your Next.js application should already be ready for deployment to Vercel.

## Configure your Vercel project's settings appropriately

### New Vercel project

1. If you are "importing" your Nx workspace's repository for the first time, make sure you do _not_ choose a root directory as part of the repo selection process (therefore leaving it to be the root of the full repo/workspace)
2. Ensure the Next.js "Framework Preset" is selected
3. Expand the "Build and Output Settings" and toggle the override switch for the build command. For example, for an application named `tuskdesk` the value will look like this:

```shell
npx nx build tuskdesk --prod
```

4. Toggle the override switch for the output directory. Point it to the `.next` directory inside the built app:

```text {% frame="none" %}
apps/tuskdesk/.next
```

Therefore, our full configuration (based on a repo called "nx-workspace" and a project called "tuskdesk") will look like this:

![New Vercel Project](../../../../../assets/guides/next/next-deploy-vercel-1.png)

### Existing Vercel project

If you have an existing project on Vercel then the exact same guidance applies as for the section above, it's just that you will need to update the project's existing settings.

When everything is updated appropriately, for our `tuskdesk` example we would see the following in our "General" settings UI:

![Existing Vercel Project](../../../../../assets/guides/next/next-deploy-vercel-2.png)

## Skipping build if the application is not affected

One of the core features of Nx is to run code quality checks and builds only for projects that are affected by recent code changes. We can use [Vercel's ignored build step feature](https://vercel.com/docs/platform/projects#ignored-build-step) to only build our application if it is affected.

To build only what's affected, use the `npx nx-ignore <app-name>` command under `Project Settings > Git` on Vercel.

![Ignore build step](../../../../../assets/guides/next/next-deploy-vercel-3-2.png)

The `nx-ignore` command uses Nx to detect whether the current commit affects the specified app, and will skip the build if it is not affected.

## Next steps

You can continue to set any additional environment variables that may be appropriate for your projects.

---
<!-- source: https://nx.dev/docs/technologies/react/guides/module-federation-with-ssr.md -->
## Module Federation with Server-Side Rendering

Walk you through creating a Module Federated setup with Server Side Rendering (SSR) for Angular and React using Nx and its generators.

## Steps

### Create an empty workspace

Run the following command with the options listed to create an empty workspace.

```shell frame="terminal" title="npx create-nx-workspace@latest myorg --preset=apps"
// filename: ~

NX   Let's create a new workspace [https://nx.dev/getting-started/intro]

✔ Which CI provider would you like to use? · skip
✔ Would you like remote caching to make your build faster? · skip
```

{% card title="Opting into Nx Cloud" description="You will also be prompted whether to add Nx Cloud to your workspace. We won't address this in this recipe, but you can see the introduction to Nx Cloud for more details." url="/docs/guides/nx-cloud/setup-ci" /%}

### Install your framework plugin

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/angular` or `@nx/react` versions that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
{% /aside %}

{% tabs %}

{% tabitem label="Angular" %}

```shell frame="terminal" title="nx add @nx/angular"
// filename: ~/myorg

```

{% /tabitem %}

{% tabitem label="React" %}

```shell frame="terminal" title="nx add @nx/react"
// filename: ~/myorg

```

{% /tabitem %}

{% /tabs %}

### Generating a host and multiple remotes with SSR

We will generate the apps required for a storefront application.  
We will need the following applications:

- Store - _host application_
- Product - _remote application_
- Checkout - _remote application_

Nx allows you to do this with a single command:

{% tabs %}

{% tabitem label="Angular" %}

```shell frame="terminal" title="npx nx g @nx/angular:host apps/store --ssr --remotes=product,checkout"
// filename: ~/myorg

```

{% /tabitem %}

{% tabitem label="React" %}

```shell frame="terminal" title="npx nx g @nx/react:host apps/store --ssr --remotes=product,checkout"
// filename: ~/myorg

```

{% /tabitem %}

{% /tabs %}

This will generate three applications, set up with SSR and Module Federation.

### Serving the store application

When using Module Federation, we want to serve the host application along with the remote applications so that everything works as expected.

To do this, run:

{% tabs %}

{% tabitem label="Angular" %}

```shell frame="terminal" title="npx nx serve-ssr store"
// filename: ~/myorg

```

{% /tabitem %}

{% tabitem label="React" %}

```shell frame="terminal" title="npx nx serve store"
// filename: ~/myorg

```

{% /tabitem %}

{% /tabs %}

This will run all three application servers but only the `store` will be watching for file changes. If you make a change to one of the remote applications (`checkout` or `product`) the changes will not be hot reloaded.

### Serving the store application with file watching for checkout

If working on a remote application, we can still serve it via the host application and have it watch for changes.

To serve the `store` application and watch for changes on the `checkout` application run:

{% tabs %}

{% tabitem label="Angular" %}

```shell frame="terminal" title="npx nx serve-ssr store --devRemotes=checkout"
// filename: ~/myorg

```

{% /tabitem %}

{% tabitem label="React" %}

```shell frame="terminal" title="npx nx serve store --devRemotes=checkout"
// filename: ~/myorg

```

{% /tabitem %}

{% /tabs %}

### Additional resources

To learn more about Module Federation, we have some resources you might find useful:

- [Concepts: Nx Module Federation Technical Overview](/docs/technologies/module-federation/concepts/nx-module-federation-technical-overview)
- [Guide: Faster Builds with Module Federation](/docs/technologies/module-federation/concepts/faster-builds-with-module-federation)
- [Video: Speed up your Angular serve and build times with Module Federation and Nx](https://www.youtube.com/watch?v=JkcaGzhRjkc)

---
<!-- source: https://nx.dev/docs/technologies/react/guides/react-compiler.md -->
## React Compiler with Nx

React 19 comes with an experimental compiler that optimizes application code to automatically memoize code. Read the [official React Compiler documentation](https://react.dev/learn/react-compiler) for more information.

## Enabling React compiler in Nx projects

For Nx projects using Babel and the `@nx/react/babel` preset, install the `babel-plugin-react-compiler` package and enable it with the `reactCompiler` option.

```json frame="none" meta="{ranges: '7'}"
{
  "presets": [
    [
      "@nx/react/babel",
      {
        "runtime": "automatic",
        "reactCompiler": true
      }
    ]
  ],
  "plugins": []
}
```

You can also pass an object to set compiler options.

```json frame="none" meta="{ranges: '7-9'}"
{
  "presets": [
    [
      "@nx/react/babel",
      {
        "runtime": "automatic",
        "reactCompiler": {
          "compilationMode": "annotation"
        }
      }
    ]
  ],
  "plugins": []
}
```

Check the [React Compiler usage docs](https://react.dev/learn/react-compiler#installation) for all support setups, such as Vite, Remix, etc.

---
<!-- source: https://nx.dev/docs/technologies/react/guides/react-router.md -->
## React Router with Nx

React Router is the successor of Remix and is the recommended routing library for new projects that may require Server-Side Routing (SSR).

There are three modes when using React Router: `framework`, `declarative` and `data`. `Framework` mode is the most comprehensive and is what will be covered in this recipe.

We'll show you how to create a [React Router](https://reactrouter.com/home) application with Nx.

## Create Nx workspace

```text {% frame="terminal" title="npx create-nx-workspace@latest acme" %}

✔ Which stack do you want to use? · react
✔ What framework would you like to use? · none
✔ Application name · acme
✔ Would you like to use React Router for server-side rendering [https://reactrouter.com/]? · Yes
```

## Have an existing app?

If you already have an existing React Router application and want to add Nx to it you can do so by running the following command:

```shell
npx nx@latest init
```

## Generate a React router application

If you would like to generate a new React Router application, you can do so by running the following command in your Nx workspace

```shell
nx g @nx/react:app apps/happynrwl --routing --use-react-router
```

There is no need to install any additional plugins to use React Router with Nx. The `@nx/react` plugin already includes support for React Router.

## Running the application

Now that you have created your React Router application with Nx you can build, serve and test with the following commands:

### Build

To build your application run the following command:

```text {% frame="terminal" title="nx build happynrwl" %}

> nx run acme:happynrwl

> react-router build

vite v6.2.1 building for production...
✓ 45 modules transformed.
build/client/.vite/manifest.json                  1.40 kB │ gzip:  0.32 kB
build/client/assets/about-D7ArdXr1.js             0.20 kB │ gzip:  0.18 kB
build/client/assets/with-props-CQyfqcsx.js        0.22 kB │ gzip:  0.19 kB
build/client/assets/root-BKqDrCrU.js              0.99 kB │ gzip:  0.54 kB
build/client/assets/app-DnLbn-a2.js              24.50 kB │ gzip:  6.26 kB
build/client/assets/chunk-K6CSEXPM-DXuCqE6i.js  111.05 kB │ gzip: 37.47 kB
build/client/assets/entry.client-CkXnIIWp.js    179.95 kB │ gzip: 56.93 kB
✓ built in 576ms
vite v6.2.1 building SSR bundle for production...
✓ 9 modules transformed.
build/server/.vite/manifest.json   0.17 kB
build/server/index.js             43.12 kB
✓ built in 35ms



 NX   Successfully ran target build for project happynrwl (1s)
```

### Serve (Development)

To serve your application for development use the following command:

```text {% frame="terminal" title="nx dev happynrwl" %}
> nx run happynrwl:dev

> react-router dev

1:30:42 p.m. [vite] (client) Re-optimizing dependencies because lockfile has changed
  ➜  Local:   http://localhost:4200/
  ➜  press h + enter to show help
```

### Serve (Production)

To serve your application's production build use the following command:

```text {% frame="terminal" title="nx start happynrwl" %}
> nx run happynrwl:build

> react-router build

vite v6.2.1 building for production...
✓ 45 modules transformed.
build/client/.vite/manifest.json                  1.40 kB │ gzip:  0.32 kB
build/client/assets/about-D7ArdXr1.js             0.20 kB │ gzip:  0.18 kB
build/client/assets/with-props-CQyfqcsx.js        0.22 kB │ gzip:  0.19 kB
build/client/assets/root-BKqDrCrU.js              0.99 kB │ gzip:  0.54 kB
build/client/assets/app-DnLbn-a2.js              24.50 kB │ gzip:  6.26 kB
build/client/assets/chunk-K6CSEXPM-DXuCqE6i.js  111.05 kB │ gzip: 37.47 kB
build/client/assets/entry.client-CkXnIIWp.js    179.95 kB │ gzip: 56.93 kB
✓ built in 576ms
vite v6.2.1 building SSR bundle for production...
✓ 9 modules transformed.
build/server/.vite/manifest.json   0.17 kB
build/server/index.js             43.12 kB
✓ built in 35ms

> nx run happynrwl:start

> react-router-serve build/server/index.js

[react-router-serve] http://localhost:3000 (http://192.168.0.112:3000)
```

{% aside type="note" title="PORT" %}
The default port for `production` is 3000 if you want to change it use the PORT environment variable
{% /aside %}

### Unit test

To unit test the application run the following command:

```text {% frame="terminal" title="nx test happynrwl" %}
// filename: ~/acme
> nx run happynrwl:test

> vitest


 RUN  v3.0.8 /private/tmp/projects/acme/apps/happynrwl

 ✓ tests/routes/_index.spec.tsx (1 test) 45ms
   ✓ renders loader data

 Test Files  1 passed (1)
      Tests  1 passed (1)
   Start at  13:40:29
   Duration  807ms (transform 59ms, setup 0ms, collect 168ms, tests 45ms, environment 372ms, prepare 52ms)
```

## Generate a route

By default a route is generated for you when you create a new React Router application. If you would like to generate a new route you can do so by running the following command:

```shell {% frame="terminal" title="nx g @nx/react:component --path=apps/happynrwl/app/routes/contact" %}
CREATE apps/happynrwl/app/routes/contact.tsx
CREATE apps/happynrwl/app/routes/contact.module.scss
CREATE apps/happynrwl/app/routes/contact.spec.tsx
```

Now we have create a new route called `contact` in our application. Let's add that route to our `routes.tsx` file.

```tsx
// routes.tsx
import { type RouteConfig, index, route } from "@react-router/dev/routes";

export default [
  index('./app.tsx'),
  route('about', './routes/about.tsx')
  route('contact', './routes/contact.tsx')
  ] satisfies RouteConfig;
```

Now if we serve or app and navigate to `https://localhost:4200/contact` we will see our new route.

## GitHub repository with example

You can find an example of an Nx Workspace using React Router by clicking below

{% github_repository url="https://github.com/nrwl/nx-recipes/tree/main/react-router" /%}

---
<!-- source: https://nx.dev/docs/technologies/react/guides/use-environment-variables-in-react.md -->
## Using Environment Variables in React Applications

## For React applications using Vite

In React applications using Vite (e.g. those using `@nx/vite:*` executors), Nx includes the following variables in the build process:

- `NODE_ENV`
- Variables prefixed with `VITE_`, such as `VITE_CUSTOM_VAR`

For more details, see the [Vite environment variables documentation](https://vite.dev/guide/env-and-mode.html).

You can then use these variables in your application code like so: `import.meta.env.VITE_CUSTOM_VAR`.

### Environment variable conflict between Nx and Vite

When using Nx with Vite, you may encounter an issue related to loading environment variables that can lead to unexpected behavior. This issue arises due to the way Nx and Vite handle environment files and configuration settings.

1. **Nx Environment Variable Loading**: Nx loads environment variables from configuration names using the `--configuration` flag. This is the preferred method in Nx, especially when you have a default configuration specified in your `project.json` file for most targets. In our [guide on how to define environment variables](/docs/guides/tips-n-tricks/define-environment-variables), you can see that if you're using the `configuration` option, then Nx will load `.env.[configuration-name]` files.

2. **Vite Environment Variable Loading**: Vite loads environment files named `.env.[mode]` using the `--mode` flag.

The conflict occurs when you use the `--configuration` flag in Nx. In such cases, the `--mode` flag in Vite is ignored. For example, this behavior can be particularly confusing, as it may seem like you are always loading the `development` mode in Vite, instead of the expected one, if you're using the `--configuration=development` setting or if your default configuration is `development`.

The root cause of this issue is that Nx has already loaded variables from `.env.[configuration]`. So any variables defined in both Nx and Vite `.env.[mode]` files will have their values overridden by the Nx-loaded values.

#### Solution

Adapt to the Nx way of handling environment variables by following the [guide on defining environment variables](/docs/guides/tips-n-tricks/define-environment-variables). This ensures consistent behavior and prevents conflicts when using Nx with Vite.

However, if you still want to use Vite `mode`, you can. To avoid conflicts between Nx and Vite environment variables, establish a clear distinction between `configuration` and `mode` names. By assigning distinct names to both `configuration` and `mode`, you can eliminate any potential conflicts that may arise during environment variable loading. Additionally, consider defining custom configurations in your Nx workspace, each with a corresponding `mode` option. For example, you can create configurations like `development`, `production`, and `staging`, each with its respective `mode` set, like this:

```json frame="none"
"configurations": {
  "development": {
    "mode": "development"
  },
  "production": {
    "mode": "production"
  },
  "staging": {
    "mode": "staging"
  },
  "my-other-mode": {
    "mode": "my-other-mode"
  }
}
```

That way, you can set the `--configuration` flag to `development`, `production`, or `staging` to load the corresponding `.env.[configuration]` file, and this will respect the `mode` set in the configuration.

### Using environment variables in `index.html`

You cannot interpolate environment variables into your `index.html` file for React applications using Vite.

## For non-Vite React applications

In React applications (e.g. those using the `@nx/web:webpack` executor or an [inferred task](/docs/concepts/inferred-tasks) that runs the Webpack CLI for building), Nx
includes the following variables in the build process:

- `NODE_ENV`
- Variables prefixed with `NX_PUBLIC`, such as `NX_PUBLIC_CUSTOM_VAR` (when using the [NxAppWebpackPlugin](/docs/technologies/build-tools/webpack/guides/webpack-plugins#nxappwebpackplugin) or the [withNx](/docs/technologies/build-tools/webpack/guides/webpack-plugins#withnx) plugins)

Defining environment variables can vary between OSes. This is temporary for the life of the shell session.

### Using environment variables in `index.html`

Nx supports interpolating environment variables into your `index.html` file for React and Web applications built with Webpack.
This feature is available when using the [NxAppWebpackPlugin](/docs/technologies/build-tools/webpack/guides/webpack-plugins#nxappwebpackplugin) or the [withNx](/docs/technologies/build-tools/webpack/guides/webpack-plugins#withnx) plugins.

{% aside type="note" title="Predefined Nx variables" %}
You can't use [predefined Nx environment variables](/docs/reference/environment-variables) in `index.html` interpolation.
{% /aside %}

To interpolate an environment variable named `NX_PUBLIC_DOMAIN_NAME` into your `index.html`, surround it with `%` symbols like so:

```html frame="none"
// filename: index.html
<html>
  <body>
    <p>The domain name is %NX_PUBLIC_DOMAIN_NAME%.</p>
  </body>
</html>
```

---
<!-- source: https://nx.dev/docs/technologies/react/guides/using-tailwind-css-in-react.md -->
## Using Tailwind CSS with React

This guide shows how to set up [Tailwind CSS](https://tailwindcss.com) in your React applications within an Nx workspace.

## Installation

For the most up-to-date installation instructions, refer to the official Tailwind CSS documentation:

- **Vite projects**: [Tailwind CSS with Vite](https://tailwindcss.com/docs/installation/using-vite)
- **Next.js projects**: [Tailwind CSS with Next.js](https://tailwindcss.com/docs/installation/framework-guides/nextjs)
- **Other setups**: [Tailwind CSS installation guide](https://tailwindcss.com/docs/installation)

## Configuring sources for monorepos

### Tailwind CSS v4

Tailwind CSS v4 [automatically detects classes from source files](https://tailwindcss.com/docs/detecting-classes-in-source-files). However, with the Vite plugin, scanning only covers the app directory. This means classes from workspace libraries won't be included unless you explicitly add them.

Use `@source` directives to include your library dependencies:

```css
// apps/myapp/src/styles.css
@import 'tailwindcss';

@source "../../../libs/ui";
@source "../../../libs/shared";
```

#### Automating @source directives

Manually maintaining `@source` directives is tedious and error-prone. Use [`@juristr/nx-tailwind-sync`](https://www.npmjs.com/package/@juristr/nx-tailwind-sync) to automate this based on your project's dependency graph.

Install the package:

```shell
npm install @juristr/nx-tailwind-sync
```

Register the sync generator for your application's `build` and `dev` targets:

{% tabs syncKey="project-config-file" %}
{% tabitem label="package.json" %}

```json
{
  "name": "myapp",
  "nx": {
    "targets": {
      "build": {
        "syncGenerators": ["@juristr/nx-tailwind-sync:source-directives"]
      },
      "dev": {
        "syncGenerators": ["@juristr/nx-tailwind-sync:source-directives"]
      }
    }
  }
}
```

{% /tabitem %}
{% tabitem label="project.json" %}

```json
{
  "name": "myapp",
  "targets": {
    "build": {
      "syncGenerators": ["@juristr/nx-tailwind-sync:source-directives"]
    },
    "dev": {
      "syncGenerators": ["@juristr/nx-tailwind-sync:source-directives"]
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

When you run `nx build myapp` or `nx dev myapp`, the sync generator analyzes your dependency graph and updates your stylesheet with the correct `@source` directives automatically.

For more details on why this is necessary and how to build your own sync generator, see [Tailwind v4 with Vite in an NPM Workspace](/blog/setup-tailwind-4-npm-workspace).

### Tailwind CSS v3

For Tailwind CSS v3, the [`content`](https://v3.tailwindcss.com/docs/content-configuration) property should be configured to include glob patterns that cover your project and its dependencies:

```javascript
// apps/my-app/tailwind.config.js
const { join } = require('path');

module.exports = {
  content: [
    join(__dirname, '{src,pages,components,app}/**/*.{ts,tsx,js,jsx}'),
    join(__dirname, '../../libs/**/*.{ts,tsx,js,jsx}'),
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};
```

You can adjust the glob patterns based on your workspace structure. For example, you can be more selective by targeting individual libraries such as `libs/my-lib` rather than all libraries (`libs`). To learn how to automatically sync library dependencies with Tailwind sources, watch our video [Never Update Tailwind Glob Patterns Manually Again](https://www.youtube.com/watch?v=huTmV-F8c0A).

---
<!-- source: https://nx.dev/docs/technologies/react/introduction.md -->
## React Plugin for Nx

The React plugin for Nx, `@nx/react`, provides generators for [applications and libraries](#generate-react-applications-and-libraries), executors for [Module Federation](/docs/technologies/react/guides/module-federation-with-ssr), and [library build support](/docs/concepts/buildable-and-publishable-libraries). It integrates with popular bundlers and test runners so you can configure each project to match your team's toolchain.

You don't need the plugin to use React with Nx. Any project already benefits from [caching](/docs/features/cache-task-results), [task orchestration](/docs/features/run-tasks), and the [project graph](/docs/features/explore-graph). The plugin simplifies scaffolding and code generation.

## Requirements

The `@nx/react` plugin supports the following package versions.

| Package | Supported Versions   |
| ------- | -------------------- |
| `react` | ^18.0.0 \|\| ^19.0.0 |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

{% aside type="tip" title="Using a React Meta-Framework?" %}
If you're building with **Next.js** or **Remix**, use their dedicated plugins which include inferred task support. See the [Next.js plugin](/docs/technologies/react/next/introduction) or [Remix plugin](/docs/technologies/react/remix/introduction) hub pages. For **React Router** in framework mode, see the [React Router guide](/docs/technologies/react/guides/react-router).
{% /aside %}

## Setting up @nx/react

### Add to an existing Nx workspace

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/react` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
Using `nx add` helps ensure the correct version is installed and configured.
{% /aside %}

```shell
nx add @nx/react
```

### Verification

{% steps %}

1. Check that `@nx/react` is listed:

   ```shell
   nx report
   ```

2. Verify generators are available:

   ```shell
   nx list @nx/react
   ```

{% /steps %}

### Create a new workspace

```shell
npx create-nx-workspace@latest --template=nrwl/react-template
```

{% aside type="tip" title="Tutorial" %}
For a guided walkthrough, follow the [Learn Nx Tutorial](/docs/getting-started/tutorials/crafting-your-workspace).
{% /aside %}

### Generate a new application

```shell
nx g @nx/react:app apps/my-app
```

To start the application in development mode, run `nx serve my-app`. Read more about the options available for the [application generator](/docs/technologies/react/generators#application).

#### Choose a Bundler

The `--bundler` option selects the build tool for your application or buildable library. You can learn more about the specific bundler you scaffolded your project with on the bundler's plugin page:

- [Vite](/docs/technologies/build-tools/vite/introduction) (Recommended)
- [Webpack](/docs/technologies/build-tools/webpack/introduction)
- [Rspack](/docs/technologies/build-tools/rspack/introduction)
- [Rollup](/docs/technologies/build-tools/rollup/introduction)

### Generate a new library

```shell
nx g @nx/react:lib libs/my-lib

# With a bundler for buildable/publishable libraries
nx g @nx/react:lib libs/my-lib --bundler=vite
nx g @nx/react:lib libs/my-lib --bundler=rollup
nx g @nx/react:lib libs/my-lib --publishable --importPath=@myorg/my-lib
```

The same [bundler options](#choose-a-bundler) apply when creating buildable libraries. Read more about the options available for the [library generator](/docs/technologies/react/generators#library).
You can also read more about [buildable and publishable libraries](/docs/concepts/buildable-and-publishable-libraries).

### Serve applications

```shell
nx serve my-app
```

This starts the development server with hot module replacement so you can iterate on your application locally.

### Build projects

```shell
nx build my-app
nx build my-lib
```

Build output goes to the `dist` folder by default. You can customize the output folder by setting `outputPath` in the [project's configuration file](/docs/reference/project-configuration).

Nx [caches build results](/docs/features/cache-task-results) automatically. Subsequent builds of unchanged projects restore from cache.

### View project configuration

To see the full configuration for a project:

```shell
nx show project my-app
```

Or open the [project details view in Nx Console](/docs/guides/nx-console/console-project-details#_top).

For full generator and executor option lists, see the [generators reference](/docs/technologies/react/generators) and [executors reference](/docs/technologies/react/executors).

## CI considerations

See [Set Up CI](/docs/guides/nx-cloud/setup-ci) for a complete CI configuration guide.

### Build and test only what changed

```shell
nx affected -t build test lint
```

This uses the [project graph](/docs/features/explore-graph) to determine which projects are [affected](/docs/features/ci-features/affected) by your changes and only runs tasks for those.

### Remote caching

Share build and test cache results across your team and CI with [remote caching](/docs/features/ci-features/remote-cache):

```shell
nx connect
```

## What's next

{% cardgrid %}
{% linkcard title="Learn Nx Tutorial" description="Build a monorepo step-by-step with Nx." href="/docs/getting-started/tutorials/crafting-your-workspace" /%}
{% linkcard title="React Router Guide" description="Set up React Router in framework mode with Nx." href="/docs/technologies/react/guides/react-router" /%}
{% linkcard title="Module Federation with SSR" description="Configure Module Federation with server-side rendering." href="/docs/technologies/react/guides/module-federation-with-ssr" /%}
{% linkcard title="Next.js Plugin" description="Use Nx with Next.js for inferred tasks and generators." href="/docs/technologies/react/next/introduction" /%}
{% linkcard title="Generators Reference" description="Full API reference for @nx/react generators." href="/docs/technologies/react/generators" /%}
{% linkcard title="Executors Reference" description="Full API reference for @nx/react executors." href="/docs/technologies/react/executors" /%}
{% /cardgrid %}

---
<!-- source: https://nx.dev/docs/technologies/react/migrations.md -->
## @nx/react Migrations

The @nx/react plugin provides various migrations to help you migrate to newer versions of react projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 22.6.x

### 22.6.0-package-updates
**Version**: 22.6.0-beta.10


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@module-federation/enhanced` | `^2.1.0` | Updated only
| `@module-federation/node` | `^2.7.21` | Updated only



## 22.3.x

### 22.3.4-package-updates
**Version**: 22.3.4-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `react-router-dom` | `6.30.3` | Updated only
| `react-router` | `7.12.0` | Updated only
| `@react-router/dev` | `7.12.0` | Updated only
| `@react-router/node` | `7.12.0` | Updated only
| `@react-router/serve` | `7.12.0` | Updated only
| `@react-router/express` | `7.12.0` | Updated only
| `@react-router/fs-routes` | `7.12.0` | Updated only
| `@react-router/cloudflare` | `7.12.0` | Updated only
| `@react-router/architect` | `7.12.0` | Updated only
| `@react-router/remix-routes-option-adapter` | `7.12.0` | Updated only



## 22.2.x

### 22.2.0-package-updates
**Version**: 22.2.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@module-federation/enhanced` | `^0.21.2` | Updated only
| `@module-federation/runtime` | `^0.21.2` | Updated only
| `@module-federation/sdk` | `^0.21.2` | Updated only
| `@module-federation/node` | `^2.7.21` | Updated only


### 22.2.0-emotion-package-updates
**Version**: 22.2.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@emotion/react` | `11.14.0` | Updated only
| `@emotion/styled` | `11.14.1` | Updated only
| `@emotion/babel-plugin` | `11.13.5` | Updated only



## 22.0.x

### `update-22-0-0-add-svgr-to-webpack-config`
**Version**: 22.0.0-beta.0

Updates webpack configs using React to use the new withSvgr composable function instead of the svgr option in withReact or NxReactWebpackPlugin.



## 21.4.x

### 21.4.0-package-updates
**Version**: 21.4.0-beta.8


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `http-proxy-middleware` | `^3.0.5` | Updated only



## 21.0.x

### `update-21-0-0-update-babel-loose`
**Version**: 21.0.0-beta.11

Replaces `classProperties.loose` option with `loose`.

#### Replace `classProperties.loose` option in `.babelrc`

The `classProperties.loose` option is replaced by `loose` in `.babelrc` files.

#### Sample Code Changes

##### Before

```json title=".babelrc"
{
  "presets": [
    [
      "@nx/react/babel",
      {
        "runtime": "automatic",
        "classProperties": {
          "loose": true
        },
        "useBuiltIns": "usage"
      }
    ]
  ],
  "plugins": []
}
```

##### After

```json title=".babelrc" {7}
{
  "presets": [
    [
      "@nx/react/babel",
      {
        "runtime": "automatic",
        "loose": true,
        "useBuiltIns": "usage"
      }
    ]
  ],
  "plugins": []
}
```




## 20.4.x

### `add-mf-env-var-to-target-defaults`
**Version**: 20.4.0-beta.0

Add NX_MF_DEV_REMOTES to inputs for task hashing when '@nx/webpack:webpack' or '@nx/rspack:rspack' is used for Module Federation.

#### Add Module Federation Env Var to Target Defaults

Add NX_MF_DEV_REMOTES to inputs for task hashing when `@nx/webpack:webpack` or `@nx/rspack:rspack` is used for Module Federation.

#### Sample Code Changes

##### Before

```json title="nx.json"
{
  "targetDefaults": {
    "@nx/webpack:webpack": {
      "inputs": ["^build"]
    }
  }
}
```

##### After

```json title="nx.json" {4-6}
{
  "targetDefaults": {
    "@nx/webpack:webpack": {
      "cache": true,
      "dependsOn": ["^build"],
      "inputs": [
        "^build",
        {
          "env": "NX_MF_DEV_REMOTES"
        }
      ]
    }
  }
}
```




## 20.3.x

### `ensure-nx-module-federation-package`
**Version**: 20.3.0-beta.2

If workspace includes Module Federation projects, ensure the new @nx/module-federation package is installed.

#### Ensure the @nx/module-federation Package is Installed

If workspace includes Module Federation projects, ensure the new `@nx/module-federation` package is installed.

#### Sample Code Changes

##### Before

```json title="package.json"
{
  "dependencies": {}
}
```

##### After

```json title="package.json"
{
  "dependencies": {
    "@nx/module-federation": "20.3.0"
  }
}
```



### 20.3.0-package-updates
**Version**: 20.3.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@testing-library/react` | `16.1.0` | Updated only



## 20.2.x

### `update-20-2-0-update-module-federation-config-import`
**Version**: 20.2.0-beta.2

Update the ModuleFederationConfig import use @nx/module-federation.

#### Migrate Module Federation Imports to New Package

Update the ModuleFederationConfig imports to use @nx/module-federation.

#### Sample Code Changes

Update import paths for ModuleFederationConfig.

##### Before

```js title="apps/shell/webpack.config.js"
import { ModuleFederationConfig } from '@nx/webpack';
```

```js title="apps/shell/rspack.config.js"
import { ModuleFederationConfig } from '@nx/rspack/module-federation';
```

##### After

```js title="apps/shell/webpack.config.js"
import { ModuleFederationConfig } from '@nx/module-federation';
```

```js title="apps/shell/rspack.config.js"
import { ModuleFederationConfig } from '@nx/module-federation';
```



### `update-20-2-0-update-with-module-federation-import`
**Version**: 20.2.0-beta.2

Update the withModuleFederation import use @nx/module-federation/webpack.

#### Migrate withModuleFederation Import to New Package

Update the withModuleFederation import to use @nx/module-federation/webpack.

#### Sample Code Changes

Update import paths for `withModuleFederation` and `withModuleFederationForSSR`.

##### Before

```ts title="apps/shell/webpack.config.ts"
import {
  withModuleFederation,
  withModuleFederationForSSR,
} from '@nx/react/module-federation';
```

##### After

```ts title="apps/shell/webpack.config.ts"
import {
  withModuleFederation,
  withModuleFederationForSSR,
} from '@nx/module-federation/webpack';
```



### 20.2.0-package-updates
**Version**: 20.2.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@module-federation/enhanced` | `0.7.6` | Updated only
| `@module-federation/runtime` | `0.7.6` | Updated only
| `@module-federation/sdk` | `0.7.6` | Updated only
| `@module-federation/node` | `2.6.11` | Updated only



## 20.1.x

### 20.1.0-package-updates
**Version**: 20.1.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `eslint-plugin-react-hooks` | `5.0.0` | Updated only
| `eslint-plugin-jsx-a11y` | `6.10.1` | Updated only



## 20.0.x

### 20.0.0-package-updates
**Version**: 20.0.0-beta.8


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `eslint-plugin-import` | `2.31.0` | Updated only

---
<!-- source: https://nx.dev/docs/technologies/react/next.md -->
## Next.js

{% index_page_cards path="technologies/react/next" /%}

---
<!-- source: https://nx.dev/docs/technologies/react/next/executors.md -->
## @nx/next Executors

The @nx/next plugin provides various executors to help you create and configure next projects within your Nx workspace.
Below is a complete reference for all available executors and their options.

### `build`
Build a Next.js app.

`project.json`:

```json
//...
{
  "name": "acme",
  "$schema": "node_modules/nx/schemas/project-schema.json",
  "sourceRoot": ".",
  "projectType": "application",
  "targets": {
    //...
    "build": {
      "executor": "@nx/next:build",
      "outputs": ["{options.outputPath}"],
      "defaultConfiguration": "production",
      "options": {
        "outputPath": "dist/acme"
      }
    }
    //...
  }
}
```

```bash
nx run acme:build
```

### Examples

#### For Next.js Standalone projects

###### Default configuration

This is the default configuration for Next.js standalone projects. Our `@nx/next:build` executor is integrated to use Next.js' CLI. You can read more about the build options at [Next.js CLI Options](https://nextjs.org/docs/app/api-reference/next-cli)

```json
    "build": {
      "executor": "@nx/next:build",
      "outputs": ["{options.outputPath}"],
      "defaultConfiguration": "production",
      "options": {
        "outputPath": "dist/acme"
      },
      "configurations": {
        "development": {
          "outputPath": "."
        },
        "production": {}
      }
    },
```

###### Enable debug

You can create a debug build for more verbose output by:

Using the `--debug` flag

```shell
nx run acme:build:development --debug
```

Updating the build options to include `debug`.

```json
    "build": {
      "executor": "@nx/next:build",
      "outputs": ["{options.outputPath}"],
      "defaultConfiguration": "production",
      "options": {
        "outputPath": "dist/acme"
      },
      "configurations": {
        "development": {
          "outputPath": ".",
          "debug": true
        },
        "production": {}
      }
    },
```

```bash
nx run acme:build:development
```

###### Adding profiling

You can enable profiing for React by

Using the `--profile` flag

```shell
nx run acme:build:production --profile
```

Updating the build options to include `profile`.

```json
    "build": {
      "executor": "@nx/next:build",
      "outputs": ["{options.outputPath}"],
      "defaultConfiguration": "production",
      "options": {
        "outputPath": "dist/acme"
      },
      "configurations": {
        "development": {
          "outputPath": ".",
        },
        "production": {
          "profile": true
        }
      }
    },
```

```shell
nx run acme:build:production
```

###### Enable experimental app only

Since Next.js 13 the `app/` directory it is reserved.
You can enable to build only `app/` routes by

Using the `--experimentalAppOnly` flag

```shell
nx run acme:build:production --experimentalAppOnly
```

Updating the build options to include `experimentalAppOnly`.

```json
    "build": {
      "executor": "@nx/next:build",
      "outputs": ["{options.outputPath}"],
      "defaultConfiguration": "production",
      "options": {
        "outputPath": "dist/acme"
      },
      "configurations": {
        "development": {
          "outputPath": ".",
          "experimentalAppOnly": true
        },
        "production": {}
      }
    },
```

```shell
nx run acme:build:production
```
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `outputPath` | string [**required**] | The output path of the generated files. |  |
| `buildLibsFromSource` | boolean | Read buildable libraries from source instead of building them separately. | `true` |
| `debug` | boolean | Enable Next.js debug build logging |  |
| `experimentalAppOnly` | boolean | Only build 'app' routes |  |
| `experimentalBuildMode` | string | Change the build mode. |  |
| `fileReplacements` | array | Replace files with other files in the build. | `[]` |
| `generateLockfile` | boolean | Generate a lockfile (e.g. package-lock.json) that matches the workspace lockfile to ensure package versions match. | `false` |
| `includeDevDependenciesInPackageJson` | boolean | Include `devDependencies` in the generated package.json file. By default only production `dependencies` are included. | `false` |
| `nextConfig` | string | Path (relative to workspace root) to a function which takes phase, config, and builder options, and returns the resulting config. This is an advanced option and should not be used with a normal Next.js config file (i.e. `next.config.js`). |  |
| `profile` | boolean | Used to enable React Production Profiling |  |
| `skipOverrides` | boolean | Do not add a `overrides` and `resolutions` entries to the generated package.json file. Only works in conjunction with `generatePackageJson` option. |  |
| `skipPackageManager` | boolean | Do not add a `packageManager` entry to the generated package.json file. |  |
| `turbo` | boolean | Use Turbopack for building (Next.js 15 and below). In Next.js 16+, Turbopack is enabled by default. |  |
| `webpack` | boolean | Use webpack bundler instead of Turbopack (Next.js 16+ only). This flag is only applicable in Next.js 16 and above where Turbopack is the default. |  |

### `server`
Serve a Next.js app.

`project.json`:

```json
//...
{
  "name": "acme",
  "$schema": "node_modules/nx/schemas/project-schema.json",
  "sourceRoot": ".",
  "projectType": "application",
  "targets": {
    //...
    "serve": {
      "executor": "@nx/next:server",
      "defaultConfiguration": "production",
      "options": {
        "buildTarget": "acme:build",
        "dev": true
      }
    }
    //...
  }
}
```

```bash
nx run acme:serve
```

### Examples

#### For Next.js Standalone projects

###### Default configuration

This is the default configuration for Next.js standalone projects. Our `@nx/next:server` executor is integrated to use Next.js' CLI. You can read more about the serve options at [Next.js CLI Options](https://nextjs.org/docs/app/api-reference/next-cli)

```json
    "serve": {
      "executor": "@nx/next:server",
      "defaultConfiguration": "development",
      "options": {
        "buildTarget": "acme:build",
        "dev": true
      },
      "configurations": {
        "development": {
          "buildTarget": "acme:build:development",
          "dev": true
        },
        "production": {
          "buildTarget": "acme:build:production",
          "dev": false
        }
      }
    },
```

###### Choosing your bundler

Turbopack is a cutting-edge bundler designed for JavaScript and TypeScript. To read more about supported features see [Next.js Turbopack Documentation](https://turbo.build/pack/docs/features)

**Important: Next.js 16 changed the default bundler**

- **Next.js 15 and below**: Webpack is the default bundler. Use `--turbo` to enable Turbopack.
- **Next.js 16 and above**: Turbopack is the default bundler. Use `--webpack` to use Webpack instead.

#### Using Turbopack in Next.js 15 and below

Append the `--turbo` flag while executing the Nx development server:

```shell
nx run acme:serve --turbo
```

Or update the serve options to include `turbo`:

```json
    "serve": {
      "executor": "@nx/next:server",
      "defaultConfiguration": "development",
      "options": {
        "buildTarget": "acme:build",
        "dev": true
      },
      "configurations": {
        "development": {
          "buildTarget": "acme:build:development",
          "dev": true,
          "turbo": true
        }
      }
    }
```

#### Using Webpack in Next.js 16 and above

If you need to use Webpack instead of the default Turbopack in Next.js 16+:

```shell
nx run acme:serve --webpack
```

Or update the serve options to include `webpack`:

```json
    "serve": {
      "executor": "@nx/next:server",
      "defaultConfiguration": "development",
      "options": {
        "buildTarget": "acme:build",
        "dev": true
      },
      "configurations": {
        "development": {
          "buildTarget": "acme:build:development",
          "dev": true,
          "webpack": true
        }
      }
    }
```

###### Adding keep alive timeout

When using Nx with Next.js behind a downstream proxy, it's important to make sure that the `keep-alive timeouts` of Next.js' HTTP server are set to longer durations than the timeouts of the proxy. If you don't do this, Node.js will unexpectedly end TCP connections without notifying the proxy when the `keep-alive timeout` is reached. This can lead to a proxy error when the proxy tries to reuse a connection that Node.js has already terminated.

To configure timeout values (in milliseconds) you can:

Pass `--keepAliveTimeout`

```shell
nx run acme:serve --keepAliveTimeout 60000
```

Updating the serve options to include `keepAliveTimeout`.

```json
    "serve": {
      "executor": "@nx/next:server",
      "defaultConfiguration": "development",
      "options": {
        "buildTarget": "acme:build",
        "dev": true
      },
      "configurations": {
        "development": {
          "buildTarget": "acme:build:development",
          "dev": true,
          "keepAliveTimeout": 60000
        },
        //
    }
  }
```

```shell
nx run acme:serve
```
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `buildTarget` | string [**required**] | Target which builds the application. |  |
| `buildLibsFromSource` | boolean | Read buildable libraries from source instead of building them separately. | `true` |
| `customServerHttps:` | boolean | Enable HTTPS support for the custom server. |  |
| `customServerTarget` | string | Target which builds the custom server. |  |
| `dev` | boolean | Serve the application in the dev mode. | `true` |
| `experimentalHttps` | boolean | Enable HTTPS support for the Next.js development server. |  |
| `experimentalHttpsCa` | string | Path to a HTTPS certificate authority file. |  |
| `experimentalHttpsCert` | string | Path to a HTTPS certificate file. |  |
| `experimentalHttpsKey` | string | Path to a HTTPS key file. |  |
| `hostname` | string | Hostname on which the application is served. |  |
| `keepAliveTimeout` | number | Max milliseconds to wait before closing inactive connection. |  |
| `port` | number | Port to listen on. | `4200` |
| `quiet` | boolean | Hide error messages containing server information. | `false` |
| `staticMarkup` | boolean | Static markup. | `false` |
| `turbo` | boolean | Activate Turbopack for Next.js (Next.js 15 and below). In Next.js 16+, Turbopack is enabled by default for development mode. |  |
| `webpack` | boolean | Use webpack bundler instead of Turbopack (Next.js 16+ only). This flag is only applicable in Next.js 16 and above where Turbopack is the default for development mode. |  |

---
<!-- source: https://nx.dev/docs/technologies/react/next/generators.md -->
## @nx/next Generators

The @nx/next plugin provides various generators to help you create and configure next projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `application`
Create a Next.js Application for Nx.

### Examples

###### Create app in a nested directory

```shell
nx g app apps/nested/myapp
```

###### Use a custom Express server

```shell
nx g app apps/myapp --custom-server
```

###### Use plain JavaScript (not TypeScript)

```shell
nx g app apps/myapp --js
```

**Usage:**
```bash
nx generate @nx/next:application [options]
```

**Aliases:** `app`

**Arguments:**
```bash
nx generate @nx/next:application <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--appDir` | boolean | Enable the App Router for this project. | `true` |
| `--customServer` | boolean | Use a custom Express server for the Next.js application. | `false` |
| `--e2eTestRunner` | string | Test runner to use for end to end (E2E) tests. | `"playwright"` |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"none"` |
| `--name` | string | The name of the application. |  |
| `--rootProject` | boolean | Create an application at the root of the workspace. | `false` |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--src` | boolean | Generate a `src` directory for the project. | `true` |
| `--style` | string | The file extension to be used for style files. | `"css"` |
| `--swc` | boolean | Enable the Rust-based compiler SWC to compile JS/TS files. | `true` |
| `--tags` | string | Add tags to the application (used for linting). |  |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"none"` |
| `--useProjectJson` | boolean | Use a `project.json` configuration file instead of inlining the Nx configuration in the `package.json` file. |  |

## `component`
Create a React Component for Next.

### Examples

###### Create a Component

Generate a component named `MyComponent` at `apps/my-app/src/app/my-component/my-component.tsx`:

```shell
nx g component apps/my-app/src/app/my-component/my-component.tsx
```

###### Create a Component with a Different Symbol Name

Generate a component named `Custom` at `apps/my-app/src/app/my-component/my-component.tsx`:

```shell
nx g component apps/my-app/src/app/my-component/my-component.tsx --name=custom
```

###### Create a Component Omitting the File Extension

Generate a component named `MyComponent` at `apps/my-app/src/app/my-component/my-component.tsx` without specifying the file extension:

```shell
nx g component apps/my-app/src/app/my-component/my-component
```

**Usage:**
```bash
nx generate @nx/next:component [options]
```

**Arguments:**
```bash
nx generate @nx/next:component <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--export` | boolean | When true, the component is exported from the project index.ts (if it exists). | `false` |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. |  |
| `--name` | string | The component symbol name. Defaults to the last segment of the file path. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipTests` | boolean | When true, does not create `spec.ts` test files for the new component. | `false` |
| `--style` | string | The file extension to be used for style files. | `"css"` |

## `convert-to-inferred`
Convert existing Next.js project(s) using `@nx/next:build` executor to use `@nx/next/plugin`.

**Usage:**
```bash
nx generate @nx/next:convert-to-inferred [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string | The project to convert from using the `@nx/next:build` executor to use `@nx/next/plugin`. If not provided, all projects using the `@nx/next:build` executor will be converted. |  |
| `--skipFormat` | boolean | Whether to format files. | `false` |

## `custom-server`
Add a custom server to existing Next.js application.

### Examples

###### Add a custom server to existing app

```shell
nx g custom-server my-app
```

**Usage:**
```bash
nx generate @nx/next:custom-server [options]
```

**Arguments:**
```bash
nx generate @nx/next:custom-server <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--compiler` | string | The compiler used to build the custom server. | `"tsc"` |

## `cypress-component-configuration`
Add Cypress Componet Testing to an existing NextJS project.

:::caution[Can I use component testing?]
Next component testing with Nx requires **Cypress version 10.7.0** and up.

You can migrate with to v11 via the [migrate-to-cypress-11 generator](/nx-api/cypress/generators/migrate-to-cypress-11).

This generator is for Cypress based component testing.

If you want to test components via Storybook with Cypress, then check out the [storybook-configuration generator docs](/nx-api/react/generators/storybook-configuration). However, this functionality is deprecated, and will be removed on Nx version 19.
:::

This generator is designed to get your Next project up and running with Cypress Component Testing.

```shell
nx g @nx/next:cypress-component-configuration --project=my-cool-next-project
```

Running this generator, adds the required files to the specified project with a preconfigured `cypress.config.ts` designed for Nx workspaces.

```ts title="cypress.config.ts"
import { defineConfig } from 'cypress';
import { nxComponentTestingPreset } from '@nx/next/plugins/component-testing';

export default defineConfig({
  component: nxComponentTestingPreset(__filename),
});
```

Here is an example on how to add custom options to the configuration

```ts title="cypress.config.ts"
import { defineConfig } from 'cypress';
import { nxComponentTestingPreset } from '@nx/next/plugins/component-testing';

export default defineConfig({
  component: {
    ...nxComponentTestingPreset(__filename),
    // extra options here
  },
});
```

```shell
nx g @nx/next:cypress-component-project --project=my-cool-next-project
```

### Auto Generating Tests

You can optionally use the `--generate-tests` flag to generate a test file for each component in your project.

```shell
nx g @nx/next:cypress-component-configuration --project=my-cool-next-project --generate-tests
```

### Running Component Tests

A new `component-test` target will be added to the specified project to run your component tests.

```shell
nx g component-test my-cool-next-project
```

Here is an example of the project configuration that is generated.

```json title="project.json"
{
  "targets" {
    "component-test": {
      "executor": "@nx/cypress:cypress",
      "options": {
        "cypressConfig": "<path-to-project-root>/cypress.config.ts",
        "testingType": "component",
        "skipServe": true
      }
    }
  }
}
```

Nx also supports [Angular component testing](/nx-api/angular/generators/cypress-component-configuration).

**Usage:**
```bash
nx generate @nx/next:cypress-component-configuration [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string [**required**] | The name of the project to add cypress component testing configuration to |  |
| `--generateTests` | boolean | Generate default component tests for existing components in the project | `false` |
| `--skipFormat` | boolean | Skip formatting files | `false` |

## `library`
Create a React Library for an Nx workspace.

### Examples

###### Create a new lib

```shell
nx g lib libs/my-lib
```

###### Create a new lib under a directory

The following will create a library at `libs/shared/my-lib`.

```shell
nx g lib libs/shared/my-lib
```

**Usage:**
```bash
nx generate @nx/next:library [options]
```

**Aliases:** `lib`

**Arguments:**
```bash
nx generate @nx/next:library <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--appProject` | string | The application project to add the library route to. |  |
| `--buildable` | boolean | Generate a buildable library that uses rollup to bundle. | `false` |
| `--bundler` | string | The bundler to use. Choosing 'none' means this library is not buildable. | `"none"` |
| `--component` | boolean | Generate a default component. | `true` |
| `--globalCss` | boolean | When true, the stylesheet is generated using global CSS instead of CSS modules (e.g. file is `*.css` rather than `*.module.css`). | `false` |
| `--importPath` | string | The library name used to import it, like `@myorg/my-awesome-lib`. |  |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"none"` |
| `--name` | string | Library name |  |
| `--publishable` | boolean | Create a publishable library. |  |
| `--routing` | boolean | Generate library with routes. |  |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--skipTsConfig` | boolean | Do not update tsconfig.json for development experience. | `false` |
| `--strict` | boolean | Whether to enable tsconfig strict mode or not. | `true` |
| `--style` | string | The file extension to be used for style files. | `"css"` |
| `--tags` | string | Add tags to the library (used for linting). |  |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"none"` |
| `--useProjectJson` | boolean | Use a `project.json` configuration file instead of inlining the Nx configuration in the `package.json` file. |  |

## `page`
Create a Page for Next.

### Examples

###### Create a Static Page

Generate a static page named `MyPage` at `apps/my-app/pages/my-page/page.tsx`:

```shell
nx g page apps/my-app/pages/my-page
```

###### Create a Dynamic Page

Generate a dynamic page at `apps/my-app/pages/products/[id]/page.tsx`:

```shell
nx g page "apps/my-app/pages/products/[id]"
```

**Usage:**
```bash
nx generate @nx/next:page [options]
```

**Arguments:**
```bash
nx generate @nx/next:page <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--export` | boolean | When true, the component is exported from the project `index.ts` (if it exists). | `false` |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. | `false` |
| `--name` | string | The page symbol name. Defaults to the page directory name. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--style` | string | The file extension to be used for style files. | `"css"` |
| `--withTests` | boolean | When true, creates a `spec.ts` test file for the new page. | `false` |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/next:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/react/next/guides.md -->
## Guides

{% index_page_cards path="technologies/react/next/guides" /%}

---
<!-- source: https://nx.dev/docs/technologies/react/next/guides/next-config-setup.md -->
## How to configure Next.js plugins

Next.js plugins are configured in the project's `next.config.js` file. Nx adds its own plugin (`withNx`) to help the Next.js application
understand workspace libraries, and other Nx-specific features. See below for an example of the `withNx` plugin that Nx adds by default.

```js frame="none"
// next.config.js

// ...

module.exports = withNx({
  // Nx configuration goes here
  nx: {
    babelUpwardRootMode: true,
  },
  // Add Next.js configuration goes here
});
```

You can configure and compose the Nx plugin with other plugins, such as `@next/mdx`.

{% aside type="caution" title="Avoid next-compose-plugins" %}
There is a popular package called `next-compose-plugins` that has not been maintained for over two years. This package does not correctly combine plugins in all situations. If you do use it, replace the package with Nx 16's `composePlugins` utility (see below).
{% /aside %}

## `withNx` plugin

The `withNx` Next.js plugin provides integration with Nx, including support for [workspace libraries](/docs/technologies/react/next/generators#library), SVGR, and more. It is included by default when you generate a Next.js [application](/docs/technologies/react/next/generators#application) with Nx. When you customize your `next.config.js` file, make sure to include the `withNx` plugin.

### Options

#### svgr

Type: `boolean`

Set this to true if you would like to use SVGR. See: https://react-svgr.com/

**Deprecated:** Configure SVGR support in your `next.config.js` file without Nx. This option will be removed in Nx 22. See: https://react-svgr.com/docs/next/

#### babelUpwardRootMode

Type: `boolean`

For a monorepo, set to `true` to incorporate `.babelrc` files from individual libraries into the build. Note, however, that doing so will prevent the application's `.babelrc` settings from being applied to its libraries. It is generally recommended not to enable this option, as it can lead to a lack of consistency throughout the workspace. Instead, the application's `.babelrc` file should include the presets and plugins needed by its libraries directly. For more information on babel root-mode, see here: https://babeljs.io/docs/en/options#rootmode

## Composing plugins using `composePlugins` utility

The `composePlugins` utility function helps you combine multiple Next.js plugins together.

```js frame="none"
// next.config.js
const { composePlugins, withNx } = require('@nx/next');
/**
 * @type {import('@nx/next/plugins/with-nx').WithNxOptions}
 **/
const nextConfig = {
  nx: {
    svgr: true,
    babelUpwardRootMode: true,
  },
  // Add Next.js configuration here
};

const plugins = [
  // Add more Next.js plugins to this list if needed.
  withNx,
];

module.exports = composePlugins(...plugins)(nextConfig);
```

If you want to add additional plugins, say [`@next/mdx`](https://www.npmjs.com/package/@next/mdx), you can add it to the plugins list.

```js frame="none"
const plugins = [
  // Add more Next.js plugins to this list if needed.
  require('@next/mdx')(),
  withNx,
];

module.exports = composePlugins(...plugins)(nextConfig);
```

The exported configuration will correctly call each plugin in order and apply their configuration changes to the final object. Note that `composePlugins` function will return an async function, so if you need to debug the configuration you can add a debug plugin as follows.

```js frame="none"
module.exports = composePlugins(...plugins, function debug(config) {
  // The debug plugin will be called last
  console.log({ config });
  return config;
})(nextConfig);
```

---
<!-- source: https://nx.dev/docs/technologies/react/next/introduction.md -->
## Next.js Plugin for Nx

The Next.js plugin for Nx, `@nx/next`, automatically [infers `build`, `dev`, and `start` tasks](#how-nxnext-infers-tasks) from your Next.js configuration and provides [generators for creating applications and libraries](#develop-nextjs-applications).

You don't need the plugin to use Next.js with Nx. Any project already benefits from [caching](/docs/features/cache-task-results), [task orchestration](/docs/features/run-tasks), and the [project graph](/docs/features/explore-graph). The plugin adds automatic task inference, code generators, and simplified configuration.

## Requirements

The `@nx/next` plugin supports the following package versions.

| Package | Supported Versions |
| ------- | ------------------ |
| `next`  | >=14.0.0 <17.0.0   |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

## Setting up @nx/next

### Add to an existing Nx workspace

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/next` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
Using `nx add` helps ensure the correct version is installed and configured.
{% /aside %}

```shell
nx add @nx/next
```

Verify the plugin is setup:

{% steps %}

1. Check for `@nx/next` listed as a plugin:

   ```shell
   nx report
   ```

2. Ensure inferred project targets are working:

   ```shell
   nx show projects --with-target=build
   ```

3. Inspect a specific project configuration:

   ```shell
   nx show project my-next-app
   ```

{% /steps %}

### Create a new workspace

```shell
npx create-nx-workspace@latest --preset=next
```

### Generate a new application

```shell
nx g @nx/next:app apps/my-app
```

To start the application in development mode, run `nx dev my-app`. Read more about the options available for the [application generator](/docs/technologies/react/next/generators#application).

### Generate a library

```shell
nx g @nx/next:lib libs/my-lib

# For a publishable library
nx g @nx/next:lib libs/my-lib --publishable --importPath=@myorg/my-lib
```

Read more about the options available for the [library generator](/docs/technologies/react/next/generators#library).

## Develop Next.js applications

### Serve for development

```shell
nx dev my-app
```

Starts the Next.js development server at http://localhost:3000 by default.

### Build for production

```shell
nx build my-app
```

The output goes to the `.next` folder inside your app's project directory by default. Customize the output directory with `distDir` in your `next.config.js`:

```javascript
// apps/my-app/next.config.js
const nextConfig = {
  distDir: 'dist',
};

module.exports = nextConfig;
```

### Start production server

```shell
nx start my-app
```

Serves the production build. Depends on `build` completing first.

### Use libraries in your application

```typescript
// apps/my-app/pages/index.tsx
import { MyComponent } from '@myorg/my-lib';

export default function Index() {
  return <MyComponent />;
}
```

There is no need to build the library prior to using it. When you update your library, the Next.js application automatically picks up the changes.

## Configure @nx/next

### How @nx/next infers tasks

The `@nx/next` plugin creates tasks for any project that has a Next.js configuration file. Any of the following files are recognized:

- `next.config.js`
- `next.config.cjs`
- `next.config.mjs`
- `next.config.ts`

### Plugin options

Configure `@nx/next/plugin` in the `plugins` array in `nx.json`:

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/next/plugin",
      "options": {
        "buildTargetName": "build",
        "devTargetName": "dev",
        "startTargetName": "start",
        "serveStaticTargetName": "serve-static"
      }
    }
  ]
}
```

| Option                  | Description                          | Default        |
| ----------------------- | ------------------------------------ | -------------- |
| `buildTargetName`       | Name of the production build task    | `build`        |
| `devTargetName`         | Name of the development server task  | `dev`          |
| `startTargetName`       | Name of the production server task   | `start`        |
| `serveStaticTargetName` | Name of the static export serve task | `serve-static` |

### Exclude or include specific projects

Use `include`/`exclude` glob patterns in the plugin configuration to scope which projects the plugin applies to:

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/next/plugin",
      "include": ["apps/**/*"],
      "exclude": ["apps/legacy-app/**/*"],
      "options": {
        "buildTargetName": "build",
        "devTargetName": "dev",
        "startTargetName": "start",
        "serveStaticTargetName": "serve-static"
      }
    }
  ]
}
```

### View inferred tasks

To see what tasks Nx inferred for a project:

```shell
nx show project my-app
```

Or open the [project details view in Nx Console](/docs/guides/nx-console/console-project-details#_top).

## CI considerations

See [Set Up CI](/docs/guides/nx-cloud/setup-ci) for a complete CI configuration guide.

### Build and test only what changed

```shell
nx affected -t build test lint
```

This uses the [project graph](/docs/features/explore-graph) to determine which projects are affected by your changes and only runs tasks for those. Read more about [the benefits of `nx affected`](/docs/features/ci-features/affected).

### Remote caching

Share build cache results across your team and CI with [remote caching](/docs/features/ci-features/remote-cache):

```shell
nx connect
```

### Static HTML export for E2E testing

Next.js applications support [static HTML export](https://nextjs.org/docs/app/building-your-application/deploying/static-exports) by setting `output: 'export'` in `next.config.js`. The `serve-static` target serves these static files for E2E testing in CI, without requiring a Next.js server.

## What's next

{% cardgrid %}
{% linkcard title="Deploy Next.js to Vercel" description="Deploy your Next.js application to Vercel with Nx." href="/docs/technologies/react/guides/deploy-nextjs-to-vercel" /%}
{% linkcard title="Next.js Config Setup" description="Configure Next.js settings for your Nx workspace." href="/docs/technologies/react/next/guides/next-config-setup" /%}
{% linkcard title="Learn Nx Tutorial" description="Build a monorepo step-by-step with Nx." href="/docs/getting-started/tutorials/crafting-your-workspace" /%}
{% linkcard title="Generators Reference" description="Full API reference for @nx/next generators." href="/docs/technologies/react/next/generators" /%}
{% linkcard title="Executors Reference" description="Full API reference for @nx/next executors." href="/docs/technologies/react/next/executors" /%}
{% linkcard title="Migrations Reference" description="Full reference for @nx/next migrations." href="/docs/technologies/react/next/migrations" /%}
{% /cardgrid %}

---
<!-- source: https://nx.dev/docs/technologies/react/next/migrations.md -->
## @nx/next Migrations

The @nx/next plugin provides various migrations to help you migrate to newer versions of next projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 22.6.x

### 22.6.0-package-updates
**Version**: 22.6.0-beta.10


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `next` | `~16.1.6` | Updated only
| `eslint-config-next` | `^16.1.6` | Updated only



## 22.2.x

### `update-22-2-0-create-ai-instructions-for-next-16`
**Version**: 22.2.0-beta.1

Create AI Instructions to help migrate users workspaces to Next.js 16.

#### Requires

| Name | Version |
|------|---------|
 `next` | `>=16.0.0` |

### 22.2.0-beta.1-package-updates
**Version**: 22.2.0-beta.1


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `next` | `~16.0.1` | Updated only
| `eslint-config-next` | `^16.0.1` | Updated only



## 22.0.x

### `update-22-0-0-add-svgr-to-next-config`
**Version**: 22.0.0-beta.0

Updates next.config.js files to add SVGR webpack configuration directly instead of using the nx.svgr option in withNx.



## 20.7.x

### 20.7.1-beta.0-package-updates
**Version**: 20.7.1-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `eslint-config-next` | `^15.2.4` | Updated only


### 20.7.1-beta.0-next14-package-updates
**Version**: 20.7.1-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `next` | `~14.2.26` | Updated only


### 20.7.1-beta.0-next15-package-updates
**Version**: 20.7.1-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `next` | `~15.2.4` | Updated only

---
<!-- source: https://nx.dev/docs/technologies/react/react-native.md -->
## React Native

{% index_page_cards path="technologies/react/react-native" /%}

---
<!-- source: https://nx.dev/docs/technologies/react/react-native/executors.md -->
## @nx/react-native Executors

The @nx/react-native plugin provides various executors to help you create and configure react-native projects within your Nx workspace.
Below is a complete reference for all available executors and their options.

### `build-android`
Build target options for Android.

`project.json`:

```json
{
  "name": "mobile",
  //...
  "targets": {
    //...
    "build-android": {
      "executor": "@nx/react-native:build-android",
      "outputs": [
        "{projectRoot}/build/outputs/bundle",
        "{projectRoot}/build/outputs/apk"
      ],
      "options": {}
    }
  }
}
```

```bash
nx run mobile:build-android
```

### Examples

###### Build with custom tasks

The `tasks` option accepts any custom gradle task, such as `assembleDebug`, `assembleRelease`, `bundleDebug`, `bundleRelease`, `installDebug`, `installRelease`.
For example, pass in `bundleRelease` or `bundleRelease` to tasks, it will create with `.aab` extension under bundle folder.
Pass in `assembleDebug` or `assembleRelease` to tasks, it will create a build with `.apk` extension under apk folder.
Pass in `installDebug` or `installRelease` to tasks, it will create a build with `.apk` extension and immediately install it on a running emulator or connected device.

```json
    "build-android": {
      "executor": "@nx/react-native:build-android",
      "outputs": [
        "{projectRoot}/build/outputs/bundle",
        "{projectRoot}/build/outputs/apk"
      ],
      "options": {
        "tasks": ["bundleRelease"]
      }
    }
```

###### Build for debug/release

The `mode` option allows you determine whether to build for debug/release apk.

```json
    "build-android": {
      "executor": "@nx/react-native:build-android",
      "outputs": [
        "{projectRoot}/build/outputs/bundle",
        "{projectRoot}/build/outputs/apk"
      ],
      "options": {
        "mode": "debug"
      }
    }
```

###### Build for current device architecture

The `activeArchOnly` option allows you to build native libraries only for the current device architecture for debug builds.

```json
    "build-android": {
      "executor": "@nx/react-native:build-android",
      "outputs": [
        "{projectRoot}/build/outputs/bundle",
        "{projectRoot}/build/outputs/apk"
      ],
      "options": {
        "activeArchOnly": true
      }
    }
```

---
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `activeArchOnly` | boolean | Build native libraries only for the current device architecture for debug builds. | `false` |
| `extraParams` | string | Custom params passed to gradle build command |  |
| `interactive` | boolean | Explicitly select build type and flavour to use before running a build |  |
| `mode` | string | Specify your app's build variant | `"debug"` |
| `port` | number | The port where the packager server is listening on. | `8081` |
| `resetCache` | boolean | Resets metro cache. | `false` |
| `tasks` | string | Run custom Gradle tasks. By default it's "assembleDebug". Will override passed mode and variant arguments. |  |

### `build-ios`
Build iOS app.

`project.json`:

```json
{
  "name": "mobile",
  //...
  "targets": {
    //...
    "build-ios": {
      "executor": "@nx/react-native:build-ios",
      "options": {}
    }
  }
}
```

```bash
nx run mobile:build-ios
```

### Examples

###### Build in Specific Location

The `buildFolder` option allows to specify the location for ios build artifacts. It corresponds to Xcode's -derivedDataPath.

```json
    "build-ios": {
      "executor": "@nx/react-native:build-ios",
      "options": {
        "buildFolder": "dist/ios/build"
      }
    }
```

```bash
nx build-ios <app-name> --buildFolder=dist/ios/build
```

###### Build the Debug/Release app

The `mode` option allows to specify the xcode configuartion, such as `Debug` or `Release`.

```json
    "build-ios": {
      "executor": "@nx/react-native:build-ios",
      "options": {
        "mode": "Release"
      }
    }
```

```bash
nx build-ios <app-name> --mode=Debug
nx build-ios <app-name> --mode=Release
```

###### Build for a simulator

The `simulator` option allows you to launch your iOS app in a specific simulator:

To see all the available simulators, run command:

```bash
xcrun simctl list devices available
```

```json
    "build-ios": {
      "executor": "@nx/react-native:build-ios",
      "options": {
        "simulator": "iPhone 14 Pro"
      }
    }
```

```bash
nx build-ios <app-name> --simulator="iPhone 14 Pro"
```

###### Build for a device

The `device` option allows you to launch your iOS app in a specific device.

To see all the available device, run command:

```bash
xcrun simctl list devices available
```

```json
    "build-ios": {
      "executor": "@nx/react-native:build-ios",
      "options": {
        "device": "deviceName"
      }
    }
```

```bash
nx build-ios <app-name> --device="deviceName"
```

###### Set Device by udid

The `udid` option allows you to explicitly set device to use by udid.

To see all the available simulators and devices with udid, run command:

```bash
xcrun simctl list devices available
```

```json
    "build-ios": {
      "executor": "@nx/react-native:build-ios",
      "options": {
        "udid": "device udid"
      }
    }
```

```bash
nx build-ios <app-name> --udid="device udid"
```

---
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `buildFolder` | string | Location for iOS build artifacts. Corresponds to Xcode's "-derivedDataPath". Relative to ios directory | `"./build"` |
| `device` | string | Explicitly set device to use by name. The value is not required if you have a single device connected. |  |
| `extraParams` | string | Custom params that will be passed to xcodebuild command. |  |
| `interactive` | boolean | Explicitly select which scheme and configuration to use before running a build |  |
| `mode` | string | Explicitly set the scheme configuration to use | `"Debug"` |
| `port` | number | The port where the packager server is listening on. | `8081` |
| `resetCache` | boolean | Resets metro cache. | `false` |
| `scheme` | string | Explicitly set Xcode scheme to use |  |
| `simulator` | string | Explicitly set simulator to use. Optionally include iOS version between parenthesis at the end to match an exact version: "iPhone 6 (10.0)" |  |
| `udid` | string | Explicitly set device to use by udid |  |
| `verbose` | boolean | Do not use xcbeautify or xcpretty even if installed |  |
| `xcconfig` | string | Explicitly set xcconfig to use |  |

### `bundle`
JS Bundle target options.

`project.json`:

```json
{
  "name": "mobile",
  //...
  "targets": {
    //...
    "bundle-ios": {
      "executor": "@nx/react-native:bundle",
      "outputs": ["{projectRoot}/build"],
      "options": {
        "entryFile": "src/main.tsx",
        "platform": "ios",
        "bundleOutput": "dist/apps/mobile/ios/main.jsbundle"
      }
    },
    "bundle-android": {
      "executor": "@nx/react-native:bundle",
      "options": {
        "entryFile": "src/main.tsx",
        "platform": "android",
        "bundleOutput": "dist/apps/mobile/android/main.jsbundle"
      }
    }
  }
}
```

```bash
nx run mobile:bundle-ios
nx run mobile:bundle-android
```

### Examples

###### Bundle with sourcemap

The `sourcemapOutput` option allows you to specify the path of the source map relative to app folder:

```json
    "bundle-ios": {
      "executor": "@nx/react-native:bundle",
      "options": {
        "entryFile": "src/main.tsx",
        "platform": "ios",
        "bundleOutput": "dist/apps/mobile/ios/main.jsbundle",
        "sourcemapOutput": "../../dist/apps/mobile/ios/main.map",
      }
    },
    "bundle-android": {
      "executor": "@nx/react-native:bundle",
      "options": {
        "entryFile": "src/main.tsx",
        "platform": "android",
        "bundleOutput": "dist/apps/mobile/android/main.jsbundle",
        "sourcemapOutput": "../../dist/apps/mobile/android/main.map",
      }
    }
```

###### Create a dev/release bundle

The `dev` option determines whether to create a dev or release bundle. The default value is `true`, by setting it as `false`, warnings are disabled and the bundle is minified.

```json
    "bundle-ios": {
      "executor": "@nx/react-native:bundle",
      "options": {
        "entryFile": "src/main.tsx",
        "platform": "ios",
        "bundleOutput": "dist/apps/mobile/ios/main.jsbundle",
        "dev": false
      }
    },
    "bundle-android": {
      "executor": "@nx/react-native:bundle",
      "options": {
        "entryFile": "src/main.tsx",
        "platform": "android",
        "bundleOutput": "dist/apps/mobile/android/main.jsbundle",
        "dev": false
      }
    }
```

###### Create a minified bundle

The `minify` option allows you to create a minified bundle:

```json
    "bundle-ios": {
      "executor": "@nx/react-native:bundle",
      "options": {
        "entryFile": "src/main.tsx",
        "platform": "ios",
        "bundleOutput": "dist/apps/mobile/ios/main.jsbundle",
        "minify": true
      }
    },
    "bundle-android": {
      "executor": "@nx/react-native:bundle",
      "options": {
        "entryFile": "src/main.tsx",
        "platform": "android",
        "bundleOutput": "dist/apps/mobile/android/main.jsbundle",
        "minify": true
      }
    }
```

---
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `bundleOutput` | string [**required**] | The output path of the generated files. |  |
| `entryFile` | string [**required**] | The entry file relative to project root. |  |
| `platform` | any [**required**] | Platform to build for. |  |
| `assetsDest` | string | Directory name where to store assets referenced in the bundle. |  |
| `dev` | boolean | Generate a development build. | `true` |
| `maxWorkers` | number | The number of workers we should parallelize the transformer on. |  |
| `minify` | boolean | Allows overriding whether bundle is minified. |  |
| `readGlobalCache` | boolean | Try to fetch transformed JS code from the global cache, if configured. | `false` |
| `resetCache` | boolean | Removes cached files. | `false` |
| `sourcemapOutput` | string | File name where to store the sourcemap file for resulting bundle, ex. /tmp/groups.map. |  |
| `sourcemapSourcesRoot` | string | Path to make sourcemaps sources entries relative to, ex. /root/dir. |  |
| `sourcemapUseAbsolutePath` | boolean | Report SourceMapURL using its full path. | `false` |
| `transformer` | string | Specify a custom transformer to be used. |  |

### `ensure-symlink`
Ensure workspace node_modules is symlink under app's node_modules folder.


### `pod-install`
Run `pod install` for React Native iOS Project.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `buildFolder` | string [**required**] | Location for iOS build artifacts. Corresponds to Xcode's "-derivedDataPath". Relative to ios directory. | `"./build"` |
| `deployment` | boolean | Disallow any changes to the Podfile or the Podfile.lock during installation. | `false` |
| `repoUpdate` | boolean | Force running `pod repo update` before install. | `false` |
| `useBundler` | boolean | Run cocoapods within a Bundler environment, i.e. with the `bundle exec pod install` command | `false` |

### `run-android`
Run Android target options.

`project.json`:

```json
{
  "name": "mobile",
  //...
  "targets": {
    //...
    "run-android": {
      "executor": "@nx/react-native:run-android",
      "options": {}
    }
  }
}
```

```bash
nx run mobile:run-android
```

### Examples

###### Run on a specific device/simulator

To see all the available emulators, run command:

```bash
emulator -list-avds
```

The `deviceId` option allows you to launch your android app in a specific device/simulator:

```json
    "run-android": {
      "executor": "@nx/react-native:run-android",
      "options": {
        "deviceId": "Pixel_5_API_30"
      }
    }
```

###### Run the debug/release app

The `mode` option allows to specify the build variant, such as `debug` or `release`.

```json
    "run-android": {
      "executor": "@nx/react-native:run-android",
      "options": {
        "mode": "release"
      }
    }
```

---
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `activeArchOnly` | boolean | Build native libraries only for the current device architecture for debug builds. | `false` |
| `appId` | string | Specify an `applicationId` to launch after build. If not specified, `package` from `AndroidManifest.xml` will be used. |  |
| `appIdSuffix` | string | Specify an `applicationIdSuffix` to launch after build. |  |
| `binaryPath` | string | Path relative to project root where pre-built .apk binary lives. |  |
| `deviceId` | string | Builds your app and starts it on a specific device/simulator with the given device id (listed by running `adb devices` on the command line). |  |
| `extraParams` | string | Custom params passed to gradle build command |  |
| `interactive` | boolean | Explicitly select build type and flavour to use before running a build |  |
| `listDevices` | boolean | Lists all available Android devices and simulators and let you choose one to run the app |  |
| `mainActivity` | string | Name of the activity to start. | `"MainActivity"` |
| `mode` | string | Specify your app's build variant | `"debug"` |
| `port` | number | The port where the packager server is listening on. | `8081` |
| `resetCache` | boolean | Resets metro cache. | `false` |
| `tasks` | string | Run custom Gradle tasks. By default it's "assembleDebug". Will override passed mode and variant arguments. |  |

### `run-ios`
Run iOS target options.

`project.json`:

```json
{
  "name": "mobile",
  //...
  "targets": {
    //...
    "run-ios": {
      "executor": "@nx/react-native:run-ios",
      "options": {}
    }
  }
}
```

```bash
nx run mobile:run-ios
```

### Examples

###### Build the Debug/Release app

The `mode` option allows to specify the xcode configuartion schema, such as `Debug` or `Release`.

```json
    "run-ios": {
      "executor": "@nx/react-native:run-ios",
      "options": {
        "mode": "Release"
      }
    }
```

```bash
nx run-ios <app-name> --mode=Debug
```

###### Run on a simulator

The `simulator` option allows you to launch your iOS app in a specific simulator.

To see all the available simulators, run command:

```bash
xcrun simctl list devices available
```

```json
    "run-ios": {
      "executor": "@nx/react-native:run-ios",
      "options": {
        "simulator": "iPhone 14 Pro (16.2)"
      }
    }
```

```bash
nx run-ios <app-name> --simulator="iPhone 14 Pro (16.2)"
```

###### Run on a device

The `device` option allows you to launch your iOS app in a specific device.

To see all the available devices, run command:

```bash
xcrun simctl list devices available
```

```json
    "run-ios": {
      "executor": "@nx/react-native:run-ios",
      "options": {
        "device": "deviceName"
      }
    }
```

```bash
nx run-ios <app-name> --device="deviceName"
```

###### Set Device by udid

The `udid` option allows you to explicitly set device to use by udid.

To see all the available simulators and devices with udid, run command:

```bash
xcrun simctl list devices available
```

```json
    "run-ios": {
      "executor": "@nx/react-native:run-ios",
      "options": {
        "udid": "device udid"
      }
    }
```

```bash
nx run-ios <app-name> --udid="device udid"
```

---
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `binaryPath` | string | Path relative to project root where pre-built .app binary lives. |  |
| `buildFolder` | string | Location for iOS build artifacts. Corresponds to Xcode's "-derivedDataPath". Relative to ios directory. |  |
| `device` | string | Explicitly set device to use by name. The value is not required if you have a single device connected. |  |
| `extraParams` | string | Custom params that will be passed to xcodebuild command. |  |
| `interactive` | boolean | Explicitly select which scheme and configuration to use before running a build |  |
| `mode` | string | Explicitly set the scheme configuration to use | `"Debug"` |
| `port` | number | The port where the packager server is listening on. | `8081` |
| `resetCache` | boolean | Resets metro cache. | `false` |
| `scheme` | string | Explicitly set Xcode scheme to use |  |
| `simulator` | string | Explicitly set simulator to use. Optionally include iOS version between parenthesis at the end to match an exact version: "iPhone 6 (10.0)" |  |
| `udid` | string | Explicitly set device to use by udid |  |
| `verbose` | boolean | Do not use xcbeautify or xcpretty even if installed |  |
| `xcconfig` | string | Explicitly set xcconfig to use |  |

### `start`
Packager Server target options.

`project.json`:

```json
{
  "name": "mobile",
  //...
  "targets": {
    //...
    "start": {
      "executor": "@nx/react-native:start",
      "options": {
        "port": 8081
      }
    }
  }
}
```

```bash
nx run mobile:start
```

### Examples

###### Starts the server non-interactively

The `interactive` option allows you to specify whether to use interactive mode:

```json
    "start": {
      "executor": "@nx/react-native:start",
      "options": {
        "port": 8081,
        "interactive": false
      }
    }
```

###### Starts the server with cache reset

The `resetCache` option allows you to remove cached files.

```json
    "start": {
      "executor": "@nx/react-native:start",
      "options": {
        "port": 8081,
        "resetCache": true
      }
    }
```

---
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `interactive` | boolean | Run packager server in interactive mode. | `true` |
| `port` | number | The port to listen on. | `8081` |
| `resetCache` | boolean | Resets metro cache. | `false` |

### `storybook`
Load stories for react native.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `outputFile` | string [**required**] | The output file that will be written. It is relative to the project directory. | `"./.storybook/story-loader.ts"` |
| `pattern` | string [**required**] | The pattern of files to look at. It can be a specific file, or any valid glob. Note: if using the CLI, globs with `**/*...` must be escaped with quotes | `"**/*.stories.@(js|jsx|ts|tsx|md)"` |
| `searchDir` | array [**required**] | The directory or directories, relative to the project root, to search for files in. | `[]` |

### `sync-deps`
Updates `package.json` with project dependencies.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `all` | boolean | Copy all dependencies and devDependencies from the workspace root package.json. | `false` |
| `exclude` | array | An array of npm packages to exclude. | `[]` |
| `include` | array | An array of additional npm packages to include. | `[]` |

### `upgrade`
Upgrade React Native code for project.

---
<!-- source: https://nx.dev/docs/technologies/react/react-native/generators.md -->
## @nx/react-native Generators

The @nx/react-native plugin provides various generators to help you create and configure react-native projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `application`
Create a React Application for Nx.

**Usage:**
```bash
nx generate @nx/react-native:application [options]
```

**Aliases:** `app`

**Arguments:**
```bash
nx generate @nx/react-native:application <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--bundler` | string | The bundler to use. | `"vite"` |
| `--displayName` | string | The display name to show in the application. Defaults to name. |  |
| `--e2eTestRunner` | string | Adds the specified e2e test runner. | `"none"` |
| `--install` | boolean | Runs `pod install` for native modules before building iOS app. | `true` |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"none"` |
| `--name` | string | The name of the application. |  |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--tags` | string | Add tags to the application (used for linting). |  |
| `--unitTestRunner` | string | Test runner to use for unit tests | `"none"` |
| `--useProjectJson` | boolean | Use a `project.json` configuration file instead of inlining the Nx configuration in the `package.json` file. |  |

## `component`
Create a React native Component for Nx.

**Usage:**
```bash
nx generate @nx/react-native:component [options]
```

**Aliases:** `c`

**Arguments:**
```bash
nx generate @nx/react-native:component <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--classComponent` | boolean | Use class components instead of functional component. | `false` |
| `--export` | boolean | When true, the component is exported from the project `index.ts` (if it exists). | `false` |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. |  |
| `--name` | string | The component symbol name. Defaults to the last segment of the file path. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipTests` | boolean | When true, does not create `spec.ts` test files for the new component. | `false` |

## `convert-to-inferred`
Convert existing React Native project(s) using `@nx/react-native:*` executors to use `@nx/react-native/plugin`. Defaults to migrating all projects. Pass '--project' to migrate only one target.

**Usage:**
```bash
nx generate @nx/react-native:convert-to-inferred [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string | The project to convert from using the `@nx/react-native:*` executors to use `@nx/react-native/plugin`. |  |
| `--skipFormat` | boolean | Whether to format files at the end of the migration. | `false` |

## `library`
Create a React Native Library for Nx.

**Usage:**
```bash
nx generate @nx/react-native:library [options]
```

**Aliases:** `lib`

**Arguments:**
```bash
nx generate @nx/react-native:library <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--buildable` | boolean | Generate a buildable library. | `false` |
| `--importPath` | string | The library name used to import it, like `@myorg/my-awesome-lib`. |  |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"none"` |
| `--name` | string | Library name. |  |
| `--publishable` | boolean | Create a publishable library. |  |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--skipTsConfig` | boolean | Do not update `tsconfig.json` for development experience. | `false` |
| `--strict` | boolean | Whether to enable tsconfig strict mode or not. | `true` |
| `--tags` | string | Add tags to the library (used for linting). |  |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"none"` |
| `--useProjectJson` | boolean | Use a `project.json` configuration file instead of inlining the Nx configuration in the `package.json` file. |  |

## `web-configuration`
Setup web configuration to React Native apps using react-native-web.

**Usage:**
```bash
nx generate @nx/react-native:web-configuration [options]
```

**Arguments:**
```bash
nx generate @nx/react-native:web-configuration <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--bundler` | string [**required**] | The bundler to use. | `"vite"` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/react-native:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/react/react-native/introduction.md -->
## React Native Plugin for Nx

React Native brings the React declarative UI framework to iOS and Android. With React Native, you use native UI controls and have full access to the native platform.

The Nx Plugin for React Native contains generators for managing React Native applications and libraries within an Nx workspace. It provides:

- Integration with libraries such as Jest, Detox, and Storybook.
- Scaffolding for creating buildable libraries that can be published to npm.
- Utilities for automatic workspace refactoring.

## Requirements

The `@nx/react-native` plugin supports the following package versions.

| Package        | Supported Versions |
| -------------- | ------------------ |
| `metro-config` | >= 0.82.0          |
| `react-native` | ~0.79.3            |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

## Setting up React native

### Create a new workspace

To create a new workspace with React Native, run the following command:

```shell
npx create-nx-workspace@latest your-workspace-name --preset=react-native --appName=your-app-name
```

{% aside type="note" title="Don't know what you need?" %}
You can also run the command without arguments to go through the interactive prompts.
{% /aside %}

```shell
npx create-nx-workspace your-workspace-name
```

### Installation

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/react-native` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
{% /aside %}

In any Nx workspace, you can install `@nx/react-native` by running the following command:

```shell
nx add @nx/react-native
```

This will install the correct version of `@nx/react-native`.

### How @nx/react-native infers tasks

{% aside type="note" title="Inferred Tasks" %}
Nx plugins can infer tasks for your projects based on the configuration of different tools. You can read more about it at the [Inferred Tasks concept page](/docs/concepts/inferred-tasks).
{% /aside %}

The `@nx/react-native` plugin will create a task for any project that has an app configuration file present. Any of the following files will be recognized as an app configuration file:

- `app.config.js`
- `app.json`

### View inferred tasks

To view inferred tasks for a project, open the [project details view](/docs/concepts/inferred-tasks) in Nx Console or run `nx show project my-project --web` in the command line.

### @nx/react-native configuration

The `@nx/react-native/plugin` is configured in the `plugins` array in `nx.json`.

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/react-native/plugin",
      "options": {
        "startTargetName": "start",
        "podInstallTargetName": "pod-install",
        "bundleTargetName": "bundle",
        "runIosTargetName": "run-ios",
        "runAndroidTargetName": "run-android",
        "buildIosTargetName": "build-ios",
        "buildAndroidTargetName": "build-android"
      }
    }
  ]
}
```

Once a React Native configuration file has been identified, the targets are created with the name you specify under `startTargetName`, `podInstallTargetName`, `bundleTargetName`, `runIosTargetName`, `runAndroidTargetname`, `buildIosTargetName` or `buildAndroidTargetName` in the `nx.json` `plugins` array. The default names for the inferred targets are `start`, `pod-install`, `bundle`, `run-ios`, `run-android`, `build-ios` and `build-android`.

### Generating applications

To create additional React Native apps run:

```shell
nx g @nx/react-native:app apps/<your-app-name>
```

### Generating libraries

To generate a new library run:

```shell
nx g @nx/react-native:lib libs/<your-lib-name>
```

### Generating components

To generate a new component inside library run:

```shell
nx g @nx/react-native:component <component-path> --export
```

Replace `<component-directory>` with the directory where you want to place the component. It must be a path to a directory relative to the workspace root and located inside the library project root.

### Upgrade React Native

The Nx CLI provides the [`migrate` command](/docs/features/automate-updating-dependencies) to help you stay up to date with the latest version of Nx.

#### Use upgrade-native generator

To upgrade native iOS and Android code to latest, you can use the [upgrade-native](/docs/technologies/react/react-native/generators#upgrade-native) generator:

```shell
nx generate @nx/react-native:upgrade-native apps/<your-app-name>
```

This is a command that will replace the iOS and Android native code folder entirely.

#### Upgrade manually

You can also upgrade React Native iOS and Android code using the [rn-diff-purge](https://react-native-community.github.io/upgrade-helper/) project.

### Start metro server

To start the server that communicates with connected devices:

```shell
nx start <your-app-name>
```

### Run iOS

To build your app and start it on iOS simulator or device:

```shell
nx run-ios <your-app-name>
```

### Run android

To build your app and start it on a connected Android emulator or device:

```shell
nx run-android <your-app-name>
```

### Build iOS

To build an iOS app:

```shell
nx build-ios <your-app-name>
```

The build artifacts will be located under `<your app folder>/ios/build`.

You can specify the build folder by setting the `buildFolder` option:

```shell
nx build-ios <your-app-name> --buildFolder="./build"
```

### Build android

To build an Android app, run:

```shell
nx build-android <your app name>
```

The build artifacts will be located under `<your app folder>/android/app/build`.

## More documentation

- [Using Detox](/docs/technologies/test-tools/detox/introduction)
- [Using Jest](/docs/technologies/test-tools/jest/introduction)

---
<!-- source: https://nx.dev/docs/technologies/react/react-native/migrations.md -->
## @nx/react-native Migrations

The @nx/react-native plugin provides various migrations to help you migrate to newer versions of react-native projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 21.4.x

### `update-21-4-0-remove-deprecated-deps`
**Version**: 21.4.0-beta.0

Remove deprecated dependencies from package.json


### `update-21-4-0-upgrade-react-native-projects`
**Version**: 21.4.0-beta.0

Run nx upgrade for each React Native project


### 21.4.0-package-updates
**Version**: 21.4.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `react-native` | `~0.79.3` | Updated only
| `@react-native-community/cli` | `~18.0.0` | Added if not installed
| `@react-native-community/cli-platform-android` | `~18.0.0` | Added if not installed
| `@react-native-community/cli-platform-ios` | `~18.0.0` | Added if not installed
| `@react-native/babel-preset` | `~0.79.3` | Updated only
| `@react-native/metro-config` | `~0.79.3` | Updated only
| `react-native-web` | `~0.20.0` | Updated only
| `react` | `19.0.0` | Updated only
| `react-dom` | `19.0.0` | Updated only
| `react-test-renderer` | `~19.0.0` | Updated only
| `@types/react` | `~19.0.10` | Updated only
| `@types/react-dom` | `~19.0.6` | Updated only
| `@testing-library/react-native` | `~13.2.0` | Updated only
| `react-native-svg-transformer` | `~1.5.1` | Updated only
| `react-native-svg` | `~15.11.2` | Updated only
| `react-native-svg-web` | `~1.0.9` | Updated only
| `@babel/runtime` | `~7.27.6` | Updated only



## 20.3.x

### 20.3.0-package-updates
**Version**: 20.3.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `react-native` | `~0.76.3` | Updated only
| `@react-native-community/cli` | `~15.0.1` | Added if not installed
| `@react-native-community/cli-platform-android` | `~15.0.1` | Added if not installed
| `@react-native-community/cli-platform-ios` | `~15.0.1` | Added if not installed
| `@react-native/babel-preset` | `~0.76.3` | Updated only
| `@react-native/metro-config` | `~0.76.3` | Updated only
| `react-native-web` | `~0.19.13` | Updated only
| `react` | `~18.3.1` | Updated only
| `react-dom` | `~18.3.1` | Updated only
| `react-test-renderer` | `~18.3.1` | Updated only
| `@types/react` | `~18.3.12` | Updated only
| `@types/react-dom` | `~18.3.1` | Updated only
| `@testing-library/react-native` | `~12.9.0` | Updated only
| `react-native-svg-transformer` | `~1.5.0` | Updated only
| `react-native-svg` | `~15.8.0` | Updated only
| `react-native-svg-web` | `~1.0.9` | Updated only
| `@babel/runtime` | `~7.26.0` | Updated only

---
<!-- source: https://nx.dev/docs/technologies/react/remix.md -->
## Remix

{% index_page_cards path="technologies/react/remix" /%}

---
<!-- source: https://nx.dev/docs/technologies/react/remix/executors.md -->
## @nx/remix Executors

The @nx/remix plugin provides various executors to help you create and configure remix projects within your Nx workspace.
Below is a complete reference for all available executors and their options.

### `build`
Build a Remix app.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `outputPath` | string [**required**] | The output path of the generated files. |  |
| `generateLockfile` | boolean | Generate a lockfile (e.g. package-lock.json) that matches the workspace lockfile to ensure package versions match. | `false` |
| `generatePackageJson` | boolean | Generate package.json file in the output folder. | `false` |
| `includeDevDependenciesInPackageJson` | boolean | Include `devDependencies` in the generated package.json file. By default only production `dependencies` are included. | `false` |
| `skipOverrides` | boolean | Do not add a `overrides` and `resolutions` entries to the generated package.json file. Only works in conjunction with `generatePackageJson` option. |  |
| `skipPackageManager` | boolean | Do not add a `packageManager` entry to the generated package.json file. Only works in conjunction with `generatePackageJson` option. |  |
| `sourcemap` | boolean | Generate source maps for production. | `false` |

### `serve`
Serve a Remix app.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `command` | string | Command used to run your app server. |  |
| `debug` | boolean | Attach a Node.js inspector. | `false` |
| `devServerPort` | number | Port to start the dev server on. |  |
| `manual` | boolean | Enable manual mode | `false` |
| `port` | number | Set PORT environment variable that can be used to serve the Remix application. | `4200` |
| `tlsCert` | string | Path to TLS certificate (cert.pem). |  |
| `tlsKey` | string | Path to TLS key (key.pem). |  |

---
<!-- source: https://nx.dev/docs/technologies/react/remix/generators.md -->
## @nx/remix Generators

The @nx/remix plugin provides various generators to help you create and configure remix projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `action`
Generate an action for a given route.

**Usage:**
```bash
nx generate @nx/remix:action [options]
```

**Arguments:**
```bash
nx generate @nx/remix:action <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|

## `application`
Generate a new Remix application.

**Usage:**
```bash
nx generate @nx/remix:application [options]
```

**Aliases:** `app`

**Arguments:**
```bash
nx generate @nx/remix:application <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--e2eTestRunner` | string | Test runner to use for e2e tests | `"none"` |
| `--linter` | string | The tool to use for running lint checks. | `"none"` |
| `--name` | string | The name of the application. |  |
| `--rootProject` | boolean |  | `false` |
| `--skipFormat` | boolean | Skip formatting files | `false` |
| `--tags` | string | Add tags to the project (used for linting) |  |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"none"` |
| `--useProjectJson` | boolean | Use a `project.json` configuration file instead of inlining the Nx configuration in the `package.json` file. |  |

## `convert-to-inferred`
Convert existing Remix project(s) using `@nx/remix:*` executors to use `@nx/remix/plugin`. Defaults to migrating all projects. Pass '--project' to migrate only one target.

**Usage:**
```bash
nx generate @nx/remix:convert-to-inferred [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string | The project to convert from using the `@nx/remix:*` executors to use `@nx/remix/plugin`. |  |
| `--skipFormat` | boolean | Whether to format files at the end of the migration. | `false` |

## `cypress-component-configuration`
Add a Cypress component testing configuration to an existing project.

**Usage:**
```bash
nx generate @nx/remix:cypress-component-configuration [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string [**required**] | The name of the project to add cypress component testing configuration to |  |
| `--generateTests` | boolean | Generate default component tests for existing components in the project | `false` |
| `--skipFormat` | boolean | Skip formatting files | `false` |

## `error-boundary`
Generate an ErrorBoundary for a given route.

**Usage:**
```bash
nx generate @nx/remix:error-boundary [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--path` | string [**required**] | The path to route file relative to the project root. |  |
| `--skipFormat` | boolean | Skip formatting files after generation. | `false` |

## `library`
Generate a Remix library to help structure workspace and application.

**Usage:**
```bash
nx generate @nx/remix:library [options]
```

**Aliases:** `lib`

**Arguments:**
```bash
nx generate @nx/remix:library <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--buildable` | boolean | Generate a buildable library that uses rollup to bundle. | `false` |
| `--bundler` | string | The bundler to use. Choosing 'none' means this library is not buildable. | `"none"` |
| `--importPath` | string | The library name used to import it, like @myorg/my-awesome-lib |  |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"none"` |
| `--name` | string | Library name |  |
| `--skipFormat` | boolean | Skip formatting files after generator runs | `false` |
| `--style` | string | Generate a stylesheet | `"css"` |
| `--tags` | string | Add tags to the library (used for linting) |  |
| `--unitTestRunner` | string | Test Runner to use for Unit Tests | `"none"` |
| `--useProjectJson` | boolean | Use a `project.json` configuration file instead of inlining the Nx configuration in the `package.json` file. |  |

## `loader`
Generate an loader for a given route.

**Usage:**
```bash
nx generate @nx/remix:loader [options]
```

**Arguments:**
```bash
nx generate @nx/remix:loader <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|

## `meta`
Generate a meta function for a given route.

**Usage:**
```bash
nx generate @nx/remix:meta [options]
```

**Arguments:**
```bash
nx generate @nx/remix:meta <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|

## `resource-route`
Generate a resource route.

**Usage:**
```bash
nx generate @nx/remix:resource-route [options]
```

**Arguments:**
```bash
nx generate @nx/remix:resource-route <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--action` | boolean | Generate an action function | `false` |
| `--loader` | boolean | Generate a loader function | `true` |
| `--skipChecks` | boolean | Skip route error detection | `false` |

## `route`
Generate a route.

**Usage:**
```bash
nx generate @nx/remix:route [options]
```

**Arguments:**
```bash
nx generate @nx/remix:route <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--action` | boolean | Generate an action function | `false` |
| `--loader` | boolean | Generate a loader function | `false` |
| `--meta` | boolean | Generate a meta function | `false` |
| `--skipChecks` | boolean | Skip route error detection | `false` |
| `--style` | string | Generate a stylesheet | `"css"` |

## `setup-tailwind`
Setup tailwindcss for a given project.

**Usage:**
```bash
nx generate @nx/remix:setup-tailwind [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string [**required**] | The name of the project to add tailwind to |  |
| `--skipFormat` | boolean | Skip formatting files after generator runs | `false` |

## `storybook-configuration`
Set up Storybook for a Remix library.

**Usage:**
```bash
nx generate @nx/remix:storybook-configuration [options]
```

**Arguments:**
```bash
nx generate @nx/remix:storybook-configuration <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--configureStaticServe` | boolean | Specifies whether to configure a static file server target for serving storybook. Helpful for speeding up CI build/test times. | `true` |
| `--configureTestRunner` | boolean | Add a Storybook Test-Runner target. |  |
| `--generateStories` | boolean | Automatically generate `*.stories.ts` files for components declared in this project? | `true` |
| `--ignorePaths` | array | Paths to ignore when looking for components. |  |
| `--interactionTests` | boolean | Set up Storybook interaction tests. | `true` |
| `--js` | boolean | Generate JavaScript story files rather than TypeScript story files. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"eslint"` |
| `--tsConfiguration` | boolean | Configure your project with TypeScript. Generate main.ts and preview.ts files, instead of main.js and preview.js. | `false` |

## `style`
Generate a style import and file for a given route.

**Usage:**
```bash
nx generate @nx/remix:style [options]
```

**Arguments:**
```bash
nx generate @nx/remix:style <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/remix:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/react/remix/introduction.md -->
## Remix Plugin for Nx

The Remix plugin for Nx, `@nx/remix`, automatically [infers `build`, `dev`, `start`, and `typecheck` tasks](#how-nxremix-infers-tasks) from your Remix configuration and provides [generators for applications, libraries, routes, loaders, actions, and meta functions](#develop-remix-applications).

You don't need the plugin to use Remix with Nx. Any project already benefits from [caching](/docs/features/cache-task-results), [task orchestration](/docs/features/run-tasks), and the [project graph](/docs/features/explore-graph). The plugin adds automatic task inference, route scaffolding, and simplified configuration.

{% aside type="note" %}
React Router is the successor to Remix. For new projects, consider using [React Router](/docs/technologies/react/guides/react-router) instead. Existing Remix projects continue to work with `@nx/remix`.
{% /aside %}

## Requirements

The `@nx/remix` plugin supports the following package versions.

| Package          | Supported Versions |
| ---------------- | ------------------ |
| `@remix-run/dev` | ^2.17.3            |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

## Setting up @nx/remix

### Add to an existing Nx workspace

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/remix` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
Using `nx add` helps ensure the correct version is installed and configured.
{% /aside %}

```shell
nx add @nx/remix
```

Verify the plugin is setup:

{% steps %}

1. Check for `@nx/remix` listed as a plugin:

   ```shell
   nx report
   ```

2. Ensure inferred project targets are working:

   ```shell
   nx show projects --with-target=build
   ```

3. Inspect a specific project configuration for the inferred targets:

   ```shell
   nx show project my-remix-app
   ```

{% /steps %}

### Generate a new application

```shell
nx g @nx/remix:app apps/my-app
```

To start the application in development mode, run `nx dev my-app`. Read more about the options available for the [application generator](/docs/technologies/react/remix/generators#application).

### Generate a library

When developing your application, it often makes sense to split your codebase into smaller, more focused libraries.

```shell
nx g @nx/remix:lib libs/my-lib
```

Read more about the options available for the [library generator](/docs/technologies/react/remix/generators#library). Libraries let you share code between applications, enforce architectural boundaries with the [project graph](/docs/features/explore-graph), and speed up CI by only rebuilding what changed.

## Develop Remix applications

### Generate routes

```shell
nx g @nx/remix:route apps/my-app/app/routes/admin
```

This creates a new route file in your application's `routes` directory following Remix's file-based routing conventions. Read more about the options available for the [route generator](/docs/technologies/react/remix/generators#route).

### Add loaders, actions, and meta

```shell
nx g @nx/remix:loader apps/my-app/app/routes/admin
nx g @nx/remix:action apps/my-app/app/routes/admin
nx g @nx/remix:meta apps/my-app/app/routes/admin
```

These generators add loader, action, and meta functions to existing route files. Read more about the options available for the [loader](/docs/technologies/react/remix/generators#loader), [action](/docs/technologies/react/remix/generators#action), and [meta](/docs/technologies/react/remix/generators#meta) generators.

### Serve for development

```shell
nx dev my-app
```

This starts the Remix development server with hot module replacement at `http://localhost:3000`.

### Build for production

```shell
nx build my-app
```

Compiles the application for production deployment. The output is written to the `build` directory inside your project folder by default.

### Start production server

```shell
nx start my-app
```

Serves the production build using `remix-serve`. Depends on `build` completing first.

### Use libraries in your application

Import library code directly into your route files:

```tsx
// apps/my-app/app/routes/_index.tsx
import { MyComponent } from '@myorg/my-lib';

export default function Index() {
  return <MyComponent />;
}
```

You can also use library code in loaders by exporting from a separate server entry point:

```ts
// libs/my-lib/src/server.ts
export { myLoader } from './lib/my-loader';
```

```tsx
// apps/my-app/app/routes/admin.tsx
import { myLoader } from '@myorg/my-lib/server';

export const loader = myLoader;
```

## Configure @nx/remix

### How @nx/remix infers tasks

The `@nx/remix` plugin creates tasks for any project that has a Remix configuration file. The plugin recognizes two setups:

**Classic Remix Compiler** -- looks for any of the following files:

- `remix.config.js`
- `remix.config.mjs`
- `remix.config.cjs`

**Remix with Vite** -- looks for `vite.config.{js,ts,mjs,mts,cjs,cts}` files that import the Remix plugin from `@remix-run/dev`.

### Plugin options

Configure `@nx/remix/plugin` in the `plugins` array in `nx.json`:

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/remix/plugin",
      "options": {
        "buildTargetName": "build",
        "devTargetName": "dev",
        "startTargetName": "start",
        "typecheckTargetName": "typecheck"
      }
    }
  ]
}
```

| Option                | Description                         | Default     |
| --------------------- | ----------------------------------- | ----------- |
| `buildTargetName`     | Name of the production build task   | `build`     |
| `devTargetName`       | Name of the development server task | `dev`       |
| `startTargetName`     | Name of the production server task  | `start`     |
| `typecheckTargetName` | Name of the typecheck task          | `typecheck` |

### Exclude or include specific projects

Use `include`/`exclude` glob patterns in the plugin configuration:

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/remix/plugin",
      "include": ["apps/**/*"],
      "exclude": ["apps/legacy-app/**/*"],
      "options": {
        "buildTargetName": "build",
        "devTargetName": "dev",
        "startTargetName": "start",
        "typecheckTargetName": "typecheck"
      }
    }
  ]
}
```

### View inferred tasks

To see what tasks Nx inferred for a project:

```shell
nx show project my-app
```

Or open the [project details view in Nx Console](/docs/guides/nx-console/console-project-details#_top).

## CI considerations

See [Set Up CI](/docs/guides/nx-cloud/setup-ci) for a complete CI configuration guide.

### Build and test only what changed

```shell
nx affected -t build test typecheck lint
```

This uses the [project graph](/docs/features/explore-graph) to determine which projects are affected by your changes and only runs tasks for those.
Read more about [the benefits of `nx affected`](/docs/features/ci-features/affected).

### Remote caching

Share build and typecheck cache results across your team and CI with [remote caching](/docs/features/ci-features/remote-cache):

```shell
nx connect
```

## What's next

{% cardgrid %}
{% linkcard title="React Router Guide" description="React Router is the successor to Remix. Learn how to use it with Nx." href="/docs/technologies/react/guides/react-router" /%}
{% linkcard title="Learn Nx Tutorial" description="Build a monorepo step-by-step with Nx." href="/docs/getting-started/tutorials/crafting-your-workspace" /%}
{% linkcard title="Generators Reference" description="Full API reference for @nx/remix generators." href="/docs/technologies/react/remix/generators" /%}
{% linkcard title="Executors Reference" description="Full API reference for @nx/remix executors." href="/docs/technologies/react/remix/executors" /%}
{% linkcard title="Migrations Reference" description="Full reference for @nx/remix migrations." href="/docs/technologies/react/remix/migrations" /%}
{% /cardgrid %}

---
<!-- source: https://nx.dev/docs/technologies/react/remix/migrations.md -->
## @nx/remix Migrations

The @nx/remix plugin provides various migrations to help you migrate to newer versions of remix projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 22.3.x

### 22.3.4-package-updates
**Version**: 22.3.4-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@remix-run/node` | `2.17.3` | Added if not installed
| `@remix-run/react` | `2.17.3` | Added if not installed
| `@remix-run/serve` | `2.17.3` | Added if not installed
| `@remix-run/dev` | `2.17.3` | Added if not installed
| `@remix-run/css-bundle` | `2.17.3` | Added if not installed
| `@remix-run/eslint-config` | `2.17.3` | Added if not installed
| `@remix-run/server-runtime` | `2.17.3` | Updated only
| `@remix-run/testing` | `2.17.3` | Updated only
| `@remix-run/express` | `2.17.3` | Updated only
| `@remix-run/cloudflare` | `2.17.3` | Updated only
| `@remix-run/cloudflare-pages` | `2.17.3` | Updated only
| `@remix-run/cloudflare-workers` | `2.17.3` | Updated only
| `@remix-run/architect` | `2.17.3` | Updated only
| `@remix-run/deno` | `2.17.3` | Updated only
| `@remix-run/route-config` | `2.17.3` | Updated only
| `@remix-run/fs-routes` | `2.17.3` | Updated only



## 20.1.x

### 20.1.0-package-updates
**Version**: 20.1.0-beta.5


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@remix-run/node` | `^2.14.0` | Added if not installed
| `@remix-run/react` | `^2.14.0` | Added if not installed
| `@remix-run/serve` | `^2.14.0` | Added if not installed
| `@remix-run/dev` | `^2.14.0` | Added if not installed
| `@remix-run/css-bundle` | `^2.14.0` | Added if not installed
| `@remix-run/eslint-config` | `^2.14.0` | Added if not installed
| `@remix-run/server-runtime` | `^2.14.0` | Updated only
| `@remix-run/testing` | `^2.14.0` | Updated only
| `@remix-run/express` | `^2.14.0` | Updated only
| `@remix-run/cloudflare` | `^2.14.0` | Updated only
| `@remix-run/cloudflare-pages` | `^2.14.0` | Updated only
| `@remix-run/cloudflare-workers` | `^2.14.0` | Updated only
| `@remix-run/architect` | `^2.14.0` | Updated only
| `@remix-run/deno` | `^2.14.0` | Updated only
| `@remix-run/route-config` | `^2.14.0` | Updated only
| `@remix-run/fs-routes` | `^2.14.0` | Updated only

---
<!-- source: https://nx.dev/docs/technologies/test-tools.md -->
## Test Tools

{% index_page_cards path="technologies/test-tools" /%}

---
<!-- source: https://nx.dev/docs/technologies/test-tools/cypress.md -->
## Cypress

{% index_page_cards path="technologies/test-tools/cypress" /%}

---
<!-- source: https://nx.dev/docs/technologies/test-tools/cypress/executors.md -->
## @nx/cypress Executors

The @nx/cypress plugin provides various executors to help you create and configure cypress projects within your Nx workspace.
Below is a complete reference for all available executors and their options.

### `cypress`
Run Cypress for e2e, integration and component testing.

Depending on your testing type, the Cypress executor is configured in different ways. The following are sample configurations that are created via the [configuration](/nx-api/cypress/generators/configuration) and [component-configuration](/nx-api/cypress/generators/component-configuration) generators.

###### E2E Testing

```json
"targets": {
  "e2e": {
    "executor": "@nx/cypress:cypress",
    "options": {
      "cypressConfig": "apps/app-e2e/cypres.config.ts",
      "devServerTarget": "my-react-app:serve",
      "testingType": "e2e"
    }
  }
}
```

:::note[API Testing]
API testing with Cypress is the same setup as e2e testing. Just change which `devServerTarget` is used!
:::

#### Providing a Base URL

If `devServerTarget` is provided, the url returned from started the dev server will be passed to cypress as the `baseUrl` option.

Defining a `baseUrl` in the executor options will override the inferred `baseUrl` from the `devServerTarget`.

The `baseUrl` defined in the Cypress config file is the last value used if no url is found in the `devServerTarget` or executor options.

#### Static Serving

When running in CI it doesn't make sense to start up a dev server since there aren't changes to watch for.

You can use [`@nx/web:file-server`](/nx-api/web/executors/file-server) to serve the pre-built static files of your frontend project.

In some _frontend_ application, add a 'static-serve' target.

```json
"serve-static": {
  "executor": "@nx/web:file-server",
  "options":{
    "buildTarget": "frontend:build"
  }
}
```

In the _e2e_ application add a configuration to change `devServerTarget` to point to the `static-serve` from the _frontend_ application

```json
"e2e": {
  //...
  "configurations": {
    "ci": {
      "devServerTarget": "frontend:serve-static"
    }
  }
}
```

:::note[What about Node projects?]
The same can be done for backend node apps with [`@nx/js:node` executor](/nx-api/js/executors/node)
:::

```bash
nx e2e my-app-e2e
```

###### Component Testing

:::note[Cypress Component Testing]
When adding component testing to a project, it's best to use the framework specific generator, instead `cypress-component-project` directly.

- [React component testing](/nx-api/react/generators/cypress-component-configuration)
- [Angular component testing](/nx-api/angular/generators/cypress-component-configuration)
  :::

```json
"targets": {
  "component-test": {
    "executor": "@nx/cypress:cypress",
    "options": {
      "cypressConfig": "apps/app/cypres.config.ts",
      "devServerTarget": "my-react-app:build",
      "testingType": "component",
      "skipServe": true
    }
  }
}
```

It's important `skipServe` is set to true. Nx doesn't need to run the `devServerTarget`, Cypress creates its own dev server for component testing.
Instead, Nx needs to know what build target to create the correct configuration to pass to Cypress, which is why it's still used in component testing.

#### Environment Variables

Using [executor configurations](/concepts/executors-and-configurations#executors-and-configurations) offers flexibility to set environment variables

```json
"targets": {
  "e2e": {
    "executor": "@nx/cypress:cypress",
    "options": {
      "cypressConfig": "apps/app-e2e/cypres.config.ts",
      "devServerTarget": "my-react-app:serve",
      "testingType": "e2e"
    },
    "configurations": {
      "qa": {
        "env": {
          "API_URL": "https://api.qa.company.com"
        }
      },
      "dev": {
        "env": {
          "API_URL": "http://localhost:3333/api"
        }
      }
    }
  }
}
```

Read more on different ways to use [environment variables for cypress executor](/nx-api/cypress#environment-variables)
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `cypressConfig` | string [**required**] | The path of the Cypress configuration json file. |  |
| `autoCancelAfterFailures` | string | Specify the number of failures to cancel a run being recorded to the Cypress Cloud or `false` to disable auto-cancellation. |  |
| `baseUrl` | string | The address (with the port) which your application is running on. |  |
| `browser` | string | The browser to run tests in. |  |
| `ciBuildId` | string | A unique identifier for a run to enable grouping or parallelization. |  |
| `devServerTarget` | string | Dev server target to run tests against. |  |
| `env` | object | A key-value Pair of environment variables to pass to Cypress runner. |  |
| `exit` | boolean | Whether or not the Cypress Test Runner will stay open after running tests in a spec file. | `true` |
| `group` | string | A named group for recorded runs in the Cypress dashboard. |  |
| `headed` | boolean | Displays the browser instead of running headlessly. Set this to `true` if your run depends on a Chrome extension being loaded. | `false` |
| `headless` | boolean | Hide the browser instead of running headed. | `false` |
| `ignoreTestFiles` | string | A String or Array of glob patterns used to ignore test files that would otherwise be shown in your list of tests. Cypress uses minimatch with the options: `{dot: true, matchBase: true}`. We suggest using https://globster.xyz to test what files would match. |  |
| `key` | string | The key cypress should use to run tests in parallel/record the run (CI only). |  |
| `parallel` | boolean | Whether or not Cypress should run its tests in parallel (CI only). | `false` |
| `port` | string | Pass a specified port value to the devServerTarget, if the value is 'cypress-auto' a free port will automatically be picked for the devServerTarget. |  |
| `quiet` | boolean | If passed, Cypress output will not be printed to stdout. Only output from the configured Mocha reporter will print. | `false` |
| `record` | boolean | Whether or not Cypress should record the results of the tests. | `false` |
| `reporter` | string | The reporter used during cypress run. |  |
| `reporterOptions` | string | The reporter options used. Supported options depend on the reporter. https://docs.cypress.io/guides/tooling/reporters#Reporter-Options |  |
| `runnerUi` | boolean | Displays the Cypress Runner UI. Useful for when Test Replay is enabled and you would still like the Cypress Runner UI to be displayed for screenshots and video. |  |
| `skipServe` | boolean | Skip dev-server build. | `false` |
| `spec` | string | A comma delimited glob string that is provided to the Cypress runner to specify which spec files to run. i.e. `**examples/**,**actions.spec**`. |  |
| `tag` | string | A comma delimited list to identify a run with. |  |
| `testingType` | string | Specify the type of tests to execute. | `"e2e"` |
| `watch` | boolean | Recompile and run tests when files change. | `false` |

---
<!-- source: https://nx.dev/docs/technologies/test-tools/cypress/generators.md -->
## @nx/cypress Generators

The @nx/cypress plugin provides various generators to help you create and configure cypress projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `configuration`
Add a Cypress configuration to an existing project.

### Examples

This is a generator to add a cypress e2e configuration to an existing project.

```bash
nx g @nx/cypress:configuration --project=my-cool-project --devServerTarget=some-app:serve
```

Running this generator, adds the required files to run cypress tests for a project,
Mainly a `cypress.config.ts` file and default files in the `<project-root>/cypress/` directory.
Tests will be located in `<project-root>/cypress/e2e/*` by default.

You can customize the directory used via the `--directory` flag, the value is relative to the project root.

For example if you wanted to place the files inside an `e2e` folder

```bash
nx g @nx/cypress:configuration --project=my-cool-project --devServerTarget=some-app:serve --directory=e2e
```

Providing a `--devServerTarget` is optional if you provide a `--baseUrl` or the project you're adding the configuration to has a `serve` target already.
Otherwise, a `--devServerTarget` is recommend for the `@nx/cypress:cypress` executor to spin up the dev server for you automatically when needed.

**Usage:**
```bash
nx generate @nx/cypress:configuration [options]
```

**Aliases:** `cypress-e2e-configuration`, `e2e`, `e2e-config`

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string [**required**] | The project to add a Cypress configuration to |  |
| `--baseUrl` | string | The address (with the port) which your application is running on. If you wish to start your application when running the e2e target, then use --devServerTarget instead. |  |
| `--bundler` | string | The Cypress bundler to use. | `"webpack"` |
| `--devServerTarget` | string | A devServerTarget,'<projectName>:<targetName>[:<configName>], that will be used to run tests against. This is usually the app this project will be used in. Pass --baseUrl if you wish to not use a devServerTarget. |  |
| `--directory` | string | A directory where the project is placed relative from the project root | `"cypress"` |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. | `false` |
| `--jsx` | boolean | Whether or not this project uses JSX. | `true` |
| `--linter` | string | The tool to use for running lint checks. |  |
| `--port` | string | Set the 'port' option on the e2e target. It's recommend to set a different port so you can run tests e2e targets in parallel. Most dev servers support using '0' to automatically find a free port. The value 'cypress-auto' can be used if the underlying dev server does not support automatically finding a free port. |  |
| `--rootProject` | boolean | Create a application at the root of the workspace | `false` |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |

## `convert-to-inferred`
Convert existing Cypress project(s) using `@nx/cypress:cypress` executor to use `@nx/cypress/plugin`.

**Usage:**
```bash
nx generate @nx/cypress:convert-to-inferred [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string | The project to convert from using the `@nx/cypress:cypress` executor to use `@nx/cypress/plugin`. |  |
| `--skipFormat` | boolean | Whether to format files at the end of the migration. | `false` |

## `migrate-to-cypress-11`
Migrate Cypress e2e project from v8/v9 to Cypress v11.

**Usage:**
```bash
nx generate @nx/cypress:migrate-to-cypress-11 [options]
```

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/cypress:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/test-tools/cypress/guides.md -->
## Guides

{% index_page_cards path="technologies/test-tools/cypress/guides" /%}

---
<!-- source: https://nx.dev/docs/technologies/test-tools/cypress/guides/cypress-component-testing.md -->
## Cypress Component Testing

> Component testing requires Cypress v10 and above.
> See our [guide for more information](/docs/technologies/test-tools/cypress/guides/cypress-v11-migration) to migrate to Cypress v10.

Unlike [E2E testing](/docs/technologies/test-tools/cypress/introduction), component testing does not create a new project. Instead, Cypress component testing is added
directly to a project, like [Jest](/docs/technologies/test-tools/jest/introduction)

## Add component testing to a project

> Currently only [@nx/react](/docs/technologies/react/generators#cypress-component-configuration), [@nx/angular](/docs/technologies/angular/generators#cypress-component-configuration), and [@nx/next](/docs/technologies/react/next/generators#cypress-component-configuration) plugins support component testing

Use the `cypress-component-configuration` generator from the respective plugin to add component testing to a project.

```shell
nx g @nx/react:cypress-component-configuration --project=your-project

nx g @nx/angular:cypress-component-configuration --project=your-project

nx g @nx/next:cypress-component-configuration --project=your-project
```

You can optionally pass in `--generate-tests` to create component tests for all components within the library.

Component testing supports both applications and libraries. By default, the generator attempts to find the build target for you based on the project's dependent apps. But you can manually specify the build target to use via the `--build-target` option. Note, in most cases, the build target will be from a different project than the one being configured. The only case where the build targets are from the same project is when the component tests are being added to an application.

> Note: The [@nx/next:cypress-component-configuration generator](/docs/technologies/react/next/generators#cypress-component-configuration) doesn't require a build target

```shell
nx g @nx/react:cypress-component-configuration --project=your-project --build-target=my-react-app:build

nx g @nx/angular:cypress-component-configuration --project=your-project --build-target=my-ng-app:build
```

The build target option can be changed later via updating the `devServerTarget` option in the `component-test` target.

{% aside type="caution" title="Executor Options" %}
When using component testing make sure to set `skipServe: true` in the component test target options, otherwise `@nx/cypress` will attempt to run the build first which can slow down your component tests. `skipServe: true` is automatically set when using the `cypress-component-configuration` generator.
{% /aside %}

## Configuration

When using the `cypress-component-configuration` generator, a helper function is used in the `cypress.config.ts` to setup the ideal settings for your project.

If you need to add additional configuration properties, you can spread the returned object from the helper function.

```ts
// cypress.config.ts
export default defineConfig({
  component: {
    ...nxComponentTestingPreset(__filename),
    // add your own config here
  },
});
```

## Testing projects

Run `nx component-test your-lib` to execute the component tests with Cypress.

By default, Cypress will run in headless mode. You will have the result of all the tests and errors (if any) in your
terminal. Screenshots and videos will be accessible in `dist/cypress/libs/your-lib/screenshots` and `dist/cypress/libs/your-lib/videos`.

## Watching for changes (Headed mode)

With, `nx component-test your-lib --watch` Cypress will start in headed mode. Where you can see your component being tested.

Running Cypress with `--watch` is a great way to iterate on your components since cypress will rerun your tests as you make those changes validating the new behavior.

## Splitting component testing tasks by file

{% aside type="note" title="Available since Nx 21.6.1" %}
Splitting component testing tasks by file is available since Nx 21.6.1.
{% /aside %}

Nx provides powerful features for [distributing tasks in CI](/docs/features/ci-features/distribute-task-execution), including [splitting tasks by file](/docs/features/ci-features/split-e2e-tasks) (also known as atomization). The `@nx/cypress` plugin facilitates this for Cypress projects, allowing you to run your tests more efficiently in your Continuous Integration (CI) environment.

To enable component testing task splitting, set the `ciComponentTestingTargetName` option of the `@nx/cypress/plugin` in your `nx.json` file. It will look something like this:

```json {% meta="{10}" %}
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/cypress/plugin",
      "options": {
        "targetName": "e2e",
        "ciTargetName": "e2e-ci",
        "componentTestingTargetName": "component-test",
        "ciComponentTestingTargetName": "component-test-ci",
        "openTargetName": "open-cypress"
      }
    }
  ]
}
```

The plugin will infer the `component-test-ci` task, which depends on individual component testing tasks for each file. You can then replace the `component-test` task with the `component-test-ci` task in your CI configuration to run your tests in a distributed fashion:

```diff {% meta="lang='yaml'" %}
// .github/workflows/ci.yaml
-     - run: pnpm exec nx affected -t lint test build component-test
+     - run: pnpm exec nx affected -t lint test build component-test-ci
```

## More information

You can read more on component testing in the [Cypress documentation](https://docs.cypress.io/guides/component-testing/writing-your-first-component-test).

---
<!-- source: https://nx.dev/docs/technologies/test-tools/cypress/guides/cypress-setup-node-events.md -->
## Using setupNodeEvents with Cypress preset

The [`setupNodeEvents`](https://docs.cypress.io/guides/references/configuration#setupNodeEvents) function in a Cypress configuration file allows you to tap into the internal behavior of Cypress using the `on` and `config` arguments.

```ts
// cypress.config.ts
import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      // e2e testing node events setup code
    },
  },
});
```

The Cypress preset that Nx provides (`@nx/cypress/plugins/cypress-preset`) uses `setupNodeEvents` to start the web server. Thus, if you provide your own function, then you must invoke the `setupNodeEvents` function that our preset provides.

```ts {% meta="{20}" %}
// cypress.config.ts
import { defineConfig } from 'cypress';
import { nxE2EPreset } from '@nx/cypress/plugins/cypress-preset';

const preset = nxE2EPreset(__filename, {
  cypressDir: 'src',
  bundler: 'vite',
  webServerCommands: {
    default: 'nx run my-project:serve',
    production: 'nx run my-project:preview',
  },
  ciWebServerCommand: 'nx run my-project:serve-static',
});

export default defineConfig({
  e2e: {
    ...preset,
    async setupNodeEvents(on, config) {
      // This line sets up the web server as provided via `webServerCommands` and `ciWebServerCommand`
      await preset.setupNodeEvents(on, config);

      // Register your listeners here
    },
  },
});
```

{% aside type="note" title="Note on async-await" %}
The `setupNodeEvents` function from our Cypress preset returns a promise, so make sure to await the result.
{% /aside %}

---
<!-- source: https://nx.dev/docs/technologies/test-tools/cypress/guides/cypress-v11-migration.md -->
## Migrating to Cypress V11

Cypress v10 introduce new features, like component testing, along with some breaking changes. Nx can help you migrate from v8 or v9 of Cypress to v10 and then to v11.

Before continuing, make sure you have all your changes committed and have a clean working tree.

You can migrate an E2E project to v11 by running the following command:

```shell
nx g @nx/cypress:migrate-to-cypress-11
```

In general, these are the steps taken to migrate your project:

1. Migrates your existing `cypress.json` configuration to a new `cypress.config.ts` configuration file.
   - The `pluginsFile` option has been replaced for `setupNodeEvents`. We will import the file and add it to
     the `setupNodeEvents` config option. Double-check your plugins are working correctly.
2. Rename all test files from `.spec.ts` to `.cy.ts`
3. Rename the `support/index.ts` to `support/e2e.ts` and update any associated imports
4. Rename the `integrations` folder to the `e2e` folder

{% aside type="caution" title="Root cypress.json" %}
Keeping a root `cypress.json` file, will cause issues with [Cypress trying to load the project](https://github.com/nrwl/nx/issues/11512).
Instead, you can create a [root ts file and import it into each project's cypress config file](https://github.com/nrwl/nx/issues/11512#issuecomment-1213420638) to share values across projects.
{% /aside %}

We take the best effort to make this migration seamless, but there can be edge cases we didn't anticipate. So feel free to [open an issue](https://github.com/nrwl/nx/issues/new?assignees=&labels=type%3A+bug&template=1-bug.md) if you come across any problems.

You can also consult the [official Cypress migration guide](https://docs.cypress.io/guides/references/migration-guide#Migrating-to-Cypress-version-10-0) if you get stuck and want to manually migrate your projects.

---
<!-- source: https://nx.dev/docs/technologies/test-tools/cypress/introduction.md -->
## Cypress Plugin for Nx

Cypress is a test runner built for the modern web. It has a lot of great features:

- Time travel
- Real-time reloads
- Automatic waiting
- Spies, stubs, and clocks
- Network traffic control
- Screenshots and videos

## Requirements

The `@nx/cypress` plugin supports the following package versions.

| Package   | Supported Versions |
| --------- | ------------------ |
| `cypress` | >= 13 < 16         |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

## Setting up @nx/cypress

> For Cypress Component Testing, see [the component testing guide](/docs/technologies/test-tools/cypress/guides/cypress-component-testing).

### Installation

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/cypress` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
{% /aside %}

In any Nx workspace, you can install `@nx/cypress` by running the following command:

```shell
nx add @nx/cypress
```

This will install the correct version of `@nx/cypress`.

### How @nx/cypress infers tasks

{% aside type="note" title="Inferred Tasks" %}
Nx plugins can infer tasks for your projects based on the configuration of different tools. You can read more about it at the [Inferred Tasks concept page](/docs/concepts/inferred-tasks).
{% /aside %}

The `@nx/cypress` plugin will create a task for any project that has a Cypress configuration file present. Any of the following files will be recognized as a Cypress configuration file:

- `cypress.config.js`
- `cypress.config.ts`
- `cypress.config.mjs`
- `cypress.config.cjs`

### View inferred tasks

To view inferred tasks for a project, open the [project details view](/docs/concepts/inferred-tasks) in Nx Console or run `nx show project my-project --web` in the command line.

### @nx/cypress configuration

The `@nx/cypress/plugin` is configured in the `plugins` array in `nx.json`.

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/cypress/plugin",
      "options": {
        "targetName": "e2e",
        "ciTargetName": "e2e-ci",
        "componentTestingTargetName": "component-test",
        "ciComponentTestingTargetName": "component-test-ci",
        "openTargetName": "open-cypress"
      }
    }
  ]
}
```

The options shown above control the names of the inferred Cypress tasks. The following table shows the default values for each option:

| Option                         | Default                                       |
| ------------------------------ | --------------------------------------------- |
| `targetName`                   | `"e2e"`                                       |
| `ciTargetName`                 | `"e2e-ci"`                                    |
| `componentTestingTargetName`   | `"component-test"`                            |
| `ciComponentTestingTargetName` | `undefined` (task is not inferred by default) |
| `openTargetName`               | `"open-cypress"`                              |

### Splitting E2E tasks by file

The `@nx/cypress/plugin` will automatically split your e2e tasks by file. Read more about the [Atomizer feature](/docs/features/ci-features/split-e2e-tasks).

To enable e2e task splitting, make sure there is a `ciWebServerCommand` property set in your `cypress.config.ts` file. It will look something like this:

```ts {% meta="{14}" %}
// apps/my-project-e2e/cypress.config.ts
import { defineConfig } from 'cypress';
import { nxE2EPreset } from '@nx/cypress/plugins/cypress-preset';

export default defineConfig({
  e2e: {
    ...nxE2EPreset(__filename, {
      cypressDir: 'src',
      bundler: 'vite',
      webServerCommands: {
        default: 'nx run my-project:serve',
        production: 'nx run my-project:preview',
      },
      ciWebServerCommand: 'nx run my-project:serve-static',
    }),
    baseUrl: 'http://localhost:4200',
  },
});
```

{% aside type="note" title="Using setupNodeEvents function" %}
If you use the `setupNodeEvents` function in your Cypress configuration, make sure to invoke the same function that is returned by `nxE2EPreset`. See the recipe on [using `setupNodeEvents` with Cypress preset](/docs/technologies/test-tools/cypress/guides/cypress-setup-node-events) for more details.
{% /aside %}

### Splitting component testing tasks by file

{% aside type="note" title="Available since Nx 21.6.1" %}
Splitting component testing tasks by file is available since Nx 21.6.1.
{% /aside %}

The `@nx/cypress/plugin` can also automatically split your component testing tasks by file. To enable it, set the `ciComponentTestingTargetName` option of the `@nx/cypress/plugin` in your `nx.json` file. It will look something like this:

```json {% meta="{10}" %}
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/cypress/plugin",
      "options": {
        "targetName": "e2e",
        "ciTargetName": "e2e-ci",
        "componentTestingTargetName": "component-test",
        "ciComponentTestingTargetName": "component-test-ci",
        "openTargetName": "open-cypress"
      }
    }
  ]
}
```

## E2E testing

By default, when creating a new frontend application, Nx will use Cypress to create the e2e tests project.

```shell
nx g @nx/web:app apps/frontend
```

### Configure Cypress for an existing project

To configure Cypress for an existing project, run the following generator:

```shell
nx g @nx/cypress:configuration --project=your-app-name
```

Optionally, you can use the `--baseUrl` option if you don't want the Cypress plugin to serve `your-app-name`.

```shell
nx g @nx/cypress:configuration --project=your-app-name --baseUrl=http://localhost:4200
```

Replace `your-app-name` with the app's name as defined in your `project.json` file or the `name` property of your `package.json`.

{% aside type="note" title="E2E setup location" %}
The `@nx/cypress:configuration` generator is not a project generator. It won't generate a separate project for the E2E tests. It will configure Cypress for the provided project.

To set up a separate project, you can generate a separate project with a project generator like `@nx/js:library` first and then run the `@nx/cypress:configuration` generator.
{% /aside %}

### Testing applications

Run `nx e2e frontend-e2e` to execute e2e tests with Cypress.

You can run your e2e test against a production build by using the `production` [configuration](/docs/concepts/executors-and-configurations#use-task-configurations)

```shell
nx e2e frontend-e2e --configuration=production
```

You can use the `--spec` flag to glob for test files.

```shell
# run the tests in the smoke/ directory
nx e2e frontend-e2e --spec="**smoke/**"

# run the tests in smoke/ directory and with dashboard in the file name
nx e2e frontend-e2e --spec="**smoke/**,**dashboard.cy**"
```

By default, Cypress will run in headless mode. You will have the result of all the tests and errors (if any) in your
terminal. Screenshots and videos will be accessible in `dist/cypress/apps/frontend/screenshots` and `dist/cypress/apps/frontend/videos`.

### Watching for changes (Headed mode)

You can also run Cypress in headed mode and watching for changes. This is a great way to enhance the dev workflow. You can build up test files with the application
running and Cypress will re-run those tests as you enhance and add to the suite.

{% tabs %}
{% tabitem label="Using inferred tasks" %}

```shell
nx open-cypress frontend-e2e
```

{% /tabitem %}

{% tabitem label="Using the @nx/cypress:cypress executor" %}

```shell
nx e2e frontend-e2e --watch
```

{% /tabitem %}
{% /tabs %}

### Specifying a custom url to test

The `baseUrl` property provides you the ability to test an application hosted on a specific domain.

{% tabs %}
{% tabitem label="Using inferred tasks" %}

```shell
nx e2e frontend-e2e --config="baseUrl=https://frontend.com"
```

{% aside type="note" title="Required options" %}
If `baseUrl` is not provided, Cypress will expect to have the `baseUrl` property in its config file. Otherwise, it will error.
{% /aside %}

{% /tabitem %}

{% tabitem label="Using the @nx/cypress:cypress executor" %}

```shell
nx e2e frontend-e2e --baseUrl=https://frontend.com
```

{% aside type="note" title="Required options" %}
If no `baseUrl` and no `devServerTarget` are provided, Cypress will expect to have the `baseUrl` property in its config file. Otherwise, it will error.
{% /aside %}

{% /tabitem %}
{% /tabs %}

## Using cypress.config.ts

If you need to fine tune your Cypress setup, you can do so by modifying `cypress.config.ts` in the project root. For
instance,
you can add your `projectId` to save all the screenshots and videos into your Cypress dashboard. The complete
configuration is documented
on [the official website](https://docs.cypress.io/guides/references/configuration.html#Options).

For adding more dynamic configurations to your Cypress configuration, you can look into using [setupNodeEvents](https://docs.cypress.io/api/plugins/browser-launch-api#Syntax) configuration option.

## Environment variables

If you need to pass a variable to Cypress that you don't want to commit to your repository (i.e. API keys, dynamic values based on configurations, API URLs), you can use [Cypress environment variables](https://docs.cypress.io/guides/guides/environment-variables).

There are a handful of ways to pass environment variables to Cypress, but the most common is via the [`cypress.env.json` file](https://docs.cypress.io/guides/guides/environment-variables#Option-1-configuration-file), the `-e` Cypress arg or the `env` option from the `@nx/cypress:cypress` executor in the [project configuration](/docs/reference/project-configuration#task-definitions-targets) or the command line.

Create a `cypress.env.json` file in the projects root (i.e. `apps/my-cool-app-e2e/cypress.env.json`). Cypress will automatically pick up this file. This method is helpful for configurations that you don't want to commit. Make sure to add the file to the `.gitignore` and add documentation so people in your repo know what values to populate in their local copy of the `cypress.env.json` file.

Setting the `-e` Cypress arg or the `env` option from the `@nx/cypress:cypress` executor in the project configuration is a good way to add values you want to define that you don't mind committing to the repository, such as a base API URL.

{% tabs %}
{% tabitem label="Using inferred tasks" %}

```json
// project.json
{
  ...
  "targets": {
    "e2e": {
      "options": {
        "args": "--env=API_URL=https://api.my-nx-website.com"
      }
    }
  }
}
```

{% /tabitem %}

{% tabitem label="Using the @nx/cypress:cypress executor" %}

```json
// project.json
{
  ...
  "targets": {
    "e2e": {
      "executor": "@nx/cypress:cypress",
      "options": {
        "env": "API_URL=https://api.my-nx-website.com"
      }
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

Finally, you can also pass environment variables via the command line with the `-e` Cypress arg or the `--env` option for the `@nx/cypress:cypress` executor.

{% tabs %}
{% tabitem label="Using inferred tasks" %}

```shell
nx e2e frontend-e2e -e=API_URL=https://api.my-nx-website.com,API_KEY=abc-123
```

{% /tabitem %}

{% tabitem label="Using the @nx/cypress:cypress executor" %}

```shell
nx e2e frontend-e2e --env.API_URL="https://api.my-nx-website.com" --env.API_KEY="abc-123"
```

{% /tabitem %}
{% /tabs %}

{% aside type="caution" title="Command-line args vs configuration options" %}
Providing a flag will override any option with the same name set in the project or workspace configuration.
{% /aside %}

---
<!-- source: https://nx.dev/docs/technologies/test-tools/cypress/migrations.md -->
## @nx/cypress Migrations

The @nx/cypress plugin provides various migrations to help you migrate to newer versions of cypress projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 22.3.x

### 22.3.2-package-updates
**Version**: 22.3.2-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `cypress` | `^15.8.0` | Updated only
| `@cypress/webpack-dev-server` | `^5.4.1` | Updated only



## 22.1.x

### `rename-cy-exec-code-property`
**Version**: 22.1.0-beta.6

Renames `cy.exec().its('code')` usages to the new `exitCode` property introduced in Cypress v15.

#### Requires

| Name | Version |
|------|---------|
 `cypress` | `>=15.0.0` |
#### Rename `cy.exec().its('code')` to `cy.exec().its('exitCode')`

Cypress v15 renamed the result property exposed by `cy.exec()` from `code` to `exitCode`. This migration updates Cypress spec files managed by Nx so that assertions such as `cy.exec(...).its('code')` use the new `exitCode` property.

Read more in the [migration guide](https://docs.cypress.io/app/references/migration-guide#cyexec-code-property-renamed).

#### Examples

##### Before

```ts title="apps/app-e2e/src/e2e/sample.cy.ts"
cy.exec('echo 0').its('code').should('eq', 0);
```

##### After

```ts title="apps/app-e2e/src/e2e/sample.cy.ts"
cy.exec('echo 0').its('exitCode').should('eq', 0);
```



### `update-selector-playground-api`
**Version**: 22.1.0-beta.6

Updates the deprecated `Cypress.SelectorPlayground` API to `Cypress.ElementSelector` and removes the unsupported `onElement` option.

#### Requires

| Name | Version |
|------|---------|
 `cypress` | `>=15.0.0` |
#### Update the Selector Playground API

Cypress v15 renamed `Cypress.SelectorPlayground` to `Cypress.ElementSelector` and removed the deprecated `onElement` option when calling `Cypress.ElementSelector.defaults()`. This migration updates existing Cypress support files to use the new API.

Read more in the [migration guide](https://docs.cypress.io/app/references/migration-guide#Selector-Playground-API-changes).

#### Examples

##### Before

```ts title="apps/web-e2e/src/support/selector.ts"
Cypress.SelectorPlayground.defaults({
  selectorPriority: ['data-cy'],
  onElement: (el) => el,
});
```

##### After

```ts title="apps/web-e2e/src/support/selector.ts"
Cypress.ElementSelector.defaults({
  selectorPriority: ['data-cy'],
});
```



### `update-angular-component-testing-support`
**Version**: 22.1.0-beta.6

For Angular component testing projects below v18, switches to the fallback `@cypress/angular` harness required by Cypress v15.

#### Requires

| Name | Version |
|------|---------|
 `cypress` | `>=15.0.0` |
#### Use the fallback Angular component testing harness for Cypress v15

Cypress v15 requires Angular component testing projects running Angular versions below 18 to migrate from the built-in `cypress/angular` helper to the `@cypress/angular` harness (v3). This migration updates component testing imports and ensures the correct dependency is installed.

Read more in the [migration guide](https://docs.cypress.io/app/references/migration-guide#Angular-17-CT-no-longer-supported).

#### Examples

##### Before

```ts title="apps/dashboard/src/app/app.component.cy.ts"
import { mount } from 'cypress/angular';
```

##### After

```ts title="apps/dashboard/src/app/app.component.cy.ts"
import { mount } from '@cypress/angular';
```



### 22.1.0-package-updates
**Version**: 22.1.0-beta.6


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `cypress` | `^15.6.0` | Updated only
| `@cypress/vite-dev-server` | `^7.0.1` | Updated only
| `@cypress/webpack-dev-server` | `^5.1.4` | Updated only



## 21.0.x

### `remove-tsconfig-and-copy-files-options-from-cypress-executor`
**Version**: 21.0.0-beta.10

Removes the `tsConfig` and `copyFiles` options from the `@nx/cypress:cypress` executor.

#### Remove `tsConfig` and `copyFiles` Options from Cypress Executor

Removes the previously deprecated and unused `tsConfig` and `copyFiles` options from the `@nx/cypress:cypress` executor configuration in all projects.

#### Examples

Remove the options from the project configuration:

##### Before

```json title="apps/app1-e2e/project.json" {7-8}
{
  "targets": {
    "e2e": {
      "executor": "@nx/cypress:cypress",
      "options": {
        "cypressConfig": "apps/app1-e2e/cypress.config.ts",
        "tsConfig": "apps/app1-e2e/tsconfig.json",
        "copyFiles": "**/*.spec.ts",
        "devServerTarget": "app1:serve"
      }
    }
  }
}
```

##### After

```json title="apps/app1-e2e/project.json"
{
  "targets": {
    "e2e": {
      "executor": "@nx/cypress:cypress",
      "options": {
        "cypressConfig": "apps/app1-e2e/cypress.config.ts",
        "devServerTarget": "app1:serve"
      }
    }
  }
}
```

Remove the options from a target default using the `@nx/cypress:cypress` executor:

##### Before

```json title="nx.json" {7-8}
{
  "targetDefaults": {
    "e2e": {
      "cache": true,
      "executor": "@nx/cypress:cypress",
      "options": {
        "tsConfig": "{projectRoot}/tsconfig.json",
        "copyFiles": "**/*.spec.ts"
      }
    }
  }
}
```

##### After

```json title="nx.json"
{
  "targetDefaults": {
    "e2e": {
      "cache": true,
      "executor": "@nx/cypress:cypress"
    }
  }
}
```

Remove the options from a target default using the `@nx/cypress:cypress` executor as the key:

##### Before

```json title="nx.json" {6-7}
{
  "targetDefaults": {
    "@nx/cypress:cypress": {
      "cache": true,
      "options": {
        "tsConfig": "{projectRoot}/tsconfig.json",
        "copyFiles": "**/*.spec.ts"
      }
    }
  }
}
```

##### After

```json title="nx.json"
{
  "targetDefaults": {
    "@nx/cypress:cypress": {
      "cache": true
    }
  }
}
```




## 20.8.x

### `set-inject-document-domain`
**Version**: 20.8.0-beta.0

Replaces the `experimentalSkipDomainInjection` configuration option with the new `injectDocumentDomain` configuration option.

#### Requires

| Name | Version |
|------|---------|
 `cypress` | `>=14.0.0` |
#### Set `injectDocumentDomain` Configuration Option

Replaces the removed `experimentalSkipDomainInjection` configuration option with the new `injectDocumentDomain` configuration option when needed. Skipping domain injection is the default behavior in Cypress v14 and therefore, it is required to use the `cy.origin()` command when navigating between domains. The `injectDocumentDomain` option was introduced to ease the transition to v14, but it is deprecated and will be removed in Cypress v15. Read more at the [migration notes](https://docs.cypress.io/app/references/migration-guide#Changes-to-cyorigin).

#### Examples

If the `experimentalSkipDomainInjection` configuration option is present, the migration will remove it. This is to account for the fact that skipping domain injection is the default behavior in Cypress v14.

##### Before

```ts title="apps/app1-e2e/cypress.config.ts"
import { nxE2EPreset } from '@nx/cypress/plugins/cypress-preset';
import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    ...nxE2EPreset(__filename, {
      cypressDir: 'src',
      bundler: 'vite',
      webServerCommands: {
        default: 'pnpm exec nx run app1:dev',
        production: 'pnpm exec nx run app1:dev',
      },
      ciWebServerCommand: 'pnpm exec nx run app1:dev',
      ciBaseUrl: 'http://localhost:4200',
    }),
    baseUrl: 'http://localhost:4200',
    experimentalSkipDomainInjection: ['https://example.com'],
  },
});
```

##### After

```ts title="apps/app1-e2e/cypress.config.ts"
import { nxE2EPreset } from '@nx/cypress/plugins/cypress-preset';
import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    ...nxE2EPreset(__filename, {
      cypressDir: 'src',
      bundler: 'vite',
      webServerCommands: {
        default: 'pnpm exec nx run app1:dev',
        production: 'pnpm exec nx run app1:dev',
      },
      ciWebServerCommand: 'pnpm exec nx run app1:dev',
      ciBaseUrl: 'http://localhost:4200',
    }),
    baseUrl: 'http://localhost:4200',
  },
});
```

If the `experimentalSkipDomainInjection` configuration option is present and set to an empty array (no domain injection is skipped), the migration will remove it and will set the `injectDocumentDomain` option to `true`.

##### Before

```ts title="apps/app1-e2e/cypress.config.ts"
import { nxE2EPreset } from '@nx/cypress/plugins/cypress-preset';
import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    ...nxE2EPreset(__filename, {
      cypressDir: 'src',
      bundler: 'vite',
      webServerCommands: {
        default: 'pnpm exec nx run app1:dev',
        production: 'pnpm exec nx run app1:dev',
      },
      ciWebServerCommand: 'pnpm exec nx run app1:dev',
      ciBaseUrl: 'http://localhost:4200',
    }),
    baseUrl: 'http://localhost:4200',
    experimentalSkipDomainInjection: [],
  },
});
```

##### After

```ts title="apps/app1-e2e/cypress.config.ts" {17-19}
import { nxE2EPreset } from '@nx/cypress/plugins/cypress-preset';
import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    ...nxE2EPreset(__filename, {
      cypressDir: 'src',
      bundler: 'vite',
      webServerCommands: {
        default: 'pnpm exec nx run app1:dev',
        production: 'pnpm exec nx run app1:dev',
      },
      ciWebServerCommand: 'pnpm exec nx run app1:dev',
      ciBaseUrl: 'http://localhost:4200',
    }),
    baseUrl: 'http://localhost:4200',
    // Please ensure you use `cy.origin()` when navigating between domains and remove this option.
    // See https://docs.cypress.io/app/references/migration-guide#Changes-to-cyorigin
    injectDocumentDomain: true,
  },
});
```

If the `experimentalSkipDomainInjection` configuration option is not present (no domain injection is skipped), the migration will set the `injectDocumentDomain` option to `true`.

##### Before

```ts title="apps/app1-e2e/cypress.config.ts"
import { nxE2EPreset } from '@nx/cypress/plugins/cypress-preset';
import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    ...nxE2EPreset(__filename, {
      cypressDir: 'src',
      bundler: 'vite',
      webServerCommands: {
        default: 'pnpm exec nx run app1:dev',
        production: 'pnpm exec nx run app1:dev',
      },
      ciWebServerCommand: 'pnpm exec nx run app1:dev',
      ciBaseUrl: 'http://localhost:4200',
    }),
    baseUrl: 'http://localhost:4200',
  },
});
```

##### After

```ts title="apps/app1-e2e/cypress.config.ts" {17-19}
import { nxE2EPreset } from '@nx/cypress/plugins/cypress-preset';
import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    ...nxE2EPreset(__filename, {
      cypressDir: 'src',
      bundler: 'vite',
      webServerCommands: {
        default: 'pnpm exec nx run app1:dev',
        production: 'pnpm exec nx run app1:dev',
      },
      ciWebServerCommand: 'pnpm exec nx run app1:dev',
      ciBaseUrl: 'http://localhost:4200',
    }),
    baseUrl: 'http://localhost:4200',
    // Please ensure you use `cy.origin()` when navigating between domains and remove this option.
    // See https://docs.cypress.io/app/references/migration-guide#Changes-to-cyorigin
    injectDocumentDomain: true,
  },
});
```



### `remove-experimental-fetch-polyfill`
**Version**: 20.8.0-beta.0

Removes the `experimentalFetchPolyfill` configuration option.

#### Requires

| Name | Version |
|------|---------|
 `cypress` | `>=14.0.0` |
#### Remove `experimentalFetchPolyfill` Configuration Option

Removes the `experimentalFetchPolyfill` configuration option that was removed in Cypress v14. Read more at the [migration notes](<https://docs.cypress.io/app/references/changelog#:~:text=The%20experimentalFetchPolyfill%20configuration%20option%20was,cy.intercept()%20for%20handling%20fetch%20requests>).

#### Examples

##### Before

```ts title="apps/app1-e2e/cypress.config.ts"
import { nxE2EPreset } from '@nx/cypress/plugins/cypress-preset';
import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    ...nxE2EPreset(__filename, {
      cypressDir: 'src',
      bundler: 'vite',
      webServerCommands: {
        default: 'pnpm exec nx run app1:dev',
        production: 'pnpm exec nx run app1:dev',
      },
      ciWebServerCommand: 'pnpm exec nx run app1:dev',
      ciBaseUrl: 'http://localhost:4200',
    }),
    baseUrl: 'http://localhost:4200',
    experimentalFetchPolyfill: true,
  },
});
```

##### After

```ts title="apps/app1-e2e/cypress.config.ts"
import { nxE2EPreset } from '@nx/cypress/plugins/cypress-preset';
import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    ...nxE2EPreset(__filename, {
      cypressDir: 'src',
      bundler: 'vite',
      webServerCommands: {
        default: 'pnpm exec nx run app1:dev',
        production: 'pnpm exec nx run app1:dev',
      },
      ciWebServerCommand: 'pnpm exec nx run app1:dev',
      ciBaseUrl: 'http://localhost:4200',
    }),
    baseUrl: 'http://localhost:4200',
  },
});
```



### `replace-experimental-just-in-time-compile`
**Version**: 20.8.0-beta.0

Replaces the `experimentalJustInTimeCompile` configuration option with the new `justInTimeCompile` configuration option.

#### Requires

| Name | Version |
|------|---------|
 `cypress` | `>=14.0.0` |
#### Replace the `experimentalJustInTimeCompile` Configuration Option with `justInTimeCompile`

Replaces the `experimentalJustInTimeCompile` configuration option with the new `justInTimeCompile` configuration option. Read more at the [migration notes](https://docs.cypress.io/app/references/migration-guide#CT-Just-in-Time-Compile-changes).

#### Examples

If the `experimentalJustInTimeCompile` configuration option is present and set to `true`, the migration will remove it. This is to account for the fact that JIT compilation is the default behavior in Cypress v14.

##### Before

```ts title="apps/app1/cypress.config.ts"
import { defineConfig } from 'cypress';

export default defineConfig({
  component: {
    devServer: {
      framework: 'angular',
      bundler: 'webpack',
    },
    experimentalJustInTimeCompile: true,
  },
});
```

##### After

```ts title="apps/app1/cypress.config.ts"
import { defineConfig } from 'cypress';

export default defineConfig({
  component: {
    devServer: {
      framework: 'angular',
      bundler: 'webpack',
    },
  },
});
```

If the `experimentalJustInTimeCompile` configuration option is set to `false` and it is using webpack, the migration will rename it to `justInTimeCompile`.

##### Before

```ts title="apps/app1/cypress.config.ts"
import { defineConfig } from 'cypress';

export default defineConfig({
  component: {
    devServer: {
      framework: 'angular',
      bundler: 'webpack',
    },
    experimentalJustInTimeCompile: false,
  },
});
```

##### After

```ts title="apps/app1/cypress.config.ts" {9}
import { defineConfig } from 'cypress';

export default defineConfig({
  component: {
    devServer: {
      framework: 'angular',
      bundler: 'webpack',
    },
    justInTimeCompile: false,
  },
});
```

If the `experimentalJustInTimeCompile` configuration is set to any value and it is using Vite, the migration will remove it. This is to account for the fact that JIT compilation no longer applies to Vite.

##### Before

```ts title="apps/app1/cypress.config.ts"
import { defineConfig } from 'cypress';

export default defineConfig({
  component: {
    devServer: {
      framework: 'react',
      bundler: 'vite',
    },
    experimentalJustInTimeCompile: false,
  },
});
```

##### After

```ts title="apps/app1/cypress.config.ts"
import { defineConfig } from 'cypress';

export default defineConfig({
  component: {
    devServer: {
      framework: 'react',
      bundler: 'vite',
    },
  },
});
```



### `update-component-testing-mount-imports`
**Version**: 20.8.0-beta.0

Updates the module specifier for the Component Testing `mount` function.

#### Requires

| Name | Version |
|------|---------|
 `cypress` | `>=14.0.0` |
#### Update Component Testing `mount` Imports

Updates the relevant module specifiers when importing the `mount` function and using the Angular or React frameworks. Read more at the [Angular migration notes](https://docs.cypress.io/app/references/migration-guide#Angular-1720-CT-no-longer-supported) and the [React migration notes](https://docs.cypress.io/app/references/migration-guide#React-18-CT-no-longer-supported).

#### Examples

If using the Angular framework with a version greater than or equal to v17.2.0 and importing the `mount` function from the `cypress/angular-signals` module, the migration will update the import to use the `cypress/angular` module.

##### Before

```ts title="apps/app1/cypress/support/component.ts"
import { mount } from 'cypress/angular-signals';
import './commands';

declare global {
  namespace Cypress {
    interface Chainable<Subject> {
      mount: typeof mount;
    }
  }
}

Cypress.Commands.add('mount', mount);
```

##### After

```ts title="apps/app1/cypress/support/component.ts" {1}
import { mount } from 'cypress/angular';
import './commands';

declare global {
  namespace Cypress {
    interface Chainable<Subject> {
      mount: typeof mount;
    }
  }
}

Cypress.Commands.add('mount', mount);
```

If using the Angular framework with a version lower than v17.2.0 and importing the `mount` function from the `cypress/angular` module, the migration will install the `@cypress/angular@2` package and update the import to use the `@cypress/angular` module.

##### Before

```json title="package.json"
{
  "name": "@my-repo/source",
  "dependencies": {
    ...
    "cypress": "^14.2.1"
  }
}
```

```ts title="apps/app1/cypress/support/component.ts"
import { mount } from 'cypress/angular';
import './commands';

declare global {
  namespace Cypress {
    interface Chainable<Subject> {
      mount: typeof mount;
    }
  }
}

Cypress.Commands.add('mount', mount);
```

##### After

```json title="package.json" {6}
{
  "name": "@my-repo/source",
  "dependencies": {
    ...
    "cypress": "^14.2.1",
    "@cypress/angular": "^2.1.0"
  }
}
```

```ts title="apps/app1/cypress/support/component.ts" {1}
import { mount } from '@cypress/angular';
import './commands';

declare global {
  namespace Cypress {
    interface Chainable<Subject> {
      mount: typeof mount;
    }
  }
}

Cypress.Commands.add('mount', mount);
```

If using the React framework and importing the `mount` function from the `cypress/react18` module, the migration will update the import to use the `cypress/react` module.

##### Before

```ts title="apps/app1/cypress/support/component.ts"
import { mount } from 'cypress/react18';
import './commands';

declare global {
  namespace Cypress {
    interface Chainable<Subject> {
      mount: typeof mount;
    }
  }
}

Cypress.Commands.add('mount', mount);
```

##### After

```ts title="apps/app1/cypress/support/component.ts" {1}
import { mount } from 'cypress/react';
import './commands';

declare global {
  namespace Cypress {
    interface Chainable<Subject> {
      mount: typeof mount;
    }
  }
}

Cypress.Commands.add('mount', mount);
```



### 20.8.0-package-updates
**Version**: 20.8.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `cypress` | `^14.2.1` | Updated only
| `@cypress/vite-dev-server` | `^6.0.3` | Updated only
| `@cypress/webpack-dev-server` | `^4.0.2` | Updated only

---
<!-- source: https://nx.dev/docs/technologies/test-tools/detox.md -->
## Detox

{% index_page_cards path="technologies/test-tools/detox" /%}

---
<!-- source: https://nx.dev/docs/technologies/test-tools/detox/executors.md -->
## @nx/detox Executors

The @nx/detox plugin provides various executors to help you create and configure detox projects within your Nx workspace.
Below is a complete reference for all available executors and their options.

### `build`
Run detox build options.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `configPath` | string | Specify Detox config file path. If not supplied, detox searches for `.detoxrc[.js]` or `detox` section in `package.json`. |  |
| `detoxConfiguration` | string | Select a device configuration from your defined configurations, if not supplied, and there's only one configuration, detox will default to it. |  |

### `test`
Run detox test options.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `detoxConfiguration` | string [**required**] | Select a device configuration from your defined configurations, if not supplied, and there's only one configuration, detox will default to it. |  |
| `appLaunchArgs` | number | Custom arguments to pass (through) onto the app every time it is launched. |  |
| `artifactsLocation` | string | Artifacts (logs, screenshots, etc) root directory. |  |
| `buildTarget` | string | Target which builds the application. |  |
| `captureViewHierarchy` | string | [iOS Only] Capture `*.uihierarchy` snapshots on view action errors and `device.captureViewHierarchy()` calls. |  |
| `cleanup` | boolean | Shutdown simulator when test is over, useful for CI scripts, to make sure detox exists cleanly with no residue |  |
| `color` | boolean | Colors in log output |  |
| `configPath` | string | Specify Detox config file path. If not supplied, detox searches for `.detoxrc[.js]` or `detox` section in package.json. |  |
| `debugSynchronization` | boolean | Customize how long an action/expectation can take to complete before Detox starts querying the app why it is busy. By default, the app status will be printed if the action takes more than 10s to complete. |  |
| `deviceBootArgs` | string | Custom arguments to pass (through) onto the device (emulator/simulator) binary when booted. |  |
| `deviceLaunchArgs` | string | A list of passthrough-arguments to use when (if) devices (Android emulator / iOS simulator) are launched by Detox. |  |
| `deviceName` | string | Override the device name specified in a configuration. Useful for running a single build configuration on multiple devices. |  |
| `forceAdbInstall` | boolean | Due to problems with the adb install command on Android, Detox resorts to a different scheme for install APK's. Setting true will disable that and force usage of `adb install`, instead. |  |
| `gpu` | boolean | [Android Only] Launch Emulator with the specific `-gpu [gpu mode]` parameter. |  |
| `headless` | boolean | Android Only] Launch Emulator in headless mode. Useful when running on CI. |  |
| `inspectBrk` | boolean | Uses node's `--inspect-brk` flag to let users debug the jest/mocha test runner |  |
| `jestReportSpecs` | boolean | [Jest Only] Whether to output logs per each running spec, in real-time. By default, disabled with multiple workers. |  |
| `keepLockFile` | boolean | Keep the device lock file when running Detox tests. |  |
| `loglevel` | string | Log level: `fatal`, `error`, `warn`, `info`, `verbose`, `trace`. |  |
| `recordLogs` | string | Save logs during each test to artifacts directory. Pass `failing` to save logs of failing tests only. |  |
| `recordPerformance` | string | [iOS Only] Save Detox Instruments performance recordings of each test to artifacts directory. |  |
| `recordTimeline` | string | [Jest Only] Record tests and events timeline, for visual display on the `chrome://tracing` tool. |  |
| `recordVideos` | string | Save screen recordings of each test to artifacts directory. Pass `failing` to save recordings of failing tests only. |  |
| `retries` | number | [Jest Circus Only] Re-spawn the test runner for individual failing suite files until they pass, or `<N>` times at least. |  |
| `reuse` | boolean | Reuse existing installed app (do not delete + reinstall) for a faster run. | `false` |
| `runnerConfig` | string | Test runner config file, defaults to `e2e/mocha.opts` for mocha and `e2e/config.json` for Jest. |  |
| `takeScreenshots` | string | Save screenshots before and after each test to artifacts directory. Pass `failing` to save screenshots of failing tests only.  |  |
| `useCustomLogger` | boolean | Use Detox' custom console-logging implementation, for logging Detox (non-device) logs. Disabling will fallback to Node.js / test-runner's implementation (e.g. Jest / Mocha). |  |
| `workers` | number | Specifies number of workers the test runner should spawn, requires a test runner with parallel execution support (Detox CLI currently supports Jest). |  |

---
<!-- source: https://nx.dev/docs/technologies/test-tools/detox/generators.md -->
## @nx/detox Generators

The @nx/detox plugin provides various generators to help you create and configure detox projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `application`
Create Detox Configuration for the workspace.

**Usage:**
```bash
nx generate @nx/detox:application [options]
```

**Aliases:** `app`

**Arguments:**
```bash
nx generate @nx/detox:application <e2eDirectory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--appProject` | string [**required**] | Name of the frontend project to be tested. |  |
| `--framework` | string [**required**] | App framework to test |  |
| `--appDisplayName` | string | Display name of the app to be tested if different from appProject |  |
| `--appName` | string | Name of the app to be tested if different from appProject |  |
| `--e2eName` | string | Name of the E2E Project. |  |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"eslint"` |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--useProjectJson` | boolean | Use a `project.json` configuration file instead of inlining the Nx configuration in the `package.json` file. |  |

## `convert-to-inferred`
Convert existing Detox project(s) using `@nx/detox:*` executors to use `@nx/detox/plugin`. Defaults to migrating all projects. Pass '--project' to migrate only one target.

**Usage:**
```bash
nx generate @nx/detox:convert-to-inferred [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string | The project to convert from using the `@nx/detox:*` executors to use `@nx/detox/plugin`. |  |
| `--skipFormat` | boolean | Whether to format files at the end of the migration. | `false` |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/detox:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/test-tools/detox/introduction.md -->
## Detox Plugin for Nx

Detox is gray box end-to-end testing and automation library for mobile apps. It has a lot of great features:

- Cross Platform
- Runs on Devices
- Automatically Synchronized
- Test Runner Independent
- Debuggable

## Requirements

The `@nx/detox` plugin supports the following package versions.

| Package | Supported Versions |
| ------- | ------------------ |
| `detox` | ^20.9.0            |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

## Setting up detox

### Setup environment

#### Install applesimutils (Mac only)

[applesimutils](https://github.com/wix/AppleSimulatorUtils) is a collection of utils for Apple simulators.

```shell
brew tap wix/brew
brew install applesimutils
```

#### Install Jest globally

```shell
npm install -g jest
```

### Installation

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/detox` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
{% /aside %}

In any Nx workspace, you can install `@nx/detox` by running the following command:

```shell
nx add @nx/detox
```

This will install the correct version of `@nx/detox`.

### How @nx/detox infers tasks

The `@nx/detox` plugin will create a task for any project that has an ESLint configuration file present. Any of the following files will be recognized as an ESLint configuration file:

- `.detoxrc.js`
- `.detoxrc.json`
- `detox.config.js`
- `detox.config.json`

### View inferred tasks

To view inferred tasks for a project, open the [project details view](/docs/concepts/inferred-tasks) in Nx Console or run `nx show project my-project --web` in the command line.

### @nx/detox configuration

The `@nx/detox/plugin` is configured in the `plugins` array in `nx.json`.

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/detox/plugin",
      "options": {
        "buildTargetName": "build",
        "startTargetName": "start",
        "testTargetName": "test"
      }
    }
  ]
}
```

Once a Detox configuration file has been identified, the targets are created with the name you specify under `buildTargetName`, `startTargetName` or `testTargetName` in the `nx.json` `plugins` array. The default names for the inferred targets are `build` and `test`.

## Using detox

### Testing applications

- Run `nx test-ios frontend-e2e` to build the iOS app and execute e2e tests with Detox for iOS (Mac only)
- Run `nx test-android frontend-e2e` to build the Android app and execute e2e tests with Detox for Android

You can run below commands:

- `nx build-ios frontend-e2e`: build the iOS app (Mac only)
- `nx build-android frontend-e2e`: build the Android app

### Testing against prod build

You can run your e2e test against a production build:

- `nx test-ios frontend-e2e --prod`: to build the iOS app and execute e2e tests with Detox for iOS with Release configuration (Mac only)
- `nx test-android frontend-e2e --prod`: to build the Android app and execute e2e tests with Detox for Android with release build type
- `nx build-ios frontend-e2e --prod`: build the iOS app using Release configuration (Mac only)
- `nx build-android frontend-e2e --prod`: build the Android app using release build type

## Configuration

### Using .detoxrc.json

If you need to fine tune your Detox setup, you can do so by modifying `.detoxrc.json` in the e2e project.

#### Change testing simulator/emulator

For iOS, in terminal, run `xcrun simctl list devices available` to view a list of simulators on your Mac. To open your active simulator, `run open -a simulator`. In `frontend-e2e/.detoxrc.json`, you could change the simulator under `devices.simulator.device`.

For Android, in terminal, run `emulator -list-avds` to view a list of emulators installed. To open your emulator, run `emulator -avd <your emulator name>`. In `frontend-e2e/.detoxrc.json`, you could change the simulator under `devices.emulator.device`.

In addition, to override the device name specified in a configuration, you could use `--device-name` option: `nx test-ios <app-name-e2e> --device-name "iPhone 11"`. The `device-name` property provides you the ability to test an application run on specific device.

```shell
nx test-ios frontend-e2e --device-name "iPhone 11"
nx test-android frontend-e2e --device-name "Pixel_4a_API_30"
```

---
<!-- source: https://nx.dev/docs/technologies/test-tools/detox/migrations.md -->
## @nx/detox Migrations

The @nx/detox plugin provides various migrations to help you migrate to newer versions of detox projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 22.2.x

### `update-22-0-0-remove-config-plugins-detox-for-expo-54`
**Version**: 22.2.0-beta.2

Remove @config-plugins/detox for Expo 54+ projects (package discontinued)

#### Requires

| Name | Version |
|------|---------|
 `expo` | `>= 54.0.0` |


## 22.0.x

### 22.0.0-package-updates
**Version**: 22.0.0-beta.5


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `detox` | `~20.43.0` | Updated only
| `@config-plugins/detox` | `~11.0.0` | Updated only
| `@testing-library/jest-dom` | `~6.9.1` | Updated only



## 20.4.x

### 20.4.0-package-updates
**Version**: 20.4.0-beta.2


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `detox` | `~20.31.0` | Updated only
| `@config-plugins/detox` | `~9.0.0` | Updated only



## 20.3.x

### 20.3.0-package-updates
**Version**: 20.3.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `detox` | `~20.28.0` | Updated only
| `@testing-library/jest-dom` | `~6.6.3` | Updated only

---
<!-- source: https://nx.dev/docs/technologies/test-tools/jest.md -->
## Jest

{% index_page_cards path="technologies/test-tools/jest" /%}

---
<!-- source: https://nx.dev/docs/technologies/test-tools/jest/executors.md -->
## @nx/jest Executors

The @nx/jest plugin provides various executors to help you create and configure jest projects within your Nx workspace.
Below is a complete reference for all available executors and their options.

### `jest`
Jest target options for Build Facade.

Jest can be configured in many ways, but primarily you'll need to at least have the jestConfig options

```json
"test": {
  "executor": "@nx/jest:jest",
  "options": {
    "jestConfig": "libs/my-lib/jest.config.ts"
  }
}
```

It is also helpful to have `passWithNoTests: true` set so your project doesn't fail testing while tests are still being added.

```json
"test": {
  "executor": "@nx/jest:jest",
  "options": {
    "jestConfig": "libs/my-lib/jest.config.ts",
    "passWithNoTests": true
  }
}
```

#### Snapshots

Update snapshots running with `--update-snapshot` or `-u` for short.

```bash
nx test my-project -u
```

Other times you might not want to allow updating snapshots such as in CI.
Adding a _ci_ configuration is helpful for adding this behavior.

```json
"test": {
  "executor": "@nx/jest:jest",
  "options": {
    "jestConfig": "libs/my-lib/jest.config.ts",
    "passWithNoTests": true
  },
  "configurations": {
    "ci": {
      "ci": true
    }
  }
}
```

```bash
nx affected --target=test
```

Learn more [about _affected_](/ci/features/affected)
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `jestConfig` | string [**required**] | The path of the Jest configuration. (https://jestjs.io/docs/en/configuration) |  |
| `bail` | string | Exit the test suite immediately after `n` number of failing tests. (https://jestjs.io/docs/cli#--bail) |  |
| `changedSince` | string | Runs tests related to the changes since the provided branch or commit hash. If the current branch has diverged from the given branch, then only changes made locally will be tested. (https://jestjs.io/docs/cli#--changedsince) |  |
| `ci` | boolean | Whether to run Jest in continuous integration (CI) mode. This option is on by default in most popular CI environments. It will prevent snapshots from being written unless explicitly requested. (https://jestjs.io/docs/cli#--ci) |  |
| `clearCache` | boolean | Deletes the Jest cache directory and then exits without running tests. Will delete Jest's default cache directory. _Note: clearing the cache will reduce performance_. |  |
| `codeCoverage` | boolean | Indicates that test coverage information should be collected and reported in the output. (https://jestjs.io/docs/cli#--coverageboolean) |  |
| `color` | boolean | Forces test results output color highlighting (even if `stdout` is not a TTY). Set to false if you would like to have no colors. (https://jestjs.io/docs/cli#--colors) |  |
| `colors` | boolean | Forces test results output highlighting even if stdout is not a TTY. (https://jestjs.io/docs/cli#--colors) |  |
| `config` | string | The path to a Jest config file specifying how to find and execute tests. If no `rootDir` is set in the config, the directory containing the config file is assumed to be the `rootDir` for the project. This can also be a JSON-encoded value which Jest will use as configuration. |  |
| `coverageDirectory` | string | The directory where Jest should output its coverage files. |  |
| `coverageReporters` | array | A list of reporter names that Jest uses when writing coverage reports. Any istanbul reporter. |  |
| `detectLeaks` | boolean | **EXPERIMENTAL**: Detect memory leaks in tests. After executing a test, it will try to garbage collect the global object used, and fail if it was leaked |  |
| `detectOpenHandles` | boolean | Attempt to collect and print open handles preventing Jest from exiting cleanly (https://jestjs.io/docs/cli#--detectopenhandles) |  |
| `findRelatedTests` | string | Find and run the tests that cover a comma separated list of source files that were passed in as arguments. (https://jestjs.io/docs/cli#--findrelatedtests-spaceseparatedlistofsourcefiles) |  |
| `forceExit` | boolean | Force Jest to exit after all tests have completed running. This is useful when resources set up by test code cannot be adequately cleaned up.This feature is an escape-hatch. If Jest doesn't exit at the end of a test run, it means external resources are still being held on to or timers are still pending in your code. It is advised to tear down external resources after each test to make sure Jest can shut down cleanly. You can use --detectOpenHandles to help track it down. |  |
| `json` | boolean | Prints the test results in `JSON`. This mode will send all other test output and user messages to `stderr`. (https://jestjs.io/docs/cli#--json) |  |
| `logHeapUsage` | boolean | Logs the heap usage after every test. Useful to debug memory leaks. Use together with --runInBand and --expose-gc in node. |  |
| `maxWorkers` | string | Specifies the maximum number of workers the worker-pool will spawn for running tests. This defaults to the number of the cores available on your machine. Useful for CI. (its usually best not to override this default) (https://jestjs.io/docs/cli#--maxworkersnumstring) |  |
| `onlyChanged` | boolean | Attempts to identify which tests to run based on which files have changed in the current repository. Only works if you're running tests in a `git` or `hg` repository at the moment. (https://jestjs.io/docs/cli#--onlychanged) |  |
| `outputFile` | string | Write test results to a file when the `--json` option is also specified. (https://jestjs.io/docs/cli#--outputfilefilename) |  |
| `passWithNoTests` | boolean | Will not fail if no tests are found (for example while using `--testPathPatterns`.) (https://jestjs.io/docs/cli#--passwithnotests) |  |
| `randomize` | boolean | Shuffle the order of the tests within a file. The shuffling is based on the seed. This option is only supported using the default jest-circus test runner. |  |
| `reporters` | array | Run tests with specified reporters. Reporter options are not available via CLI. Example with multiple reporters: `jest --reporters="default" --reporters="jest-junit"`. (https://jestjs.io/docs/cli#--reporters) |  |
| `runInBand` | boolean | Run all tests serially in the current process (rather than creating a worker pool of child processes that run tests). This is sometimes useful for debugging, but such use cases are pretty rare. Useful for CI. (https://jestjs.io/docs/cli#--runinband) |  |
| `setupFile` | string | The name of a setup file used by Jest. |  |
| `showConfig` | boolean | Print your Jest config and then exits. (https://jestjs.io/docs/en/cli#--showconfig) |  |
| `silent` | boolean | Prevent tests from printing messages through the console. (https://jestjs.io/docs/cli#--silent) |  |
| `testFile` | string | The name of the file to test. | From command line |
| `testLocationInResults` | boolean | Adds a location field to test results.  Used to report location of a test in a reporter. { "column": 4, "line": 5 } (https://jestjs.io/docs/cli#--testlocationinresults) |  |
| `testNamePattern` | string | Run only tests with a name that matches the regex pattern. (https://jestjs.io/docs/cli#--testnamepatternregex) |  |
| `testPathIgnorePatterns` | array | An array of regexp pattern strings that is matched against all tests paths before executing the test. Only run those tests with a path that does not match with the provided regexp expressions. (https://jestjs.io/docs/cli#--testpathignorepatternsregexarray) |  |
| `testPathPatterns` | array | An array of regexp pattern strings that is matched against all tests paths before executing the test. (https://jestjs.io/docs/cli#--testpathpatternsregex) | `[]` |
| `testResultsProcessor` | string | Node module that implements a custom results processor. (https://jestjs.io/docs/en/configuration#testresultsprocessor-string) |  |
| `testTimeout` | number | Default timeout of a test in milliseconds. Default value: `5000`. (https://jestjs.io/docs/cli#--testtimeoutnumber) |  |
| `tsConfig` | string | The path to the TypeScript configuration file, relative to the workspace root. Note this is only metadata used by Angular migrations. This executor does not use it. |  |
| `updateSnapshot` | boolean | Use this flag to re-record snapshots. Can be used together with a test suite pattern or with `--testNamePattern` to re-record snapshot for test matching the pattern. (https://jestjs.io/docs/cli#--updatesnapshot) |  |
| `useStderr` | boolean | Divert all output to stderr. |  |
| `verbose` | boolean | Display individual test results with the test suite hierarchy. (https://jestjs.io/docs/cli#--verbose) |  |
| `watch` | boolean | Watch files for changes and rerun tests related to changed files. If you want to re-run all tests when a file has changed, use the `--watchAll` option. (https://jestjs.io/docs/cli#--watch) |  |
| `watchAll` | boolean | Watch files for changes and rerun all tests when something changes. If you want to re-run only the tests that depend on the changed files, use the `--watch` option. (https://jestjs.io/docs/cli#--watchall) |  |

---
<!-- source: https://nx.dev/docs/technologies/test-tools/jest/generators.md -->
## @nx/jest Generators

The @nx/jest plugin provides various generators to help you create and configure jest projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `convert-to-inferred`
Convert existing Jest project(s) using `@nx/jest:jest` executor to use `@nx/jest/plugin`.

**Usage:**
```bash
nx generate @nx/jest:convert-to-inferred [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string | The project to convert from using the `@nx/jest:jest` executor to use `@nx/jest/plugin`. If not provided, all projects using the `@nx/jest:jest` executor will be converted. |  |
| `--skipFormat` | boolean | Whether to format files. | `false` |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/jest:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/test-tools/jest/introduction.md -->
## Jest Plugin for Nx

[Jest](https://jestjs.io) is a JavaScript testing framework.

The `@nx/jest` plugin adds [inferred Jest targets](#configuration), a [Jest configuration generator](#add-jest-to-a-project), and CI-ready [test splitting](#unit-and-e2e-configurations).

You can use Jest with Nx without the plugin and still get [task caching](/docs/features/cache-task-results), [task orchestration](/docs/features/run-tasks), and the [project graph](/docs/features/explore-graph).

## Requirements

The `@nx/jest` plugin supports the following package versions.

| Package | Supported Versions   |
| ------- | -------------------- |
| `jest`  | ^29.0.0 \|\| ^30.0.0 |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

## Setup

### Add to an existing workspace

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/jest` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
Using `nx add` helps ensure the correct version is installed and configured.
{% /aside %}

```shell
nx add @nx/jest
```

Verify the inferred test target in the project details view:

```shell
nx show project my-app
```

### Add Jest to a project

Generate Jest configuration for an existing project:

```shell
nx g @nx/jest:configuration --project=my-app
```

Replace `my-app` with your project name.

The generator accepts framework-specific options. Pass the right flags for your project type:

{% tabs syncKey="framework" %}
{% tabitem label="React" %}

```shell
nx g @nx/jest:configuration --project=my-react-lib --supportTsx
```

Enables the JSX/TSX transform so Jest can process React components.

{% /tabitem %}
{% tabitem label="Angular" %}

```shell
nx g @nx/jest:configuration --project=my-angular-lib --setupFile=angular
```

Configures `jest-preset-angular` and keeps Angular snapshot serializers enabled.

{% /tabitem %}
{% tabitem label="Node / TypeScript" %}

```shell
nx g @nx/jest:configuration --project=my-node-lib --testEnvironment=node
```

Uses the `node` test environment instead of the default `jsdom`.

{% /tabitem %}
{% /tabs %}

See the full [configuration generator reference](/docs/technologies/test-tools/jest/generators#configuration) for all options.

{% aside type="tip" title="Framework generators handle this automatically" %}
When generating a new project with a framework generator, you can specify Jest as the test runner and Nx passes the correct options automatically:

```shell
nx g @nx/react:lib libs/my-react-lib --unitTestRunner=jest
nx g @nx/node:app apps/my-api --unitTestRunner=jest
```

{% /aside %}

## Local development

Run tests:

```shell
nx test my-app
```

Watch for changes:

```shell
nx test my-app --watch
```

Run a specific file (positional argument or `--testFile`):

```shell
nx test my-app ./path/to/spec/file/user-profile.spec.ts
nx test my-app --testFile user-profile.spec.ts
```

Collect coverage:

```shell
nx test my-app --coverage
```

Snapshot example:

```typescript
describe('userProfile', () => {
  it('matches the saved snapshot', () => {
    expect(renderUserProfile()).toMatchSnapshot();
  });
});
```

Update snapshots with `-u`/`--updateSnapshot` and check snapshot files into source control.

## Configuration

### Task inference

The `@nx/jest` plugin infers tasks for any project with a Jest configuration file:

- `jest.config.js`
- `jest.config.ts`
- `jest.config.mjs`
- `jest.config.mts`
- `jest.config.cjs`
- `jest.config.cts`

### Plugin options

Configure the plugin in `nx.json`:

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/jest/plugin",
      "options": {
        "targetName": "test"
      }
    }
  ]
}
```

| Option               | Type    | Default                        | Description                                                                                                                                                                                                      |
| -------------------- | ------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `targetName`         | string  | `test`                         | Name of the inferred Jest target.                                                                                                                                                                                |
| `ciTargetName`       | string  | none                           | Creates a CI-only target for atomized test tasks.                                                                                                                                                                |
| `ciGroupName`        | string  | none                           | Custom group name for atomized tasks in Nx Cloud/UI.                                                                                                                                                             |
| `disableJestRuntime` | boolean | `true`                         | When `true`, Nx skips creating the Jest runtime and computes inputs/outputs itself. Set to `false` to enable the Jest runtime.                                                                                   |
| `useJestResolver`    | boolean | `true` when runtime is enabled | Whether to use Jest's resolver for resolving config file references as task inputs. Follows symlinks and honors custom `moduleDirectories`/`modulePaths`. Faster path-based classification is used when `false`. |

`disableJestRuntime` defaults to `true` because the plugin treats it as enabled only when `options.disableJestRuntime !== false`. This reduces computation time for inferred tasks; set it to `false` if you need Jest runtime inference.

### Unit and e2e configurations

Use two plugin entries to separate unit and E2E Jest tasks, and enable CI splitting for E2E:

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/jest/plugin",
      "exclude": ["e2e/**/*"],
      "options": {
        "targetName": "test"
      }
    },
    {
      "plugin": "@nx/jest/plugin",
      "include": ["e2e/**/*"],
      "options": {
        "targetName": "e2e",
        "ciTargetName": "e2e-ci"
      }
    }
  ]
}
```

`ciTargetName` enables [split E2E tasks](/docs/features/ci-features/split-e2e-tasks) so each test file runs as its own CI task with better caching and retries. Use `ciGroupName` if you want a custom group label.

### View inferred tasks

Open the project details view in Nx Console or run:

```shell
nx show project my-app
```

## CI considerations

See [Set Up CI](/docs/guides/nx-cloud/setup-ci) for a complete CI configuration guide.

### Build and test only what changed

```shell
nx affected -t build test typecheck lint
```

This uses the [project graph](/docs/features/explore-graph) to determine which projects are affected by your changes and only runs tasks for those.
Read more about [the benefits of `nx affected`](/docs/features/ci-features/affected).

### Remote caching

Share build and typecheck cache results across your team and CI with [remote caching](/docs/features/ci-features/remote-cache):

```shell
nx connect
```

### Task splitting for slow tests

For slow test suites (e.g. E2E or integration tests), set `ciTargetName` to split tests by file for distributed CI runs. Each test file becomes its own cacheable CI task with better caching and retries. See [split e2e tasks](/docs/features/ci-features/split-e2e-tasks) for details.

### Feature-based testing

Organize tests by feature to get better cache hits and more targeted CI runs. See the [feature-based testing guide](/docs/guides/tips-n-tricks/feature-based-testing) for strategies on structuring tests in a monorepo.

### Performance with parallelization

Typically, in CI it's recommended to use `nx affected -t test --parallel=[# CPUs] --runInBand` for the best performance.

This is because each Jest process creates workers based on system resources, and running multiple projects via Nx with Jest workers will create too many processes overall, causing the system to run slower than desired. Using the `--runInBand` flag tells Jest to run in a single process. You can then use Nx parallelism to run multiple Jest projects at once.

### Batch mode

For large monorepos with many Jest projects, Batch mode can improve performance by batching compilation across projects into a single process.

```shell
NX_BATCH_MODE=true nx run-many -t test
```

## What's next

{% cardgrid %}
{% linkcard title="Jest Configuration" description="Explore all Jest configuration options." href="https://jestjs.io/docs/configuration" /%}
{% linkcard title="Snapshot Testing" description="Learn how Jest snapshot testing works and when to use it." href="https://jestjs.io/docs/snapshot-testing" /%}
{% linkcard title="Split E2E Tasks" description="Distribute E2E tests across CI for better caching and retries." href="/docs/features/ci-features/split-e2e-tasks" /%}
{% linkcard title="Feature-Based Testing" description="Organize tests by feature for better caching and targeted CI." href="/docs/guides/tips-n-tricks/feature-based-testing" /%}
{% linkcard title="Jest Generators Reference" description="Full API reference for @nx/jest generators." href="/docs/technologies/test-tools/jest/generators" /%}
{% linkcard title="Jest Executors Reference" description="Full API reference for @nx/jest executors." href="/docs/technologies/test-tools/jest/executors" /%}
{% /cardgrid %}

---
<!-- source: https://nx.dev/docs/technologies/test-tools/jest/migrations.md -->
## @nx/jest Migrations

The @nx/jest plugin provides various migrations to help you migrate to newer versions of jest projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 22.3.x

### `replace-removed-matcher-aliases-v22-3`
**Version**: 22.3.2-beta.0

Replace removed matcher aliases in Jest v30 with their corresponding matcher

#### Requires

| Name | Version |
|------|---------|
 `jest` | `>=30.0.0` |
#### Replace Removed Matcher Aliases

Replaces removed Jest matcher aliases in test files with their corresponding matchers to align with Jest v30 changes. Read more at the [Jest v30 migration notes](https://jestjs.io/docs/upgrading-to-jest30#jest-expect--matchers).

#### Examples

##### Before

```typescript title="apps/myapp/src/app.spec.ts"
describe('test', () => {
  it('should pass', async () => {
    expect(mockFn).toBeCalled();
    expect(mockFn).toBeCalledTimes(1);
    expect(mockFn).toBeCalledWith(arg);
    expect(mockFn).lastCalledWith(arg);
    expect(mockFn).nthCalledWith(1, arg);
    expect(mockFn).toReturn();
    expect(mockFn).toReturnTimes(1);
    expect(mockFn).toReturnWith(value);
    expect(mockFn).lastReturnedWith(value);
    expect(mockFn).nthReturnedWith(1, value);
    expect(() => someFn()).toThrowError();
    expect(() => someFn()).not.toThrowError();
    await expect(someAsyncFn()).rejects.toThrowError();
    await expect(someAsyncFn()).resolves.not.toThrowError();
  });
});
```

##### After

```typescript title="apps/myapp/src/app.spec.ts"
describe('test', () => {
  it('should pass', async () => {
    expect(mockFn).toHaveBeenCalled();
    expect(mockFn).toHaveBeenCalledTimes(1);
    expect(mockFn).toHaveBeenCalledWith(arg);
    expect(mockFn).toHaveBeenLastCalledWith(arg);
    expect(mockFn).toHaveBeenNthCalledWith(1, arg);
    expect(mockFn).toHaveReturned();
    expect(mockFn).toHaveReturnedTimes(1);
    expect(mockFn).toHaveReturnedWith(value);
    expect(mockFn).toHaveLastReturnedWith(value);
    expect(mockFn).toHaveNthReturnedWith(1, value);
    expect(() => someFn()).toThrow();
    expect(() => someFn()).not.toThrow();
    await expect(someAsyncFn()).rejects.toThrow();
    await expect(someAsyncFn()).resolves.not.toThrow();
  });
});
```



### 22.3.0-package-updates
**Version**: 22.3.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `jest` | `^30.0.0` | Updated only
| `@types/jest` | `^30.0.0` | Updated only
| `expect` | `^30.0.0` | Updated only
| `@jest/globals` | `^30.0.0` | Updated only
| `jest-jasmine2` | `^30.0.0` | Updated only
| `jest-environment-jsdom` | `^30.0.0` | Updated only
| `jest-util` | `^30.0.0` | Updated only
| `babel-jest` | `^30.0.0` | Updated only
| `@swc/jest` | `~0.2.38` | Updated only


### 22.3.0-jest-preset-angular-package-updates
**Version**: 22.3.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `jest-preset-angular` | `~16.0.0` | Updated only



## 22.2.x

### `convert-jest-config-to-cjs`
**Version**: 22.2.0-beta.2

Convert jest.config.ts files from ESM to CJS syntax (export default -> module.exports, import -> require) for projects using CommonJS resolution to ensure correct loading under Node.js type-stripping.

#### Convert Jest Config to CJS

Converts `jest.config.ts` files to `jest.config.cts`. This is needed because Node.js type-stripping in newer versions (22+, 24+) can cause issues with ESM syntax in `.ts` files when the project is configured for CommonJS.

This migration only runs if `@nx/jest/plugin` is registered in `nx.json`.

#### Examples

##### Before

```typescript title="jest.config.ts"
import { foo } from 'bar';
import baz from 'qux';

export default {
  displayName: 'myapp',
  preset: foo,
  transform: baz,
};
```

##### After

```typescript title="jest.config.cts"
const { foo } = require('bar');
const baz = require('qux').default ?? require('qux');

module.exports = {
  displayName: 'myapp',
  preset: foo,
  transform: baz,
};
```




## 21.3.x

### `rename-test-path-pattern`
**Version**: 21.3.0-beta.3

Rename the CLI option `testPathPattern` to `testPathPatterns`.

#### Rename `testPathPattern` to `testPathPatterns`

Renames the `testPathPattern` option to `testPathPatterns` in the `@nx/jest:jest` executor configuration to align with Jest v30 CLI changes. Read more at the [Jest v30 migration notes](https://jestjs.io/docs/upgrading-to-jest30#--testpathpattern-was-renamed-to---testpathpatterns).

#### Examples

Rename the option in project configuration:

##### Before

```json title="apps/myapp/project.json" {7}
{
  "targets": {
    "test": {
      "executor": "@nx/jest:jest",
      "options": {
        "jestConfig": "apps/myapp/jest.config.ts",
        "testPathPattern": "some-regex"
      }
    }
  }
}
```

##### After

```json title="apps/myapp/project.json" {7}
{
  "targets": {
    "test": {
      "executor": "@nx/jest:jest",
      "options": {
        "jestConfig": "apps/myapp/jest.config.ts",
        "testPathPatterns": "some-regex"
      }
    }
  }
}
```

Rename the option in project configuration with configurations:

##### Before

```json title="apps/myapp/project.json" {7,10,11}
{
  "targets": {
    "test": {
      "executor": "@nx/jest:jest",
      "options": {
        "jestConfig": "apps/myapp/jest.config.ts",
        "testPathPattern": "some-regex"
      },
      "configurations": {
        "development": { "testPathPattern": "regex-dev" },
        "production": { "testPathPattern": "regex-prod" }
      }
    }
  }
}
```

##### After

```json title="apps/myapp/project.json" {7,10,11}
{
  "targets": {
    "test": {
      "executor": "@nx/jest:jest",
      "options": {
        "jestConfig": "apps/myapp/jest.config.ts",
        "testPathPatterns": "some-regex"
      },
      "configurations": {
        "development": { "testPathPatterns": "regex-dev" },
        "production": { "testPathPatterns": "regex-prod" }
      }
    }
  }
}
```

Rename the option in a target default using the `@nx/jest:jest` executor:

##### Before

```json title="nx.json" {7}
{
  "targetDefaults": {
    "test": {
      "executor": "@nx/jest:jest",
      "options": {
        "jestConfig": "{projectRoot}/jest.config.ts",
        "testPathPattern": "some-regex"
      }
    }
  }
}
```

##### After

```json title="nx.json" {7}
{
  "targetDefaults": {
    "test": {
      "executor": "@nx/jest:jest",
      "options": {
        "jestConfig": "{projectRoot}/jest.config.ts",
        "testPathPatterns": "some-regex"
      }
    }
  }
}
```

Rename the option in a target default using the `@nx/jest:jest` executor as the key:

##### Before

```json title="nx.json" {6}
{
  "targetDefaults": {
    "@nx/jest:jest": {
      "options": {
        "jestConfig": "{projectRoot}/jest.config.ts",
        "testPathPattern": "some-regex"
      }
    }
  }
}
```

##### After

```json title="nx.json" {6}
{
  "targetDefaults": {
    "@nx/jest:jest": {
      "options": {
        "jestConfig": "{projectRoot}/jest.config.ts",
        "testPathPatterns": "some-regex"
      }
    }
  }
}
```



### `replace-removed-matcher-aliases`
**Version**: 21.3.0-beta.3

Replace removed matcher aliases in Jest v30 with their corresponding matcher

#### Requires

| Name | Version |
|------|---------|
 `jest` | `>=30.0.0` |
#### Replace Removed Matcher Aliases

Replaces removed Jest matcher aliases in test files with their corresponding matchers to align with Jest v30 changes. Read more at the [Jest v30 migration notes](https://jestjs.io/docs/upgrading-to-jest30#jest-expect--matchers).

#### Examples

##### Before

```typescript title="apps/myapp/src/app.spec.ts"
describe('test', () => {
  it('should pass', async () => {
    expect(mockFn).toBeCalled();
    expect(mockFn).toBeCalledTimes(1);
    expect(mockFn).toBeCalledWith(arg);
    expect(mockFn).lastCalledWith(arg);
    expect(mockFn).nthCalledWith(1, arg);
    expect(mockFn).toReturn();
    expect(mockFn).toReturnTimes(1);
    expect(mockFn).toReturnWith(value);
    expect(mockFn).lastReturnedWith(value);
    expect(mockFn).nthReturnedWith(1, value);
    expect(() => someFn()).toThrowError();
    expect(() => someFn()).not.toThrowError();
    await expect(someAsyncFn()).rejects.toThrowError();
    await expect(someAsyncFn()).resolves.not.toThrowError();
  });
});
```

##### After

```typescript title="apps/myapp/src/app.spec.ts"
describe('test', () => {
  it('should pass', async () => {
    expect(mockFn).toHaveBeenCalled();
    expect(mockFn).toHaveBeenCalledTimes(1);
    expect(mockFn).toHaveBeenCalledWith(arg);
    expect(mockFn).toHaveBeenLastCalledWith(arg);
    expect(mockFn).toHaveBeenNthCalledWith(1, arg);
    expect(mockFn).toHaveReturned();
    expect(mockFn).toHaveReturnedTimes(1);
    expect(mockFn).toHaveReturnedWith(value);
    expect(mockFn).toHaveLastReturnedWith(value);
    expect(mockFn).toHaveNthReturnedWith(1, value);
    expect(() => someFn()).toThrow();
    expect(() => someFn()).not.toThrow();
    await expect(someAsyncFn()).rejects.toThrow();
    await expect(someAsyncFn()).resolves.not.toThrow();
  });
});
```



### 21.3.0-package-updates
**Version**: 21.3.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `jest` | `~30.0.0` | Updated only
| `@types/jest` | `~30.0.0` | Updated only
| `expect` | `~30.0.0` | Updated only
| `@jest/globals` | `~30.0.0` | Updated only
| `jest-jasmine2` | `~30.0.0` | Updated only
| `jest-environment-jsdom` | `~30.0.0` | Updated only
| `babel-jest` | `~30.0.0` | Updated only
| `@swc/jest` | `~0.2.38` | Updated only


### 21.3.3-package-updates
**Version**: 21.3.3-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `ts-jest` | `~29.4.0` | Updated only


### 21.3.3-jest-util-package-updates
**Version**: 21.3.3-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `jest-util` | `~30.0.0` | Updated only



## 21.0.x

### `replace-getJestProjects-with-getJestProjectsAsync-v21`
**Version**: 21.0.0-beta.9

Replace usage of `getJestProjects` with `getJestProjectsAsync`.

#### Replace Usage of `getJestProjects` with `getJestProjectsAsync`

Replaces the usage of the removed `getJestProjects` function with the `getJestProjectsAsync` function.

#### Sample Code Changes

##### Before

```ts title="jest.config.ts"
import { getJestProjects } from '@nx/jest';

export default {
  projects: getJestProjects(),
};
```

##### After

```ts title="jest.config.ts"
import { getJestProjectsAsync } from '@nx/jest';

export default async () => ({
  projects: await getJestProjectsAsync(),
});
```



### `remove-tsconfig-option-from-jest-executor`
**Version**: 21.0.0-beta.10

Remove the previously deprecated and unused `tsConfig` option from the `@nx/jest:jest` executor.

#### Remove `tsConfig` Option from Jest Executor

Removes the previously deprecated and unused `tsConfig` option from the `@nx/jest:jest` executor configuration in all projects.

#### Examples

Remove the option from the project configuration:

##### Before

```json title="apps/myapp/project.json" {7}
{
  "targets": {
    "test": {
      "executor": "@nx/jest:jest",
      "options": {
        "jestConfig": "apps/myapp/jest.config.ts",
        "tsConfig": "apps/myapp/tsconfig.spec.json"
      }
    }
  }
}
```

##### After

```json title="apps/myapp/project.json"
{
  "targets": {
    "test": {
      "executor": "@nx/jest:jest",
      "options": {
        "jestConfig": "apps/myapp/jest.config.ts"
      }
    }
  }
}
```

Remove the option from a target default using the `@nx/jest:jest` executor:

##### Before

```json title="nx.json" {7}
{
  "targetDefaults": {
    "test": {
      "executor": "@nx/jest:jest",
      "options": {
        "jestConfig": "{projectRoot}/jest.config.ts",
        "tsConfig": "{projectRoot}/tsconfig.spec.json"
      }
    }
  }
}
```

##### After

```json title="nx.json"
{
  "targetDefaults": {
    "test": {
      "executor": "@nx/jest:jest",
      "options": {
        "jestConfig": "{projectRoot}/jest.config.ts"
      }
    }
  }
}
```

Remove the option from a target default using the `@nx/jest:jest` executor as the key:

##### Before

```json title="nx.json" {6}
{
  "targetDefaults": {
    "@nx/jest:jest": {
      "options": {
        "jestConfig": "{projectRoot}/jest.config.ts",
        "tsConfig": "{projectRoot}/tsconfig.spec.json"
      }
    }
  }
}
```

##### After

```json title="nx.json"
{
  "targetDefaults": {
    "@nx/jest:jest": {
      "options": {
        "jestConfig": "{projectRoot}/jest.config.ts"
      }
    }
  }
}
```




## 20.0.x

### `replace-getJestProjects-with-getJestProjectsAsync`
**Version**: 20.0.0-beta.5

Replace usage of `getJestProjects` with `getJestProjectsAsync`.

#### Replace Usage of `getJestProjects` with `getJestProjectsAsync`

Replaces the usage of the deprecated `getJestProjects` function with the `getJestProjectsAsync` function.

#### Sample Code Changes

##### Before

```ts title="jest.config.ts"
import { getJestProjects } from '@nx/jest';

export default {
  projects: getJestProjects(),
};
```

##### After

```ts title="jest.config.ts"
import { getJestProjectsAsync } from '@nx/jest';

export default async () => ({
  projects: await getJestProjectsAsync(),
});
```

---
<!-- source: https://nx.dev/docs/technologies/test-tools/playwright.md -->
## Playwright

{% index_page_cards path="technologies/test-tools/playwright" /%}

---
<!-- source: https://nx.dev/docs/technologies/test-tools/playwright/executors.md -->
## @nx/playwright Executors

The @nx/playwright plugin provides various executors to help you create and configure playwright projects within your Nx workspace.
Below is a complete reference for all available executors and their options.

### `playwright`
Run Playwright tests.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `browser` | string | Browser to use for tests, one of 'all', 'chromium', 'firefox' or 'webkit'. If a playwright config is provided/discovered then the browserName value is expected from the configured 'projects' |  |
| `cacheDir` | string | Directory for Playwright internal cache (browser binaries, etc.). Sets the PWTEST_CACHE_DIR environment variable. |  |
| `config` | string | Configuration file, or a test directory with optional |  |
| `debug` | boolean | Run tests with Playwright Inspector. Shortcut for 'PWDEBUG=1' environment variable and '--timeout=0',--max-failures=1 --headed --workers=1' options |  |
| `forbidOnly` | boolean | Fail if test.only is called |  |
| `fullyParallel` | boolean | Run all tests in parallel |  |
| `globalTimeout` | number | Maximum time this test suite can run in milliseconds |  |
| `grep` | string | Only run tests matching this regular expression |  |
| `grepInvert` | string | Only run tests that do not match this regular expression |  |
| `headed` | boolean | Run tests in headed browsers |  |
| `ignoreSnapshots` | boolean | Ignore screenshot and snapshot expectations |  |
| `lastFailed` | boolean | Run only the tests that failed in the last run |  |
| `list` | boolean | Collect all the tests and report them, but do not run |  |
| `maxFailures` | string | Stop after the first N failures |  |
| `noDeps` | boolean | Do not run project dependencies |  |
| `output` | string | Folder for output artifacts |  |
| `passWithNoTests` | boolean | Makes test run succeed even if no tests were found | `true` |
| `project` | array | Only run tests from the specified list of projects |  |
| `quiet` | boolean | Suppress stdio |  |
| `repeatEach` | number | Run each test N times |  |
| `reporter` | string | Common Reporter values to use, comma-separated, 'list', 'line', 'dot', 'json', 'junit', 'null', 'github', 'html', 'blob'. To configure reporter options, use the playwright configuration. |  |
| `retries` | number | Maximum retry count for flaky tests, zero for no retries |  |
| `shard` | string | Shard tests and execute only the selected shard, specify in the form 'current/all', 1-based, for example '3/5' |  |
| `skipInstall` | boolean | Skip running playwright install before running playwright tests. This is to ensure that playwright browsers are installed before running tests. | `false` |
| `testFiles` | array | Test files to run |  |
| `timeout` | number | Specify test timeout threshold in milliseconds, zero for unlimited |  |
| `trace` | string | Force tracing mode, can be 'on', 'off', 'on-first-retry', 'on-all-retries', 'retain-on-failure' |  |
| `ui` | boolean | Run tests in interactive UI mode |  |
| `uiHost` | string | Host to serve UI on; specifying this option opens UI in a browser tab |  |
| `uiPort` | number | Port to serve UI on, 0 for any free port; specifying this option opens UI in a browser tab |  |
| `updateSnapshots` | boolean | Update snapshots with actual results. Snapshots will be created if missing. |  |
| `workers` | string | Number of concurrent workers or percentage of logical CPU cores, use 1 to run in a single worker |  |

---
<!-- source: https://nx.dev/docs/technologies/test-tools/playwright/generators.md -->
## @nx/playwright Generators

The @nx/playwright plugin provides various generators to help you create and configure playwright projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `configuration`
Add a Playwright configuration.

**Usage:**
```bash
nx generate @nx/playwright:configuration [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string [**required**] | The project to add a Playwright configuration to. |  |
| `--directory` | string | A directory where the project is placed relative from the project root. | `"e2e"` |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. | `false` |
| `--linter` | string | The tool to use for running lint checks. |  |
| `--rootProject` | boolean | Create a application at the root of the workspace | `false` |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipInstall` | boolean | Skip running `playwright install`. This is to ensure that playwright browsers are installed. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--webServerAddress` | string | The address of the web server. |  |
| `--webServerCommand` | string | The command to start the web server. |  |

## `convert-to-inferred`
Convert existing Playwright project(s) using `@nx/playwright:playwright` executor to use `@nx/playwright/plugin`. Defaults to migrating all projects. Pass '--project' to migrate only one target.

**Usage:**
```bash
nx generate @nx/playwright:convert-to-inferred [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string | The project to convert from using the `@nx/playwright:playwright` executor to use `@nx/playwright/plugin`. |  |
| `--skipFormat` | boolean | Whether to format files at the end of the migration. | `false` |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/playwright:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/test-tools/playwright/guides.md -->
## Guides

{% index_page_cards path="technologies/test-tools/playwright/guides" /%}

---
<!-- source: https://nx.dev/docs/technologies/test-tools/playwright/guides/merge-atomized-outputs.md -->
## Merge Atomized Playwright Outputs

When running Playwright tests in CI environments, Nx can [split tests across multiple parallel tasks](/docs/features/ci-features/split-e2e-tasks) for faster execution.
However, this creates separate test reports for each task.
With the Nx Plugin, the Playwright report merging feature allows you to combine these individual reports into a single, unified report.

**Benefits:**

- View all test results in one consolidated report
- Maintain the same reporting experience as non-atomized tests
- Keep the performance benefits of parallel test execution

## Prerequisites

- Nx workspace with `@nx/playwright` plugin
- Playwright tests configured in your project
- CI environment with [task atomization enabled](/docs/features/ci-features/split-e2e-tasks)
- Nx v21.6.1

{% aside type="note" title="Nx Version"%}
Nx v21.6.1 introduced automatic configuration of report merging which is the focus of this guide.
Similar steps can be followed for manual configuration of Playwright for any versions prior to Nx v21.6.1
{%/aside%}

## How report merging works

1. **Blob Reports**: Playwright generates [lightweight "blob" reports](https://playwright.dev/docs/test-reporters#blob-reporter) during test execution
2. **Individual Tasks**: Each atomized test task creates its own blob report
3. **Report Merging**: A separate merge task combines all blob reports into unified output using your configured reporters (HTML, JSON, JUnit, etc.)

## Configuration

### Step 1: Enable blob reports

The `nxE2EPreset` from `@nx/playwright/preset` automatically enable the blob reporter when running in CI:

```ts
// playwright.config.ts
import { defineConfig } from '@playwright/test';
import { nxE2EPreset } from '@nx/playwright/preset';

export default defineConfig({
  // automatically uses the blob reporter for CI
  ...nxE2EPreset(__filename, { testDir: './src' }),
  // Your additional configuration
});
```

> The preset has a `generateBlobReports` option that can be used to disable the reporter or maybe enable it not just in CI.

**Alternative manual configuration:**

```ts
// playwright.config.ts
export default defineConfig({
  reporter: [
    ['html', { outputFolder: 'playwright-report' }],
    // NOTE: depending on your TS config, you might need to use `as const` to prevent type errors
    ...(process.env.CI
      ? [['blob', { outputDir: 'blob-report' }] as const]
      : []),
  ],
  // Your other configuration
});
```

### Step 2: Configure the Playwright plugin

Add a `ciTargetName` to the Playwright plugin to your `nx.json`. This will enable task splitting and report merging features for CI environments:

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/playwright/plugin",
      "options": {
        "targetName": "e2e",
        "ciTargetName": "e2e-ci"
      }
    }
  ]
}
```

With the above configurations, Nx automatically creates these targets for your Playwright projects:

- `e2e`: Regular target for local development (runs all tests together)
- `e2e-ci`: CI target that runs tests in parallel across multiple tasks
- `e2e-ci--merge-reports`: Target that merges blob reports into unified reports

## Running the feature

**Local Development:**

```shell
# Run tests normally (no blob reports generated)
nx run my-app:e2e
```

**CI Environment:**

```shell
# Run atomized tests (generates blob reports)
nx run my-app:e2e-ci

# Merge the reports
nx run my-app:e2e-ci--merge-reports
```

## Complete example

Here's a complete working example for reference:

```ts
// playwright.config.ts
import { defineConfig } from '@playwright/test';
import { nxE2EPreset } from '@nx/playwright/preset';

export default defineConfig({
  ...nxE2EPreset(__filename, { testDir: './e2e' }),
  use: {
    baseURL: 'http://localhost:4200',
  },
  webServer: {
    command: 'npm run start',
    port: 4200,
    reuseExistingServer: !process.env.CI,
  },
});
```

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/playwright/plugin",
      "options": {
        "targetName": "e2e",
        "ciTargetName": "e2e-ci"
      }
    }
  ]
}
```

## CI integration

> The following example CI configuration is for GitHub Actions, but the same steps can be followed in all CI providers.
> The most important part is to always call the merge report target, `e2e-ci--merge-reports`, even if the E2E tests fail to always have a final merged report.

```yaml
// .github/workflows/ci.yaml
name: CI
on:
  pull_request:

jobs:
  main:
    steps:
      ...
      - name: Run E2E Tests
        run: nx run my-app:e2e-ci

      - name: Merge Test Reports
        run: nx run my-app:e2e-ci--merge-reports
        # Run even if tests fail to get partial results
        if: always()
```

## Troubleshooting

### "The blob reporter is not configured"

**Problem:** The merge task warns that no blob reporter is configured.

**Solution:** Ensure the blob reporter is added to your Playwright configuration:

- If overriding the `reporter` in the Playwright configuration, make sure to add the blob reporter:

```ts
// playwright.config.ts
export default defineConfig({
  reporter: [
    // existing reporters
    ...(process.env.CI ? [['blob', { outputDir: 'blob-report' }]] : []),
  ],
  // Your other configuration
});
```

### Missing test results in report

**Problem:** The merge shows fewer results than expected test suites.

**Solution:**

- Check if some test tasks failed or were cancelled
- Verify all blob report files are present in the blob report directory
- Review CI logs for any task failures

### Reports not merging

**Problem:** Individual blob reports exist but aren't being merged.

**Solution:**

- Ensure the merge target is running after all test tasks complete
  - The default merge target name is `e2e-ci--merge-reports`
  - You can run `nx show project <e2e-project-name>` to view targets available on your project to verify the target exists
- Check that the blob report directory path is correct
- Verify Playwright CLI is available in the CI environment

### [WARNING] "No additional reporters are configured"

**Problem:** Only the blob reporter is configured, so it will be the only report produced

**Solution:** Add at least one additional reporter (HTML, JSON, JUnit, etc.) alongside the blob reporter.

List of available Playwright reports can be found in the [Playwright documentation](https://playwright.dev/docs/test-reporters).

## Best practices

1. **Environment-based Configuration**: Only enable blob reports in CI to avoid overhead during local development
2. **Error Handling**: Use `if: always()` (or similar) in CI workflows to merge partial results even when some tests fail
3. **Output Artifacts**: Archive both blob reports and merged reports as CI artifacts for debugging
4. **Validation**: The merge task automatically validates the expected number of test results

---
<!-- source: https://nx.dev/docs/technologies/test-tools/playwright/introduction.md -->
## Playwright Plugin for Nx

Playwright is a modern web test runner. With included features such as:

- Cross browser support, including mobile browsers
- Multi tab, origin, and user support
- Automatic waiting
- Test generation
- Screenshots and videos

## Requirements

The `@nx/playwright` plugin supports the following package versions.

| Package            | Supported Versions |
| ------------------ | ------------------ |
| `@playwright/test` | ^1.36.0            |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

## Setting up @nx/playwright

### Installation

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/playwright` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
{% /aside %}

In any Nx workspace, you can install `@nx/playwright` by running the following command:

```shell
nx add @nx/playwright
```

This will install the correct version of `@nx/playwright`.

### How @nx/playwright infers tasks

The `@nx/playwright` plugin will create a task for any project that has a Playwright configuration file present. Any of the following files will be recognized as a Playwright configuration file:

- `playwright.config.js`
- `playwright.config.ts`
- `playwright.config.mjs`
- `playwright.config.mts`
- `playwright.config.cjs`
- `playwright.config.cts`

### View inferred tasks

To view inferred tasks for a project, open the [project details view](/docs/concepts/inferred-tasks) in Nx Console or run `nx show project my-project --web` in the command line.

### @nx/playwright configuration

The `@nx/playwright/plugin` is configured in the `plugins` array in `nx.json`.

```json frame="none"
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/playwright/plugin",
      "options": {
        "ciTargetName": "e2e-ci",
        "targetName": "e2e"
      }
    }
  ]
}
```

The `targetName` and `ciTargetName` options control the name of the inferred Playwright tasks. The default names are `e2e` and `e2e-ci`.

### Splitting E2E tests

`@nx/playwright/plugin` uses Nx Atomizer to automatically split your e2e tests into smaller tasks for more efficient distribution in CI. Read more about the [Atomizer feature](/docs/features/ci-features/split-e2e-tasks).

If you would like to disable Atomizer for Playwright tasks, set `ciTargetName` to `false`.

## E2E testing

By default, when creating a new frontend application, Nx will prompt for which e2e test runner to use. Select `playwright` or pass in the arg `--e2eTestRunner=playwright`

```shell
nx g @nx/web:app apps/frontend --e2eTestRunner=playwright
```

### Add Playwright e2e to an existing project

To generate an E2E project for an existing project, run the following generator

```shell
nx g @nx/playwright:configuration --project=your-app-name
```

Optionally, you can use the `--webServerCommand` and `--webServerAddress` option, to auto setup the [web server option](https://playwright.dev/docs/test-webserver) in the playwright config

```shell
nx g @nx/playwright:configuration --project=your-app-name --webServerCommand="npx serve your-project-name" --webServerAddress="http://localhost:4200"
```

### Testing applications

Run `nx e2e <your-app-name>` to execute e2e tests with Playwright

{% aside type="note" title="Selecting Specific Specs" %}

You can use the `--grep/-g` flag to filter tests using regular expressions.
You can use the `--grepInvert/-gv` flag to filter out tests that match the regular expression.

```bash frame="none"
# run tests that match the regular expression
nx e2e frontend-e2e --grep="feat-a"

# run tests that don't match the regular expression
nx e2e frontend-e2e --grepInvert="feat-a"
```

{% /aside %}

By default, Playwright will run in headless mode. You will have the result of all the tests and errors (if any) in your
terminal. Test output such as reports, screenshots and videos, will be accessible in `dist/.playwright/apps/<your-app-name>/`. This can be configured with the `outputDir` configuration options.

{% aside type="note" title="Output Caching" %}
If changing the output directory or report output, make sure to update the [target outputs](/docs/concepts/how-caching-works#what-is-cached) so the artifacts are correctly cached
{% /aside %}

### Watching for changes

With, `nx e2e frontend-e2e --ui` Playwright will start in headed mode where you can see your application being tested.

From, there you can toggle on the watch icon which will rerun the tests when the spec file updates.

```shell
nx e2e <your-app-name> --ui
```

You can also use `--headed` flag to run Playwright where the browser can be seen without using the [Playwright UI](https://playwright.dev/docs/test-ui-mode)

### Specifying a project/target browser

The default generated Playwright configuration will contain a `projects` property that contains a list of browsers to run the tests against.

It should look similar to this:

```ts frame="none"
export default defineConfig({
  ...,
  projects: [
    {
      name: "chromium",
      use: { ...devices["Desktop Chrome"] },
    },

    {
      name: "firefox",
      use: { ...devices["Desktop Firefox"] },
    },

    {
      name: "webkit",
      use: { ...devices["Desktop Safari"] },
    }
  ]
});
```

By default, Playwright will run tests against all browsers in the `projects` list.

You can specify a specific browser to run the tests against by passing the `--project` flag to the `nx e2e` command.

```shell
nx e2e frontend-e2e -- --project=firefox
```

{% aside type="note" title="Argument Forwarding" %}
As Nx also has a `--project` argument, you need to use `--` to forward the argument to the Playwright configuration.
{% /aside %}

### Specifying a base url

The `baseURL` property within the Playwright configuration can control where the tests visit by default.

```ts frame="none"
import { defineConfig } from '@playwright/test';

export default defineConfig({
  // Rest of your config...

  // Run your local dev server before starting the tests
  webServer: {
    command: 'npx serve <your-app-name>',
    url: 'http://localhost:4200',
    reuseExistingServer: !process.env.CI,
  },
  use: {
    baseURL: 'http://localhost:4200', // url playwright visits with `await page.goto('/')`;
  },
});
```

In order to set different `baseURL` values for different environments you can pass them via the [environment variables and nx configurations](/docs/guides/tips-n-tricks/define-environment-variables) or optionally via setting them per the environment they are needed in such as `CI`

```ts frame="none"
import { defineConfig } from '@playwright/test';

const baseUrl =
  (process.env.BASE_URL ?? process.env.CI)
    ? 'https://some-staging-url.example.com'
    : 'http://localhost:4200';

export default defineConfig({
  // Rest of your config...

  // Run your local dev server before starting the tests
  webServer: {
    command: 'npx serve <your-app-name>',
    url: baseUrl,
    reuseExistingServer: !process.env.CI,
  },
  use: {
    baseURL: baseUrl, // url playwright visits with `await page.goto('/')`;
  },
});
```

By default Nx, provides a `nxE2EPreset` with predefined configuration for Playwright.

```ts frame="none"
import { defineConfig } from '@playwright/test';
import { nxE2EPreset } from '@nx/playwright/preset';
import { workspaceRoot } from '@nx/devkit';

// For CI, you may want to set BASE_URL to the deployed application.
const baseURL = process.env['BASE_URL'] || 'http://localhost:4200';

/**
 * Read environment variables from file.
 * https://github.com/motdotla/dotenv
 */
// require('dotenv').config();

/**
 * See https://playwright.dev/docs/test-configuration.
 */
export default defineConfig({
  ...nxE2EPreset(__filename, { testDir: './e2e' }),
  /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
  use: {
    baseURL,
    /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
    trace: 'on-first-retry',
  },
  /* Run your local dev server before starting the tests */
  webServer: {
    command: 'npx nx serve <your-app-name>',
    url: baseURL,
    reuseExistingServer: !process.env.CI,
    cwd: workspaceRoot,
  },
});
```

This preset sets up the `outputDir` and [HTML reporter](https://playwright.dev/docs/test-reporters#html-reporter) to output in `dist/.playwright/<path-to-project-root>` and sets up chromium, firefox, webkit browsers to be used a browser targets. If you want to use mobile and/or branded browsers you can pass those options into the preset function

```ts frame="none"
export default defineConfig({
  ...nxE2EPreset(__filename, {
    testDir: './e2e',
    includeMobileBrowsers: true, // includes mobile Chrome and Safari
    includeBrandedBrowsers: true, // includes Google Chrome and Microsoft Edge
  }),
  // other settings
});
```

If you want to override any settings within the `nxE2EPreset`, You can define them after the preset like so

```ts frame="none"
const config = nxE2EPreset(__filename, {
  testDir: './e2e',
  includeMobileBrowsers: true, // includes mobile Chrome and Safari
  includeBrandedBrowsers: true, // includes Google Chrome and Microsoft Edge
});
export default defineConfig({
  ...config
  retries: 3,
  reporters: [...config.reporters, /* other reporter settings */],
});
```

See the [Playwright configuration docs](https://playwright.dev/docs/test-configuration) for more options for Playwright.

---
<!-- source: https://nx.dev/docs/technologies/test-tools/playwright/migrations.md -->
## @nx/playwright Migrations

No migrations found for `@nx/playwright`.
Nx only retains migrations for the last 2 major versions of Nx.
It's possible migrations existed in previous versions of `@nx/playwright`.

You can check the previous docs for [Nx v21](https://21.nx.dev/docs) or [Nx v20](https://20.nx.dev/docs).

---
<!-- source: https://nx.dev/docs/technologies/test-tools/storybook.md -->
## Storybook

{% index_page_cards path="technologies/test-tools/storybook" /%}

---
<!-- source: https://nx.dev/docs/technologies/test-tools/storybook/executors.md -->
## @nx/storybook Executors

The @nx/storybook plugin provides various executors to help you create and configure storybook projects within your Nx workspace.
Below is a complete reference for all available executors and their options.

### `build`
Build storybook in production mode.

`project.json`:

```json
//...
"ui": {
    "targets": {
        //...
        "build-storybook": {
            "executor": "@nx/storybook:build",
            "outputs": ["{options.outputDir}"],
            "options": {
                "outputDir": "dist/storybook/ui",
                "configDir": "libs/ui/.storybook"
            },
            "configurations": {
                "ci": {
                    "quiet": true
                }
            }
        }
}
```

```bash
nx run ui:build-storybook
```

### Examples

#### For non-Angular projects

###### Working in docsMode

You can work in docs mode, building a documentation-only site, by setting the `docsMode` option to `true` and using the `@storybook/addon-docs` addon.

Read more on the [Storybook documentation page for `addon-docs`](https://storybook.js.org/addons/@storybook/addon-docs).

```json
"storybook": {
    "executor": "@nx/storybook:build",
    "options": {
        "port": 4400,
        "configDir": "libs/ui/.storybook",
        "docsMode": true
    },
    "configurations": {
        "ci": {
            "quiet": true
        }
    }
}
```

#### For Angular projects

###### Default configuration

This is the default configuration for Angular projects using Storybook. You can see that it uses the native `@storybook/angular:build-storybook` executor. You can read more about the configuration options at the relevant [Storybook documentation page](https://storybook.js.org/docs/angular/get-started/install).

```json
"build-storybook": {
  "executor": "@storybook/angular:build-storybook",
  "outputs": ["{options.outputDir}"],
  "options": {
    "outputDir": "dist/storybook/ngapp",
    "configDir": "apps/ngapp/.storybook",
    "browserTarget": "ngapp:build",
    "compodoc": false
  },
  "configurations": {
    "ci": {
      "quiet": true
    }
  }
}
```

###### Changing the browserTarget

You can set the `browserTarget` to use `build-storybook` as the builder. This is most useful in the cases where your project does not have a `build` target. Read more about the `browserTarget` in the [Set up Storybook for Angular Projects](/recipes/storybook/overview-angular) recipe.

```json
"build-storybook": {
  "executor": "@storybook/angular:build-storybook",
  "outputs": ["{options.outputDir}"],
  "options": {
    "outputDir": "dist/storybook/ngapp",
    "configDir": "apps/ngapp/.storybook",
    "browserTarget": "ngapp:build-storybook",
    "compodoc": false
  },
  "configurations": {
    "ci": {
      "quiet": true
    }
  }
}
```

###### Adding styles

You can add paths to stylesheets to be included in the Storybook build by using the `styles` array. You can also add `stylePreprocessorOptions`, much like you would do in the Angular builder. You can read more in our guide about [styles and preprocessor options for Storybook](/recipes/storybook/angular-configuring-styles).

```json
"build-storybook": {
  "executor": "@storybook/angular:build-storybook",
  "outputs": ["{options.outputDir}"],
  "options": {
    "outputDir": "dist/storybook/ngapp",
    "configDir": "apps/ngapp/.storybook",
    "browserTarget": "ngapp:build-storybook",
    "compodoc": false,
    "styles": ["some-styles.css"],
    "stylePreprocessorOptions": {
        "includePaths": ["some-style-paths"]
 }
  },
  "configurations": {
    "ci": {
      "quiet": true
    }
  }
}
```
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `configDir` | string [**required**] | Directory where to load Storybook configurations from. |  |
| `debugWebpack` | boolean | Display final webpack configurations for debugging purposes. |  |
| `disableTelemetry` | boolean | Disables Storybook's telemetry. |  |
| `docs` | boolean | Starts Storybook in documentation mode. Learn more about it : https://storybook.js.org/docs/react/writing-docs/build-documentation#preview-storybooks-documentation. |  |
| `docsMode` | boolean | Build a documentation-only site using addon-docs. | `false` |
| `loglevel` | string | Controls level of logging during build. Can be one of: [silly, verbose, info (default), warn, error, silent]. |  |
| `outputDir` | string | Directory where to store built files. |  |
| `quiet` | boolean | Suppress verbose build output. |  |
| `stylePreprocessorOptions` | object | Options to pass to style preprocessors. |  |
| `styles` | array | Global styles to be included in the build. |  |
| `webpackStatsJson` | boolean | string | Write Webpack Stats JSON to disk. | `false` |

### `storybook`
Serve up Storybook in development mode.

`project.json`:

```json
//...
"ui": {
    "targets": {
        //...
        "storybook": {
            "executor": "@nx/storybook:storybook",
            "options": {
                "port": 4400,
                "configDir": "libs/ui/.storybook"
            },
            "configurations": {
                "ci": {
                    "quiet": true
                }
            }
        },
    }
}
```

```bash
nx run ui:storybook
```

### Examples

#### For non-Angular projects

###### Working in docsMode

You can work in docs mode, building a documentation-only site, by setting the `docsMode` option to `true` and using the `@storybook/addon-docs` addon.

Read more on the [Storybook documentation page for `addon-docs`](https://storybook.js.org/addons/@storybook/addon-docs).

```json
"storybook": {
    "executor": "@nx/storybook:storybook",
    "options": {
        "port": 4400,
        "configDir": "libs/ui/.storybook",
        "docsMode": true
    },
    "configurations": {
        "ci": {
            "quiet": true
        }
    }
}
```

#### For Angular projects

###### Default configuration

This is the default configuration for Angular projects using Storybook. You can see that it uses the native `@storybook/angular:start-storybook` executor. You can read more about the configuration options at the relevant [Storybook documentation page](https://storybook.js.org/docs/angular/get-started/install).

```json
"storybook": {
  "executor": "@storybook/angular:start-storybook",
  "options": {
    "port": 4400,
    "configDir": "libs/ui/.storybook",
    "browserTarget": "ui:build",
    "compodoc": false
  },
  "configurations": {
    "ci": {
      "quiet": true
    }
  }
},
```

###### Changing the browserTarget

You can set the `browserTarget` to use `build-storybook` as the builder. This is most useful in the cases where your project does not have a `build` target. Read more about the `browserTarget` in the [Set up Storybook for Angular Projects](/recipes/storybook/overview-angular) recipe.

```json
"storybook": {
  "executor": "@storybook/angular:start-storybook",
  "options": {
    "port": 4400,
    "configDir": "libs/ui/.storybook",
    "browserTarget": "ui:build-storybook",
    "compodoc": false
  },
  "configurations": {
    "ci": {
      "quiet": true
    }
  }
},
```

###### Adding styles

You can add paths to stylesheets to be included in the Storybook build by using the `styles` array. You can also add `stylePreprocessorOptions`, much like you would do in the Angular builder. You can read more in our guide about [styles and preprocessor options for Storybook](/recipes/storybook/angular-configuring-styles).

```json
"storybook": {
  "executor": "@storybook/angular:start-storybook",
  "options": {
    "port": 4400,
    "configDir": "libs/ui/.storybook",
    "browserTarget": "ui:build",
    "compodoc": false,
    "styles": ["some-styles.css"],
    "stylePreprocessorOptions": {
          "includePaths": ["some-style-paths"]
    }
  },
  "configurations": {
    "ci": {
      "quiet": true
    }
  }
},
```
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `configDir` | string [**required**] | Directory where to load Storybook configurations from. |  |
| `ci` | boolean | CI mode (skip interactive prompts, don't open browser). | `false` |
| `debugWebpack` | boolean | Display final webpack configurations for debugging purposes. |  |
| `disableTelemetry` | boolean | Disables Storybook's telemetry. |  |
| `docs` | boolean | Starts Storybook in documentation mode. Learn more about it : https://storybook.js.org/docs/react/writing-docs/build-documentation#preview-storybooks-documentation. |  |
| `docsMode` | boolean | Starts Storybook in documentation mode. Learn more about it : https://storybook.js.org/docs/react/writing-docs/build-documentation#preview-storybooks-documentation. | `false` |
| `host` | string | Host to listen on. |  |
| `https` | boolean | Serve Storybook over HTTPS. Note: You must provide your own certificate information. | `false` |
| `loglevel` | string | Controls level of logging during build. Can be one of: [silly, verbose, info (default), warn, error, silent]. |  |
| `noOpen` | boolean | Do not open Storybook automatically in the browser. |  |
| `open` | boolean | Open browser window automatically. |  |
| `port` | number | Port to listen on. | `9009` |
| `previewUrl` | string | Preview URL. |  |
| `quiet` | boolean | Suppress verbose build output. |  |
| `smokeTest` | boolean | Exit after successful start. |  |
| `sslCa` | string | Provide an SSL certificate authority. (Optional with --https, required if using a self-signed certificate). |  |
| `sslCert` | string | Provide an SSL certificate. (Required with --https). |  |
| `sslKey` | string | Provide an SSL key. (Required with --https). |  |
| `uiFramework` | string | Storybook framework npm package. |  |
| `webpackStatsJson` | boolean | string | Write Webpack Stats JSON to disk. | `false` |

---
<!-- source: https://nx.dev/docs/technologies/test-tools/storybook/generators.md -->
## @nx/storybook Generators

The @nx/storybook plugin provides various generators to help you create and configure storybook projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `configuration`
Add Storybook configuration to a UI library or an application.

This is a framework-agnostic generator for setting up Storybook configuration for a project.

```bash
nx g @nx/storybook:configuration
```

:::tip[Nx uses Storybook 10]
Nx will configure your project to use Storybook v10. If you are not on Storybook 10 yet, please migrate. Please follow our [Storybook 10 migration generator](/docs/technologies/test-tools/storybook/generators#migrate-10) guide.
:::

If you are using Angular, React, Next.js, Vue or React Native in your project, it's best to use the framework specific Storybook configuration generator:

- [React Storybook Configuration Generator](/nx-api/react/generators/storybook-configuration) (React and Next.js projects)

- [Angular Storybook Configuration Generator](/nx-api/angular/generators/storybook-configuration)

- [React Native Storybook Configuration Generator](/nx-api/react-native/generators/storybook-configuration)

- [Vue Storybook Configuration Generator](/nx-api/vue/generators/storybook-configuration)

If you are not using one of the framework-specific generators mentioned above, when running this generator you will be prompted to provide the following:

- The `name` of the project you want to generate the configuration for.
- The `uiFramework` you want to use. Supported values are:
  - `@storybook/angular`
  - `@storybook/html-webpack5`
  - `@storybook/nextjs`
  - `@storybook/preact-webpack5`
  - `@storybook/react-webpack5`
  - `@storybook/react-vite`
  - `@storybook/server-webpack5`
  - `@storybook/svelte-webpack5`
  - `@storybook/svelte-vite`
  - `@storybook/sveltekit`
  - `@storybook/vue-webpack5`
  - `@storybook/vue-vite`
  - `@storybook/vue3-webpack5`
  - `@storybook/vue3-vite`
  - `@storybook/web-components-webpack5`
  - `@storybook/web-components-vite`
- Whether you want to set up [Storybook interaction tests](https://storybook.js.org/docs/angular/writing-tests/interaction-testing) (`interactionTests`). If you choose `yes`, all the necessary dependencies will be installed. Also, a `test-storybook` target will be generated in your project's `project.json`, with a command to invoke the [Storybook `test-runner`](https://storybook.js.org/docs/angular/writing-tests/test-runner). You can read more about this in the [Nx Storybook interaction tests documentation page](/recipes/storybook/storybook-interaction-tests#setup-storybook-interaction-tests).

You must provide a `name` and a `uiFramework` for the generator to work.

You can read more about how this generator works, in the [Storybook package overview page](/nx-api/storybook#generating-storybook-configuration).

### Examples

#### Generate Storybook configuration using JavaScript

```bash
nx g @nx/storybook:configuration ui --uiFramework=@storybook/web-components-vite --tsConfiguration=false
```

By default, our generator generates TypeScript Storybook configuration files. You can choose to use JavaScript for the Storybook configuration files of your project (the files inside the `.storybook` directory, eg. `.storybook/main.js`).

**Usage:**
```bash
nx generate @nx/storybook:configuration [options]
```

**Arguments:**
```bash
nx generate @nx/storybook:configuration <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--uiFramework` | string [**required**] | Storybook UI Framework to use. |  |
| `--configureStaticServe` | boolean | Add a static-storybook to serve the static storybook built files. | `false` |
| `--interactionTests` | boolean | Set up Storybook interaction tests. | `true` |
| `--js` | boolean | Generate JavaScript story files rather than TypeScript story files. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"eslint"` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--standaloneConfig` | boolean | Split the project configuration into `<projectRoot>/project.json` rather than including it inside `workspace.json`. | `true` |
| `--tsConfiguration` | boolean | Configure your project with TypeScript. Generate main.ts and preview.ts files, instead of main.js and preview.js. | `true` |

## `convert-to-inferred`
Convert existing Storybook project(s) using `@nx/storybook:*` executors to use `@nx/storybook/plugin`. Defaults to migrating all projects. Pass '--project' to migrate only one target.

**Usage:**
```bash
nx generate @nx/storybook:convert-to-inferred [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string | The project to convert from using the `@nx/storybook:*` executors to use `@nx/storybook/plugin`. |  |
| `--skipFormat` | boolean | Whether to format files at the end of the migration. | `false` |

## `migrate-10`
Migrate Storybook to version 10.

Storybook 10 is a major release that brings new features and improvements. You can read more about it in the [Storybook 10 release article](https://storybook.js.org/blog/storybook-10). Apart from the new features, it also brings some breaking changes—notably, Storybook 10 requires configuration files to use ESM syntax instead of CommonJS.

You can migrate your existing Nx workspace with Storybook configuration to use Storybook version 10. Nx offers the `@nx/storybook:migrate-10` generator to help you with this migration.

### How to use it

Just call:

```bash
npx nx g @nx/storybook:migrate-10
```

:::danger[Commit your changes]
It is advised that you start with a clean git history before running this generator, since it is going to be making changes to your workspace.
:::

This generator calls the Storybook CLI upgrade command (`storybook@latest upgrade`) to update your Storybook packages and configuration. The logs will explain what is happening in every step.

#### Accept the automigration prompts

The Storybook CLI will prompt you to run some code generators and modifiers. You can say `yes` to these prompts to let Storybook automatically update your configuration files.

#### Check the result

Once the generator finishes and the Storybook CLI automigration scripts have run, verify that your `.storybook/main.ts` files use ESM syntax:

```ts title="apps/my-app/.storybook/main.ts"
import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = {
  stories: ['../src/app/**/*.@(mdx|stories.@(js|jsx|ts|tsx))'],
  addons: ['@storybook/addon-essentials'],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },
};

export default config;
```

#### Make sure that all works by running Storybook

You can now use Storybook 10! 🎉

```bash
npx nx storybook PROJECT_NAME
```

and

```bash
npx nx build-storybook PROJECT_NAME
```

### Run the generator by automatically accepting the Storybook CLI prompts

You can run the generator with the `--autoAcceptAllPrompts` flag, which will automatically accept all the Storybook CLI prompts. This is useful if you want to run the generator in a CI environment, or if you want to run the generator in a script.

```bash
npx nx g @nx/storybook:migrate-10 --autoAcceptAllPrompts
```

### AI-assisted migration for ESM conversion

Storybook 10 requires configuration files to use ESM syntax. If you have CommonJS configuration files, Nx will generate an instructions file at `tools/ai-migrations/MIGRATE_STORYBOOK_10.md` when running `nx migrate`. This file contains detailed instructions that an AI agent (Claude, ChatGPT, GitHub Copilot, etc.) can use to convert your CJS configs to ESM.

See the [Upgrading Storybook guide](/docs/technologies/test-tools/storybook/guides/upgrading-storybook) for more details on AI-assisted migrations.

### Report any issues and bugs

Please report any issues and bugs you find [on the Nx GitHub page](https://github.com/nrwl/nx/issues/new/choose) or on the [Storybook GitHub page](https://github.com/storybookjs/storybook/issues/new/choose).

**Usage:**
```bash
nx generate @nx/storybook:migrate-10 [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--autoAcceptAllPrompts` | boolean | Say yes to all the prompts from the Storybook CLI migration scripts. | `false` |
| `--configDir` | array | Directory(ies) where to load Storybook configurations from. Use this if you want to customize the Storybook projects you'd like to migrate. | `[]` |

## `migrate-8`
Migrate Storybook to version 8.

Storybook 8 is a major release that brings a lot of new features and improvements. You can read more about it in the [Storybook 8.0.0 release article](https://storybook.js.org/blog/storybook-8/). Apart from the new features and improvements it introduces, it also brings some breaking changes. You can read more about them in the [Storybook 8 migration docs](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-7x-to-800) and the [Storybook 8.0.0 migration guide](https://storybook.js.org/docs/react/migration-guide).

You can now migrate your existing Nx workspace with Storybook configuration to use Storybook version 8. To help you, Nx offers the `@nx/storybook:migrate-8` generator. This generator will help you migrate your existing Storybook setup to version 8.

### How to use it

Just call:

```bash
npx nx g @nx/storybook:migrate-8
```

:::danger[Commit your changes]
It is advised that you start with a clean git history before running this generator, since it is going to be making lots of changes to your workspace.
:::

You can run this generator using the above command, without passing any options. This will start the migration process for all your projects that have Storybook configured. The logs will explain what is happening in every step, and the logs are mixed Nx and Storybook CLI logs. During the process you will be prompted by the Storybook CLI to accept the automigration scripts. You can read more about that in the next section.

When the generator finishes, you will see a summary of the changes that were made to your workspace, and it will also create a new file, called `storybook-migration-summary.md` at the root of your project, which will contain a list of all the changes that were made to your workspace.

#### Accept the automigration prompts

The Storybook CLI (running through our generator) will prompt you to run some code generators and modifiers.

You can say `yes` to these prompts, which are usually the following (there may be more or less, depending on your setup,
and depending on the latest versions of the Storybook CLI - this code is NOT managed by Nx, but by Storybook):

- `mainjsFramework`: It will try to add the `framework` field in your project's `.storybook/main.js|ts` file.
- `eslintPlugin`: installs the `eslint-plugin-storybook`
- `newFrameworks`: removes unused dependencies (eg. `@storybook/builder-webpack5`, `@storybook/manager-webpack5`, `@storybook/builder-vite`)
- `autodocsTrue`: adds `autodocs: true` to your project's `.storybook/main.js|ts` file

#### Check the result

Once the generator finishes, and the Storybook CLI automigration scripts have run, you should check the result. Examples of migrated `.storybook/main.js|ts` files would look like this:

##### Full example for Angular projects

Here is an example of a project-level `.storybook/main.js|ts` file for an Angular project that has been migrated to Storybook version 8:

```ts title="apps/my-angular-app/.storybook/main.js"
const config = {
  stories: ['../src/app/**/*.@(mdx|stories.@(js|jsx|ts|tsx)'],
  addons: ['@storybook/addon-essentials'],
  framework: {
    name: '@storybook/angular',
    options: {},
  },
};

export default config;
```

##### Full example for React projects with Vite

Here is an example of a project-level `.storybook/main.js|ts` file for a React project using Vite that has been migrated to Storybook version 8:

```ts title="apps/my-react-app/.storybook/main.js"
const config = {
  stories: ['../src/app/**/*.@(mdx|stories.@(js|jsx|ts|tsx)'],
  addons: ['@storybook/addon-essentials'],
  framework: {
    name: '@storybook/react-vite',
    options: {
      builder: {
        viteConfigPath: 'apps/rv1/vite.config.ts',
      },
    },
  },
};

export default config;
```

#### Make sure that all works by running Storybook

You can now use Storybook 8! 🎉

```bash
npx nx build-storybook PROJECT_NAME
```

and

```bash
npx nx storybook PROJECT_NAME
```

### Run the generator by automatically accepting the Storybook CLI prompts

You can run the generator with the `--autoAcceptAllPrompts` flag, which will automatically accept all the Storybook CLI prompts. This is useful if you want to run the generator in a CI environment, or if you want to run the generator in a script. Or if you are sure that you want to accept all the prompts!

```bash
npx nx g @nx/storybook:migrate-8 --autoAcceptAllPrompts
```

The Storybook CLI may still ask you about some things, but mostly it should just run the whole migration suite uninterrupted.

### Run the migration manually

Nx gives you the ability to run all the migration steps one by one, manually, but still with the help of our migrator. To help you out with the commands that you need to run, Nx will print out the instructions if you run the generator with the `--onlyShowListOfCommands` flag, like this:

```bash
npx nx g @nx/storybook:migrate-8 --onlyShowListOfCommands
```

Essentially, the way to run the migration manually is the following:

1. Call the Nx generator to show you the list of commands:
   `npx nx g @nx/storybook:migrate-8 --onlyShowListOfCommands`
2. Call the Storybook upgrade script:
   `npx storybook@latest upgrade`
3. Call the Storybook automigrate scripts for each one of the projects using Storybook (the `@nx/storybook:migrate-8` will give you the list of all the commands)

### Report any issues and bugs

Please report any issues and bugs you find [on the Nx GitHub page](https://github.com/nrwl/nx/issues/new/choose) or on the [Storybook GitHub page](https://github.com/storybookjs/storybook/issues/new/choose).

**Usage:**
```bash
nx generate @nx/storybook:migrate-8 [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--autoAcceptAllPrompts` | boolean | Say yes to all the prompts from the Storybook CLI migration scripts. | `false` |
| `--noUpgrade` | boolean | Skip upgrading Storybook packages. Only use this option if you are already on version 8, and you do not want the latest beta. | `false` |
| `--onlyShowListOfCommands` | boolean | Only show the steps that you need to follow in order to migrate. This does NOT make any changes to your code. | `false` |

## `migrate-9`
Migrate Storybook to version 9.

Storybook 9 is a major release that brings a lot of new features and improvements. You can read more about it in the [Storybook 9.0.0 release article](https://storybook.js.org/blog/storybook-9). Apart from the new features and improvements it introduces, it also brings some breaking changes. You can read more about them in the [Storybook 9 migration docs](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-8x-to-900) and the [Storybook 9.0.0 migration guide](https://storybook.js.org/docs/react/migration-guide).

You can now migrate your existing Nx workspace with Storybook configuration to use Storybook version 9. To help you, Nx offers the `@nx/storybook:migrate-9` generator. This generator will help you migrate your existing Storybook setup to version 9.

### How to use it

Just call:

```bash
npx nx g @nx/storybook:migrate-9
```

:::danger[Commit your changes]
It is advised that you start with a clean git history before running this generator, since it is going to be making lots of changes to your workspace.
:::

You can run this generator using the above command, without passing any options. This will start the migration process for all your projects that have Storybook configured. The logs will explain what is happening in every step, and the logs are mixed Nx and Storybook CLI logs. During the process you will be prompted by the Storybook CLI to accept the automigration scripts. You can read more about that in the next section.

When the generator finishes, you will see a summary of the changes that were made to your workspace, and it will also create a new file, called `storybook-migration-summary.md` at the root of your project, which will contain a list of all the changes that were made to your workspace.

#### Accept the automigration prompts

The Storybook CLI (running through our generator) will prompt you to run some code generators and modifiers.

You can say `yes` to these prompts, which are usually the following (there may be more or less, depending on your setup,
and depending on the latest versions of the Storybook CLI - this code is NOT managed by Nx, but by Storybook):

- `mainjsFramework`: It will try to add the `framework` field in your project's `.storybook/main.js|ts` file.
- `eslintPlugin`: installs the `eslint-plugin-storybook`
- `newFrameworks`: removes unused dependencies (eg. `@storybook/builder-webpack5`, `@storybook/manager-webpack5`, `@storybook/builder-vite`)
- `autodocsTrue`: adds `autodocs: true` to your project's `.storybook/main.js|ts` file

#### Check the result

Once the generator finishes, and the Storybook CLI automigration scripts have run, you should check the result. Examples of migrated `.storybook/main.js|ts` files would look like this:

##### Full example for Angular projects

Here is an example of a project-level `.storybook/main.js|ts` file for an Angular project that has been migrated to Storybook version 9:

```ts title="apps/my-angular-app/.storybook/main.js"
const config = {
  stories: ['../src/app/**/*.@(mdx|stories.@(js|jsx|ts|tsx)'],
  addons: ['@storybook/addon-essentials'],
  framework: {
    name: '@storybook/angular',
    options: {},
  },
};

export default config;
```

##### Full example for React projects with Vite

Here is an example of a project-level `.storybook/main.js|ts` file for a React project using Vite that has been migrated to Storybook version 9:

```ts title="apps/my-react-app/.storybook/main.js"
const config = {
  stories: ['../src/app/**/*.@(mdx|stories.@(js|jsx|ts|tsx)'],
  addons: ['@storybook/addon-essentials'],
  framework: {
    name: '@storybook/react-vite',
    options: {
      builder: {
        viteConfigPath: 'apps/rv1/vite.config.ts',
      },
    },
  },
};

export default config;
```

#### Make sure that all works by running Storybook

You can now use Storybook 9! 🎉

```bash
npx nx build-storybook PROJECT_NAME
```

and

```bash
npx nx storybook PROJECT_NAME
```

### Run the generator by automatically accepting the Storybook CLI prompts

You can run the generator with the `--autoAcceptAllPrompts` flag, which will automatically accept all the Storybook CLI prompts. This is useful if you want to run the generator in a CI environment, or if you want to run the generator in a script. Or if you are sure that you want to accept all the prompts!

```bash
npx nx g @nx/storybook:migrate-9 --autoAcceptAllPrompts
```

The Storybook CLI may still ask you about some things, but mostly it should just run the whole migration suite uninterrupted.

### Run the migration manually

Nx gives you the ability to run all the migration steps one by one, manually, but still with the help of our migrator. To help you out with the commands that you need to run, Nx will print out the instructions if you run the generator with the `--onlyShowListOfCommands` flag, like this:

```bash
npx nx g @nx/storybook:migrate-9 --onlyShowListOfCommands
```

Essentially, the way to run the migration manually is the following:

1. Call the Nx generator to show you the list of commands:
   `npx nx g @nx/storybook:migrate-9 --onlyShowListOfCommands`
2. Call the Storybook upgrade script:
   `npx storybook@latest upgrade`
3. Call the Storybook automigrate scripts for each one of the projects using Storybook (the `@nx/storybook:migrate-9` will give you the list of all the commands)

### Report any issues and bugs

Please report any issues and bugs you find [on the Nx GitHub page](https://github.com/nrwl/nx/issues/new/choose) or on the [Storybook GitHub page](https://github.com/storybookjs/storybook/issues/new/choose).

**Usage:**
```bash
nx generate @nx/storybook:migrate-9 [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--autoAcceptAllPrompts` | boolean | Say yes to all the prompts from the Storybook CLI migration scripts. | `false` |
| `--noUpgrade` | boolean | Skip upgrading Storybook packages. Only use this option if you are already on version 9, and you do not want to install the packages again. | `false` |
| `--onlyShowListOfCommands` | boolean | Only show the steps that you need to follow in order to migrate. This does NOT make any changes to your code. | `false` |
| `--versionTag` | string | The version of Storybook to use. Use 'latest' to use the latest stable version, or 'next' to use the latest beta. | `"latest"` |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/storybook:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/test-tools/storybook/guides.md -->
## Guides

{% index_page_cards path="technologies/test-tools/storybook/guides" /%}

---
<!-- source: https://nx.dev/docs/technologies/test-tools/storybook/guides/angular-configuring-styles.md -->
## Angular - Configuring styles and preprocessor options

When working with Angular and Storybook in an Nx workspace, you may need to configure styles and CSS preprocessors to ensure your components render correctly in Storybook.

## Global styles

### Adding global styles to Storybook

You can add global styles to your Storybook by creating a `preview.ts` file in your `.storybook` directory:

```typescript
// .storybook/preview.ts
import type { Preview } from '@storybook/angular';

// Import global styles
import '../src/styles.scss'; // Your global styles
import '@angular/material/prebuilt-themes/indigo-pink.css'; // Material theme

const preview: Preview = {
  parameters: {
    actions: { argTypesRegex: '^on[A-Z].*' },
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/,
      },
    },
  },
};

export default preview;
```

### Using Angular material styles

If you're using Angular Material, you can include the theme in your Storybook:

```typescript
// .storybook/preview.ts
import '@angular/material/prebuilt-themes/indigo-pink.css';
// or your custom theme
import '../src/styles/material-theme.scss';
```

## SCSS/SASS configuration

### Configuring SCSS in Storybook

If your Angular project uses SCSS, you can configure Storybook to handle SCSS files properly:

```typescript
// .storybook/main.ts
import type { StorybookConfig } from '@storybook/angular';

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
  addons: ['@storybook/addon-essentials', '@storybook/addon-interactions'],
  framework: {
    name: '@storybook/angular',
    options: {},
  },
  core: {
    builder: '@storybook/builder-webpack5',
  },
  typescript: {
    check: false,
    checkOptions: {},
    reactDocgen: 'react-docgen-typescript',
    reactDocgenTypescriptOptions: {
      shouldExtractLiteralValuesFromEnum: true,
      propFilter: (prop) =>
        prop.parent ? !/node_modules/.test(prop.parent.fileName) : true,
    },
  },
};

export default config;
```

### Including SCSS variables and mixins

To use SCSS variables and mixins in your stories, you may need to configure additional include paths:

```typescript
// .storybook/main.ts
import type { StorybookConfig } from '@storybook/angular';

const config: StorybookConfig = {
  // ... other config
  webpackFinal: async (config) => {
    // Add SCSS support with include paths
    const scssRule = config.module?.rules?.find((rule: any) =>
      rule.test?.toString().includes('scss')
    );

    if (scssRule && scssRule.use) {
      const sassLoaderOptions = scssRule.use.find((use: any) =>
        use.loader?.includes('sass-loader')
      );

      if (sassLoaderOptions) {
        sassLoaderOptions.options = {
          ...sassLoaderOptions.options,
          sassOptions: {
            includePaths: ['src/styles', 'src/assets/styles'],
          },
        };
      }
    }

    return config;
  },
};

export default config;
```

## Tailwind CSS configuration

### Setting up Tailwind CSS with Storybook

If your Angular project uses Tailwind CSS, configure it in your Storybook:

1. Install Tailwind CSS for Storybook:

```shell
npm install -D @storybook/addon-postcss
```

2. Add the addon to your Storybook configuration:

```typescript
// .storybook/main.ts
import type { StorybookConfig } from '@storybook/angular';

const config: StorybookConfig = {
  // ... other config
  addons: [
    '@storybook/addon-essentials',
    {
      name: '@storybook/addon-postcss',
      options: {
        postcssLoaderOptions: {
          implementation: require('postcss'),
        },
      },
    },
  ],
};

export default config;
```

3. Import Tailwind in your preview file:

```typescript
// .storybook/preview.ts
import '../src/styles.css'; // This should include Tailwind CSS imports
```

## Component-specific styles

### Using Angular component styles in stories

Component styles defined in Angular components should work automatically in Storybook. However, if you need to override styles for stories, you can do so in individual story files:

```typescript
// button.stories.ts
import type { Meta, StoryObj } from '@storybook/angular';
import { ButtonComponent } from './button.component';

const meta: Meta<ButtonComponent> = {
  title: 'Components/Button',
  component: ButtonComponent,
  parameters: {
    // Add custom styles for this story
    docs: {
      description: {
        component: 'A customizable button component.',
      },
    },
  },
  decorators: [
    (story) => ({
      template: `
        <div style="padding: 20px; background: #f5f5f5;">
          <story></story>
        </div>
      `,
    }),
  ],
};

export default meta;
type Story = StoryObj<ButtonComponent>;

export const Default: Story = {
  args: {
    label: 'Button',
  },
};

export const CustomStyling: Story = {
  args: {
    label: 'Custom Button',
  },
  decorators: [
    (story) => ({
      template: `
        <div style="padding: 40px; background: linear-gradient(45deg, #ff6b6b, #4ecdc4);">
          <story></story>
        </div>
      `,
    }),
  ],
};
```

## Troubleshooting style issues

### Common issues and solutions

1. **Styles not loading**: Ensure your global styles are imported in `.storybook/preview.ts`

2. **SCSS variables not available**: Configure include paths in the webpack configuration

3. **Angular Material styles missing**: Import the Material theme CSS file in your preview

4. **Component styles not applying**: Check that component stylesheets are properly referenced in the component decorator

5. **CSS modules not working**: Ensure your webpack configuration supports CSS modules if your project uses them

### Debug style loading

You can debug style loading by checking the browser's developer tools to see if stylesheets are being loaded correctly and if there are any 404 errors for missing style files.

---
<!-- source: https://nx.dev/docs/technologies/test-tools/storybook/guides/angular-storybook-compodoc.md -->
## Angular - Set up Compodoc for Storybook on Nx

[Compodoc](https://compodoc.app/) is a documentation tool for Angular applications. When used with Storybook, Compodoc can automatically generate documentation for your Angular components by analyzing their TypeScript code, decorators, and JSDoc comments.

## What is compodoc?

Compodoc automatically generates documentation by:

- Analyzing TypeScript interfaces and classes
- Reading Angular decorators (`@Input`, `@Output`, etc.)
- Parsing JSDoc comments
- Generating `argTypes` for Storybook controls

## Setting up Compodoc with Storybook

### Prerequisites

You need to have Storybook already configured for your Angular project. If you haven't set up Storybook yet, follow the [Angular Storybook setup guide](/docs/technologies/test-tools/storybook/guides/overview-angular).

### Install compodoc

Install Compodoc as a dev dependency:

```shell
npm install --save-dev @compodoc/compodoc
```

### Configure Compodoc in your Storybook

Add Compodoc configuration to your Storybook's `main.ts` file:

```typescript
// .storybook/main.ts
import type { StorybookConfig } from '@storybook/angular';

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
  addons: ['@storybook/addon-essentials', '@storybook/addon-interactions'],
  framework: {
    name: '@storybook/angular',
    options: {},
  },
  typescript: {
    check: false,
    checkOptions: {},
    reactDocgen: 'react-docgen-typescript',
    reactDocgenTypescriptOptions: {
      shouldExtractLiteralValuesFromEnum: true,
      propFilter: (prop) =>
        prop.parent ? !/node_modules/.test(prop.parent.fileName) : true,
      compilerOptions: {
        allowSyntheticDefaultImports: false,
        esModuleInterop: false,
      },
    },
  },
  docs: {
    autodocs: true,
  },
};

export default config;
```

### Generate compodoc documentation

Add a script to your `package.json` to generate Compodoc documentation:

```json
// package.json
{
  "scripts": {
    "docs:json": "compodoc -p tsconfig.json -e json -d .",
    "storybook": "npm run docs:json && nx storybook your-project"
  }
}
```

### Configure your Angular component for better documentation

Add JSDoc comments and use TypeScript interfaces for better documentation generation:

```typescript
// button.component.ts
import { Component, Input, Output, EventEmitter } from '@angular/core';

export interface ButtonProps {
  /** The button label */
  label: string;
  /** Primary or secondary styling */
  primary?: boolean;
  /** Disabled state */
  disabled?: boolean;
  /** Button size */
  size?: 'small' | 'medium' | 'large';
}

/**
 * A customizable button component
 */
@Component({
  selector: 'app-button',
  template: `
    <button
      [class]="classes"
      [disabled]="disabled"
      (click)="onClick.emit($event)"
    >
      {{ label }}
    </button>
  `,
  styleUrls: ['./button.component.css'],
})
export class ButtonComponent implements ButtonProps {
  /** The button label */
  @Input() label: string = '';

  /** Primary or secondary styling */
  @Input() primary: boolean = false;

  /** Disabled state */
  @Input() disabled: boolean = false;

  /** Button size */
  @Input() size: 'small' | 'medium' | 'large' = 'medium';

  /** Click event handler */
  @Output() onClick = new EventEmitter<Event>();

  get classes(): string {
    return [
      'btn',
      this.primary ? 'btn-primary' : 'btn-secondary',
      `btn-${this.size}`,
    ].join(' ');
  }
}
```

### Enhanced story with Compodoc integration

Create a story that leverages the Compodoc-generated documentation:

```typescript
// button.stories.ts
import type { Meta, StoryObj } from '@storybook/angular';
import { ButtonComponent } from './button.component';

const meta: Meta<ButtonComponent> = {
  title: 'Components/Button',
  component: ButtonComponent,
  parameters: {
    docs: {
      description: {
        component:
          'A customizable button component with multiple variants and sizes.',
      },
    },
  },
  argTypes: {
    size: {
      control: { type: 'select' },
      options: ['small', 'medium', 'large'],
    },
    onClick: { action: 'clicked' },
  },
};

export default meta;
type Story = StoryObj<ButtonComponent>;

export const Primary: Story = {
  args: {
    primary: true,
    label: 'Primary Button',
    size: 'medium',
  },
};

export const Secondary: Story = {
  args: {
    primary: false,
    label: 'Secondary Button',
    size: 'medium',
  },
};

export const Large: Story = {
  args: {
    label: 'Large Button',
    size: 'large',
  },
};

export const Small: Story = {
  args: {
    label: 'Small Button',
    size: 'small',
  },
};

export const Disabled: Story = {
  args: {
    label: 'Disabled Button',
    disabled: true,
  },
};
```

## Benefits of using Compodoc with Storybook

1. **Automatic Documentation**: Compodoc generates component documentation automatically from your TypeScript code
2. **Better Controls**: Enhanced Storybook controls based on your component's `@Input` properties
3. **Type Safety**: Leverages TypeScript types for accurate documentation
4. **JSDoc Integration**: Uses JSDoc comments for rich descriptions
5. **Less Maintenance**: Documentation stays in sync with your code

## Running Storybook with compodoc

With the setup complete, run your Storybook:

```shell
npm run storybook
```

This will generate the Compodoc documentation and then start Storybook with enhanced documentation for your Angular components.

---
<!-- source: https://nx.dev/docs/technologies/test-tools/storybook/guides/best-practices.md -->
## Storybook best practices for making the most out of Nx

## Purpose of this guide

The purpose of this guide is to help you [set up Storybook in your Nx workspace](/docs/technologies/test-tools/storybook/introduction) so that you can get the most out of Nx and its powerful capabilities.

## When to use Storybook

Usually, Storybook is mainly used for two reasons. Testing and documentation. You can read more on when and why to use Storybook in the [Why Storybook in 2022?](https://storybook.js.org/blog/why-storybook-in-2022/) article and also in the [Introduction to Storybook](https://storybook.js.org/docs/react/get-started/introduction) documentation page.

### Testing

Storybook helps you test your UIs. You can read more about testing with Storybook in the [How to test your UIs with Storybook](https://storybook.js.org/docs/react/writing-tests/introduction) documentation page. Essentially, Storybook uses the stories as a starting point for testing.

### Documentation

Storybook helps you document your UI elements, or your design system, effectively and in an interactive way. You can read more in the [How to document components](https://storybook.js.org/docs/react/writing-docs/introduction) documentation page. Essentially, you can use Storybook to publish a catalog of your components. A catalog that you can share with the design team, the developer team, the product team, anyone else in the product development process, or even the client. The components are isolated, interactive, and can be represented in all possible forms that they can take (e.g. for a button: enabled, disabled, active, etc). You can read more about publishing your Storybook in the [Publish Storybook](https://storybook.js.org/docs/react/sharing/publish-storybook) documentation page.

## Nx and Storybook

Now let's see how Nx can be used to accommodate both of these pillars of Storybook. Nx takes lots of the burden off your arms when setting up Storybook initially. It essentially provides you with all that you need to start using Storybook's capabilities (testing and documentation) right away, without having to write a single line of code.

### Development tools

First, let's see what Nx offers, when you are in the process of developing a project with Storybook.

#### Configuration generation

You can generate the Storybook configuration files and settings using the Nx [`@nx/storybook:configuration` generator](/docs/technologies/test-tools/storybook/generators#configuration). You can read more about configuring Storybook with Nx in our [`@nx/storybook` introduction page](/docs/technologies/test-tools/storybook/introduction#generating-storybook-configuration). With Nx, you configure Storybook for each individual project.

#### Stories generation

If you are on a project using Angular, React or React Native, you can also generate stories for your components. You can do so either by using each package's `storybook-configuration` generators or by using the `stories` generator, if you already have Storybook configured for your project.

If your project is not configured yet, check out one of these guides:

- [Set up Storybook for React (and Next.js) Projects](/docs/technologies/test-tools/storybook/guides/overview-react)

- [Set up Storybook for Angular Projects](/docs/technologies/test-tools/storybook/guides/overview-angular)

- [Set up Storybook for Vue Projects](/docs/technologies/test-tools/storybook/guides/overview-vue)

If your project is [already configured](/docs/technologies/test-tools/storybook/introduction), you can use the `stories` generator:

- [React (and Next.js) stories generator](/docs/technologies/react/generators#stories)

- [Angular stories generator](/docs/technologies/angular/generators#stories)

- [Vue stories generator](/docs/technologies/vue/generators#stories)

The stories generator will read your inputs (if you're using Angular), or your props (if you're using React), and will generate stories with the corresponding arguments/controls already prefilled.

#### Storybook interaction tests

[Storybook interaction tests](https://storybook.js.org/docs/react/writing-tests/interaction-testing) allow you to test user interactions within your Storybook stories. It enhances your [Storybook](https://storybook.js.org/) setup, ensuring that not only do your components look right, but they also work correctly when interacted with.

Nx will generate interaction tests for your stories. You can read more in our [Setting up Storybook Interaction Tests with Nx guide](/docs/technologies/test-tools/storybook/guides/storybook-interaction-tests).

### CI/CD tools

Now let's see how Nx helps in the CI/CD journey, as well.

#### Interaction tests in your CI

You can set up your interaction tests to run as part of your CI. You can read more in the [Storybook docs](https://storybook.js.org/docs/react/writing-tests/test-runner#set-up-ci-to-run-tests).

#### Serve

When you are configuring Storybook, Nx [adds a serve and a build target for Storybook](/docs/technologies/test-tools/storybook/introduction#generating-storybook-configuration) in your `project.json`, as we explained above. You can use these targets to [serve](/docs/technologies/test-tools/storybook/executors#storybook) and [build](/docs/technologies/test-tools/storybook/executors#build) storybook locally, and also in production. Cypress will also use these targets when firing up the e2e tests. While developing, you can serve your Storybooks locally to see if your components work and look as expected. This can help you and speed up the development and debugging process (no need to fire up a complex dev stack).

#### Build and deploy

The build and deploy step usually comes in handy when you are ready to use Storybook for documentation, and you want to publish it. The [building](/docs/technologies/test-tools/storybook/executors#build) step of Storybook is integrated in the Nx ecosystem, as explained above, and you can trigger your Storybook builds as you would trigger any other build inside your workspace.

When you publish your organization's Storybook, as a result, ideally, you would want to have one shareable Storybook page/application living under one URL, that you can share. With Nx, you can build your Storybook and it will be ready for deployment. **However**, at this point, you have one Storybook per project in your workspace, and you could end up with far too many Storybooks that are built and ready for deployment. This is not ideal, and does not accomplish the ultimate goal of "one shareable documentation page".

In the following section, we are going to see how to set up Storybook in these cases, to get the most out of Nx.

## How to set up Storybook to get the most out of Nx

### Philosophy

Setting up Storybook on Nx reflects - and takes advantage of - the [mental model](/docs/concepts/mental-model) of Nx. What that means, in essence, is that you still maintain the individual Storybook instances (per project) which you use for testing and local development, but you also keep one extra "container" for publishing, that serves as a single entry point. Let's see this in more detail.

#### Local development and testing

##### Development and debugging

In the process of setting up Storybook in your Nx workspace that we described above, you end up with one Storybook instance per project. That way, you can use your project's Storybook targets to serve, test and build Storybook:

```shell
nx storybook my-project
```

and

```shell
nx build-storybook my-project
```

and

```shell
nx test-storybook my-project
```

This feature is extremely useful when developing locally. The containerized stories in your Storybook are the only ones that are built/served/tested when you want to debug just one component, or just one library. You don't have to wait for a huge Storybook containing all your stories in your repository to fire up. You just need to wait for the Storybook of a single project to start. This speeds up the process.

##### Caching, affected, dependency management

Since each Storybook, in this case, is attached to a project, so is the serving of Storybook and the building of Storybook and the e2e tests for that project. That means that Nx is aware of these tasks, so it caches them, it knows when to fetch them from the cache or re-run them according to the affected status of that project. It also knows that project's dependencies and knows which things to rebuild before each task.

#### Publishing

When you are publishing your Storybook, you can follow the principles described in the [project size](/docs/concepts/decisions/project-size) decision page. The general idea is to have one central Storybook container, into which you are going to gather your stories from multiple libraries.

You can think of the central Storybook container as a grouping of similar-concept or same-scope UI parts of your workspace. In the same way you are scoping libraries, you can group your stories as well.

Then, according to your use-case, you can have one central Storybook for your whole workspace, importing all the stories from all the projects. Alternatively, you can have one Storybook per "scope", which imports all the stories from projects the same scope. Or even one Storybook per application, importing all the stories of all the libraries that it is depending on. As you can see, there are many options, and you can choose the one that best suits your needs.

{% aside type="note" title="Storybook Composition" %}
In order to achieve some things mentioned above, you may use [Storybook Composition](/docs/technologies/test-tools/storybook/guides/storybook-composition-setup). However, in this case, you would still need to build each project's Storybook individually, and also deploy it individually. So in the cases where you have multiple projects, Storybook Composition would not be very efficient.
{% /aside %}

Before moving on to the examples section, it could be useful to read the [Library Types](/docs/concepts/decisions/project-dependency-rules) documentation page and the [Grouping libraries](/docs/concepts/decisions/folder-structure) documentation page. These could help you decide which way fits your use case better.

## Examples / use cases

You can check out the following examples (recipes) to see publishing strategies for Storybook in Nx:

- [One main Storybook instance for all projects](/docs/technologies/test-tools/storybook/guides/one-storybook-for-all)
- [One Storybook instance per scope](/docs/technologies/test-tools/storybook/guides/one-storybook-per-scope)
- [One main Storybook instance using Storybook Composition](/docs/technologies/test-tools/storybook/guides/one-storybook-with-composition)

## Conclusion

We have given a direction towards the most efficient way to use Storybook in a Nx workspace, in a way that takes advantage of the all that Nx has to offer.
We have covered the different ways to set up Storybook, and publish it, too. We have also covered the different use cases that apply to each of the solutions.

If you have any questions or suggestions, please feel free to reach out to us on [GitHub](https://github.com/nrwl/nx), and don't hesitate to ask your questions or share your stories in the [Official Nx Discord Server](https://go.nx.dev/community).

### Nx & Storybook documentation

You can find all Storybook-related Nx documentation in the [packages page](/docs/technologies/test-tools/storybook/introduction).

---
<!-- source: https://nx.dev/docs/technologies/test-tools/storybook/guides/configuring-storybook.md -->
## How Storybook is configured on your Nx workspace

{% aside type="note" title="Best practices" %}
Read our [Using Storybook in a Nx workspace - Best practices](/docs/technologies/test-tools/storybook/guides/best-practices) guide!
{% /aside %}

Nx does not generate a root Storybook directory and shared root Storybook configurations. Instead, it only generates a Storybook configuration for each project in your workspace. You may still manually create a root Storybook configuration file, if it is needed for your use case.

You can read all about creating and using a root Storybook configuration in our guide [How to configure Webpack and Vite for Storybook](/docs/technologies/test-tools/storybook/guides/custom-builder-configs).

This change means that each of your projects that has Storybook configured has only one, project-level, project-specific `.storybook/main.js|ts` file that it relies on, without importing settings from external files. This simplifies the configuration process, makes it easier for the user to understand the configuration that each project is using, and also makes it easier to maintain, relying on automatic migration scripts, for example.

This does not change much for the user, as the configuration process is still the same, and you may still manually create a root Storybook configuration file, if it is needed for your use case.

## Project-specific configuration

You will notice that all project-specific configuration files contain the `@storybook/addon-essentials` addon, which is the shared setting among projects. Other than that, depending on the project type, the settings differ in regards to the builder used, the stories import glob pattern, and, in the case of projects using Vite, the path to the `vite.config.ts` file or the root of the project, for correct path resolution.
All these are automatically generated by Nx, so you don't have to worry about them.

## Root Storybook configuration

If you need to create a root Storybook configuration file, you can do so by creating a `.storybook/main.js|ts` file in your workspace root. Then, you may import this file in your project-level Storybook configuration files. However, this is rarely needed in most cases, since most settings for builders like Webpack and Vite, for example, are already built-in into the Storybook builders.

## Read our guides for Configuring Storybook

You can read all our guides for configuring Storybook in our [Storybook guides page](/docs/technologies/test-tools/storybook/guides).

Please also make sure to read our [Using Storybook in a Nx workspace - Best practices](/docs/technologies/test-tools/storybook/guides/best-practices) guide, where you can find some best practices for using Storybook in a Nx workspace.

---
<!-- source: https://nx.dev/docs/technologies/test-tools/storybook/guides/custom-builder-configs.md -->
## How to configure Webpack and Vite for Storybook

Storybook allows you to customize the `webpack` configuration and your `vite` configuration. For that, it offers two fields you can add in your `.storybook/main.js|ts` file, called `webpackFinal` and `viteFinal`. These fields are functions that take the default configuration as an argument, and return the modified configuration. You can read more about them in the [Storybook documentation for `webpack`](https://storybook.js.org/docs/react/builders/webpack#extending-storybooks-webpack-config) and the [Storybook documentation for `vite`](https://storybook.js.org/docs/react/builders/vite#configuration).

You can use these fields in your Nx workspace Storybook configurations normally, following the Storybook docs. However, let's see how you can create a global configuration for every project in your workspace, and how you can override it for specific projects.

## Global configuration

If you want to add a global configuration for Webpack or Vite in your workspace, you may create a `.storybook/main.js` file at the root of your workspace. In that root `.storybook/main.js|ts` file, you can add the `webpackFinal` or `viteFinal` field, and return the modified configuration. This will be applied to every project in your workspace.

### `webpack` and `webpackFinal`

The `webpackFinal` field would look like this:

```ts
// .storybook/main.ts
webpackFinal: async (config, { configType }) => {
  // Make whatever fine-grained changes you need that should apply to all storybook configs

  // Return the altered config
  return config;
},
```

### `vite` and `viteFinal`

The `viteFinal` field would look like this:

```ts
// .storybook/main.ts
async viteFinal(config, { configType }) {
   if (configType === 'DEVELOPMENT') {
     // Your development configuration goes here
   }
   if (configType === 'PRODUCTION') {
     // Your production configuration goes here.
   }
   return mergeConfig(config, {
     // Your environment configuration here
   });
 },
```

In the `viteFinal` case, you would have to import the `mergeConfig` function from `vite`. So, on the top of your root `.storybook/main.js|ts` file, you would have to add:

```ts
// .storybook/main.ts
import { mergeConfig } from 'vite';
```

## Project-specific configuration

### `webpack` and `webpackFinal`

You can customize the `webpack` configuration for a specific project by adding a `webpackFinal` field in your project-specific `.storybook/main.js|ts` file, like this:

```ts
// apps/my-react-webpack-app/.storybook/main.ts
import type { StorybookConfig } from '@storybook/react-webpack5';

const config: StorybookConfig = {
  stories: ...,
  addons: ...,
  framework: {
    name: '@storybook/react-webpack5',
    options: {},
  },
  webpackFinal: async (config, { configType }) => {
    // add your own webpack tweaks if needed
    return config;
  },
};

export default config;
```

If you are using a global, root-level, `webpack` configuration in your project, you can customize or extend that for a specific project by importing and extending the root configuration.

### `vite` and `viteFinal`

You can customize the `vite` configuration for a specific project by adding a `viteFinal` field in your project-specific `.storybook/main.js|ts` file, following the same pattern as shown above for webpack configuration.

---
<!-- source: https://nx.dev/docs/technologies/test-tools/storybook/guides/one-storybook-for-all.md -->
## Publishing Storybook - One main Storybook instance for all projects

This guide extends the
[Using Storybook in a Nx workspace - Best practices](/docs/technologies/test-tools/storybook/guides/best-practices) guide. In that guide, we discussed the best practices of using Storybook in a Nx workspace. We explained the main concepts and the mental model of how to best set up Storybook. we are going to see how to put that into practice, by looking at a real-world example. We are going to see how you can publish one single Storybook for your workspace.

This case would work if all your projects (applications and libraries) containing stories that you want to use are using the same framework (Angular, React, Vue, etc). The reason is that you will be importing the stories in a central host Storybook's `.storybook/main.ts`, and we will be using one specific builder to build that Storybook. Storybook does not support mixing frameworks in the same Storybook instance.

Let's see how we can implement this solution:

{% github_repository url="https://github.com/nrwl/nx-recipes/tree/main/storybook-publishing-strategies-single-framework" /%}

## Steps

### Generate a new library that will host our Storybook instance

According to the framework you are using, use the corresponding generator to generate a new library. Let's suppose that you are using React and all your stories are using the `@storybook/react-vite` framework:

```shell
nx g @nx/react:library libs/storybook-host --bundler=none --unitTestRunner=none
```

Now, you have a new library, which will act as a shell/host for all your stories.

### Configure the new library to use Storybook

Now let's configure our new library to use Storybook, using the [`@nx/storybook:configuration` generator](/docs/technologies/test-tools/storybook/generators#configuration). Run:

```shell
nx g @nx/storybook:configuration storybook-host --interactionTests=true --uiFramework=@storybook/react-vite
```

This generator will only create the `libs/storybook-host/.storybook` folder. It will also [infer the tasks](/docs/concepts/inferred-tasks): `storybook`, `build-storybook`, and `test-storybook`. This is all we care about. We don't need any stories for this project since we will import the stories from other projects in our workspace. So, if you want, you can delete the contents of the `src/lib` folder.

{% aside type="note" title="Using explicit tasks" %}
If you're on an Nx version lower than 18 or have opted out of using inferred tasks, the `storybook`, `build-storybook`, and `test-storybook` targets will be explicitly defined in the `libs/storybook-host/project.json` file.
{% /aside %}

### Import the stories in our library's main.ts

Now it's time to import the stories of our other projects in our new library's `./storybook/main.ts`.

Here is a sample `libs/storybook-host/.storybook/main.ts` file:

```javascript {% meta="{6}" %}
// libs/storybook-host/.storybook/main.ts
import type { StorybookConfig } from '@storybook/react-vite';
import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
import { mergeConfig } from 'vite';

const config: StorybookConfig = {
  stories: ['../../**/ui/**/src/lib/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
  addons: ['@storybook/addon-essentials', '@storybook/addon-interactions'],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },

  viteFinal: async (config) =>
    mergeConfig(config, {
      plugins: [nxViteTsPaths()],
    }),
};

export default config;
```

Notice how we only link the stories matching a specific pattern. According to your workspace set-up, you can adjust the pattern, or add more patterns, so that you can match all the stories in all the projects you want.

For example:

```javascript
// libs/storybook-host/.storybook/main.ts
const config: StorybookConfig = {
  stories: [
    '../../**/ui/**/src/lib/**/*.stories.@(js|jsx|ts|tsx|mdx)',
    '../../**/src/lib/**/*.stories.@(js|jsx|ts|tsx|mdx)',
    // ...
  ],
  // ...
};
```

### If you're using Angular add the stories in your tsconfig.json

Here is a sample `libs/storybook-host/.storybook/tsconfig.json` file:

```json {%  meta="{7}" %}
// libs/storybook-host/.storybook/tsconfig.json
{
  "extends": "../tsconfig.json",
  "compilerOptions": {
    "emitDecoratorMetadata": true
  },
  "exclude": ["../**/*.spec.ts"],
  "include": ["../../**/ui/**/src/lib/**/*.stories.ts", "*.ts"]
}
```

Notice how in the `include` array we are specifying the paths to our stories, using the same pattern we used in our `.storybook/main.ts`.

### Serve or build your Storybook

Now you can serve, test or build your Storybook as you would, normally. And then you can publish the bundled app!

```shell
nx storybook storybook-host
```

or

```shell
nx build-storybook storybook-host
```

or

```shell
nx test-storybook storybook-host
```

## Use cases that apply to this solution

Can be used for:

- Workspaces with multiple apps and libraries, all using a single framework

Ideal for:

- Workspaces with a single app and multiple libraries all using a single framework

## Extras - dependencies

Your new Storybook host, essentially, depends on all the projects from which it is importing stories. This means whenever one of these projects updates a component, or updates a story, our Storybook host would have to rebuild, to reflect these changes. It cannot rely on the cached result. However, Nx does not understand the imports in `libs/storybook-host/.storybook/main.ts`, and the result is that Nx does not know which projects the Storybook host depends on, based solely on the `main.ts` imports.

The good thing is that there is a solution to this. You can manually add the projects your Storybook host depends on as implicit dependencies in your project's `project.json` file:

```json {% meta="{6-14}" %}
// libs/storybook-host/project.json
{
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "sourceRoot": "libs/storybook-host/src",
  "projectType": "library",
  "tags": ["type:storybook"],
  "implicitDependencies": [
    "admin-ui-footer",
    "admin-ui-header",
    "client-ui-footer",
    "client-ui-header",
    "shared-ui-button",
    "shared-ui-main",
    "shared-ui-notification"
  ]
}
```

---
<!-- source: https://nx.dev/docs/technologies/test-tools/storybook/guides/one-storybook-per-scope.md -->
## Publishing Storybook - One Storybook instance per scope

This guide extends the
[Using Storybook in a Nx workspace - Best practices](/docs/technologies/test-tools/storybook/guides/best-practices) guide. It discussed the best practices of using Storybook in a Nx workspace, explaining the main concepts and the mental model of how to best set up Storybook. Now, we are going to see how to put that into practice, by looking at a real-world example. We are going to see how you can publish one Storybook per scope (eg. theme, app, framework) for your workspace.

Sometimes, you have multiple apps and libraries, and each of these is associated with a specific scope. You can read more about grouping libraries and scoping them in the [Library Types](/docs/concepts/decisions/project-dependency-rules) documentation page.

In this case, you can have one Storybook instance per scope. If you follow the folder organization convention described above, it is easy to configure Storybook to import all the stories under a specific folder, for example, which are associated with a specific app or scope.

{% github_repository url="https://github.com/nrwl/nx-recipes/tree/main/storybook-publishing-strategies-single-framework" /%}

## Structure of the folders

Say, for example, that you have a client app, an admin app, and a number of UI libraries, organized under the name of each app. So you would have a folder structure that looks like this:

{%filetree %}

- happynrwl/
  - apps/
    - client/
    - admin/
  - libs/
    - client/
      - feature/
    - ui/
      - header/
        - .storybook/
      - src/
        - lib/
          - my-header/
            - my-header.ts
            - my-header.stories.ts
            - etc...
        - etc...
      - README.md
      - tsconfig.json
      - etc...
    - utils/
    - admin/
      - feature/
      - ui/
        - dashboard/
          - .storybook/
        - src/
          - etc..
        - README.md
        - tsconfig.json
        - etc...
      - utils/
    - shared/
      - ui/
        - cta/
        - .storybook/
        - src/
          - etc..
        - README.md
        - tsconfig.json
        - etc...
      - utils/
  - tools/
  - nx.json
  - package.json
  - tsconfig.base.json

{% /filetree %}

In this case you can see that we have two deployable applications, `client` and `admin`, and we have a number of UI libraries, each associated with a specific app. For example, `client-ui-header` is a UI library associated with the `client` app, and `admin-ui-dashboard` is a UI library associated with the `admin` app. We also have one more library, the `shared-ui-cta` library, which is shared between the two apps. The way we have structured our folders is such that any new library that is related to the `client` app will go in the `libs/client` folder, and in that folder we have a sub-folder to determine if the new library is related to `ui` or anything else. The same applies to the `admin` app. Any library shared between the two apps will live under a subfolder of the `libs/shared` folder.

Notice how we have already generated Storybook configuration and stories for all of our `ui` libraries.

## Setting up the thematic Storybook instances

Now, we want to have one Storybook instance per _thematic scope_. This is quite easy to implement since we are following this specific folder structure.

First of all, we need to generate three new libraries (or as many as our "thematic scopes"), which will host all the stories for each specific scope. We can do this following the same steps described above.

If we want to combine stories from different libraries in the same Storybook instance, _the stories need to use the same framework_.

Let's assume in this case that all our libraries are using Angular.

### Generate the libraries

Let's generate three Angular libraries, one for each scope, and let's call them `storybook-host-client`, `storybook-host-admin`, and `storybook-host-shared`. We can do this by running the following commands:

```shell
nx g @nx/angular:lib libs/storybook-host-client
```

```shell
nx g @nx/angular:lib libs/storybook-host-admin
```

```shell
nx g @nx/angular:lib libs/storybook-host-shared
```

### Generate the Storybook configuration for the libraries

Now, we need to generate Storybook configuration for all these new libraries. We don't want to generate `stories` for these libraries, so we can run the following commands:

```shell
nx g @nx/storybook:configuration storybook-host-client --uiFramework=@storybook/angular --interactionTests=true
```

```shell
nx g @nx/storybook:configuration storybook-host-admin --uiFramework=@storybook/angular --interactionTests=true
```

```shell
nx g @nx/storybook:configuration storybook-host-shared --uiFramework=@storybook/angular --interactionTests=true
```

### Import the stories

Now that our Storybook configuration is ready for our new libraries, we can go ahead and import the stories!

Thanks to our folder structure, we can easily configure Storybook to import all the stories under a specific folder, for example, which are associated with a specific scope.

For example, `libs/storybook-host-admin/.storybook/main.ts`:

```javascript
// libs/storybook-host-admin/.storybook/main.ts
import type { StorybookConfig } from '@storybook/angular';

const config: StorybookConfig = {
  stories: ['../../admin/ui/**/src/lib/**/*.stories.ts'],
  addons: ['@storybook/addon-essentials', '@storybook/addon-interactions'],
  framework: {
    name: '@storybook/angular',
    options: {},
  },
};

export default config;
```

And don't forget the `libs/storybook-host-admin/.storybook/tsconfig.json`:

```json
// libs/storybook-host-admin/.storybook/tsconfig.json
{
  "extends": "../tsconfig.json",
  "compilerOptions": {
    "emitDecoratorMetadata": true
  },
  "exclude": ["../**/*.spec.ts"],
  "include": ["../../admin/ui/**/src/lib/**/*.stories.ts", "*.ts"]
}
```

## Use cases that apply to this solution

- Workspaces with multiple apps and libraries, all using a single framework

- Workspaces that use scopes and follow the suggested folder structure

- Workspaces that have multiple apps and libs divided by theme and by framework, that do not mind having more than one Storybook

## Extras - dependencies

In this example, you can still use the implicit dependencies to manually tell Nx which projects your new libraries depend on.

---
<!-- source: https://nx.dev/docs/technologies/test-tools/storybook/guides/one-storybook-with-composition.md -->
## Publishing Storybook - One main Storybook instance using Storybook Composition

This guide extends the
[Using Storybook in a Nx workspace - Best practices](/docs/technologies/test-tools/storybook/guides/best-practices) guide. In that guide, we discussed the best practices of using Storybook in a Nx workspace. We explained the main concepts and the mental model of how to best set up Storybook. we are going to see how to put that into practice, by looking at a real-world example. We are going to see how you can publish one single Storybook for your workspace, even you are using multiple frameworks, taking advantage of [Storybook Composition](/docs/technologies/test-tools/storybook/guides/storybook-composition-setup).

In this case, we are dealing with a Nx workspace that uses multiple frameworks. Essentially, you would need to have one Storybook host for each of the frameworks, containing all the stories of that specific framework, since the Storybook builder can not handle multiple frameworks simultaneously.

However, there is still the option to combine all the hosts into one single Storybook instance, using _Storybook composition_.

Let's assume that you have a structure like the one described in the previous example, and your `client` app and the `client` libs are written in Angular, and the `admin` app the `admin` libs are written in React.

First of all, you have to create two Storybook host apps, one for Angular and one for React. Let's call them `storybook-host-angular` and `storybook-host-react`, which are configured to import all the Angular stories and all the React stories accordingly.

Now, we are going to combine the two Storybook host apps into one, using Storybook composition. You can read our [Storybook Composition guide](/docs/technologies/test-tools/storybook/guides/storybook-composition-setup) for a detailed explanation for how Storybook Composition works. In a nutshell, you can have one "host" Storybook instance running, where you can link other running Storybook instances.

{% github_repository url="https://github.com/nrwl/nx-recipes/tree/main/storybook-publishing-strategies-multiple-frameworks" /%}

## Steps

We are going to assume that you are at the state where you already have your `storybook-host-angular` and `storybook-host-react` set up and ready to go.

### Generate a Storybook host library

It does not matter which framework you use for the host Storybook library. It can be any framework really, and it does not have to be one of the frameworks that are used in the hosted apps. The only thing that is important is for this host library to have _at least one story_. This is important, or else Storybook will not load. The one story can be a component, for example, which would work like a title for the application, or any other introduction to your Storybook you see fit.

So, let's use React for the Storybook Composition host library:

```shell
nx g @nx/react:lib libs/storybook-host --bundler=none --unitTestRunner=none
```

Now that your library is generated, you can write your intro in the generated component (you can also do this later, it does not matter).

### Generate Storybook configuration for the host library

Since you do need a story for your host Storybook, you should use the React storybook configuration generator, and actually choose to generate stories (not an e2e project though):

```shell
nx g @nx/react:storybook-configuration storybook-host --interactionTests=true --generateStories=true
```

### Change the Storybook port in the hosted apps

It's important to change the Storybook ports in the `storybook-host-angular` and `storybook-host-react` projects. This is because the Storybook Composition host is going to be looking at these ports to find which Storybooks to host, and which Storybook goes where.

Update the `project.json` file of each library to set the `port` option to `4401` and `4402` accordingly:

```json {% meta="{8}" %}
// libs/storybook-host-angular/project.json
{
  // ...
  "targets": {
    // ...
    "storybook": {
      "options": {
        "port": 4401
      }
    }
  }
}
```

```json {% meta="{8}" %}
// libs/storybook-host-react/project.json
{
  // ...
  "targets": {
    // ...
    "storybook": {
      "options": {
        "port": 4402
      }
    }
  }
}
```

{% aside type="note" title="Inferred tasks vs explicit tasks" %}
Projects using [inferred tasks](/docs/concepts/inferred-tasks) might not have the `storybook` target defined in the `project.json` file, so you need to add the target with only the `port` option set.

If the project has the `storybook` target explicitly defined in the `project.json` file, you need to update or set the `port` option.
{% /aside %}

### Add the `refs` to the main.ts of the host library

Update the `libs/storybook-host/.storybook/main.ts` file as shown below:

```javascript {% meta="{14-23}" %}
// libs/storybook-host/.storybook/main.ts
import type { StorybookConfig } from '@storybook/react-vite';
import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
import { mergeConfig } from 'vite';

const config: StorybookConfig = {
  stories: ['../src/lib/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
  addons: ['@storybook/addon-essentials', '@storybook/addon-interactions'],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },

  refs: {
    'my-angular-app': {
      title: 'My Angular App',
      url: 'http://localhost:4401',
    },
    'my-react-app': {
      title: 'My React App',
      url: 'http://localhost:4402',
    },
  },

  viteFinal: async (config) =>
    mergeConfig(config, {
      plugins: [nxViteTsPaths()],
    }),
};

export default config;
```

## Serve the Storybooks

Now, you can serve your host Storybook, as well as the hosted, composed Storybooks. You need to serve the composed Storybooks first, and then your host.

```shell
nx run storybook-host-angular:storybook
```

and on a different terminal:

```shell
nx run storybook-host-react:storybook
```

and then on a different terminal serve the host:

```shell
nx run storybook-host:storybook
```

You should now be able to see your host Storybook on your default port (usually `4400`) and you should also be able to see your composed Storybooks in the sidebar.

## Build and deploy

You can now build and deploy the Storybook host.

You can build the Storybook with:

```shell
nx run storybook-host:build-storybook
```

Here's the catch. You will need to build and deploy the composed Storybooks independently as well, and make sure that they are available on the URLs that you have configured in your host Storybook's `main.ts`. In our example above, the host Storybook would be looking for the composed Storybooks on `http://localhost:4401` and `http://localhost:4402`. So you need to build and deploy:

- `storybook-host-angular` on some URL, let's say https://my-angular-stories.my-company.com/
- `storybook-host-react` on some URL, let's say https://my-react-stories.my-company.com/

and then change the host Storybook's `main.ts` file to point to these URLs accordingly:

```javascript
// libs/storybook-host/.storybook/main.ts
import type { StorybookConfig } from '@storybook/react-vite';
import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
import { mergeConfig } from 'vite';

const config: StorybookConfig = {
  stories: ['../src/lib/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
  addons: ['@storybook/addon-essentials', '@storybook/addon-interactions'],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },

  refs: {
    'my-angular-app': {
      title: 'My Angular App',
      url: 'https://my-angular-stories.my-company.com/',
    },
    'my-react-app': {
      title: 'My React App',
      url: 'https://my-react-stories.my-company.com/',
    },
  },

  viteFinal: async (config) =>
    mergeConfig(config, {
      plugins: [nxViteTsPaths()],
    }),
};

export default config;
```

As you can see, the Storybook Composition solution would work for a small number of composed apps, but it can become quite cumbersome to manage if you have too many apps that you want to compose into your host Storybook.

## Use cases that apply to this solution

- Workspaces using multiple frameworks
- Workspaces that have multiple Storybooks that they want to view in one single interface
- Workspaces that use component libraries in multiple frameworks and want to showcase all their components in one single Storybook instance

---
<!-- source: https://nx.dev/docs/technologies/test-tools/storybook/guides/overview-angular.md -->
## Set up Storybook for Angular Projects

Walk you through setting up [Storybook](https://storybook.js.org) for Angular projects in your Nx workspace.

{% aside type="caution" title="Set up Storybook in your workspace" %}
You first need to set up Storybook for your Nx workspace, if you haven't already. You can read the [Storybook plugin overview guide](/docs/technologies/test-tools/storybook/introduction) to get started.
{% /aside %}

## Generate Storybook Configuration for an Angular project

You can generate Storybook configuration for an individual Angular project by using the [`@nx/angular:storybook-configuration` generator](/docs/technologies/angular/generators#storybook-configuration), like this:

```shell
nx g @nx/angular:storybook-configuration project-name
```

## Auto-generate stories

The [`@nx/angular:storybook-configuration` generator](/docs/technologies/angular/generators#storybook-configuration) has the option to automatically generate `*.stories.ts` files for each component declared in the library. The stories will be generated using [Component Story Format 3 (CSF3)](https://storybook.js.org/blog/storybook-csf3-is-here/).

{%filetree %}

- <some-folder>/
  - my-component.ts
  - my-component.stories.ts

{%/filetree %}
If you add more components to your project, and want to generate stories for all your (new) components at any point, you can use the [`@nx/angular:stories` generator](/docs/technologies/angular/generators#stories):

```shell
nx g @nx/angular:stories --project=<project-name>
```

### Example library

Let's take for a example a library in your workspace, under `libs/feature/ui`, called `feature-ui`. This library contains a component, called `my-button`.

The command to generate stories for that library would be:

```shell
nx g @nx/angular:stories --project=feature-ui
```

and the result would be the following:

{% filetree %}

- workspace name/
  - apps/
  - libs/
    - feature/
      - ui/
        - .storybook/
      - src/
        - lib
          - my-button
            - my-button.ts
            - my-button.stories.ts
            - etc...
        - etc...
      - README.md
      - tsconfig.json
      - etc...
    - etc...
    - etc...
  - nx.json
  - package.json
  - README.md
  - etc...

{% /filetree %}

## Example files

Let's take for example a library in your workspace, under `libs/feature/ui`, called `feature-ui` with a component, called `my-button`.

Let's say that the template for that component looks like this:

```html
// libs/feature/ui/src/lib/my-button/my-button.html
<button [disabled]="disabled" [ngStyle]="{ 'padding.px': padding }">
  {{ text }}
</button>
```

and the component looks like this:

```typescript
// libs/feature/ui/src/lib/my-button/my-button.ts
import { Component, Input } from '@angular/core';

@Component({
  selector: 'feature-ui-my-button',
  standalone: true,
  templateUrl: './my-button.html',
  styleUrls: ['./my-button.css'],
})
export class MyButton {
  @Input() text = 'Click me!';
  @Input() padding = 10;
  @Input() disabled = true;
}
```

### Story file

The [`@nx/angular:storybook-configuration` generator](/docs/technologies/angular/generators#storybook-configuration) would generate a Story file that looks like this:

```typescript
// libs/feature/ui/src/lib/my-button/my-button.stories.ts
import type { Meta, StoryObj } from '@storybook/angular';
import { MyButton } from './my-button';
import { within } from '@storybook/testing-library';
import { expect } from '@storybook/jest';

const meta: Meta<MyButton> = {
  component: MyButton,
  title: 'MyButton',
};
export default meta;

type Story = StoryObj<MyButton>;

export const Primary: Story = {
  args: {
    text: 'Click me!',
    padding: 10,
    disabled: true,
  },
};

export const Heading: Story = {
  args: {
    text: 'Click me!',
    padding: 10,
    disabled: true,
  },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    expect(canvas.getByText(/my-button/gi)).toBeTruthy();
  },
};
```

Notice the interaction test on the second story, inside the `play` function. This just tests if the default text that appears on generated components exists in the rendered component. You can edit this test to suit your needs. You can read more about interaction tests [here](https://storybook.js.org/docs/angular/writing-tests/interaction-testing).

## Understanding the role of `browserTarget`

You will notice that `browserTarget` is specified for the `storybook` and `build-storybook` targets, much like it is done for `serve` or other targets. Angular needs the `browserTarget` for Storybook in order to know which configuration to use for the build. If your project is buildable (it has a `build` target, and uses the main Angular builder - `@angular-devkit/build-angular:browser`, `@angular-devkit/build-angular:application` or `@angular-devkit/build-angular:browser-esbuild`) the `browserTarget` for Storybook will use the `build` target, if it's not buildable (or is using another Angular builder) it will use the `build-storybook` target.
You do not have to do anything manually. Nx will create the configuration for you. Even if you are migrating from an older version of Nx, Nx will make sure to change your `package.json` Storybook targets to match the new schema.

You can read more about the `browserTarget` in the [official Angular documentation](https://angular.dev/cli/serve).

Your Storybook targets in your `project.json` (or if you run `nx show project my-project --web`) will look like this:

```jsonc
// project.json
    "storybook": {
      "executor": "@storybook/angular:start-storybook",
      "options": {
         ...
        "browserTarget": "my-project:build"
      },
      ...
    },
    "build-storybook": {
      "executor": "@storybook/angular:build-storybook",
       ...
      "options": {
         ...
        "browserTarget": "my-project:build"
      },
     ...
    }
```

This setup instructs Nx to use the configuration under the `build` target of `my-project` when using the `storybook` and `build-storybook` executors.

## More documentation

- [Set up Compodoc for Storybook on Nx](/docs/technologies/test-tools/storybook/guides/angular-storybook-compodoc)
- [Configuring styles and preprocessor options](/docs/technologies/test-tools/storybook/guides/angular-configuring-styles)

You can find all Storybook-related Nx topics [here](/docs/technologies/test-tools/storybook/introduction).

For more on using Storybook, see the [official Storybook documentation](https://storybook.js.org/docs/angular/get-started/introduction).

### Migration scenarios

Here's more information on common migration scenarios for Storybook with Nx. For Storybook specific migrations that are not automatically handled by Nx please refer to the [official Storybook page](https://storybook.js.org/)

- [Upgrading Storybook guide](/docs/technologies/test-tools/storybook/guides/upgrading-storybook)
- [Storybook 10 migration generator](/docs/technologies/test-tools/storybook/generators#migrate-10)

---
<!-- source: https://nx.dev/docs/technologies/test-tools/storybook/guides/overview-react.md -->
## Set up Storybook for React Projects

Walk you through setting up [Storybook](https://storybook.js.org) for React projects in your Nx workspace.

{% aside type="caution" title="Set up Storybook in your workspace" %}
You first need to set up Storybook for your Nx workspace, if you haven't already. You can read the [Storybook plugin overview guide](/docs/technologies/test-tools/storybook/introduction) to get started.
{% /aside %}

## Generate Storybook Configuration for a React project

You can generate Storybook configuration for an individual React project by using the [`@nx/react:storybook-configuration` generator](/docs/technologies/react/generators#storybook-configuration), like this:

```shell
nx g @nx/react:storybook-configuration project-name
```

## Auto-generate stories

The [`@nx/react:storybook-configuration` generator](/docs/technologies/react/generators#storybook-configuration) has the option to automatically generate `*.stories.ts|tsx` files for each component declared in the library. The stories will be generated using [Component Story Format 3 (CSF3)](https://storybook.js.org/blog/storybook-csf3-is-here/).

{% filetree %}

- <some-folder>/
  - my-component.tsx
  - my-component.stories.tsx

{% /filetree %}

If you add more components to your project, and want to generate stories for all your (new) components at any point, you can use the [`@nx/react:stories` generator](/docs/technologies/react/generators#stories):

```shell
nx g @nx/react:stories --project=<project-name>
```

### Example library

Let's take for a example a library in your workspace, under `libs/feature/ui`, called `feature-ui`. This library contains a component, called `my-button`.

The command to generate stories for that library would be:

```shell
nx g @nx/react:stories --project=feature-ui
```

and the result would be the following:

{% filetree %}

- workspace-name/
  - apps/
  - libs/
    - feature/
      - ui/
        - .storybook/
      - src/
        - lib/
          - my-button/
            - my-button.tsx
            - my-button.stories.tsx
        - etc...
      - README.md
      - tsconfig.json
  - nx.json
  - package.json
  - README.md

{% /filetree %}

## Example files

Let's take for a example a library in your workspace, under `libs/feature/ui`, called `feature-ui` with a component, called `my-button`.

Let's say that your component code looks like this:

```typescript
// libs/feature/ui/src/lib/my-button/my-button.tsx
export interface MyButtonProps {
  text: string;
  padding: number;
  disabled: boolean;
}

export function MyButton(props: MyButtonProps) {
  return (
    <button disabled={props.disabled} style={{ padding: props.padding }}>
      {props.text}
    </button>
  );
}

export default MyButton;
```

### Story file

The [`@nx/react:storybook-configuration` generator](/docs/technologies/react/generators#storybook-configuration) would generate a Story file that looks like this:

```typescript
// libs/feature/ui/src/lib/my-button/my-button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react-vite';
import { MyButton } from './my-button';
import { within } from '@storybook/testing-library';
import { expect } from '@storybook/jest';

const meta = {
  component: MyButton,
  title: 'MyButton',
} satisfies Meta<typeof MyButton>;
export default meta;

type Story = StoryObj<typeof MyButton>;

export const Primary = {
  args: {
    text: '',
    padding: 0,
    disabled: false,
  },
} satisfies Story;

export const Heading = {
  args: {
    text: '',
    padding: 0,
    disabled: false,
  },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    expect(canvas.getByText(/MyButton!/gi)).toBeTruthy();
  },
} satisfies Story;
```

Notice the interaction test on the second story, inside the `play` function. This just tests if the default text that appears on generated components exists in the rendered component. You can edit this test to suit your needs. You can read more about interaction tests [here](https://storybook.js.org/docs/react/writing-tests/interaction-testing).

## More documentation

You can find all Storybook-related Nx topics [here](/docs/technologies/test-tools/storybook/introduction).

For more on using Storybook, see the [official Storybook documentation](https://storybook.js.org/docs/react/get-started/introduction).

### Migration scenarios

Here's more information on common migration scenarios for Storybook with Nx. For Storybook specific migrations that are not automatically handled by Nx please refer to the [official Storybook page](https://storybook.js.org/)

- [Upgrading Storybook guide](/docs/technologies/test-tools/storybook/guides/upgrading-storybook)
- [Storybook 10 migration generator](/docs/technologies/test-tools/storybook/generators#migrate-10)

---
<!-- source: https://nx.dev/docs/technologies/test-tools/storybook/guides/overview-vue.md -->
## Set up Storybook for Vue and Nuxt Projects

Walk you through setting up [Storybook](https://storybook.js.org) for Vue and Nuxt projects in your Nx workspace.

{% aside type="caution" title="Set up Storybook in your workspace" %}
You first need to set up Storybook for your Nx workspace, if you haven't already. You can read the [Storybook plugin overview guide](/docs/technologies/test-tools/storybook/introduction) to get started.
{% /aside %}

## Generate Storybook Configuration for a Vue or Nuxt project

You can generate Storybook configuration for an individual Vue or Nuxt project by using the [`@nx/vue:storybook-configuration` generator](/docs/technologies/vue/generators#storybook-configuration), like this:

{% tabs %}
{% tabitem label="Vue" %}

```shell
nx g @nx/vue:storybook-configuration project-name
```

{% /tabitem %}
{% tabitem label="Nuxt" %}

```shell
nx g @nx/nuxt:storybook-configuration my-nuxt-app
```

{% /tabitem %}

{% /tabs %}

## Auto-generate stories

The [`@nx/vue:storybook-configuration` generator](/docs/technologies/vue/generators#storybook-configuration) has the option to automatically generate `*.stories.ts` files for each component declared in the library.

```text {% frame="none" %}
<some-folder>/
├── MyComponent.vue
└── MyComponent.stories.ts
```

If you add more components to your project, and want to generate stories for all your (new) components at any point, you can use the [`@nx/vue:stories` generator](/docs/technologies/vue/generators#stories):

{% tabs %}
{% tabitem label="Vue" %}

```shell
nx g @nx/vue:stories --project=<project-name>
```

{% /tabitem %}
{% tabitem label="Nuxt" %}

```shell
nx g @nx/nuxt:stories --project=<project-name>
```

{% /tabitem %}

{% /tabs %}

### Example library

Let's take for a example a library in your workspace, under `libs/feature/ui`, called `feature-ui`. This library contains a component, called `my-button`.

The command to generate stories for that library would be:

```shell
nx g @nx/vue:stories --project=feature-ui
```

and the result would be the following:

{% filetree %}

- workspace name/
  - apps/
  - libs/
    - feature/
      - ui/
        - .storybook/
      - src/
        - lib/
          - my-button/
            - MyButton.vue
            - MyButton.stories.ts
            - etc...
        - etc...
      - README.md
      - tsconfig.json
      - etc...
    - etc...
  - nx.json
  - package.json
  - README.md
  - etc...

{% /filetree %}

## More documentation

You can find all Storybook-related Nx topics [here](/docs/technologies/test-tools/storybook/introduction).

For more on using Storybook, see the [official Storybook documentation](https://storybook.js.org/docs/vue/get-started/introduction).

---
<!-- source: https://nx.dev/docs/technologies/test-tools/storybook/guides/storybook-composition-setup.md -->
## Setting up Storybook Composition with Nx

[Storybook Composition](https://storybook.js.org/docs/sharing/storybook-composition) allows you to embed multiple Storybook instances in one Storybook, giving you a unified view of all your components across different projects and frameworks.

## What is Storybook composition?

Storybook Composition is a way to combine multiple Storybook instances into a single interface. This is particularly useful when:

- You have multiple projects using different frameworks (React, Angular, Vue, etc.)
- You want to create a central hub for all your design system components
- You need to showcase components from different teams or repositories

## Setting up the main Storybook

First, you need a main Storybook instance that will serve as the host for other Storybooks.

### Generate a host library

```shell
nx g @nx/react:library storybook-host --bundler=none --unitTestRunner=none
```

### Configure Storybook for the host

```shell
nx g @nx/storybook:configuration storybook-host --uiFramework=@storybook/react-vite
```

## Setting up composed Storybooks

Each Storybook that you want to compose needs to be accessible via a URL. This means you need to:

1. Ensure each composed Storybook runs on a different port
2. Build and deploy each composed Storybook to a URL

### Configure ports for composed Storybooks

Update the `project.json` files of your composed Storybooks to use different ports:

```json
// libs/ui-lib-1/project.json
{
  "targets": {
    "storybook": {
      "options": {
        "port": 4401
      }
    }
  }
}
```

```json
// libs/ui-lib-2/project.json
{
  "targets": {
    "storybook": {
      "options": {
        "port": 4402
      }
    }
  }
}
```

## Configure the main Storybook

In your main Storybook's configuration file, add references to the composed Storybooks:

```typescript
// libs/storybook-host/.storybook/main.ts
import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = {
  stories: ['../src/lib/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
  addons: ['@storybook/addon-essentials'],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },
  refs: {
    'ui-lib-1': {
      title: 'UI Library 1',
      url: 'http://localhost:4401',
    },
    'ui-lib-2': {
      title: 'UI Library 2',
      url: 'http://localhost:4402',
    },
  },
};

export default config;
```

## Running the composed Storybooks

To see your composed Storybooks in action:

1. Start each composed Storybook on its designated port:

```shell
nx storybook ui-lib-1
nx storybook ui-lib-2
```

2. Start the main Storybook:

```shell
nx storybook storybook-host
```

Now when you open the main Storybook, you'll see entries in the sidebar for each composed Storybook.

## Deploying composed Storybooks

For production use, you'll need to:

1. Build and deploy each composed Storybook to a URL
2. Update the `refs` in your main Storybook configuration to point to these deployed URLs

```typescript
// libs/storybook-host/.storybook/main.ts
const config: StorybookConfig = {
  // ... other config
  refs: {
    'ui-lib-1': {
      title: 'UI Library 1',
      url: 'https://ui-lib-1.storybook.company.com',
    },
    'ui-lib-2': {
      title: 'UI Library 2',
      url: 'https://ui-lib-2.storybook.company.com',
    },
  },
};
```

## Benefits and limitations

### Benefits

- Unified interface for multiple Storybooks
- Support for different frameworks in the same view
- Centralized documentation hub

### Limitations

- Each composed Storybook needs to be built and deployed separately
- Network latency can affect loading times
- More complex deployment setup

For detailed implementation examples, see the guides on [publishing strategies](/docs/technologies/test-tools/storybook/guides/one-storybook-with-composition).

---
<!-- source: https://nx.dev/docs/technologies/test-tools/storybook/guides/storybook-interaction-tests.md -->
## Setting up Storybook Interaction Tests with Nx

[Storybook interaction tests](https://storybook.js.org/docs/react/writing-tests/interaction-testing) allow you to test user interactions within your Storybook stories. It enhances your [Storybook](https://storybook.js.org/) setup, ensuring that not only do your components look right, but they also work correctly when interacted with.

## Setting up Storybook interaction tests

### Prerequisites

You need to have Storybook already set up in your Nx workspace. If you don't have Storybook set up yet, you can read the [Storybook plugin overview guide](/docs/technologies/test-tools/storybook/introduction).

### Generate Storybook configuration with interaction tests

When generating your Storybook configuration, make sure to answer `Yes` to the `Do you want to set up Storybook interaction tests?` prompt, or pass the `--interactionTests=true` flag when generating your Storybook configuration.

```shell
nx g @nx/storybook:configuration my-project --interactionTests=true
```

This will set up:

- The `@storybook/addon-interactions` addon
- The `@storybook/testing-library` and `@storybook/jest` dependencies
- A `test-storybook` target for running the interaction tests

### Writing interaction tests

You can now write interaction tests in your stories by using the `play` function. Here's an example:

```typescript
import type { Meta, StoryObj } from '@storybook/react';
import { within, userEvent } from '@storybook/testing-library';
import { expect } from '@storybook/jest';

import { Button } from './button';

const meta: Meta<typeof Button> = {
  title: 'Example/Button',
  component: Button,
  parameters: {
    layout: 'centered',
  },
  tags: ['autodocs'],
  argTypes: {
    backgroundColor: { control: 'color' },
  },
};

export default meta;
type Story = StoryObj<typeof meta>;

export const Primary: Story = {
  args: {
    primary: true,
    label: 'Button',
  },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    const button = canvas.getByRole('button');

    await expect(button).toBeInTheDocument();
    await userEvent.click(button);
    await expect(button).toHaveFocus();
  },
};
```

### Running interaction tests

You can run your interaction tests using:

```shell
nx test-storybook my-project
```

This will run all the interaction tests in your Storybook stories.

You can also run the tests in headless mode for CI:

```shell
nx test-storybook my-project --ci
```

### Debugging interaction tests

During development, you can watch your interaction tests run in the Storybook UI by:

1. Starting your Storybook: `nx storybook my-project`
2. Opening the Interactions panel in the Storybook UI
3. Running individual story tests by clicking the play button

This allows you to see the tests run step by step and debug any issues.

---
<!-- source: https://nx.dev/docs/technologies/test-tools/storybook/guides/upgrading-storybook.md -->
## Upgrading Storybook

Nx provides migration support for major Storybook versions (8, 9, and 10). You can upgrade using Nx built-in migration system or the Storybook CLI directly.

## Upgrading with Nx

You can run a migration generator for the specific Storybook version you want to upgrade to, or starting with Nx 22, run `nx migrate` to automatically upgrade to Storybook 10.

### Using migration generators

Run the Storybook migration generator for your target version:

| Generator                                                                   | Command                         | Description             |
| --------------------------------------------------------------------------- | ------------------------------- | ----------------------- |
| [migrate-8](/docs/technologies/test-tools/storybook/generators#migrate-8)   | `nx g @nx/storybook:migrate-8`  | Migrate to Storybook 8  |
| [migrate-9](/docs/technologies/test-tools/storybook/generators#migrate-9)   | `nx g @nx/storybook:migrate-9`  | Migrate to Storybook 9  |
| [migrate-10](/docs/technologies/test-tools/storybook/generators#migrate-10) | `nx g @nx/storybook:migrate-10` | Migrate to Storybook 10 |

### Using `nx migrate` (Nx 22+)

Starting with Nx 22, when you run `nx migrate`, Nx automatically migrates Storybook 9 to Storybook 10. If you're already on Storybook 10, no migration runs. If you're on Storybook 8 or earlier, you'll need to use the migration generators above first.

```shell
nx migrate latest
nx migrate --run-migrations
```

#### AI-assisted migrations

For Storybook 10, some changes cannot be fully automated. When this happens, Nx generates an instructions file at `ai-migrations/MIGRATE_STORYBOOK_10.md` that an AI agent (Claude, ChatGPT, GitHub Copilot, etc.) can use to complete the migration.

For example, Storybook 10 requires configuration files to use ESM syntax instead of CommonJS. The AI migration instructions guide an agent to find and convert any CJS Storybook configs to ESM format.

## Upgrading with Storybook CLI

If you prefer to skip Nx migrations and use the Storybook CLI directly:

```shell
npx storybook@latest upgrade
```

This runs Storybook's own upgrade command which updates dependencies and configuration files. See the [Storybook upgrade documentation](https://storybook.js.org/docs/react/configure/upgrading) for more details.

## After upgrading

1. Review breaking changes in the [Storybook release notes](https://storybook.js.org/blog/)
2. Update your stories to use new APIs if needed
3. Test your Storybook instances to ensure everything works
4. Update any custom configurations or addons

## Troubleshooting

If you encounter issues:

1. Check the [Storybook migration guide](https://storybook.js.org/docs/react/migration-guide) for framework-specific changes
2. Review the [Nx Storybook documentation](/docs/technologies/test-tools/storybook/introduction)
3. Report issues on the [Nx GitHub](https://github.com/nrwl/nx/issues/new/choose) or [Storybook GitHub](https://github.com/storybookjs/storybook/issues/new/choose)

---
<!-- source: https://nx.dev/docs/technologies/test-tools/storybook/introduction.md -->
## Storybook Plugin for Nx

[Storybook](https://storybook.js.org) is a development environment for UI components. Browse a component library, view the different states of each component, and interactively develop and test components.

Briefly walk you through using Storybook within an Nx workspace.

## Requirements

The `@nx/storybook` plugin supports the following package versions.

| Package     | Supported Versions |
| ----------- | ------------------ |
| `storybook` | >=8.0.0 <11.0.0    |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

<!-- The peerDependencies in @nx/storybook's package.json declares >=7.0.0 so that
     users who still have Storybook 7 installed get a friendlier error from Nx
     rather than a cryptic package-manager resolution failure. Storybook 7 is
     no longer actively supported. -->

## Setting up Storybook

### Installation

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/storybook` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
{% /aside %}

In any Nx workspace, you can install `@nx/storybook` by running the following command:

```shell
nx add @nx/storybook
```

This will install the correct version of `@nx/storybook`.

### How @nx/storybook infers tasks

The `@nx/storybook` plugin will create a task for any project that has a Storybook configuration file present. Any of the following files will be recognized as a Storybook configuration file:

- `.storybook/main.js`
- `.storybook/main.ts`
- `.storybook/main.cjs`
- `.storybook/main.cts`
- `.storybook/main.mjs`
- `.storybook/main.mts`

### View inferred tasks

To view inferred tasks for a project, open the [project details view](/docs/concepts/inferred-tasks) in Nx Console or run `nx show project my-project --web` in the command line.

### @nx/storybook configuration

The `@nx/storybook/plugin` is configured in the `plugins` array in `nx.json`.

```json frame="none"
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/storybook/plugin",
      "options": {
        "buildStorybookTargetName": "build-storybook",
        "serveStorybookTargetName": "storybook",
        "testStorybookTargetName": "test-storybook",
        "staticStorybookTargetName": "static-storybook"
      }
    }
  ]
}
```

The `builtStorybookTargetName`, `serveStorybookTargetName`, `testStorybookTargetName` and `staticStorybookTargetName` options control the names of the inferred Storybook tasks. The default names are `build-storybook`, `storybook`, `test-storybook` and `static-storybook`.

## Using Storybook

### Generating Storybook configuration

You can generate Storybook configuration for an individual project with this command:

```shell
nx g @nx/storybook:configuration project-name
```

or

{% tabs %}
{% tabitem label="Angular" %}

```shell
nx g @nx/angular:storybook-configuration my-angular-project
```

{% /tabitem %}
{% tabitem label="React" %}

```shell
nx g @nx/react:storybook-configuration my-react-project
```

{% /tabitem %}
{% tabitem label="Vue" %}

```shell
nx g @nx/vue:storybook-configuration my-vue-project
```

{% /tabitem %}
{% /tabs %}

These framework-specific generators will also **generate stories** and interaction tests for you.

If you are NOT using a framework-specific generator (for [Angular](/docs/technologies/angular/generators#storybook-configuration), [React](/docs/technologies/react/generators#storybook-configuration), [Vue](/docs/technologies/vue/generators#storybook-configuration)), in the field `uiFramework` you must choose one of the following Storybook frameworks:

- `@storybook/angular`
- `@storybook/nextjs`
- `@storybook/react-webpack5`
- `@storybook/react-vite`
- `@storybook/server-webpack5`
- `@storybook/svelte-vite`
- `@storybook/sveltekit`
- `@storybook/vue-vite`
- `@storybook/vue3-vite`
- `@storybook/web-components-vite`

Choosing one of these frameworks will have the following effects on your workspace:

1. Nx will install all the required Storybook packages that go with it.

2. Nx will generate a project-level `.storybook` folder (located under `libs/your-project/.storybook` or `apps/your-project/.storybook`) containing the essential configuration files for Storybook.

3. Nx will create new `targets` in your project's `project.json`, called `storybook`, `test-storybook` and `build-storybook`, containing all the necessary configuration to serve, test and build Storybook.

Make sure to **use the framework-specific generators** if your project is using Angular, React, Next.js, Vue, Nuxt, or React Native: [`@nx/angular:storybook-configuration`](/docs/technologies/angular/generators#storybook-configuration), [`@nx/react:storybook-configuration`](/docs/technologies/react/generators#storybook-configuration), [`@nx/vue:storybook-configuration`](/docs/technologies/vue/generators#storybook-configuration) as shown above.

### Running Storybook

Serve Storybook using this command:

```shell
nx run project-name:storybook
```

or

```shell
nx storybook project-name
```

### Building Storybook

Build Storybook using this command:

```shell
nx run project-name:build-storybook
```

or

```shell
nx build-storybook project-name
```

### Testing Storybook

With the Storybook server running, you can test Storybook (run all the interaction tests) using this command:

```shell
nx run project-name:test-storybook
```

or

```shell
nx test-storybook project-name
```

### Anatomy of the Storybook setup

When running the Nx Storybook generator, it configures the Nx workspace to run Storybook and creates a project-specific Storybook configuration.

The project-specific Storybook configuration is pretty much similar to what you would have for a non-Nx setup of Storybook. There's a `.storybook` folder within the project root folder.

```text frame="none"
<project root>/
├── .storybook/
│   ├── main.ts
│   └── preview.ts
├── src/
├── README.md
├── tsconfig.json
├── tsconfig.storybook.json
└── etc...
```

### Using addons

To register a [Storybook addon](https://storybook.js.org/addons/) for all Storybook instances in your workspace:

1. In your project's `.storybook/main.ts` file, in the `addons` array of the `module.exports` object, add the new addon:

```typescript frame="none"
// <project-path>/.storybook/main.ts
import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = {
  ...
  addons: ['@storybook/addon-essentials', '@storybook/addon-interactions', ...],
  ...
};

export default config;
```

2. If a decorator is required, in each project's `<project-path>/.storybook/preview.ts`, you can export an array called `decorators`.

   ```typescript frame="none"
   // <project-path>/.storybook/preview.ts
   import someDecorator from 'some-storybook-addon';
   export const decorators = [someDecorator];
   ```

### Setting up documentation

To set up documentation, you can use [Storybook Autodocs](https://storybook.js.org/docs/react/writing-docs/autodocs). For Angular, [you can use `compodoc`](/docs/technologies/test-tools/storybook/guides/angular-storybook-compodoc) to infer `argTypes`. You can read more about `argTypes` in the [official Storybook `argTypes` documentation](https://storybook.js.org/docs/angular/api/argtypes#automatic-argtype-inference).

You can read more about how to best set up documentation using Storybook for your project in the [official Storybook documentation](https://storybook.js.org/docs/react/writing-docs/introduction).

## More documentation

You can find dedicated information for React and Angular:

- [Set up Storybook for Angular Projects](/docs/technologies/test-tools/storybook/guides/overview-angular)
- [Set up Storybook for React Projects](/docs/technologies/test-tools/storybook/guides/overview-react)
- [Set up Storybook for Vue Projects](/docs/technologies/test-tools/storybook/guides/overview-vue)

You can find all Storybook-related Nx documentation in the [Storybook guides section](/docs/technologies/test-tools/storybook/guides).

For more on using Storybook, see the [official Storybook documentation](https://storybook.js.org/docs/basics/introduction/).

### Migration scenarios

Here's more information on common migration scenarios for Storybook with Nx. For Storybook specific migrations that are not automatically handled by Nx please refer to the [official Storybook page](https://storybook.js.org/)

- [Upgrading Storybook guide](/docs/technologies/test-tools/storybook/guides/upgrading-storybook)
- [Storybook 10 migration generator](/docs/technologies/test-tools/storybook/generators#migrate-10)

---
<!-- source: https://nx.dev/docs/technologies/test-tools/storybook/migrations.md -->
## @nx/storybook Migrations

The @nx/storybook plugin provides various migrations to help you migrate to newer versions of storybook projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 22.2.x

### 22.2.0-package-updates
**Version**: 22.2.0-beta.1


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@storybook/angular` | `^10.1.0` | Updated only
| `@storybook/react` | `^10.1.0` | Updated only
| `storybook` | `^10.1.0` | Added if not installed
| `@storybook/addon-onboarding` | `^10.1.0` | Updated only
| `@storybook/addon-themes` | `^10.1.0` | Updated only
| `@storybook/builder-webpack5` | `^10.1.0` | Updated only
| `@storybook/core-webpack` | `^10.1.0` | Updated only
| `@storybook/html` | `^10.1.0` | Updated only
| `@storybook/html-vite` | `^10.1.0` | Updated only
| `@storybook/nextjs` | `^10.1.0` | Updated only
| `@storybook/preact` | `^10.1.0` | Updated only
| `@storybook/preact-vite` | `^10.1.0` | Updated only
| `@storybook/react-vite` | `^10.1.0` | Updated only
| `@storybook/react-webpack5` | `^10.1.0` | Updated only
| `@storybook/server` | `^10.1.0` | Updated only
| `@storybook/server-webpack5` | `^10.1.0` | Updated only
| `@storybook/svelte` | `^10.1.0` | Updated only
| `@storybook/svelte-vite` | `^10.1.0` | Updated only
| `@storybook/sveltekit` | `^10.1.0` | Updated only
| `@storybook/vue3` | `^10.1.0` | Updated only
| `@storybook/vue3-vite` | `^10.1.0` | Updated only
| `@storybook/web-components` | `^10.1.0` | Updated only
| `@storybook/web-components-vite` | `^10.1.0` | Updated only



## 22.1.x

### `update-22-1-0-migrate-storybook-v10`
**Version**: 22.1.0-beta.8

Update workspace to use Storybook v10

#### Requires

| Name | Version |
|------|---------|
 `storybook` | `>=10.0.0` |

### 21.1.0-package-updates
**Version**: 22.1.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@storybook/angular` | `^9.0.5` | Updated only
| `@storybook/react` | `^9.0.5` | Updated only
| `storybook` | `^9.0.5` | Added if not installed
| `@storybook/addon-onboarding` | `^9.0.5` | Updated only
| `@storybook/addon-themes` | `^9.0.5` | Updated only
| `@storybook/builder-webpack5` | `^9.0.5` | Updated only
| `@storybook/core-webpack` | `^9.0.5` | Updated only
| `@storybook/html` | `^9.0.5` | Updated only
| `@storybook/html-vite` | `^9.0.5` | Updated only
| `@storybook/nextjs` | `^9.0.5` | Updated only
| `@storybook/preact` | `^9.0.5` | Updated only
| `@storybook/preact-vite` | `^9.0.5` | Updated only
| `@storybook/react-vite` | `^9.0.5` | Updated only
| `@storybook/react-webpack5` | `^9.0.5` | Updated only
| `@storybook/server` | `^9.0.5` | Updated only
| `@storybook/server-webpack5` | `^9.0.5` | Updated only
| `@storybook/svelte` | `^9.0.5` | Updated only
| `@storybook/svelte-vite` | `^9.0.5` | Updated only
| `@storybook/sveltekit` | `^9.0.5` | Updated only
| `@storybook/vue3` | `^9.0.5` | Updated only
| `@storybook/vue3-vite` | `^9.0.5` | Updated only
| `@storybook/web-components` | `^9.0.5` | Updated only
| `@storybook/web-components-vite` | `^9.0.5` | Updated only


### 22.1.0-package-updates
**Version**: 22.1.0-beta.8


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@storybook/angular` | `^10.0.0` | Updated only
| `@storybook/react` | `^10.0.0` | Updated only
| `storybook` | `^10.0.0` | Added if not installed
| `@storybook/addon-onboarding` | `^10.0.0` | Updated only
| `@storybook/addon-themes` | `^10.0.0` | Updated only
| `@storybook/builder-webpack5` | `^10.0.0` | Updated only
| `@storybook/core-webpack` | `^10.0.0` | Updated only
| `@storybook/html` | `^10.0.0` | Updated only
| `@storybook/html-vite` | `^10.0.0` | Updated only
| `@storybook/nextjs` | `^10.0.0` | Updated only
| `@storybook/preact` | `^10.0.0` | Updated only
| `@storybook/preact-vite` | `^10.0.0` | Updated only
| `@storybook/react-vite` | `^10.0.0` | Updated only
| `@storybook/react-webpack5` | `^10.0.0` | Updated only
| `@storybook/server` | `^10.0.0` | Updated only
| `@storybook/server-webpack5` | `^10.0.0` | Updated only
| `@storybook/svelte` | `^10.0.0` | Updated only
| `@storybook/svelte-vite` | `^10.0.0` | Updated only
| `@storybook/sveltekit` | `^10.0.0` | Updated only
| `@storybook/vue3` | `^10.0.0` | Updated only
| `@storybook/vue3-vite` | `^10.0.0` | Updated only
| `@storybook/web-components` | `^10.0.0` | Updated only
| `@storybook/web-components-vite` | `^10.0.0` | Updated only



## 21.2.x

### `update-21-2-0-migrate-storybook-v9`
**Version**: 21.2.0-beta.3

Update workspace to use Storybook v9


### `update-21-2-0-remove-addon-dependencies`
**Version**: 21.2.0-beta.3

Remove deprecated Storybook addon dependencies



## 20.8.x

### 20.8.0-package-updates
**Version**: 20.8.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@storybook/test-runner` | `^0.22.0` | Updated only
| `@storybook/core-server` | `^8.6.11` | Updated only
| `@storybook/angular` | `^8.6.11` | Updated only
| `@storybook/react` | `^8.6.11` | Updated only
| `@storybook/react-vite` | `^8.6.11` | Updated only
| `@storybook/react-webpack5` | `^8.6.11` | Updated only
| `@storybook/web-components-vite` | `^8.6.11` | Updated only
| `@storybook/web-components-webpack5` | `^8.6.11` | Updated only
| `@storybook/addon-a11y` | `^8.6.11` | Updated only
| `@storybook/addon-actions` | `^8.6.11` | Updated only
| `@storybook/addon-backgrounds` | `^8.6.11` | Updated only
| `@storybook/addon-controls` | `^8.6.11` | Updated only
| `@storybook/addon-docs` | `^8.6.11` | Updated only
| `@storybook/addon-essentials` | `^8.6.11` | Updated only
| `@storybook/addon-interactions` | `^8.6.11` | Updated only
| `@storybook/addon-mdx-gfm` | `^8.6.11` | Updated only
| `@storybook/addon-highlight` | `^8.6.11` | Updated only
| `@storybook/addon-jest` | `^8.6.11` | Updated only
| `@storybook/addon-links` | `^8.6.11` | Updated only
| `@storybook/addon-measure` | `^8.6.11` | Updated only
| `@storybook/addon-outline` | `^8.6.11` | Updated only
| `@storybook/addon-storysource` | `^8.6.11` | Updated only
| `@storybook/addon-toolbars` | `^8.6.11` | Updated only
| `@storybook/addon-viewport` | `^8.6.11` | Updated only
| `@storybook/vue3` | `^8.6.11` | Updated only
| `@storybook/vue3-vite` | `^8.6.11` | Updated only
| `@storybook/addon-onboarding` | `^8.6.11` | Updated only
| `@storybook/addon-themes` | `^8.6.11` | Updated only
| `@storybook/blocks` | `^8.6.11` | Updated only
| `@storybook/builder-manager` | `^8.6.11` | Updated only
| `@storybook/builder-webpack5` | `^8.6.11` | Updated only
| `@storybook/cli` | `^8.6.11` | Updated only
| `@storybook/components` | `^8.6.11` | Updated only
| `@storybook/core` | `^8.6.11` | Updated only
| `@storybook/core-common` | `^8.6.11` | Updated only
| `@storybook/core-events` | `^8.6.11` | Updated only
| `@storybook/core-webpack` | `^8.6.11` | Updated only
| `@storybook/csf-tools` | `^8.6.11` | Updated only
| `@storybook/html` | `^8.6.11` | Updated only
| `@storybook/html-vite` | `^8.6.11` | Updated only
| `@storybook/html-webpack5` | `^8.6.11` | Updated only
| `@storybook/manager` | `^8.6.11` | Updated only
| `@storybook/manager-api` | `^8.6.11` | Updated only
| `@storybook/nextjs` | `^8.6.11` | Updated only
| `@storybook/preact` | `^8.6.11` | Updated only
| `@storybook/preact-vite` | `^8.6.11` | Updated only
| `@storybook/preact-webpack5` | `^8.6.11` | Updated only
| `@storybook/preset-create-react-app` | `^8.6.11` | Updated only
| `@storybook/preset-html-webpack` | `^8.6.11` | Updated only
| `@storybook/preset-preact-webpack` | `^8.6.11` | Updated only
| `@storybook/preset-react-webpack` | `^8.6.11` | Updated only
| `@storybook/preset-server-webpack` | `^8.6.11` | Updated only
| `@storybook/preset-vue3-webpack` | `^8.6.11` | Updated only
| `@storybook/router` | `^8.6.11` | Updated only
| `@storybook/server` | `^8.6.11` | Updated only
| `@storybook/server-webpack5` | `^8.6.11` | Updated only
| `@storybook/svelte` | `^8.6.11` | Updated only
| `@storybook/svelte-vite` | `^8.6.11` | Updated only
| `@storybook/sveltekit` | `^8.6.11` | Updated only
| `@storybook/theming` | `^8.6.11` | Updated only
| `@storybook/types` | `^8.6.11` | Updated only
| `@storybook/vue3-webpack5` | `^8.6.11` | Updated only
| `@storybook/web-components` | `^8.6.11` | Updated only



## 20.2.x

### 20.2.0-package-updates
**Version**: 20.2.0-beta.5


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@storybook/test-runner` | `^0.19.0` | Updated only
| `@storybook/core-server` | `^8.4.6` | Updated only
| `@storybook/angular` | `^8.4.6` | Updated only
| `@storybook/react` | `^8.4.6` | Updated only
| `@storybook/react-vite` | `^8.4.6` | Updated only
| `@storybook/react-webpack5` | `^8.4.6` | Updated only
| `@storybook/web-components-vite` | `^8.4.6` | Updated only
| `@storybook/web-components-webpack5` | `^8.4.6` | Updated only
| `@storybook/addon-a11y` | `^8.4.6` | Updated only
| `@storybook/addon-actions` | `^8.4.6` | Updated only
| `@storybook/addon-backgrounds` | `^8.4.6` | Updated only
| `@storybook/addon-controls` | `^8.4.6` | Updated only
| `@storybook/addon-docs` | `^8.4.6` | Updated only
| `@storybook/addon-essentials` | `^8.4.6` | Updated only
| `@storybook/addon-interactions` | `^8.4.6` | Updated only
| `@storybook/addon-mdx-gfm` | `^8.4.6` | Updated only
| `@storybook/addon-highlight` | `^8.4.6` | Updated only
| `@storybook/addon-jest` | `^8.4.6` | Updated only
| `@storybook/addon-links` | `^8.4.6` | Updated only
| `@storybook/addon-measure` | `^8.4.6` | Updated only
| `@storybook/addon-outline` | `^8.4.6` | Updated only
| `@storybook/addon-storysource` | `^8.4.6` | Updated only
| `@storybook/addon-toolbars` | `^8.4.6` | Updated only
| `@storybook/addon-viewport` | `^8.4.6` | Updated only
| `@storybook/vue3` | `^8.4.6` | Updated only
| `@storybook/vue3-vite` | `^8.4.6` | Updated only
| `@storybook/addon-onboarding` | `^8.4.6` | Updated only
| `@storybook/addon-themes` | `^8.4.6` | Updated only
| `@storybook/blocks` | `^8.4.6` | Updated only
| `@storybook/builder-manager` | `^8.4.6` | Updated only
| `@storybook/builder-webpack5` | `^8.4.6` | Updated only
| `@storybook/cli` | `^8.4.6` | Updated only
| `@storybook/components` | `^8.4.6` | Updated only
| `@storybook/core` | `^8.4.6` | Updated only
| `@storybook/core-common` | `^8.4.6` | Updated only
| `@storybook/core-events` | `^8.4.6` | Updated only
| `@storybook/core-webpack` | `^8.4.6` | Updated only
| `@storybook/csf-tools` | `^8.4.6` | Updated only
| `@storybook/html` | `^8.4.6` | Updated only
| `@storybook/html-vite` | `^8.4.6` | Updated only
| `@storybook/html-webpack5` | `^8.4.6` | Updated only
| `@storybook/manager` | `^8.4.6` | Updated only
| `@storybook/manager-api` | `^8.4.6` | Updated only
| `@storybook/nextjs` | `^8.4.6` | Updated only
| `@storybook/preact` | `^8.4.6` | Updated only
| `@storybook/preact-vite` | `^8.4.6` | Updated only
| `@storybook/preact-webpack5` | `^8.4.6` | Updated only
| `@storybook/preset-create-react-app` | `^8.4.6` | Updated only
| `@storybook/preset-html-webpack` | `^8.4.6` | Updated only
| `@storybook/preset-preact-webpack` | `^8.4.6` | Updated only
| `@storybook/preset-react-webpack` | `^8.4.6` | Updated only
| `@storybook/preset-server-webpack` | `^8.4.6` | Updated only
| `@storybook/preset-vue3-webpack` | `^8.4.6` | Updated only
| `@storybook/router` | `^8.4.6` | Updated only
| `@storybook/server` | `^8.4.6` | Updated only
| `@storybook/server-webpack5` | `^8.4.6` | Updated only
| `@storybook/svelte` | `^8.4.6` | Updated only
| `@storybook/svelte-vite` | `^8.4.6` | Updated only
| `@storybook/sveltekit` | `^8.4.6` | Updated only
| `@storybook/theming` | `^8.4.6` | Updated only
| `@storybook/types` | `^8.4.6` | Updated only
| `@storybook/vue3-webpack5` | `^8.4.6` | Updated only
| `@storybook/web-components` | `^8.4.6` | Updated only

---
<!-- source: https://nx.dev/docs/technologies/test-tools/vitest.md -->
## Vitest

{% index_page_cards path="technologies/test-tools/vitest" /%}

---
<!-- source: https://nx.dev/docs/technologies/test-tools/vitest/executors.md -->
## @nx/vitest Executors

The @nx/vitest plugin provides various executors to help you create and configure vitest projects within your Nx workspace.
Below is a complete reference for all available executors and their options.

### `test`
Test using Vitest.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `configFile` | string | The path to the local vitest config, relative to the workspace root. |  |
| `mode` | string | Vite mode for loading configuration. |  |
| `reportsDirectory` | string | Directory to write coverage report to. |  |
| `runMode` | string | Vitest execution mode. | `"test"` |
| `testFiles` | array |  |  |
| `watch` | boolean | Watch files for changes and rerun tests related to changed files. |  |

---
<!-- source: https://nx.dev/docs/technologies/test-tools/vitest/generators.md -->
## @nx/vitest Generators

The @nx/vitest plugin provides various generators to help you create and configure vitest projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `configuration`
Generate a Vitest setup for a project.

**Usage:**
```bash
nx generate @nx/vitest:configuration [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string [**required**] | The name of the project to test. |  |
| `--compiler` | string | The compiler to use | `"babel"` |
| `--coverageProvider` | string | Coverage provider to use. | `"v8"` |
| `--inSourceTests` | boolean | Do not generate separate spec files and set up in-source testing. | `false` |
| `--runtimeTsconfigFileName` | string | The name of the project's tsconfig file that includes the runtime source files. If not provided, it will default to `tsconfig.lib.json` for libraries and `tsconfig.app.json` for applications. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--skipViteConfig` | boolean | Skip generating a vite config file. | `false` |
| `--testEnvironment` | string | The vitest environment to use. See https://vitest.dev/config/#environment. |  |
| `--testTarget` | string | The test target of the project to be transformed to use the @nx/vitest:test executor. |  |
| `--uiFramework` | string | UI framework to use with vitest. |  |
| `--zoneless` | boolean | Whether the Angular project is zoneless. When not provided, it is auto-detected from the project configuration. |  |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/vitest:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/test-tools/vitest/guides.md -->
## Guides

{% index_page_cards path="technologies/test-tools/vitest/guides" /%}

---
<!-- source: https://nx.dev/docs/technologies/test-tools/vitest/guides/migrating-from-nx-vite.md -->
## Migrating to @nx/vitest from @nx/vite

# Migrating from @nx/vite to @nx/vitest

## Overview

Vitest functionality has been split from `@nx/vite` into a standalone `@nx/vitest` package. This provides better separation of concerns and allows vitest to be used independently of vite.

## What changed

### Generators

- `@nx/vite:vitest` → `@nx/vitest:configuration`

### Executors

- `@nx/vite:test` → `@nx/vitest:test`

### Plugins

- `@nx/vite/plugin` (for vitest) → `@nx/vitest`

## Migration steps

### 1. Install @nx/vitest

```bash
npm install --save-dev @nx/vitest
# or
pnpm add -D @nx/vitest
# or
yarn add -D @nx/vitest
```

### 2. Update project.json

**Before:**

```json
{
  "targets": {
    "test": {
      "executor": "@nx/vite:test",
      "options": {
        "config": "vite.config.ts"
      }
    }
  }
}
```

**After:**

```json
{
  "targets": {
    "test": {
      "executor": "@nx/vitest:test",
      "options": {
        "config": "vite.config.ts"
      }
    }
  }
}
```

### 3. Update nx.json (if using plugin)

**Before:**

```json
{
  "plugins": [
    {
      "plugin": "@nx/vite/plugin",
      "options": {
        "testTargetName": "test"
      }
    }
  ]
}
```

**After:**

```json
{
  "plugins": [
    {
      "plugin": "@nx/vitest",
      "options": {
        "testTargetName": "test"
      }
    }
  ]
}
```

### 4. Update future generator usage

When adding vitest to new projects:

```bash
# Old
nx g @nx/vite:vitest my-project

# New
nx g @nx/vitest:configuration my-project
```

## Backward compatibility

The old `@nx/vite:vitest` generator and `@nx/vite:test` executor still work but are deprecated. They will be removed in Nx 23. Please migrate before upgrading to Nx 23.

When you use the deprecated generators/executors, you'll see a warning message:

```text
The '@nx/vite:vitest' generator is deprecated. Please use '@nx/vitest:configuration' instead.
This generator will be removed in Nx 23.
```

## No changes required for these files

- **vite.config.ts / vitest.config.ts**: No changes needed
- **Test files**: No changes needed
- **vitest.config.ts**: No changes needed

## Questions?

File an issue at https://github.com/nrwl/nx/issues

---
<!-- source: https://nx.dev/docs/technologies/test-tools/vitest/guides/testing-without-building-dependencies.md -->
## Testing Without Building Dependencies

When using [TypeScript project references](/docs/concepts/typescript-project-linking) in a monorepo, you might find that running tests requires building all dependency libraries first. This can slow down the test feedback loop, especially during development. This guide shows how to configure Vitest to resolve imports directly to source TypeScript files, eliminating the need to build dependencies before running tests.

## Prerequisites

- A workspace using [TypeScript project references with package manager workspaces](/docs/technologies/typescript/guides/switch-to-workspaces-project-references)
- Vitest configured for testing your projects

## How it works

The solution uses **custom export conditions** to tell both TypeScript and Vitest to resolve imports to source `.ts` files instead of built `.js` files. This requires three pieces working together:

1. **`customConditions`** in `tsconfig.base.json` tells TypeScript to recognize a custom export condition
2. **Library `package.json` exports** include the custom condition pointing to source files
3. **`resolve.conditions`** in Vitest config tells Vite to use the same condition at runtime

The good news is that **Nx already configures the first two pieces for you** in new workspaces created with workspaces enabled.

## What Nx configures for you

When you create a new Nx workspace with workspaces enabled (the default), Nx automatically sets up:

### tsconfig.base.json

```json
// tsconfig.base.json
{
  "compilerOptions": {
    "customConditions": ["@myorg/source"]
    // ... other options
  }
}
```

### Library package.json exports

```json
// libs/my-lib/package.json
{
  "name": "@myorg/my-lib",
  "exports": {
    ".": {
      "@myorg/source": "./src/index.ts",
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "default": "./dist/index.js"
    }
  }
}
```

The `@myorg/source` condition points to the source TypeScript file, while the other conditions point to built output. TypeScript uses `customConditions` to resolve types correctly in your IDE, and Vitest needs to be told to use this condition as well.

## Configure Vitest

Add `resolve.conditions` to your `vitest.config.mts` (or `vitest.config.ts`) file:

```ts
// vitest.config.mts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  resolve: {
    conditions: ['@myorg/source'],
  },
  test: {
    globals: true,
    environment: 'node',
    include: ['src/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
  },
});
```

This tells Vite (which powers Vitest) to prefer the `@myorg/source` export condition when resolving imports. Now when your test imports `@myorg/my-lib`, it will resolve directly to `./src/index.ts` instead of requiring the built `./dist/index.js`.

{% aside type="caution" title="Use a Separate Config for Testing" %}
If you also use Vite to **build** your project, keep the `resolve.conditions` configuration in a separate `vitest.config.mts` file rather than in `vite.config.mts`. Vitest automatically merges configuration from both files, so you only need to add the test-specific settings (like `resolve.conditions` and `test` options) to your `vitest.config.mts`. This ensures that your production build still resolves to built artifacts while tests resolve to source files.
{% /aside %}

## For migrated workspaces

If you migrated from an older Nx setup or TypeScript path aliases, you may need to manually add the configuration that Nx now generates automatically.

### Step 1: Add customConditions to tsconfig.base.json

Add the `customConditions` array to your `tsconfig.base.json`:

```json
// tsconfig.base.json
{
  "compilerOptions": {
    "customConditions": ["@myorg/source"],
    "composite": true,
    "declaration": true
    // ... other options
  }
}
```

{% aside type="note" title="Condition Naming" %}
You can use any condition name you like (e.g., `@myorg/source`). Just make sure to use the same name consistently across all configuration files. Using an organization-scoped name avoids conflicts with conditions that third-party packages might define.
{% /aside %}

### Step 2: Update Library package.json Exports

Update each library's `package.json` to include the custom condition in exports:

{% tabs %}
{% tabitem label="Before" %}

```json
// libs/my-lib/package.json
{
  "name": "@myorg/my-lib",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "default": "./dist/index.js"
    }
  }
}
```

{% /tabitem %}
{% tabitem label="After" %}

```json
// libs/my-lib/package.json
{
  "name": "@myorg/my-lib",
  "exports": {
    ".": {
      "@myorg/source": "./src/index.ts",
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "default": "./dist/index.js"
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

The order matters: export conditions are evaluated from top to bottom. When `@myorg/source` is recognized (by TypeScript or Vitest), it will be used. Otherwise, the resolver falls back to `types`, `import`, or `default`.

### Step 3: Configure Vitest

Follow the [Configure Vitest](#configure-vitest) section above to add `resolve.conditions` to your Vitest config.

## Removing dependsOn from test targets

If your test targets previously included `dependsOn: ["^build"]` to ensure dependencies were built before testing, you can now remove this:

{% tabs %}
{% tabitem label="Before" %}

```json
// project.json
{
  "targets": {
    "test": {
      "executor": "@nx/vitest:test",
      "dependsOn": ["^build"],
      "options": {
        "config": "vitest.config.mts"
      }
    }
  }
}
```

{% /tabitem %}
{% tabitem label="After" %}

```json
// project.json
{
  "targets": {
    "test": {
      "executor": "@nx/vitest:test",
      "options": {
        "config": "vitest.config.mts"
      }
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

This can significantly speed up your test runs, especially when you're iterating on changes across multiple libraries.

## Important considerations

- **IDE support**: TypeScript's `customConditions` setting ensures your IDE correctly resolves types to source files, giving you accurate IntelliSense and error checking
- **Live changes**: Tests now run against source files directly, so any changes you make are immediately reflected without rebuilding
- **Production builds**: Keep `resolve.conditions` out of your production Vite build config to ensure builds use the compiled artifacts

## Example repository

For a complete working example of this pattern, see the [vitest-test-without-build-example](https://github.com/Coly010/vitest-test-without-build-example) repository.

## Related documentation

- [TypeScript Project Linking](/docs/concepts/typescript-project-linking)
- [Switch to Workspaces and Project References](/docs/technologies/typescript/guides/switch-to-workspaces-project-references)
- [Vitest Introduction](/docs/technologies/test-tools/vitest/introduction)

---
<!-- source: https://nx.dev/docs/technologies/test-tools/vitest/introduction.md -->
## Vitest Plugin for Nx

[Vitest](https://vitest.dev) is a fast test runner built on Vite.

The `@nx/vitest` plugin adds [inferred Vitest targets](#configuration), a [project configuration generator](#add-vitest-to-a-project), and CI-friendly [test splitting](#ci-considerations).

You can use Vitest with Nx without the plugin and still get [task caching](/docs/features/cache-task-results), [task orchestration](/docs/features/run-tasks), and the [project graph](/docs/features/explore-graph).

## Requirements

The `@nx/vite` plugin supports the following package versions.

| Package  | Supported Versions                         |
| -------- | ------------------------------------------ |
| `vitest` | ^1.0.0 \|\| ^2.0.0 \|\| ^3.0.0 \|\| ^4.0.0 |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

## Setup

### Add to an existing workspace

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Install the `@nx/vitest` version that matches the version of `nx` in your workspace. If the version numbers get out of sync, you can encounter difficult to debug errors. Use the [version sync recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync) to fix mismatches.
Using `nx add` helps ensure the correct version is installed and configured.
{% /aside %}

```shell
nx add @nx/vitest
```

### Verify inferred tasks

Nx infers Vitest tasks from your Vitest or Vite config files. To confirm which targets were created, open the project details view in Nx Console or run:

```shell
nx show project my-app
```

### Add Vitest to a project

Use the configuration generator to set up a project with Vitest:

```shell
nx g @nx/vitest:configuration --project=my-app
```

The generator accepts framework-specific options. Pass the right flags for your project type:

{% tabs syncKey="framework" %}
{% tabitem label="React" %}

```shell
nx g @nx/vitest:configuration --project=my-react-lib --uiFramework=react
```

Sets up Vitest with React JSX support and `jsdom` test environment.

{% /tabitem %}
{% tabitem label="Vue" %}

```shell
nx g @nx/vitest:configuration --project=my-vue-lib --uiFramework=vue
```

Sets up Vitest with Vue SFC support and `jsdom` test environment.

{% /tabitem %}
{% tabitem label="Angular" %}

```shell
nx g @nx/vitest:configuration --project=my-angular-lib --uiFramework=angular
```

Configures Vitest for Angular with the appropriate test setup.

{% /tabitem %}
{% tabitem label="Node / TypeScript" %}

```shell
nx g @nx/vitest:configuration --project=my-node-lib --testEnvironment=node
```

Uses the `node` test environment instead of the default `jsdom`.

{% /tabitem %}
{% /tabs %}

See the full [configuration generator reference](/docs/technologies/test-tools/vitest/generators#configuration) for all options.

{% aside type="tip" title="Framework generators handle this automatically" %}
When generating a new project with a framework generator, you can specify Vitest as the test runner and Nx passes the correct options automatically:

```shell
nx g @nx/react:lib libs/my-react-lib --unitTestRunner=vitest
nx g @nx/vue:lib libs/my-vue-lib --unitTestRunner=vitest
```

{% /aside %}

## Local development

Run Vitest through Nx so caching and the project graph work together.

```shell
nx test my-app
```

```shell
nx test my-app --watch
```

```shell
nx test my-app -- MyComponent.spec.ts
```

```shell
nx test my-app --ui
```

```shell
nx test my-app --coverage
```

{% aside type="note" title="Replace the project name" %}
Replace `my-app` with the name of your project and the test file pattern with the file you want to run.
{% /aside %}

## Configuration

### How tasks are inferred

The `@nx/vitest` plugin creates a target for any project that has a Vitest or Vite config file with test settings. The plugin looks for:

- `vitest.config.js`
- `vitest.config.ts`
- `vitest.config.mjs`
- `vitest.config.mts`
- `vitest.config.cjs`
- `vitest.config.cts`
- `vite.config.js` (with `test` configuration)
- `vite.config.ts` (with `test` configuration)
- `vite.config.mjs` (with `test` configuration)
- `vite.config.mts` (with `test` configuration)
- `vite.config.cjs` (with `test` configuration)
- `vite.config.cts` (with `test` configuration)

To view inferred tasks, open the [project details view](/docs/concepts/inferred-tasks) in Nx Console or run `nx show project my-app`.

### Plugin options

Configure the plugin in `nx.json`:

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/vitest",
      "options": {
        "testTargetName": "test",
        "ciTargetName": "test-ci",
        "ciGroupName": "Unit Tests (CI)",
        "testMode": "watch"
      }
    }
  ]
}
```

| Option           | Type             | Default                     | Description                                                               |
| ---------------- | ---------------- | --------------------------- | ------------------------------------------------------------------------- |
| `testTargetName` | string           | `test`                      | Name of the inferred local target.                                        |
| `ciTargetName`   | string           | none                        | Creates a CI-only target used for atomized runs.                          |
| `ciGroupName`    | string           | derived from `ciTargetName` | Display name for the atomized CI group.                                   |
| `testMode`       | `watch` or `run` | `watch`                     | Determines whether Nx runs `vitest` (watch) or `vitest run` (single run). |

There is no single "disable" flag for inference. Use `include` and `exclude` to scope which projects each plugin instance applies to.

### Configure unit and e2e separately

If you use Vitest for unit and e2e tests, configure the plugin twice with different include and exclude patterns.

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/vitest",
      "exclude": ["e2e/**/*"],
      "options": {
        "testTargetName": "test",
        "testMode": "watch"
      }
    },
    {
      "plugin": "@nx/vitest",
      "include": ["e2e/**/*"],
      "options": {
        "testTargetName": "e2e",
        "ciTargetName": "e2e-ci",
        "ciGroupName": "E2E Tests (CI)",
        "testMode": "run"
      }
    }
  ]
}
```

## CI considerations

See [Set Up CI](/docs/guides/nx-cloud/setup-ci) for a complete CI configuration guide.

### Build and test only what changed

```shell
nx affected -t test
```

This uses the [project graph](/docs/features/explore-graph) to determine which projects are affected by your changes and only runs tasks for those.
Read more about [the benefits of `nx affected`](/docs/features/ci-features/affected).

### Remote caching

Share test and e2e cache results across your team and CI with [remote caching](/docs/features/ci-features/remote-cache):

```shell
nx connect
```

### Task splitting for slow tests

For slow test suites (e.g. E2E or integration tests), set `ciTargetName` to split tests by file for distributed CI runs. Each test file becomes its own cacheable CI task with better caching and retries. See [split e2e tasks](/docs/features/ci-features/split-e2e-tasks) for details.

If you use `testMode: "watch"` locally, use `testMode: "run"` for CI to keep runs deterministic.

### Feature-based testing

Organize tests by feature to get better cache hits and more targeted CI runs. See the [feature-based testing guide](/docs/guides/tips-n-tricks/feature-based-testing) for strategies on structuring tests in a monorepo.

## What's next

{% cardgrid %}
{% linkcard title="Vitest Config Reference" description="Learn about Vitest configuration options and defaults." href="https://vitest.dev/config/" /%}
{% linkcard title="Migrate from @nx/vite" description="Move Vitest tasks from the Vite plugin to @nx/vitest." href="/docs/technologies/test-tools/vitest/guides/migrating-from-nx-vite" /%}
{% linkcard title="Split E2E Tasks" description="Distribute E2E tests by file with atomized tasks." href="/docs/features/ci-features/split-e2e-tasks" /%}
{% linkcard title="Feature-Based Testing" description="Organize tests by feature for better caching and targeted CI." href="/docs/guides/tips-n-tricks/feature-based-testing" /%}
{% linkcard title="Vitest Generators Reference" description="Reference for @nx/vitest generators." href="/docs/technologies/test-tools/vitest/generators" /%}
{% linkcard title="Vitest Executors Reference" description="Reference for @nx/vitest executors." href="/docs/technologies/test-tools/vitest/executors" /%}
{% /cardgrid %}

---
<!-- source: https://nx.dev/docs/technologies/test-tools/vitest/migrations.md -->
## @nx/vitest Migrations

The @nx/vitest plugin provides various migrations to help you migrate to newer versions of vitest projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 22.6.x

### `update-22-6-0-prefix-reports-directory`
**Version**: 22.6.0-beta.11

Prefix reportsDirectory with {projectRoot} to maintain correct resolution after workspace-root-relative behavior change.

#### Prefix `reportsDirectory` with `{projectRoot}`

The `reportsDirectory` option for `@nx/vitest:test` (and `@nx/vite:test`) is now resolved relative to the workspace root instead of the project root. This migration prepends `{projectRoot}/` to existing `reportsDirectory` values so the resolved path remains the same.

#### Sample Code Changes

##### Before

```json title="project.json"
{
  "targets": {
    "test": {
      "executor": "@nx/vitest:test",
      "options": {
        "reportsDirectory": "coverage/libs/my-lib"
      }
    }
  }
}
```

##### After

```json title="project.json" {6}
{
  "targets": {
    "test": {
      "executor": "@nx/vitest:test",
      "options": {
        "reportsDirectory": "{projectRoot}/coverage/libs/my-lib"
      }
    }
  }
}
```




## 22.3.x

### `update-22-3-2`
**Version**: 22.3.2-beta.0

Create AI Instructions to help migrate users workspaces past breaking changes for Vitest 4.

#### Requires

| Name | Version |
|------|---------|
 `@angular/build` | `>=21.0.0` |

### 22.3.2-package-updates
**Version**: 22.3.2-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `vitest` | `^4.0.8` | Updated only
| `@vitest/coverage-v8` | `^4.0.8` | Updated only
| `@vitest/coverage-istanbul` | `^4.0.8` | Updated only
| `@vitest/ui` | `^4.0.8` | Updated only
| `jsdom` | `^27.1.0` | Updated only


### 22.3.2-analog-package-updates
**Version**: 22.3.2-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@analogjs/vite-plugin-angular` | `~2.2.0` | Updated only
| `@analogjs/vitest-angular` | `~2.2.0` | Updated only



## 22.2.x

### 22.2.0-analog-package-updates
**Version**: 22.2.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@analogjs/vite-plugin-angular` | `~2.1.2` | Updated only
| `@analogjs/vitest-angular` | `~2.1.2` | Updated only



## 22.1.x

### `update-22-1-0`
**Version**: 22.1.0-beta.8

Create AI Instructions to help migrate users workspaces past breaking changes for Vitest 4.


### 22.1.0-package-updates
**Version**: 22.1.0-beta.8


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `vitest` | `^4.0.0` | Updated only
| `@vitest/coverage-v8` | `^4.0.0` | Updated only
| `@vitest/coverage-istanbul` | `^4.0.0` | Updated only
| `@vitest/ui` | `^4.0.0` | Updated only



## 20.3.x

### `update-20-3-0`
**Version**: 20.3.0-beta.2

Add gitignore entry for temporary vitest config files.

#### Add Vitest Temp Files to Git Ignore

Add gitignore entry for temporary vitest config files.

#### Sample Code Changes

Adds the following entries to the `.gitignore` file.

```text title=".gitignore"
vite.config.*.timestamp*
vitest.config.*.timestamp*
```

---
<!-- source: https://nx.dev/docs/technologies/typescript.md -->
## TypeScript

{% index_page_cards path="technologies/typescript" /%}

---
<!-- source: https://nx.dev/docs/technologies/typescript/executors.md -->
## @nx/js Executors

The @nx/js plugin provides various executors to help you create and configure js projects within your Nx workspace.
Below is a complete reference for all available executors and their options.

### `copy-workspace-modules`
Copies Workspace Modules into the output directory after a build to prepare it for use with Docker or alternatives.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `buildTarget` | string [**required**] | The build target that produces the output directory to transform. | `"build"` |
| `outputPath` | string | The output path to transform. Usually inferred from the outputs of the buildTarget. |  |

### `node`
Execute Nodejs applications.

The `@nx/js:node` executor runs the output of a build target. For example, an application uses esbuild ([`@nx/esbuild:esbuild`](/nx-api/esbuild/executors/esbuild)) to output the bundle to `dist/my-app` folder, which can then be executed by `@nx/js:node`.

`project.json`:

```json
"my-app": {
  "targets": {
    "serve": {
      "executor": "@nx/js:node",
      "options": {
        "buildTarget": "my-app:build"
      }
    },
    "build": {
      "executor": "@nx/esbuild:esbuild",
      "options": {
        "main": "my-app/src/main.ts",
        "output": ["dist/my-app"],
        //...
      }
    },
  }
}
```

```bash
npx nx serve my-app
```

### Examples

###### Pass extra Node CLI arguments

Using `runtimeArgs`, you can pass arguments to the underlying `node` command. For example, if you want to set [`--no-warnings`](https://nodejs.org/api/cli.html#--no-warnings) to silence all Node warnings, then add the following to the `project.json` file.

```json
"my-app": {
  "targets": {
    "serve": {
      "executor": "@nx/js:node",
      "options": {
        "runtimeArgs": ["--no-warnings"],
        //...
      },
    },
  }
}
```

###### Run all task dependencies

If your application build depends on other tasks, and you want those tasks to also be executed, then set the `runBuildTargetDependencies` to `true`. For example, a library may have a task to generate GraphQL schemas, which is consume by the application. In this case, you want to run the generate task before building and running the application.

This option is also useful when the build consumes a library from its output, not its source. For example, if an executor that supports `buildLibsFromSource` option has it set to `false` (e.g. [`@nx/webpack:webpack`](/nx-api/webpack/executors/webpack)).

Note that this option will increase the build time, so use it only when necessary.

```json
"my-app": {
  "targets": {
    "serve": {
      "executor": "@nx/js:node",
      "options": {
        "runBuildTargetDependencies": true,
        //...
      },
    },
  }
}
```
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `buildTarget` | string [**required**] | The target to run to build you the app. |  |
| `args` | array | Extra args when starting the app. | `[]` |
| `buildTargetOptions` | object | Additional options to pass into the build target. | `{}` |
| `debounce` | number | Delay in milliseconds to wait before restarting. Useful to batch multiple file changes events together. Set to zero (0) to disable. | `500` |
| `host` | string | The host to inspect the process on. | `"localhost"` |
| `inspect` | string | Ensures the app is starting with debugging. | `"inspect"` |
| `port` | number | The port to inspect the process on. Setting port to 0 will assign random free ports to all forked processes. | `9229` |
| `runBuildTargetDependencies` | boolean | Whether to run dependencies before running the build. Set this to true if the project does not build libraries from source (e.g. 'buildLibsFromSource: false'). | `false` |
| `runtimeArgs` | array | Extra args passed to the node process. | `[]` |
| `waitUntilTargets` | array | The targets to run before starting the node app. Listed in the form <project>:<target>. The main target will run once all listed targets have output something to the console. | `[]` |
| `watch` | boolean | Enable re-building when files change. | `true` |

### `prune-lockfile`
Creates a pruned lockfile based on the project dependencies and places it into the output directory.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `buildTarget` | string [**required**] | The build target that produces the output directory to place the pruned lockfile. | `"build"` |
| `outputPath` | string | The output path to place the pruned lockfile. Usually inferred from the outputs of the buildTarget. |  |

### `swc`
Builds using SWC.

### Examples

###### Custom swcrc

`@nx/js:swc` can compile your code with a custom `.swcrc`

```json title="libs/ts-lib/project.json"
{
  "build": {
    "executor": "@nx/js:swc",
    "options": {
      "outputPath": "dist/libs/ts-lib",
      "main": "libs/ts-lib/src/index.ts",
      "tsConfig": "libs/ts-lib/tsconfig.lib.json",
      "assets": ["libs/ts-lib/*.md"],
      "swcrc": "libs/ts-lib/.dev.swcrc"
    },
    "configurations": {
      "production": {
        "swcrc": "libs/ts-lib/.prod.swcrc"
      }
    }
  }
}
```
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `main` | string [**required**] | The name of the main entry-point file. |  |
| `outputPath` | string [**required**] | The output path of the generated files. |  |
| `tsConfig` | string [**required**] | The path to the Typescript configuration file. |  |
| `additionalEntryPoints` | array | Additional entry-points to add to exports field in the package.json file. |  |
| `assets` | array | List of static assets. | `[]` |
| `clean` | boolean | Remove previous output before build. | `true` |
| `generateExportsField` | boolean | Update the output package.json file's 'exports' field. This field is used by Node and bundles. | `false` |
| `generateLockfile` | boolean | Generate a lockfile (e.g. package-lock.json) that matches the workspace lockfile to ensure package versions match. | `false` |
| `includeIgnoredAssetFiles` | boolean | Include files that are ignored by .gitignore and .nxignore when copying assets. WARNING: Ignored files are not automatically considered when calculating the task hash. To ensure Nx tracks these files for caching, add them to your target's inputs using 'dependentTasksOutputs' or 'runtime' configuration. | `false` |
| `skipTypeCheck` | boolean | Whether to skip TypeScript type checking. | `false` |
| `stripLeadingPaths` | boolean | Remove leading directory from output (e.g. src). See: https://swc.rs/docs/usage/cli#--strip-leading-paths | `false` |
| `swcExclude` | array | List of SWC Glob/Regex to be excluded from compilation (https://swc.rs/docs/configuration/compilation#exclude). | `["./src/**/.*.spec.ts$","./**/.*.spec.ts$","./src/**/jest-setup.ts$","./**/jest-setup.ts$","./**/.*.js$"]` |
| `swcrc` | string | The path to the SWC configuration file. Default: .swcrc |  |
| `watch` | boolean | Enable re-building when files change. | `false` |

### `tsc`
Builds using TypeScript.

### Examples

###### Using TypeScript Transformer Plugins

`@nx/js:tsc` can run the [TypeScript Transformers](https://github.com/madou/typescript-transformer-handbook) by using the `transformers` option.

```json title="libs/ts-lib/project.json"
{
  "build": {
    "executor": "@nx/js:tsc",
    "options": {
      "outputPath": "dist/libs/ts-lib",
      "main": "libs/ts-lib/src/index.ts",
      "tsConfig": "libs/ts-lib/tsconfig.lib.json",
      "assets": ["libs/ts-lib/*.md"],
      "transformers": [
        "@nestjs/swagger/plugin",
        {
          "name": "@automapper/classes/transformer-plugin",
          "options": {}
        }
      ]
    }
  }
}
```

###### Batch mode execution

:::tip[Available since Nx 16.6.0]
The `@nx/js:tsc` batch implementation was introduced in Nx **16.6.0**.
:::

The `@nx/js:tsc` executor supports running multiple tasks in a single process. When running in batch mode, the executor uses the [TypeScript APIs for incremental builds](https://www.typescriptlang.org/docs/handbook/project-references.html#build-mode-for-typescript). This results in a much faster build time when compared to the default implementation (the bigger the task graph to run, the more the performance improvements).

:::danger[Experimental feature]
Executing tasks in batch mode is an experimental feature.
:::

:::tip[Requirements]
Building a project with the `@nx/js:tsc` executor in batch mode requires all dependent projects (excluding implicit dependencies) to be buildable and built using the `@nx/js:tsc` executor.
:::

To run your builds using the batch implementation, pass in `--batch` flag:

```shell
nx build ts-lib --batch
```

For optimal performance, you could set the `clean` option to `false`. Otherwise, the executor cleans the output folder before running the build, which results in the loss of the [`.tsbuildinfo` file](https://www.typescriptlang.org/tsconfig/#tsBuildInfoFile) and, consequently, the loss of important optimizations performed by TypeScript. This is not a requirement. Even if the `clean` option is not set to `false` there are other important optimizations that are performed by the batch implementation.

```json title="libs/ts-lib/project.json"
{
  "build": {
    "executor": "@nx/js:tsc",
    "options": {
      "outputPath": "dist/libs/ts-lib",
      "main": "libs/ts-lib/src/index.ts",
      "tsConfig": "libs/ts-lib/tsconfig.lib.json",
      "assets": ["libs/ts-lib/*.md"],
      "clean": false
    }
  }
}
```
#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `main` | string [**required**] | The name of the main entry-point file. |  |
| `outputPath` | string [**required**] | The output path of the generated files. |  |
| `tsConfig` | string [**required**] | The path to the Typescript configuration file. |  |
| `additionalEntryPoints` | array | Additional entry-points to add to exports field in the package.json file. Ignored when `generatePackageJson` is set to `false`. |  |
| `assets` | array | List of static assets. | `[]` |
| `clean` | boolean | Remove previous output before build. | `true` |
| `generateExportsField` | boolean | Update the output package.json file's 'exports' field. This field is used by Node and bundlers. Ignored when `generatePackageJson` is set to `false`. | `false` |
| `generateLockfile` | boolean | Generate a lockfile (e.g. package-lock.json) that matches the workspace lockfile to ensure package versions match. Ignored when `generatePackageJson` is set to `false`. | `false` |
| `generatePackageJson` | boolean | Generate package.json file in the output folder. | `true` |
| `includeIgnoredAssetFiles` | boolean | Include files that are ignored by .gitignore and .nxignore when copying assets. WARNING: Ignored files are not automatically considered when calculating the task hash. To ensure Nx tracks these files for caching, add them to your target's inputs using 'dependentTasksOutputs' or 'runtime' configuration. | `false` |
| `outputFileName` | string | The path to the main file relative to the outputPath |  |
| `rootDir` | string | Sets the rootDir for TypeScript compilation. When not defined, it uses the root of project. |  |
| `transformers` | array | List of TypeScript Transformer Plugins. | `[]` |
| `watch` | boolean | Enable re-building when files change. | `false` |

### `verdaccio`
Start a local registry with Verdaccio.


#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `port` | number [**required**] | Port of local registry that Verdaccio should listen to |  |
| `clear` | boolean | Clear local registry storage before starting Verdaccio | `true` |
| `config` | string | Path to the custom Verdaccio config file |  |
| `listenAddress` | string | Listen address that Verdaccio should listen to | `"localhost"` |
| `location` | string | Location option for npm config | `"user"` |
| `scopes` | array | Scopes to be added to the Verdaccio config |  |
| `storage` | string | Path to the custom storage directory for Verdaccio |  |

---
<!-- source: https://nx.dev/docs/technologies/typescript/generators.md -->
## @nx/js Generators

The @nx/js plugin provides various generators to help you create and configure js projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `convert-to-swc`
Convert a TSC library to SWC.

**Usage:**
```bash
nx generate @nx/js:convert-to-swc [options]
```

**Aliases:** `swc`

**Arguments:**
```bash
nx generate @nx/js:convert-to-swc <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--targets` | array | List of targets to convert. | `["build"]` |

## `library`
Create a TypeScript Library.

The `@nx/js:lib` generator will generate a library for you, and it will configure it according to the options you provide.

```bash
npx nx g @nx/js:lib libs/mylib
```

By default, the library that is generated when you use this executor without passing any options, like the example above, will be a buildable library, using the `@nx/js:tsc` executor as a builder.

You may configure the tools you want to use to build your library, or bundle it too, by passing the `--bundler` flag. The `--bundler` flag controls the compiler and/or the bundler that will be used to build your library. If you choose `tsc` or `swc`, the result will be a buildable library using either `tsc` or `swc` as the compiler. If you choose `rollup` or `vite`, the result will be a buildable library using `rollup` or `vite` as the bundler. In the case of `rollup`, it will default to the `tsc` compiler. If you choose `esbuild`, you may use the [`esbuildOptions` property](https://esbuild.github.io/api/) in your `project.json` under the `build` target options to specify whether you wish to bundle your library or not.

### Examples

###### Buildable with default compiler (tsc)

Generate a buildable library using the `@nx/js:tsc` executor. This uses `tsc` as the compiler.

```bash
npx nx g @nx/js:lib libs/mylib
```

###### Buildable with SWC compiler

Generate a buildable library using [SWC](https://swc.rs) as the compiler. This will use the `@nx/js:swc` executor.

```bash
npx nx g @nx/js:lib libs/mylib --bundler=swc
```

###### Buildable with tsc

Generate a buildable library using tsc as the compiler. This will use the `@nx/js:tsc` executor.

```bash
npx nx g @nx/js:lib libs/mylib --bundler=tsc
```

###### Buildable, with Rollup as a bundler

Generate a buildable library using [Rollup](https://rollupjs.org) as the bundler. This will use the `@nx/rollup:rollup` executor. It will also use [SWC](https://swc.rs) as the compiler.

```bash
npx nx g @nx/js:lib libs/mylib --bundler=rollup
```

If you do not want to use `swc` as the compiler, and want to use the default `babel` compiler, you can do so in your `project.json` under the `build` target options, using the [`compiler` property](/nx-api/rollup/executors/rollup#compiler):

```jsonc title="libs/mylib/project.json"
"build": {
  "executor": "@nx/rollup:rollup",
  "options": {
    //...
    "compiler": "babel"
  }
}
```

###### Buildable, with Vite as a bundler

Generate a buildable library using [Vite](https://vite.dev/) as the bundler. This will use the `@nx/vite:build` executor.

```bash
npx nx g @nx/js:lib libs/mylib --bundler=vite
```

###### Using ESBuild

Generate a buildable library using [ESBuild](https://esbuild.github.io/) as the bundler. This will use the `@nx/esbuild:esbuild` executor.

```bash
npx nx g @nx/js:lib libs/mylib --bundler=esbuild
```

If you want to specify whether you want to bundle your library or not, you can do so in your `project.json` under the `build` target options, using the [`esbuildOptions` property](https://esbuild.github.io/api/):

```jsonc title="libs/mylib/project.json"
"build": {
  "executor": "@nx/esbuild:esbuild",
  "options": {
    //...
    "esbuildOptions": {
        "bundle": true
    }
  }
}
```

###### Minimal publishing target

Generate a **publishable** library with a minimal publishing target. The result will be a buildable library using the `@nx/js:tsc` executor, using `tsc` as the compiler. You can change the compiler or the bundler by passing the `--bundler` flag.

```bash
npx nx g lib libs/mylib --publishable
```

###### In a nested directory

Generate a library named `mylib` and put it under a directory named `nested` (`libs/nested/mylib`).

```shell
npx nx g lib libs/nested/mylib
```

###### Non-buildable library

Generate a non-buildable library.

```bash
npx nx g @nx/js:lib libs/mylib --bundler=none
```

**Usage:**
```bash
nx generate @nx/js:library [options]
```

**Aliases:** `lib`

**Arguments:**
```bash
nx generate @nx/js:library <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--buildable` | boolean | Generate a buildable library. | `true` |
| `--bundler` | string | The bundler to use. Choosing 'none' means this library is not buildable. | `"tsc"` |
| `--compiler` | string | The compiler used by the build and test targets |  |
| `--config` | string | Determines whether the project's executors should be configured in `workspace.json`, `project.json` or as npm scripts. | `"project"` |
| `--importPath` | string | The library name used to import it, like @myorg/my-awesome-lib. Required for publishable library. |  |
| `--includeBabelRc` | boolean | Include a .babelrc configuration to compile TypeScript files |  |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. | `false` |
| `--linter` | string | The tool to use for running lint checks. |  |
| `--minimal` | boolean | Generate a library with a minimal setup. No README.md generated. | `false` |
| `--name` | string | Library name. |  |
| `--publishable` | boolean | Configure the library ready for use with `nx release` (https://nx.dev/core-features/manage-releases). | `false` |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--skipTsConfig` | boolean | Do not update tsconfig.json for development experience. | `false` |
| `--skipTypeCheck` | boolean | Whether to skip TypeScript type checking for SWC compiler. | `false` |
| `--strict` | boolean | Whether to enable tsconfig strict mode or not. | `true` |
| `--tags` | string | Add tags to the library (used for linting). |  |
| `--testEnvironment` | string | The test environment to use if unitTestRunner is set to jest or vitest. | `"node"` |
| `--unitTestRunner` | string | Test runner to use for unit tests. |  |
| `--useProjectJson` | boolean | Use a `project.json` configuration file instead of inlining the Nx configuration in the `package.json` file. |  |

## `setup-build`
Sets up build target for a project.

**Usage:**
```bash
nx generate @nx/js:setup-build [options]
```

**Arguments:**
```bash
nx generate @nx/js:setup-build <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--bundler` | string [**required**] | The bundler to use to build the project. | `"tsc"` |
| `--buildTarget` | string | The build target to add. | `"build"` |
| `--main` | string | The path to the main entry file, relative to workspace root. Defaults to <project>/src/index.ts or <project>/src/main.ts. |  |
| `--tsConfig` | string | The path to the tsConfig file, relative to workspace root. Defaults to <project>/tsconfig.lib.json or <project>/tsconfig.app.json depending on project type. |  |

## `setup-prettier`
Setup Prettier as the formatting tool.

**Usage:**
```bash
nx generate @nx/js:setup-prettier [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |

## `setup-verdaccio`
Setup Verdaccio local-registry.

**Usage:**
```bash
nx generate @nx/js:setup-verdaccio [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--skipFormat` | boolean | Skip formatting files. | `false` |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/js:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/typescript/guides.md -->
## Guides

{% index_page_cards path="technologies/typescript/guides" /%}

---
<!-- source: https://nx.dev/docs/technologies/typescript/guides/compile-multiple-formats.md -->
## Compile TypeScript Libraries to Multiple Formats

{% youtube src="https://youtu.be/Vy4d0-SF5cY" title="Packaging Typescript Lbraries" /%}

It can be difficult to set up a TypeScript library to compile to ESM and CommonJS. You can use `@nx/rollup` to take care of it for you.

## Use Rollup to compile your TypeScript project

If you do not use Rollup already, install the corresponding Nx plugin as follows:

```shell
nx add @nx/rollup
```

Make sure the version of `@nx/rollup` matches your other `@nx/*` package versions.

## Configure Rollup to create multiple formats

Create a `rollup.config.cjs` file in your project with the following configuration:

```javascript {% meta="{10}" %}
// packages/my-awesome-lib/rollup.config.cjs
const { withNx } = require('@nx/rollup/with-nx');

module.exports = withNx(
  {
    main: './src/index.ts',
    outputPath: './dist',
    tsConfig: './tsconfig.lib.json',
    compiler: 'swc',
    format: ['esm', 'cjs'],
    additionalEntryPoints: ['./src/foo.ts'],
  },
  {
    // Additional rollup configuration options
  }
);
```

The `@nx/rollup/plugin` will automatically infer a `build` target for any project with a `rollup.config.cjs` file.

{% aside title="Using the Executor Directly" %}
You can also configure the build using the `@nx/rollup:rollup` executor in your `project.json` or `package.json` instead of the inferred plugin approach:

```jsonc
// packages/my-awesome-lib/project.json
{
  "name": "my-awesome-lib",
  "targets": {
    "build": {
      "executor": "@nx/rollup:rollup",
      "options": {
        "main": "packages/my-awesome-lib/src/index.ts",
        "format": ["esm", "cjs"],
        "additionalEntryPoints": ["packages/my-awesome-lib/src/foo.ts"],
        "generateExportsField": true,
      },
    },
  },
}
```

{% /aside %}

After compiling our package using `nx build my-awesome-lib` we'll get the following output in our `dist` folder.

{% filetree %}

- my-awesome-lib/
  - dist/
    - foo.cjs.js
    - foo.esm.js
    - foo.d.ts
    - index.cjs.js
    - index.esm.js
    - index.d.ts
    - src/
      - lib/
        - my-awesome-lib.d.ts
  - src/
    - ...
  - ...

{% /filetree %}

## Configure package exports

To ensure your package works correctly with TypeScript's module resolution, you need to configure the `exports` field in your source `package.json` with proper `types` entries. This is critical for TypeScript 4.7+ which requires explicit type declarations for each export condition.

{% callout type="warning" title="Types Must Be Specified for Each Condition" %}
When using conditional exports with both ESM and CJS formats, you must include `types` entries for each condition. Without this, TypeScript may fail to resolve types correctly, causing compilation errors for consumers of your package. See the [TypeScript 4.7 release notes](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-7.html#packagejson-exports-imports-and-self-referencing) for more details.
{% /callout %}

Update your source `package.json` to include the exports configuration:

```json
// packages/my-awesome-lib/package.json
{
  "name": "my-awesome-lib",
  "version": "0.0.1",
  "type": "commonjs",
  "main": "./dist/index.cjs.js",
  "module": "./dist/index.esm.js",
  "types": "./dist/index.d.ts",
  "exports": {
    "./package.json": "./package.json",
    ".": {
      "import": {
        "types": "./dist/index.d.ts",
        "default": "./dist/index.esm.js"
      },
      "require": {
        "types": "./dist/index.d.ts",
        "default": "./dist/index.cjs.js"
      }
    },
    "./foo": {
      "import": {
        "types": "./dist/foo.d.ts",
        "default": "./dist/foo.esm.js"
      },
      "require": {
        "types": "./dist/foo.d.ts",
        "default": "./dist/foo.cjs.js"
      }
    }
  }
}
```

Now consumers of your package can access the appropriate format for their codebase and TypeScript will correctly resolve types regardless of whether they're using ESM or CommonJS.

## Verify your package

After building your package, verify that the types are correctly configured. A common mistake is misconfiguring the `exports` field, which can cause TypeScript compilation errors for consumers of your package.

Use [Are the types wrong?](https://arethetypeswrong.github.io/) to check your package:

- **Web app**: Upload your built package or check a published npm package at [arethetypeswrong.github.io](https://arethetypeswrong.github.io/)
- **CLI tool**: Install `@arethetypeswrong/cli` to check packages locally or in CI:

```shell
npx @arethetypeswrong/cli ./dist/my-awesome-lib
```

This tool will identify common issues like missing type declarations for specific export conditions, helping you catch problems before publishing.

---
<!-- source: https://nx.dev/docs/technologies/typescript/guides/define-secondary-entrypoints.md -->
## Define Secondary Entry Points for TypeScript Packages

If you have a package where you want people to be able to access more than just the `main` file, you can define an `exports` property in the `package.json` file. Like this:

```json
// packages/my-lib/package.json
{
  "exports": {
    "./package.json": "./package.json",
    ".": "./src/index.js",
    "./foo": "./src/foo.js",
    "./bar": "./src/bar.js"
  }
}
```

Then people can access code in your library through any of the provided entry points.

```ts
// some-file.ts
import myLib from 'my-lib';
import foo from 'my-lib/foo';
import bar from 'my-lib/bar';
```

## Setup package.json export fields with Nx

Nx helps generate other properties in the `package.json` file, and you can also use Nx to maintain this property.

If you're using the `@nx/js:tsc` executor, as of Nx 16.8, you can specify the `additionalEntryPoints` and `generateExportsField` options. Here's an example:

{% tabs %}
{% tabitem label="package.json" %}

```jsonc
// packages/my-awesome-lib/package.json
{
  "name": "my-awesome-lib",
  "nx": {
    "targets": {
      "build": {
        "executor": "@nx/js:tsc",
        "options": {
          "main": "packages/my-awesome-lib/src/index.ts",
          "additionalEntryPoints": [
            "packages/my-awesome-lib/src/foo.ts",
            "packages/my-awesome-lib/src/bar.ts",
          ],
          "generateExportsField": true,
        },
      },
    },
  },
}
```

{% /tabitem %}
{% tabitem label="project.json" %}

```jsonc
// packages/my-awesome-lib/project.json
{
  "name": "my-awesome-lib",
  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "options": {
        "main": "packages/my-awesome-lib/src/index.ts",
        "additionalEntryPoints": [
          "packages/my-awesome-lib/src/foo.ts",
          "packages/my-awesome-lib/src/bar.ts",
        ],
        "generateExportsField": true,
      },
    },
  },
}
```

{% /tabitem %}
{% /tabs %}

When building the library, the `@nx/js:tsc` executor automatically adds the correct `exports` definition to the resulting `package.json`.

## Compile to multiple formats

You can also compile to multiple formats, if you switch to using the `@nx/rollup:rollup` executor. Read all [the details here](/docs/technologies/typescript/guides/compile-multiple-formats).

---
<!-- source: https://nx.dev/docs/technologies/typescript/guides/enable-tsc-batch-mode.md -->
## Enable TypeScript Batch Mode

{% aside type="tip" title="Available since Nx 16.6.0" %}
The `@nx/js:tsc` batch implementation was introduced in Nx **16.6.0**.
{% /aside %}

If you're using `@nx/js:tsc` to build your projects, you can opt in to its batch implementation. It uses the [TypeScript APIs for incremental builds](https://www.typescriptlang.org/docs/handbook/project-references.html#build-mode-for-typescript) to batch task execution into a single process, which is faster than the default one-process-per-task approach. The larger the task graph, the bigger the speedup.

{% aside type="caution" title="Experimental feature" %}
Executing tasks in batch mode is an experimental feature.
{% /aside %}

{% aside type="note" title="Requirements" %}
Building a project with the `@nx/js:tsc` executor in batch mode requires all dependent projects (excluding implicit dependencies) to be buildable and built using the `@nx/js:tsc` executor.
{% /aside %}

To run your builds using the batch implementation, pass in `--batch` flag:

```shell
nx build my-project --batch
```

For optimal performance, you could set the `clean` option to `false`. Otherwise, the executor cleans the output folder before running the build, which results in the loss of the [`.tsbuildinfo` file](https://www.typescriptlang.org/tsconfig/#tsBuildInfoFile) and, consequently, the loss of important optimizations performed by TypeScript. This is not a requirement. Even if the `clean` option is not set to `false` there are other important optimizations that are performed by the batch implementation.

```json
// libs/ts-lib/project.json
{
  "build": {
    "executor": "@nx/js:tsc",
    "options": {
      "outputPath": "dist/libs/ts-lib",
      "main": "libs/ts-lib/src/index.ts",
      "tsConfig": "libs/ts-lib/tsconfig.lib.json",
      "assets": ["libs/ts-lib/*.md"],
      "clean": false
    }
  }
}
```

You can get a sense of the performance improvements over using the `@nx/js:tsc` default implementation in the [tsc batch mode benchmark](/docs/reference/benchmarks/tsc-batch-mode).

---
<!-- source: https://nx.dev/docs/technologies/typescript/guides/js-and-ts.md -->
## JavaScript and TypeScript

Nx is a general-purpose monorepo platform and CLI. It works with JavaScript, TypeScript, Java, C#, Go, etc.. The core plugins Nx comes with do work best with JavaScript or TypeScript.

TypeScript is a great choice for many teams, but not for everyone. If you want to use Nx with JavaScript, simply pass `--js` to all generate commands, as follows:

```shell
nx g @nx/react:app apps/myapp --js
nx g @nx/react:component apps/myapp/src/lib/mycmp --js
```

You can build/test/lint/serve your applications and libraries the same way whether you use JavaScript and TypeScript. You can also mix and match them.

Regardless whether you use JavaScript or TypeScript, you will have a `tsconfig.base.json` file at the root of the workspace. **It's not used to build the applications and libraries in the workspace. It's only used to improve the editor experience.**

## Interested in building and distributing TypeScript packages?

You might want to check out the `@nx/js` package which comes with advanced TypeScript support, including [SWC](https://swc.rs/) and more. Find out more in the [plugin documentation](/docs/technologies/typescript/introduction).

---
<!-- source: https://nx.dev/docs/technologies/typescript/guides/switch-to-workspaces-project-references.md -->
## Switch to Workspaces and Project References

{% llm_copy_prompt title="Migrate to TS solution setup" %}
Migrate this Nx workspace from TypeScript path aliases to workspaces and project references.

1. Enable package manager workspaces
2. Update root TypeScript configuration
3. Create project package.json files
4. Update project TypeScript configurations
5. Update bundler configurations
6. Verify the migration

Analyze my repository and walk me through each step. Adapt the instructions to my specific workspace setup.

Guide: {pageUrl}
{% /llm_copy_prompt %}

To get the [performance benefits](/docs/concepts/typescript-project-linking#typescript-project-references-performance-benefits) of TypeScript project references, use package manager workspaces for [project linking](/docs/concepts/typescript-project-linking) instead of TypeScript path aliases.

## Enable package manager workspaces

Configure your package manager to use workspaces for project linking.

{% tabs %}
{% tabitem label="npm" %}

```json
// package.json
{
  "workspaces": ["apps/*", "libs/*"]
}
```

The `workspaces` property tells npm to look for `package.json` files in the specified folders. Running `npm install` installs all project dependencies in the root `node_modules` and symlinks the local projects so they can be imported like npm packages.

Include local libraries in `devDependencies` of the consuming project's `package.json` with `*` as the version. `*` tells npm to use whatever local version is available. This applies to both buildable and non-buildable libraries.

```json
// apps/my-app/package.json
{
  "devDependencies": {
    "@my-org/some-project": "*"
  }
}
```

{% /tabitem %}
{% tabitem label="yarn" %}

```json
// package.json
{
  "workspaces": ["apps/*", "libs/*"]
}
```

The `workspaces` property tells yarn to look for `package.json` files in the specified folders. Running `yarn` installs all project dependencies in the root `node_modules` and symlinks the local projects so they can be imported like npm packages.

Include local libraries in `devDependencies` of the consuming project's `package.json` with `workspace:*` as the version. [`workspace:*` tells yarn the project is in the same repository](https://yarnpkg.com/features/workspaces) and not an npm package.

```json
// apps/my-app/package.json
{
  "devDependencies": {
    "@my-org/some-project": "workspace:*"
  }
}
```

{% /tabitem %}
{% tabitem label="bun" %}

```json
// package.json
{
  "workspaces": ["apps/*", "libs/*"]
}
```

The `workspaces` property tells bun to look for `package.json` files in the specified folders. Running `bun install` installs all project dependencies in the root `node_modules` and symlinks the local projects so they can be imported like npm packages.

Include local libraries in `devDependencies` of the consuming project's `package.json` with `workspace:*` as the version. [`workspace:*` tells bun the project is in the same repository](https://bun.sh/docs/install/workspaces) and not an npm package.

```json
// apps/my-app/package.json
{
  "devDependencies": {
    "@my-org/some-project": "workspace:*"
  }
}
```

{% /tabitem %}
{% tabitem label="pnpm" %}

```yaml
// pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'libs/*'
```

The `packages` property tells pnpm to look for `package.json` files in the specified folders. Running `pnpm install` installs all project dependencies in the root `node_modules`.

Include local libraries in `devDependencies` of the consuming project's `package.json` with `workspace:*` as the version. [`workspace:*` tells pnpm the project is in the same repository](https://pnpm.io/workspaces#workspace-protocol-workspace) and not an npm package.

```json
// apps/my-app/package.json
{
  "devDependencies": {
    "@my-org/some-project": "workspace:*"
  }
}
```

{% /tabitem %}
{% /tabs %}

{% aside type="caution" title="Non-standard project locations" %}
The patterns above (`apps/*`, `libs/*`) only match projects directly inside those folders. If you have projects in other directories (e.g. `tools/*`, `packages/*`) or nested deeper (e.g. `libs/shared/ui`), add the appropriate patterns. Root-level projects (where the project root is `.`) don't need a workspace pattern but can't be added as a workspace entry.
{% /aside %}

## Update .gitignore

With TypeScript project references, build artifacts are output within each project's directory rather than a shared root `dist` folder. Add these patterns to your root `.gitignore`:

```text
out-tsc
dist
test-output
```

Use root-level entries (not path-prefixed like `/dist`) so they match in nested project directories.

## Update root TypeScript configuration

The root `tsconfig.base.json` should contain only `compilerOptions`, not top-level properties like `include`, `exclude`, or `files`. If yours has any of these, move them to the appropriate project-level tsconfig files before proceeding.

Set `compilerOptions.composite` to `true`. If `declaration` is explicitly set to `false` anywhere in the config chain, remove it — `composite` requires declarations and will fail with **TS6304** if `declaration` is disabled. It can be omitted entirely since it defaults to `true` when `composite` is `true`. Delete `compilerOptions.paths` entirely (not set to `{}`), and remove `compilerOptions.rootDir` and `compilerOptions.baseUrl` if present. These aren't needed in TS solution mode since imports resolve through `node_modules` symlinks.

If `moduleResolution` is set to `"node"` (Node10), change it to `"bundler"`. The `"node"` setting does not support `exports` fields in `package.json`, so TypeScript will fail to resolve workspace libraries after removing path aliases. The `"bundler"` setting supports `exports` while still allowing extensionless relative imports.

If you changed `moduleResolution` to `"bundler"` (or are using `"node16"`/`"nodenext"`), add `customConditions` with a condition unique to your organization (e.g. `@myorg/source`). This tells TypeScript to prefer the matching condition in each library's `exports` field, resolving workspace dependencies to source `.ts` files during development without requiring a build step first. `customConditions` is not supported with `moduleResolution: "node"` (Node10) — if you must keep `"node"`, skip this and the corresponding `@myorg/source` condition in library `exports`. Also add `declarationMap: true` for better editor navigation across project boundaries and `isolatedModules: true` for compatibility with bundlers and SWC.

{% aside type="caution" title="Order of operations" %}
Run your package manager's install command (e.g. `npm install`) **before** deleting `compilerOptions.paths`. The workspace symlinks in `node_modules` must be in place before path aliases are removed, otherwise Jest, Vite, and webpack resolvers won't find local projects.
{% /aside %}

{% aside type="note" title="pnpm requires explicit workspace dependencies" %}
Unlike npm and yarn, pnpm only symlinks workspace packages that are listed as dependencies in a project's `package.json`. Each project must declare its workspace dependencies explicitly. As a quick workaround, you can add all workspace packages to the root `package.json` under `devDependencies`, but the recommended long-term approach is to list them in each project's own `package.json`.
{% /aside %}

Copy the `paths` entries before deleting them. You'll need them as a reference for creating project `package.json` files and `references` in `tsconfig.json`.

{% tabs %}
{% tabitem label="Before" %}

```jsonc
// tsconfig.base.json
{
  "compilerOptions": {
    "allowJs": false,
    "allowSyntheticDefaultImports": true,
    // ...
    "paths": {
      "@myorg/utils": ["libs/utils/src/index.ts"],
      "@myorg/ui": ["libs/ui/src/index.ts"],
    },
  },
}
```

{% /tabitem %}
{% tabitem label="After" %}

```jsonc
// tsconfig.base.json
{
  "compilerOptions": {
    "composite": true,
    "moduleResolution": "bundler",
    "declarationMap": true,
    "isolatedModules": true,
    "customConditions": ["@myorg/source"],
    // declaration defaults to true when composite is true
    // paths, rootDir, baseUrl, and module have been removed
    "allowJs": false,
    "allowSyntheticDefaultImports": true,
  },
}
```

{% /tabitem %}
{% /tabs %}

The root `tsconfig.json` should extend `tsconfig.base.json`, include no files, and list `references` for every project so editor tooling works correctly.

{% tabs %}
{% tabitem label="Before" %}

```jsonc
// tsconfig.json
{
  "extends": "./tsconfig.base.json",
  "files": [], // intentionally empty
}
```

{% /tabitem %}

{% tabitem label="After" %}

```jsonc
// tsconfig.json
{
  "extends": "./tsconfig.base.json",
  "files": [], // intentionally empty
  "references": [
    {
      "path": "./libs/utils",
    },
    {
      "path": "./libs/ui",
    },
    // Generated projects are added here automatically
  ],
}
```

{% /tabitem %}
{% /tabs %}

## Register Nx TypeScript plugin

Install `@nx/js` and register `@nx/js/typescript` as a plugin in `nx.json`:

```jsonc
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/js/typescript",
      "options": {
        "typecheck": {
          "targetName": "typecheck",
        },
        "build": {
          "targetName": "build",
          "configName": "tsconfig.lib.json",
          "buildDepsName": "build-deps",
          "watchDepsName": "watch-deps",
        },
      },
    },
  ],
}
```

This plugin registers a [sync generator](/docs/concepts/sync-generators) that automatically maintains project references across the workspace.

## Update build targets

The `@nx/js/typescript` plugin infers both `typecheck` and `build` targets from `tsconfig.lib.json`, so explicit `@nx/js:tsc` build targets in `project.json` (or `package.json`) should be removed. Keeping both the explicit target and the inferred one leads to duplicated configuration — the output path, entry point, and tsconfig are already defined in `tsconfig.lib.json` and `package.json`, so the `project.json` target becomes redundant.

{% tabs %}
{% tabitem label="Before" %}

```jsonc
// libs/ui/project.json
{
  "name": "ui",
  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/libs/ui",
        "main": "libs/ui/src/index.ts",
        "tsConfig": "libs/ui/tsconfig.lib.json",
      },
    },
  },
}
```

{% /tabitem %}
{% tabitem label="After" %}

```jsonc
// libs/ui/project.json
{
  "name": "ui",
  // build target removed — typecheck and build are inferred by @nx/js/typescript plugin
}
```

{% /tabitem %}
{% /tabs %}

If the only remaining property in `project.json` is `name`, delete the file entirely. Nx infers the project name from `package.json`, so `project.json` is only needed when it contains custom target configuration, tags, or `implicitDependencies` that aren't expressed elsewhere.

### Verify inferred targets

After removing explicit build targets, confirm the plugin infers the correct targets for each project:

```shell
nx show project my-lib
```

For **non-buildable libraries** (whose `exports` point directly to source `.ts` files), you should see an inferred `typecheck` target. For **buildable libraries**, you should see both `typecheck` and `build` targets. The plugin infers a `build` target when `package.json` entry points (`exports`, `main`, or `module`) resolve to paths inside the tsconfig's `outDir`. If a buildable library is missing its `build` target, check that `package.json` entry points point inside `outDir` (e.g. `"main": "./dist/index.js"` with `outDir: "./dist"`) and that `rootDir` is set to `./src` (see [Update individual project TypeScript configuration](#update-individual-project-typescript-configuration)).

{% llm_only %}
CRITICAL: When removing `@nx/js:tsc` build targets from `project.json`, you MUST ensure the library's `tsconfig.lib.json` and `package.json` are configured correctly first, otherwise the library will lose its build capability.

For buildable libraries, before removing the build target:

1. Set `outDir` to `./dist` in `tsconfig.lib.json`
2. Set `rootDir` to `./src` in `tsconfig.lib.json` (so output is `dist/index.js` not `dist/src/index.js`)
3. Add `"type": "module"`, `"main": "./dist/index.js"`, `"types": "./src/index.ts"` to `package.json`
4. Add the `@myorg/source` custom condition to `exports` in `package.json`, with `types` pointing to source (`./src/index.ts`) and `import`/`default` pointing to `./dist/`

The plugin decides whether to infer a `build` target by checking if `package.json` entry points (`exports`, `main`, `module`) resolve to paths inside the tsconfig's `outDir`. If entry points still point to source files (e.g. `./src/index.ts`), no `build` target is inferred.

After removing the target, run `nx show project <name>` and verify `build` appears in the inferred targets. If it doesn't, check that `package.json` entry points point inside `outDir`.

Do NOT remove the build target and delete `project.json` in the same step. Remove the target first, verify, then delete the file if empty.
{% /llm_only %}

## Create individual project package.json files

Every project needs a `package.json` for workspaces to link projects as dependencies. Without it, your package manager won't create the `node_modules` symlinks that replace the old TypeScript path aliases. For applications, a `name` field is sufficient since apps are consumed by dev servers and bundlers, not imported by other projects. Use the same name as the existing `project.json` so that e2e configurations (e.g. Playwright's `webServer.command: 'nx run myapp:preview'`) continue to work without changes. For libraries, add an `exports` field that maps to the source entry points so that TypeScript and bundlers can resolve imports to the library's source code.

{% aside type="note" title="Existing package.json files" %}
If a project already has a `package.json` (e.g. a published library with `main`, `module`, or `types` fields), preserve the existing configuration and only add `exports` if not already defined.
{% /aside %}

The examples below use `*` for workspace dependency versions. If you use yarn, pnpm, or bun, replace `*` with `workspace:*` as shown in the [package manager setup](#enable-package-manager-workspaces) above.

{% tabs %}
{% tabitem label="Non-buildable library" %}

```json
// libs/ui/package.json
{
  "name": "@myorg/ui",
  "devDependencies": {
    "@myorg/utils": "*"
  },
  "exports": {
    "./package.json": "./package.json",
    ".": {
      "@myorg/source": "./src/index.ts",
      "types": "./src/index.ts",
      "import": "./src/index.ts",
      "default": "./src/index.ts"
    }
  }
}
```

{% /tabitem %}
{% tabitem label="Buildable library" %}

The `@myorg/source` condition matches the `customConditions` in `tsconfig.base.json`, so TypeScript resolves to source during development. The `types` condition points to source so TypeScript resolves correctly within the monorepo. The `import`/`default` conditions resolve to built output for production consumers.

```json
// libs/ui/package.json
{
  "name": "@myorg/ui",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./src/index.ts",
  "devDependencies": {
    "@myorg/utils": "*"
  },
  "exports": {
    "./package.json": "./package.json",
    ".": {
      "@myorg/source": "./src/index.ts",
      "types": "./src/index.ts",
      "import": "./dist/index.js",
      "default": "./dist/index.js"
    }
  }
}
```

{% /tabitem %}
{% tabitem label="Application" %}

```json
// apps/my-app/package.json
{
  "name": "@myorg/my-app",
  "devDependencies": {
    "@myorg/ui": "*",
    "@myorg/utils": "*"
  }
}
```

{% /tabitem %}
{% /tabs %}

After creating or updating project `package.json` files, run your package manager's install command again (e.g. `npm install`) so that new workspace symlinks are created in `node_modules`.

### Package names with multiple slashes

A `package.json` name can only have one `/` (the scope separator), so a name like `@myorg/shared/ui` is invalid. This is more restrictive than TypeScript path aliases, so you'll need to flatten any nested aliases. You have two main options:

1. **Drop the original scope:** `@myorg/shared/ui` becomes `@shared/ui`
2. **Combine scope segments with a dash:** `@myorg/shared/ui` becomes `@myorg-shared/ui`

| Old path alias       | Option 1 (drop scope) | Option 2 (combine with dash) |
| -------------------- | --------------------- | ---------------------------- |
| `@myorg/shared/ui`   | `@shared/ui`          | `@myorg-shared/ui`           |
| `@myorg/foo/bar`     | `@foo/bar`            | `@myorg-foo/bar`             |
| `@myorg/foo/bar/baz` | `@foo/bar-baz`        | `@myorg-foo/bar-baz`         |

Choose a convention and apply it consistently. Update all import statements to match the new names.

If multiple path aliases point to different entry points within the same library (e.g. `@myorg/utils` and `@myorg/utils/testing`), you could use the `exports` field to map multiple entry points from a single package:

```json
{
  "name": "@myorg/utils",
  "exports": {
    "./package.json": "./package.json",
    ".": {
      "types": "./src/index.ts",
      "default": "./src/index.ts"
    },
    "./testing": {
      "types": "./src/testing.ts",
      "default": "./src/testing.ts"
    }
  }
}
```

However, this approach requires consolidating code from separate libraries into one, which adds complexity. For the initial migration, prefer the renaming strategies above and tackle library consolidation separately.

## Update individual project TypeScript configuration

{% aside type="note" title="Applications and libraries" %}
These requirements apply to both application and library projects. The examples show libraries, but the same applies to applications using `tsconfig.app.json` instead of `tsconfig.lib.json`.
{% /aside %}

Each project's `tsconfig.json` should extend `tsconfig.base.json` and list `references` to its dependencies. If the project `tsconfig.json` has `compilerOptions`, move them into the solution files (any `tsconfig.*.json` files, such as `tsconfig.lib.json`/`tsconfig.app.json` and `tsconfig.spec.json`), merging with any existing options. Then remove `compilerOptions` from the project `tsconfig.json`.

When merging, also remove `module` and `moduleResolution` from individual project tsconfigs. Let these inherit from `tsconfig.base.json` for consistency. If `typecheck` or `build` fails for specific projects after this change, add `module` and `moduleResolution` back to that project's solution files with the values it needs.

{% aside type="caution" title="moduleResolution and import extensions" %}
The `moduleResolution` value in `tsconfig.base.json` affects how imports are resolved across all projects. If your root config uses `node` (Node10) or `bundler`, extensionless imports like `import { foo } from './bar'` work as expected. If you plan to switch to `nodenext`, all relative imports must include file extensions (e.g. `import { foo } from './bar.js'`). This is a significant codebase-wide change, so consider it a follow-up task after the initial migration rather than doing both at once.
{% /aside %}

The project `tsconfig.json` provides your IDE with `references` to the `tsconfig.*.json` files that define compilation settings. `tsconfig.spec.json` handles test files, and `tsconfig.lib.json` (or `tsconfig.app.json`) handles production code.

{% aside type="note" title="Extends chain" %}
Each `tsconfig.lib.json`, `tsconfig.app.json`, and `tsconfig.spec.json` should extend `tsconfig.base.json` directly (via a relative path like `../../tsconfig.base.json`), not the project's own `tsconfig.json`. This avoids circular reference issues and ensures each solution file inherits only the shared compiler options.
{% /aside %}

{% tabs %}
{% tabitem label="Before" %}

```jsonc
// libs/ui/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "module": "commonjs",
    "strict": true,
    "forceConsistentCasingInFileNames": true,
  },
  "files": [],
  "include": [],
  "references": [
    { "path": "./tsconfig.lib.json" },
    { "path": "./tsconfig.spec.json" },
  ],
}
```

{% /tabitem %}
{% tabitem label="After" %}

```jsonc
// libs/ui/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "files": [], // intentionally empty
  "references": [
    // Project dependencies are added by nx sync
    { "path": "./tsconfig.lib.json" },
    { "path": "./tsconfig.spec.json" },
  ],
}
```

{% /tabitem %}
{% /tabs %}

Each solution file (`tsconfig.lib.json`, `tsconfig.app.json`, `tsconfig.spec.json`, or any other `tsconfig.*.json`) should extend `tsconfig.base.json` directly, not the project's `tsconfig.json`. This is because `tsconfig.json` references `tsconfig.spec.json`, and keeping test files unreferenced from the lib/app config makes `typecheck` and `build` faster.

The solution files that handle production code (`tsconfig.lib.json` or `tsconfig.app.json`) also need `references` to the solution files of their dependency projects. These are added automatically by `nx sync`. Each `outDir` must be unique across solution files so cached outputs don't interfere with each other.

{% aside type="note" title="Shared compiler options" %}
If `tsconfig.lib.json` and `tsconfig.spec.json` share many `compilerOptions`, create a `tsconfig.project.json` with those shared settings. Have `tsconfig.project.json` extend `tsconfig.base.json`, then both `tsconfig.lib.json` and `tsconfig.spec.json` extend `tsconfig.project.json`.
{% /aside %}

{% tabs %}
{% tabitem label="Before" %}

```jsonc
// libs/ui/tsconfig.lib.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "../../dist/out-tsc",
    "declaration": true,
    "types": ["node"],
  },
  "include": ["src/**/*.ts"],
  "exclude": ["src/**/*.spec.ts", "src/**/*.test.ts"],
}
```

{% /tabitem %}
{% tabitem label="After (non-buildable)" %}

```jsonc
// libs/ui/tsconfig.lib.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    // Merged from project tsconfig.json (module/moduleResolution removed)
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "types": ["node"],
    // outDir can be anything — non-buildable libraries aren't compiled
    "outDir": "./out-tsc/lib",
  },
  "include": ["src/**/*.ts"],
  "exclude": ["src/**/*.spec.ts", "src/**/*.test.ts"],
  "references": [
    // References to dependency projects — added by nx sync
    // e.g. if ui depends on utils:
    { "path": "../utils/tsconfig.lib.json" },
  ],
}
```

{% /tabitem %}
{% tabitem label="After (buildable)" %}

```jsonc
// libs/ui/tsconfig.lib.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    // Merged from project tsconfig.json (module/moduleResolution removed)
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "types": ["node"],
    // outDir matches where package.json entry points resolve — plugin infers build
    "outDir": "./dist",
    "rootDir": "./src",
  },
  "include": ["src/**/*.ts"],
  "exclude": ["src/**/*.spec.ts", "src/**/*.test.ts"],
  "references": [
    // References to dependency projects — added by nx sync
    { "path": "../utils/tsconfig.lib.json" },
  ],
}
```

{% /tabitem %}
{% /tabs %}

{% aside type="caution" title="Buildable library configuration" %}
The `@nx/js/typescript` plugin infers a `build` target when `package.json` entry points (`exports`, `main`, or `module`) resolve to paths inside the tsconfig's `outDir`. For buildable libraries, set `outDir` to `./dist` and ensure `package.json` has `"main": "./dist/index.js"` (or equivalent `exports`). Set `rootDir` to `./src` so the output is `dist/index.js` rather than `dist/src/index.js`. For non-buildable libraries, no `build` target is inferred because their entry points point to source files, not compiled output.
{% /aside %}

The `tsconfig.spec.json` doesn't need to reference project dependencies, but it **must** include a `references` entry pointing to `tsconfig.lib.json` (or `tsconfig.app.json`). Without this, TypeScript will fail with **TS6307: File is not listed within the file list of project** when spec files import from the project's source code.

{% tabs %}
{% tabitem label="Before" %}

```jsonc
// libs/ui/tsconfig.spec.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "../../dist/out-tsc",
    "types": ["jest", "node"],
  },
  "include": ["src/**/*.spec.ts", "src/**/*.test.ts", "src/**/*.d.ts"],
}
```

{% /tabitem %}
{% tabitem label="After" %}

```jsonc
// libs/ui/tsconfig.spec.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    // Merged from project tsconfig.json (module/moduleResolution removed)
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    // Original options from tsconfig.spec.json
    "types": ["jest", "node"],
    // outDir is now local to the project
    "outDir": "./out-tsc/spec",
  },
  "include": ["src/**/*.spec.ts", "src/**/*.test.ts", "src/**/*.d.ts"],
  "references": [{ "path": "./tsconfig.lib.json" }],
}
```

{% /tabitem %}
{% /tabs %}

After updating the tsconfig files, run `nx sync` to have Nx add the correct project references.

{% aside type="caution" title="Circular dependencies" %}
TypeScript project references don't support circular dependencies. If project A depends on project B and B depends on A, `tsc --build` will fail. Run `nx graph` to visualize your dependency graph and resolve any cycles before migrating. This may require extracting shared code into a new library.
{% /aside %}

### E2E projects

End-to-end test projects (Cypress, Playwright) typically have a `tsconfig.json` but no `tsconfig.lib.json`. These projects don't need a `build` target or `tsconfig.lib.json`. They only need `tsconfig.json` to extend `tsconfig.base.json` with `references` to the projects they test. The `@nx/js/typescript` plugin adds the correct references via `nx sync`.

{% aside type="caution" title="Exclude out-tsc from E2E tsconfig" %}
If your E2E project's `tsconfig.json` uses a broad `include` like `"**/*.ts"`, it may pick up stale `.d.ts` files from the `out-tsc/` directory, causing **TS5055: Cannot write file — would overwrite input file** errors. Add `"exclude": ["out-tsc"]` to prevent this.
{% /aside %}

### Verify `include`/`exclude` patterns

Since `tsconfig.lib.json` and `tsconfig.spec.json` now extend `tsconfig.base.json` directly instead of the project's `tsconfig.json`, any `include` or `exclude` patterns that were defined in the project `tsconfig.json` are no longer inherited. Check that each solution file has the correct `include` and `exclude` patterns, and add any that were previously inherited.

For example, if your project `tsconfig.json` had an `include` that the solution files relied on:

{% tabs %}
{% tabitem label="Before" %}

```jsonc
// libs/ui/tsconfig.json (had include that solution files inherited)
{
  "extends": "../../tsconfig.base.json",
  "include": ["src/**/*.ts", "src/**/*.tsx"]
}

// libs/ui/tsconfig.lib.json (inherited include from tsconfig.json)
{
  "extends": "./tsconfig.json",
  "exclude": ["src/**/*.spec.ts"]
}
```

{% /tabitem %}
{% tabitem label="After" %}

```jsonc
// libs/ui/tsconfig.json (no include — just references)
{
  "extends": "../../tsconfig.base.json",
  "files": [],
  "include": [],
  "references": [
    { "path": "./tsconfig.lib.json" },
    { "path": "./tsconfig.spec.json" }
  ]
}

// libs/ui/tsconfig.lib.json (include must be explicit now)
{
  "extends": "../../tsconfig.base.json",
  "include": ["src/**/*.ts", "src/**/*.tsx"],
  "exclude": ["src/**/*.spec.ts"]
}
```

{% /tabitem %}
{% /tabs %}

## Update import paths

If your new package names match the old TypeScript path aliases exactly, no import changes are needed. If you renamed packages (e.g. to resolve the multiple-slash restriction), update all import statements across the codebase.

Search and replace in files with these extensions: `.ts`, `.tsx`, `.js`, `.jsx`, `.mts`, `.cts`, `.mjs`, `.cjs`.

For example, if you renamed `@myorg/shared/ui` to `@myorg/shared-ui`:

```diff
- import { Button } from '@myorg/shared/ui';
+ import { Button } from '@myorg/shared-ui';
```

{% aside type="tip" title="Automating import updates" %}
Use your IDE's global find-and-replace or a tool like `sed` for bulk replacements. Verify the replacements don't affect string literals or comments that contain the old path.
{% /aside %}

## Bundler configuration updates

### Webpack and Rspack

If your applications use `NxAppWebpackPlugin` from `@nx/webpack` or `NxAppRspackPlugin` from `@nx/rspack`, no changes are needed. Both plugins detect TS solution workspaces and disable `TsconfigPathsPlugin`, relying on `node_modules` symlinks instead.

### Jest

If your projects use Jest with the `@nx/jest` resolver (`@nx/jest/plugins/resolver`), no changes are needed. The resolver falls back to TypeScript module resolution when the default Node resolver fails, finding local projects through `node_modules` symlinks.

### Vite

Update `vite.config.ts` for each Vite project:

1. Remove `nxViteTsPaths` from `plugins` (if present). This plugin resolved TypeScript path aliases in older Nx versions. After migration, Vite built-in resolver finds local projects through `node_modules` symlinks. Newer Nx versions may not include this plugin.
2. Add `resolve.conditions` with the same custom condition used in `tsconfig.base.json` (e.g. `@myorg/source`). This lets Vite resolve workspace libraries to source files during dev server and test runs, matching TypeScript's `customConditions` behavior. See [Testing without building dependencies](/docs/technologies/test-tools/vitest/guides/testing-without-building-dependencies) for more details on how this works.
3. Set `build.outDir` to `./dist` relative to the project folder.

{% aside type="note" title="Vitest" %}
If your `vitest.config.ts` or `vitest.config.mts` also uses `nxViteTsPaths`, remove it and add `resolve.conditions` there as well.
{% /aside %}

{% tabs %}
{% tabitem label="Before" %}

```ts
// libs/ui/vite.config.ts
import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
import { nxCopyAssetsPlugin } from '@nx/vite/plugins/nx-copy-assets.plugin';

export default defineConfig({
  // ...
  plugins: [react(), nxViteTsPaths(), nxCopyAssetsPlugin(['*.md'])],
  build: {
    outDir: '../../dist/libs/ui',
    // ...
  },
});
```

{% /tabitem %}
{% tabitem label="After" %}

```ts
// libs/ui/vite.config.ts
import { nxCopyAssetsPlugin } from '@nx/vite/plugins/nx-copy-assets.plugin';

export default defineConfig({
  // ...
  plugins: [react(), nxCopyAssetsPlugin(['*.md'])],
  resolve: {
    conditions: ['@myorg/source'],
  },
  build: {
    outDir: './dist',
    // ...
  },
});
```

{% /tabitem %}
{% /tabs %}

## Verify the migration

{% llm_only %}
Before running verification, clear the Nx daemon cache with `nx reset` to avoid stale state. Also run `nx sync` first to ensure all project references are up to date.
{% /llm_only %}

Run the full target suite to confirm everything works:

```shell
nx run-many -t typecheck,build,lint,test
```

Fix any issues that come up before continuing. Common problems at this stage include:

- **Missing `references`**: Run `nx sync` to populate project references automatically.
- **TS2307 "Cannot find module"**: If the error suggests updating to `node16`, `nodenext`, or `bundler`, your `moduleResolution` is set to `"node"` (Node10) which does not support the `exports` field in `package.json`. Change `moduleResolution` to `"bundler"` in `tsconfig.base.json`.
- **TS5095 `module: "commonjs"` incompatible with `moduleResolution: "bundler"`**: Project-level tsconfigs (especially spec and e2e files) that set `module: "commonjs"` will conflict with `moduleResolution: "bundler"` inherited from the base config. Remove `module` and `moduleResolution` from these files — Jest and Vitest use their own transformers and don't rely on the tsconfig `module` setting for execution.
- **Import path errors**: Ensure all import paths match the `name` field in each project's `package.json`.
- **Missing `exports` in `package.json`**: Verify each library has an `exports` field. Non-buildable libraries should point all conditions to source (e.g. `./src/index.ts`). Buildable libraries should point `import`/`default` to compiled output (e.g. `./dist/index.js`) but keep `types` pointing to source so TypeScript resolves correctly within the monorepo.
- **`@nx/dependency-checks` lint errors**: For buildable libraries, this lint rule requires runtime workspace dependencies to be in `dependencies` (not `devDependencies`). If the rule reports a missing dependency for a workspace library that is imported in production code, move it from `devDependencies` to `dependencies`.
- **`@nx/dependency-checks` false positives for dev tool packages**: Buildable libraries using this rule may report missing dependencies for packages like `vitest`, `@nx/vite`, or `jest` after migration. This happens because the rule scans config files like `vitest.config.mts` and detects imports that shouldn't be declared as project-level dependencies — they belong in the root `package.json`. Do not add these packages to individual project `package.json` files. Instead, add the config files to `ignoredFiles` in the lint rule configuration:

  ```js
  // eslint.config.mjs
  '@nx/dependency-checks': [
    'error',
    {
      ignoredFiles: [
        '{projectRoot}/eslint.config.{js,cjs,mjs,ts,cts,mts}',
        '{projectRoot}/vite.config.{js,ts,mjs,mts}',
        '{projectRoot}/vitest.config.{js,ts,mjs,mts}',
        '{projectRoot}/jest.config.{js,ts,cjs,cts,mjs,mts}',
      ],
    },
  ],
  ```

Once the above passes, run end-to-end tests:

```shell
nx run-many -t e2e
```

{% aside type="tip" title="Run e2e tests individually" %}
E2e tests are slow and each one spins up a dev server, so it's easier to debug failures one project at a time rather than running them all at once. Use `nx e2e my-app-e2e` to isolate issues.
{% /aside %}

Fix any e2e failures before considering the migration complete. Common e2e issues include:

- **Vite/webpack dev server resolution failures**: Confirm `nxViteTsPaths` was removed and workspace symlinks are in place (`node_modules/@myorg/lib` should be a symlink to the library directory).
- **Cypress/Playwright projects missing tsconfig changes**: E2e projects need the same tsconfig restructuring as other projects. Their solution files should extend `tsconfig.base.json` directly.

{% llm_only %}
If `typecheck` fails with TS6305 ("Output file has not been built from source file"), the project references are missing or stale. Run `nx sync` and retry. If errors persist, check that each `tsconfig.lib.json` has `"composite": true` inherited from `tsconfig.base.json` and that `outDir` is set to a unique path per solution file.

If you encounter TS2307 ("Cannot find module") after removing `paths`:

- Check if the error message suggests `node16`, `nodenext`, or `bundler`. If so, `moduleResolution` is `"node"` which cannot resolve `exports` fields. Change it to `"bundler"` in `tsconfig.base.json`.
- Verify `npm install`/`pnpm install` was run to create workspace symlinks.
- Verify the `name` field in the library's `package.json` matches the import path.
- Verify the consuming project lists the library in its `devDependencies`.

CRITICAL: When fixing `@nx/dependency-checks` lint errors, NEVER add `nx`, `@nx/*`, `vitest`, `@nx/vite`, `jest`, or other dev tool packages to individual project `package.json` files. These packages MUST only be in the root `package.json` to keep versions in sync across the monorepo. If the lint rule reports these as missing dependencies, the correct fix is to add the config files that import them (e.g. `vite.config.mts`, `vitest.config.mts`) to the rule's `ignoredFiles` list in `eslint.config.mjs`. Only workspace library dependencies (e.g. `@myorg/utils`) belong in project-level `package.json` files.

Resolve all errors before considering the migration complete.
{% /llm_only %}

---
<!-- source: https://nx.dev/docs/technologies/typescript/introduction.md -->
## TypeScript Plugin for Nx

The TypeScript plugin for Nx, `@nx/js`, provides [generators for creating TypeScript and JavaScript projects](#generate-and-manage-typescript-libraries), and the `@nx/js/typescript` plugin automatically infers [`typecheck` and `build` tasks](#how-the-typescript-plugin-infers-tasks) for your projects using package manager workspaces and TypeScript project references. Maintaining TypeScript project references in a monorepo can be cumbersome, the `@nx/js` plugin comes with a [sync generator](/docs/concepts/sync-generators) to automatically upkeep these references.

You don't need the plugin to use TypeScript with Nx, any project already benefits from [caching](/docs/features/cache-task-results), [task orchestration](/docs/features/run-tasks), and the [project graph](/docs/features/explore-graph). The plugin can help simplify setups and maintenance of TypeScript projects at scale.

## Requirements

Nx supports the latest version of TypeScript. TypeScript itself only officially supports its latest release under the [Modern Lifecycle Policy](https://learn.microsoft.com/en-us/lifecycle/policies/modern), but Nx maintains a wider range to give you time to upgrade. Support for an older TypeScript version may be dropped in an Nx major release, and support for a newer version may be added in an Nx minor release.

| Nx Version     | TypeScript Version |
| -------------- | ------------------ |
| 22.x (current) | >= 5.4.2 < 5.10.0  |
| 21.x           | >= 5.4.2 < 5.10.0  |
| 20.x           | ~5.4.2             |

## Setting up @nx/js plugin

### Add to an existing Nx workspace

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/js` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
Using `nx add` helps ensure the correct version is installed and configured.
{% /aside %}

```shell
nx add @nx/js
```

Verify the plugin is setup:

{% steps %}

1. Check for the `@nx/js` listed as a plugin:

   ```shell
   nx report
   ```

2. Ensure inferred project targets are working:

   ```shell
   nx show projects --with-target=typecheck
   ```

3. Inspect a specific project configuration for the `typecheck`/`build` target, depending on your project configuration:

   ```shell
   nx show project <ts-project-name>
   ```

{% /steps %}

If your TypeScript projects aren't showing up with the right targets, then [view read how `@nx/js` infers projects](#how-the-typescript-plugin-infers-tasks)

### Create a new TypeScript monorepo

{% tabs syncKey="package-manager" %}
{% tabitem label="npm" %}

```shell
npx create-nx-workspace my-org --template nrwl/typescript-template
```

{% /tabitem %}
{% tabitem label="yarn" %}

```shell
yarn create nx-workspace my-org --template nrwl/typescript-template
```

{% /tabitem %}
{% tabitem label="pnpm" %}

```shell
pnpm create nx-workspace my-org --template nrwl/typescript-template
```

{% /tabitem %}
{% /tabs %}

This creates a monorepo configured with [TypeScript Project References](https://www.typescriptlang.org/docs/handbook/project-references.html) and your package manager's [workspaces](https://docs.npmjs.com/cli/using-npm/workspaces) feature. [Nx automatically maintains the project references](/docs/features/maintain-typescript-monorepos) as you add and remove projects.

{% aside type="tip" title="Tutorial" %}
For a guided walkthrough, follow the [Learn Nx Tutorial](/docs/getting-started/tutorials/crafting-your-workspace).
{% /aside %}

The `--template nrwl/typescript-template` uses the modern setup with workspaces and project references as of Nx 20.
You can [migrate an existing workspace from path aliases ](/docs/technologies/typescript/guides/switch-to-workspaces-project-references) to the modern setup.

If you want to keep using the older style of setups with `compilerOptions.paths`, use `create-nx-workspace --preset=apps`.

### Add build support to an existing project

If you have a TypeScript project that doesn't have a build target, you can use the [`setup-build` generator](/docs/technologies/typescript/generators#setup-build) to add one:

```shell
nx g @nx/js:setup-build my-lib
```

You'll be prompted to choose a bundler. This configures the project for compilation without recreating it from scratch.

## Generate and manage TypeScript libraries

### Create a library

Quickly scaffold out a new typescript library. You'll be prompted for common options like test runner and linter.
See all the [library generator options](/docs/technologies/typescript/generators#library) for more customization.

```shell
nx g @nx/js:lib libs/my-lib
```

### Create a buildable or publishable library

To create a library that can be compiled and published to npm, specify a bundler:

```shell
# Using TSC (default compiler)
nx g @nx/js:lib libs/my-lib --bundler=tsc

# Using SWC (faster compilation)
nx g @nx/js:lib libs/my-lib --bundler=swc

# Using Rollup (to output in multiple formats)
nx g @nx/js:lib libs/my-lib --bundler=rollup
```

If you plan to publish your library to npm, then you can pass in the `--publishable` flag to automatically setup [Nx Release](/docs/guides/nx-release/release-npm-packages) to manage the releasing process.

```shell
nx g @nx/js:lib libs/my-lib --bundler=tsc --publishable
```

By default, `@nx/js` uses [TSC](https://www.typescriptlang.org/docs/handbook/2/basic-types.html#tsc-the-typescript-compiler) to compile libraries. You can convert to use [SWC](https://swc.rs) for faster compilation at any time with the `convert-to-swc` generator:

```shell
nx g @nx/js:convert-to-swc my-lib
```

SWC dependencies are installed automatically the first time the generator is ran.

### Build TypeScript libraries

```shell
nx build my-lib
```

The output location is controlled by `outDir` in your build tsconfig (defaults to `tsconfig.lib.json`):

```json
// packages/my-lib/tsconfig.lib.json
{
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  }
}
```

The plugin reads `outDir` automatically and sets the correct [task outputs](/docs/concepts/how-caching-works) for caching.

If you're manually defining the `build` targets, make sure to keep the [target configuration outputs](/docs/guides/tasks--caching/configure-outputs) in sync with where typescript is outputting the built artifacts. This ensures Nx properly restores the cache for your build tasks.

### Run typechecking

```shell
nx typecheck my-lib
```

The `typecheck` task is automatically inferred for any project with a `tsconfig.json`.

If you're not using inferred plugins, then you can manually define a `typecheck` target in your [projects configuration](/docs/reference/project-configuration#project-level-configuration-files).

## Configure `@nx/js` TypeScript inference

By default, when you add the `@nx/js` the plugin will be configured to use project and target inference.

Otherwise you can manually add the [plugin to your `nx.json#plugins` to enable it](#plugin-options)

### How the TypeScript plugin infers tasks

The `@nx/js/typescript` plugin adds tasks based on the files it finds in your project:

The `@nx/js/typescript` plugin will add a `typecheck` task to any project that has a `tsconfig.json`.

The plugin also adds a `build` task for projects that meet both of the following conditions:

1. Have a runtime tsconfig file (defaults to `tsconfig.lib.json`)
2. Have a `package.json` with entry points that reference compiled output (not source files)

For example, this project **will** get a `build` task because its exports point to `dist/`:

```json
// packages/my-lib/package.json
{
  "name": "@my-org/my-lib",
  "exports": {
    "./package.json": "./package.json",
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  }
}
```

This project **will not** get a `build` task because its exports point directly to source:

```json
// packages/my-lib/package.json
{
  "name": "@my-org/my-lib",
  "exports": {
    "./package.json": "./package.json",
    ".": "./src/index.ts"
  }
}
```

This distinction is important in monorepos — not all libraries need to be compiled. Libraries consumed only within the monorepo can point directly to source for faster development, while libraries published to npm need a build step. See [TypeScript Project Linking](/docs/concepts/typescript-project-linking) for more on how projects reference each other.

### Plugin options

Configure `@nx/js/typescript` in the `plugins` array in `nx.json`:

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/js/typescript",
      "options": {
        "typecheck": {
          "targetName": "typecheck"
        },
        "build": {
          "targetName": "build",
          "configName": "tsconfig.lib.json",
          "buildDepsName": "build-deps",
          "watchDepsName": "watch-deps"
        }
      }
    }
  ]
}
```

| Option                 | Description                                               | Default             |
| ---------------------- | --------------------------------------------------------- | ------------------- |
| `typecheck.targetName` | Name of the typecheck task                                | `typecheck`         |
| `build.targetName`     | Name of the build task                                    | `build`             |
| `build.configName`     | The tsconfig file used for builds                         | `tsconfig.lib.json` |
| `build.buildDepsName`  | Name of the task for building all dependencies            | `build-deps`        |
| `build.watchDepsName`  | Name of the task for watching and rebuilding dependencies | `watch-deps`        |

Set `typecheck` or `build` to `false` to disable that task entirely.

### Exclude or include specific projects

You can control which projects the plugin applies to at three levels:

**Plugin-level:** Use `include`/`exclude` glob patterns to scope the plugin to specific projects:

```json {% meta="{5-6}" %}
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/js/typescript",
      "include": ["packages/**/*"],
      "exclude": ["packages/legacy-app/**/*"],
      "options": { ... }
    }
  ]
}
```

**Project-level:** To opt a specific project out of the `typecheck` task, set `nx.addTypecheckTarget` to `false` in that project's `tsconfig.json`:

```json {% meta="{6-8}" %}
// packages/my-lib/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "files": [],
  "include": [],
  "references": [{ "path": "./tsconfig.lib.json" }],
  "nx": {
    "addTypecheckTarget": false
  }
}
```

### View inferred tasks

To see what tasks Nx inferred for a project:

```shell
nx show project <my-project>
```

Or open the [project details view in Nx Console](/docs/guides/nx-console/console-project-details#_top).

## CI considerations for TypeScript projects

See [Set Up CI](/docs/guides/nx-cloud/setup-ci) for a complete CI configuration guide.

### Build and test only what changed

```shell
nx affected -t build test typecheck lint
```

This uses the [project graph](/docs/features/explore-graph) to determine which projects are affected by your changes and only runs tasks for those.
Read more about [the benefits of `nx affected`](/docs/features/ci-features/affected).

### Remote caching

Share build and typecheck cache results across your team and CI with [remote caching](/docs/features/ci-features/remote-cache):

```shell
nx connect
```

### Batch mode

For large monorepos with many TypeScript projects, [TSC batch mode](/docs/technologies/typescript/guides/enable-tsc-batch-mode) can improve build performance by batching compilation across projects.

## What's next

{% cardgrid %}
{% linkcard title="Learn Nx Tutorial" description="Build a TypeScript monorepo step-by-step with Nx." href="/docs/getting-started/tutorials/crafting-your-workspace" /%}
{% linkcard title="Switch to Workspaces & Project References" description="Migrate from path aliases to the modern monorepo setup." href="/docs/technologies/typescript/guides/switch-to-workspaces-project-references" /%}
{% linkcard title="Compile to Multiple Formats" description="Build libraries to both ESM and CommonJS with Rollup." href="/docs/technologies/typescript/guides/compile-multiple-formats" /%}
{% linkcard title="Generators Reference" description="Full API reference for @nx/js generators." href="/docs/technologies/typescript/generators" /%}
{% linkcard title="Executors Reference" description="Full API reference for @nx/js executors." href="/docs/technologies/typescript/executors" /%}
{% linkcard title="Migrations Reference" description="Full reference for @nx/js migrations." href="/docs/technologies/typescript/migrations" /%}
{% /cardgrid %}

---
<!-- source: https://nx.dev/docs/technologies/typescript/migrations.md -->
## @nx/js Migrations

The @nx/js plugin provides various migrations to help you migrate to newer versions of js projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 22.6.x

### 22.6.4-package-updates
**Version**: 22.6.4


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `verdaccio` | `^6.3.2` | Updated only



## 22.5.x

### 22.5.0-package-updates
**Version**: 22.5.0-beta.1


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@swc/core` | `^1.15.5` | Updated only
| `@swc/cli` | `^0.7.10` | Updated only
| `@swc/helpers` | `^0.5.18` | Updated only
| `@swc-node/register` | `^1.11.1` | Updated only



## 22.1.x

### `remove-redundant-ts-project-references`
**Version**: 22.1.0-rc.1

Removes redundant TypeScript project references from project's tsconfig.json files when runtime tsconfig files (e.g., tsconfig.lib.json, tsconfig.app.json) exist.

#### Removes Redundant TypeScript Project References from tsconfig.json Files

Removes redundant TypeScript project references from `tsconfig.json` files when runtime tsconfig files (e.g., `tsconfig.lib.json`, `tsconfig.app.json`) exist. Previously, external project references were duplicated in both the project's `tsconfig.json` and runtime tsconfig files. This migration syncs the TypeScript project references to match the project graph, ensuring that external references only appear in runtime tsconfig files when they exist.

#### Examples

When a project has runtime tsconfig files like `tsconfig.lib.json`, the migration will remove external project references from the project's `tsconfig.json` file:

##### Before

```jsonc {7-9}
// libs/my-lib/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
  },
  "references": [
    {
      "path": "../other-lib",
    },
  ],
}
```

##### After

```jsonc {6}
// libs/my-lib/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
  },
  "references": [],
}
```

The external references remain in the runtime tsconfig file where they belong:

##### Before

```jsonc {7-9}
// libs/my-lib/tsconfig.lib.json
{
  "compilerOptions": {
    "composite": true,
  },
  "references": [
    {
      "path": "../other-lib/tsconfig.lib.json",
    },
  ],
}
```

##### After

```jsonc {7-9}
// libs/my-lib/tsconfig.lib.json
{
  "compilerOptions": {
    "composite": true,
  },
  "references": [
    {
      "path": "../other-lib/tsconfig.lib.json",
    },
  ],
}
```

For projects without runtime tsconfig files, the project's `tsconfig.json` file will continue to contain external project references:

##### Before

```jsonc {7-9}
// libs/legacy-lib/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
  },
  "references": [
    {
      "path": "../other-lib",
    },
  ],
}
```

##### After

```jsonc {7-9}
// libs/legacy-lib/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
  },
  "references": [
    {
      "path": "../other-lib",
    },
  ],
}
```

Internal project references (references within the same project directory) are preserved in the project's `tsconfig.json`:

##### Before

```jsonc {7-12}
// libs/my-lib/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
  },
  "references": [
    {
      "path": "./tsconfig.lib.json",
    },
    {
      "path": "./tsconfig.spec.json",
    },
  ],
}
```

##### After

```jsonc {7-12}
// libs/my-lib/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
  },
  "references": [
    {
      "path": "./tsconfig.lib.json",
    },
    {
      "path": "./tsconfig.spec.json",
    },
  ],
}
```




## 22.0.x

### `remove-external-options-from-js-executors`
**Version**: 22.0.0-beta.0

Remove the deprecated `external` and `externalBuildTargets` options from the `@nx/js:swc` and `@nx/js:tsc` executors.

#### Remove the `external` and `externalBuildTargets` Options from the `@nx/js:swc` and `@nx/js:tsc` Executors

Remove the deprecated `external` and `externalBuildTargets` options from the `@nx/js:swc` and `@nx/js:tsc` executors. These options were used for inlining dependencies, which was an experimental feature and has been deprecated for a long time. The migration only removes the options from the project configuration and target defaults. If you rely on inlining dependencies, you need to make sure they are all buildable or use a different build tool that supports bundling.

#### Sample Code Changes

Remove `external` and `externalBuildTargets` from the `@nx/js:swc` or `@nx/js:tsc` executor options in project configuration.

##### Before

```json title="libs/my-lib/project.json" {9-10}
{
  "targets": {
    "build": {
      "executor": "@nx/js:swc",
      "options": {
        "main": "libs/my-lib/src/index.ts",
        "outputPath": "dist/libs/my-lib",
        "tsConfig": "libs/my-lib/tsconfig.lib.json",
        "external": ["react", "react-dom"],
        "externalBuildTargets": ["build"]
      }
    }
  }
}
```

##### After

```json title="libs/my-lib/project.json"
{
  "targets": {
    "build": {
      "executor": "@nx/js:swc",
      "options": {
        "main": "libs/my-lib/src/index.ts",
        "outputPath": "dist/libs/my-lib",
        "tsConfig": "libs/my-lib/tsconfig.lib.json"
      }
    }
  }
}
```

Remove `external` and `externalBuildTargets` from the `@nx/js:swc` or `@nx/js:tsc` executor target defaults in `nx.json`.

##### Before

```json title="nx.json" {8-9}
{
  "targetDefaults": {
    "@nx/js:swc": {
      "options": {
        "main": "{projectRoot}/src/index.ts",
        "outputPath": "dist/{projectRoot}",
        "tsConfig": "{projectRoot}/tsconfig.lib.json",
        "external": "all",
        "externalBuildTargets": ["build"]
      }
    }
  }
}
```

##### After

```json title="nx.json"
{
  "targetDefaults": {
    "@nx/js:swc": {
      "options": {
        "main": "{projectRoot}/src/index.ts",
        "outputPath": "dist/{projectRoot}",
        "tsConfig": "{projectRoot}/tsconfig.lib.json"
      }
    }
  }
}
```




## 21.5.x

### `migrate-development-custom-condition`
**Version**: 21.5.0-beta.2

Migrate the legacy 'development' custom condition to a workspace-unique custom condition name.

#### Migrate `development` custom condition to unique workspace-specific name

Replace the TypeScript `development` custom condition with a unique workspace-specific name to avoid conflicts when consuming packages in other workspaces.

#### Examples

The migration will update the custom condition name in both `tsconfig.base.json` and all workspace package.json files that use the `development` custom condition:

##### Before

```json title="tsconfig.base.json" {3}
{
  "compilerOptions": {
    "customConditions": ["development"]
  }
}
```

##### After

```json title="tsconfig.base.json" {3}
{
  "compilerOptions": {
    "customConditions": ["@my-org/source"] // assuming the root package.json name is `@my-org/source`
  }
}
```

The migration also updates `package.json` files that use the `development` condition in their `exports` field and point to TypeScript files:

##### Before

```json title="libs/my-lib/package.json" {5}
{
  "name": "@myorg/my-lib",
  "exports": {
    ".": {
      "development": "./src/index.ts",
      "default": "./dist/index.js"
    }
  }
}
```

##### After

```json title="libs/my-lib/package.json" {5}
{
  "name": "@myorg/my-lib",
  "exports": {
    ".": {
      "@my-org/source": "./src/index.ts",
      "default": "./dist/index.js"
    }
  }
}
```

If the custom condition is not set to `["development"]` or the `package.json`'s `exports` field doesn't point to TypeScript files, the migration will not modify the configuration:

##### Before

```json title="libs/my-lib/package.json" {5}
{
  "name": "@myorg/my-lib",
  "exports": {
    ".": {
      "development": "./dist/index.js",
      "default": "./dist/index.js"
    }
  }
}
```

##### After

```json title="libs/my-lib/package.json" {5}
{
  "name": "@myorg/my-lib",
  "exports": {
    ".": {
      "development": "./dist/index.js",
      "default": "./dist/index.js"
    }
  }
}
```



### 21.5.0-package-updates
**Version**: 21.5.0-beta.2


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `typescript` | `~5.9.2` | Updated only



## 21.2.x

### 21.2.0-package-updates
**Version**: 21.2.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `typescript` | `~5.8.2` | Updated only



## 20.7.x

### 20.7.1-beta.0-package-updates
**Version**: 20.7.1-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@swc/cli` | `~0.6.0` | Updated only



## 20.5.x

### 20.5.0-package-updates
**Version**: 20.5.0-beta.3


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `verdaccio` | `^6.0.5` | Updated only



## 20.4.x

### 20.4.0-package-updates
**Version**: 20.4.0-beta.1


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `typescript` | `~5.7.2` | Updated only



## 20.2.x

### 20.2.0-package-updates
**Version**: 20.2.0-beta.5


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `typescript` | `~5.6.2` | Updated only

---
<!-- source: https://nx.dev/docs/technologies/vue.md -->
## Vue

{% index_page_cards path="technologies/vue" /%}

---
<!-- source: https://nx.dev/docs/technologies/vue/generators.md -->
## @nx/vue Generators

The @nx/vue plugin provides various generators to help you create and configure vue projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `application`
Create a Vue application for Nx.

### Examples

###### Simple Application

Create an application named `my-app`:

```shell
nx g @nx/vue:app apps/my-app
```

###### Specify style extension

Create an application named `my-app` in the `my-dir` directory and use `scss` for styles:

```shell
nx g @nx/vue:app apps/my-dir/my-app --style=scss
```

###### Add tags

Add tags to the application (used for linting).

```shell
nx g @nx/vue:app apps/my-app --tags=scope:admin,type:ui
```

**Usage:**
```bash
nx generate @nx/vue:application [options]
```

**Aliases:** `app`

**Arguments:**
```bash
nx generate @nx/vue:application <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--bundler` | string | The bundler to use. | `"vite"` |
| `--e2eTestRunner` | string | Test runner to use for end to end (E2E) tests. | `"playwright"` |
| `--inSourceTests` | boolean | When using Vitest, separate spec files will not be generated and instead will be included within the source files. Read more on the Vitest docs site: https://vitest.dev/guide/in-source.html | `false` |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"none"` |
| `--name` | string | The name of the application. |  |
| `--rootProject` | boolean | Create a application at the root of the workspace | `false` |
| `--routing` | boolean | Generate application with routes. | `false` |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--strict` | boolean | Whether to enable tsconfig strict mode or not. | `true` |
| `--style` | string | The file extension to be used for style files. | `"css"` |
| `--tags` | string | Add tags to the application (used for linting). |  |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"none"` |
| `--useProjectJson` | boolean | Use a `project.json` configuration file instead of inlining the Nx configuration in the `package.json` file. |  |

## `component`
Create a Vue Component for Nx.

**Usage:**
```bash
nx generate @nx/vue:component [options]
```

**Aliases:** `c`

**Arguments:**
```bash
nx generate @nx/vue:component <path> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--export` | boolean | When true, the component is exported from the project `index.ts` (if it exists). | `false` |
| `--fileName` | string | Create a component with this file name. |  |
| `--inSourceTests` | boolean | When using Vitest, separate spec files will not be generated and instead will be included within the source files. Read more on the Vitest docs site: https://vitest.dev/guide/in-source.html | `false` |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. | `false` |
| `--routing` | boolean | Generate a library with routes. |  |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipTests` | boolean | When true, does not create `spec.ts` test files for the new component. | `false` |

## `library`
Create a Vue Library for an Nx workspace.

**Usage:**
```bash
nx generate @nx/vue:library [options]
```

**Aliases:** `lib`

**Arguments:**
```bash
nx generate @nx/vue:library <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--appProject` | string | The application project to add the library route to. |  |
| `--bundler` | string | The bundler to use. Choosing 'none' means this library is not buildable. | `"none"` |
| `--component` | boolean | Generate a default component. | `false` |
| `--importPath` | string | The library name used to import it, like `@myorg/my-awesome-lib`. |  |
| `--inSourceTests` | boolean | When using Vitest, separate spec files will not be generated and instead will be included within the source files. | `false` |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"none"` |
| `--minimal` | boolean | Create a Vue library with a minimal setup, no separate test files. | `false` |
| `--name` | string | Library name |  |
| `--publishable` | boolean | Create a publishable library. |  |
| `--routing` | boolean | Generate library with routes. |  |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--skipTsConfig` | boolean | Do not update `tsconfig.json` for development experience. | `false` |
| `--strict` | boolean | Whether to enable tsconfig strict mode or not. | `true` |
| `--tags` | string | Add tags to the library (used for linting). |  |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"none"` |
| `--useProjectJson` | boolean | Use a `project.json` configuration file instead of inlining the Nx configuration in the `package.json` file. |  |

## `setup-tailwind`
Adds the Tailwind CSS configuration files for a given Vue project and installs, if needed, the packages required for Tailwind CSS to work.

**Usage:**
```bash
nx generate @nx/vue:setup-tailwind [options]
```

**Arguments:**
```bash
nx generate @nx/vue:setup-tailwind <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--skipFormat` | boolean | Skips formatting the workspace after the generator completes. |  |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--stylesheet` | string | Path to the styles entry point relative to the workspace root. This option is only needed if the stylesheet location cannot be found automatically. |  |

## `stories`
Generate stories/specs for all components declared in a project.

This generator will generate stories for all your components in your project. The stories will be generated using [Component Story Format 3 (CSF3)](https://storybook.js.org/blog/storybook-csf3-is-here/).

You can also use this generator to generate stories for your **Nuxt** project:

```bash
nx g @nx/vue:stories project-name
```

or

```bash
nx g @nx/nuxt:stories project-name
```

You can read more about how this generator works, in the [Storybook for Vue overview page](/recipes/storybook/overview-vue#auto-generate-stories).

When running this generator, you will be prompted to provide the following:

- The `name` of the project you want to generate the configuration for.
- Whether you want to set up [Storybook interaction tests](https://storybook.js.org/docs/angular/writing-tests/interaction-testing) (`interactionTests`). If you choose `yes`, a `play` function will be added to your stories, and all the necessary dependencies will be installed. You can read more about this in the [Nx Storybook interaction tests documentation page](/recipes/storybook/storybook-interaction-tests#setup-storybook-interaction-tests)..

You must provide a `name` for the generator to work.

By default, this generator will also set up [Storybook interaction tests](https://storybook.js.org/docs/angular/writing-tests/interaction-testing). If you don't want to set up Storybook interaction tests, you can pass the `--interactionTests=false` option, but it's not recommended.

There are a number of other options available. Let's take a look at some examples.

### Examples

#### Ignore certain paths when generating stories

```bash
nx g @nx/vue:stories --name=ui --ignorePaths=libs/ui/src/not-stories/**,**/**/src/**/*.other.*
```

This will generate stories for all the components in the `ui` project, except for the ones in the `libs/ui/src/not-stories` directory, and also for components that their file name is of the pattern `*.other.*`.

This is useful if you have a project that contains components that are not meant to be used in isolation, but rather as part of a larger component.

By default, Nx will ignore the following paths:

```text
*.stories.ts, *.stories.tsx, *.stories.js, *.stories.jsx, *.stories.mdx
```

but you can change this behaviour easily, as explained above.

#### Generate stories using JavaScript instead of TypeScript

```bash
nx g @nx/vue:stories --name=ui --js=true
```

This will generate stories for all the components in the `ui` project using JavaScript instead of TypeScript. So, you will have `.stories.js` files next to your components.

**Usage:**
```bash
nx generate @nx/vue:stories [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--project` | string [**required**] | Project for which to generate stories. |  |
| `--ignorePaths` | array | Paths to ignore when looking for components. | `["*.stories.ts,*.stories.tsx,*.stories.js,*.stories.jsx,*.stories.mdx"]` |
| `--interactionTests` | boolean | Set up Storybook interaction tests. | `true` |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |

## `storybook-configuration`
Set up Storybook for a Vue project.

This generator will set up Storybook for your **Vue** project. You can also use this generator to generate Storybook configuration for your **Nuxt** project.

```bash
nx g @nx/vue:storybook-configuration project-name
```

or

```bash
nx g @nx/nuxt:storybook-configuration project-name
```

You can read more about how this generator works, in the [Storybook for Vue overview page](/recipes/storybook/overview-vue#generate-storybook-configuration-for-a-vue-project).

When running this generator, you will be prompted to provide the following:

- The `name` of the project you want to generate the configuration for.
- Whether you want to set up [Storybook interaction tests](https://storybook.js.org/docs/vue/writing-tests/interaction-testing) (`interactionTests`). If you choose `yes`, a `play` function will be added to your stories, and all the necessary dependencies will be installed. Also, a `test-storybook` target will be generated in your project's `project.json`, with a command to invoke the [Storybook `test-runner`](https://storybook.js.org/docs/vue/writing-tests/test-runner). You can read more about this in the [Nx Storybook interaction tests documentation page](/recipes/storybook/storybook-interaction-tests#setup-storybook-interaction-tests)..
- Whether you want to `generateStories` for the components in your project. If you choose `yes`, a `.stories.ts` file will be generated next to each of your components in your project.

You must provide a `name` for the generator to work.

By default, this generator will also set up [Storybook interaction tests](https://storybook.js.org/docs/vue/writing-tests/interaction-testing). If you don't want to set up Storybook interaction tests, you can pass the `--interactionTests=false` option, but it's not recommended.

There are a number of other options available. Let's take a look at some examples.

### Examples

#### Generate Storybook configuration

```bash
nx g @nx/vue:storybook-configuration ui
```

This will generate Storybook configuration for the `ui` project using TypeScript for the Storybook configuration files (the files inside the `.storybook` directory, eg. `.storybook/main.ts`).

#### Ignore certain paths when generating stories

```bash
nx g @nx/vue:storybook-configuration ui --generateStories=true --ignorePaths=libs/ui/src/not-stories/**,**/**/src/**/*.other.*,apps/my-app/**/*.something.ts
```

This will generate a Storybook configuration for the `ui` project and generate stories for all components in the `libs/ui/src/lib` directory, except for the ones in the `libs/ui/src/not-stories` directory, and the ones in the `apps/my-app` directory that end with `.something.ts`, and also for components that their file name is of the pattern `*.other.*`.

This is useful if you have a project that contains components that are not meant to be used in isolation, but rather as part of a larger component.

By default, Nx will ignore the following paths:

```text
*.stories.ts, *.stories.tsx, *.stories.js, *.stories.jsx, *.stories.mdx
```

but you can change this behaviour easily, as explained above.

#### Generate stories using JavaScript instead of TypeScript

```bash
nx g @nx/vue:storybook-configuration ui --generateStories=true --js=true
```

This will generate stories for all the components in the `ui` project using JavaScript instead of TypeScript. So, you will have `.stories.js` files next to your components.

#### Generate Storybook configuration using JavaScript

```bash
nx g @nx/vue:storybook-configuration ui --tsConfiguration=false
```

By default, our generator generates TypeScript Storybook configuration files. You can choose to use JavaScript for the Storybook configuration files of your project (the files inside the `.storybook` directory, eg. `.storybook/main.js`).

**Usage:**
```bash
nx generate @nx/vue:storybook-configuration [options]
```

**Arguments:**
```bash
nx generate @nx/vue:storybook-configuration <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--configureStaticServe` | boolean | Specifies whether to configure a static file server target for serving storybook. Helpful for speeding up CI build/test times. | `true` |
| `--generateStories` | boolean | Automatically generate `*.stories.ts` files for components declared in this project? | `true` |
| `--ignorePaths` | array | Paths to ignore when looking for components. | `["*.stories.ts,*.stories.tsx,*.stories.js,*.stories.jsx,*.stories.mdx"]` |
| `--interactionTests` | boolean | Set up Storybook interaction tests. | `true` |
| `--js` | boolean | Generate JavaScript story files rather than TypeScript story files. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"eslint"` |
| `--tsConfiguration` | boolean | Configure your project with TypeScript. Generate main.ts and preview.ts files, instead of main.js and preview.js. | `true` |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/vue:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/vue/introduction.md -->
## Vue Plugin for Nx

The Nx plugin for [Vue](https://vuejs.org/).

## Requirements

The `@nx/vue` plugin supports the following package versions.

| Package | Supported Versions |
| ------- | ------------------ |
| `vue`   | ^3.5.13            |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

## Setting up @nx/vue

### Generating a new workspace

To create a new workspace with Vue, run `npx create-nx-workspace@latest --preset=vue`.

### Installation

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/vue` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
{% /aside %}

In any Nx workspace, you can install `@nx/vue` by running the following command:

```shell
nx add @nx/vue
```

This will install the correct version of `@nx/vue`.

## Using the @nx/vue plugin

### Generate a new project using Vue

To generate a Vue application, run the following:

```shell
nx g @nx/vue:app apps/my-app
```

To generate a Vue library, run the following:

```shell
nx g @nx/vue:lib libs/my-lib
```

---
<!-- source: https://nx.dev/docs/technologies/vue/migrations.md -->
## @nx/vue Migrations

The @nx/vue plugin provides various migrations to help you migrate to newer versions of vue projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 22.0.x

### 22.0.0-package-updates
**Version**: 22.0.0-beta.8


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `@vitejs/plugin-vue` | `^6.0.1` | Updated only



## 20.7.x

### 20.7.1-package-updates
**Version**: 20.7.1-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `vue` | `^3.5.13` | Updated only
| `vue-tsc` | `^2.2.8` | Updated only
| `vue-router` | `^4.5.0` | Updated only
| `@vitejs/plugin-vue` | `^5.2.3` | Updated only

---
<!-- source: https://nx.dev/docs/technologies/vue/nuxt.md -->
## Nuxt

{% index_page_cards path="technologies/vue/nuxt" /%}

---
<!-- source: https://nx.dev/docs/technologies/vue/nuxt/generators.md -->
## @nx/nuxt Generators

The @nx/nuxt plugin provides various generators to help you create and configure nuxt projects within your Nx workspace.
Below is a complete reference for all available generators and their options.

## `application`
Create a Nuxt Application for Nx.

Your new Nuxt application will be generated with the following directory structure, following the suggested [directory structure](https://nuxt.com/docs/guide/directory-structure) for Nuxt applications:

```text
my-nuxt-app
├── nuxt.config.ts
├── project.json
├── src
│   ├── app.vue
│   ├── assets
│   │   └── css
│   │       └── styles.css
│   ├── components
│   │   └── NxWelcome.vue
│   ├── pages
│   │   ├── about.vue
│   │   └── index.vue
│   ├── public
│   │   └── favicon.ico
│   └── server
│       ├── api
│       │   └── greet.ts
│       └── tsconfig.json
├── tsconfig.app.json
├── tsconfig.json
├── tsconfig.spec.json
└── vitest.config.ts
```

Your new app will contain the following:

- Two pages (home and about) under `pages`
- A component (`NxWelcome`) under `components`
- A `greet` API endpoint that returns a JSON response under `/api/greet`
- Configuration for `vitest`
- Your app's entrypoint (`app.vue`) will contain the navigation links to the home and about pages, and the `nuxt-page` component to display the contents of your pages.

### Examples

###### Create app in a nested directory

```shell
nx g @nx/nuxt:app apps/nested/myapp
```

###### Create app with vitest configured

```shell
nx g @nx/nuxt:app apps/nested/myapp --unitTestRunner=vitest
```

###### Use plain JavaScript (not TypeScript)

```shell
nx g @nx/nuxt:app apps/myapp --js
```

### Generate pages and components

You can use the the [`@nx/vue:component` generator](/nx-api/vue/generators/component) to generate new pages and components for your application. You can read more on the [`@nx/vue:component` generator documentation page](/nx-api/vue/generators/component), but here are some examples:

###### New page

```shell
nx g @nx/nuxt:component my-app/src/pages/my-page
```

###### New component

```shell
nx g @nx/nuxt:component my-app/src/components/my-cmp
```

**Usage:**
```bash
nx generate @nx/nuxt:application [options]
```

**Aliases:** `app`

**Arguments:**
```bash
nx generate @nx/nuxt:application <directory> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--e2eTestRunner` | string | Test runner to use for end to end (E2E) tests. | `"playwright"` |
| `--js` | boolean | Generate JavaScript files rather than TypeScript files. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"none"` |
| `--name` | string | The name of the application. |  |
| `--rootProject` | boolean | Create an application at the root of the workspace. | `false` |
| `--setParserOptionsProject` | boolean | Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons. | `false` |
| `--skipFormat` | boolean | Skip formatting files. | `false` |
| `--skipPackageJson` | boolean | Do not add dependencies to `package.json`. | `false` |
| `--style` | string | The file extension to be used for style files. | `"css"` |
| `--tags` | string | Add tags to the application (used for linting). |  |
| `--unitTestRunner` | string | Test runner to use for unit tests. | `"none"` |
| `--useAppDir` | boolean | Use Nuxt 4 app/ directory structure instead of src/ directory. Defaults to true for Nuxt v4, false for Nuxt v3. |  |
| `--useProjectJson` | boolean | Use a `project.json` configuration file instead of inlining the Nx configuration in the `package.json` file. |  |

## `storybook-configuration`
Set up Storybook for a Nuxt project.

This generator calls the `@nx/vue:storybook-configuration` generator under the hood. It will set up Storybook for your **Nuxt** project.

```bash
nx g @nx/nuxt:storybook-configuration project-name
```

You can read more about how this generator works, in the [Storybook for Vue overview page](/recipes/storybook/overview-vue#generate-storybook-configuration-for-a-vue-project).

When running this generator, you will be prompted to provide the following:

- The `name` of the project you want to generate the configuration for.
- Whether you want to set up [Storybook interaction tests](https://storybook.js.org/docs/vue/writing-tests/interaction-testing) (`interactionTests`). If you choose `yes`, a `play` function will be added to your stories, and all the necessary dependencies will be installed. Also, a `test-storybook` target will be generated in your project's `project.json`, with a command to invoke the [Storybook `test-runner`](https://storybook.js.org/docs/vue/writing-tests/test-runner). You can read more about this in the [Nx Storybook interaction tests documentation page](/recipes/storybook/storybook-interaction-tests#setup-storybook-interaction-tests)..
- Whether you want to `generateStories` for the components in your project. If you choose `yes`, a `.stories.ts` file will be generated next to each of your components in your project.

You must provide a `name` for the generator to work.

By default, this generator will also set up [Storybook interaction tests](https://storybook.js.org/docs/vue/writing-tests/interaction-testing). If you don't want to set up Storybook interaction tests, you can pass the `--interactionTests=false` option, but it's not recommended.

There are a number of other options available. Let's take a look at some examples.

### Examples

#### Generate Storybook configuration

```bash
nx g @nx/nuxt:storybook-configuration ui
```

This will generate Storybook configuration for the `ui` project using TypeScript for the Storybook configuration files (the files inside the `.storybook` directory, eg. `.storybook/main.ts`).

#### Ignore certain paths when generating stories

```bash
nx g @nx/nuxt:storybook-configuration ui --generateStories=true --ignorePaths="libs/ui/src/not-stories/**,**/**/src/**/*.other.*,apps/my-app/**/*.something.ts"
```

This will generate a Storybook configuration for the `ui` project and generate stories for all components in the `libs/ui/src/lib` directory, except for the ones in the `libs/ui/src/not-stories` directory, and the ones in the `apps/my-app` directory that end with `.something.ts`, and also for components that their file name is of the pattern `*.other.*`.

This is useful if you have a project that contains components that are not meant to be used in isolation, but rather as part of a larger component.

By default, Nx will ignore the following paths:

```text
*.stories.ts, *.stories.tsx, *.stories.js, *.stories.jsx, *.stories.mdx
```

but you can change this behaviour easily, as explained above.

#### Generate stories using JavaScript instead of TypeScript

```bash
nx g @nx/nuxt:storybook-configuration ui --generateStories=true --js=true
```

This will generate stories for all the components in the `ui` project using JavaScript instead of TypeScript. So, you will have `.stories.js` files next to your components.

#### Generate Storybook configuration using JavaScript

```bash
nx g @nx/nuxt:storybook-configuration ui --tsConfiguration=false
```

By default, our generator generates TypeScript Storybook configuration files. You can choose to use JavaScript for the Storybook configuration files of your project (the files inside the `.storybook` directory, eg. `.storybook/main.js`).

**Usage:**
```bash
nx generate @nx/nuxt:storybook-configuration [options]
```

**Arguments:**
```bash
nx generate @nx/nuxt:storybook-configuration <project> [options]
```

#### Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `--configureStaticServe` | boolean | Specifies whether to configure a static file server target for serving storybook. Helpful for speeding up CI build/test times. | `true` |
| `--generateStories` | boolean | Automatically generate `*.stories.ts` files for components declared in this project? | `true` |
| `--ignorePaths` | array | Paths to ignore when looking for components. | `["*.stories.ts,*.stories.tsx,*.stories.js,*.stories.jsx,*.stories.mdx"]` |
| `--interactionTests` | boolean | Set up Storybook interaction tests. | `true` |
| `--js` | boolean | Generate JavaScript story files rather than TypeScript story files. | `false` |
| `--linter` | string | The tool to use for running lint checks. | `"eslint"` |
| `--tsConfiguration` | boolean | Configure your project with TypeScript. Generate main.ts and preview.ts files, instead of main.js and preview.js. | `true` |

## Getting Help

You can get help for any generator by adding the `--help` flag:

```bash
nx generate @nx/nuxt:<generator> --help
```

---
<!-- source: https://nx.dev/docs/technologies/vue/nuxt/guides.md -->
## Guides

{% index_page_cards path="technologies/vue/nuxt/guides" /%}

---
<!-- source: https://nx.dev/docs/technologies/vue/nuxt/guides/deploy-nuxt-to-vercel.md -->
## Deploying Nuxt applications to Vercel

## Configure your Nuxt application appropriately for Vercel deployment

In your application's `nuxt.config.ts` file, ensure that the `nitro` property is configured to use the `vercel` preset, and that the `output.dir` property is set to the appropriate directory. The directory that Vercel expects to find the application's build output (as explained in the [Vercel documentation](https://vercel.com/docs/build-output-api/v3)) in is `.vercel/output` at the root of the repository/workspace. So, if your application is located at `apps/my-app` then the `output.dir` property should be set to `../../.vercel/output`.

For example, if your Nx workspace is structured like this:

{%filetree %}

- apps/
  - my-app/
    - nuxt.config.ts
    - src/
    - tsconfig.app.json
    - tsconfig.json
    - tsconfig.spec.json
- nx.json
- package-lock.json
- package.json
- tsconfig.base.json

{% /filetree %}
Then your `nitro` configuration should look like this:

```ts {% meta="{2-6}" %}
// apps/my-app/nuxt.config.ts
  nitro: {
    preset: 'vercel',
    output:{
      dir: '../../.vercel/output'
    }
  },
```

For Vercel deployment, it does not really matter what the `buildDir` property in your `nuxt.config.ts` is set to.

So, your entire `nuxt.config.ts` file may look something like this:

```ts
// apps/my-app/nuxt.config.ts
import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
import { defineNuxtConfig } from 'nuxt/config';

export default defineNuxtConfig({
  workspaceDir: '../../',
  srcDir: 'src',
  devtools: { enabled: true },
  buildDir: '../../dist/apps/my-app/.nuxt',
  devServer: {
    host: 'localhost',
    port: 4200,
  },
  typescript: {
    typeCheck: true,
    tsConfig: {
      extends: './tsconfig.app.json',
    },
  },
  imports: {
    autoImport: false,
  },
  css: ['~/assets/css/styles.css'],
  vite: {
    plugins: [nxViteTsPaths()],
  },
  nitro: {
    preset: 'vercel',
    output: {
      dir: '../../.vercel/output',
    },
  },
});
```

## Configure your Vercel project's settings appropriately

### New Vercel project

1. If you are "importing" your Nx workspace's repository for the first time, make sure you do _not_ choose a root directory as part of the repo selection process (therefore leaving it to be the root of the full repo/workspace)
2. Ensure the Nuxt.js "Framework Preset" is selected
3. Expand the "Build & Development Settings" and toggle the override switch for the build command. For example, for an application named `my-app` the value will look like this:

```shell
npx nx build my-app --prod
```

![New Vercel Project](../../../../../../assets/guides/nuxt/nuxt-deploy-vercel-1.png)

### Existing Vercel project

If you have an existing project on Vercel then the exact same guidance applies as for the section above, it's just that you will need to update the project's existing settings.

When everything is updated appropriately, for our `my-app` example we would see the following in our "General" settings UI:

![Existing Vercel Project](../../../../../../assets/guides/nuxt/nuxt-deploy-vercel-2.png)

## Skipping build if the application is not affected

One of the core features of Nx is to run code quality checks and builds only for projects that are affected by recent code changes. We can use [Vercel's ignored build step feature](https://vercel.com/docs/platform/projects#ignored-build-step) to only build our application if it is affected.

To build only what's affected, use the `npx nx-ignore <app-name>` command under `Project Settings > Git` on Vercel.

![Ignore build step](../../../../../../assets/guides/nuxt/nuxt-deploy-vercel-3.png)

The `nx-ignore` command uses Nx to detect whether the current commit affects the specified app, and will skip the build if it is not affected.

## Next steps

Naturally, you can continue on and set any additional Environment Variables etc that may be appropriate for your projects, but we have now covered the key points needed to deploy Nuxt.js projects from Nx workspaces on Vercel!

---
<!-- source: https://nx.dev/docs/technologies/vue/nuxt/introduction.md -->
## Nuxt Plugin for Nx

The Nx plugin for [Nuxt](https://nuxt.com/).

## Requirements

The `@nx/nuxt` plugin supports the following package versions.

| Package | Supported Versions  |
| ------- | ------------------- |
| `nuxt`  | ^3.10.0 \|\| ^4.0.0 |

[Nx generators](/docs/features/generate-code) install the latest supported versions automatically when scaffolding new projects.

## Setting up a new Nx workspace with @nx/nuxt

You can create a new workspace that uses Nuxt with one of the following commands:

- Generate a new monorepo with a Nuxt app

```shell
npx create-nx-workspace@latest --preset=nuxt
```

### Installation

{% aside type="note" title="Keep Nx Package Versions In Sync" %}
Make sure to install the `@nx/nuxt` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/docs/guides/tips-n-tricks/keep-nx-versions-in-sync).
{% /aside %}

In any Nx workspace, you can install `@nx/nuxt` by running the following command:

```shell
nx add @nx/nuxt
```

This will install the correct version of `@nx/nuxt`.

### How @nx/nuxt infers tasks

The `@nx/nuxt` plugin will create a task for any project that has an Nuxt configuration file present. Any of the following files will be recognized as an Nuxt configuration file:

- `nuxt.config.js`
- `nuxt.config.ts`
- `nuxt.config.mjs`
- `nuxt.config.mts`
- `nuxt.config.cjs`
- `nuxt.config.cts`

### View inferred tasks

To view inferred tasks for a project, open the [project details view](/docs/concepts/inferred-tasks) in Nx Console or run `nx show project my-project --web` in the command line.

### @nx/nuxt configuration

The `@nx/nuxt/plugin` is configured in the `plugins` array in `nx.json`.

```json {% meta="{2-11}" %}
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/nuxt/plugin",
      "options": {
        "buildTargetName": "build",
        "testTargetName": "test",
        "serveTargetName": "serve",
        "buildStaticTargetName": "build-static",
        "serveStaticTargetName": "serve-static"
      }
    }
  ]
}
```

The `buildTargetName`, `testTargetName` and `serveTargetName` options control the names of the inferred Nuxt tasks. The default names are `build`, `test` and `serve`.

The `buildStaticTargetName` and `serveStaticTargetName` options control the names of the inferred Nuxt static tasks. The default names are `build-static` and `serve-static`.

## Using Nuxt

### Generate a new Nuxt app

```shell
nx g @nx/nuxt:app apps/my-app
```

### Deploy a Nuxt app

Once you are ready to deploy your Nuxt application, you have absolute freedom to choose any hosting provider that fits your needs.

We have detailed [how to deploy your Nuxt application to Vercel in a separate guide](/docs/technologies/vue/nuxt/guides/deploy-nuxt-to-vercel).

### E2E testing

By default `nuxt` **does not** generate static HTML files when you run the `build` command. However, Nx provides a `build-static` target that you can use to generate static HTML files for your Nuxt application. Essentially, this target runs the `nuxt build --prerender` command to generate static HTML files.

To perform end-to-end (E2E) testing on static HTML files using a test runner like Cypress. When you create a Nuxt application, Nx automatically creates a `serve-static` target. This target is designed to serve the static HTML files produced by the `build-static` command.

This feature is particularly useful for testing in continuous integration (CI) pipelines, where resources may be constrained. Unlike the `serve` target, `serve-static` does not require a Nuxt's Nitro server to operate, making it more efficient and faster by eliminating background processes, such as file change monitoring.

To use the `serve-static` target for testing, run the following command:

```shell
nx serve-static my-nuxt-app-e2e
```

This command performs several actions:

1. It will build the Nuxt application and generate the static HTML files.
2. It will serve the static HTML files using a simple HTTP server.
3. It will run the Cypress tests against the served static HTML files.

---
<!-- source: https://nx.dev/docs/technologies/vue/nuxt/migrations.md -->
## @nx/nuxt Migrations

The @nx/nuxt plugin provides various migrations to help you migrate to newer versions of nuxt projects within your Nx workspace.
Below is a complete reference for all available migrations.

## 22.2.x

### `update-22-2-0-create-ai-instructions-for-nuxt-4`
**Version**: 22.2.0-beta.0

Create AI Instructions to help migrate workspaces to Nuxt 4.


### 22.2.0-package-updates
**Version**: 22.2.0-beta.0


#### Packages

The following packages will be updated:

| Name | Version | Always add to `package.json`
|---------|----------|---------|
| `nuxt` | `^4.0.0` | Updated only
| `@nuxt/eslint-config` | `^1.10.0` | Updated only
| `@nuxt/kit` | `^4.0.0` | Updated only
| `@nuxt/schema` | `^4.0.0` | Updated only
| `@nuxt/devtools` | `^3.0.0` | Updated only


# Reference

---
<!-- source: https://nx.dev/docs/reference.md -->
## References

{% index_page_cards path="reference" /%}

---
<!-- source: https://nx.dev/docs/reference/angular.md -->
## Angular

{% sidebar_group_cards group="Reference/Angular" /%}

---
<!-- source: https://nx.dev/docs/reference/benchmarks.md -->
## Benchmarks

{% index_page_cards path="reference/benchmarks" /%}

---
<!-- source: https://nx.dev/docs/reference/benchmarks/caching.md -->
## Large Next.js Apps Made Faster with Nx

Repo contains:

- 5 shared buildable packages/libraries with 250 components each
- 5 Next.js applications built out of 20 app-specific libraries. Each app-specific lib has 250 components each. Each library uses the shared components.

The repo shows how Nx works in a large workspace. It also benchmarks Nx and explains the optimisations Nx uses to be fast.

{% github_repository url="https://github.com/vsavkin/large-monorepo" /%}

---
<!-- source: https://nx.dev/docs/reference/benchmarks/nx-agents.md -->
## Nx Agents at Scale

Repo contains:

- 5 shared buildable packages/libraries with 250 components each
- 5 Next.js applications built out of 20 app-specific libraries. Each app-specific lib has 250 components each. Each library uses the shared components.

The repo shows how Nx Agents can make the CI 16 times faster with a small configuration change.

{% github_repository url="https://github.com/vsavkin/interstellar" /%}

---
<!-- source: https://nx.dev/docs/reference/benchmarks/tsc-batch-mode.md -->
## TSC Batch Mode

![Side by side demo of normal tsc taking 1m48s and batch mode tsc taking 28s](/img/ts-benchmark.gif)

This repo compares two modes of running the `@nx/js:tsc` executor: the regular one and the batch one. The batch implementation, apart from running multiple tasks in a single process, also creates the required [TypeScript project references](https://www.typescriptlang.org/docs/handbook/project-references.html) on the fly to perform incremental builds.

{% github_repository url="https://github.com/nrwl/large-ts-monorepo" /%}

{% aside type="note" title="Potential speed improvement" %}
Depending on the use case, batch mode compilation is from 1.16 to 7.73 times faster. More details on the exact scenarios tested can be found in the [repository `README.md` file](https://github.com/nrwl/large-ts-monorepo).
{% /aside %}

## Why is the batch implementation faster?

The non-batch implementation runs each task in a separate process. Each process creates a new `ts.Program` instance and performs a full build. Creating a full `ts.Program` instance is an expensive operation. Creating processes and `ts.Program` comes with a lot of overhead. Thanks to the project graph, this is already improved by orchestrating tasks and running them in parallel. Still, there's only so much that can be run in parallel and the more deeply nested the dependencies are, the less parallelism we can achieve.

The batch implementation runs multiple tasks in a single process. This reduces the overhead of starting a new process for each task. It also creates the required [TypeScript project references](https://www.typescriptlang.org/docs/handbook/project-references.html) (based on the project graph information) on the fly to perform [incremental builds](https://www.typescriptlang.org/docs/handbook/project-references.html#build-mode-for-typescript). This is what yields the main performance benefits over the non-batch implementation. In this mode, the TypeScript compiler doesn't create a full `ts.Program` per project. Instead, it acts more like a build orchestrator and runs only out-of-date projects in the correct order.

## Compatible with Nx caching and distributed task execution 🏎️

TSC has powerful capabilities for incremental builds. Nx has powerful capabilities for caching and task distribution. These features compose very nicely. First Nx will retreive whatever it can from its local and remote caches (which includes `.tsbuildinfo` files), and then TSC will compile the remaining libs using the cached `.tsbuildinfo` files. This results in the minimum amount of computation.

Note even though the batch implementation can compile hundreds of libraries in the same process, each compiled library will be cached separately by Nx, which greatly increase computation reuse and the percentage of cache hits.

## Performance and DX balance

In large monorepos, it can be challenging to maintain Project references required for TSC incremental builds. Developers need to manually keep those references up to date, which is error-prone and can lead to broken builds.

The `@nx/js:tsc` batch implementation addresses this by creating the required project references on the fly using the project graph information. Nx already knows how your projects relate, so no need to tell it again. This eliminates the need for developers to manually maintain the project references while still getting the performance benefits of incremental builds. Zero DX cost, huge perf benefits.

## See also

- [Enable Typescript Batch Mode](/docs/technologies/typescript/guides/enable-tsc-batch-mode)

---
<!-- source: https://nx.dev/docs/reference/conformance.md -->
## Conformance

{% index_page_cards path="reference/conformance" /%}

---
<!-- source: https://nx.dev/docs/reference/conformance/create-conformance-rule.md -->
## Create a Conformance Rule

For local conformance rules, the resolution utilities from `@nx/js` are used in the same way they are for all other JavaScript/TypeScript files in Nx. Therefore, you can simply reference an adhoc JavaScript file or TypeScript file in your `"rule"` property (as long as the path is resolvable based on your package manager and/or tsconfig setup), and the rule will be loaded/transpiled as needed. The rule implementation file should also have a `schema.json` file next to it that defines the available rule options, if any.

In practice, writing your local conformance rules in an Nx generated library is the easiest way to organize them and ensure that they are easily resolvable via TypeScript. The library in question could also be an Nx plugin, but it does not have to be.

## Generate a conformance rule

To write your own conformance rule, run the `@nx/conformance:create-rule` generator and answer the prompts.

```text {% title="nx g @nx/conformance:create-rule" frame="terminal" %}
 NX  Generating @nx/conformance:create-rule

✔ What is the name of the rule? · local-conformance-rule-example
✔ Which directory do you want to create the rule directory in? · packages/my-plugin/local-conformance-rule
✔ What category does this rule belong to? · security
✔ What is the description of the rule? · an example of a conformance rule
CREATE packages/my-plugin/local-conformance-rule/local-conformance-rule-example/index.ts
CREATE packages/my-plugin/local-conformance-rule/local-conformance-rule-example/schema.json
```

The generated rule definition file should look like this:

```ts
// packages/my-plugin/local-conformance-rule/index.ts
import { createConformanceRule, ConformanceViolation } from '@nx/conformance';

export default createConformanceRule({
  name: 'local-conformance-rule-example',
  category: 'security',
  description: 'an example of a conformance rule',
  implementation: async (context) => {
    const violations: ConformanceViolation[] = [];

    return {
      severity: 'low',
      details: {
        violations,
      },
    };
  },
});
```

To enable the rule, you need to register it in the `nx.json` file.

```json
// nx.json
{
  "conformance": {
    "rules": [
      {
        "rule": "./packages/my-plugin/local-conformance-rule/index.ts"
      }
    ]
  }
}
```

Note that the severity of the error is defined by the rule author and can be adjusted based on the specific violations that are found.

## Understanding rule context

The implementation function of the rule is passed a `context` object which contains:

- **`tree`**: A `ReadOnlyConformanceTree` that can be used to read files from the workspace instead of directly from disk. Useful for unit testing rules as a test tree can be provided to the rule implementation (see [Testing Conformance Rules](/docs/reference/conformance/test-conformance-rule)).
- **`projectGraph`**: The Nx project graph
- **`fileMapCache`**: The Nx file map cache
- **`ruleOptions`**: The resolved rule configuration options based on the current workspace

## Violation interface

Violations must follow this interface:

```typescript
interface ConformanceViolation {
  message: string;
  file?: string; // Used if the violation is attributed to a specific file
  sourceProject?: string; // Used if the violation is attributed to a specific project
  workspaceViolation?: boolean; // Used if the violation is attributed to the entire workspace
}
```

### Automatic project inference

```typescript
violations.push({
  message: 'File violates standards',
  file: 'libs/my-lib/src/problematic.ts', // sourceProject auto-inferred as 'my-lib'
});
```

### Best practices for violations

1. **Use `workspaceViolation: true`** for issues affecting the entire workspace (global configs, workspace structure, etc.)
2. **Use `sourceProject` only** for project-wide issues (missing configuration, structure problems)
3. **Use `file` (and optional explicit `sourceProject`)** for violations tied to specific files in projects
4. **Use `file` only** for files that may not belong to projects (CI configs, root files, etc.)

## Conformance rule examples

The following examples demonstrate how to write rules that report violations at different scopes.

{% tabs %}
{% tabitem label="workspace violation" %}

This rule checks to see if there is a root README.md file in the workspace, and if there is not, it reports on the workspace itself.

```ts
import { workspaceRoot } from '@nx/devkit';
import { createConformanceRule, ConformanceViolation } from '@nx/conformance';
import { join } from 'node:path';
import { existsSync } from 'node:fs';

export default createConformanceRule<object>({
  name: 'readme-file',
  category: 'maintainability',
  description: 'The workspace should have a root README.md file',
  implementation: async () => {
    const violations: ConformanceViolation[] = [];

    const readmePath = join(workspaceRoot, 'README.md');
    if (!existsSync(readmePath)) {
      violations.push({
        message: 'The workspace should have a root README.md file',
        workspaceViolation: true,
      });
    }

    return {
      severity: 'low',
      details: {
        violations,
      },
    };
  },
});
```

{% /tabitem %}
{% tabitem label="project violation" %}

The `@nx/conformance:ensure-owners` rule provides us an example of how to write a rule that reports on a project being in violation of the rule. The `@nx/owners` plugin adds an `owners` metadata property to every project node that has an owner in the project graph. This rule checks each project node metadata to make sure that each project has some owner defined.

```ts
import { ProjectGraphProjectNode } from '@nx/devkit';
import { createConformanceRule, ConformanceViolation } from '@nx/conformance';

export default createConformanceRule({
  name: 'ensure-owners',
  category: 'consistency',
  description: 'Ensure that all projects have owners defined via Nx Owners.',
  implementation: async (context) => {
    const violations: ConformanceViolation[] = [];

    for (const node of Object.values(
      context.projectGraph.nodes
    ) as ProjectGraphProjectNode[]) {
      const metadata = node.data.metadata;
      if (!metadata?.owners || Object.keys(metadata.owners).length === 0) {
        violations.push({
          sourceProject: node.name,
          message: `This project currently has no owners defined via Nx Owners.`,
        });
      }
    }

    return {
      severity: 'medium',
      details: {
        violations,
      },
    };
  },
});
```

{% /tabitem %}
{% tabitem label="file violation" %}

This rule uses TypeScript AST processing to ensure that `index.ts` files use a client-side style of export syntax and `server.ts` files use a server-side style of export syntax.

```ts
import { createConformanceRule, ConformanceViolation } from '@nx/conformance';
import { existsSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
import {
  createSourceFile,
  isExportDeclaration,
  isStringLiteral,
  isToken,
  ScriptKind,
  ScriptTarget,
} from 'typescript';

export default createConformanceRule({
  name: 'server-client-public-api',
  category: 'consistency',
  description: 'Ensure server-only and client-only public APIs are not mixed',
  implementation: async ({ projectGraph }) => {
    const violations: ConformanceViolation[] = [];

    for (const nodeId in projectGraph.nodes) {
      const node = projectGraph.nodes[nodeId];

      const sourceRoot = node.data.root;

      const indexPath = join(sourceRoot, 'src/index.ts');
      const serverPath = join(sourceRoot, 'src/server.ts');

      if (existsSync(indexPath)) {
        const fileContent = readFileSync(indexPath, 'utf8');
        violations.push(
          ...processEntryPoint(fileContent, indexPath, nodeId, 'client')
        );
      }

      if (existsSync(serverPath)) {
        const fileContent = readFileSync(serverPath, 'utf8');
        violations.push(
          ...processEntryPoint(fileContent, serverPath, nodeId, 'server')
        );
      }
    }

    return {
      severity: 'medium',
      details: { violations },
    };
  },
});

export function processEntryPoint(
  fileContent: string,
  entryPoint: string,
  project: string,
  style: 'server' | 'client'
) {
  const violations: ConformanceViolation[] = [];

  const sf = createSourceFile(
    entryPoint,
    fileContent,
    ScriptTarget.Latest,
    true,
    ScriptKind.TS
  );

  let hasNotOnlyExports = false;
  sf.forEachChild((node) => {
    if (isExportDeclaration(node)) {
      const moduleSpecifier =
        node.moduleSpecifier && isStringLiteral(node.moduleSpecifier)
          ? node.moduleSpecifier.getText()
          : '';

      if (isModuleSpecifierViolated(moduleSpecifier, style)) {
        if (
          violations.find(
            (v) => v.file === entryPoint && v.sourceProject === project
          )
        ) {
          // we already have a violation for this file and project, so we don't need to add another one
          return;
        }

        violations.push({
          message:
            style === 'client'
              ? 'Client-side only entry point cannot export from server-side modules'
              : 'Server-side only entry point can only export server-side modules ',
          file: entryPoint,
          sourceProject: project,
        });
      }
    } else if (isToken(node) && node === sf.endOfFileToken) {
      // do nothing
    } else {
      hasNotOnlyExports = true;
    }
  });

  if (hasNotOnlyExports) {
    violations.push({
      message: `Entry point should only contain exported APIs`,
      file: entryPoint,
      sourceProject: project,
    });
  }

  return violations;
}

function isModuleSpecifierViolated(
  moduleSpecifier: string,
  style: 'server' | 'client'
) {
  // should not get here. if this is the case, it's a grammar error in the source code.
  if (!moduleSpecifier) return false;

  if (style === 'server' && !moduleSpecifier.includes('.server')) {
    return true;
  }

  if (style === 'client' && moduleSpecifier.includes('.server')) {
    return true;
  }

  return false;
}
```

{% /tabitem %}
{% /tabs %}

## Auto-fixing violations with fix generators

Rules can optionally implement a `fixGenerator` function that will be used to automatically fix violations.

### When fix generators run

- **`nx conformance`**: Evaluates rules and applies any available fix generators. Changes are written to disk and rules are evaluated once more to calculate how many violations were fixed.
- **`nx conformance:check`**: Evaluates rules only. Fix generators are not applied (useful for CI).

Fix generators are only ever applied for rules whose final status is not `disabled`.

### Fix generator function signature

Fix generators are essentially standard Nx generators. They receive a `WritableConformanceTree` (an extension of the `FsTree` used in other Nx generators) and a schema containing violations, rule options, and optional extra data exposed by the rule implementation via `result.details.fixGeneratorData`.

```typescript
type ConformanceRuleFixGenerator<RuleOptions> = (
  tree: WritableConformanceTree,
  schema: {
    violations: ConformanceViolation[];
    ruleOptions: RuleOptions;
    fixGeneratorData?: Record<string, unknown>;
  }
) => Promise<void> | void;
```

During rule evaluation (diagnostics phase) the `tree` is read-only. During the fix phase, the `tree` is writable for generators to modify files.

### Passing data from rules to fix generators

There are two supported ways to pass data from your rule implementation to its fix generator:

1. **Per-violation data**: The exact `details.violations` array returned by your rule is provided to the fix generator. Each violation can provide `fixGeneratorData` for targeted fixes.

   ```typescript
   violations.push({
     message: 'Missing license header',
     file: 'libs/my-lib/src/index.ts',
     fixGeneratorData: { header: '/* LICENSE */\n', missing: true },
   });
   ```

   Note: Before final results are reported, any `fixGeneratorData` fields are stripped out.

2. **Global data**: Put shared data on `details.fixGeneratorData`. If present, it will be passed as `schema.fixGeneratorData` to the fix generator and then stripped from the final report.

   ```typescript
   return {
     severity: 'low',
     details: {
       violations,
       fixGeneratorData: { dryRun: ruleOptions.addHeader === false },
     },
   };
   ```

   Useful for expensive precomputed lookups or workspace-wide context that applies to all violations.

### Additional notes

- **Project filtering**: If the rule is configured with `projects`, the runner filters the violations accordingly before calling the fix generator. The generator receives only the filtered set.
- **File-to-project inference**: If a violation specifies `file` but not `sourceProject`, the runner attempts to infer the owning project and will include that on the violation provided to the fix generator where possible.
- **Data privacy**: Both `details.fixGeneratorData` and per-violation `fixGeneratorData` are never included in the emitted report. They are only available to the fix generator.

### Example conformance rule with fix generator

```typescript
import { createConformanceRule } from '@nx/conformance';
import type { ConformanceViolation } from '@nx/conformance';

type RuleOptions = {
  addHeader: boolean;
};

export default createConformanceRule<RuleOptions>({
  name: 'license-header',
  category: 'maintainability',
  description: 'Ensure files contain a license header',
  implementation: async ({ tree, ruleOptions }) => {
    const violations: ConformanceViolation[] = [];

    for (const filePath of tree.children('libs/my-lib/src')) {
      if (!filePath.endsWith('.ts')) continue;
      const contents = tree.read(filePath, 'utf-8') ?? '';
      if (!contents.startsWith('/* LICENSE */')) {
        violations.push({
          message: 'Missing license header',
          file: `libs/my-lib/src/${filePath}`,
          fixGeneratorData: { header: '/* LICENSE */\n', missing: true },
        });
      }
    }

    return {
      severity: 'low',
      details: {
        violations,
        fixGeneratorData: { dryRun: ruleOptions.addHeader === false },
      },
    };
  },
  fixGenerator: async (tree, { violations, ruleOptions, fixGeneratorData }) => {
    if (fixGeneratorData?.dryRun) return;

    for (const v of violations) {
      if (!('file' in v) || !v.file) continue;
      const header = (v as any).fixGeneratorData?.header ?? '/* LICENSE */\n';
      const existing = tree.read(v.file, 'utf-8') ?? '';
      if (!existing.startsWith(header) && ruleOptions.addHeader !== false) {
        tree.write(v.file, header + existing);
      }
    }
  },
});
```

### Best practices for fix generators

- **Idempotent**: Generators should be safe to run multiple times without changing files after the first successful run.
- **Minimal changes**: Modify only what is necessary to address the reported violations.
- **Respect options**: Honor `ruleOptions` so users can tune behavior.
- **Avoid re-discovery**: Prefer using the provided `violations` and optional `fixGeneratorData` rather than rescanning the workspace.
- **Clear boundaries**: Keep heavy computation inside the rule implementation and pass the results via `fixGeneratorData` to the generator.

## Share conformance rules across workspaces

If you have an Enterprise Nx Cloud contract, you can share your conformance rules across every repository in your organization. Read more in these articles:

- [Publish Conformance Rules to Nx Cloud](/docs/enterprise/publish-conformance-rules-to-nx-cloud)
- [Configure Conformance Rules in Nx Cloud](/docs/enterprise/configure-conformance-rules-in-nx-cloud)

---
<!-- source: https://nx.dev/docs/reference/conformance/executors.md -->
## @nx/conformance - Executors

## `bundle-rules`

Compile and bundle one or more Nx Conformance Rules

### Options

| Options                     | Type   | Description                                                                                  | Default                         |
| --------------------------- | ------ | -------------------------------------------------------------------------------------------- | ------------------------------- |
| `outputPath` **[required]** | string | The output path for the bundled rules to be written to.                                      |                                 |
| `rulesDirectory`            | string | The directory, relative to the workspace root, containing the rule subdirectories to bundle. | Defaults to `{projectRoot}/src` |

---
<!-- source: https://nx.dev/docs/reference/conformance/generators.md -->
## @nx/conformance - Generators

## `create-rule`

Create a new conformance rule

**Usage:**

```shell
nx g @nx/conformance:create-rule [options]

```

| Options       | Type                                                                          | Description                                      | Default                   |
| ------------- | ----------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------- |
| `category`    | `consistency`, `maintainability`, `reliability`, or `security` **[required]** | The category of the rule                         |                           |
| `directory`   | string **[required]**                                                         | A directory where the rule directory is created. | `{projectRoot}/src/rules` |
| `name`        | string **[required]**                                                         | The name of the rule.                            |                           |
| `description` | string                                                                        | The description of the rule.                     |                           |

## `preset`

Generate a Nx workspace with a working conformance rule

**Usage:**

```shell
npx create-nx-workspace@latest --preset=@nx/conformance
```

---
<!-- source: https://nx.dev/docs/reference/conformance/overview.md -->
## Overview of the Nx Conformance Plugin

The `@nx/conformance` plugin allows [Nx Enterprise](https://nx.dev/enterprise) users to write and apply rules for your entire workspace that help with **consistency**, **maintainability**, **reliability** and **security**.

The conformance plugin allows you to encode your own organization's standards so that they can be enforced automatically. Conformance rules can also complement linting tools by enforcing that those tools are configured in the recommended way. The rules are written in TypeScript but can be applied to any language in the codebase or focus entirely on configuration files.

The plugin also provides the following pre-written rules:

- [**Enforce Project Boundaries**](#enforce-project-boundaries): Similar to the Nx [ESLint Enforce Module Boundaries rule](/docs/features/enforce-module-boundaries), but enforces the boundaries on every project dependency, not just those created from TypeScript imports or `package.json` dependencies.
- [**Ensure Owners**](#ensure-owners): Require every project to have an owner defined for the [`@nx/owners` plugin](/docs/reference/owners)

{% aside type="note" title="This plugin requires an active Nx Enterprise license" %}
In order to use `@nx/conformance`, you need to have an active [Nx Enterprise license](https://nx.dev/enterprise). If you don't have a license or it has expired, the `nx conformance` command will fail.
{% /aside %}

## Set up @nx/conformance

1. [Activate your license](/docs/enterprise/activate-license) if you haven't already
2. Install the package

   ```shell
   nx add @nx/conformance
   ```

3. Configure Conformance Rules

   Configure the `@nx/conformance` plugin in the `nx.json` file or in individual project configuration files. Consult the [Conformance Configuration Reference](#conformance-configuration-reference) section for more details.

4. Run the `nx conformance` or `nx conformance:check` command

The `@nx/conformance` plugin enables two commands:

- **`nx conformance`**: Evaluates rules and applies any available fix generators. Changes are written to disk and rules are evaluated once more to calculate how many violations were fixed. Use this locally while working on feature branches.
- **`nx conformance:check`**: Evaluates rules only. Fix generators are not applied. Use this in CI to enforce conformance rules for every PR.

{% tabs %}
{% tabitem label="Local Development" %}

```shell
npx nx conformance
```

{% /tabitem %}
{% tabitem label="CI without Nx Cloud" %}

```yaml
- name: Enforce all conformance rules
  run: npx nx conformance:check
```

{% /tabitem %}
{% tabitem label="CI with Nx Cloud" %}

```yaml
- name: Enforce all conformance rules
  run: npx nx record -- npx nx conformance:check
```

Use `npx nx record --` to capture the logs for `nx conformance:check` in the Nx Cloud dashboard.

{% /tabitem %}
{% /tabs %}

## Conformance configuration reference

```jsonc
// nx.json
{
  "conformance": {
    "rules": [
      {
        /**
         * Relative path to a local rule implementation or node_module path.
         */
        "rule": "@nx/conformance/enforce-project-boundaries",
        /**
         * Rule specific configuration options. (Optional)
         */
        "options": {},
        /**
         * The projects array allows users to opt in or out of violations for specific projects being reported by the current rule.
         * The array can contain any valid matchers for findMatchingProjects(), by default the implied value is ["*"]. (Optional)
         */
        "projects": ["*"],
      },
    ],
  },
}
```

## Provided conformance rules

The following rules are provided by Nx along with the `@nx/conformance` plugin.

### Enforce project boundaries

This rule is similar to the Nx [ESLint Enforce Module Boundaries rule](/docs/technologies/eslint/eslint-plugin/guides/enforce-module-boundaries), but enforces the boundaries on every project dependency, not just those created from TypeScript imports or `package.json` dependencies.

Set the `rule` property to: `@nx/conformance/enforce-project-boundaries`

```json
// nx.json
{
  "conformance": {
    "rules": [
      {
        "rule": "@nx/conformance/enforce-project-boundaries",
        "options": {
          // Optional
          // Can be a boolean or an object with an array of buildTargetNames
          "requireBuildableDependenciesForBuildableProjects": {
            // Defaults to ["build"]
            "buildTargetNames": ["build", "compile"]
          },
          // Optional
          "ignoredCircularDependencies": [["projectA", "projectB"]],
          // Optional
          "depConstraints": [
            {
              // Must define either `sourceTag` or `allSourceTags`
              "sourceTag": "string",
              "allSourceTags": ["string"],
              // Optional
              "onlyDependOnProjectsWithTags": [],
              // Optional
              "notDependOnProjectsWithTags": []
            }
          ]
        }
      }
    ]
  }
}
```

#### Options

| Property                                         | Type                      | Default | Description                                                                                                                                                                                                                                    |
| ------------------------------------------------ | ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ignoredCircularDependencies                      | _Array<[string, string]>_ | _[]_    | List of project pairs that should be skipped from `Circular dependencies` checks, including the self-circular dependency check. E.g. `['feature-project-a', 'myapp']`. Project name can be replaced by catch all `*` for more generic matches. |
| requireBuildableDependenciesForBuildableProjects | _boolean_                 | _false_ | Enable to restrict the buildable projects from importing non-buildable libraries                                                                                                                                                               |
| depConstraints                                   | _Array<object>_           | _[]_    | List of dependency constraints between projects                                                                                                                                                                                                |

#### Dependency constraints

The `depConstraints` is an array of objects representing the constraints defined between source and target projects. A
constraint must include `sourceTag` or `allSourceTags`. The constraints are applied with **AND** logical operation - for
a given `source` project the resulting constraints would be **all** that match its tags.

| Property                     | Type            | Description                                                                        |
| ---------------------------- | --------------- | ---------------------------------------------------------------------------------- |
| sourceTag                    | _string_        | Tag that source project must contain to match the constraint                       |
| allSourceTags                | _Array<string>_ | List of tags the source project must contain to match the constraint               |
| onlyDependOnProjectsWithTags | _Array<string>_ | The source **can depend only** on projects that contain at least one of these tags |
| notDependOnProjectsWithTags  | _Array<string>_ | The source **can not depend** on projects that contain at least one of these tags  |

### Ensure owners

This rule requires every project to have an owner defined for the [`@nx/owners` plugin](/docs/reference/owners)

Set the `rule` property to: `@nx/conformance/ensure-owners`

```json
// nx.json
{
  "conformance": {
    "rules": [
      {
        "rule": "@nx/conformance/ensure-owners"
      }
    ]
  }
}
```

## Next steps

For more information about the conformance plugin, consult the following articles:

- [Create a Conformance Rule](/docs/reference/conformance/create-conformance-rule)
- [Testing Conformance Rules](/docs/reference/conformance/test-conformance-rule)
- [Publish Conformance Rules to Nx Cloud](/docs/enterprise/publish-conformance-rules-to-nx-cloud)
- [Configure Conformance Rules in Nx Cloud](/docs/enterprise/configure-conformance-rules-in-nx-cloud)

---
<!-- source: https://nx.dev/docs/reference/conformance/test-conformance-rule.md -->
## Test a Conformance Rules

The `@nx/conformance/testing` package provides utilities for testing conformance rules in a controlled environment.

It's recommended for all conformance rule tests to follow the same pattern using `createReadOnlyTree` and `createStubbedProjectGraphAndFileMapCache` when setting up test workspaces:

```typescript
import type { ReadOnlyConformanceTree } from '@nx/conformance';
import {
  applyProjectNodesAndFiles,
  createReadOnlyTree,
  createStubbedProjectGraphAndFileMapCache,
} from '@nx/conformance/testing';
import type { ProjectGraph } from '@nx/devkit';
import type { FileMapCache } from 'nx/src/project-graph/nx-deps-cache';
import { afterEach, beforeEach, describe, expect, it } from 'vitest';

import rule from './index';

describe('my-rule', () => {
  let tree: ReadOnlyConformanceTree;
  let projectGraph: ProjectGraph;
  let fileMapCache: FileMapCache;
  let cleanup: () => void;

  beforeEach(async () => {
    // Create the test workspace in a temporary directory and return a read-only tree and a cleanup function
    ({ tree, cleanup } = await createReadOnlyTree());
    // Prepare a stubbed project graph and file map cache for the test workspace
    ({ projectGraph, fileMapCache } =
      await createStubbedProjectGraphAndFileMapCache(tree, [
        // Optionally add projects and files to the tree, project graph and file map cache if the rule implementation needs them
        // This can also be done later in specific tests using the `applyProjectNodesAndFiles` function
      ]));
  });

  // Invoke the cleanup function to remove the generated temporary directory after each test
  afterEach(() => cleanup());

  it('should return a violation when something specific happens', async () => {
    // Optionally add projects and files to the tree, project graph and file map cache if the rule implementation needs them
    applyProjectNodesAndFiles(tree, projectGraph, fileMapCache, [
      {
        projectNode: {
          name: 'my-lib',
          type: 'lib',
          data: {
            root: 'libs/my-lib',
          },
        },
        projectFiles: [
          // If our specific rule needs to know about project graph dependencies, we add them like so
          // In this example this entry causes my-lib to depend on my-app on the project graph and have it correctly attributed to my-lib in the file map cache
          {
            projectRootRelativeFile: 'src/index.ts',
            depsItCreates: ['my-app'],
          },
        ],
      },
      {
        projectNode: {
          name: 'my-app',
          type: 'app',
          data: {
            root: 'apps/my-app',
          },
        },
      },
    ]);

    const result = await rule.implementation({
      tree,
      projectGraph,
      fileMapCache,
      ruleOptions: {},
    });

    expect(result.details.violations).toMatchInlineSnapshot(`
      // YOUR SNAPSHOT HERE
    `);
  });
});
```

## Adding files to the test workspace

You can optionally provide an async callback to `createReadOnlyTree` to add files or even run Nx generators before the tests run:

```typescript
const { tree, cleanup } = await createReadOnlyTree(async (writableTree) => {
  // Add files to the tree before it becomes read-only
  writableTree.write(
    'libs/my-lib/custom-config.json',
    JSON.stringify({ setting: 'value' })
  );
  // Run some Nx generator
  await libraryGenerator(writableTree, {
    // generator options
  });
});
```

## Testing fix generators

If your rule includes a fix generator, you can test it by converting the read-only tree to a writable one using `convertToWritable` and then running the fix generator:

```typescript
import { convertToWritable, convertToReadOnly } from '@nx/conformance/testing';

it('should fix violations when fix generator is applied', async () => {
  // ... setup and rule implementation test ...

  // Convert to a WritableConformanceTree and run fix generator
  const writableTree = convertToWritable(tree);
  await rule.fixGenerator(writableTree, {
    violations: result.details.violations,
    ruleOptions: {},
  });

  const resultAfterFix = await rule.implementation({
    // Convert back to a ReadOnlyConformanceTree for the rule implementation and verify the fix worked
    tree: convertToReadOnly(writableTree),
    projectGraph,
    fileMapCache,
    ruleOptions: {},
  });

  expect(resultAfterFix.details.violations).toMatchInlineSnapshot(`[]`);
});
```

## Complete example

Here's a complete example testing a rule that checks for license headers and includes a fix generator:

```typescript
import type { ReadOnlyConformanceTree } from '@nx/conformance';
import {
  applyProjectNodesAndFiles,
  createReadOnlyTree,
  createStubbedProjectGraphAndFileMapCache,
  convertToWritable,
  convertToReadOnly,
} from '@nx/conformance/testing';
import type { ProjectGraph } from '@nx/devkit';
import type { FileMapCache } from 'nx/src/project-graph/nx-deps-cache';
import { afterEach, beforeEach, describe, expect, it } from 'vitest';

import rule from './license-header-rule';

describe('license-header-rule', () => {
  let tree: ReadOnlyConformanceTree;
  let projectGraph: ProjectGraph;
  let fileMapCache: FileMapCache;
  let cleanup: () => void;

  beforeEach(async () => {
    ({ tree, cleanup } = await createReadOnlyTree(async (writableTree) => {
      // Create a test file without a license header
      writableTree.write(
        'libs/my-lib/src/index.ts',
        'export const foo = "bar";'
      );
    }));

    ({ projectGraph, fileMapCache } =
      await createStubbedProjectGraphAndFileMapCache(tree, [
        {
          projectNode: {
            name: 'my-lib',
            type: 'lib',
            data: {
              root: 'libs/my-lib',
            },
          },
        },
      ]));
  });

  afterEach(() => cleanup());

  it('should detect missing license header', async () => {
    const result = await rule.implementation({
      tree,
      projectGraph,
      fileMapCache,
      ruleOptions: { addHeader: true },
    });

    expect(result.details.violations).toHaveLength(1);
    expect(result.details.violations[0]).toMatchObject({
      message: 'Missing license header',
      file: 'libs/my-lib/src/index.ts',
    });
  });

  it('should fix missing license header when fix generator is applied', async () => {
    const result = await rule.implementation({
      tree,
      projectGraph,
      fileMapCache,
      ruleOptions: { addHeader: true },
    });

    expect(result.details.violations).toHaveLength(1);

    // Apply the fix
    const writableTree = convertToWritable(tree);
    await rule.fixGenerator(writableTree, {
      violations: result.details.violations,
      ruleOptions: { addHeader: true },
    });

    // Verify the fix worked
    const resultAfterFix = await rule.implementation({
      tree: convertToReadOnly(writableTree),
      projectGraph,
      fileMapCache,
      ruleOptions: { addHeader: true },
    });

    expect(resultAfterFix.details.violations).toHaveLength(0);

    // Verify the file content
    const fixedContent = writableTree.read('libs/my-lib/src/index.ts', 'utf-8');
    expect(fixedContent).toContain('/* LICENSE */');
  });
});
```

## Conformance testing best practices

1. **Use snapshots**: Use `toMatchInlineSnapshot()` for violation arrays to easily see changes in test output.
2. **Test isolation**: Always use cleanup in the `afterEach` (or your testing framework equivalent) to ensure tests don't interfere with each other.
3. **Test both detection and fixes**: If your rule has a fix generator, test both that violations are detected and that the fix works correctly.
4. **Test edge cases**: Test with empty workspaces, missing files, and various project configurations.

### Writing performant conformance rules

Each rule will show its respective execution time and you can use this to identify rules that are slow to run.

#### Avoid blocking the main thread

Sometimes you may notice that a rule that seems to take a while to complete when run as part of the full rule set but is much faster when run individually. This is because another rule is blocking the main thread. Conformance rules are executed in parallel on the main thread so it is important to avoid blocking actions in a particular rule or it will impact the execution of others.

## Available conformance testing utilities

The `@nx/conformance/testing` package exports the following utilities:

### `createReadOnlyTree(callback?)`

Creates a read-only tree with a basic Nx workspace structure. Returns `Promise<{ tree, cleanup }>`.

**Parameters:**

- `callback` (optional): An async function that receives a writable tree before it becomes read-only. Use this to add files or run generators.

**Returns:**

- `tree`: A `ReadOnlyConformanceTree` instance
- `cleanup`: A function to call in `afterEach` to remove the temporary directory

### `createStubbedProjectGraphAndFileMapCache(tree, projectNodesWithFiles)`

Creates a stubbed project graph and file map cache for testing. Returns `Promise<{ projectGraph, fileMapCache }>`.

**Parameters:**

- `tree`: The `ReadOnlyConformanceTree` from `createReadOnlyTree`
- `projectNodesWithFiles`: An array of `ProjectNodesWithFiles` to initialize the graph with (can be empty)

**Returns:**

- `projectGraph`: A stubbed `ProjectGraph` instance
- `fileMapCache`: A stubbed `FileMapCache` instance

### `applyProjectNodesAndFiles(tree, projectGraph, fileMapCache, projectNodesWithFiles)`

Adds projects and files to the test workspace, updating both the tree and the project graph.

**Parameters:**

- `tree`: The `ReadOnlyConformanceTree`
- `projectGraph`: The `ProjectGraph` to update
- `fileMapCache`: The `FileMapCache` to update
- `projectNodesWithFiles`: An array of `ProjectNodesWithFiles` describing projects and their files to add

### `convertToWritable(tree)`

Converts a `ReadOnlyConformanceTree` to a `WritableConformanceTree` for fix generator testing.

**Parameters:**

- `tree`: The `ReadOnlyConformanceTree` to convert

**Returns:** A `WritableConformanceTree` instance

### `convertToReadOnly(tree)`

Converts a `WritableConformanceTree` back to a `ReadOnlyConformanceTree`.

**Parameters:**

- `tree`: The `WritableConformanceTree` to convert

**Returns:** A `ReadOnlyConformanceTree` instance

### `type ProjectNodesWithFiles`

A type that represents the projects and files to be added to the test workspace:

```typescript
type ProjectNodesWithFiles = {
  projectNode: {
    name: string;
    type: string;
    data: {
      root: string;
      // ... other project data
    };
  };
  projectFiles?: Array<{
    projectRootRelativeFile: string;
    depsItCreates?: string[];
  }>;
};
```

---
<!-- source: https://nx.dev/docs/reference/cypress.md -->
## Cypress

{% sidebar_group_cards group="Reference/Cypress" /%}

---
<!-- source: https://nx.dev/docs/reference/deprecated.md -->
## Deprecated

{% index_page_cards path="reference/deprecated" /%}

---
<!-- source: https://nx.dev/docs/reference/deprecated/affected-graph.md -->
## affected:graph - CLI command

**Deprecated:** Use `nx graph --affected`, or `nx affected --graph` instead depending on which best suits your use case.
The `affected:graph` command was removed in Nx 19.

Graph dependencies affected by changes

## Usage

```shell
nx affected:graph
```

Install `nx` globally to invoke the command directly using `nx`, or use `npx nx`, `yarn nx`, or `pnpm nx`.

### Examples

Open the project graph of the workspace in the browser, and highlight the projects affected by changing the index.ts
file:

```shell
 nx affected:graph --files=libs/mylib/src/index.ts
```

Open the project graph of the workspace in the browser, and highlight the projects affected by the changes between main
and HEAD (e.g., PR):

```shell
 nx affected:graph --base=main --head=HEAD
```

Save the project graph of the workspace in a json file, and highlight the projects affected by the changes between main
and HEAD (e.g., PR):

```shell
 nx affected:graph --base=main --head=HEAD --file=output.json
```

Generate a static website with project graph data in an html file, highlighting the projects affected by the changes
between main and HEAD (e.g., PR):

```shell
 nx affected:graph --base=main --head=HEAD --file=output.html
```

Open the project graph of the workspace in the browser, and highlight the projects affected by the last commit on main:

```shell
 nx affected:graph --base=main~1 --head=main
```

Open the project graph of the workspace in the browser, highlight the projects affected, but exclude project-one and
project-two:

```shell
 nx affected:graph --exclude=project-one,project-two
```

## Options

### base

Type: `string`

Base of the current branch (usually main)

### exclude

Type: `string`

Exclude certain projects from being processed

### file

Type: `string`

Output file (e.g. --file=output.json or --file=dep-graph.html)

### files

Type: `string`

Change the way Nx is calculating the affected command by providing directly changed files, list of files delimited by
commas or spaces

### focus

Type: `string`

Use to show the project graph for a particular project and every node that is either an ancestor or a descendant.

### groupByFolder

Type: `boolean`

Group projects by folder in the project graph

### head

Type: `string`

Latest commit of the current branch (usually HEAD)

### help

Type: `boolean`

Show help

### host

Type: `string`

Bind the project graph server to a specific ip address.

### open

Type: `boolean`

Default: `true`

Open the project graph in the browser.

### port

Type: `number`

Bind the project graph server to a specific port.

### targets

Type: `string`

The target to show tasks for in the task graph

### uncommitted

Type: `boolean`

Uncommitted changes

### untracked

Type: `boolean`

Untracked changes

### version

Type: `boolean`

Show version number

### view

Type: `string`

Choices: [projects, tasks]

Default: `projects`

Choose whether to view the projects or task graph

### watch

Type: `boolean`

Default: `true`

Watch for changes to project graph and update in-browser

---
<!-- source: https://nx.dev/docs/reference/deprecated/angular-schematics-builders.md -->
## Angular Schematics and Builders

As of Nx 17, official Nx plugins no longer export [schematics](https://angular.dev/tools/cli/schematics) and [builders](https://angular.dev/tools/cli/cli-builder) that can be directly consumed by the Angular CLI. Since Angular CLI users are not a large portion of Nx user base, it made sense to stop maintaining that code.

Currently, the Angular CLI can only run its own schematics and builders. The Nx CLI is still able to directly run any schematics or builders created for the Angular CLI as well as Nx own generators and executors. The only thing that has changed is that Nx is no longer taking the extra step of converting our own code into a format that the Angular CLI recognizes.

To switch from using the Angular CLI to using the Nx CLI follow the [migrating an Angular CLI project to Nx](/docs/technologies/angular/migration/angular) recipe.

## Interop between Nx generators and Angular schematics

You can wrap any Nx generator with the [convertNxGenerator](/docs/reference/devkit/convertNxGenerator) function and re-export it in your own plugin as a schematic. This is helpful if you still want to support the Angular CLI.

To convert an existing Angular Schematic to an Nx Generator, use the [wrapAngularDevkitSchematic](/docs/reference/devkit/ngcli_adapter/wrapAngularDevkitSchematic) utility function. This is helpful if you want to [programmatically call](/docs/extending-nx/composing-generators) an Angular Schematic inside of a [custom Nx Generator](/docs/extending-nx/local-generators).

## Interop between Nx executors and Angular builders

You can wrap any Nx executor with the [convertNxExecutor](/docs/reference/devkit/convertNxExecutor) function and re-export it in your own plugin as a builder.

There is no existing utility function to convert an Angular Builder to an Nx Executor. If you want to [programmatically call](/docs/extending-nx/compose-executors) an Angular Builder inside of a [custom Nx Executor](/docs/extending-nx/local-executors), you can import the Angular Builder into your Nx Executor's implementation and call it directly.

---
<!-- source: https://nx.dev/docs/reference/deprecated/as-provided-vs-derived.md -->
## As Provided vs. Derived Generator Path Options

Nx is moving toward a more transparent and predictable way of determining where code will be generated when you run a generator. The new behavior is to take generator options _as provided_ and place the generated code in the exact folder that you specify. Nx will only use the new behavior in Nx version 20. The directory can be specified with a `--directory` flag or use a fully specified path (i.e. `libs/shared/my-lib/src/my-component`). The `--directory` flag will be calculated relative to where you run the command.

In the past, Nx had lots of logic to try and _derive_ the best place to put code for you. This approach worked for some people, but there were always people that wanted to generate their code in a slightly different location. Accounting for these variations lead to either (1) people in repos with a different structure not being able to use these generators or (2) Nx introducing lots of flags to allow people to tweak where code was generated (flags like `--project`, `--flat`, `--pascalCaseFiles`, `--pascalCaseDirectory`, `--fileName`). It also caused some confusion when code was not generated in the expected location or frustration when the user did not know how to get Nx to derive the right thing.

Here are some of the issues with the `derived` behavior that are addressed with `as-provided`:

- Some generators had multiple flags for the same thing: `directory`, `path`, etc. Going forward, we only use `--directory` across all generators.
- Generators resolved the directory option inconsistently. Some resolved it relative to the workspace root while others resolved it relative to the project's source root. In the future, all generators will resolve the directory option relative to the current working directory. As such, your terminal's path autocomplete will work as expected and you can also `cd` right into the directory you want.
- Nx transformed the provided names to `kebab-case`. In the future, the name will be taken as provided. This allows for users to deviate from the `kebab-case` directory structure. Nx also included the directory in the project name, which lead to verbose names such as `products-product-detail-page`. Now that Nx takes options as provided, names will be as simple as you would like. You can keep it simple for feature projects (.e.g. `home-page`), or name libraries based on their import path like `@my-org/design-system/buttons`. You can do a mix of both, or deviate from this completely. Note that projects still need to have unique names so you might encounter an error when the name you provide is not valid, but you can resolve the conflict however suits your workspace best.

## Using Nx Console

You can use [Nx Console](/docs/getting-started/editor-setup) for an intuitive experience running generators.

1. If you right-click a folder and choose `Nx generate`, the code generation will be run from that folder.
2. As you fill out the generate form, Nx Console will show you a preview of where the new files will be generated.

## Prompting

To mitigate the impact of this change of direction, Nx will prompt you when running most generators until Nx 20. We know changing these habits may take time so this prompt allows you to choose the previous behavior.

```text {% title="nx g lib my-lib --directory=shared/my-lib" frame="none" %}
✔ Which generator would you like to use? · @nx/node:library

NX  Generating @nx/node:library

? What should be the project name and where should it be generated? …
❯ As provided:
    Name: my-lib
    Root: shared/my-lib
  Derived:
    Name: shared-my-lib-my-lib
    Root: packages/shared/my-lib/my-lib
```

There are two different kinds of generators that will prompt you to choose between `as-provided` and `derived`:

- Project Generators (applications and libraries)
- Other Code Generators (components and other code)

Your intent is your intent. However, the commands you write and run are based on how you think Nx will act. Nx used to derive the location of your code, but Nx will not in the future. In the future for the reasons stated above, Nx will _only_ take options as provided so you should no longer expect Nx to derive the location. We know it will take time to get used to the new way Nx calculates generated code paths and names.

## Project generators

As of Nx 16.8.0, generating a project will prompt you to choose how Nx will calculate where the project should be located. For now, you can choose between `as-provided` and `derived` but `as-provided` will be the only option in Nx 20. The CLI flag to choose between the two algorithms for project generators is `--projectNameAndRootFormat`.

### Generate paths and names `as-provided`

This setting makes app or lib generators behave in the following way:

- `nx g app my-app` creates a new application named `my-app` in the `/my-app` folder
- `nx g lib my-lib` creates a new library named `my-lib` in the `/my-lib` folder
- `cd apps/nested/my-app && nx g app my-app` creates a new application named `my-app` in the `/apps/nested/my-app` folder
- `nx g app my-app --directory=apps/nested/my-app` creates a new application named `my-app` in the `/apps/nested/my-app` folder
- `nx g lib my-lib --directory=libs/shared/ui/my-lib` creates a new library named `my-lib` in the `/libs/shared/ui/my-lib` folder

### Use the old `derived` paths and names

Choosing `derived` makes Nx behave the way it did before version 16.8.0. Nx will check the `workspaceLayout` property in `nx.json` to determine how it should calculate the path to the new project.

```json
{
  "workspaceLayout": {
    "appsDir": "demos",
    "libsDir": "packages"
  }
}
```

These settings would store apps in `/demos/` and libraries in `/packages/`. The paths specified are relative to the
workspace root.

This makes app or lib generators behave in the following way:

- `nx g app my-app` creates a new application named `my-app` in the `/demos/my-app` folder
- `nx g lib my-lib` creates a new library named `my-lib` in the `/packages/my-lib` folder
- `nx g app my-app --directory=nested` creates a new application named `nested-my-app` in the `/demos/nested/my-app` folder
- `nx g lib my-lib --directory=shared/ui` creates a new library named `shared-ui-my-lib` in the `/packages/shared/ui/my-lib` folder

If you accidentally generate a project in the wrong folder, use the [move generator](/docs/reference/workspace/generators#move) to move it to the correct location.

## Code generators

As of Nx 17, code generators such as `component`, `service`, and others will prompt you to choose whether or not Nx will derive the location based on your options or not. In Nx 20, Nx will take the generator options as provided. The following flags are deprecated and will be removed in Nx 20: `--project`, `--flat`, `--pascalCaseFiles`, `--pascalCaseDirectory`, `--fileName`. The CLI flag to choose between the two algorithms for code generators is `--nameAndDirectoryFormat`.

### Generate paths and names `as-provided`

This setting makes generators behave in the following way:

- `nx g component my-component` creates a component in the root.
- `cd apps/nested/my-app && nx g component my-component` creates a new component named `my-component` in the `/apps/nested/my-app` folder
- `nx g component my-component --directory=apps/nested/my-app` creates a new component named `my-component` in the `/apps/nested/my-app` folder
- `nx g component apps/nested/my-app/my-component` creates a new component named `my-component` in the `/apps/nested/my-app` folder

{% callout type="note" title="Must generate inside a project" %}
If the directory specified is not inside a project, an error will be thrown.
{% /callout %}

### Use the old `derived` paths and names

Choosing `derived` makes Nx behave the way it did before version 17. Nx will use the deprecated flags (`--project`, `--flat`, `--pascalCaseFiles`, `--pascalCaseDirectory`, `--fileName`) to calculate where to generate the code. This behavior will not be available in Nx 20.

This makes generators behave in the following way:

- `nx g component my-component` creates a component in the default project.
- `nx g component my-component --project=my-app` creates a new component named `my-component` in the `/apps/nested/my-app` folder
- `nx g component apps/nested/my-app/my-component` creates a new component named `my-component` in the `/apps/nested/my-app` folder

## Writing scripts

If you are using `nx generate` in a script or another environment where it cannot have an interactive prompt, the command will still behave as it did before. You should opt into the new behavior and change the command with a command line flag.

```diff
- nx g lib lib1 --no-interactive`
+ nx g lib lib1 --directory libs/lib1 --projectNameAndRootFormat as-provided --no-interactive
- nx g c button --project lib1 --no-interactive
+ nx g c button --directory libs/lib1/src/lib/button --nameAndDirectoryFormat as-provided --no-interactive
```

---
<!-- source: https://nx.dev/docs/reference/deprecated/cacheable-operations.md -->
## Cacheable Operations

In Nx < 17, the way to define which tasks were cacheable was to add the task name to the `cacheableOperations` array in `nx.json`. This way of defining cacheable tasks required all tasks named `test` to be either cacheable or not cacheable.

In Nx 17, use the `cache` property in `targetDefaults` or individual target definitions in the project level configuration.

---
<!-- source: https://nx.dev/docs/reference/deprecated/custom-tasks-runner.md -->
## Deprecating Custom Tasks Runner

The Custom Task Runners API was created many years ago and has not been supported for several years. It was developed before we introduced a formal method for extending Nx through [plugins](/docs/extending-nx/intro). The API potentially allows modifications to the lifecycle of the Nx command execution, which breaks important invariants that Nx depends on. The new API leverages the plugins API for better performance and functionality.

This page guides you on how to migrate off the now deprecated Custom Task Runner API for both:

- choosing the best remote cache option for your organization
- implementing pre/post processing logic when running tasks

## Remote cache

There are several ways to set up remote caching with Nx.
[Read more about remote cache options](/docs/guides/tasks--caching/self-hosted-caching).

## The preTasksExecution and postTasksExecution hooks

Starting with Nx 20.4, a dedicated plugin-based API has been introduced that allows you to safely hook into the task running lifecycle. This new approach provides pre and post execution hooks without compromising Nx internal operations. For comprehensive documentation on this feature, see [Hook into the Task Running Lifecycle](/docs/extending-nx/task-running-lifecycle).

Let's look into some concrete examples of how you can migrate from the previous custom task runners to this new API.

### Before: custom tasks runner version

Let's imagine that you have implemented a custom task runner as follows:

```typescript
function serializeTasksResults(taskResults: { [taskId: string]: TaskResult }) {
  // ...
}

function validateEnv() {
  // ...
}

export default async function customTasksRunner(tasks, options, context) {
  if (process.env.QA_ENV) {
    process.env.NX_SKIP_NX_CACHE = 'true';
  }
  if (!validateEnv()) {
    throw new Error('Env is not set up correctly');
  }
  const allTaskResults = {};
  const lifeCycle = {
    endTasks(taskResults) {
      taskResults.forEach((tr) => {
        allTaskResults[tr.task.id] = tr;
      });
    },
  };
  const ret = await defaultTasksRunner(
    tasks,
    { ...options, lifeCycle },
    context
  );
  if (options.reportAnalytics) {
    await fetch(process.env.DATACAT_API, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: serializeTasksResults(allTaskResults),
    });
  }
  return ret;
}
```

And let's imagine you configured it in `nx.json` as follows:

```json
{
  "tasksRunnerOptions": {
    "default": {
      "runner": "npm-package-with-custom-tasks-runner",
      "options": {
        "reportAnalytics": true
      }
    }
  }
}
```

### After: Using the New API

The new API includes `preTasksExecution` and `postTasksExecution` hooks that plugins can register. These hooks do not affect task execution and cannot violate any invariants.

The custom task runner above can be implemented as follows:

```typescript
function serializeTasksResults(taskResults: { [taskId: string]: TaskResult }) {
  // task results contain timings and status information useful for gathering analytics
}

function validateEnv() {
  // ...
}

// context contains workspaceRoot and nx.json configuration
export async function preTasksExecution(options: any, context) {
  if (process.env.QA_ENV) {
    process.env.NX_SKIP_NX_CACHE = 'true';
  }
  if (!validateEnv()) {
    throw new Error('Env is not set up correctly');
  }
}

// context contains workspaceRoot, nx.json configuration, and task results
export async function postTasksExecution(options: any, context) {
  if (options.reportAnalytics) {
    await fetch(process.env.DATACAT_API, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: serializeTasksResults(context.taskResults),
    });
  }
}
```

Because it's a regular plugin, it can be configured as follows in `nx.json`:

```json
{
  "plugins": [
    {
      "plugin": "npm-package-with-the-plugin",
      "options": {
        "reportAnalytics": true
      }
    }
  ]
}
```

As with all plugin hooks, the `preTasksExecution` and `postTasksExecution` hooks must be exported so that they load properly when the "npm-package-with-the-plugin" is initialized.

### Multiple tasks runners

You can implement multiple tasks runners using the new hooks.

Imagine you have the following `nx.json`:

```json
{
  "tasksRunnerOptions": {
    "a": {
      "runner": "package-a"
    },
    "b": {
      "runner": "package-b"
    }
  }
}
```

You can replace it with two plugins:

```json
{
  "plugins": [
    {
      "plugin": "package-a"
    },
    {
      "plugin": "package-b"
    }
  ]
}
```

Simply add a condition to your hooks as follows:

```typescript
export async function preTasksExecution() {
  if (process.env.RUNNER != 'a') return;
}

export async function postTasksExecution(options, tasksResults) {
  if (process.env.RUNNER != 'a') return;
}
```

You can then choose which hooks to use by setting the RUNNER env variable.

### Passing options

You can no longer augment options passed to the default tasks runner, so instead you need to set env variables in the `preTasksExecution` hook.

### Composing plugins

Implementing hooks in plugins offers several advantages. It allows multiple plugins to be loaded simultaneously, enabling a clean separation of concerns.

### Keeping state across command invocations

By default, every plugin initiates a long-running process, allowing you to maintain state across command invocations, which can be very useful for advanced analytics.

## Unhandled custom tasks runner use cases?

If you have a use case that the new API doesn't handle, please [open an issue](http://github.com/nrwl/nx).

---
<!-- source: https://nx.dev/docs/reference/deprecated/global-implicit-dependencies.md -->
## Global Implicit Dependencies

Since v14.4, Nx supports [`inputs` and `namedInputs`](/docs/guides/tasks--caching/configure-inputs) for setting up implicit dependencies. As of Nx v16, the `implicitDependencies` defined in `nx.json` are ignored and do not influence the affected graph. This field will be removed in v17. The [`implicitDependencies` in the project configuration](/docs/reference/project-configuration#implicitdependencies) are still the best way to manually set up a dependency between two projects that Nx is not able to detect automatically.

## Projects depending on global files

The old way to have the `myapp` project depend on specific files in the root of the workspace was to use `implicitDependencies`, like this:

```json
{
  "implicitDependencies": {
    "globalConfig.js": ["myapp"],
    "styles/**/*.css": ["myapp"]
  }
}
```

To express the same dependencies with `inputs` and `namedInputs`, modify the default `sharedGlobals` named input:

```json
// nx.json
{
  "namedInputs": {
    "sharedGlobals": [
      "{workspaceRoot}/globalConfig.js",
      "{workspaceRoot}/styles/**/*.css"
    ],
    "default": [
      "sharedGlobals"
      // etc
    ]
  }
}
```

The `sharedGlobals` are included in the `default` named input, so most targets will be set up to depend on them.

For a more detailed explanation, read the [Customizing Inputs and Named Inputs guide](/docs/guides/tasks--caching/configure-inputs)

### Dependencies on sections of the root `package.json` file

You used to be able to set up dependencies on specific packages in the `dependencies` and `devDependencies` sections of the `package.json` file, like this:

```json
{
  "implicitDependencies": {
    "package.json": {
      "dependencies": "*",
      "devDependencies": {
        "mypackage": ["mylib"]
      }
    }
  }
}
```

As of Nx 15, this is inferred automatically by Nx based on the `import` statements in your code. These `implicitDependencies` can be safely deleted.

---
<!-- source: https://nx.dev/docs/reference/deprecated/integrated-vs-package-based.md -->
## Integrated Repos vs. Package-Based Repos vs. Standalone Apps

{% aside type="note" title="" %}
As of Nx 20, it is no longer useful to draw a distinction between integrated and package-based repositories. We've removed references to these terms in the rest of the documentation, but this page is kept here to describe the terms for historical reasons.

Instead of using terms that classify Nx repositories into two different types, we want to highlight the fact that Nx features can be enabled independently of each other. Choose the features that make sense for your repository.
{% /aside %}

There are many different ways to structure a repository and Nx is designed to support them all. To better discuss how Nx can improve a repository, it is helpful to define some terms.

- Standalone Application - A repository with a single application
- Package-Based Repository - A repository with multiple projects that depend on each other via `package.json` and often have nested `node_modules`
- Integrated Repository - A repository with multiple projects that depend on each other via typescript imports and often employ a single version policy

Nx features can be enabled in each of these types of repositories. Just as each repository is unique and may not exactly fit in one of these categories, the way Nx is used will vary between repositories.

{% cardgrid %}
{% linkcard title="Packaged based vs Integrated Style - Use Nx however it works best for you" description="Choose your style and what works best for you!" href="https://youtu.be/ArmERpNvC8Y" /%}
{% linkcard title="Getting Started with Package-Based Repos" description="Walkthrough for creating a package-based monorepo with Nx" href="https://youtu.be/hzTMKuE3CDw" /%}
{% linkcard title="Getting Started with Integrated Repos" description="Walkthrough for creating an integrated monorepo with Nx" href="https://youtu.be/weZ7NAzB7PM" /%}
{% /cardgrid %}

## Package-based repos

A package-based repo is a collection of packages that depend on each other via `package.json` files and nested `node_modules`. With this setup, you typically have [different dependencies for each project](/docs/concepts/decisions/dependency-management). Build tools like Jest and Webpack work as usual, since everything is resolved as if each package was in a separate repo and all of its dependencies were published to npm. Moving an existing package into a package-based repo is very easy since you generally leave that package's existing build tooling untouched. Creating a new package inside the repo is just as difficult as spinning up a new repo since you have to create all the build tooling from scratch.

Lerna, Yarn, Lage, [Turborepo](/docs/guides/adopting-nx/from-turborepo) and Nx support this style.

Someone who appreciates the flexibility of a package-based repository will be most interested in the following features of Nx:

- Add [caching](/docs/features/cache-task-results) and [task orchestration](/docs/features/run-tasks) without modifying tooling or file structure
- Import existing projects into the repo without modifying their tooling
- Easily create new projects or tools with [code generators](/docs/features/generate-code)

{% linkcard title="Learn Nx Tutorial" description="Add Nx to an existing TypeScript repo"  href="/docs/getting-started/tutorials/crafting-your-workspace" /%}

## Integrated repos

An integrated repo contains projects that depend on each other through standard import statements. There is typically a [single version of every dependency](/docs/concepts/decisions/dependency-management) defined at the root. Sometimes build tools like Jest and Webpack need to be wrapped to work correctly. It's harder to add an existing package to this repo style because the build tooling for that package may need to be modified. It's straightforward to add a brand-new project to the repo because all the tooling decisions have already been made.

Bazel and Nx support this style.

Someone who appreciates the structure and consistency of an integrated repository will be most interested in the following features of Nx:

- [Enforce architectural decisions](/docs/features/enforce-module-boundaries) with tagging rules
- Encourage consistency with custom [code generators](/docs/features/generate-code)
- [Automate updating dependencies](/docs/features/automate-updating-dependencies) of the entire toolchain

{% cardgrid %}
{% linkcard title="Learn Nx Tutorial" description="Create a monorepo with Nx" href="/docs/getting-started/tutorials/crafting-your-workspace" /%}
{% /cardgrid %}

## Standalone applications

Nx plugins, especially the [generators](/docs/features/generate-code), [executors](/docs/concepts/executors-and-configurations) and [migrations](/docs/features/automate-updating-dependencies) that come with them, are not only valuable for a monorepo scenario. In fact, many developers use Nx not primarily for its monorepo support, but for its tooling support, particularly its ability to modularize a codebase and, thus, better scale it. Nx supports standalone applications, which are like an integrated monorepo setup, but with just a single, root-level application. Think of it as an advanced, more capable Create-React-App or Angular CLI. And obviously, you can still leverage all the generators and executors and structure your application into libraries or submodules.

Someone whose main focus is on improving their single application will be most interested in the following features of Nx:

- Set up a [fast CI system](/docs/guides/nx-cloud/setup-ci) without CI expertise
- Easily [add new tooling](/docs/plugin-registry)

{% linkcard title="Standalone Applications with Nx" description="Learn what Standlone Apps are and how Nx can be useful" href="https://youtu.be/qEaVzh-oBBc" /%}

## How to choose

Nx itself doesn't care which style you choose. You can use all the features of Nx whether you are in a package based repo or integrated repo. Certain Nx features will be more or less valuable for a standalone app, but all the features of Nx are still available to be put in place as soon as that repo grows to include more apps.

You can be successful working in any style, and there are ways to transition between them. At a high level

- **standalone apps -** for when you want a single project that can be nicely structured and modularized. It's a good starting point if you're not looking into a monorepo but with the option to expand later.
- **package-based repos -** ideally when you already have a monorepo (e.g. yarn/npm/pnpm workspace) and you want Nx primarily for speed and task scheduling. Also, when you want Nx to stay mostly out of your way and you set up everything on your own.
- **integrated repos -** when you want more help from Nx. It takes away the burden of the configuration by coming up with a pre-configured setup that scales well, and provides scaffolding support and automated code migrations. Organizations choose this approach if they are bought into monorepos and want to scale up. Integrated repos might restrict some choices to allow Nx to help you more but result in better maintainability and more value in the long run.

The comparison between package-based repos and integrated repos is similar to that between JSDoc and TypeScript. The former is easier to adopt and provides some good benefits. The latter takes more work but offers more value, especially at a larger scale.

---
<!-- source: https://nx.dev/docs/reference/deprecated/legacy-cache.md -->
## Legacy Cache

In Nx 21, the legacy file system cache will be removed in favor of a new database cache. The new database cache stores metadata in a database, rather than blindly trusting the file system. The database cache has the following benefits:

1. Cache reads and writes are faster.
2. The local cache is more secure since Nx will no longer retrieve artifacts it does not recognize.

The legacy file system cache can still be used in Nx 20 by setting `useLegacyCache: true` in your `nx.json` file. To gain the benefits above, remove `useLegacyCache: true` from your `nx.json`.

If you are currently using a custom task runner or the `NX_REJECT_UNKNOWN_LOCAL_CACHE` environment variable continue reading below.

## tasksRunnerOptions

As of Nx 20, the `tasksRunnerOptions` property in `nx.json` is deprecated. This property was used to register custom task runners. `tasksRunnerOptions` and custom task runners will not work with the new database cache.

If you are using a custom tasks runner to customize your cache, you have the following options:

Use [Nx Cloud](https://nx.dev/nx-cloud) for your remote cache. This is the safest, lowest-maintenance, most recommended option.

If you cannot use Nx Cloud, consider an Nx first party plugin for caching: [Amazon S3](/docs/reference/remote-cache-plugins/s3-cache), [Google Cloud](/docs/reference/remote-cache-plugins/gcs-cache), [Azure](/docs/reference/remote-cache-plugins/azure-cache) or a [shared network drive](/docs/reference/remote-cache-plugins/shared-fs-cache). If there is no plugin that supports the service where you want to store the remote cache, [file an issue](https://github.com/nrwl/nx/issues/new).

**To learn more about migrating from custom task runners, [please refer to this detailed guide](/docs/reference/deprecated/custom-tasks-runner).**

## NX_REJECT_UNKNOWN_LOCAL_CACHE

The `NX_REJECT_UNKNOWN_LOCAL_CACHE` environment variable does not work with the new database cache. We have introduced a new cache which will recognize artifacts from other machines.

If you are using `NX_REJECT_UNKNOWN_LOCAL_CACHE` to share your local cache on a network drive, you have a few options moving forward:

1. Use [Nx Cloud](https://nx.dev/nx-cloud) for your remote cache. This is the safest, lowest-maintenance, most recommended option
2. Use the [Nx Enterprise Shared Fs Cache](/docs/reference/remote-cache-plugins/shared-fs-cache) which recognizes artifacts from other machines
3. Use another [Nx Enterprise](https://nx.dev/enterprise) plugin for caching on a cloud provider: [Amazon S3](/docs/reference/remote-cache-plugins/s3-cache), [Google Cloud](/docs/reference/remote-cache-plugins/gcs-cache), or [Azure](/docs/reference/remote-cache-plugins/azure-cache)

---
<!-- source: https://nx.dev/docs/reference/deprecated/npm-scope.md -->
## NPM Scope

The `npmScope` property of the `nx.json` file is deprecated as of version 16.2.0. `npmScope` was used as a prefix for the names of newly created projects. The new recommended way to define the organization prefix is to set the `name` property in the root `package.json` file to `@my-org/root`. Then `@my-org/` will be used as a prefix for all newly created projects.

In Nx 16, if the `npmScope` property is present, it will be used as a prefix. If the `npmScope` property is not present, the `name` property of the root `package.json` file will be used to infer the prefix.

In Nx 17+, the `npmScope` property is ignored.

---
<!-- source: https://nx.dev/docs/reference/deprecated/print-affected.md -->
## print-affected - CLI command

**Deprecated:** Use `nx show projects --affected`, `nx affected --graph -t build` or `nx graph --affected` depending on
which best suits your use case. The `print-affected` command was removed in Nx 19.

Prints information about the projects and targets affected by changes

## Usage

```shell
nx print-affected
```

Install `nx` globally to invoke the command directly using `nx`, or use `npx nx`, `yarn nx`, or `pnpm nx`.

### Examples

Print information about affected projects and the project graph:

```shell
 nx print-affected
```

Print information about the projects affected by the changes between main and HEAD (e.g,. PR):

```shell
 nx print-affected --base=main --head=HEAD
```

Prints information about the affected projects and a list of tasks to test them:

```shell
 nx print-affected -t test
```

Prints the projects property from the print-affected output:

```shell
 nx print-affected -t build --select=projects
```

Prints the tasks.target.project property from the print-affected output:

```shell
 nx print-affected -t build --select=tasks.target.project
```

## Options

### base

Type: `string`

Base of the current branch (usually main)

### configuration

Type: `string`

This is the configuration to use when performing tasks on projects

### exclude

Type: `string`

Exclude certain projects from being processed

### files

Type: `string`

Change the way Nx is calculating the affected command by providing directly changed files, list of files delimited by
commas or spaces

### head

Type: `string`

Latest commit of the current branch (usually HEAD)

### help

Type: `boolean`

Show help

### select

Type: `string`

Select the subset of the returned json document (e.g., --select=projects)

### targets

Type: `string`

Tasks to run for affected projects

### type

Type: `string`

Choices: [app, lib]

Select the type of projects to be returned (e.g., --type=app)

### uncommitted

Type: `boolean`

Uncommitted changes

### untracked

Type: `boolean`

Untracked changes

### version

Type: `boolean`

Show version number

---
<!-- source: https://nx.dev/docs/reference/deprecated/rescope.md -->
## Rescoping Packages from @nrwl to @nx

As of version 16, all the official Nx plugins moved from the `@nrwl` npm scope to `@nx`. The goal is for anyone looking through a list of dependencies to easily make the connection between the `nx` package and the `@nx` plugins that are associated with it.

As of version 20, the `@nrwl` scoped packages will no longer be published to npm.

## What do you need to do?

For new repos, run `npx create-nx-workspace` as usual. The correct packages will be added.

For existing repos, run `nx migrate` as you normally would. When migrating to version 16 or higher, the package names will be automatically updated for you. If you have a local script, update it to use `@nx/*` packages.

If you maintain a Nx plugin, please update it to use the `@nx/*` packages.

> If you come across Nrwl in blog posts, videos, or elsewhere, that content is likely referring to these packages. Depending on when the content was published, it is likely still relevant.

### Rename

The packages are being renamed as defined in the tables below:

The following packages were not simply rescoped `@nrwl` to `@nx`.

| Nx 15 and lower        | Nx 16 and higher  |
| ---------------------- | ----------------- |
| @nrwl/nx-cloud         | nx-cloud          |
| @nrwl/eslint-plugin-nx | @nx/eslint-plugin |
| @nrwl/nx-plugin        | @nx/plugin        |

| Nx 15 and lower | Nx 16      | Nx 17      |
| --------------- | ---------- | ---------- |
| @nrwl/linter    | @nx/linter | @nx/eslint |

### Rescope only

All other packages keep the same name, but change scope from `@nrwl` to `@nx`.

| Nx 15 and lower    | Nx 16            |
| ------------------ | ---------------- |
| @nrwl/angular      | @nx/angular      |
| @nrwl/aws-lambda   | @nx/aws-lambda   |
| @nrwl/cypress      | @nx/cypress      |
| @nrwl/detox        | @nx/detox        |
| @nrwl/devkit       | @nx/devkit       |
| @nrwl/esbuild      | @nx/esbuild      |
| @nrwl/expo         | @nx/expo         |
| @nrwl/express      | @nx/express      |
| @nrwl/gatsby       | @nx/gatsby       |
| @nrwl/jest         | @nx/jest         |
| @nrwl/js           | @nx/js           |
| @nrwl/nest         | @nx/nest         |
| @nrwl/netlify      | @nx/netlify      |
| @nrwl/next         | @nx/next         |
| @nrwl/node         | @nx/node         |
| @nrwl/react        | @nx/react        |
| @nrwl/react-native | @nx/react-native |
| @nrwl/remix        | @nx/remix        |
| @nrwl/rollup       | @nx/rollup       |
| @nrwl/rspack       | @nx/rspack       |
| @nrwl/storybook    | @nx/storybook    |
| @nrwl/vite         | @nx/vite         |
| @nrwl/web          | @nx/web          |
| @nrwl/webpack      | @nx/webpack      |
| @nrwl/workspace    | @nx/workspace    |

## @nrwl scope end of life

Starting in version 20, the `@nrwl` scoped packages will no longer be published to npm. Only the `@nx` scoped packages will be available on the npm registry.

---
<!-- source: https://nx.dev/docs/reference/deprecated/runtime-cache-inputs.md -->
## Runtime Cache Inputs

The `runtimeCacheInputs` property was used as a way to add extra inputs to the Nx cache, like the version of node on that particular machine.

`runtimeCacheInputs` were set as follows:

```json
{
  "tasksRunnerOptions": {
    "default": {
      "runner": "nx/tasks-runners/default",
      "options": {
        "cacheableOperations": ["build", "lint", "test", "e2e"],
        "runtimeCacheInputs": ["node -v"]
      }
    }
  }
}
```

Instead of specifying the runtime inputs in `tasksRunnerOptions`, in Nx 14.4 you can include them as runtime inputs in the standard [`inputs` and `namedInputs` area of your project configuration](/docs/reference/project-configuration#inputs-and-named-inputs) or [`nx.json`](/docs/reference/nx-json#inputs-namedinputs).

The new style looks like this:

```jsonc
{
  "targets": {
    "build": {
      "inputs": ["^build", { "runtime": "node -v" }],
      // ...
    },
  },
}
```

---
<!-- source: https://nx.dev/docs/reference/deprecated/v1-nx-plugin-api.md -->
## Extending the Project Graph (v1 API)

{% aside type="caution" title="Experimental" %}
This API has been superceded by the [v2 API](/docs/extending-nx/project-graph-plugins) and will be removed in Nx 20. If targeting Nx version 16.7 or higher, please use the v2 API instead.
{% /aside %}

The v1 plugin API for modifying the project graph was split into two parts:

- [Project Inference Plugins](#project-inference-plugins)
- [Project Graph Plugins](#project-graph-plugins)

Project inference plugins are used to infer projects from the file system. Project graph plugins are used to modify the project graph after projects have been identified. In the v2 API, there are still two parts but they are divided differently:

- [createNodes](/docs/extending-nx/project-graph-plugins#adding-new-nodes-to-the-project-graph)
- [createDependencies](/docs/extending-nx/project-graph-plugins#adding-new-dependencies-to-the-project-graph)

These are much clearer in terms of responsibility, and are more flexible. The v1 API is still documented below for reference.

## Adding plugins to workspace

You can register a plugin by adding it to the plugins array in `nx.json`:

```jsonc
// nx.json
{
  ...,
  "plugins": [
    "awesome-plugin"
  ]
}
```

## Project inference plugins

Project inference describes the ability of Nx to discover and work with projects based on source code and configuration files in your repo. Out of the box, Nx identifies projects based on the presence of `package.json` and `project.json` files. It also identifies targets in the `package.json` scripts and the `project.json` `target`s.

Project inference plugins allow you to extend this functionality of Nx to other languages and file structures.

### Project file patterns

Project file patterns are used in two scenarios:

- Inferring projects
- Determining which files should be passed into `registerProjectTargets`.

Let's use the below plugin and workspace layout as an example:

```typescript
// libs/awesome-plugin/index.ts
export const projectFilePatterns = ['project.json', 'my-other-project-file'];
export function registerProjectTargets(projectFilePath) {
  console.log(projectFilePath);
}
```

> workspace layout

```text
my-workspace/
├─ node_modules/
├─ libs/
│  ├─ my-project/
│  │  ├─ my-other-project-file
│  ├─ nx-project/
│  │  ├─ my-other-project-file
│  │  ├─ project.json
├─ nx.json
└─ package.json

```

During initialization, we would expect to see "libs/my-project/my-other-project-file", "libs/nx-project/my-other-project-file", "libs/nx-project/project.json" all logged out to the console. Nx was able to infer `my-project` from the layout.

### Implementing a project target configurator

A project target configurator is a function that takes a path to a project file, and returns the targets inferred from that file.

Plugins should export a function named `registerProjectTargets` that infers the targets from each matching project file. This function receives the path to the project file as its sole parameter.

The `registerProjectTargets` function should return a `Record<string, TargetConfiguration>`, which describes the targets inferred for that specific project file.

```typescript
import { TargetConfiguration } from '@nx/devkit';

export const projectFilePatterns = ['project.json', 'my-other-project-file'];

export function registerProjectTargets(
  projectFilePath: string
): Record<string, TargetConfiguration> {
  return {
    build: {
      /**
       * This object should look exactly like a target
       * configured inside `project.json`
       */
    },
  };
}
```

For guidance on implementing a similar function in the v2 API, see the documentation on [createNodes](/docs/extending-nx/project-graph-plugins#example-extending-projects-adding-inferred-targets).

### Multiple matches

It is possible that the registerProjectTargets function may be called multiple times for one project. This could occur in a few cases, one of which is demonstrated above.

- One plugin may list multiple file patterns, and a project may match more than one of them.
- Multiple plugins may list similar patterns, and pick up the project separately.

**In the first case**, the plugin that you are writing will be called into multiple times. If you return the same target (e.g. `build`) on each call, whichever is ran last would be the target that Nx calls into.

The order that the function would be called is **NOT** guaranteed, so you should try to avoid this when possible. If specifying multiple patterns, they should either be mutually exclusive (e.g. one match per project) or the plugin should conditionally add targets based on the file passed in.

**In the second case**, different plugins may attempt to register the same target on a project. If this occurs, whichever target was registered by the plugin listed latest in `nx.json` would be the one called into by Nx. As an example, assume `plugin-a`, `plugin-b`, and `plugin-c` all match a file and register `build` as a target. If `nx.json` included `"plugins": ["plugin-a", "plugin-b", "plugin-c"]`, running `nx build my-project` would run the target as defined by `"plugin-c"`.

Alternatively, if `nx.json` included `"plugins": ["plugin-c", "plugin-b", "plugin-a"]`, running `nx build my-project` would run the target as defined by `"plugin-a"`.

### Development tips

There is a cache that Nx uses to avoid recalculating the project graph as much as possible, but it may need to be skipped during plugin development. You can set the following environment variable to disable the project graph cache: `NX_CACHE_PROJECT_GRAPH=false`.

It might also be a good idea to ensure that the dep graph is not running on the nx daemon by setting `NX_DAEMON=false`, as this will ensure you will be able to see any `console.log` statements you add as you're developing. You can also leave the daemon active, but `console.log` statements would only appear in its log file.

## Project graph plugins

The Project Graph is the representation of the source code in your repo. Projects can have files associated with them. Projects can have dependencies on each other.

One of the best features of Nx the ability to construct the project graph automatically by analyzing your source code. Currently, this works best within the JavaScript ecosystem, but it can be extended to other languages and technologies using plugins.

### Implementing a project graph processor

A Project Graph Processor takes a project graph and returns a new project graph. It can add/remove nodes and edges.

Plugins should export a function named `processProjectGraph` that handles updating the project graph with new nodes and edges. This function receives two things:

- A `ProjectGraph`
  - `graph.nodes` lists all the projects currently known to Nx.
  - `graph.dependencies` lists the dependencies between projects.

- A `Context`
  - `context.workspace` contains the combined configuration for the workspace.
  - `files` contains all the files found in the workspace.
  - `filesToProcess` contains all the files that have changed since the last invocation and need to be reanalyzed.

The `processProjectGraph` function should return an updated `ProjectGraph`. This is most easily done using `ProjectGraphBuilder`. The builder is there for convenience, so you don't have to use it.

```typescript
import {
  ProjectGraph,
  ProjectGraphBuilder,
  ProjectGraphProcessorContext,
  DependencyType,
} from '@nx/devkit';

export function processProjectGraph(
  graph: ProjectGraph,
  context: ProjectGraphProcessorContext
): ProjectGraph {
  const builder = new ProjectGraphBuilder(graph);
  // We will see how this is used below.
  return builder.getUpdatedProjectGraph();
}
```

### Adding new nodes to the project graph

You can add nodes to the project graph. Since first-party code is added to the graph automatically, this is most commonly used for third-party packages.

A Project Graph Plugin can add them to the project graph. After these packages are added as nodes to the project graph, dependencies can then be drawn from the workspace projects to the third party packages as well as between the third party packages.

```typescript
// Add a new node
builder.addNode({
  name: 'new-project',
  type: 'npm',
  data: {
    files: [],
  },
});
```

{% aside type="note" title="More details" %}
You can designate any type for the node. This differentiates third party projects from projects in the workspace. If you are writing a plugin for a different language, it's common to use IPC to get the list of nodes which you can then add using the builder.
{% /aside %}

### Adding new dependencies to the project graph

It's more common for plugins to create new dependencies. First-party code contained in the workspace is added to the project graph automatically. Whether your project contains TypeScript or say Java, both projects will be created in the same way. However, Nx does not know how to analyze Java sources, and that's what plugins can do.

You can create 2 types of dependencies.

#### Implicit dependencies

An implicit dependency is not associated with any file, and can be created as follows:

```typescript
// Add a new edge
builder.addImplicitDependency('existing-project', 'new-project');
```

{% aside type="note" title="More details" %}
Even though the plugin is written in JavaScript, resolving dependencies of different languages will probably be more easily written in their native language. Therefore, a common approach is to spawn a new process and communicate via IPC or `stdout`.
{% /aside %}

Because an implicit dependency is not associated with any file, Nx doesn't know when it might change, so it will be recomputed every time.

#### Static dependencies

Nx knows what files have changed since the last invocation. Only those files will be present in the provided `filesToProcess`. You can associate a dependency with a particular file (e.g., if that file contains an import).

```typescript
// Add a new edge
builder.addStaticDependency(
  'existing-project',
  'new-project',
  'libs/existing-project/src/index.ts'
);
```

If a file hasn't changed since the last invocation, it doesn't need to be reanalyzed. Nx knows what dependencies are associated with what files, so it will reuse this information for the files that haven't changed.

#### Dynamic dependencies

Dynamic dependencies are a special type of explicit dependencies. In contrast to standard `explicit` dependencies, they are only imported in the runtime under specific conditions.
A typical example would be lazy-loaded routes. Having separation between these two allows us to identify situations where static import breaks the lazy-loading.

```typescript
import { DependencyType } from '@nx/devkit';

// Add a new edge
builder.addDynamicDependency(
  'existing-project',
  'lazy-route',
  'libs/existing-project/src/router-setup.ts'
);
```

### Visualizing the project graph

You can then visualize the project graph as described [here](/docs/features/explore-graph). However, there is a cache that Nx uses to avoid recalculating the project graph as much as possible. As you develop your project graph plugin, it might be a good idea to set the following environment variable to disable the project graph cache: `NX_CACHE_PROJECT_GRAPH=false`.

It might also be a good idea to ensure that the dep graph is not running on the nx daemon by setting `NX_DAEMON=false`, as this will ensure you will be able to see any `console.log` statements you add as you're developing.

### Example project graph plugin

The [nrwl/nx-go-project-graph-plugin](https://github.com/nrwl/nx-go-project-graph-plugin) repo contains an example project graph plugin which adds [Go](https://golang.org/) dependencies to the Nx Project Graph! A similar approach can be used for other languages.

{% github_repository url="https://github.com/nrwl/nx-go-project-graph-plugin" /%}

---
<!-- source: https://nx.dev/docs/reference/deprecated/workspace-executors.md -->
## Workspace Executors

In Nx 13.10+, local nx plugins can contain executors that are used in the workspace. When creating a custom executor for your workspace, look into the [local executor guide](/docs/extending-nx/local-executors) to simplify the build process.

## Converting workspace executors to local executors

- If you don't already have a local plugin, use Nx to generate one:

```shell
npm add -D @nx/plugin
nx g @nx/plugin:plugin tools/my-plugin
```

- Use the Nx CLI to generate the initial files needed for your executor. Replace `my-executor` with the name of your workspace executor.

```shell
nx generate @nx/plugin:executor tools/my-plugin/src/executors/my-executor
```

- Copy the code for your workspace executor into the newly created executor's folder. e.g. `libs/my-plugin/src/executors/my-executor/`

- Now you can reference the executor like this:

```jsonc
{
  "executor": "@my-org/my-plugin:my-executor",
}
```

---
<!-- source: https://nx.dev/docs/reference/deprecated/workspace-generators.md -->
## Workspace Generators

In Nx 13.10, we introduced the ability to run generators from Nx plugins in the workspace they were created in.

By using a "local" plugin, you can set the plugin as your workspace's default collection and get several other affordances that are not provided to workspace generators. This is the preferred method for "workspace generators", and existing generators will eventually be transitioned to use a local plugin.

Check the [local generator guide](/docs/extending-nx/local-generators) for information on creating a new plugin.

## Converting workspace generators to local generators

{% aside type="note" %}
When migrating to Nx 16, a new workspace plugin is automatically generated in the tools folder if you already have workspace-generators.
{% /aside %}

- If you don't already have a local plugin, use Nx to generate one:

```shell
npm add -D @nx/plugin
nx g @nx/plugin:plugin tools/my-plugin
```

- Use the Nx CLI to generate the initial files needed for your generator. Replace `my-generator` with the name of your workspace generator.

```shell
nx generate @nx/plugin:generator tools/my-plugin/src/generators/my-generator
```

- Copy the code for your workspace generator into the newly created generator's folder. e.g. `libs/my-plugin/src/generators/my-generator/`

- Now you can run the generator like this:

```shell
nx g my-generator
```

---
<!-- source: https://nx.dev/docs/reference/deprecated/workspace-json.md -->
## workspace.json

Nx used to have a `workspace.json` file at the root of the repo that at various points performed these functions:

1. Identified the locations of all project in the repo
2. Contained the target configuration for all projects

Identifying the locations of projects is now done automatically through project inference. You can even customize how projects are inferred with a [project inference plugin](/docs/extending-nx/project-graph-plugins).

The target configuration for each project is now stored in individual `project.json` files or `package.json` files.

## Removing workspace.json

To remove `workspace.json` in favor of `project.json` files, run:

```shell
nx g @nx/workspace:fix-configuration
```

See [fix-configuration](/docs/reference/workspace/generators#fix-configuration) for more options.

After this command, `workspace.json` should look like this:

```jsonc
{
  "version": 2,
  "projects": {
    "my-app": "apps/my-app",
    "some-lib": "libs/some-lib",
    // ...
  },
  "$schema": "./node_modules/nx/schemas/workspace-schema.json",
}
```

If every project is listed as a string, instead of an object with project configuration properties, then it is safe to delete the `workspace.json` file.

---
<!-- source: https://nx.dev/docs/reference/detox.md -->
## Detox

{% sidebar_group_cards group="Reference/Detox" /%}

---
<!-- source: https://nx.dev/docs/reference/dotnet.md -->
## .NET

{% sidebar_group_cards group="Reference/.NET" /%}

---
<!-- source: https://nx.dev/docs/reference/environment-variables.md -->
## Environment Variables

## Nx environment variables

The following environment variables are ones that you can set to change the behavior of Nx in different environments.

| Property                           | Type           | Description                                                                                                                                                                                                                         |
| ---------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NX_ADD_PLUGINS`                   | boolean        | If set to `false`, Nx will not add plugins to infer tasks. This is `true` by default.                                                                                                                                               |
| `NX_BASE`                          | string         | The default base branch to use when calculating the affected projects. Can be overridden on the command line with `--base`.                                                                                                         |
| `NX_CACHE_DIRECTORY`               | string         | The cache for task outputs is stored in `.nx/cache` by default. Set this variable to use a different directory.                                                                                                                     |
| `NX_CACHE_PROJECT_GRAPH`           | boolean        | If set to `false`, disables the project graph cache. Most useful when developing a plugin that modifies the project graph.                                                                                                          |
| `NX_DAEMON`                        | boolean        | If set to `false`, disables the Nx daemon process. Disable the daemon to print `console.log` statements in plugin code you are developing.                                                                                          |
| `NX_DEFAULT_PROJECT`               | string         | The default project used for commands which require a project. e.g. `nx build`, `nx g component`, etc.                                                                                                                              |
| `NX_DEFAULT_OUTPUT_STYLE`          | string         | The default output style to use when running tasks. Can be overridden on the command line with `--outputStyle`.                                                                                                                     |
| `NX_HEAD`                          | string         | The default head branch to use when calculating the affected projects. Can be overridden on the command line with `--head`.                                                                                                         |
| `NX_PERF_LOGGING`                  | boolean        | If set to `true`, will print debug information useful for profiling executors and Nx itself                                                                                                                                         |
| `NX_PROFILE`                       | string         | Prepend `NX_PROFILE=profile.json` before running targets with Nx to generate a file that be [loaded in Chrome dev tools](/docs/troubleshooting/performance-profiling) to visualize the performance of Nx across multiple processes. |
| `NX_WORKSPACE_DATA_DIRECTORY`      | string         | The project graph cache and some other internal nx caches are stored in `.nx/workspace-data` by default. Set this variable to use a different directory.                                                                            |
| `NX_PARALLEL`                      | number         | The number of tasks Nx should run in parallel. Overrides any configured value inside nx.json                                                                                                                                        |
| `NX_RUNNER`                        | string         | The name of task runner from the config to use. Can be overridden on the command line with `--runner`. Not read if `NX_TASKS_RUNNER` is set.                                                                                        |
| `NX_SKIP_FORMAT`                   | boolean        | If set to `true`, skips Prettier formatting in generators and migrations. Useful for repositories that use alternative formatters like Biome, dprint, or have custom formatting requirements.                                       |
| `NX_SKIP_NX_CACHE`                 | boolean        | Rerun the tasks even when the results are available in the cache.                                                                                                                                                                   |
| `NX_DISABLE_NX_CACHE`              | boolean        | Rerun the tasks even when the results are available in the cache.                                                                                                                                                                   |
| `NX_SKIP_REMOTE_CACHE`             | boolean        | Disable all remote caching features. This means that the remote cache will not be read from or written to. Includes Nx Cloud and self-hosted caches.                                                                                |
| `NX_DISABLE_REMOTE_CACHE`          | boolean        | Disable all remote caching features. This means that the remote cache will not be read from or written to. Includes Nx Cloud and self-hosted caches.                                                                                |
| `NX_TASKS_RUNNER`                  | string         | The name of task runner from the config to use. Can be overridden on the command line with `--runner`. Preferred over `NX_RUNNER`.                                                                                                  |
| `NX_TASKS_RUNNER_DYNAMIC_OUTPUT`   | boolean        | If set to `false`, will use non-dynamic terminal output strategy (what you see in CI), even when you terminal can support the dynamic version                                                                                       |
| `NX_TUI`                           | boolean        | If set to `true` or `false`, will enable or disable the Terminal UI (TUI) for running tasks. TUI provides an interactive visual interface for task execution                                                                        |
| `NX_TUI_AUTO_EXIT`                 | boolean/number | Controls whether the TUI automatically exits after tasks finish. If `true`, exits immediately. If `false`, never exits automatically. If a number, shows a countdown for that many seconds before exiting                           |
| `NX_USE_LOCAL`                     | boolean        | If set to `true`, Nx will use the locally installed version instead of downloading the latest version from npm for commands like `nx init` and `nx migrate`.                                                                        |
| `NX_VERBOSE_LOGGING`               | boolean        | If set to `true`, will print debug information useful for troubleshooting                                                                                                                                                           |
| `NX_DRY_RUN`                       | boolean        | If set to `true`, will perform a dry run of the generator. No files will be created and no packages will be installed.                                                                                                              |
| `NX_INTERACTIVE`                   | boolean        | If set to `true`, will allow Nx to prompt you in the terminal to answer some further questions when running generators.                                                                                                             |
| `NX_GENERATE_QUIET`                | boolean        | If set to `true`, will prevent Nx logging file operations during generate                                                                                                                                                           |
| `NX_PREFER_TS_NODE`                | boolean        | If set to `true`, Nx will use `ts-node` for local execution of plugins even if `@swc-node/register` is installed.                                                                                                                   |
| `NX_PREFER_NODE_STRIP_TYPES`       | boolean        | If set to `true` and running on Node.js 22.6+, Nx will use Node.js native TypeScript type stripping instead of `@swc-node/register` or `ts-node` when loading TypeScript configuration files. This improves performance.            |
| `NX_IGNORE_CYCLES`                 | boolean        | If set to `true`, Nx will ignore errors created by a task graph circular dependency. Can be overridden on the command line with `--nxIgnoreCycles`                                                                                  |
| `NX_BATCH_MODE`                    | boolean        | If set to `true`, Nx will run task(s) in batches for executors which support batches.                                                                                                                                               |
| `NX_SKIP_LOG_GROUPING`             | boolean        | If set to `true`, Nx will not group command's logs on CI.                                                                                                                                                                           |
| `NX_MIGRATE_CLI_VERSION`           | string         | The version of Nx to use for running the `nx migrate` command. If not set, it defaults to `latest`.                                                                                                                                 |
| `NX_MIGRATE_SKIP_INSTALL`          | boolean        | If set to `true`, `nx migrate --run-migrations` will not automatically perform the installation of the packages.                                                                                                                    |
| `NX_MIGRATE_SKIP_REGISTRY_FETCH`   | boolean        | If set to `true`, will skip fetching metadata from the registry and instead use the installation method directly.                                                                                                                   |
| `NX_MIGRATE_USE_LOCAL`             | boolean        | If set to `true`, will use the locally installed version of `nx` instead of downloading the latest version to run the `nx migrate` command.                                                                                         |
| `NX_LOAD_DOT_ENV_FILES`            | boolean        | If set to 'false', Nx will not load any environment files (e.g. `.local.env`, `.env.local`)                                                                                                                                         |
| `NX_MAX_CACHE_SIZE`                | string         | Alternative to configuring `maxCacheSize` in `nx.json`. Defines the maximum size of the local task cache. See [`maxCacheSize`](/docs/reference/nx-json#max-cache-size) for supported units and behavior details.                    |
| `NX_NATIVE_FILE_CACHE_DIRECTORY`   | string         | The cache for native `.node` files is stored under a global temp directory by default. Set this variable to use a different directory. This is interpreted as an absolute path.                                                     |
| `NX_PLUGIN_NO_TIMEOUTS`            | boolean        | If set to `true`, plugin operations will not timeout                                                                                                                                                                                |
| `NX_FORMAT_SORT_TSCONFIG_PATHS`    | boolean        | If set to `true`, generators will sort the TypeScript path mappings in the root tsconfig file.                                                                                                                                      |
| `NX_SKIP_VSCODE_EXTENSION_INSTALL` | boolean        | If set to `true`, skips the automatic installation of the Nx Console extension for supported editors. Set this in environments where the temp file that we store this information in otherwise isn't accessible.                    |

## Plugin environment variables

The following environment variables can be used to configure specific Nx plugins. This is useful in CI environments where the required tooling (e.g., Java) is not available or where plugin behavior needs to be customized.

| Property                          | Type    | Description                                                                                                                                               |
| --------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NX_DOTNET_DISABLE`               | boolean | If set to `true`, disables the `@nx/dotnet` plugin. Useful in environments where .NET SDK is not available.                                               |
| `NX_GRADLE_DISABLE`               | boolean | If set to `true`, disables the `@nx/gradle` plugin. Useful in environments where Java/Gradle is not available.                                            |
| `NX_GRADLE_PROJECT_GRAPH_TIMEOUT` | number  | Timeout in seconds for Gradle project graph generation. Defaults to `60`. Increase this value for large Gradle workspaces that need more time to resolve. |
| `NX_MAVEN_DISABLE`                | boolean | If set to `true`, disables the `@nx/maven` plugin. Useful in environments where Java/Maven is not available.                                              |

Nx will set the following environment variables so they can be accessible within the process even outside of executors and generators.

| Property                       | Type    | Description                                                                                                                                               |
| ------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NX_TASK_TARGET_PROJECT`       | string  | Set to the project name of the task being run. Use this to tell which project is being run.                                                               |
| `NX_TASK_TARGET_TARGET`        | string  | Set to the target name of the task being run. Use this to tell which target of the project is being run.                                                  |
| `NX_TASK_TARGET_CONFIGURATION` | string  | Set to the configuration name of the task being run. Use this to tell which configuration of the target is being run.                                     |
| `NX_GRAPH_CREATION`            | boolean | Set to `true` during the graph creation process. Use this to have inference plugins run different code during graph creation versus during task execution |
| `NX_DRY_RUN`                   | boolean | Set to `true` during dry runs of generators. Use this to avoid side effects during generators.                                                            |
| `NX_INTERACTIVE`               | boolean | Set to `false` when running generators with `--interactive=false`. Use this to prevent prompting during generators                                        |

## Nx Cloud environment variables

The following environment variables are specific to Nx Cloud and can be used to configure cloud-specific behavior:

{% aside type="tip" title="Verbose Logging" %}
Similar to the Nx CLI, Nx Cloud also uses the `NX_VERBOSE_LOGGING` environment variable to output debug information
{% /aside %}

| Property                              | Type    | Description                                                                                                                                                                                                            |
| ------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NX_BRANCH`                           | string  | The current branch name. For most CI providers, `nx-cloud` determines this automatically. Must be set to the PR number for GitHub, BitBucket and GitLab integrations to work properly.                                 |
| `NX_CLOUD_DISABLE_METRICS_COLLECTION` | boolean | Disables collection of CPU and memory metrics during task execution (enabled by default for enterprise users on Nx 22.1+). See [Task Resource Usage](/docs/guides/nx-cloud/ci-resource-usage).                         |
| `NX_CLOUD_METRICS_DIRECTORY`          | string  | Directory where Nx writes resource metrics during task execution. See [Task Resource Usage](/docs/guides/nx-cloud/ci-resource-usage).                                                                                  |
| `NX_CI_EXECUTION_ID`                  | string  | A unique identifier for the current CI run or job. For most CI providers, `nx-cloud` determines this automatically. The value on the main job must match the value on all agents.                                      |
| `NX_CI_EXECUTION_ENV`                 | string  | Used when you have multiple main jobs (e.g., running CI on both Linux and Windows). The main job with this env variable will connect to agents with the same env name.                                                 |
| `NX_AGENT_LAUNCH_TEMPLATE`            | string  | Should only be used when running agents with Manual DTE. Attaches a launch template type to your agents to leverage assignment rules for task distribution.                                                            |
| `NX_CLOUD_ACCESS_TOKEN`               | string  | Configure the Nx Cloud access token. Takes precedence over the `accessToken` property in `nx.json`. Common to have a read-only token in `nx.json` and a read-write token set via this environment variable in CI.      |
| `NX_CLOUD_API`                        | string  | The URL of the Nx Cloud instance to connect to. Overrides `nxCloudUrl` in `nx.json`.                                                                                                                                   |
| `NX_CLOUD_ENCRYPTION_KEY`             | string  | Enable end-to-end encryption of artifacts. Artifacts will be encrypted/decrypted on your machine. Can also be set via the `encryptionKey` property in `nx.json`.                                                       |
| `NX_CLOUD_NO_TIMEOUTS`                | boolean | Disables the default 10-second timeout for Nx Cloud requests.                                                                                                                                                          |
| `NX_NO_CLOUD`                         | boolean | If set to `true`, prevents Nx Cloud from being used for the current run. No remote cache will be used. Value cannot be set if using [distributed task execution](/docs/features/ci-features/distribute-task-execution) |
| `NX_VERBOSE_LOGGING`                  | boolean | Outputs debug information about agents communicating with the main job. Useful for debugging cache misses and on-premises setup issues.                                                                                |
| `NX_WORKING_DIRECTORY`                | string  | The subdirectory containing your Nx workspace. Set this in your launch template if your Nx workspace is not at the repository root. Only used by Nx Agents.                                                            |

### Deprecated Nx Cloud environment variables

| Property                                                | Type    | Description                                                                                                                            |
| ------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `NX_RUN_GROUP`                                          | string  | Older versions of `nx-cloud` used this instead of `NX_CI_EXECUTION_ID` and `NX_CI_EXECUTION_ENV`. Served the same purpose.             |
| `NX_CLOUD_DISTRIBUTED_EXECUTION_STOP_AGENTS_ON_FAILURE` | boolean | When set to `true`, tells Nx Cloud to stop agents if a command fails. Use `npx nx start-ci-run --stop-agents-on-failure=true` instead. |
| `NX_CLOUD_DISTRIBUTED_EXECUTION`                        | boolean | When set to `false`, disables distributed task execution. Use `--no-dte` or `--no-agents` flags instead.                               |

---
<!-- source: https://nx.dev/docs/reference/esbuild.md -->
## ESBuild

{% sidebar_group_cards group="Reference/ESBuild" /%}

---
<!-- source: https://nx.dev/docs/reference/eslint.md -->
## ESLint

{% sidebar_group_cards group="Reference/ESLint" /%}

---
<!-- source: https://nx.dev/docs/reference/glossary.md -->
## Nx Glossary

This is a short list of Nx-specific terms that will help you understand the rest of the documentation.

## Terms

### Application

A [project](#project) that can run on its own. Generally uses [libraries](#library).

### Atomizer

The Atomizer is an Nx Cloud feature that automatically splits tasks so that they can be executed in parallel.

Atomizer automatically splits tasks on [Nx Agents](#nx-agents), providing you detailed task information in the UI, including interpreted logs and artifacts, automatically grouped by project and workflow.

> See: [Automatically Split E2E Tasks](/docs/features/ci-features/split-e2e-tasks)

### Batch mode

A way to run multiple [tasks](#task) in a single process instead of spawning a separate process for each one.
Batch mode reduces per-process startup overhead and lets tools like `tsc` and Gradle share state across tasks.
Enable it by setting `NX_BATCH_MODE=true` or passing `--batch`.
Not all plugin executors support batch mode, check the specific plugin [technology page](/docs/technologies-tools) to see if it's supported.

### Buildable library

A [library](#library) that has a `build` [target](#target). Some libraries can be generated with a `build` target using the `--buildable` flag.

> See: [Publishable and Buildable Nx Libraries](/docs/concepts/buildable-and-publishable-libraries)

### Cache

A mechanism for saving the output of a calculation so it can be replayed later without actually performing the calculation again.

> See: [Cache Task Results](/docs/features/cache-task-results)

### Cache hit

When the [cache inputs](#cache-inputs) for a [task](#task) match an existing entry in the [cache](#cache) and the [cache outputs](#cache-outputs) can be replayed without actually running the task.

> See: [Cache Task Results](/docs/features/cache-task-results)

### Cache inputs

Everything that might change the output of a [task](#task). This may include source code, task options, environment variables and other settings determined at run time. These values are combined as a hash to serve as a key for an entry in the [cache](#cache).

> See: [Customizing Inputs and Named Inputs](/docs/guides/tasks--caching/configure-inputs)

### Cache miss

When the [cache inputs](#cache-inputs) for a [task](#task) do not match an existing entry in the [cache](#cache) and the task needs to be executed.

> See: [Cache Task Results](/docs/features/cache-task-results)

### Cache outputs

The terminal output and any file artifacts created by running a [task](#task). These values are stored in the [cache](#cache) to be replayed later.

> See: [Outputs Reference](/docs/reference/project-configuration#outputs)

### CIPE (Continuous integration pipeline execution)

CI Pipeline Executions are a grouping mechanism for all Nx and Nx Cloud actions
that occur within a single continuous integration pipeline. The Nx Cloud task
runner automatically detects when it is running in a CI environment, so this
grouping is done automatically. In almost all cases, this detection will be a
1:1 match with your CI provider's concept of a "pipeline" or "workflow".

### Command

Anything you run in the terminal. An example command that invokes a [task](#task) is `nx build my-app`.

> See: [Run Tasks](/docs/features/run-tasks)

### Configurations

A set of preconfigured options for a [target](#target) that should be enabled altogether. For example, a `production` configuration would set all the options needed for a build that could be deployed to production.

> See: [Use Task Configurations](/docs/concepts/executors-and-configurations#use-task-configurations)

### Distributed task execution

A system for running [tasks](#task) in CI across multiple agent processes across many machines. [Nx Agents](#nx-agents) enables distributed task execution on agent machines that are managed by Nx.

> See: [Distribute Task Execution](/docs/features/ci-features/distribute-task-execution)

### Executor

A script that performs some action on your code. This can include building, linting, testing, serving and many other actions. A [target](#target) configuration specifies an executor and a set of options. Executors can be found in [plugins](#plugin).

> See: [Executors and Configurations](/docs/concepts/executors-and-configurations)

### Flake rate

A metric that measures how often a task succeeds due to flakiness rather than reliable code. It represents the percentage of total successes that came from unreliable (flaky) task hashes: `flaky_successes / (flaky_successes + non_flaky_successes)`. This answers the question: "Of all the times this task succeeded, how many successes came from unreliable code?"

> See: [Flaky Task Analytics](/docs/features/ci-features/flaky-tasks#flaky-task-analytics)

### Flaky tasks

Tasks that will sometimes succeed and sometimes fail without any change to the inputs. These tasks are often e2e tests and are particularly problematic in CI. Nx Cloud automatically detects flaky tasks and re-runs them.

> See: [Identify and Re-run Flaky Tasks](/docs/features/ci-features/flaky-tasks)

### Generator

A script that creates or modifies your code. Generators can be found in [plugins](#plugin).

> See: [Use Code Generators](/docs/features/generate-code)

### Graph

A computer science concept that consists of nodes connected by edges. In the Nx context, there are two graphs: the [project](#project) graph which describes dependencies between projects and the [task](#task) graph which describes dependencies between tasks.

> See: [Explore the Graph](/docs/features/explore-graph)

### Impact score

A metric used in [Flaky Task Analytics](#flaky-tasks) to prioritize which flaky tasks need attention. Calculated as `flake_rate × sample_size`, it weights frequently-run flaky tasks higher than rarely-run flaky tasks. For example, a task with 50% flake rate and 100 runs has an impact score of 50, the same as a task with 10% flake rate and 500 runs.

> See: [Flaky Task Analytics](/docs/features/ci-features/flaky-tasks#flaky-task-analytics)

### Launch template

Launch Templates are used to set up an agent machine. They specify a resource class, an image and a series of set up steps before tasks are executed on that machine.

> See: [Launch Templates](/docs/reference/nx-cloud/launch-templates)

### Library

A [project](#project) that is used by [applications](#application) or other [libraries](#library).

### Monolith

A large [application](#application) that is difficult to separate into smaller pieces.

### Monorepo

A repository with multiple [projects](#project).

> See: [monorepo.tools](https://monorepo.tools)

### Nested project

A [project](#project) that is located in a sub-folder of another project. This was made possible in Nx 15.3.

### Nx Agents

A paid service that hosts and manages customizable worker machines to run parts of your CI pipeline faster and cheaper than a traditional CI provider. When possible, Nx Agents uses [distributed task execution](#distributed-task-execution) to optimize your pipeline.

> See: [Distribute Task Execution](/docs/features/ci-features/distribute-task-execution)

### Nx Cloud

The umbrella term for all CI-related products that Nx provides.

> See: [CI with Nx](/docs/guides/nx-cloud/setup-ci)

### Nx Replay

Nx Replay is the product offered by [Nx Cloud](#nx-cloud) that enables [remote caching](#remote-cache).

> See: [Use Remote Caching](/docs/features/ci-features/remote-cache)

### Package

A [project](#project). It is sometimes published as an npm package.

### Plugin

A set of [executors](#executor), [generators](#generator) and other code that extends the functionality of Nx. May be installed from a package manager like NPM or developed directly in the repository.

> See: [Create Your Own Plugin](/docs/extending-nx/intro)

### Polyrepo

Related [projects](#project) spread across multiple repositories.

### Project

The unit of code on which a [task](#task) can be run. A project can be an [application](#application) or a [library](#library).

### Publishable library

A [library](#library) that has a `publish` [target](#target). Some libraries can be generated with a `publish` target using the `--publishable` flag.

> See: [Publishable and Buildable Nx Libraries](/docs/concepts/buildable-and-publishable-libraries)

### Remote cache

A [cache](#cache) that can be shared between all developers using the repo and the CI system. This product is called [Nx Replay](#nx-replay).

> See: [Share Your Cache](/docs/features/ci-features/remote-cache)

### Root-level project

A [project](#project) that has its own root folder at the root of the repository. Every other project in the repo is a [nested project](#nested-project).

### Run

Runs in Nx Cloud are Nx commands that result in some number of `Task`s being performed.

- `nx run my-app:build` is a run that performs a single task
- `nx run-many -t test,build` is a run that performs many tasks.
- `nx affected -t test,build` is a run that performs zero to many tasks.

When a run exists in a CI environment, Nx Cloud will automatically associate it
with the appropriate `Run Group` and `CI Pipeline Execution`

### Run group

Run groups are a more specific grouping mechanism for Nx and Nx Cloud actions,
and exist as children within a single CI Pipeline Execution. Typically, run groups
are used when there are different _hardware_ requirements (ex: a Linux run group,
and a MacOS run group) for the different commands.

When using Distributed Task Execution, Nx Agents can only belong to a single
run group. This means each additional run group requires its own pool of agents.

### Standalone repository

A repository with a single [application](#application) at the [root level](#root-level-project). This set up is made possible in Nx 15.3.

### Target

The name of an action taken on a [project](#project).

> See: [Run Tasks](/docs/features/run-tasks)

### Task

An invocation of a [target](#target) on a specific [project](#project).

> See: [Run Tasks](/docs/features/run-tasks)

### Task pipeline

The set of dependencies between [tasks](#task) that ensure that tasks are run in the correct order.

> See: [Task Pipeline Configuration](/docs/concepts/task-pipeline-configuration)

### Workspace

A git repository. An Nx workspace is a git repository using Nx.

---
<!-- source: https://nx.dev/docs/reference/inputs.md -->
## Inputs and Named Inputs

When Nx [computes the hash for a given operation](/docs/concepts/how-caching-works), it takes into account the `inputs` of the target.
The `inputs` are a list of **file sets**, **runtime** inputs, **environment variables**, and **working directory** that affect the output of the target.
If any of the `inputs` change, the cache is invalidated and the target is re-run.

## Types of inputs

Nx can consider the following types of Inputs when computing the hash for a given operation.

### Project configuration

Nx always considers the configuration of the project of a task and its dependencies when calculating the hash of a task.

### Command arguments

Passing different arguments to an Nx command will often change the behavior of a task. Nx will filter out arguments which are for Nx itself and do not have any effect on running of tasks such as `--parallel` or `--projects`.

For example, running `nx build myreactapp --prod` will not reuse the cached output of running `nx build myreactapp`.

### Source files

Changing source code will often change the behavior of a task. Nx can consider the contents of files matching a pattern when calculating the computation hash.
Source file inputs are defined like this:

```jsonc
{
  "inputs": [
    "{projectRoot}/**/*", // All files in a project
    "{workspaceRoot}/.gitignore", // A specific file in the workspace
    "{projectRoot}/**/*.ts", // A glob pattern for files
    "!{projectRoot}/**/*.spec.ts", // Excluding files matching a glob pattern
  ],
}
```

Source file inputs can be specified as strings with glob patterns. These patterns must be prefixed with either `{projectRoot}` or `{workspaceRoot}` to distinguish where the paths should be resolved from. `{workspaceRoot}` should only appear in the beginning of an input but `{projectRoot}` and `{projectName}` can be specified later in the input to interpolate the root or name of the project into the input location.

Alternatively, you can use the object format with the `fileset` property:

```jsonc
{
  "inputs": [{ "fileset": "{projectRoot}/**/*" }],
}
```

#### Directory paths

When specifying a directory as an input, you must use a trailing slash or a glob pattern. A path without a trailing slash or glob pattern will be treated as a file path and will not match any files within the directory.

```jsonc
// nx.json
{
  "inputs": [
    "{projectRoot}/src/", // ✓ Matches all files in src (note the trailing slash)
    "{projectRoot}/src/**/*", // ✓ Matches all files in src using glob
    "{projectRoot}/src", // ✗ Does NOT match files - treated as a file path
  ],
}
```

{% aside type="note" title="Difference from Outputs" %}
This behavior differs from `outputs`, which support naked directory paths without a trailing slash. For example, `{projectRoot}/dist` works as an output but would not work as an input.
{% /aside %}

#### Token behavior with nested projects

These tokens behave differently when dealing with nested projects:

- `{projectRoot}/**/*` only includes files that are assigned to the specific project. Files in nested projects are excluded.
- `{workspaceRoot}/path/**/*` includes all files matching the pattern in the entire workspace, including files from nested projects.

For example, in a structure like `packages/parent/nested-child/`, using `{projectRoot}/**/*` for the `parent` project will exclude files from `nested-child`, while `{workspaceRoot}/packages/parent/**/*` will include them.

{% aside type="tip" title="Gitignored Files Are Excluded" %}
Files listed in `.gitignore` are automatically excluded from inputs. Nx will not consider gitignored files when computing the hash for tasks; therefore, changes to ignored files will not invalidate the cache.
{% /aside %}

Prefixing a source file input with `!` will exclude the files matching the pattern from the set of files used to calculate the hash.
Prefixing a source file input with `^` means this entry applies to the project dependencies of the project, not the project itself. This allows you to specify exactly which files from dependency projects should be considered as inputs.

```jsonc
{
  "inputs": [
    "{projectRoot}/**/*.ts", // .ts files in the current project
    "^{projectRoot}/**/*.ts", // .ts files in all dependency projects
    "^{workspaceRoot}/tools/**/*", // workspace-level files, applied per dependency
  ],
}
```

You can also use the object format with the `dependencies` property to achieve the same result:

```jsonc
{
  "inputs": [{ "fileset": "{projectRoot}/**/*.ts", "dependencies": true }],
}
```

By default, Nx will use all files in a project as well as all files in the project's dependencies when computing a hash for tasks belonging to the project.
This may cause Nx to rerun some tasks even when files irrelevant to the task have changed but it ensures that by default, Nx always re-runs the task when it should.

To get a better idea of how to use inputs, you can browse some [common input sets](/docs/guides/tasks--caching/configure-inputs#common-inputs).

### Environment variables

Tools and scripts will often use some environment variables to change their behavior. Nx can consider the value of environment variables when calculating the computation hash in order to invalidate the cache if the environment variable value changes. Environment variable inputs are defined like this:

```jsonc
{
  "inputs": [
    { "env": "API_KEY" }, // this will include the value of $API_KEY in the cache hash
  ],
}
```

### Runtime inputs

You can use a Runtime input to provide a script which will output the information you want to include in the computation hash. Runtime inputs are defined like this:

```jsonc
{
  "inputs": [{ "runtime": "node --version" }],
}
```

This kind of input is often used to include versions of tools used to run the task. You should ensure that these scripts work on any platform where the workspace is used. Avoid using `.sh` or `.bat` files as these will not work across Windows and \*nix operating systems.

### Working directory

Some tasks may behave differently depending on which directory they are run from. Nx can include the current working directory in the computation hash to ensure that tasks are re-run when the working directory changes. Working directory inputs are defined like this:

```jsonc
{
  "inputs": [
    { "workingDirectory": "relative" }, // Hash the path relative to workspace root
  ],
}
```

The `workingDirectory` input accepts two values:

- `"relative"` - Hashes the relative path from the workspace root to the current working directory. This is useful when tasks should be invalidated when run from different subdirectories within the workspace.
- `"absolute"` - Hashes the full absolute path of the current working directory. This is useful when tasks depend on the exact location on the filesystem. Notably, this will invalidate cache entries if the repository is cloned to a different location on the filesystem, such as between CI and local development environments.

### External dependencies

Source code often imports from external dependencies installed through package managers. For example, a React application will likely import `react`. It is not needed to configure those `externalDependencies` directly. Nx will always consider external dependencies depended upon by any source code within the project.

External dependencies can also be tools used to run tasks. Updating the versions of those tools will change the behavior of those tasks. External dependencies inputs are defined like this:

```jsonc
{
  "inputs": [{ "externalDependencies": ["jest"] }],
}
```

By default, if no external dependencies inputs are specified, Nx will include the hash of all external dependencies of the workspace in the computation hash.
For many targets, Nx does not know which external dependencies are used and which are not.
By considering all external dependencies, Nx will always re-run tasks when necessary even though in some cases, it might have been able to restore from cache.

For example, when defining a target to run `eslint .`, Nx does not know which ESLint plugins are used by the eslint config.
To be safe, it will consider all external dependencies, including all ESLint plugins, to ensure that the `lint` task is re-run when any of the plugins have been updated.
The drawback of this assumption is that Nx will re-run the `lint` task even when external dependencies not used by ESLint are updated.

```jsonc
{
  "targets": {
    "lint": {
      "command": "eslint .",
    },
  },
}
```

This default behavior can be overridden by adding any external dependency inputs and enables Nx to use cached results more often.

```jsonc {% meta="{7}" %}
{
  "targets": {
    "lint": {
      "command": "eslint .",
      "inputs": [
        "default",
        { "externalDependencies": ["eslint", "eslint-config-airbnb"] },
      ],
    },
  },
}
```

Targets which use an executor from a Nx Plugin maintained by the Nx Team will have the correct set of external dependencies considered when calculating the hash.

### Outputs of dependent tasks

When a task depends on another task, it is possible that the outputs of the dependent task will affect the behavior of the task. The Nx caching mechanism can consider the contents of files produced by dependent tasks that match a pattern. Use outputs of dependent tasks as inputs like this:

```jsonc
{
  "inputs": [
    { "dependentTasksOutputFiles": "**/*.d.ts" },
    { "dependentTasksOutputFiles": "**/*.d.ts", "transitive": true },
  ],
}
```

The glob pattern is matched against the file paths resolved from workspace root. For example, if a dependent task has `outputs: ["{workspaceRoot}/dist/{projectRoot}"]` and the project root is `libs/my-lib`, the output path becomes `dist/libs/my-lib`.
Files such as `dist/libs/my-lib/index.d.ts` would be matched by patterns `**/*.d.ts`, `dist/**/*.d.ts`, or `dist/libs/my-lib/**/*.d.ts`. Setting `transitive` to `true` will also include outputs of all task dependencies of this task in the [task pipeline](/docs/concepts/task-pipeline-configuration). It's possible the dependent tasks can change over time, so be careful to not overly scope the matching glob to prevent accidental false cache hits.

### A subset of the root `tsconfig.json` or `tsconfig.base.json`

When a root `tsconfig.json` or `tsconfig.base.json` is present, Nx will always consider parts of the file which apply to the project of a task being run.
This includes the full `compilerOptions` section and particular path mappings in the `compilerOptions.paths` property.
This allows Nx to not invalidate every single task when a path mapping is added or removed from the root `tsconfig.json` file

### Named inputs from other projects

You can reference named inputs from specific projects or from project dependencies using the object format with the `input` property:

```jsonc
{
  "inputs": [
    // Reference a named input from specific project(s)
    { "input": "production", "projects": "mylib" },
    { "input": "production", "projects": ["mylib", "myapp"] },

    // Reference a named input from the current project
    // Equivalent to: { "input": "production" }
    "production",

    // Reference a named input from all project dependencies
    // Equivalent to: { "input": "production", "dependencies": true }
    "^production",
  ],
}
```

The `projects` property can be a string or an array of strings specifying which project(s) to reference the named input from. Using just the string name (e.g., `"production"`) is shorthand for referencing the named input from the current project. Prefixing with `^` (e.g., `"^production"`) references the named input from all project dependencies.

{% aside type="note" title="^ with filesets vs named inputs" %}
The `^` prefix behaves differently depending on what follows it:

- `^{projectRoot}/**/*.ts` — treated as a **dependency fileset**, hashing matching files in each dependency project
- `^{workspaceRoot}/tools/**/*` — treated as a **dependency fileset** with workspace-level files
- `^production` — treated as a **named input reference**, resolving the `production` named input for each dependency project

In short, if the value after `^` starts with `{projectRoot}` or `{workspaceRoot}`, it is a fileset applied to dependencies. Otherwise, it is interpreted as a named input reference.
{% /aside %}

## Named inputs

Many tasks will utilize the same sets of inputs with minor differences. Nx allows you to define these sets in the `namedInputs` section of the `nx.json` file.

These sets of inputs can then be referenced and reused in the `inputs` array of targets. You can think of these as variables which can be used in the `inputs` array.

Named Inputs can be defined for the entire workspace in `nx.json` or for a specific project in `project.json`/`package.json`.

### Workspace level named inputs

Named inputs defined in `nx.json` can be used by any project in the workspace in the `inputs` array. The following example shows how to define named inputs for the entire workspace in `nx.json`.

```jsonc {%  meta="{3-5}" %}
// nx.json
{
  "namedInputs": {
    "default": ["{projectRoot}/**/*"], // Default Inputs
  },
}
```

### Project level named inputs

Named inputs defined in `package.json` or `project.json` define the value of the named input for tasks belonging to that specific project.

Naming a set of inputs with the same name as a set of inputs defined for the workspace in `nx.json` will override the meaning of that set for the project.

{% tabs %}
{% tabitem label="project.json" %}

```jsonc {% meta="{3-7}" %}
// project.json
{
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"], // Default Inputs
    "production": ["default", "!{projectRoot}/jest.config.ts"], // Production Inputs
    "sharedGlobals": [] // Shared Global Inputs
  },
  "targets": { ... }
}
```

{% /tabitem %}
{% tabitem label="Project Level (package.json)" %}

```jsonc {% meta="{4-8}" %}
// package.json
{
  "dependencies": { ... },
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"], // Default Inputs
    "production": ["default", "!{projectRoot}/jest.config.ts"], // Production Inputs
    "sharedGlobals": [] // Shared Global Inputs
  },
}
```

{% /tabitem %}
{% /tabs %}

### Named input conventions

By default, Nx Workspaces are generated with the following named inputs:

```jsonc
// nx.json
{
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"], // Default Inputs
    "production": ["default", "!{projectRoot}/jest.config.ts"], // Production Inputs
    "sharedGlobals": [], // Shared Global Inputs
  },
}
```

The above inputs follow a convention that Nx recommends for named inputs. Nx generates these by default but you can also introduce your own conventions.

#### Default inputs

The `default` inputs include all files in a project as well as any shared global inputs which should be considered for all tasks. Defaulting to the set of everything that matters ensures that Nx will always re-run tasks when necessary by default.

#### Shared global inputs

The `sharedGlobals` inputs include things that Nx should always look at when determining computation hashes. For instance, this could be the OS where the command is being run or the version of Node.

#### Production inputs

The `production` inputs only include the set of files in a project which will affect behavior of the project in production.
For instance, the `main.ts` of an application will be compiled as the main application logic and will affect the end user experience while files such as `.eslintrc.json` only affect the tools used by the developers and have no direct impact on the end user experience.
In general, it is best to define the `production` inputs as the `default` inputs (everything) excluding the specific files which are known not to affect end user experience. This makes it so that by default, all files are considered to affect end user behavior unless excluded from the `production` fileset.

### Using named inputs on project dependencies

It is common for most tasks to consider a set of inputs for the project it belongs to and a set of inputs for dependencies of the project. For instance, running the tests of a project should consider all files of the project being tested but only production files of its dependencies. The following `inputs` configuration uses named inputs in two different ways:

```jsonc {% meta="{6}" %}
// project.json
{
  "name": "myreactapp",
  "targets": {
    "test": {
      "inputs": ["default", "^production", "{projectRoot}/jest.config.js"],
    },
  },
}
```

1. `default` tells Nx to consider all files within the project root of `myreactapp` when running the `test` task.
2. `^production` is prefixed with `^` and applies the to projects which `myreactapp` depends on.
3. You can add other modifications to the inputs set directly without defining them as named inputs.

All of the above inputs are taken into consideration when the following command is run:

```shell
nx test myreactapp
```

{% cardgrid %}
{% linkcard title="nx.json reference"  description="namedInputs can be defined in nx.json" href="/docs/reference/nx-json#inputs-namedinputs" /%}
{% linkcard title="Project configuration reference"  description="inputs and namedInputs can be defined in project configuration" href="/docs/reference/project-configuration#inputs-and-named-inputs" /%}
{% linkcard title="Configure Inputs for Task Caching"  description="This recipes walks you through a few examples of how to configure inputs and namedInputs" href="/docs/guides/tasks--caching/configure-inputs" /%}
{% /cardgrid %}

---
<!-- source: https://nx.dev/docs/reference/java.md -->
## Java

{% sidebar_group_cards group="Reference/Java" /%}

---
<!-- source: https://nx.dev/docs/reference/jest.md -->
## Jest

{% sidebar_group_cards group="Reference/Jest" /%}

---
<!-- source: https://nx.dev/docs/reference/module-federation.md -->
## Module Federation

{% sidebar_group_cards group="Reference/Module Federation" /%}

---
<!-- source: https://nx.dev/docs/reference/node.md -->
## Node

{% sidebar_group_cards group="Reference/Node" /%}

---
<!-- source: https://nx.dev/docs/reference/nx-cloud.md -->
## Nx Cloud References

{% index_page_cards path="reference/nx-cloud" /%}

---
<!-- source: https://nx.dev/docs/reference/nx-cloud-cli.md -->
## Cloud Commands

The Nx Cloud command line interface provides various commands to connect and interact with Nx Cloud, manage distributed task execution, and handle authentication.
Below is a complete reference for all available commands and their options.

## Available commands

### `nx login`

Provision a local personal access token to access Nx Cloud features. This will open your browser to the Nx Cloud application and after signing in will generate a personal access token and save it in a configuration file locally called `nxcloud.ini`.

This command is the same as running `nx login`.

**Usage:**

```shell
npx nx login [nxCloudUrl]
```

#### Options

| Option       | Type   | Description                                    | Default                |
| ------------ | ------ | ---------------------------------------------- | ---------------------- |
| `nxCloudUrl` | string | The URL of the Nx Cloud instance to connect to | `https://cloud.nx.app` |

#### Configuration file location

{% tabs %}
{% tabitem label="macOS & Linux" %}

We look for this file at the following locations:

- `$XDG_CONFIG_HOME/nxcloud/nxcloud.ini`
- `$HOME/config/nxcloud/nxcloud.ini`
- `$HOME/.nxcloud.ini`

If we don't find an existing config file, we create one at `$HOME/config/nxcloud/nxcloud.ini`

{% /tabitem %}
{% tabitem label="Windows" %}

We look for this file within the `%LOCALAPPDATA%/nxcloud` directory and if it does not exist, we will create a new `nxcloud.ini` file there.

{% /tabitem %}
{% /tabs %}
The format of this file is as follows:

```ini
[https://cloud\.nx\.app]
personalAccessToken=SOME_ACCESS_TOKEN
```

If you have access to multiple instances of the Nx Cloud application (e.g. self-hosted Enterprise and our managed instance), each instance will be saved to this file under its URL.

### `nx logout`

Revoke a personal access token from your local environment. This will remove the personal access token from the locally initialized configuration file and also invalidate the token from the Nx Cloud application. You will be prompted to remove a single token or all tokens from your local environment.

**Usage:**

```shell
npx nx logout
```

### `nx-cloud configure`

To provision more than one personal access token for multiple contexts (e.g. home and work machines) you can use the personal access tokens page under your Nx Cloud profile. To save a personal access token to your local `nxcloud.ini` file without needing to edit the file yourself call `nx-cloud configure`.

**Usage:**

```shell
npx nx-cloud configure
```

#### Options

| Option                  | Type   | Description                            | Default                |
| ----------------------- | ------ | -------------------------------------- | ---------------------- |
| `--personalAccessToken` | string | The personal access token to configure |                        |
| `--nx-cloud-url`        | string | The URL of the Nx Cloud instance       | `https://cloud.nx.app` |

#### Examples

```shell
npx nx-cloud configure --personalAccessToken=SOME_ACCESS_TOKEN
```

To configure multiple tokens for different instances of the Nx Cloud app:

```shell
npx nx-cloud configure --personalAccessToken=SOME_ACCESS_TOKEN --nx-cloud-url=https://nx-cloud.my-domain.app
```

### `nx-cloud convert-to-nx-cloud-id`

When logging into Nx Cloud with a [Personal Access Token](/docs/guides/nx-cloud/personal-access-tokens), your `nx.json` file needs to include the `nxCloudId` property, which acts as a unique identifier for your workspace. If you have been using the previous `nxCloudAccessToken` to connect, simply run `npx nx-cloud convert-to-nx-cloud-id` to automatically update your configuration to use `nxCloudId`.

If you are connecting to Nx Cloud with a workspace that is version 19.6 or lower, this command will also install the latest version of the Nx Cloud npm package and add it into your `package.json`. Only Nx versions 19.7 and higher natively support the `nxCloudId` property in the `nx.json` file; for versions 19.6 and lower, the Nx Cloud npm package will be needed to use that property.

**Usage:**

```shell
npx nx-cloud convert-to-nx-cloud-id
```

### `nx-cloud onboard`

Connect a workspace to Nx Cloud. This command supports an interactive onboarding wizard for humans and JSON-based subcommands for automation and AI agents.

Authentication is required before using this command. Either run `nx login` first or configure a personal access token with `nx-cloud configure`.

**Usage:**

```shell
npx nx-cloud onboard [subcommand] [options]
```

- Without flags, this starts the interactive onboarding wizard.
- With `--no-interactive`, it runs an automation-friendly flow.
- With `--no-interactive` and explicit workspace creation flags such as `--repo`, `--template`, or `--detect-repo`, it routes to `workspace create`.
- With `--no-interactive` and no explicit creation flags, it routes to `connect-workspace` and defaults to JSON output.

#### Options

| Option             | Type    | Description                                                          | Default |
| ------------------ | ------- | -------------------------------------------------------------------- | ------- |
| `--json`           | boolean | Output JSON for scripting                                            | `false` |
| `--token`          | string  | Use a specific Nx Cloud access token for this invocation             |         |
| `--no-interactive` | boolean | Disable interactive prompts                                          | `false` |
| `--workspace-name` | string  | Alias for `--name`                                                   |         |
| `--name`           | string  | Workspace or organization name, depending on the selected flow       |         |
| `--org`            | string  | Organization ID to use                                               |         |
| `--detect-repo`    | boolean | Auto-detect the current Git repository                               | `false` |
| `--write-config`   | boolean | Write the returned `nxCloudId` to `nx.json` after workspace creation | `false` |

#### Examples

```shell
npx nx-cloud onboard
npx nx-cloud onboard --no-interactive --json
npx nx-cloud onboard --no-interactive --org=org_123 --detect-repo --write-config
```

#### Subcommands

##### `nx-cloud onboard status`

Show onboarding status for the authenticated user, including organizations and GitHub connection state.

**Usage:**

```shell
npx nx-cloud onboard status
```

| Option   | Type    | Description               | Default |
| -------- | ------- | ------------------------- | ------- |
| `--json` | boolean | Output JSON for scripting | `false` |

##### `nx-cloud onboard connect-workspace`

One-shot command intended for agents and automated flows. It:

1. Detects the current repository from git remotes.
2. Selects or creates an organization.
3. Checks GitHub connection status.
4. Creates an Nx Cloud workspace from the repository.
5. Writes `nxCloudId` to `nx.json` when possible.

If GitHub authentication is required, JSON mode returns an `actionRequired` payload instead of failing the command.

**Usage:**

```shell
npx nx-cloud onboard connect-workspace
```

| Option   | Type    | Description               | Default |
| -------- | ------- | ------------------------- | ------- |
| `--json` | boolean | Output JSON for scripting | `false` |
| `--org`  | string  | Organization ID to use    |         |
| `--name` | string  | Workspace name override   |         |

```shell
npx nx-cloud onboard connect-workspace --json
npx nx-cloud onboard connect-workspace --org=org_123 --name=my-workspace
```

##### `nx-cloud onboard connect github`

Start GitHub device-flow authentication.

- In interactive mode, this prints instructions, attempts to open the browser, and polls until authorization completes.
- In JSON mode, this returns the device-flow payload and leaves polling to the caller.

**Usage:**

```shell
npx nx-cloud onboard connect github
```

| Option   | Type    | Description               | Default |
| -------- | ------- | ------------------------- | ------- |
| `--json` | boolean | Output JSON for scripting | `false` |

##### `nx-cloud onboard connect github poll`

Poll for completion of a GitHub device-flow authentication started with `connect github`.

**Usage:**

```shell
npx nx-cloud onboard connect github poll --device-code <code>
```

| Option          | Type    | Description                       | Default |
| --------------- | ------- | --------------------------------- | ------- |
| `--device-code` | string  | Device code returned by `connect` |         |
| `--json`        | boolean | Output JSON for scripting         | `false` |

##### `nx-cloud onboard orgs list`

List organizations available to the authenticated user.

**Usage:**

```shell
npx nx-cloud onboard orgs list
```

| Option   | Type    | Description               | Default |
| -------- | ------- | ------------------------- | ------- |
| `--json` | boolean | Output JSON for scripting | `false` |

##### `nx-cloud onboard orgs create`

Create a new organization.

**Usage:**

```shell
npx nx-cloud onboard orgs create <name>
```

| Option   | Type    | Description               | Default |
| -------- | ------- | ------------------------- | ------- |
| `--json` | boolean | Output JSON for scripting | `false` |

##### `nx-cloud onboard repos list`

List repositories available to an organization.

**Usage:**

```shell
npx nx-cloud onboard repos list --org <org-id>
```

| Option       | Type    | Description                        | Default |
| ------------ | ------- | ---------------------------------- | ------- |
| `--org`      | string  | Organization ID                    |         |
| `--search`   | string  | Filter repositories by search term |         |
| `--page`     | number  | Page number to fetch               |         |
| `--per-page` | number  | Number of repositories per page    |         |
| `--json`     | boolean | Output JSON for scripting          | `false` |

##### `nx-cloud onboard templates list`

List available Nx Cloud workspace templates.

**Usage:**

```shell
npx nx-cloud onboard templates list
```

| Option   | Type    | Description               | Default |
| -------- | ------- | ------------------------- | ------- |
| `--json` | boolean | Output JSON for scripting | `false` |

##### `nx-cloud onboard vcs status`

Show GitHub App connection status for an organization.

**Usage:**

```shell
npx nx-cloud onboard vcs status --org <org-id>
```

| Option   | Type    | Description               | Default |
| -------- | ------- | ------------------------- | ------- |
| `--org`  | string  | Organization ID           |         |
| `--json` | boolean | Output JSON for scripting | `false` |

##### `nx-cloud onboard workspace create`

Create a workspace either from an existing repository or from a template.

Use exactly one of:

- `--repo` with `--repo-full-name`
- `--template`
- `--detect-repo`

When `--write-config` is provided, the command attempts to add the returned `nxCloudId` to `nx.json`.

**Usage:**

```shell
npx nx-cloud onboard workspace create --org <org-id> [options]
```

| Option                  | Type    | Description                                                          | Default |
| ----------------------- | ------- | -------------------------------------------------------------------- | ------- |
| `--org`                 | string  | Organization ID                                                      |         |
| `--name`                | string  | Workspace name                                                       |         |
| `--workspace-name`      | string  | Alias for `--name`                                                   |         |
| `--repo`                | string  | Repository ID for an existing repository                             |         |
| `--repo-full-name`      | string  | Repository full name in `owner/repo` format                          |         |
| `--default-branch`      | string  | Default branch for an existing repository                            | `main`  |
| `--template`            | string  | Template ID for template-based workspace creation                    |         |
| `--github-organization` | string  | GitHub organization for template-based workspace creation            |         |
| `--repo-name`           | string  | Repository name override for template-based workspace creation       |         |
| `--private`             | boolean | Mark the created workspace repository as private                     | `true`  |
| `--installation-id`     | string  | GitHub App installation ID override for existing repositories        |         |
| `--detect-repo`         | boolean | Auto-detect the current repository and populate repository arguments | `false` |
| `--write-config`        | boolean | Write the returned `nxCloudId` to `nx.json`                          | `false` |
| `--json`                | boolean | Output JSON for scripting                                            | `false` |

```shell
npx nx-cloud onboard workspace create --org=org_123 --repo=repo_456 --repo-full-name=acme/web --name=web
npx nx-cloud onboard workspace create --org=org_123 --detect-repo --write-config
npx nx-cloud onboard workspace create --org=org_123 --template=tmpl_react --name=demo
```

#### Automation notes

- `--json` is supported across all onboarding subcommands intended for scripting.
- `connect-workspace` is the best entry point for AI agents because it can detect the repository, create an organization when needed, and return actionable JSON when GitHub authorization is required.
- `connect github --json` starts device flow, and `connect github poll --device-code ... --json` can be used to poll for completion.

### `nx-cloud start-ci-run`

At the beginning of your main job, invoke `npx nx start-ci-run`. This tells Nx Cloud that the following series of command correspond to the same CI run.

**Usage:**

```shell
npx nx start-ci-run
```

{% aside type="caution" title="Do not run start-ci-run locally" %}
`npx nx start-ci-run` generates a temporary marker file that can cause a local Nx repo to behave as if it is a part of a CI run. This can cause strange behavior like Nx commands timing out or throwing unexpected errors.
To discourage this from happening, this command will run a check to see if it is running in a CI environment. You can bypass this check with `npx nx start-ci-run --force`.

If you accidentally run this command locally, remove all generated marker files with `npx nx-cloud cleanup`.

{% /aside %}

#### Options

| Option                          | Type    | Description                                                                                                                                                                               | Default |
| ------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `--distribute-on`               | string  | Configure the number of agents, [launch templates](/docs/reference/nx-cloud/launch-templates) and [assignment rules](/docs/reference/nx-cloud/assignment-rules) for distributed execution |         |
| `--assignment-rules`            | string  | Path to the [assignment rules configuration](/docs/reference/nx-cloud/assignment-rules#using-assignment-rules-with-manual-dte) for manual distribution.                                   |         |
| `--require-explicit-completion` | boolean | Disable automatic completion monitoring and require explicit `nx complete-ci-run`                                                                                                         | `false` |
| `--stop-agents-after`           | string  | Comma-separated list of targets after which agents should terminate                                                                                                                       |         |
| `--stop-agents-on-failure`      | boolean | Terminate all agents when a command fails. This flag does not interrupt the command itself. To cancel the command on failure use [nxBail](/docs/reference/nx-commands)                    | `true`  |
| `--use-dte-by-default`          | boolean | Configure Nx to distribute all commands by default                                                                                                                                        | `true`  |
| `--with-env-vars`               | string  | Comma-separated list of environment variables to pass to Nx Agents                                                                                                                        |         |
| `--fix-tasks`                   | string  | Comma-separated glob patterns for tasks to enable [AI self-healing](/docs/features/ci-features/self-healing-ci). Supports negation with `!` prefix                                        |         |
| `--auto-apply-fixes`            | string  | Comma-separated glob patterns for [self-healing](/docs/features/ci-features/self-healing-ci) tasks to auto-apply to PRs without manual review                                             |         |
| `--force`                       | boolean | Bypass CI environment check. Run [`nx-cloud cleanup`](#nx-cloud-cleanup) if accidentally ran locally.                                                                                     |         |

#### Detailed option usage

##### `--distribute-on`

By default, `npx nx start-ci-run` is intended for use with [Nx Agents](/docs/features/ci-features/distribute-task-execution) and expects `--distribute-on` to be configured. It will output a warning if this flag is not set. If you are running a distributed execution with a legacy setup without Nx Agents, you can pass `--distribute-on=manual` to disable this warning.

This command tells Nx Cloud how many agents to use (and what launch templates to use) to distribute tasks. E.g.,
`npx nx start-ci-run --distribute-on="8 linux-medium-js"` will distribute CI using 8 agents that are initialized
using the `linux-medium-js` launch template.

You can also [define the configuration in a file](/docs/features/ci-features/dynamic-agents) and reference it as follows:
`npx nx start-ci-run --distribute-on=".nx/workflows/dynamic-changesets.yaml"`.

```yaml
// .nx/workflows/dynamic-changesets.yaml
distribute-on:
  small-changeset: 3 linux-medium-js
  medium-changeset: 6 linux-medium-js
  large-changeset: 10 linux-medium-js
```

##### --stop-agents-after

You can tell Nx Cloud to terminate agents after it sees a certain
target or group of targets: `npx nx start-ci-run --stop-agents-after=build,test,e2e`.

{% aside type="tip" title="Be specific!" %}
For the best results, always tell Nx Cloud about all targets that should be expected during your pipeline. This will
prevent your CI Pipeline Execution from ending prematurely, cutting off any unfinished work.

{% /aside %}

Whether you are running commands serially or in parallel (through use of the `&` operand or discrete jobs), you should
include one or more targets from each command.

{% tabs %}
{% tabitem label="Serial command execution" %}

#### Incorrect example:

```yaml
- run: npx nx start-ci-run --stop-agents-after=build
- run: nx affected -t build
- run: nx affected -t lint
- run: nx affected -t test
```

Nx Cloud will only look for the presence of a `build` target before determining your pipeline can be shut down. Since
both `lint` and `test` will only run after `build` is complete, your pipeline would end before all intended work is
executed.

#### Corrected example:

```yaml
- run: npx nx start-ci-run --stop-agents-after=lint,test,build
- run: nx affected -t lint
- run: nx affected -t test
- run: nx affected -t build
```

{% /tabitem %}
{% tabitem label="Parallel command execution" %}

#### Incorrect example:

```yaml
- run: npx nx start-ci-run --stop-agents-after=test
- run: nx affected -t build & nx affected -t lint & nx affected -t test
```

At first glance, this example may appear correct. However, since all the commands are executed in parallel, it could
be possible that your `test` command results in full cache hits and finishes faster than the `build` and `lint` commands.
In this case, Nx Cloud will stop your pipeline, leaving work incomplete for both the `build` and `lint` commands.

#### Corrected example:

```yaml
- run: npx nx start-ci-run --stop-agents-after=lint,test,build
- run: nx affected -t build & nx affected -t lint & nx affected -t test
```

{% /tabitem %}
{% /tabs %}

#### Advanced shutdown targeting

In advanced pipeline setups, it is possible that you want to run multiple commands with the same target, but with
distinct configurations. An example of this may be doing static translations for different locales during your builds.

```yaml
- run: npx nx start-ci-run --stop-agents-after=build
- run: nx affected -t build --configuration=locale-en
- run: nx affected -t build --configuration=locale-es
```

In this case, the `build` target will be executed twice, once with the `locale-en` configuration and once with the
`locale-es` configuration. However, Nx Cloud is only looking for the `build` target to assess whether the CI Pipeline
Execution can be marked complete.

To address this, you can pass an optional `configuration` to make your `target`s more specific.

```yaml
- run: npx nx start-ci-run --stop-agents-after=build:locale-en,build:locale-es
- run: nx affected -t build --configuration=locale-en
- run: nx affected -t build --configuration=locale-es
```

##### --with-env-vars (Nx Agents only)

By default, invoking `npx nx start-ci-run` will take all environment variables prefixed with `NX_` and send them over to Nx Agents.
This means that your access token, verbose logging configuration and other Nx-related environment variables will be the same on your
main CI jobs and the Nx Agent machines.

If you want to pass other environment variables from the main job to Nx Agents, you can do it as follows: `--with-env-vars="VAR1,VAR2"`.
This will set `VAR1` and `VAR2` on Nx Agents to the same values set on the main job before any steps run.

> Note: none of the values passed to Nx Agents are stored by Nx Cloud.

##### --fix-tasks

Enable [AI-powered self-healing](/docs/features/ci-features/self-healing-ci) for specific tasks. When a task fails, Nx Cloud will attempt to analyze the error and generate a fix. By default, all tasks are enabled for self-healing. You can use glob patterns to limit which tasks are eligible.

Examples:

```shell
# Enable for lint and format tasks only
npx nx start-ci-run --fix-tasks="*lint*,*format*" --no-distribution

# Enable for all tasks except deploy and test
npx nx start-ci-run --fix-tasks="!*deploy*,!*test*" --no-distribution
```

The patterns support:

- `*` wildcard to match any characters
- `!` prefix to exclude tasks (negation)
- Multiple comma-separated patterns

##### --auto-apply-fixes

Automatically apply [AI-generated fixes](/docs/features/ci-features/self-healing-ci) to pull requests for specific tasks without requiring manual review. Fixes are only applied if the verification phase passes.

Examples:

```shell
# Auto-apply fixes for linting tasks only
npx nx start-ci-run --auto-apply-fixes="*lint*" --no-distribution

# Auto-apply fixes for both lint and format tasks
npx nx start-ci-run --auto-apply-fixes="*lint*,*format*" --no-distribution
```

#### Enabling/Disabling distribution

Invoking `npx nx start-ci-run` will tell Nx to distribute by default. You can enable/disable distribution for
individual commands as follows:

{% tabs %}
{% tabitem  label="Nx >= 18" %}

Explicitly enable distribution:

```shell
nx affected -t build --agents
```

Explicitly disable distribution:

```shell
nx affected -t build --no-agents
```

{% /tabitem %}
{% tabitem  label="Nx >= 14.7" %}

Explicitly enable distribution:

```shell
nx affected -t build --dte
```

Explicitly disable distribution:

```shell
nx affected -t build --no-dte
```

{% /tabitem %}
{% /tabs %}

### `nx start-agent`

Starts an agent process for [manual distributed task execution](/docs/guides/nx-cloud/manual-dte). The agent waits for Nx Cloud to assign tasks that have been distributed by the main CI job via `start-ci-run`. For automatic agent management, use [Nx Agents](/docs/features/ci-features/distribute-task-execution) instead.

**Usage:**

```shell
npx nx start-agent
```

#### Options

| Option      | Type    | Description                          | Default |
| ----------- | ------- | ------------------------------------ | ------- |
| `--verbose` | boolean | Enable verbose logging for debugging | `false` |

#### Environment variables

Use the `NX_AGENT_NAME` environment variable to assign a name to the agent for identification in logs and the Nx Cloud UI:

```shell
NX_AGENT_NAME=agent-1 npx nx start-agent
```

For complete examples across different CI providers, see the [Manual Distributed Task Execution guide](/docs/guides/nx-cloud/manual-dte).

### `nx stop-all-agents`

Same as `npx nx complete-ci-run`.

This command tells Nx Cloud to terminate all agents associated with this CI pipeline execution.
Invoking this command is not needed anymore. New versions of Nx Cloud can track when the main job terminates
and terminate associated agents automatically.

**Usage:**

```shell
npx nx stop-all-agents
```

### `nx complete-ci-run`

Explicitly complete a CI run when using `--require-explicit-completion` with `start-ci-run`.

**Usage:**

```shell
npx nx complete-ci-run
```

### `nx-cloud cleanup`

Remove temporary marker files created by `start-ci-run` if accidentally run locally.

**Usage:**

```shell
npx nx-cloud cleanup
```

## Getting help

You can get help for any command by adding the `--help` flag:

```shell
npx nx-cloud <command> --help
```

---
<!-- source: https://nx.dev/docs/reference/nx-cloud/assignment-rules.md -->
## Assignment Rules

Assignment rules allow you to control which tasks can run on which agents. Save on agent costs by provisioning different sizes of agents to suite the individual needs of your tasks. Ensure resource intensive targets like `e2e-ci` and `build` have what they need by using larger agents and with a specified parallelism. Lighter tasks like `lint` and `test` can run on smaller agents.

Assignment rules are defined in `yaml` files within your workspace's `.nx/workflows` directory. You can use assignment rules with [Manual Distributed Task Execution (DTE)](/docs/guides/nx-cloud/manual-dte) or with [dynamic Nx Agents](/docs/features/ci-features/dynamic-agents). Note that additional configuration is required when using Manual DTE.

## How to define an assignment rule

Each assignment rule has one of the following properties that it matches against tasks: `projects`, `targets`, and/or `configurations`. You can provide a list of globs to match against the tasks in your workspace. It also has a list of possible [agent types](/docs/reference/nx-cloud/launch-templates) that tasks with the matching properties can run on. Rules are defined in yaml like the following:

{% tabs syncKey="dte-kind" %}
{% tabitem label="Assignment rules with Nx Agents" %}

```yaml
// .nx/workflows/distribution-config.yaml
distribute-on:
  default: 5 linux-medium-js, 5 linux-large-js

assignment-rules:
  - projects:
      - app1
    targets:
      - e2e-ci*
    configurations:
      - production
    run-on:
      - agent: linux-medium
        parallelism: 5

  - targets:
      - lint
      - build
    run-on:
      - agent: linux-large
        parallelism: 10
```

{% /tabitem %}
{% tabitem label="Assignment rules with manual DTE" %}

```yaml
// .nx/workflows/assignment-rules.yaml
assignment-rules:
  - projects:
      - app1
    targets:
      - e2e-ci*
    run-on:
      - agent: linux-medium
        parallelism: 5

  - targets:
      - lint,build
    run-on:
      - agent: linux-large
        parallelism: 10
```

{% /tabitem %}
{% /tabs %}

The above rule will match any task that has a project named `app1`, any targets that begin with `e2e-ci`, and a configuration named `production`. Any tasks that match this rule will only be allowed to run on agents with `linux-medium-js` launch templates. Agents assigned these tasks will also be able to execute up to `5` tasks in parallel.

The second rule above will match any task that has a `lint` or `build` target. These tasks only run on `linux-large` agents and up to 10 tasks can be executed in parallel by agents of that type.

You can mix and match any of the criteria in an assignment rule provided that you follow the constraints:

- At least one of the following properties is defined: `projects`, `targets`, `configurations`.
- There is at least one [agent type](/docs/reference/nx-cloud/launch-templates) specified in the `run-on` field. If no parallelism is specified, the parallelism of the executed command will be used instead. If that is not specified, then the parallelism will default to `1`
- For assignment rules with Nx Agents, every changeset in your `distribute-on` field must include at **least one agent** that matches each agent type specified in the `run-on` field across all assignment rules. For example, if your rules distribute tasks on `linux-small-js`, `linux-medium-js`, and `linux-large-js`, then at least one agent of each type must be available; otherwise, tasks associated with those rules cannot be executed.

{% aside type="note" title="If you are using Manual DTE, you must define your own agent types" %}
You must define your own agent types and attach them to your agents using the `NX_AGENT_LAUNCH_TEMPLATE` environment variable. Ensure that for each `run-on` field in your assignment rules, you have corresponding agents in your agent pool that have the same agent type.
See below for an [example](#using-assignment-rules-with-manual-dte) of how to define your own agent types when using Manual DTE.
{% /aside %}

### Assignment rule property reference

<!-- vale Nx.Headings = NO -->

#### projects

<!-- vale Nx.Headings = YES -->

A list of string globs that matches against projects in your workspace.

<!-- vale Nx.Headings = NO -->

#### targets

<!-- vale Nx.Headings = YES -->

A list of string globs that matches against targets in your workspace.

<!-- vale Nx.Headings = NO -->

#### configurations

<!-- vale Nx.Headings = YES -->

A list of string globs that matches against configurations in your workspace.

<!-- vale Nx.Headings = NO -->

#### run-on

<!-- vale Nx.Headings = YES -->

Specification of which agent and how to run your tasks:

- **agent**: the type of agent to run on (`linux-medium`, `linux-large`)
- **parallelism**: the number of parallel executions allowed for agents of a given type

### Glob reference

You can use globs for better control over how to define your assignment rules.

##### `*` matches zero or more characters

- ✅ `lint*` matches `lint-js`, `linting-test`
- ✅ `*test*` matches `business-test-2`, `test-12`, `10-test`
- ❌ `lint*` does not match `eslint`, `lin-test`, `lin`

##### `?` matches exactly one character

- ✅ `app?` matches `app1`, `app3`, `apps`
- ❌ `app?` does not match `app10`, `apps1`, `bus-app1`

##### `!` at start negates the pattern

- ✅ `!prod` matches `development`, `staging`
- ❌ `!prod` does not match `prod`

#### List delimited globs

If you provide a list of globs to an individual rule property (`projects`, `targets`, `configurations`), it will match any of the patterns for that given property.

```yaml
// .nx/workflows/assignment-rules.yaml
assignment-rules:
  - targets:
      - e2e-ci*
      - lint*
    run-on:
      - agent: linux-medium
        parallelism: 2
```

The following rule will match the following tasks:

- starts with `e2e-ci` (i.e `e2e-ci--playwright-button-test`)
- starts with `lint` (i.e `lint-js`)

#### Comma delimited globs

Within each list entry, you can define a comma delimited list of globs. This notation will match a given property only if all globs match.

```yaml
// .nx/workflows/assignment-rules.yaml
assignment-rules:
  - targets:
      - 'e2e-ci*,*server-test'
      - 'lint*'
    run-on:
      - agent: linux-large
        parallelism: 5
```

The following rule will match the following tasks:

- starts with `e2e-ci` and ends with `server-test` (i.e `e2e-ci--playwright-server-test`)
- starts with `lint` (i.e `lint-js`)

### Configuring parallelism through assignment rules

You can specify how many tasks of a certain type can run in parallel on a particular agent. Each agent object within the `run-on` list can have the `parallelism` property. Configuring parallelism through your assignment rules will override the other parallelism configurations in your workspace. For a given command run with DTE, parallelism is determined by in the following order:

1. Parallelism defined in the assignment rules
2. Parallelism defined in the `--parallel` flag in your command
3. Parallelism defined in your `nx.json` file (`parallel: 3`)

If none of these methods of configuring parallelism are used, the parallelism of executed tasks will default to `1`.

Note that there are two special cases for parallelism with assignment rules where the behaviour may differ.

1. All tasks that are marked as `non-cacheable` (they are configured with `cache: false`) will be run with a parallelism of `1` regardless of the parallelism defined in the assignment rules or execution. This is usually the case with tasks such as `e2e-ci` which may requires each process to have its own environment or resources to run.
2. Assignment rules only apply to distributed executions (DTE). If you want to run multiple tasks in parallel without DTE (via the `--no-dte` flag), you will need to use the `--parallel` flag in your commands.

```shell
nx affected -t lint test built --no-dte --parallel=3
```

#### Assignment rules parallelism example

```shell
// .github/workflows/ci.yaml
nx affected -t lint test build --parallel=3
```

```yaml
// .nx/workflows/assignment-rules.yaml
assignment-rules:
  - targets:
      - lint
      - test
    run-on:
      - agent: linux-medium
        parallelism: 4

  - targets:
      - build
    run-on:
      - agent: linux-large
```

In the above example, the `lint` and `test` targets will run on `linux-medium` agents with a parallelism of `4` as defined within the rules. The `build` target will run on `linux-large` agents, but note that there is no parallelism defined for that target. The parallelism for `build` tasks will then use the value provided by the `--parallel` flag, which is `3`.

#### Setting default parallelism for multiple tasks

Putting globs and parallelism together, you can set a default parallelism for all tasks within your executions. Take the following statement:

> Only `e2e-ci` tasks should run on large agents. All other tasks should run on medium agents with a parallelism of 5.

This can be represented as the following yaml config.

```yaml
assignment-rules:
  # Since this rule was defined first and `targets` has a higher precedence order,
  # e2e-ci tasks will use this rule
  - targets:
      - e2e-ci*
    run-on:
      - agent: linux-large

  # This rule will match all projects in your workspace
  - projects:
      - '*'
    run-on:
      - agent: linux-medium
        parallelism: 5
```

## Assignment rule precedence

Having multiple assignment rules means that often rules may overlap or apply to the same tasks. For a given task, only one rule will ever be applied. To determine which rule take priority, a rule of thumb is that **more specific rules take precedence over more general rules**. You can consult our precedence chart for a full list of rule priorities. A checkmark indicates that a rule has a particular property defined.

If two rules have the same priority based on the below chart, the rule that appears first in the `assignment-rules` list will take precedence.

| Priority | Configuration | Target | Project |
| :------: | :-----------: | :----: | :-----: |
|    1     |      ✅︎      |  ✅︎   |   ✅︎   |
|    2     |      ✅︎      |  ✅︎   |         |
|    3     |      ✅︎      |        |   ✅︎   |
|    4     |               |  ✅︎   |   ✅︎   |
|    5     |      ✅︎      |        |         |
|    6     |               |  ✅︎   |         |
|    7     |               |        |   ✅    |

### Rule precedence example

In this example, the task defined below can match multiple assignment rules. However, since the second rule specifies all three properties (`projects`, `targets`, and `configurations`) rather than just two (`projects` and `targets`), it takes precedence, and we automatically apply the second rule when distributing the task.

```json {% title="A task from your workspace" %}
{
  "project": "app1",
  "target": "build",
  "configuration": "production"
}
```

```yaml
// .nx/workflows/distribution-config.yaml
assignment-rules:
  - projects:
      - app1
    targets:
      - build
    run-on:
      - agent: linux-large-js
        parallelism: 3

  # A task for app1:build:production will use this rule because it is more
  # specific (matches three properties instead of just two)
  - projects:
      - app1
    targets:
      - build
    configurations:
      - production
    run-on:
      - agent: linux-medium-js
        parallelism: 5
```

## Using assignment rules with manual DTE

A typical `assignment-rules.yaml` file might look like this:

```yaml
// .nx/workflows/assignment-rules.yaml
assignment-rules:
  - projects:
      - app1
    targets:
      - build
    configurations:
      - production
    run-on:
      - agent: linux-medium
        parallelism: 5
      - agent: linux-large

  - targets:
      - lint
    run-on:
      - agent: linux-medium

  - configurations:
      - development
    run-on:
      - agent: linux-medium
      - agent: linux-large
```

Note that the agent types supplied in the `run-on` property will be used to determine which agents will have rules applied to them.
You can choose to name your agent types anything you want, but they must be set on your agents via the `NX_AGENT_LAUNCH_TEMPLATE` environment variable.

You can then reference your assignment rules file within your `start-ci-run` command:

```shell
npx nx start-ci-run --distribute-on="manual" --assignment-rules=".nx/workflows/assignment-rules.yaml"
```

The following is an example of what this looks like within a Github Actions pipeline:

```yaml
// .github/workflows/ci.yaml
---
jobs:
  main:
    name: Main Job
    runs-on: ubuntu-latest
    steps:
      - ... # setup steps for your main job

      - run: npx nx start-ci-run --distribute-on="manual" --assignment-rules=".nx/workflows/assignment-rules.yaml" --stop-agents-after="e2e-ci"

      - ... # Nx commands you want to distribute

  medium-agents:
    name: Agents ${{ matrix.agent }}
    runs-on:
      group: medium-agents
    strategy:
      matrix:
        agent: [1, 2, 3]
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - ... # other setup steps you may need

      - name: Install dependencies
        run: npm ci

      - name: Start Agent ${{ matrix.agent }}
        run: npx nx start-agent
        env:
          NX_AGENT_NAME: ${{ matrix.agent }}
          NX_AGENT_LAUNCH_TEMPLATE: 'linux-medium' # This value needs to match one of the 'run-on' values defined in the assignment rules

  large-agents:
    name: Agents ${{ matrix.agent }}
    runs-on:
      group: large-agents
    strategy:
      matrix:
        agent: [4, 5, 6]

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - ... # other setup steps you may need

      - name: Install dependencies
        run: npm ci

      - name: Start Agent ${{ matrix.agent }}
        run: npx nx start-agent
        env:
          NX_AGENT_NAME: ${{ matrix.agent }}
          NX_AGENT_LAUNCH_TEMPLATE: 'linux-large' # This value needs to match one of the 'run-on' values defined in the assignment rules
```

## Using assignment rules with dynamic Nx Agents

A typical `distribution-config.yaml` file might look like this:

```yaml
// .nx/workflows/distribution-config.yaml
distribute-on:
  default: 5 linux-medium-js, 5 linux-large-js

assignment-rules:
  - projects:
      - app1
    targets:
      - build
    configurations:
      - production
    run-on:
      - agent: linux-large-js

  - targets:
      - lint
    run-on:
      - agent: linux-medium-js
        parallelism: 3

  - configurations:
      - development
    run-on:
      - agent: linux-medium-js
      - agent: linux-large-js
```

You can then reference your distribution configuration in your CI pipeline configuration:

```yaml {% meta="{9}" %}
// .github/workflows/main.yaml
...
jobs:
  - job: main
    name: Main Job
    ...
    steps:
      ...
      - run: npx nx start-ci-run --distribute-on=".nx/workflows/distribution-config.yaml" --stop-agents-after="e2e-ci"
      - ..
```

### More examples of assignment rules with dynamic agents

#### Invalid assignment rules example

```yaml
// .nx/workflows/distribution-config.yaml
distribute-on:
  # Invalid changeset that is missing `linux-large-js`. Tasks assigned to large agents won't be able to execute.
  small-changeset: 1 linux-small-js, 2 linux-medium-js
  medium-changeset: 2 linux-small-js, 2 linux-medium-js, 3 linux-large-js
  large-changeset: 3 linux-small-js, 3 linux-medium-js, 4 linux-large-js

assignment-rules:
  # Missing one of `projects`, `targets`, `configurations`
  - run-on:
      - agent: linux-medium-js
        parallelism: 1
      - agent: linux-large-js
        parallelism: 3

  # Missing `run-on`
  - targets:
      - lint
    configurations:
      - production

  # Agent type not found in any of the `distribute-on` changesets
  - projects:
      - lib1
    targets:
      - test
    run-on:
      - agent: linux-extra-large-js
```

#### Valid assignment rules example

```yaml
// .nx/workflows/distribution-config.yaml
distribute-on:
  default: 3 linux-small-js, 2 linux-medium-js, 1 linux-large-js

# All rules below are valid assignment rules
assignment-rules:
  - projects:
      - app1
    run-on:
      - agent: linux-medium-js
      - agent: linux-large-js

  - targets:
      - lint
    configurations:
      - production
    run-on:
      - agent: linux-large-js
        parallelism: 10

  - projects:
      - lib1
    targets:
      - test
    run-on:
      - agent: linux-medium-js
```

## Deprecated assignment rules

Assignment rules used to be defined with the following schema. However, this schema did not support multi-glob matching, nor parallelism. Rules defined in this format will still work, but we recommend updating them to the new schema.

```yaml
// .nx/workflows/distribution-config.yaml
# We recommend updating your assignment rules to the most recent schema
assignment-rules:
  - project: app1 # replaced by `projects`
    target: e2e-ci* # replaced by `targets`
    configuration: production # replaced by `configurations`
    runs-on: # replaced by `run-on`
      - linux-medium-js
      - linux-large-js
```

---
<!-- source: https://nx.dev/docs/reference/nx-cloud/config.md -->
## Configuring the Cloud Runner

The Nx Cloud runner is configured in `nx.json`.

{% tabs %}
{% tabitem label="Nx >= 19.7" %}

```json
// nx.json
{
  "nxCloudId": "SOMEID"
}
```

{% /tabitem %}
{% tabitem label="Nx <= 19.6" %}

```json
// nx.json
"tasksRunnerOptions": {
    "default": {
      "runner": "nx-cloud",
      "options": {
        "nxCloudId": "SOMEID"
      }
    }
  }
```

To utilize personal access tokens and Nx Cloud ID with Nx <= 19.6, the nx-cloud npm package is also required to be installed in your workspaces `package.json`.

```json
// package.json
{
  "devDependencies": {
    "nx-cloud": "latest"
  }
}
```

{% /tabitem %}
{% /tabs %}

## CI access tokens

CI Access Tokens are used in CI environments to provide read-write privileges for pipelines. They should not be committed to source control and should instead be exposed as CI environment secrets.  
You can configure CI Access Tokens as environment variables (`NX_CLOUD_AUTH_TOKEN` and `NX_CLOUD_ACCESS_TOKEN` are aliases of each other) or define them in `nx.json` as follows:

{% tabs %}
{% tabitem label="Nx >= 17" %}

```json
{
  "nxCloudAccessToken": "SOMETOKEN"
}
```

{% /tabitem %}
{% tabitem label="Nx < 17" %}

```json
"tasksRunnerOptions": {
    "default": {
      "runner": "nx-cloud",
      "options": {
        "accessToken": "SOMETOKEN"
      }
    }
  }
```

{% /tabitem %}
{% /tabs %}

## Cacheable operations

Targets can be marked as cacheable either in the `targetDefaults` in `nx.json` or in the project configuration by setting `"cache": true`. With this option enabled they can be cached and distributed using Nx Cloud.

## Timeouts

By default, Nx Cloud requests will time out after 10 seconds. `NX_CLOUD_NO_TIMEOUTS` disables the timeout.

```shell
NX_CLOUD_NO_TIMEOUTS=true nx run-many -t build
```

## Logging

Setting `NX_VERBOSE_LOGGING=true` when running a command will emit a large amount of metadata It will print information about what artifacts are being downloaded and uploaded, as well as information about the hashes of every computation.

This can be useful for debugging unexpected cache misses, and issues with on-prem setups.

`NX_VERBOSE_LOGGING=true` will also print detailed information about distributed task execution, such as what commands were sent where, etc.

`NX_VERBOSE_LOGGING` is often enabled in CI globally while debugging your CI setups.

## Enabling end-to-end encryption

All communication with Nx Cloud's API and cache is completed over HTTPS, but you can optionally enable e2e encryption by providing a secret key through `nx.json` or the `NX_CLOUD_ENCRYPTION_KEY` environment variable.

{% tabs %}
{% tabitem label="Nx >= 17" %}
In `nx.json`, add the `nxCloudEncryptionKey` property. It will look something like this:

```json
{
  "nxCloudEncryptionKey": "cheddar"
}
```

{% /tabitem %}
{% tabitem label="Nx < 17" %}
In `nx.json`, locate the `taskRunnerOptions` property. Under its "options" property, you can add another property called `encryptionKey`. This is what will be used to encrypt your artifacts. It will look something like this:

```json
{
  "tasksRunnerOptions": {
    "default": {
      "runner": "nx-cloud",
      "options": {
        "accessToken": "SOMETOKEN",
        // Add the following property with your secret key
        "encryptionKey": "cheddar"
      }
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

To instead use an environment variable to provide your secret key, run any Nx command as follows:

```shell
NX_CLOUD_ENCRYPTION_KEY=myEncryptionKey nx build my-project
```

This is an alternative to providing the encryption key through `nx.json`, but functionally it is identical.

## Loading env variables from a file

If you create an env file called `nx-cloud.env` at the root of the workspace, the Nx Cloud runner is going to load `NX_CLOUD_ENCRYPTION_KEY` and `NX_CLOUD_AUTH_TOKEN` from it. The file is often added to `.gitignore`.

## Disabling connections to Nx Cloud

If your organization has a security reason to disable Nx Cloud, you can cause all methods of connection to fail by adding the `neverConnectToCloud` property to `nx.json`.

This does not disable the prompts themselves, as the `nx-cloud` package handles this property to provide maximum compatibility with Nx.

A side effect of this is that the `nx-cloud` or `@nrwl/nx-cloud` package may still be installed in your workspace. You can safely remove this, and its presence will send no data (telemetry or otherwise) to Nx Cloud.

You must be on version `16.0.4` or later of `nx-cloud` or `@nrwl/nx-cloud` for this value to be respected.

```json
{
  // The following will cause all attempts to connect your workspace to Nx Cloud to fail.
  // This value does not prevent using Nx Cloud if already connected.
  // Use NX_NO_CLOUD=true env var to prevent using Nx Cloud when running commands
  "neverConnectToCloud": true
}
```

---
<!-- source: https://nx.dev/docs/reference/nx-cloud/credits-pricing.md -->
## Nx Cloud Credit Pricing Reference

Credits are the Nx Cloud currency that enables usage-based pricing. This system allows for transparent cost tracking and flexible billing based on actual consumption of resources.

## What are credits?

Credits represent the computational resources consumed during CI/CD operations. They account for:

- CPU usage
- Memory consumption
- Setup and provisioning costs
- Storage operations
- Task execution time
- AI computation

## Credit pricing

### Non-compute pricing

- **CI Pipeline Execution: 500 credits per execution**. A CI Pipeline Execution is a CI run or a Workflow run (depending on your CI provider). For instance, running a PR or running CI on the main branch are CI Pipeline Executions.
- **AI-Powered Self-Healing CI: 6555 credits per 1M input tokens, 32700 credits per 1M output tokens**. Credits are consumed by the fix-ci command.

### Agents resource classes

#### Docker / Linux AMD64

| Resource Class | Specifications    | Credits/min |
| -------------- | ----------------- | ----------- |
| Small          | 1 vCPU, 2GB RAM   | 5           |
| Medium         | 2 vCPU, 4GB RAM   | 10          |
| Medium +       | 3 vCPU, 6GB RAM   | 15          |
| Large          | 4 vCPU, 8GB RAM   | 20          |
| Large +        | 4 vCPU, 10GB RAM  | 30          |
| Extra large    | 8 vCPU, 16GB RAM  | 40          |
| Extra large +  | 10 vCPU, 20GB RAM | 60          |

#### Docker / Linux ARM64

| Resource Class | Specifications   | Credits/min |
| -------------- | ---------------- | ----------- |
| Medium         | 2 vCPU, 8GB RAM  | 13          |
| Large          | 4 vCPU, 16GB RAM | 26          |
| Extra large    | 8 vCPU, 32GB RAM | 52          |

#### Docker / Windows

| Resource Class | Specifications  | Credits/min |
| -------------- | --------------- | ----------- |
| Medium         | 3 vCPU, 6GB RAM | 40          |

---

_Note: Prices do not include applicable taxes. Credit pricing and allocations subject to change._

---
<!-- source: https://nx.dev/docs/reference/nx-cloud/custom-images.md -->
## Custom images for Nx Agents

{% aside type="caution" title="Nx Enterprise" %}
Using a custom base image for Nx Agents is a feature of Nx Enterprise plan for Nx Cloud. If you're interested in Nx Enterprise, we'd love to [chat with you about enterprise](https://nx.dev/enterprise)
{% /aside %}

Images need to have a base setup in order to run properly with Nx Agents. There are two ways to go about setting up your base image.
It's recommended to extend our base image. If you cannot extend our image, manually configure your image with the required steps.

{% tabs %}
{% tabitem label="Extend image (recommended)" %}

**Do not** override the `USER`, `WORKDIR` or `ENTRYPOINT` from the base image.

```yaml
//nx-agent-base-image.dockerfile
FROM us-east1-docker.pkg.dev/nxcloudoperations/nx-cloud-enterprise-public/nx-agents-base-images:ubuntu22.04-node24.14-v1 as base

# Add any steps you need such as installing required software
RUN sudo apt-get install....
RUN sudo chmod ....
```

{% /tabitem %}
{% tabitem label="Manual setup" %}

> It's required to use Ubuntu as the base

```yaml
// nx-agent-base-image.dockerfile
FROM ubuntu:22.04 as base

# Create workflow user
RUN groupadd -g 10001 workflows
RUN useradd -m -u 10000 -g 10001 workflows
RUN mkdir /home/workflows/workspace
RUN mkdir -p /home/workflows/.npm-global/lib /home/workflows/.npm-global/bin
RUN mkdir -p /home/workflows/.nvm
RUN chown -R 10000:10001 /home/workflows
ENV PATH=$PATH:/home/workflows/.npm-global/bin

# Docker
COPY --from=docker:24.0.2 /usr/local/bin /usr/local/bin
COPY --from=docker:24.0.2 /usr/local/libexec /usr/local/libexec

USER workflows

WORKDIR /home/workflows/workspace

ENTRYPOINT [ "/home/workflows/executor-binary/nx-cloud-workflow-executor" ]
```

{% /tabitem %}
{% /tabs %}

## Checklist

1. Image is publicly accessible to the Nx Cloud instance being used.
   - If your image must remain behind a private registry, please contact your DPE to discuss potential solutions.
2. `USER`, `WORKDIR` and `ENTRYPOINT` are not overridden
   - If manually setting they are correctly configured as outlined in the _Manual_ step above.
3. Image is used in a [custom launch template](/docs/reference/nx-cloud/launch-templates#launchtemplatestemplatenameimage) via its fully qualified path

---
<!-- source: https://nx.dev/docs/reference/nx-cloud/custom-steps.md -->
## Creating Custom Steps

While Nx Cloud provides several pre-built steps, you can create custom steps to suit your specific needs. Custom steps are defined by creating a new YAML file.

## Defining a custom step

To create a custom step, follow these steps:

1\. **Create a New YAML File**: Create a new YAML file in your `.nx/workflows` directory (e.g., `custom-step.yaml`)

{% aside type="note" title="Custom step file location" %}
Custom steps do not need to be in the `.nx/workflows` directory. However, they must be available on a public GitHub repository. You have a few options for organizing your custom steps:

- **Same Repository as your Nx Workspace**: Ideal for open-source projects where the Nx workspace is publicly accessible.
- **Create a Dedicated Repository**: Create a separate repository to store a collection of custom steps. This is useful for sharing steps across multiple projects or teams, or if your main Nx workspace is not on GitHub or is private.

{% /aside %}

2\. **Define the Step Template**: Below is an example of a custom step definition:

```yaml
// .nx/workflows/custom-step.yaml
name: 'Custom Step'
description: 'This is a custom step that does XYZ.'
definition:
  using: 'node'
  main: './scripts/custom-script.js'
  post: './scripts/post-custom-script.js'
inputs:
  - name: 'input1'
    description: 'Description for input1'
    default: 'default_value'
    required: true
  - name: 'input2'
    description: 'Description for input2'
    required: false
```

### Explanation of fields

- **name**:
  - The name of the custom step.

- **description**:
  - A description of what the custom step does.

- **definition**:
  - **using**: The runtime environment. Supported values are `node` and `aggregate`.
    - **node**: If `using` is set to `node`, then only `main` and `post` can be used.
    - **aggregate**: If `using` is set to `aggregate`, then only `steps` can be used.
  - **main**: Path to the main script to run (only if `using` is `node`).
  - **post**: Path to the post script to run (only if `using` is `node`).
    - runs before the agent is cleaned up
  - **steps**: A list of sub-steps to be executed (only if `using` is `aggregate`). Steps follow the same definition as [launch templates](/docs/reference/nx-cloud/launch-templates#launch-template-structure).

- **inputs**:
  - **name**: The name of the input.
  - **description**: A description of the input.
  - **default**: Default value for the input.
  - **required**: Whether the input is required.

### Using inputs in scripts

If your custom step has inputs, they can be accessed in scripts or JavaScript files using environment variables. Each input is prefixed with `NX_CLOUD_INPUT_`. For example, if you have an input called `input1`, you can access it in a JavaScript file like this:

```javascript
const input1 = process.env.NX_CLOUD_INPUT_input1;
console.log(`The value of input1 is: ${input1}`);
```

### Using custom steps in launch templates

Once you've defined your custom step, you can use it in your launch templates by referencing the custom step file. Here's an example:

{% aside type="note" title="Custom Step location" %}
When specifying the location for the custom step, you must include a branch or tag (e.g., `main`). Using a direct URL to the repository without a branch or tag will not work.
{% /aside %}

```yaml
// .nx/workflows/agents.yaml
launch-templates:
  custom-template:
    resource-class: 'docker_linux_amd64/medium'
    image: 'ubuntu22.04-node24.14-v1'
    init-steps:
      - name: Custom Step
        uses: 'your-org/your-repo/main/.nx/workflows/custom-steps.yaml'
        env:
          CUSTOM_VAR: 'custom_value'
        inputs:
          input1: 'value1'
          input2: 'value2'
```

{% aside type="note" title="Recommendation on Using Inputs vs. Env" %}
While you can use both `env` and `inputs` to pass values to custom steps, it is recommended to use `inputs` as they offer validation support, whereas `env` does not.
{% /aside %}

### Validating custom steps

Just like launch templates, you should validate your custom steps to ensure they are defined correctly. In your CI pipeline, use the `nx-cloud validate` command with the `--step-file` flag to ensure nobody merges in invalid changes to your step:

```shell
nx-cloud validate --workflow-file=./.nx/workflows/custom-steps.yaml --step-file
```

Ensure your custom steps are committed to your source control repository before running the validation.

By defining and organizing custom steps in this way, you can create highly tailored workflows that meet the specific needs of your projects and CI/CD pipelines.

---
<!-- source: https://nx.dev/docs/reference/nx-cloud/launch-template-examples.md -->
## Launch Template Examples

This page contains common configuration examples for [launch templates](/docs/reference/nx-cloud/launch-templates). For the full reference of available fields, see the [launch templates reference page](/docs/reference/nx-cloud/launch-templates).

## Full example

This is an example of a launch template using all pre-built features:

```yaml
// ./nx/workflows/agents.yaml
# Define common setup steps that can be reused across templates
common-js-init-steps: &common-js-init-steps
  # using a reusable step in an external GitHub repo,
  # this step is provided by Nx Cloud: https://github.com/nrwl/nx-cloud-workflows/tree/main/workflow-steps
  - name: Checkout
    uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/checkout/main.yaml'
  - name: Restore Node Modules Cache
    uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/cache/main.yaml'
    # the cache step requires configuration via env vars
    # https://github.com/nrwl/nx-cloud-workflows/tree/main/workflow-steps/cache#options
    inputs:
      # Include patches directories to ensure cache is busted when patches change
      # If you use a custom patches directory, add it to the key as well
      key: 'package-lock.json|yarn.lock|pnpm-lock.yaml|patches/**|.yarn/patches/**'
      paths: |
        ~/.npm
        # or ~/.cache/yarn
        # or ~/.local/share/pnpm/store
      base-branch: 'main'
  - name: Restore Browser Binary Cache
    uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/cache/main.yaml'
    inputs:
      key: 'package-lock.json|yarn.lock|pnpm-lock.yaml|"browsers"'
      paths: |
        '~/.cache/Cypress'
      base-branch: 'main'
  - name: Install Node Modules
    uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-node-modules/main.yaml'
  - name: Install Browsers (if needed)
    uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-browsers/main.yaml'
    # You can also run a custom script to configure various things on the agent machine
  - name: Run a custom script
    script: |
      git config --global user.email test@test.com
      git config --global user.name "Test Test"
  - name: Define Step Env Var
    # this env var will be available to all future steps using these 'common-init-steps' reusable steps
    # persist env vars between steps by writing to the $NX_CLOUD_ENV file
    script: |
      echo "MY_STEP_ENV=step-env-var" >> $NX_CLOUD_ENV

common-rust-init-steps: &common-rust-init-steps
  - name: Checkout
    uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/checkout/main.yaml'

  # add Rust-specific steps
  - name: Install Rust
    script: |
      curl --proto '=https' --tlsv1.3 https://sh.rustup.rs -sSf | sh -s -- -y
      source "$HOME/.cargo/env"
      rustup toolchain install stable
      # persist cargo bin into PATH
      echo "PATH=$HOME/.cargo/bin:$PATH" >> $NX_CLOUD_ENV

launch-templates:
  # Custom template name, the name is referenced via --distribute-on="3 my-linux-medium-js"
  # You can define as many templates as you need, commonly used to make different sizes or toolchains depending on your workspace needs
  my-linux-medium-js:
    resource-class: 'docker_linux_amd64/medium'
    image: 'ubuntu22.04-node24.14-v1'
    # Define environment variables shared among all steps in this launch template
    env:
      MY_ENV_VAR: shared
    # list out steps to run on the agent before accepting tasks
    # the agent will need a copy of the source code and dependencies installed
    # note we are using yaml anchors to reduce duplication with the below launch-template (they have the same init-steps)
    init-steps: *common-js-init-steps

  # another template which does the same as above, but with a large resource class
  # You're not required to define a template for every resource class, only define what you need!
  my-linux-large-js:
    resource-class: 'docker_linux_amd64/large'
    image: 'ubuntu22.04-node24.14-v1'
    env:
      MY_ENV_VAR: shared
    # note we are using yaml anchors to reduce duplication with the above launch-template (they have the same init-steps)
    init-steps: *common-js-init-steps

  # template that installs rust
  my-linux-rust-large:
    resource-class: 'docker_linux_amd64/large'
    image: 'ubuntu22.04-node24.14-v1'
    init-steps: *common-rust-init-steps
```

These templates can be used by passing the number of agents desired, and the template name via `--distribute-on` when starting your CI run.

```shell
nx start-ci-run --distribute-on="4 my-linux-medium-js"
```

```shell
nx start-ci-run --distribute-on="4 my-linux-large-js"
```

```shell
nx start-ci-run --distribute-on="4 my-linux-large-rust"
```

## Pass environment variables

If you need to send environment variables to agents, you can use the [--with-env-vars](/docs/reference/nx-cloud-cli#withenvvars-nx-agents-only) flag on the `nx start-ci-run` command. You can pass a specific list of environment variables like this:

```shell
nx start-ci-run --distribute-on="8 linux-medium-js" --with-env-vars="VAR1,VAR2"
```

## Pass values between steps

If you need to pass a value from one step to another step, such as assigning the value to an existing or new environment variable. You can write to the `NX_CLOUD_ENV` environment file.

Commonly used for redefining the `PATH` or setting options for tooling.

```yaml
// ./nx/workflows/agents.yaml
launch-templates:
  my-template-name:
    init-steps:
      - name: Set PATH
        script: echo "PATH=$HOME/.cargo/bin:$PATH" >> $NX_CLOUD_ENV
      - name: Check PATH
        script: |
          # now contains $HOME/.cargo/bin
          echo $PATH
          # can invoke cargo directly because it's in the PATH now.
          cargo --version
```

## Private npm registry

{% aside type="caution" title="Protect sensitive values" %}
To prevent any sensitive values from showing up in a `git diff`, we recommend using the `user` level location for the `.npmrc` or `.yarnrc` file.
{% /aside %}

If your project consumes packages from a private registry, you'll have to set up an authentication step in a custom launch template and authenticate like you normally would, usually this is via a `.npmrc` or `.yarnrc` file. You can pass the auth token from your main agent, so it's available to the agent machines.

```yaml
// .nx/workflows/agents.yaml
launch-templates:
  my-linux-medium-js:
    resource-class: 'docker_linux_amd64/medium'
    image: 'ubuntu22.04-node24.14-v1'
    init-steps:
      - name: Checkout
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/checkout/main.yaml'
      - name: Auth to Registry
        script: |
          # we recommend add to the 'user' level npmrc file
          # create .npmrc with @myorg scoped packages pointing to GH npm registry
          # or yarn config set -l user if you use yarn
          npm config set -L user "@myorg:registry" "https://npm.pkg.github.com"
          npm config set -L user "//npm.pkg.github.com/:_authToken" "${SOME_AUTH_TOKEN}"
      - name: Install Node Modules
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-node-modules/main.yaml'
```

Pass `SOME_AUTH_TOKEN` via `--with-env-vars`

```shell
# this assumes SOME_AUTH_TOKEN is already defined on the main agent
nx start-ci-run --distribute-on="5 my-linux-medium-js" --with-env-vars="SOME_AUTH_TOKEN"
```

## Custom node version

Nx Agents come with node LTS installed. If you want to use a different version, you can add a step to install the desired node version.

{% tabs %}
{% tabitem label="mise" %}

You can use [mise](#install-tools-with-mise) to manage node versions alongside other toolchains.

```yaml
// .nx/workflows/agents.yaml
launch-templates:
  node-21:
    resource-class: 'docker_linux_amd64/medium'
    image: 'ubuntu22.04-node24.14-v1'
    init-steps:
      - name: Checkout
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/checkout/main.yaml'
      - name: Install mise
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-mise/main.yaml'
        inputs:
          # you can also define a mise.toml in your repo instead of inline tools
          tools: |
            node=21
      - name: Install Node Modules
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-node-modules/main.yaml'
```

{% /tabitem %}
{% tabitem label="nvm" %}

Nx Cloud provides a [pre-built step to install a custom node version](https://github.com/nrwl/nx-cloud-workflows/tree/main/workflow-steps/install-node) within your workflow. This step is available as of `v4` of the workflow steps and requires the minimum image version to be `ubuntu22.04-node20.11-v9` or later.

```yaml
// .nx/workflows/agents.yaml
launch-templates:
  node-21:
    resource-class: 'docker_linux_amd64/medium'
    # note the image version of v9,
    # earlier versions of the base image will not work
    image: 'ubuntu22.04-node24.14-v1'
    init-steps:
      - name: Checkout
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/checkout/main.yaml'
      - name: Install Node
        # note the step is only released as of v4 of the workflow steps
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-node/main.yaml'
        inputs:
          # can omit value if a '.nvmrc' file is within the root of the repo
          node_version: '21'
```

{% /tabitem %}
{% tabitem label="Manual Installation" %}

Here is a simplified launch template manually installing [nvm](https://github.com/nvm-sh/nvm) to manage different node version.
Feel free to use your preferred tool, other popular options are [volta](https://volta.sh/) or [fnm](https://github.com/Schniz/fnm).
The steps follow the general pattern of:

1. install tool
1. install node with tool
1. persist any environment variable changes for future steps

```yaml
// .nx/workflows/agents.yaml
launch-templates:
  node-21:
    resource-class: 'docker_linux_amd64/medium'
    image: 'ubuntu22.04-node24.14-v1'
    init-steps:
      - name: Checkout
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/checkout/main.yaml'
      - name: Install nvm
        script: |
          # run nvm install script
          curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
          # source the updated profile to get the nvm command available
          source ~/.profile
          # install the needed version of node via nvm
          nvm install 21.7.3
          # echo the current path (which now includes the nvm-provided version of node) to NX_CLOUD_ENV
          echo "PATH=$PATH" >> $NX_CLOUD_ENV
      - name: Print node version
        # confirm that the node version has changed
        script: node -v
      - name: Install Node Modules
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-node-modules/main.yaml'
      # Continue setup steps as needed
```

{% /tabitem %}
{% /tabs %}

## Specific package manager version

Nx Agents have [corepack enabled](https://nodejs.org/api/corepack.html#corepack) by default, allowing you to define the yarn or pnpm version via the `package.json`.

```json
// package.json
{
  "packageManager": "yarn@4.1.1"
}
```

{% aside type="note" %}
**Supported Package Managers**

Currently, corepack [only supports yarn or pnpm](https://nodejs.org/api/corepack.html#supported-package-managers) as package managers. If you need to use a specific npm version, you will need to create a custom launch template and install the specific npm version, i.e. `npm install -g npm@<version>`
{% /aside %}

## Installing packages

You can use `apt` to install popular linux packages. This is helpful in streamlining setting up various toolchains needed for your workspace.

For example, you can install the [GitHub CLI](https://cli.github.com/) on the agents if needed.

```yaml
// ./nx/workflows/agents.yaml
launch-templates:
  my-linux-medium-js:
    resource-class: 'docker_linux_amd64/medium'
    image: 'ubuntu22.04-node24.14-v1'
    init-steps:
      - name: Install Extras
        script: |
          sudo apt install gh unzip zip -y
```

{% aside type="note" %}
**Installing without apt**

If you're trying to install a package that isn't available on `apt`, check that packages install steps for Debian base linux. Usually there are a handful of installation scripts that can be used [similar to `nvm`](#custom-node-version)
{% /aside %}

## Install tools with mise

[mise](https://mise.jdx.dev/) is a polyglot version manager that can install and manage multiple tools and runtimes (node, Rust, Python, Go, and more) in a single step. Nx Cloud provides a [pre-built step](https://github.com/nrwl/nx-cloud-workflows/tree/main/workflow-steps/install-mise) to install mise and configure tools on your agents.

{% tabs %}
{% tabitem label="With mise.toml" %}

If your repo already has a `mise.toml` file, mise automatically installs the tools defined there.

```yaml
// .nx/workflows/agents.yaml
launch-templates:
  my-linux-medium-js:
    resource-class: 'docker_linux_amd64/medium'
    image: 'ubuntu22.04-node24.14-v1'
    init-steps:
      - name: Checkout
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/checkout/main.yaml'
      - name: Install mise
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-mise/main.yaml'
      - name: Install Node Modules
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-node-modules/main.yaml'
```

{% /tabitem %}
{% tabitem label="With inline tools" %}

You can define tools inline using the `tools` input. Each line specifies a tool and version separated by `=`, `@`, or a space.

```yaml
// .nx/workflows/agents.yaml
launch-templates:
  my-linux-medium-js:
    resource-class: 'docker_linux_amd64/medium'
    image: 'ubuntu22.04-node24.14-v1'
    init-steps:
      - name: Checkout
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/checkout/main.yaml'
      - name: Install mise
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-mise/main.yaml'
        inputs:
          tools: |
            node=22
            rust=1.90
            python=3.12
      - name: Install Node Modules
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-node-modules/main.yaml'
```

{% aside type="caution" %}
Defining tools inline overrides any `mise.toml` in your repo. This can cause differences between CI and local environments. Use inline tools only when your repo does not have a `mise.toml`.
{% /aside %}

{% /tabitem %}
{% /tabs %}

## AWS CLI

First, define the environment variables on your main agent, where you call [`nx start-ci-run`](/docs/reference/nx-cloud-cli#npx-nxcloud-startcirun). Pass the same environment variables to your agents via the [`--with-env-vars` flag](/docs/reference/nx-cloud-cli#withenvvars-nx-agents-only).

Minimally the `AWS_REGION` (or `AWS_DEFAULT_REGION`), `AWS_ACCESS_KEY_ID`, and `AWS_SECRET_ACCESS_KEY` environment variables are required.

{% aside type="tip" %}
**OIDC Provider**

If using an [OIDC provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html), e.g. the [AWS GitHub Action recommended setup](https://github.com/aws-actions/configure-aws-credentials?tab=readme-ov-file#using-this-action), then the environment variables are automatically configured for you after authentication to AWS. Since the credentials created for with OIDC provider flow are temporary, you'll need to pass the `AWS_SESSION_TOKEN` environment variable to your agents.

{% /aside %}

{% tabs %}
{% tabitem label="Pre-Built Step" %}

Using the pre-built step simplifies and provides debugging checks to make sure the AWS CLI is properly authenticated to AWS before continuing. The step is recommended for most use cases.

```yaml {% meta="{6-8}" %}
// ./nx/workflows/agents.yaml
launch-templates:
  my-linux-medium-js:
    resource-class: 'docker_linux_amd64/medium'
    image: 'ubuntu22.04-node24.14-v1'
    init-steps:
      - name: Install AWS CLI
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-aws-cli/main.yaml'
        # no additional inputs required, as all configuration is via environment variables via --with-env-vars
```

{% /tabitem %}
{% tabitem label="Manual Installation" %}

Manual installation follows [installing the AWS CLI using the official directions](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). In order to decompress the installation archive, you'll need to install the `unzip` package in your step.
Manual installation is helpful if a custom installation setup is required.
It is helpful to run `aws sts get-caller-identity` command to make sure you're properly authenticated to AWS before proceeding

```yaml {% meta="{6-20}" %}
// ./nx/workflows/agents.yaml
launch-templates:
  my-linux-medium-js:
    resource-class: 'docker_linux_amd64/medium'
    image: 'ubuntu22.04-node24.14-v1'
    init-steps:
      # step assumes you've passed all required AWS_* environment variables from the main agent via --with-env-vars
      - name: Install AWS CLI
        script: |
          # unzip is required to unzip the AWS CLI installer
          sudo apt install gh unzip -y
          curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
          unzip awscliv2.zip
          # run installer, default location is already in the PATH
          # if installing in a custom location,
          # then update the $PATH like `PATH=$PATH:[extra-path-items] >> $NX_CLOUD_ENV`
          sudo ./aws/install
          # print AWS CLI version to verify command is avaiable
          aws --version
          # verify credentials to AWS is working
          aws sts get-caller-identity
```

{% /tabitem %}
{% /tabs %}

## Dynamic changesets

NxCloud can calculate how big your pull request is based on how many projects in your workspace it affects. You can then configure Nx Agents to dynamically use a different number of agents based on your changeset size.

Here we define a `small`, `medium` and `large` distribution strategy:

```yaml
// .nx/workflows/dynamic-changesets.yaml
distribute-on:
  small-changeset: 3 linux-medium-js
  medium-changeset: 8 linux-medium-js
  large-changeset: 12 linux-medium-js
```

Then you can pass the path to the file to the `--distribute-on` parameter.

```shell
nx start-ci-run --distribute-on=".nx/workflows/dynamic-changesets.yaml"
```

## Debugging

You can add steps to your template which print information about your workspace, toolchains, or any other needs.
Below are some common steps people use for debugging such as running nx commands, printing file contents and/or listing directory contents.

{% aside type="caution" %}
**Environment Variables**

Exercise caution when printing out environment variables, they will be shown in plain text.
{% /aside %}

```yaml
// .nx/workflows/agents.yaml
launch-templates:
  my-linux-medium-js:
    resource-class: 'docker_linux_amd64/medium'
    image: 'ubuntu22.04-node24.14-v1'
    env:
      # enable verbose logging for all steps
      NX_VERBOSE_LOGGING: true
    init-steps:
      - name: 'Debug: Print Nx Report'
        script: |
          nx report
      - name: 'Debug: List Directory Contents'
        script: |
          echo $HOME
          ls -la $HOME
          output_dir=$HOME/dist
          # if output directory exists list it's contents
          if [ -d output_dir ]; then
            ls -la $output_dir
          else
            echo "$output_dir does not exist"
          fi
      - name: 'Debug: Show File Contents'
        script: |
          cat $HOME/.profile
      - name: 'Debug: Check For Checkout Files'
        script: |
          git diff
      - name: 'Debug: Print Versions'
        script: |
          # note if you use yarn and try to run pnpm, corepack might throw an error at you
          # saying you're using the wrong package manager, in that case just remove the usage of pnpm
          echo "Versions:"
          echo "Node: $(node -v)"
          echo "NPM: $(npm -v)"
          echo "Yarn: $(yarn -v)"
          echo "PNPM: $(pnpm -v)"
          echo "Golang: $(go version)"
          echo "Java: $(javac --version)"
          # add any other toolchain you want
      - name: 'Debug: Print env'
        script: |
          # !!! DO NOT RUN THIS IF YOU HAVE PASSWORD/ACCESS TOKENS IN YOUR ENV VARS !!!
          # this will print your env as plain text values to the terminal
          env
          # This is a safer approach to prevent leaking tokens/passwords
          echo "SOME_VALUE: $SOME_VALUE"
```

## Nx workspace in a subdirectory

If your Nx workspace is in a subdirectory of your repository, set `NX_WORKING_DIRECTORY` in your launch template:

```yaml
launch-templates:
  my-template:
    resource-class: 'docker_linux_amd64/medium'
    image: 'ubuntu22.04-node24.14-v1'
    env:
      NX_WORKING_DIRECTORY: './client'
    init-steps:
      # ...
```

The `install-node-modules` step automatically respects this variable (but can be overridden at the step level if your lockfile is hosted at the root). For other steps, set the working directory manually.

---
<!-- source: https://nx.dev/docs/reference/nx-cloud/launch-templates.md -->
## Launch Templates

A launch template defines the setup steps Nx Agents will run before running tasks. A custom launch template isn't required to use Nx Agents.
Nx Cloud provides several pre-built launch templates for common use-cases. You can view available templates in the [`nx-cloud-workflows` repository](https://github.com/nrwl/nx-cloud-workflows/tree/main/launch-templates).

{% github_repository url="https://github.com/nrwl/nx-cloud-workflows/tree/main/launch-templates" title="Pre-Built Launch Templates" /%}

## Getting started with custom launch templates

The easiest way to create a new custom launch template is to modify one of the pre-built ones. To do that, create a file in the
`.nx/workflows` folder and copy one of the [pre-built templates](https://github.com/nrwl/nx-cloud-workflows/blob/main/launch-templates/linux.yaml). You can name the file any way you want (e.g., `agents.yaml`) and customize the steps as needed.

## Launch template structure

### `launch-templates`

A `map` of launch template configurations. This value is required.

```yaml
// .nx/workflows/agents.yaml
launch-templates:
```

### `launch-templates.<template-name>`

The name of your custom launch template. This name is used via `--distribute-on="<# of agents> <template-name>"` when starting the ci run. Supports one to many uniquely named launch templates.
Multiple launch templates can be useful for setting up different toolchains (rust, java, node versions) or resources classes for your workspace needs.

```yaml
// .nx/workflows/agents.yaml
launch-templates:
  template-one:
  template-two:
```

```shell
nx start-ci-run --distribute-on="3 template-one"
```

### `launch-templates.<template-name>.resource-class`

A launch template's `resource-class` defines the memory and vCPUs available to each agent machine.

```yaml
// .nx/workflows/agents.yaml
launch-templates:
  template-one:
    resource-class: 'docker_linux_amd64/medium'
```

The following resource classes are available:

- `docker_linux_amd64/small`
- `docker_linux_amd64/medium`
- `docker_linux_amd64/medium+`
- `docker_linux_amd64/large`
- `docker_linux_amd64/large+`
- `docker_linux_amd64/extra_large`
- `docker_linux_amd64/extra_large+`
- `docker_linux_arm64/medium`
- `docker_linux_arm64/large`
- `docker_linux_arm64/extra_large`
- `windows/medium`

See their detailed description and pricing in the [credits pricing reference](/docs/reference/nx-cloud/credits-pricing).

### `launch-templates.<template-name>.image`

A launch template's `image` defines the available base software for the agent machine.

```yaml
// .nx/workflows/agents.yaml
launch-templates:
  template-one:
    image: 'ubuntu22.04-node24.14-v1'
```

Nx Cloud provides the following images:

> Changes added in previous images are included in newer images unless otherwise denoted
> Images also have [go 1.22](https://go.dev/) installed

**Ubuntu:**

- `ubuntu22.04-node20.11-v5`: added elevated permission access via `sudo`
- `ubuntu22.04-node20.11-v6`: `corepack` enabled by default with global pnpm v8, yarn v1, npm v10. See how to install a [specific package manager version](/docs/reference/nx-cloud/launch-template-examples#specific-package-manager-version)
- `ubuntu22.04-node20.11-v7`: added Java 17
- `ubuntu22.04-node20.11-v8`: added [nvm](https://github.com/nvm-sh/nvm)
- `ubuntu22.04-node20.11-v9`: prevented corepack from auto-updating `package.json` and removed corepack enable from sudo user
- `ubuntu22.04-node20.11-v10`: added Docker support (Docker 24.0.2 binaries)
- `ubuntu22.04-node20.11-v11`: bumped default `pnpm` from v8 to v9
- `ubuntu22.04-node20.11-v12`: updated Playwright system dependencies
- `ubuntu22.04-node20.11-dockerd-v2`: Docker daemon via `get-docker.sh` script with pnpm bumped to v9
- `ubuntu22.04-node20.11-dockerd-v3`: updated Playwright system dependencies
- `ubuntu22.04-node20.19-v1`: upgrade default node version to Node 20.19.1
- `ubuntu22.04-node20.19-v2`: updated Playwright system dependencies
- `ubuntu22.04-node20.19-v3`: upgraded Docker from 24.0.2 to 28.3.1
- `ubuntu22.04-node22.22-v1`: upgrade default node version to Node 22.22.2
- `ubuntu22.04-node24.14-v1`: upgrade default node version to Node 24.14.1

**Windows:**

- `windows-2022`

> Note: Windows-based images can only run on Windows-based [resource classes](#launch-templatestemplate-nameresourceclass).

Enterprise accounts [can use custom images](/docs/reference/nx-cloud/custom-images).

### `launch-templates.<template-name>.env`

A launch template's `env` defines a `map` of environment variable names and values to be available within **all** steps of the specific launch template.

```yaml
// .nx/workflows/agents.yaml
launch-templates:
  template-one:
    env:
      MY_ENV_VAR: 'my-var-value'
```

### `launch-templates.<template-name>.init-steps`

A launch template's `init-steps` defines the series of steps to perform before an Nx Agent runs. Without a defined `init-steps` the Nx Agent is unable to process any tasks.

Typical `init-steps` perform actions such as checking out your workspace source code and installing any necessary dependencies. Any extra setup your workspace needs to run should be defined as an `init-step`. Once all steps run successfully, the agent machine will inform Nx Cloud that it is ready to accept tasks.

```yaml
// .nx/workflows/agents.yaml
launch-templates:
  template-one:
    init-steps:
```

### `launch-templates.<template-name>.init-steps[*].name`

An init-step's `name` is the label that will be reflected in the Nx Cloud UI. `name` can be used in conjunction with [`uses`](#launch-templatestemplate-nameinit-stepsuses) and [`script`](#launch-templatestemplate-nameinit-stepsscript)

```yaml
// .nx/workflows/agents.yaml
launch-templates:
  template-one:
    init-steps:
      - name: 'My Helpful Step Name'
```

### `launch-templates.<template-name>.init-steps[*].uses`

When defined, specifies an existing step file to be used. **Cannot be used when `script` is also defined**

You can find the [list of Nx Cloud reusable steps here](https://github.com/nrwl/nx-cloud-workflows/tree/main/workflow-steps). If you cannot find a reusable step that suits your needs, [you can create your own custom steps](/docs/reference/nx-cloud/custom-steps).

```yaml
// .nx/workflows/agents.yaml
launch-templates:
  template-one:
    init-steps:
      - uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/checkout/main.yaml'
      - name: 'Install Node Modules'
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/install-node-modules/main.yaml'
```

### `launch-templates.<template-name>.init-steps[*].script`

When defined, allows an inline script to be run. **Cannot be used when `uses` is also defined**

```yaml
// .nx/workflows/agents.yaml
launch-templates:
  template-one:
    init-steps:
      - name: 'Print Node Version and PATH'
        script: |
          node -v
          echo $PATH
```

### `launch-templates.<template-name>.init-steps[*].env`

An init-step's `env` is similar to the [`launch-template.<template-name>.env`](#launch-templatestemplate-nameenv), except the environment variable `map` is **scoped for the current step only**.

```yaml
// .nx/workflows/agents.yaml
launch-templates:
  template-one:
    init-steps:
      - name: 'Print Env'
        env:
          MY_STEP_ENV: 'step-env-var'
        script: |
          echo $MY_STEP_ENV # prints "step-env-var"
```

### `launch-templates.<template-name>.init-steps[*].inputs`

An init-step's `inputs` is defined by the step file in the [`launch-template.<template-name>.init-steps[*].uses`](#launch-templatestemplate-nameinit-stepsuses) property. Refer to the step file's documentation for specific inputs.

[Validation](#validating-launch-templates) can also be done to validate the step against the step file's defined inputs

```yaml
// .nx/workflows/agents.yaml
launch-templates:
  template-one:
    init-steps:
      - name: Restore Node Modules Cache
        uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/cache/main.yaml'
        inputs:
          # Include patches directories to ensure cache is busted when patches change
          key: 'package-lock.json|yarn.lock|pnpm-lock.yaml|patches/**|.yarn/patches/**|pnpm-patches/**'
          paths: |
            ~/.npm
            # or ~/.cache/yarn
            # or ~/.local/share/pnpm/store
          base-branch: 'main'
```

### `launch-templates.<template-name>.group-name`

You can define "step groups" that run in parallel. This can be useful for taking better advantage of the available CPUs of your chosen resource class.
In the example below, we can run NPM Install and install the Rust dependencies in parallel, because they do not depend on each other and they write to different places on the filesystem.
Running them in parallel can reduce agent startup time by up to 2 minutes, which can add up to a lot of compute time savings over the month.

⚠️ Tips for using parallel steps:

- don't assume everything can be run in parallel
  - you'll notice below we had to run `playwright install` after the parallel group, as it was likely writing to the same locations and fighting for similar resources to `npm install`
  - experiment with different parallel groups and measure startup times until you land on the most optimal config for your use-case
- write to PATH once
  - multiple parallel processes can overwrite each other's changes if they write to the same `>> $NX_CLOUD_ENV` location
  - below, we only update the PATH variable once at the end `echo "PATH=$CARGO_PATH:$POETRY_PATH:$PATH" >> $NX_CLOUD_ENV`

```yaml
// .nx/workflows/agents.yaml
launch-templates:
  template-one:
    init-steps:
      - group-name: Install Dependencies
        parallel: true
        # all the below steps will start at the same time and run in parallel
        steps:
          - name: Install Rust
            script: |
              curl --proto '=https' --tlsv1.3 https://sh.rustup.rs -sSf | sh -s -- -y
              source "~/workspace/.cargo/env"
              # we write the CARGO_PATH now so that it can be set in the "Start Services" step below
              echo "CARGO_PATH=~/workspace/.cargo/bin" >> $NX_CLOUD_ENV
              rustc --version
              rustup target add wasm32-wasip1-threads
              cargo fetch
              cargo check --locked
          - name: NPM Install
            uses: 'nrwl/nx-cloud-workflows/main/workflow-steps/install-node-modules/main.yaml'
          - name: Install Poetry
            script: |
              curl -sSL https://install.python-poetry.org | python3 -
              # we write the POETRY_PATH now so that it can be set in the "Start Services" step below
              export POETRY_PATH="/home/workflows/.local/bin"
              export PATH="$POETRY_PATH:$PATH"
              echo "POETRY_PATH=$POETRY_PATH" >> $NX_CLOUD_ENV
              poetry --version
              poetry install
          - name: Install Localstack
            script: |
              curl --output localstack-cli-3.7.0-linux-amd64-onefile.tar.gz --location https://github.com/localstack/localstack-cli/releases/download/v3.7.0/localstack-cli-3.7.0-linux-amd64-onefile.tar.gz
              sudo tar xvzf localstack-cli-3.7.0-linux-*-onefile.tar.gz -C /usr/local/bin
      # because both playwright and "npm install" use NPM and write to a lot of the same places on the filesystem, it would be slower to run them both in parallel
      # so we run playwright after the parallel group above
      - name: Install Playwright
        script: npx playwright install --with-deps
      - name: Start services
        script: |
          # we create the PATH here
          echo "PATH=$CARGO_PATH:$POETRY_PATH:$PATH" >> $NX_CLOUD_ENV
          npm run start-docker-services
```

We can also group steps and run them serially. This is actually the default behaviour when you don't set `parallel: true` for a group.

This can be useful if we have a set of quick enough steps, such as restoring from cache, where we don't need to optimise for speed, and instead we just want them
grouped together logically. The below cache steps will also be collapsed together in the Agents UI, making the config look cleaner:

```yaml
// ./nx/workflows/agents.yaml
- group-name: Restore Cache
  steps:
    - name: Restore Node Modules Cache
      uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/cache/main.yaml'
      inputs:
        # Include patches directories to ensure cache is busted when patches change
        key: 'package-lock.json|patches/**|.yarn/patches/**|pnpm-patches/**'
        paths: |
          ~/.npm
        base-branch: 'main'
    - name: Restore Browser Binary Cache
      uses: 'nrwl/nx-cloud-workflows/v5/workflow-steps/cache/main.yaml'
      inputs:
        # Include patches directories to ensure cache is busted when patches change
        key: 'package-lock.json|patches/**|.yarn/patches/**|pnpm-patches/**|"browsers"'
        paths: |
          '~/.cache/Cypress'
        base-branch: 'main'
```

## Validating launch templates

{% aside type="note" %}
**Commit before Validation**

Before Nx Cloud can validate your custom templates, you must first commit any changes to these templates to your source control repository. Running the validation command from a CI is the recommended approach.
{% /aside %}
After creating your custom launch template, it's recommended to validate it. This ensures that all necessary fields
within the launch template and all respective inputs within each step are appropriately defined.

To do this, run the `nx-cloud validate` command, with the path to the launch template:

```shell
nx-cloud validate --workflow-file=./.nx/workflows/agents.yaml
```

For examples of common configurations such as private registries, custom node versions, AWS CLI setup, and more, see the [launch template examples](/docs/reference/nx-cloud/launch-template-examples).

---
<!-- source: https://nx.dev/docs/reference/nx-cloud/release-notes.md -->
## Enterprise Release Notes

### 2026.01

##### Self-healing CI

- Feat: Azure DevOps support for Self-Healing CI, bringing it to feature parity with GitHub and GitLab for automated fix proposals
  - Automated fix application: Nx Cloud can now automatically create commits on Azure DevOps pull requests to apply AI-generated fixes
  - Interactive PR comments: Self-healing proposals appear as comments on Azure DevOps PRs with actions to apply, reject, or revert fixes
- Feat: Self-Healing CI fixes are now generated for draft PRs/MRs by default (configurable via workspace settings)
- Feat: Self-Healing CI now supports Bitbucket workspaces
  - Enable Self-Healing CI for PRs
  - Configure PR comment notifications
  - Set up automatic flaky task reruns
  - Define eligible task patterns and auto-apply rules
- Feat: Enable Self-Healing CI directly from the Nx Cloud UI with a single-click setup wizard
  - Automatically detects your CI provider (GitHub Actions, GitLab CI, or Azure DevOps)
  - Adds the `nx fix-ci` step to your CI configuration
  - Creates a pull request with the changes for you to review and merge
- Feat: Add support for triggering a CI rerun when Self-Healing CI determines that failures are caused by environment issues
- Feat: Allow users to configure branch patterns to ignore for AI fix generation
- Feat: Configure Self-Healing CI functionality, including task filtering and auto-apply fixes logic, from the Self-Healing settings tab under Workspace settings
- Feat: Display AI provider status banner on Self-Healing page when Claude API is experiencing issues
- Feat: Self-healing now uses affected project information to prevent misclassifying persistent failures as flaky tasks
- Feat: Updated Self-Healing CI UI within the CIPE screen for a richer, more detailed experience
  - Improved messaging and support to show why a fix was not started in the cloud UI
- Feat: Add `--no-interactive` flag to `nx-cloud apply-locally` command to improve compatibility with AI agents
- Fix: Self-Healing CI now uses the workspace's package manager (pnpm, yarn, bun) instead of hardcoded npx for task verification
- Fix: Update classification prompts to determine environmental vs flaky tasks better
- Fix: Update git operations during Self-Healing CI to be more resilient whenever there are additional commits, or branch becomes outdated
- Fix: Self-healing now correctly resolves the merge commit SHA when run as part of a GitLab Merged Results Pipeline
- Fix: Limit the amount of consecutive flaky reruns that Self-Healing CI will trigger
- Fix: In cases where auto-apply does not proceed (e.g., Nx Cloud was the previous CIPE author), a consistent message is now shown across the PR/MR review comment and the Nx Cloud UI
- Fix: Improved clarity of messages when Self-Healing CI times out or is cancelled part way through
- Fix: For suggested fix diffs consisting only of a trailing newline removal, the full diff now correctly renders in the UI
- Fix: Fixed an issue which prevented auto application of fix suggestions for configured tasks
- Fix: Ensure Self-Healing CI accurately prints information about the tasks that were run for verification
- Fix: Fixes an issue where Self-Healing CI could fail to fetch git SHAs when GitHub App tokens expire during long-running CI jobs
- Fix: No longer adds the warning about an in-flight CIPE to review comments for fixes which have already had action taken on them
- Fix: Avoid overly verbose explanations inline in review comments when issues are classified as `environment_state`

##### CI pipeline executions

- Feat: AI fix status badges and filtering for CI Pipeline Executions
  - Badges show: Generating Fix, Fix Ready, and Fix Applied
  - Filter the CIPE list by fix status (Fix Ready, Fix Applied, or Fix Rejected)
  - Click on any fix badge to navigate directly to the self-healing page
- Feat: New Configuration tab on the CI Pipeline Execution page to help verify settings and debug issues
  - Shows: explicit completion, VCS context, cache status, distribution setup, auto-stop conditions, and self-healing CI settings

  ![CIPE configuration view](../../../../assets/nx-cloud/cipe-configuration-view.png)

- Feat: Display CIPE credit usage summary under CIPE Analysis area including compute credits and AI credits
- Feat: Branch filter allows fuzzy matching by opt-in via a toggle
- Feat: Run tasks list filter supports sort by retries
- Fix: Add loading feedback when navigating between different CIPEs
- Fix: Author filter now allows searching by text input with enter
- Fix: Adjust cache status multi-select filter in Tasks list to use logical OR instead of AND
- Fix: Defer loading of the run list with a loading animation
- Fix: When using `nx affected:test` rather than `nx affected -t test`, the `--stop-agents-after` condition is now correctly matched

##### Analytics & reporting

- Feat: Workspace analytics now features a collapsible sidebar navigation

  ![Analytics sidebar layout](../../../../assets/nx-cloud/analytics-sidebar-layout.avif)
  - Range selectors are now in a dropdown

    ![New range selector dropdown](../../../../assets/nx-cloud/analytics-range-selector.avif)

  - Custom range utilizes a date-range calendar

    ![New date range picker](../../../../assets/nx-cloud/analytics-date-range-picker.avif)

- Feat: Remove non-cacheable tasks from flaky task analytics
- Feat: Added ability to filter by status in "recent executions" within flaky task analytics drawer
- Fix: Fixed issue that was errantly filtering out too much data from the flaky task view
- Fix: Improved performance of flaky task analytics queries
- Fix: Average task duration in flaky tasks analytics drawer is now fixed to 2 decimal places
- Fix: Do not show AI Credits if it's 0
- Fix: Fix enterprise usage periods for mid-month license starts — usage data now correctly starts from the actual license start date

##### Onboarding & workspace setup

- Feat: New `/welcome` page to help orient new users to Nx Cloud

  ![Welcome splash page](../../../../assets/nx-cloud/welcome-splash.avif)

- Feat: New landing page for connecting workspaces, allowing users to navigate to the right flow from their repo URL
- Feat: When creating a workspace, you will now see a description of a template before you clone it, including technologies used and Nx features demoed

  ![Template info sheet](../../../../assets/nx-cloud/template-info.avif)

- Feat: Allow members of GitHub organizations to connect existing repos to Nx Cloud
- Feat: Made the "default branch" workspace setting available for all plans
- Feat: Quickly configure recommended access control settings from the "Access control" workspace settings page
- Feat: Updated the "Connect your GitHub/GitLab user account" prompt with improved styling and doc links
- Feat: Add a prompt to remind users to set up notification settings
- Fix: Minor style and description adjustments for the manual onboarding flow
- Fix: Manual onboarding flow shows `NX_CLOUD_API` variable for instances other than Managed US
- Fix: The GitHub integration configuration view now allows authenticating through a Personal Access Token or by connecting your GitHub user account
- Fix: Fix onboarding redirect for users without their GitHub account connected

##### Developer experience

- Feat: Add a "Jump to top" button to agent and task logs
- Feat: Add tip to pull request message to run `generate ci-workflow`
- Feat: Refreshed application error views with more friendly and helpful error messages and illustrations
- Feat: Updated the permission error illustration
- Fix: A reasonable fallback image will be shown when a user avatar cannot be rendered
- Fix: Agent utilization visualization correctly visualizes agent restarts
- Fix: Compare tasks diff view correctly displays `.` in paths (applies to new hash details data)
- Fix: Fixed npm dependency hashing in the Compare Tasks view to include package names
- Fix: Updated a few outdated links to the docs

##### Workspace data & caching

- Feat: Fine-grained control over workspace data caching
  - `NX_CLOUD_SKIP_WORKSPACE_DATA_CACHE_UPLOAD` — skip the upload step
  - `NX_CLOUD_SKIP_WORKSPACE_DATA_CACHE_DOWNLOAD` — skip the download step
  - Existing `NX_CLOUD_SKIP_WORKSPACE_DATA_CACHE=true` takes precedence and skips both actions

##### Task distribution & hooks

- Fix: Resolves an issue where 'target group' name metadata was only persisted on DTE tasks that had been retried, causing inconsistent viewing on Task Analytics and Time Saved screens
- Fix: Post task execution hook no longer errors when distributed tasks are skipped due to upstream dependency failures
- Fix: Unified task timing data between DTE and local execution modes when using the post task execution hook (startTime and endTime fields now attached directly to `context.TaskResult.task`)
- Fix: Fixed a bug where a distributed task execution could slow or hang when processing a completed graph
- Fix: Fix non-Nx Agents detection for resource usage metrics upload prompt

### 2025.10

##### Self-healing CI / AI fixes

- See [self-healing CI guide](/docs/guides/nx-cloud/enable-ai-features#self-healing-ci-for-enterprise-on-prem-installations) for enablement steps.

- Feat: Automatically detect and fix failing CI tasks with AI-generated solutions
- Feat: New `nx-cloud self-heal apply-locally` command to test AI fixes before applying them in CI
- Feat: Revert previously applied AI fixes or automatically apply verified ones
- Feat: GitHub review comments now surface suggested AI-generated fixes
- Feat: Improved verification flow, prompt wording, and commit awareness to increase fix quality

##### Graph & visualization

- Feat: Workspace graph now surfaces implicit dependencies and Nx version data
- Feat: New circular dependency analysis view
- Feat: Graph toolbar persists state and adds refined controls
- Feat: Edge interactions open context menus with additional details

##### Analytics & reporting

- Feat: Time to Green (TTG) reports compare hypothetical versus observed time savings
- Feat: Context switch tracking chart highlights time saved by reducing interruptions

##### Custom workflows

- Feat: Configure working directories per workflow step
- Feat: Apply environment variables across custom workflows
- Feat: Improved launch template management UI

##### Onboarding

- Feat: Revamped end-to-end UI-only onboarding flow for GitHub workspaces
  - For this to work, please enable the "Repository Administration Write" permission in your GitHub, to allow NxCloud to create new repositories

##### Enterprise features

- Feat: SCIM support for Okta, PingIdentity and Azure AD

##### Conformance

- Feat: Better commands and validation when publishing conformance rules
- Feat: Improved GitLab section mapping to owners files

##### Developer experience

- Feat: Better reconciliation and visibility for restarted agents (view which tasks caused an agent to restart and previous logs for restarted agents)
- Feat: Comprehensive dark mode refinements across the application

##### Deployment

- Chore: Released Helm chart `1.0.0` for Nx Cloud
  - Review the [migration guide](https://github.com/nrwl/nx-cloud-helm/blob/main/charts/nx-cloud/MIGRATION.md) before upgrading

### 2025.07.7

- Fix: Resolve zod dependency issues caused by Docker images being built without package-lock file
- Fix: Normalize S3 bucket configuration to support assumedRole authentication for workspace data and conformance rule buckets
- Feat: CIPE summary table updated to display CIPE link outside the table for improved readability

### 2025.07.4 - 2025.07.6

- Note: These versions had issues and should be skipped. Please use 2025.07.7 or later.

### 2025.07.3

- Fix: use short link when generating DTE summary URLs for CI Pipeline Executions

### 2025.07.1

- Fix: auth redirect loop when using admin login
- Fix: improvement to the flaky task retry mechanism
- Fix: enable run hooks on DTE

### 2025.07

##### Breaking change

This upgrade includes a breaking change to the `nx-cloud` cluster: instead of a message queue, the `nx-api` pod needs a valid Valkey (Redis) connection string.

1. Install Valkey:
   1. You can either use the Bitnami chart: https://github.com/bitnami/charts/tree/main/bitnami/valkey
   2. Or for a simpler deployment, you can use the Valkey docker image directly: https://hub.docker.com/r/valkey/valkey/
   3. Or you can install it as a system service: https://valkey.io/topics/installation/
2. Upgrade to the latest Helm chart `0.16.3`
3. Apply the following values

```yaml
enableMessageQueue: false

nxApi:
  # add these env vars to the nx-api
  deployment:
    env:
      - name: VALKEY_CLIENT_PROVIDER
        value: 'redisson'
      - name: VALKEY_PASSWORD
        valueFrom:
          # remember to apply this secret to your cluster
          secretKeyRef:
            name: valkey-secrets
            key: VALKEY_PASSWORD
      - name: VALKEY_PORT
        value: '6379'
      - name: VALKEY_PRIMARY_ADDRESS
        value: 'valkey'
      - name: VALKEY_USE_SENTINEL
        value: 'false'
      - name: VALKEY_USERNAME
        value: 'default'
      - name: NX_CLOUD_CONFORMANCE_RULES_BUCKET
        value:
          local-cluster-file-server # use this exact value if you are using the file server, otherwise point it to an S3/Azure/Google bucket
          # it will use the same role-based auth mechanism you already configured for the NxCloud cache
          # you can also use the same bucket name that you use for the cache (rules will just be stored in a sub-folder)
```

##### Updates

- Feat: [Polygraph availability](/docs/enterprise/polygraph) (Conformance, Workspace Graph, Custom Workflows)
- Feat: Nx 21 [continuous tasks](https://nx.dev/blog/nx-21-continuous-tasks) support
- Feat: Download artifacts button
  - When you view a task that just ran in CI on the NxCloud UI, there is now a button to download any artifacts that task produced directly from your browser
  - This is especially useful if you want to view screenshots/videos of failed e2e tests
- Feat: [Self-healing CI](/docs/features/ci-features/self-healing-ci)
  - Speak to your assigned DPE about testing this
  - You will need an Anthropic API key and access to Claude's servers
- Feat: Dark Mode UI setting
- Various fixes and stability improvements to DTE, agent visualization, and other areas of the app

### 2025.06.3

- Fix: add timeouts to GitLab requests
  - the defaults are now 5 and 10 seconds for connect and read
  - these should help prevent issues with certain unstable GitLab environments

### 2025.06.2

- Fix: Terminal outputs not loading in the browser in restricted environments
  - Requires an update to the latest current nx Helm chart version 0.16.3

### 2025.06.1

- Fix: GitHub connection issue on nx-api startup when Nx Agents are active

### 2025.06

- Feat: Define your own custom resource classes (CPU, RAM etc.) for use with Nx Agents
  - See [configuration details](https://github.com/nrwl/nx-cloud-helm/blob/main/EXTERNAL-RESOURCE-CLASSES.md)
- Feat: Flaky task retry configuration
  - Configure in the workspace settings how Nx Cloud should handle flaky tasks
- Feat: Full GitLab integration
  - Allows automatic members sync to your Nx Cloud workspace
- Feat: Agent logs timestamps and full-screen mode
- Feat: Assignment rules updates
  - Parallelism configuration
  - Target globs
  - See [here](/docs/reference/nx-cloud/assignment-rules#how-to-define-an-assignment-rule) for examples
- Feat: Parallel agent steps and step groups (docs [here](/docs/reference/nx-cloud/launch-templates#launchtemplatestemplatenamegroupname))
- Feat: Reusable agent launch template snippets via yaml anchors
  - See example [here](/docs/reference/nx-cloud/launch-templates#full-example)
  - Specifically how `common-init-steps: &common-init-steps` is defined
- Feat: Individual GitHub commit statuses for each run group
  - This is configurable in your workspace settings
  - See [here](/docs/guides/nx-cloud/setup-ci#github-status-checks) for branch settings configuration
  - You might also need [to update your GitHub app permissions](/docs/guides/nx-cloud/source-control-integration/github-app-permissions)
- Misc: CIPE list is sortable by duration
- Fix: early DTE job termination improvements
- Fix: run details page performance improvements

### 2025.03.3

- Feat: provide prebuilt Java cert store to NxAPI
  - Full details [here](https://github.com/nrwl/nx-cloud-helm/blob/main/PROXY-GUIDE.md#pre-built-java-cacerts)

### 2025.03.2

- Feat: Nx Agents "bundled executors"
  - up until now, the "executor" binaries that run on each Nx Agent (and know how to parse your agents.yaml and run each step) had to be downloaded separately from an external bucket
  - this made the on-prem upgrade process more difficult, as it required a separate step to download the executor and then upload it in the correct folder on an internally available repository
  - now, the executors are available as Docker images that can be imported alongside all your other NxCloud images
  - to get started:
    - when upgrading to this version, make sure you also pull in the executor image `nxprivatecloud/nx-cloud-workflow-executor:2025.03.2`([link](https://hub.docker.com/repository/docker/nxprivatecloud/nx-cloud-workflow-executor/tags/2025.03.2/sha256-a42835a3126f21178af87f02b68d68fec1ff0654d37a57855a762c01e7795a6b))
    - as part of your controller [args](https://github.com/nrwl/nx-cloud-helm/blob/main/charts/nx-agents/values.yaml#L76) pass this option:

      ```
      args:
        # pass the internal image registry where the pods can pull the executor images from
        # for example: image-registry: us-east1-docker.pkg.dev/nxcloudoperations/nx-cloud-enterprise-public
        image-registry=<registry-where-nxcloud-images-are-hosted>

        # you can REMOVE the below option, as it's not needed anymore
        # kube-unix-init-container-name=...
      ```

    - you no longer need to upload the executor binary separately to a bucket
    - now whenever you start your agent pods, they will load the above image and copy the executor from there

### 2025.03.1

- Fix: use custom "github URL" (if defined) when checking out the repo on Nx Agents

### 2025.03

##### Assignment rules

Assignment rules allow you to control which tasks can run on which agents. Save on agent costs by provisioning different sizes of agents to suit the individual needs of your tasks. You can ensure resource intensive targets like `e2e-ci` and `build` have what they need by using larger agents. Lighter tasks like `lint` and `test` can run on smaller agents.

Assignment rules are defined in yaml files within your workspace's `.nx/workflows` directory. You can use assignment rules with DTE-agents or with dynamic Nx Agents. Note that additional configuration is required when using DTE agents.

Read the full docs [here](/docs/reference/nx-cloud/assignment-rules#assignment-rules-beta).

Once you start using assignment rules, you'll be able to see all your configured "rules" in your CIPE "Analysis page".

##### DTE/Agent utilization visualization

Speaking about the CIPE "Analysis" page, the agent utilization graph has been completely revamped.

The new agent utilization visualization allows you to see when agents were actively executing tasks, and gaps when agents were idle. You can use this tool to optimize how work gets distributed, and modify your commands and dependencies to remove idle time. Tasks that hang will be highlighted in yellow, helping you debug OOM issues. If you’re using Nx Agents, you’ll also see set up steps on the visualization.

##### Workspace data caching

Before an Nx command is run, Nx will generate some metadata that it will use when evaluating tasks (i.e project graph) and store that data in the workspace-data folder. This short process is relatively quick for small repos and only needs to be performed upon the first call to Nx. However, for larger repos and cases where Nx is frequently generating this information from scratch, it becomes a large time sink. In CI, workspace-data needs to be generated each time a new pipeline is run and each agent needs to generate its own identical copy.

You can now set-up NxCloud to cache the default branch's workspace data and allow pipeline agents to retrieve it from the cache rather than regenerate this metadata each time.

To enable it, you need to set this env variable on the nx-api deployment:

- `NX_CLOUD_WORKSPACE_ARTIFACTS_STORAGE_BUCKET=<cloud-provider-bucket-name>`
- it will then use the same authentication mechanism you've set up for your main cache bucket
- if you do not use a cloud provider bucket such as S3, you can set this variable to `NX_CLOUD_WORKSPACE_ARTIFACTS_STORAGE_BUCKET=file-server` and it will use your local cluster file server

##### Misc items

- a new version of the AMQ image was released with the latest security patches and fixes
- node modules caching fixes on Nx Agents
  - previously, we were always recommending caching the `node_modules` folder itself in your Nx Agents yaml configs
  - this does not work with `npm ci`, as it always deletes the local `node_modules` folder before starting the installation. Instead, NPM recommends caching the `$HOME/.npm` directory.
  - Yarn and PNPM also have their own dedicated folders they recommend for caching
  - Part of this release, we now fixed caching folders in the `$HOME` directory, so all the below options should work:
    - `~/.npm`
    - `~/.cache/yarn`
    - `.pnpm-store` (note PNPM on Nx Agents does not store its cache folder in the \$HOME dir)
  - Please refer to the [custom launch templates docs](/docs/reference/nx-cloud/launch-templates#full-example) for how you can setup your caching under these new recommendations
- Nx Agents `$HOME` directory mounting
  - previously, when your Nx Agents pods were starting up, we were mounting as a k8s volume just the folder in which you checkout your repo: `$HOME/workspace`
  - however, a lot of dependencies and third-party apps use `$HOME` folder to deposit a lot of files (Rust, NPM cache folders etc.)
  - this caused agents to fight for available space on the node itself, causing very hard to debug issues if the space requirements were too big
  - part of this release, we now mount the whole `$HOME` directory as a volume, ensuring each agent gets a predictable storage size allocated
  - this also enables Nx Agents to run in more restricted environments (such as OpenShift), where read-only file systems are enforced (due to mountable volumes being writeable)
  - to enable this:
    - ensure you use (or are extending from) one of our pre-built agents base images
      - this is the image you set in your `image:` portion of your `agents.yaml`
      - (you are most likely using one of our images, so you can probably skip this step)
    - if you had to import the above image into your own internal registry, ensure it is part of a repository called `nx-agents-base-images`
      - Example (see the `nx-agents-base-images` part in this path): `image: 'us-east1-docker.pkg.dev/nxcloudoperations/nx-cloud-enterprise-public/nx-agents-base-images:ubuntu22.04-node20.11-v12'`
    - enable the `--copy-home-dir-init-container` flag [on the `controller.deployment.args` section in your Nx Agents `helm-config.yaml`](https://github.com/nrwl/nx-cloud-helm/blob/main/charts/nx-agents/values.yaml#L69)
- increase restart amount for agents
  - if any of your agents go down (either because one of their init steps fails, due to networking issues for example) or they run out of memory, we now try to restart them up to `N` times, where `N` is the number of agents you have
  - this should result in more pipeline stability, though it is worth to still monitor the failed steps to ensure any persistent issues get addressed
- addresses various potential race conditions in the NxCloud runner when restoring items from the cache (this was mainly noticeable on very large workspaces)
- various UI issues with the "compare tasks diff" have now been addressed
  - this is the tool used to diagnose why a cache hit did not occur and what the differences are between two given hashes

### 2025.01.4

- Misc: adds new custom Nx Agents resource classes

### 2025.01.3

- Misc: adds new custom Nx Agents resource classes

### 2025.01.2

- Fix: issue with decoding certain branch names in the URL (fixes loading certain run pages)

### 2025.01.1

- Fix: adds data migrations for older organizations

### 2025.01

##### Affected project graph

The affected project graph for pull requests has now made it to the on-prem release! [Read the full announcement here](https://nx.dev/blog/ci-affected-graph).

##### DTE improvements

- There have been a lot of performance improvements to the DTE algorithm and how tasks get sorted to ensure optimal distribution
- Improved early agent shutdown: we now look at more parameters to decide whether we can shutdown a DTE agent earlier
- Project graph integrity checks
  - both the main job and the agents require the exact same project graph for the DTE algorithm to run correctly
  - differences can appear, for example, if the agents or main job restore an older cached version of the project graph (instead of re-calculating the current one)
  - it can also happen if the main job and agents run off of different commits (maybe your main CI job does a `git merge` with `main` and your agents do not)
  - we now explicitly check if the agents and main job run on the same exact commit hash and also if they use the same project graph: otherwise we fail the DTE early
- `stop-agents-after` now supports target configs
  - if you are running two affected commands at different points in your main job, each triggering the same target but under different configurations
    - `nx affected -t build:config1`
    - `nx affected -t build:config2`
  - you can configure agents to wait for both of them to complete before ending the DTE
    - `--stop-agents-after=build:config1,build:config2,lint,test`

##### Nx Agents improvements

Previously, if an agent ran out of memory or crashed in the middle of its run, the logs would be lost.
Now, we have a dedicated long-running "log uploader" that can upload logs even if the main agent container crashed.
To enable, you will need to configure the following env var on your workflow controller:

```yaml
- name: LOG_UPLOADER_IMAGE
  value: 'us-east1-docker.pkg.dev/nxcloudoperations/nx-cloud/nx-cloud-workflow-log-uploader'
```

We now also make much fewer requests to GitHub (or your other VCS providers) during a CIPE start, so you should see improved Nx Agents startup times.

##### PR comments look refresh

The PR comment containing status updates about your CI execution has had make-over, showing a more clear breakdown of your runs, their duration and the status:

![new PR comment](../../../../assets/nx-cloud/new_github_comment.png)

##### Misc items

- while we do our best to infer your commit message to display on the CIPE page, if it ever doesn't look right, you can manually override in your CI pipeline by setting `NX_CLOUD_COMMIT_MESSAGE`
- improved workspace analytics controls
- we now print more information on the main CI job summary table, such as a direct link to the associated CIPE
- there is now a workspace level setting enabling or disabling flaky task retrying

### 2024.10.3

- Feat: Support NO_PROXY env var on pods

### 2024.10.2

- Fix: AWS S3 bucket connections when using STS role-based authentication

### 2024.10.1

- Fix: GitHub and external bucket connection issues when using a proxy

### 2024.10

This is a big release so let's go through the highlights first. There is also an important "Breaking changes" section at the end.

##### New version structure

We have changed our version structure to a more simplified tag: `YEAR.MM.PATCH_NUMBER`
The goal is to make it easier to spot how old/recent your existing NxCloud version is and compare it against newer deployments.

##### DTE summary table on main agent

When distributing with DTE, up until now, we have been replaying all your tasks logs "as they come in" from the DTE agents back onto your main job.

This is not that useful on big workspaces, with large task affected task graphs as it can be hard to follow all the outputs from all the agents streaming back concurrently.

This release contains the new "CI Table Log View" summary, and you can [read all about it here](https://nx.dev/blog/improved-ci-log-with-nx-cloud).

If you prefer the old logs style, you can always disable the feature via your workspace's settings screen.

##### Personal access tokens

Up until now, for developers to get access to read (and maybe write) to the cache you always needed an access token to be made available locally: either
committed to the repo via `nx.json` or made available as an env variable via a `.local.env` file.

This flow was secure enough as is, even if you never rotated your access tokens, as someone would still need continuous hourly access to your source code if they wanted to retrieve any of the latest cached artifacts.

But given you already manage developer access to your NxCloud workspace via the web app, we wanted to tie local cache access to that mechanism as well.

This release contains the new ["Personal Access Tokens"](https://nx.dev/blog/personal-access-tokens) feature that now asks developers to login locally before they can use the cache.
If they are a member of the workspace, they get a local token stored on their machine that will be used to access the cache.
The moment they get removed as a member from your workspace, they won't be able to read from the cache anymore.

Please read the full announcement post here, as it contains details on how to migrate your team to using [Personal Access Tokens](https://nx.dev/blog/personal-access-tokens).

##### GitHub app integration

If you are using GitHub, setting up a custom GitHub app for your org is the best way to take advantage of all the latest "GitHub-specific" features we offer.
Please see instructions [here](/docs/enterprise/single-tenant/custom-github-app) on setting up an app.
You will then need to make sure you set up your VCS integration again through your workspace's settings screen, and use the above app you created.

As part of this, you will also get the "GitHub membership management" feature, where everybody who is a collaborator of your GitHub repo will also get "read" access to your NxCloud workspace,
without you having to explicitly invite them.

##### Misc items

- Improved docker agents support
  - We fixed a few issues related to running docker builds in Nx Agents
- Big DTE performance improvements
- Azure file storage for Nx Agents
- Auth session length has been extended to 7 days by default
  - Use NX_CLOUD_SESSION_MAX_AGE to configure this to a different value
- Various SAML fixes and improvements
  - One highlight is that users can now login from Okta directly (while before they had to initiate login through NxCloud web app)

##### Breaking changes

Most workspaces will not be affected by this, but if you have these values configured in your `helm-config.yaml`:

- `github.pr.[...]`
- or `gitlab.mr.[...]`

they will stop working with this release (see [this](https://github.com/nrwl/nx-cloud-helm/pull/141/files) for details on what was removed).
Please go to your workspace settings and you should be able to configure all the above values when you setup a VCS integration.

_Terminal outputs_ in the web app will now be fully served from storage bucket (either S3/Gcloud/Azure, or your internal file-server). This means your NxCloud cluster needs to have an open/healthy connection to the bucket. You can test this by ssh'ing into the `nx-cloud-frontend` pod and trying to `wget` one of your bucket artefacts. Any proxy or firewall constraints will need to be handled. Additionally, if your bucket is hosted at a self-signed https URL, any fetch calls from the frontend pod to your bucket will fail. If you think any of this applies to you, please contact your DPE to discuss options.

### 2406.29.1.patch1

- Fix an issue with specifying custom AWS credentials in Minio instances
- Fix an issue with removing pending invites

### 2406.29.1

##### Full terminal outputs in the web app

Due to storage constraints in Mongo, long terminal outputs were sometimes truncated when viewed in the UI. With this update we are now loading all terminal outputs directly
from the storage bucket, removing the need to keep them in Mongo. You should now be able to view full, complete logs in the UI regardless of how large the output is.

##### OpenShift fixes for agents

- the latest messagequeue image is now OpenShift ready
  - to use, just update to the latest Helm version `0.15.6` and make sure you are not passing in an explicit tag for the messagequeue
  - then use version `2406.29.1` for NxCloud. This should use the latest, OpenShift enabled messagequeue image
- when running Agents on OpenShift, they run as a specific user with ID 1000
  - to override this, make sure to set `NX_CLOUD_RUN_UNIX_PODS_AS_USER: <userId>` and `NX_CLOUD_RUN_UNIX_PODS_AS_GROUP: <groupId>` on the [workflow controller env vars](https://github.com/nrwl/nx-cloud-helm/blob/main/charts/nx-agents/values.yaml#L63)

##### Full bitbucket data center (on-prem)

We now have full support for BitBucket Data Center (self-hosted):

- VCS integration for posting comments with live updates about your CI runs
- full agents integration
- more info about each one of your commits on the NxCloud web app
- you can even [set-up auth with BitBucket Data Center](/docs/enterprise/single-tenant/auth-bitbucket-data-center#bitbucket-data-center-auth)

##### Misc

- easier workspace setup experience for new customers
- the CIPE visualisation has been updated (elapsed task time)
- general web app performance improvements

##### Breaking changes

If you are using DTE, you will now need to pass the `--distribute-on="manual"` flag to your `npx nx start-ci-run` commands.

### 2405.02.15

##### Easy membership management via GitHub

A few months ago, we introduced a new feature to our managed SASS NxCloud product: easy membership management via GitHub. If you create a new workspace on [https://cloud.nx.app/](https://cloud.nx.app/) right now you will be guided through how to connect it to your GitHub repository. Now everyone that has access to your GitHub repository will also get access to your NxCloud workspace. If anyone loses access to GitHub (maybe they leave the company), they will also lose access to NxCloud. This makes membership management easy and straightforward, as you don't have to manually invite users anymore. Of course, setting up this connection also gives you NxCloud run status updates directly on your PRs - a feature we've had for a long time.

This feature has now been release for on-prem set-ups as well. To benefit from it, you'll need to create your own Github App with permissions to access your repository. Your on-prem NxCloud instance will then use this app to pull membership info from Github and check user permissions. You can find [the full setup instructions here](/docs/enterprise/single-tenant/custom-github-app).

##### DTE v2 enabled by default

After testing the improved task distribution algorithm (DTE v2) for the past few months, we are now enabling it by default for all customers. Expect quicker CI run times when using DTE, and better utilization of your agents with less idle time.

##### Nx Agents and breaking changes

If you are using Nx Agents, this release will contain a breaking change to the workflow controller.
Before upgrading to this version, you'll need to follow the new [Agents Guide](https://github.com/nrwl/nx-cloud-helm/blob/main/agents-guide/AGENTS-GUIDE.md) and deploy an instance of Valkey that your controller can connect to.

The reason we need Valkey is that the workflow controller now persistently stores information about your workflows for up to 8 hours, and these changes will be persisted regardless of the availability of the workflow controller pod, making your in-progress workflows more resilient to rolling kubernetes updates, and will fix some previous issues with agent statuses not syncing to the UI.

If you are not using Nx Agents, this does not affect you and you can upgrade to this version straight away.

##### UI improvements

- If you are using the new Crystal plugins in Nx 18, we've now added a "technologies label" to each task, so you can quickly see which tasks are Playwright based, Cypress, React etc.
- We've added toast notifications in the app. You'll see them confirming some of your actions, such as saving workspace changes.

##### Misc fixes

- We've fixed various bugs around the task distribution algorithm and Nx Agents. CIPEs using distribution should feel more stable and faster.
- We fixed a few issues relating to the GitLab and BitBucket integrations.

### 2404.05.9

##### DTE algorithm v2 experimental flag

For the past 2 months, we've been re-writing our entire task distribution algorithm. The aim was to allocate tasks more efficiently to agents,
reduce total time spent by agents downloading artefacts and reduce idle agent time waiting for tasks.

While the features is still in its beta stage, initial tests do show a big improvement in overall CI completion time
(but this varies on a case by case basis).

If you are already using DTE or Nx Agents, you can enable this experimental feature by adding the following env var to your main job (the job
where you invoke `npx start-ci-run`):

```yaml
NX_CLOUD_DTE_V2: 'true'
```

##### Nx Agents on-prem availability

Since the previous release, we've been testing various options for deploying Nx Agents on-premise.

We now have a dedicate Helm chart dedicated to setting up an Nx Agents cluster on your infrastructure:

1. ⚠️ Please reach out to your DPE first so we can start an Nx Agents trial and discuss any limitations and requirements up-front
2. You can view the example `values.yaml` [here](https://github.com/nrwl/nx-cloud-helm/blob/main/charts/nx-agents/values.yaml)
3. Once we had a chance to look at your existing CI compute requirements, you deploy the chart via `helm install nx-cloud nx-cloud/nx-agents --values=helm-values.yml`

##### Audit logger

As an Enterprise installation admin, you can now view audit logs over NxCloud workspace events by visiting `https://<NXCLOUD-URL>/audit-log`.

This includes events such as when a workspace was created, when a new VCS integration was set-up and so on.

##### UI improvements

- Organizations can now be created directly from the "Connect a workspace" screen
- Full screen terminal outputs for your tasks

### 2402.27.3.patch3,4,5,6

- Feat: allows customising the base image for the agent init-container (in case it is self-hosted internally in the company)
- Feat: adds more logging to debug authorization errors for Github, Gitlab and SAML
- Fix: fixes an issue with using custom launch templates on GitLab

### 2402.27.3.patch3

- Feat: allows disabling the automated pod watcher which doesn't behave as expected in some k8s engines

### 2402.27.3.patch2

- Feat: allows volume class to be customised for Agents

### 2402.27.3.patch1

- Fixes an issue with the aggregator creating empty organisations during the first migration

### 2402.27.3

With this version you can take advantage of most features announced during our recent [launch week](/blog/launch-nx-week-recap).

##### Nx Agents

This release contains everything needed to run [Nx Agents](/docs/features/ci-features/distribute-task-execution) on-prem. While the on-prem configuration is still experimental, we are actively running Nx Agents trials at the moment, and if you'd like to take part please reach out to your DPE.

If you already running DTE, there are a few advantages to upgrading to Agents:

- simplified CI config: you will need to maintain just a single, main CI job config. NxCloud will create needed CI agents for you as needed.
- [dynamic agent allocation based on PR size](/docs/features/ci-features/dynamic-agents): instead of always launching all your agents NxCloud will now launch different number of agents dynamically based on your PR size
- access to [Spot instances](https://aws.amazon.com/ec2/spot/): if you are running your clusters on any of the popular cloud providers (AWS, Google Cloud, Azure etc.), you can now use their Spot instances for running your CI job. This is possible due to NxCloud's distribution model, which allows work on a reclaimed node to be re-distributed to the remaining agents.

We will shortly make available a new Helm chart that will allow you to deploy a separate Agents cluster to launch workflows: [https://github.com/nrwl/nx-cloud-helm](https://github.com/nrwl/nx-cloud-helm).

![agents_screen](../../../../assets/nx-cloud/agents.webp)

##### Task Atomizer and task retries

If you combine this release + upgrade to the latest Nx 18, you will have access to both the [task atomizer](/docs/features/ci-features/split-e2e-tasks) (which allows your e2e to be distributed among agents PER FILE, instead of previously per project) and the [flaky task retry functionality](/docs/features/ci-features/flaky-tasks).

##### CIPE page improvements

Along with all the UI changes to support agents (following their logs and track how tasks get distributed,details of which you'll find demoed on [this page](/docs/features/ci-features/distribute-task-execution)) this release also brings all the new improvements to the CI pipeline execution page, including the commit info panel at the top:

![cipe_top_half_screen](../../../../assets/nx-cloud/cipe_top.webp)

### 2312.11.7.patch1

- re-enable path style access for s3 buckets
- fix an aggregator migration issue with old CIPE data

### 2312.11.7

##### Helm package compatibility

When upgrading to this version and anything above it, you will need to use Helm version 0.12.0+:

| Chart Version |         Compatible Images          |
| :-----------: | :--------------------------------: |
| <= `0.10.11`  | `2306.01.2.patch4` **and earlier** |
|  >= `0.11.0`  |     `2308.22.7` **and later**      |
|  >= `0.12.0`  |     `2312.11.7` **and later**      |

##### New UI features and improvements

On the UI, we replaced the runs overview with the new CI Pipeline Executions (CIPE for short) screen:

![cipe_screen](../../../../assets/nx-cloud/cipe_screen.webp)

This screen organises your runs more logically, according to each invocation of your CI pipeline.
It provides more data around the committer name and commit message and a full analysis of your CIPE once it is completed.
And if you need to run your tasks on multiple environments, you can now switch between them on this page and view the results separately.
You can play around with an example on the [Nx Repo](https://staging.nx.app/orgs/62d013d4d26f260059f7765e/workspaces/62d013ea0852fe0a2df74438/overview)

There is also a new Analytics screen for your workspaces, to which we'll keep adding new features to better help you optimise your CI pipelines:

![analytics_screen](../../../../assets/nx-cloud/analytics_screen.webp)

Here you can see:

- historical trends of CIPE Average duration
- historical trends of CIPE average daily count
- average daily time saved by DTE

Other improvements:

- better overall UI performance (navigating feel much snappier now)
- improved terminal output rendering
- members can now be invited as admins directly

##### The light runner

Nx Cloud works by using a local Node runner that wraps your Nx tasks and sends information about them to the Nx Cloud API. This is how it knows whether to pull something from the remote cache or run it.

Because they work together, sometimes changes to the API required updates to this local runner. This led to workspaces that did not update their local
runner version in `package.json` sometimes running into compatibility issues.

We overhauled this mechanism, and the runner is now bundled as part of the API itself, ensuring you get sent the correct runner code when you first start running Nx commands in your workspace.
This ensures you will always have the correct local runner version that is compatible with your on-prem Nx Cloud installation.

We've been testing this out on our Public Nx Cloud instance and it is now available for on-prem installations as well.

To enable the light runner feature, make sure you:

1. remove `useLightClient: false` from your `nx.json` (if you had it)
2. If you are on Nx version > 17, you can remove any `nx-cloud` or `@nrwl/nx-cloud` package in your `package.json` and it should just work
3. If you are on Nx version < 17, upgrade to `nx-cloud@16.5.2` or `@nrwl/nx-cloud@16.5.2`.

##### Nx Agents

This release is also the first one to support ["Nx Agents"](/docs/features/ci-features/distribute-task-execution).

While currently experimental and disabled by default for on-prem users, we are looking for more on-prem workspaces to try it out with
so please reach out to your DPE contact or to [cloud-suppport@nrwl.io](mailto:cloud-support@nrwl.io) if you are interested in helping us shape this according to your needs!

##### Breaking changes - MongoDB migration

As a reminder, we now only support MongoDB 6+. If you are running an older version please refer to the upgrade instructions [here](/docs/reference/nx-cloud/release-notes#breaking-changes).

### 2308.22.7.patch7

- Allows the frontend container to be ran with `runAsNonRoot: true`

### 2308.22.7.patch6

- Fixes a UI issue on the branch when running a task in a DTE context

### 2308.22.7.patch5

- Fixes a UI issue when navigating to branches containing slashes

### 2308.22.7.patch4

- Updates the frontend image to remove some vulnerability issues

### 2308.22.7.patch3

- Fixes a compatibility issue with the latest `nx-cloud` release

### 2308.22.7.patch2

- Fix: github member invites

### 2308.22.7.patch1

- Feature: self-signed certificate support for aggregator
  - This is needed if you are using self-signed certificate for your external Mongo instance
  - See [here](https://github.com/nrwl/nx-cloud-helm/blob/main/PROXY-GUIDE.md#supporting-self-signed-ssl-certificates) for usage details.
- Fix: aggregator issue when creating text Mongo indexes

### 2308.22.7

In our last big release, we announced a completely new UI, rebuilt from the ground up in React. In this release, the frontend team
has continued that effort and wrapped the React app with the [Remix](https://remix.run/) framework. This is the same technology that powers our public https://cloud.nx.app/
product. It's faster, it handles resource caching better, and should allow the frontend team to ship features quicker than ever before.

##### Helm package compatibility

When upgrading to this version and anything above it, you will need to use Helm version 0.11.1:

| Chart Version |         Compatible Images          |
| :-----------: | :--------------------------------: |
| <= `0.10.11`  | `2306.01.2.patch4` **and earlier** |
|  >= `0.11.0`  |     `2308.22.7` **and later**      |

##### VCS proxy support

- For the GitHub/Bitbucket/Gitlab integrations to work, Nx Cloud needs to make HTTP calls to GitHub/GitLab to post comments
- If are behind a proxy however, these requests might fail
- If you are using our [Helm chart](https://github.com/nrwl/nx-cloud-helm/), you can now configure this option to unblock the vcs integration and allow it to work with your proxy:
  ```yaml
  vcsHttpsProxy: '<your-proxy-address>'
  ```

##### Misc updates

- UI enhancements of the run details screen
- UI enhancements of the task details screen
- fixes and better error handling for the DTE screen
- failed runs are now sorted at the top
- web app performance improvements for large workspaces
- more structured NxAPI pod logs (allows for better debugging)

##### Bug fixes

- Fixed an issue with applying licenses on orgs owned by non-installation admin accounts

##### Breaking changes - MongoDB migration

In the last big release we announced [the deprecation of Mongo 4.2](/docs/reference/nx-cloud/release-notes#breaking-changes)
With this release, we have now stopped supporting Mongo 4.2 completely. Please upgrade Mongo to version 6 before installing this new image. You will find instructions [here](/docs/reference/nx-cloud/release-notes#breaking-changes).

### 2306.01.2.patch4

- Fixes an issue with new licenses expiring sooner than original end date

### 2306.01.2.patch3

- Fixes an issue with multiple admin organizations being created on new installations
- Fixes an issue where Enterprise licenses could not be applied on some new orgs

### 2306.01.2.patch2

- Fixes an issue with the `single-image` container where the aggregation would block the API from starting up

### 2306.01.2.patch1

- Fixes an issue where admin users were not being created on new installations.

### 2306.01.2

This is one of our biggest Nx Cloud On-Prem releases. It also marks a change in our release process which will be explained at the end.

##### Brand new uI

A few months ago we announced a complete re-design of the Nx Cloud UI! It's faster, easier to use and pleasant to look at! We're now bringing this to On-Prem users as well:

You can read more about it in our [announcement blog post](https://nx.dev/blog/nx-cloud-3-0-faster-more-efficient-modernized).

##### Pricing updates

While before we provided you with a separate coupon for each workspace, we have now changed to "organization-wide licenses": you receive a single coupon for your whole organization, that gives you unlimited access for the agreed number of workspaces. You are then free to delete, create and re-shuffle your workspaces as often as you want without requiring new coupons for us (as long as you stay within your limit of workspaces).

You will see some updates in the UI to reflect this, however, **you don't need to do anything once you update your images!** We'll automatically migrate you to this, based on your current number of enabled workspaces!

##### Proxy updates

One of the features of Nx Cloud is its integrations with your repository hosting solution. When you open up a Pull Request, you can configure Nx Cloud to post a comment to it once your CI has finished running, with a summary of all the tasks that succeeded and failed on that code change, and a link to your branch on Nx Cloud so you can further analyse your run. Your developers save time, and allows them to skip digging through long CI logs.

Before, if you had a self-hosted instance of GitHub, Gitlab or Bitbucket, calls from Nx Cloud to your code-hosting provider would fail, because they'd be using a self-signed certificate, which Nx Cloud wouldn't recognise.

[We now support self-signed SVN certificates, via a simple k8s configMap.](https://github.com/nrwl/nx-cloud-helm/blob/main/PROXY-GUIDE.md#supporting-self-signed-ssl-certificates)

[We've also made updates to the runner, to support any internal proxies you might have within your intranet.](https://github.com/nrwl/nx-cloud-helm/blob/main/PROXY-GUIDE.md#supporting-self-signed-ssl-certificates)

##### DTE performance

We completely re-wrote our Task Distribution engine, which should result in much fewer errors due to agent timeouts, increased performance and more deterministic task distribution.

We've also added a new internal task queueing system, which should further improve the performance of DTE. While this is an implementation detail which will be automatically enabled in future releases, you can test it out today by setting [`enableMessageQueue: true`](https://github.com/nrwl/nx-cloud-helm/blob/main/charts/nx-cloud/values.yaml#L18) in your Helm config.

You can read more about the recent DTE improvements in our [Nx Cloud 3.0 blog post](https://nx.dev/blog/nx-cloud-3-0-faster-more-efficient-modernized).

##### Misc updates

- We have fixed issues related to OpenShift deployments. [Special thanks to minijus](https://github.com/nrwl/nx-cloud-helm/pull/32) for his work on the Helm charts and helping us test the changes.

##### Breaking changes

Nx Cloud uses MongoDB internally as its data store. While we've always used Mongo 4.2, in the latest release we started targeting Mongo 6.0. It's a much lighter process, with improved performance, and quicker reads and writes.

While you can still upgrade to this new image even if you are on Mongo 4.2 (nothing will break), **we strongly recommend you upgrade your Database to Mongo 6.0 to make sure nothing breaks in the future.** [We wrote a full guide on how you can approach the upgrade here](https://github.com/nrwl/nx-cloud-helm/blob/main/MONGO-OPERATOR-GUIDE.md#upgrading-to-mongo-6).
If you need assistance, please get in touch at [cloud-support@nrwl.io](mailto:cloud-support@nrwl.io).

###### Migration from community edition to enterprise

On May 16th, 2023 we announced our plans to sunset the Community Edition of Nx Cloud On-Prem to align with our new pricing plans. If you are on the Community Edition, please follow these steps to migrate:

1. Use this image: `2306.01.2.patch3`
2. Switch to private Enterprise by setting `NX_CLOUD_MODE=private-enterprise` (or `mode: 'private-enterprise'` if using Helm).
3. Reach out to us at [cloud-support@nrwl.io](mailto:cloud-support@nrwl.io). You will get a FREE, unlimited-use coupon for the next 3 months so you can trial Nx Enterprise.

##### New release process

With this update, we are also changing our release process:

1. We'll start adding release notes with every new version published
2. We switch to using [calver](https://calver.org/) versioning for our images
3. We stopped publishing the `latest` tag.
4. We will be emailing Enterprise admins with every new release. If you do not get these emails, please send us an email at [cloud-support@nrwl.io](mailto:cloud-support@nrwl.io) to get added

Any questions at all or to report issues with the new release [please get in touch!](mailto:cloud-support@nrwl.io)

### 13-02-2023T23-45-24

- Feat: Targettable agents for DTE. You can now ask specific agents to pick up specific tasks (via `--targets
- Fix: DTE fixes for 404 not found artefacts errors
- Fix: issue when using GitHub integration with self-hosted GitHub instances

### 26-01-2023T21-22-48

- Misc: Fixes to the Gitlab integration

### 05-01-2023T17-53-45

- Misc: This release contains small bug fixes and UI improvements.

### 14-12-2022T19-43-44

- Feat: IAM Role Auth. We have now deprecated "aws_access_key_id" and "aws_access_key_secret" in favor of service accounts and IAM roles for accessing AWS resources. See the [new guide here](https://github.com/nrwl/nx-cloud-helm/blob/main/aws-guide/AWS-GUIDE.md) for details.

### 13-10-2022T16-45-30

- Misc: This release mostly contains improvements that apply to the Public SASS version of Nx Cloud. No significant changes for the On-Prem version.

### 13-10-2022T16-45-30

- Feat: Private Cloud now runs completely as Kubernetes cluster. See the [Helm example repo](https://github.com/nrwl/nx-cloud-helm) for more details

### 05-08-2022T15-42-20

- Fix: issue with retrieving hashes during reads
- Feat: added route to display container version at `/version`
- Misc: forward api errors to stderr so k8s clusters can process them better

### 02-08-2022T16-11-36

- Note: The version naming scheme for the containers was changed to better track date/time of releases and to support embedding of the version inside the web UI
- Feat: view the container version under the `/errors` route
- Feat: BitBucket login (note: does not support self-hosted instances of BitBucket Server)
- Feat: New system-ui font scheme
- Fix: branch screen sorting performance improvements

### 2.4.11

- Fixes an intermittent container start-up issue when running a self-contained Mongo instance
- Fixes an issue with the self-hosted file-server where it would fail to create the initial directories

### 2.4.10

- Fix an issue with the admin password not being set correctly

### 2.4.9

- Align all Nx Cloud images to this version. No new fixes or features included.

### 2.4.8

{% callout type="caution" title="IMPORTANT" %}
The default container mode has changed from `COMMUNITY` to `ENTERPRISE`. If you are running a Community version of the container, you will need to make sure the `NX_CLOUD_MODE=private-community` is explicitly set (otherwise your container will fail to start-up).
{% /callout %}

- Fix: Web app performance improvements
- Fix: issue with GitHub logged in admins not being able to download logs
- Fix: issue with billing page when multiple access tokens were attached to the same org
- Fix: multiple Mongo DBs used to be created if a default DB was not provided in the connection string. Now it always defaults to the provided `NX_CLOUD_MONGO_DB_NAME`

### 2.4.7

- Misc: performance improvements to DB indexes
- Misc: improvements to hash differ to use regex
- Misc: export more collections for debug purposes (workspaces and organizations)

### 2.4.6

- Fix: issue with navigating to organizations/workspaces in the web app

### 2.4.5

- Feat: filters to branch and run list pages
- Fix: improved `MD5` cache artifact archiving
- Misc: various UI and UX improvements to the Nx Cloud dashboards

### 2.4.4

- Fix: Missing artefact retrieval error when using read-tokens
- Fix: Performance improvements to the branch page and run groups sorting
- Fix: better handling of artefact `.tar` archiving

### 2.4.3

- Feat: Billing page messaging improvements
- Fix: runs sorting on branch page

### 2.4.2

- Feat: DTE post-run report
- Feat: Hash Detail tool flow improvements

### 2.4.1

- Feat: Admins can now easily export debug info for error investigation
- Fix: branch screen run group sorting

### 2.4.0

- Feat: [GitLab Auth Support](https://nx.app/docs/private-cloud-gitlab-auth)/private-cloud-gitlab-auth
- Feat: Hash diffing tool improvements
- Feat: show message on branch page if workspace is unclaimed
- Fix: Agent out of memory warning
- Feat: cache inner runs
- Fix: include correct GitHub workflows path
- Fix: default to most recent run group on branch page
- Fix: handle DTEs with no tasks
- Fix: await process checkout sessions

### 2.3.1

- Feat: Increase file-server default cached artifact limit. If you are not using an external file storage (such as S3), then the cached assets will now be kept by default from 2 weeks to 4 weeks, increasing the chance of cache hits.
- Feat: "Download cache usage" data from the "Time saved" workspace page

### 2.3.0

- Feat: GitHub Integration - no token is now necessary in "`nx.json`" for the GitHub integration to work (you still need to provide as an env var for caching to work). To connect your workspace to GitHub without an access token in "`nx.json`" just pass in the "`NX_CLOUD_INTEGRATION_DEFAULT_WORKSPACE_ID=<your-workspace-id>`" env var
- Misc: better error handling (report less false positives)
- Fix: Scheduled tasks locking

### 2.2.16

- Misc: DB performance improvements (old records clean-up aggregator, indexes etc.)

### 2.2.15

- Feat: Add options to control database load
- Fix: Better exception handling in the API

### 2.2.14

- Feat: Optimize event processing to increase the throughput of workspaces with a very high number of agents.
- Fix: Gracefully recover when stats aggregation fails

### 2.2.13

- Feat: Hash diffing tool enhancements

### 2.2.12

- Feat: DTE visualisation improvements for larger workspaces
- Fix: billing page not displaying subscriptions for Private Community

### 2.2.11

- Feat: Better error handling for scheduled tasks
- Fix: branch screen not loading

### 2.2.10

- Feat: Various UI improvements to the Nx Cloud screens
- Feat: Hash detail diff tool
- Feat: GitHub app comment revamp
- Feat: DTE visualisation

### 2.2.9

- Fix: DTE bug fixes caused by incorrectly batched tasks

### 2.2.8

- Fix: various DTE bug fixes
- Feat: Add `NX_CLOUD_DISTRIBUTED_EXECUTION_AGENT_COUNT` env var for more explicitly optimising DTEs
- Feat: Send GitHub workspace membership invites by email
- Fix: improve container start-up time
- Feat: If Mongo connection fails during container start-up it keeps retrying up to a max number of times (configurable via `MONGO_MAX_RETRIES`)
- Feat: expose "/ping" endpoint (can be useful for K8s readinessProbe)
  - `curl --fail http://localhost:8081/nx-cloud/ping --header "authorization: your-nx-cloud-access-token"`
- Feat: billing estimator (on billing page)
- Fix: ignore ending slash on `NX_CLOUD_APP_URL` (in case it's added by mistake)

### 2.2.7

- Feat: `VERBOSE=1` env variable option to output extra information during container initialisation
- Feat: `MONGO_REPAIR=1` env variable option to trigger a [Mongo Repair](https://docs.mongodb.com/manual/tutorial/recover-data-following-unexpected-shutdown/) if the container data gets corrupted

### 2.2.3

- Fix: Reset the memory limits to best work on an instance with 8GB of RAM.
- Fix: Set the default `NX_CLOUD_MODE` to "community".

### 2.2

- [Nx Cloud 2.2](https://blog.nrwl.io/%EF%B8%8F-nx-cloud-2-2-%EF%B8%8F-b7656ed5ce7c)

### 2.0

- [Overview of Nx Cloud 2.0](https://blog.nrwl.io/introducing-nx-cloud-2-0-f1e5c2002a65)

---
<!-- source: https://nx.dev/docs/reference/nx-console-settings.md -->
## Nx Console Settings Reference

This page provides a complete reference of all configuration settings available for Nx Console. Each setting shows how to configure it in both VSCode and JetBrains IDEs (IntelliJ IDEA, WebStorm, etc.).

## Editor settings

{% tabs syncKey="ide" %}
{% tabitem label="VSCode" %}

VSCode uses JSON files for configuration. Settings can be configured at different scopes:

**User Settings** (global across all workspaces):

- Apply to all VSCode projects
- Location: `~/.config/Code/User/settings.json` (Linux/macOS) or `%APPDATA%\Code\User\settings.json` (Windows)
- Access via: `Cmd+,` (macOS) or `Ctrl+,` (Windows/Linux), then click the "Open Settings (JSON)" icon

**Workspace Settings** (specific to one workspace):

- Apply only to the current workspace
- Location: `.vscode/settings.json` in your workspace root
- Recommended for team-shared configurations (commit to version control)
- Override user settings

Learn more about VSCode settings in the [official VSCode documentation](https://code.visualstudio.com/docs/getstarted/settings).

{% /tabitem %}
{% tabitem label="JetBrains" %}

{% aside type="note" title="JetBrains IDE Configuration" %}
JetBrains IDEs configure Nx Console through the Settings/Preferences UI panel (**Settings > Tools > Nx Console**) rather than JSON configuration files. Only a subset of VSCode settings are available.
{% /aside %}

{% /tabitem %}
{% /tabs  %}

## Common Nx commands

Configure which Nx commands appear in the sidebar view.

{% tabs syncKey="ide" %}
{% tabitem label="VSCode" %}

**Setting:** `nxConsole.commonNxCommands`

**Default:** `["run", "run-many", "affected", "affected --graph", "list"]`

```json
{
  "nxConsole.commonNxCommands": ["run", "run-many", "affected", "test", "build"]
}
```

This setting supports both arbitrary commands and UI-based commands that open dedicated interfaces.

{% /tabitem %}
{% tabitem label="JetBrains" %}

{% aside type="caution" title="Not Available" %}
This setting is not available in JetBrains IDEs. Command customization is not currently supported.
{% /aside %}

{% /tabitem %}
{% /tabs %}

## Project viewing style

Defines how the Projects view displays entries in the sidebar.

{% tabs syncKey="ide" %}
{% tabitem label="VSCode" %}

**Setting:** `nxConsole.projectViewingStyle`

**Options:** `"list"` | `"tree"` | `"automatic"`

**Default:** `"automatic"`

```json
{
  "nxConsole.projectViewingStyle": "tree"
}
```

**Options explained:**

- `"list"`: Shows projects as a flat ordered list
- `"tree"`: Displays projects in a folder/tree structure
- `"automatic"`: Adaptively switches between list and tree based on workspace structure

{% /tabitem %}
{% tabitem label="JetBrains" %}

**Location:** Settings > Tools > Nx Console > Tool Window Style

**Options:** List | Tree | Automatic

**Default:** Automatic

Navigate to **Settings/Preferences > Tools > Nx Console** and select the desired style from the "Tool Window Style" dropdown.

**Options explained:**

- **List**: Shows projects as a flat ordered list
- **Tree**: Displays projects in a folder/tree structure
- **Automatic**: Adaptively switches between list and tree based on workspace structure

{% /tabitem %}
{% /tabs %}

## Nx workspace path

Specifies the relative path to the Nx workspace root directory.

{% tabs syncKey="ide" %}
{% tabitem label="VSCode" %}

**Setting:** `nxConsole.nxWorkspacePath`

**Default:** `undefined`

```json
{
  "nxConsole.nxWorkspacePath": "packages/workspace"
}
```

Useful when working in a monorepo where the Nx workspace is nested within a larger repository structure.

{% /tabitem %}
{% tabitem label="JetBrains" %}

**Location:** Settings > Tools > Nx Console > Nx Workspace Path

**Default:** Empty (uses project root)

Navigate to **Settings/Preferences > Tools > Nx Console** and enter the relative path in the "Nx Workspace Path" field.

For example: `packages/workspace`

{% /tabitem %}
{% /tabs %}

## Enable codeLens

Controls the visibility of CodeLens features for Nx-specific files.

{% tabs syncKey="ide" %}
{% tabitem label="VSCode" %}

**Setting:** `nxConsole.enableCodeLens`

**Default:** `true`

```json
{
  "nxConsole.enableCodeLens": false
}
```

CodeLens provides inline actionable commands directly in your editor for files like `project.json` and workspace configuration files.

{% /tabitem %}
{% tabitem label="JetBrains" %}

{% aside type="caution" title="Not Available" %}
This setting is not available in JetBrains IDEs. CodeLens is a VSCode-specific feature. JetBrains IDEs use their native intention actions and code inspections instead.
{% /aside %}

{% /tabitem %}
{% /tabs %}

## Enable library imports

Configures the TypeScript language server plugin to include configured libraries.

{% tabs syncKey="ide" %}
{% tabitem label="VSCode" %}

**Setting:** `nxConsole.enableLibraryImports`

**Default:** `true`

```json
{
  "nxConsole.enableLibraryImports": true
}
```

This enables better IntelliSense and autocompletion for library imports in your workspace.

{% /tabitem %}
{% tabitem label="JetBrains" %}

{% aside type="caution" title="Not Available" %}
This setting is not available in JetBrains IDEs. TypeScript library imports are handled through JetBrains' native TypeScript language services.
{% /aside %}

{% /tabitem %}
{% /tabs %}

## Generator allowlist

Specifies generator names or wildcard patterns to show in the generator picker.

{% tabs syncKey="ide" %}
{% tabitem label="VSCode" %}

**Setting:** `nxConsole.generatorAllowlist`

**Default:** `[]` (all generators shown)

```json
{
  "nxConsole.generatorAllowlist": [
    "@nx/react:*",
    "@nx/next:application",
    "@nrwl/workspace:library"
  ]
}
```

Use the format `@package:generator` or `@package:*` for wildcards. When this list is populated, only matching generators will be shown.

{% /tabitem %}
{% tabitem label="JetBrains" %}

**Location:** Settings > Tools > Nx Console > Generator Allowlist

**Default:** Empty (all generators shown)

Navigate to **Settings/Preferences > Tools > Nx Console** and add patterns in the "Generator Allowlist" field, one per line:

```text
@nx/react:*
@nx/next:application
@nrwl/workspace:library
```

{% /tabitem %}
{% /tabs %}

## Generator blocklist

Specifies generator names or wildcard patterns to hide from the generator picker.

{% tabs syncKey="ide" %}
{% tabitem label="VSCode" %}

**Setting:** `nxConsole.generatorBlocklist`

**Default:** `[]`

```json
{
  "nxConsole.generatorBlocklist": ["@nx/angular:*", "*:stories"]
}
```

Useful for removing generators that aren't relevant to your workflow.

{% /tabitem %}
{% tabitem label="JetBrains" %}

**Location:** Settings > Tools > Nx Console > Generator Blocklist

**Default:** Empty

Navigate to **Settings/Preferences > Tools > Nx Console** and add patterns in the "Generator Blocklist" field, one per line:

```text
@nx/angular:*
*:stories
```

{% /tabitem %}
{% /tabs %}

## Enable dry run on change

Enables automatic dry runs when using the Generate command.

{% tabs syncKey="ide" %}
{% tabitem label="VSCode" %}

**Setting:** `nxConsole.enableTaskExecutionDryRunOnChange`

**Default:** `true`

```json
{
  "nxConsole.enableTaskExecutionDryRunOnChange": false
}
```

When enabled, changing generator options triggers a dry run to preview the changes before applying them.

{% /tabitem %}
{% tabitem label="JetBrains" %}

**Location:** Settings > Tools > Nx Console > Enable Dry Run on Change

**Default:** Checked (enabled)

Navigate to **Settings/Preferences > Tools > Nx Console** and toggle the "Enable Dry Run on Change" checkbox.

{% /tabitem %}
{% /tabs %}

## Move generator patterns

Controls which collections' move generators should be used based on project path patterns.

{% tabs syncKey="ide" %}
{% tabitem label="VSCode" %}

**Setting:** `nxConsole.moveGeneratorPatterns`

**Default:** `{}`

```json
{
  "nxConsole.moveGeneratorPatterns": {
    "apps/**": "@nx/workspace:move",
    "libs/**": "@custom/generators:move"
  }
}
```

This is useful when you have multiple generator collections and want to specify which move generator to use for different project types.

{% /tabitem %}
{% tabitem label="JetBrains" %}

{% aside type="caution" title="Not Available" %}
This setting is not available in JetBrains IDEs. Move generator pattern customization is not currently supported.
{% /aside %}

{% /tabitem %}
{% /tabs %}

## Nx Cloud notifications

Controls which Nx Cloud notifications are displayed.

{% tabs syncKey="ide" %}
{% tabitem label="VSCode" %}

**Setting:** `nxConsole.nxCloudNotifications`

**Options:** `"all"` | `"errors"` | `"none"`

**Default:** `"all"`

```json
{
  "nxConsole.nxCloudNotifications": "errors"
}
```

**Options explained:**

- `"all"`: Show all Nx Cloud notifications
- `"errors"`: Only show error notifications
- `"none"`: Disable all Nx Cloud notifications

{% /tabitem %}
{% tabitem label="JetBrains" %}

**Location:** Settings > Tools > Nx Console > Nx Cloud Notifications

**Options:** All | Errors Only | None

**Default:** All

Navigate to **Settings/Preferences > Tools > Nx Console** and select the desired notification level from the "Nx Cloud Notifications" dropdown.

{% /tabitem %}
{% /tabs %}

## Show node version on startup

Shows a notification with the Node.js version information when the IDE starts.

{% tabs syncKey="ide" %}
{% tabitem label="VSCode" %}

**Setting:** `nxConsole.showNodeVersionOnStartup`

**Default:** `false`

```json
{
  "nxConsole.showNodeVersionOnStartup": true
}
```

Useful for debugging version-related issues, especially when using nvm or similar Node version managers.

{% /tabitem %}
{% tabitem label="JetBrains" %}

{% aside type="caution" title="Not Available" %}
This setting is not available in JetBrains IDEs. Node version management is handled through the IDE's Node.js interpreter settings (**Settings > Languages & Frameworks > Node.js**).
{% /aside %}

{% /tabitem %}
{% /tabs %}

## MCP port

Specifies a fixed port for the Nx MCP (Model Context Protocol) server.

{% tabs syncKey="ide" %}
{% tabitem label="VSCode" %}

**Setting:** `nxConsole.mcpPort`

**Default:** `undefined` (random port)

```json
{
  "nxConsole.mcpPort": 3333
}
```

Set to `0` to explicitly use a random available port. If not specified, a random port is used by default.

{% /tabitem %}
{% tabitem label="JetBrains" %}

{% aside type="caution" title="Not Available" %}
This setting is not available in JetBrains IDEs. MCP port configuration is not currently supported.
{% /aside %}

{% /tabitem %}
{% /tabs %}

## MCP tools filter

Filters which MCP tools are enabled using glob patterns with negation support.

{% tabs syncKey="ide" %}
{% tabitem label="VSCode" %}

**Setting:** `nxConsole.mcpToolsFilter`

**Default:** `[]` (all tools enabled)

```json
{
  "nxConsole.mcpToolsFilter": ["nx_*", "!nx_cloud_*"]
}
```

Use glob patterns to include or exclude specific MCP tools. Prefix with `!` to negate a pattern (exclude matching tools).

{% /tabitem %}
{% tabitem label="JetBrains" %}

{% aside type="caution" title="Not Available" %}
This setting is not available in JetBrains IDEs. MCP tools filtering is not currently supported.
{% /aside %}

{% /tabitem %}
{% /tabs %}

## Enable debug logging

Activates debug logging in output channels and the Language Server.

{% tabs syncKey="ide" %}
{% tabitem label="VSCode" %}

**Setting:** `nxConsole.enableDebugLogging`

**Default:** `false`

```json
{
  "nxConsole.enableDebugLogging": true
}
```

Useful for troubleshooting Nx Console issues. When enabled, detailed debug information is written to the output channels.

{% /tabitem %}
{% tabitem label="JetBrains" %}

{% aside type="caution" title="Not Available" %}
This setting is not available in JetBrains IDEs. Debug logging configuration is handled through the IDE's native logging system.
{% /aside %}

{% /tabitem %}
{% /tabs %}

## Disable file watching

Disables automatic workspace refresh after file changes in the Language Server.

{% tabs syncKey="ide" %}
{% tabitem label="VSCode" %}

**Setting:** `nxConsole.disableFileWatching`

**Default:** `false`

```json
{
  "nxConsole.disableFileWatching": true
}
```

When enabled, the workspace will not automatically refresh when files change. This can be useful for performance optimization in very large workspaces, but you will need to manually refresh the workspace to see changes.

{% /tabitem %}
{% tabitem label="JetBrains" %}

{% aside type="caution" title="Not Available" %}
This setting is not available in JetBrains IDEs. File watching behavior is managed by the IDE's native file system watcher.
{% /aside %}

{% /tabitem %}
{% /tabs %}

## Common configuration scenarios

### Team configuration for specific framework

If your team works primarily with React and Next.js:

{% tabs syncKey="ide" %}
{% tabitem label="VSCode" %}

Add to `.vscode/settings.json`:

```json
{
  "nxConsole.generatorAllowlist": [
    "@nx/react:*",
    "@nx/next:*",
    "@nx/workspace:library"
  ],
  "nxConsole.generatorBlocklist": [
    "*:stories",
    "*:cypress-component-configuration"
  ],
  "nxConsole.projectViewingStyle": "tree",
  "nxConsole.enableTaskExecutionDryRunOnChange": true,
  "nxConsole.nxCloudNotifications": "errors"
}
```

{% /tabitem %}
{% tabitem label="JetBrains" %}

Navigate to **Settings > Tools > Nx Console** and configure:

**Generator Allowlist:**

```text
@nx/react:*
@nx/next:*
@nx/workspace:library
```

**Generator Blocklist:**

```text
*:stories
*:cypress-component-configuration
```

**Nx Cloud Notifications:** Errors Only

**Enable Dry Run on Change:** Checked

{% /tabitem %}
{% /tabs %}

### Nested workspace setup

For monorepos where Nx is nested within a larger repository:

{% tabs syncKey="ide" %}
{% tabitem label="VSCode" %}

```json
{
  "nxConsole.nxWorkspacePath": "packages/my-workspace"
}
```

{% /tabitem %}
{% tabitem label="JetBrains" %}

**Nx Workspace Path:** `packages/my-workspace`

{% /tabitem %}
{% /tabs %}

### Minimal noise configuration

To reduce notifications and automatic behaviors:

{% tabs syncKey="ide" %}
{% tabitem label="VSCode" %}

```json
{
  "nxConsole.nxCloudNotifications": "errors",
  "nxConsole.enableTaskExecutionDryRunOnChange": false,
  "nxConsole.enableCodeLens": false
}
```

{% /tabitem %}
{% tabitem label="JetBrains" %}

**Nx Cloud Notifications:** Errors Only

**Enable Dry Run on Change:** Unchecked

{% /tabitem %}
{% /tabs %}

## See also

- [Nx Console Overview](/docs/guides/nx-console)
- [Nx Console Generate Command](/docs/guides/nx-console/console-generate-command)
- [Nx Console Run Command](/docs/guides/nx-console/console-run-command)
- [Nx Console Troubleshooting](/docs/guides/nx-console/console-troubleshooting)

---
<!-- source: https://nx.dev/docs/reference/nx-json.md -->
## nx.json Reference

The `nx.json` file configures the Nx CLI and project defaults. The full [machine readable schema](https://github.com/nrwl/nx/blob/master/packages/nx/schemas/nx-schema.json) is available on GitHub.

{% aside type="note" title="Nx 22 Changes" %}
Release tag configuration now uses a nested `releaseTag` object (e.g., `releaseTag.pattern` instead of `releaseTagPattern`). Old properties work until Nx 23.

See [Release Tag](#release-tag) for details.
{% /aside %}

The following is an expanded example showing all options. Your `nx.json` will likely be much shorter.

```json
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/eslint/plugin",
      "options": {
        "targetName": "lint"
      }
    }
  ],
  "parallel": 4,
  "cacheDirectory": "tmp/my-nx-cache",
  "defaultBase": "main",
  "namedInputs": {
    "default": ["{projectRoot}/**/*"],
    "production": ["!{projectRoot}/**/*.spec.tsx"]
  },
  "targetDefaults": {
    "@nx/js:tsc": {
      "inputs": ["production", "^production"],
      "dependsOn": ["^build"],
      "options": {
        "main": "{projectRoot}/src/index.ts"
      },
      "cache": true
    },
    "test": {
      "cache": true,
      "inputs": ["default", "^production", "{workspaceRoot}/jest.preset.js"],
      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
      "executor": "@nx/jest:jest"
    }
  },
  "release": {
    "version": {
      "conventionalCommits": true
    },
    "changelog": {
      "git": {
        "commit": true,
        "tag": true
      },
      "workspaceChangelog": {
        "createRelease": "github"
      },
      "projectChangelogs": true
    }
  },
  "sync": {
    "globalGenerators": ["my-plugin:my-sync-generator"]
  },
  "generators": {
    "@nx/js:library": {
      "buildable": true
    }
  },
  "extends": "nx/presets/npm.json",
  "tui": {
    "enabled": true,
    "autoExit": true
  },
  "conformance": {
    "rules": [
      {
        "rule": "@nx/conformance/enforce-module-boundaries",
        "status": "evaluated"
      },
      {
        "rule": "./tools/local-conformance-rules/check-project.ts",
        "projects": ["*"]
      }
    ]
  },
  "analytics": true
}
```

## Plugins

Nx plugins improve the experience of using different tools with Nx. One key feature of plugins is that they can [automatically configure the way Nx runs tasks](/docs/concepts/inferred-tasks) for a tool based on that tool's configuration. In order for a plugin to configure tasks for Nx, it needs to be registered in the `plugins` array. If a plugin has no options, it can be listed as a string. Otherwise, it should be listed as an object with a `plugin` property and an `options` property.

Every plugin behaves differently, so consult the plugin's own documentation for information about what it does. You can browse the [plugin registry](/docs/plugin-registry) for available plugins.

To learn about creating your own plugin read about [extending Nx](/docs/extending-nx/intro).

```json
// nx.json
{
  "plugins": [
    "@my-org/graph-plugin",
    {
      "plugin": "@nx/eslint/plugin",
      "options": {
        "targetName": "lint"
      }
    }
  ]
}
```

### Scope plugins to specific projects

Plugins use config files to infer tasks for projects. You can specify which config files are processed by Nx plugins using the `include` and `exclude` properties in the plugin configuration object.

```jsonc
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/jest/plugin",
      "include": ["packages/**/*"], // include any projects in the packages folder
      "exclude": ["**/*-e2e/**/*"], // exclude any projects in a *-e2e folder
    },
  ],
}
```

The `include` and `exclude` properties are each file glob patterns that are used to include or exclude the configuration file that the plugin is interpreting. In the example provided, the `@nx/jest/plugin` plugin will only infer tasks for projects where the `jest.config.ts` file path matches the `packages/**/*` glob but does not match the `**/*-e2e/**/*` glob.

#### Using negation patterns

You can use negation patterns (patterns starting with `!`) to create more precise include/exclude rules. Patterns are processed in order, with later patterns overriding earlier ones.

**Example: Excluding all e2e projects except one**

```jsonc
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/jest/plugin",
      "exclude": ["**/*-e2e/**/*", "!**/toolkit-workspace-e2e/**/*"],
    },
  ],
}
```

This will exclude all e2e projects except `toolkit-workspace-e2e`.

**Example: Including packages except legacy ones**

```jsonc
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/vite/plugin",
      "include": ["packages/**/*", "!packages/legacy/**/*"],
    },
  ],
}
```

**How negation patterns work:**

- Patterns are processed in order from first to last
- A pattern starting with `!` removes files from the match set
- A pattern without `!` adds files to the match set
- The last matching pattern determines if a file is included
- If the first pattern is a negation, all files are matched initially

## Task options

The following properties affect the way Nx runs tasks and can be set at the root of `nx.json`.

| Property                | Description                                                                                                                                                                                                                                                                                                                             |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| parallel                | defines the max number of targets run in parallel                                                                                                                                                                                                                                                                                       |
| captureStderr           | defines whether the cache captures stderr or just stdout                                                                                                                                                                                                                                                                                |
| skipNxCache             | defines whether the Nx Cache should be skipped (defaults to `false`)                                                                                                                                                                                                                                                                    |
| cacheDirectory          | defines where the local cache is stored (defaults to `.nx/cache`)                                                                                                                                                                                                                                                                       |
| encryptionKey           | (when using `"nx-cloud"` only) defines an encryption key to support end-to-end encryption of your cloud cache. You may also provide an environment variable with the key `NX_CLOUD_ENCRYPTION_KEY` that contains an encryption key as its value. The Nx Cloud task runner normalizes the key length, so any length of key is acceptable |
| selectivelyHashTsConfig | only hash the path mapping of the active project in the `tsconfig.base.json` (e.g., adding/removing projects doesn't affect the hash of existing projects) (defaults to `false`)                                                                                                                                                        |

You can configure `parallel` in `nx.json`, but you can also set a `--parallel` flag in the terminal `nx run-many -t test --parallel=5`.

## Default base

Tells Nx which base branch to use when calculating affected projects.

- `defaultBase` defines the default base branch, defaults to `main`.

## Target defaults

Target defaults provide ways to set common options for a particular target in your workspace. When building your project's configuration, we merge it with up to 1 default from this map. For a given target, we look at its name and its executor. We then check target defaults looking for a configuration whose key matches any of the following:

- `` `${executor}` ``
- `` `${targetName}` `` (if the configuration specifies the executor, this needs to match the target's executor as well)

Additionally, if there is not a match for either of the above, we look for other keys that may match the target name via a glob pattern. For example, a key in the target defaults that looks like `e2e-ci--**/**` would match all of the targets created by a task atomizer plugin.

Target defaults matching the executor takes precedence over those matching the target name. If we find a target default for a given target, we use it as the base for that target's configuration.

{% aside type="caution" title="Beware" %}
When using a target name as the key of a target default, make sure all the targets with that name use the same executor or that the target defaults you're setting make sense to all targets regardless of the executor they use. Anything set in a target default will also override the configuration of [tasks inferred by plugins](/docs/concepts/inferred-tasks).
{% /aside %}

Some common scenarios for this follow.

### inputs & namedInputs

Named inputs defined in `nx.json` are merged with the named inputs defined in [project level configuration](/docs/reference/project-configuration). In other words, every project has a set of named inputs, and it's defined as: `{...namedInputsFromNxJson, ...namedInputsFromProjectsProjectJson}`.

Defining `inputs` for a given target would replace the set of inputs for that target name defined in `nx.json`.
Using pseudocode `inputs = projectJson.targets.build.inputs || nxJson.targetDefaults.build.inputs`.

You can also define and redefine named inputs. This enables one key use case, where your `nx.json` can define things like this (which applies to every project):

```json
// nx.json
{
  "targetDefaults": {
    "test": {
      "inputs": ["default", "^production"]
    }
  }
}
```

And projects can define their `production` inputs, without having to redefine the inputs for the `test` target.

```json
// project.json
{
  "namedInputs": {
    "production": ["default", "!{projectRoot}/**/*.test.js"]
  }
}
```

In this case Nx will use the right `production` input for each project.

{% cardgrid %}
{% linkcard title="Inputs and Named Inputs Reference" description="Learn about all the possible settings for `inputs` and `namedInputs`" href="/docs/reference/inputs" /%}
{% linkcard title="Configure Inputs for Task Caching" description="This recipes walks you through a few examples of how to configure `inputs` and `namedInputs`" href="/docs/guides/tasks--caching/configure-inputs" /%}
{% /cardgrid %}

### Task pipelines

Targets can depend on other targets. A common scenario is having to build dependencies of a project first before
building the project. The `dependsOn` property in `project.json` can be used to define the list of dependencies of an
individual target.

Often the same `dependsOn` configuration has to be defined for every project in the repo, and that's when
defining `targetDefaults` in `nx.json` is helpful.

```json
// nx.json
{
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}
```

The configuration above is identical to adding `{"dependsOn": ["^build"]}` to every `build` target of every project.

{% cardgrid %}
{% linkcard title="Project Configuration reference" description="For full documentation of the `dependsOn` property, see the project configuration reference" href="/docs/reference/project-configuration#dependson" /%}
{% linkcard title="What is a Task Pipeline" description="This guide describes how to think about task pipelines" href="/docs/concepts/task-pipeline-configuration" /%}
{% /cardgrid %}

### Outputs

Another target default you can configure is `outputs`:

```json
// nx.json
{
  "targetDefaults": {
    "build": {
      "outputs": ["{projectRoot}/custom-dist"]
    }
  }
}
```

When defining any options or configurations inside of a target default, you may use the `{workspaceRoot}` and `{projectRoot}` tokens. This is useful for defining options whose values are paths.

```json
// nx.json
{
  "targetDefaults": {
    "@nx/js:tsc": {
      "options": {
        "main": "{projectRoot}/src/index.ts"
      },
      "configurations": {
        "prod": {
          "tsconfig": "{projectRoot}/tsconfig.prod.json"
        }
      },
      "inputs": ["prod"],
      "outputs": ["{workspaceRoot}/{projectRoot}"]
    },
    "build": {
      "inputs": ["prod"],
      "outputs": ["{workspaceRoot}/{projectRoot}"],
      "cache": true
    }
  }
}
```

#### Target default priority

Note that the inputs and outputs are specified on both the `@nx/js:tsc` and `build` default configurations. This is **required**, as when reading target defaults Nx will only ever look at one key. If there is a default configuration based on the executor used, it will be read first. If not, Nx will fall back to looking at the configuration based on target name. For instance, running `nx build project` will read the options from `targetDefaults[@nx/js:tsc]` if the target configuration for `build` uses the `@nx/js:tsc executor`. It **would not** read any of the configuration from the `build` target default configuration unless the executor does not match.

{% cardgrid %}
{% linkcard title="Configure Outputs for Task Caching" description="This recipe walks you through how to set outputs" href="/docs/guides/tasks--caching/configure-outputs" /%}
{% /cardgrid %}

### Cache

In Nx 17 and higher, caching is configured by specifying `"cache": true` in a target's configuration. This will tell Nx that it's ok to cache the results of a given target. For instance, if you have a target that runs tests, you can specify `"cache": true` in the target default configuration for `test` and Nx will cache the results of running tests.

```json
// nx.json
{
  "targetDefaults": {
    "test": {
      "cache": true
    }
  }
}
```

{% aside type="caution" title="Per Project Caching + Distribution" %}

If you are using distributed task execution and disable caching for a given target, you will not be able to use distributed task execution for that target. This is because distributed task execution requires caching to be enabled. This means that the target you have disabled caching for, and any targets which depend on that target will fail the pipeline if you try to run them with Nx Agents enabled.

{% /aside %}

### Executor/command options

You can configure options specific to a target's executor. As an example, if your repo has projects using the `@nx/js:tsc` executor, you can provide some default options as follows:

```json
// nx.json
{
  "targetDefaults": {
    "@nx/js:tsc": {
      "options": {
        "generateExportsField": true
      }
    }
  }
}
```

You can also provide defaults for [inferred targets](/docs/concepts/inferred-tasks) or targets running a command using the `nx:run-commands` executor. As an example, if your repo has projects where **all the `build` targets** run the same `vite build` command, you can provide some default options as follows:

```json
// nx.json
{
  "targetDefaults": {
    "build": {
      "options": {
        "assetsInlineLimit": 2048,
        "assetsDir": "static/assets"
      }
    }
  }
}
```

{% aside type="caution" title="Be careful" %}
If multiple targets with the same name run different commands (or use different executors), do not set options in `targetDefaults`. Different commands would accept different options, and the target defaults will apply to all targets with the same name regardless of the command they run. If you were to provide options in `targetDefaults` for them, the commands that don't expect those options could throw an error.
{% /aside %}

For more details on how to pass args to the underlying command see the [Pass Args to Commands recipe](/docs/guides/tasks--caching/pass-args-to-commands).

### Task atomizer configuration

Task Atomizer plugins create several targets with a similar pattern. For example, the `@nx/cypress` plugin creates a top level `e2e-ci` target and a target for each test file that looks like `e2e-ci--test/my/test.spec.ts`. To avoid having to write a target default for each of these targets, you can use a glob pattern in the target default key.

```json
// nx.json
{
  "targetDefaults": {
    "e2e-ci--**/**": {
      "options": {
        "headless": true
      }
    }
  }
}
```

{% aside type="note" title="Pattern Matching" %}
Nx uses glob patterns to match against the target name. This means that the `**/**` pattern above is required because tests can be nested within a directory which would make the target name contain a `/`. If your target name does not contain a `/`, you can use a simpler pattern like `e2e-ci-*`.
{% /aside %}

## Release

The `release` property in `nx.json` configures the `nx release` command. It is an optional property, as `nx release` is capable of working with zero config, but when present it is used to configure the versioning, changelog, and publishing phases of the release process.

For more information on how `nx release` works, see [manage releases](/docs/features/manage-releases).

The full list of configuration options available for `"release"` can be found here: [https://github.com/nrwl/nx/blob/master/packages/nx/src/config/nx-json.ts](https://github.com/nrwl/nx/blob/master/packages/nx/src/config/nx-json.ts) under `NxReleaseConfiguration`.

### Projects

If you want to limit the projects that `nx release` targets, you can use the `projects` property in `nx.json` to do so. This property is either a string, or an array of strings. The strings can be project names, glob patterns, directories, tag references or anything else that is supported by the `--projects` filter you may know from other commands such as `nx run`.

```jsonc
// nx.json
{
  "release": {
    // Here we are configuring nx release to target all projects
    // except the one called "ignore-me"
    "projects": ["*", "!ignore-me"],
  },
}
```

### Projects relationship

The `projectsRelationship` property tells Nx whether to release projects independently or together. By default Nx will release all your projects together in lock step, which is an equivalent of `"projectRelationships": "fixed"`. If you want to release projects independently, you can set `"projectsRelationship": "independent"`.

```jsonc
// nx.json
{
  "release": {
    // Here we are configuring nx release to release projects
    // independently, as opposed to the default of "fixed"
    "projectsRelationship": "independent",
  },
}
```

### Release tag

The `releaseTag` property controls how git tags are parsed and generated. By default tags conform to semantic version and are validated as such.

{% aside type="note" title="Nx 22 Changes" %}
Release tag configuration now uses a nested `releaseTag` object. Old flat properties (`releaseTagPattern`, etc.) are deprecated but work until Nx 23.

**Nx 22+:** `releaseTag.pattern`, `releaseTag.requireSemver`, `releaseTag.strictPreid`

**Nx < 22:** `releaseTagPattern`, `releaseTagPatternRequireSemver`, `releaseTagPatternStrictPreid`
{% /aside %}

#### Configuration options

| Property                 | Type                | Default                                                           | Description                                                                                                                                                                                                                                                                                           |
| ------------------------ | ------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **pattern**              | string              | `v{version}` for fixed, `{projectName}@{version}` for independent | The git tag pattern to use. Supports interpolation of `{version}`, `{projectName}`, and `{releaseGroupName}`                                                                                                                                                                                          |
| **requireSemver**        | boolean             | `false`                                                           | Whether to require that all tags match semantic versioning                                                                                                                                                                                                                                            |
| **strictPreid**          | boolean             | `false` for independent, `true` for fixed release groups          | Whether to ensure prerelease IDs are consistent across packages                                                                                                                                                                                                                                       |
| **preferDockerVersion**  | boolean             | `false`                                                           | Whether to prefer Docker-compatible version format in git tags                                                                                                                                                                                                                                        |
| **checkAllBranchesWhen** | boolean \| string[] | undefined                                                         | Controls whether to check all branches or only merged branches when resolving current versions from git tags. `true` = always check all branches, `false` = only check the current branch, `string[]` = check all branches when the current branch matches any of the provided names or glob patterns |

#### Branch resolution for git tags

The `checkAllBranchesWhen` option controls how Nx resolves existing git tags to determine the current version of your projects.

By default, Nx checks for matching tags on the current branch. If no tags are found, it falls back to checking all branches.

| Value      | Behavior                                                                                                                                                                  |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `true`     | Always check all branches for the latest matching tag                                                                                                                     |
| `false`    | Only check the current branch (no fallback to all branches)                                                                                                               |
| `string[]` | Check all branches when the current branch matches any of the provided names or [glob patterns](https://github.com/isaacs/minimatch). Otherwise, use the default behavior |

This option is useful when release tags may exist on multiple branches. Setting `checkAllBranchesWhen` to `true` or to a list of branch patterns ensures Nx finds the latest tag regardless of which branch it was created on.

#### Tag pattern syntax

The tag pattern supports interpolating the following values:

- `{version}` - The version currently being released
- `{projectName}` - The name of the project being released (for independent releases)
- `{releaseGroupName}` - The name of the release group being released (when using release groups)

Example patterns and their results:

- `v{version}` → `v1.0.0` (default for fixed releases)
- `{projectName}@{version}` → `my-lib@1.0.0` (default for independent releases)
- `{releaseGroupName}/{projectName}/{version}` → `backend/api/1.0.0`
- `release/{version}` → `release/1.0.0`

#### Example configuration

{% tabs syncKey="nx-release-configuration" %}
{% tabitem label="Nx 22+" %}

```jsonc
// nx.json
{
  "release": {
    "releaseTag": {
      "pattern": "{releaseGroupName}-v{version}",
      "requireSemver": true,
      "strictPreid": true,
      "preferDockerVersion": false,
      "checkAllBranchesWhen": ["main", "release/*"],
    },
  },
}
```

{% /tabitem %}
{% tabitem label="Nx < 22" %}

```jsonc
// nx.json
{
  "release": {
    "releaseTagPattern": "{releaseGroupName}-v{version}",
    "releaseTagPatternRequireSemver": true,
    "releaseTagPatternStrictPreid": true,
    "releaseTagPatternPreferDockerVersion": false,
    "releaseTagPatternCheckAllBranchesWhen": ["main", "release/*"],
  },
}
```

{% /tabitem %}
{% /tabs %}

### Version

The `version` property configures the versioning phase of the release process. It is used to determine the next version of your projects, and update any projects that depend on them to use the new version.

{% aside type="note" title="Breaking Changes in Nx v22" %}
In Nx v22, the legacy versioning implementation was removed entirely. This had been deprecated since Nx 21.
An automated migration was provided in Nx v21 to update your configuration to the new format when running `nx migrate`.

For Nx 22, this automated migration was re-added to allow updating your configuration by running `nx migrate`.
{% /aside %}

Behind the scenes, ecosystem-specific `version` logic is powered by a `VersionActions` implementation. Out of the box Nx wires up the most widely applicable `VersionActions` implementation for you, which is `@nx/js/src/release/version-actions` provided by the `@nx/js` plugin.

{% aside type="note" title="Programmatic API (Nx 22+)" %}
For advanced use cases, the `ReleaseClient` programmatic API allows you to trigger releases from custom scripts. In Nx 22+, you can optionally ignore the `nx.json` release configuration entirely when using the API, which is useful for ad-hoc scripts that only work with a subset of the repository.
{% /aside %}

Core version options are therefore directly at the top level of the `version` property (as of Nx v21), while ecosystem-specific options are available through `versionActionsOptions`:

```jsonc
// nx.json
{
  "release": {
    "version": {
      // Core options
      "conventionalCommits": true,
      "manifestRootsToUpdate": ["dist/packages/{projectName}"],
      // Ecosystem-specific options
      "versionActionsOptions": {
        "skipLockFileUpdate": true,
      },
    },
  },
}
```

Some important changes in Nx 22:

- `preserveMatchingDependencyRanges` now defaults to `true` (previously `false`)
  - When `true`, dependency version ranges are preserved if they already satisfy the new version being released
  - Example: If releasing version `1.2.0` and a dependent has range `^1.0.0`, it remains `^1.0.0` instead of being updated to `1.2.0`
  - Set to `false` explicitly if you need exact versions in all dependents
- `updateDependents` now defaults to `"always"` (previously `"auto"`)
  - `"always"`: Update dependents wherever they exist in the graph, regardless of filter selection
  - `"auto"`: Update dependents only if they're within the selected projects or release groups
  - `"never"`: Never update dependents
- `releaseTag*` properties such as `releaseTagPattern` and `releaseTagPatternStrictPreid` have been coalesced into a single `releaseTag` object. (`releaseTagPattern` -> `releaseTag.pattern`, `releaseTagPatternStrictPreid` -> `releaseTag.strictPreid`)
- `releaseTag.strictPreid` now defaults to `true`
- Fixed Release Group Release Tag Pattern now defaults to `{releaseGroupName}-v{version}`

### Changelog

The `changelog` property configures the changelog phase of the release process. It is used to generate a changelog for your projects, and commit it to your repository.

There are two types of possible changelog that can be generated:

- **Workspace Changelog**: A changelog that contains all changes across all projects in your workspace. This is not applicable when releasing projects independently.

- **Project Changelogs**: A changelog that contains all changes for a given project.

The `changelog` property is used to configure both of these changelogs.

#### Workspace changelog

The `changelog.workspaceChangelog` property configures the workspace changelog. It is used to determine if and how the workspace changelog is generated.

```jsonc
// nx.json
{
  "release": {
    "changelog": {
      // This disables the workspace changelog
      "workspaceChangelog": false,
    },
  },
}
```

```jsonc
// nx.json
{
  "release": {
    "changelog": {
      "workspaceChangelog": {
        // This will create a GitHub release containing the workspace
        // changelog contents
        "createRelease": "github",
        // This will disable creating a workspace CHANGELOG.md file
        "file": false,
      },
    },
  },
}
```

#### Project changelogs

The `changelog.projectChangelogs` property configures the project changelogs. It is used to determine if and how the project changelogs are generated.

```jsonc
// nx.json
{
  "release": {
    "changelog": {
      // This enables project changelogs with the default options
      "projectChangelogs": true,
    },
  },
}
```

```jsonc
// nx.json
{
  "release": {
    "changelog": {
      "projectChangelogs": {
        // This will create one GitHub release per project containing
        // the project changelog contents
        "createRelease": "github",
        // This will disable creating any project level CHANGELOG.md
        // files
        "file": false,
      },
    },
  },
}
```

#### Replace existing contents {% badge  text="Nx 22+" /%}

By default, changelog entries are prepended to existing changelog files. To completely replace the entire changelog file contents instead, use the `replaceExistingContents` option:

```jsonc
// nx.json
{
  "release": {
    "changelog": {
      "workspaceChangelog": {
        // Replaces the entire CHANGELOG.md file with the new content
        "replaceExistingContents": true,
      },
    },
  },
}
```

This option is available for both `workspaceChangelog` and `projectChangelogs`. It's useful when you want to regenerate the entire changelog from scratch rather than maintaining a cumulative history.

### Git

The `git` property configures the automated git operations that take place as part of the release process.

```jsonc
// nx.json
{
  "release": {
    "git": {
      // This will enable committing any changes (e.g. package.json
      // updates, CHANGELOG.md files) to git
      "commit": true,
      // This will enable create a git for the overall release, or
      // one tag per project for independent project releases
      "tag": false,
    },
  },
}
```

### Docker {% badge  text="experimental" /%}

{% aside type="caution" title="Experimental Feature" %}
Docker support in Nx is currently experimental and may undergo breaking changes without following semantic versioning.
{% /aside %}

The `docker` property configures Docker image versioning and publishing when using `nx release`. This enables calendar-based versioning schemes and automated Docker registry publishing as part of your release workflow.

```jsonc
// nx.json
{
  "release": {
    // Simple configuration - enables Docker with defaults
    "docker": true,
  },
}
```

```jsonc
// nx.json
{
  "release": {
    "docker": {
      // Run this command before versioning Docker images
      "preVersionCommand": "npx nx run-many -t docker:build",

      // Define versioning schemes for different environments
      "versionSchemes": {
        "production": "{currentDate|YYMM.DD}.{shortCommitSha}",
        "hotfix": "{currentDate|YYMM.DD}.{shortCommitSha}-hotfix",
        "staging": "{currentDate|YYMM.DD}-staging",
        "development": "{currentDate|YYMM.DD}-dev-{shortCommitSha}",
      },

      // Skip Docker versioning for these projects to prevent versioning with other tools like NPM
      // Only set this if you are not using {versionActionsVersion} in your docker version scheme
      "skipVersionActions": ["api"],

      // Default Docker repository name (can be overridden per project)
      "repositoryName": "myorg",

      // Docker registry URL
      "registryUrl": "docker.io",
    },
  },
}
```

Read more about it in the [Release Docker Images guide](/docs/guides/nx-release/release-docker-images).

#### Docker plugin options

When configuring the `@nx/docker` plugin in `nx.json`, you can customize the behavior of Docker build and run targets. One important option is `skipDefaultTag`:

```jsonc
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/docker/plugin",
      "options": {
        "buildTarget": {
          "name": "docker:build",
          // Skip the default --tag argument
          "skipDefaultTag": true,
          // You must provide your own tags via args
          "args": ["--tag myorg/myapp:latest", "--tag myorg/myapp:1.0.0"],
        },
      },
    },
  ],
}
```

**Important:** Setting `skipDefaultTag: true` opts out of Nx Release support for that project. When you explicitly manage your own Docker tags via the `args` property, the automatic versioning and publishing features of `nx release` will not work for those Docker projects. Only use `skipDefaultTag: true` if you are not using `nx release` to manage your Docker image versions.

If you want to use `nx release` with Docker projects, leave `skipDefaultTag` as `false` (the default) or omit it entirely.

#### Version scheme syntax

Docker version schemes support calendar-based patterns using the following placeholders:

- `{projectName}` - The name of the project being released
- `{currentDate}` - Current date in ISO format (e.g., 2025-01-30T14:30:00Z)
- `{currentDate|FORMAT}` - Current date with custom format using these tokens:
  - `YYYY` - 4-digit year (e.g., 2025)
  - `YY` - 2-digit year (e.g., 25)
  - `MM` - 2-digit month (01-12)
  - `DD` - 2-digit day (01-31)
  - `HH` - 2-digit hour in 24-hour format (00-23)
  - `mm` - 2-digit minutes (00-59)
  - `ss` - 2-digit seconds (00-59)
- `{shortCommitSha}` - First 7 characters of the current commit SHA
- `{commitSha}` - Full commit SHA
- `{versionActionsVersion}` - The version generated during the version actions such as "1.2.3"

Example patterns:

- `{currentDate|YYMM.DD}.{shortCommitSha}` - Results in: 2501.30.a1b2c3d
- `{projectName}-{currentDate|YYYY.MM.DD}` - Results in: api-2025.01.30
- `{currentDate|YY.MM.DD.HHmm}-{commitSha}` - Results in: 25.01.30.1430-abcdef1234567890
- `{projectName}-{versionActionsVersion}` - Results in: api-1.2.3

#### Group-level Docker configuration

You can configure [Docker release](/docs/guides/nx-release/release-docker-images) settings at the release group level:

```jsonc
// nx.json
{
  "release": {
    "groups": {
      "backend": {
        "projects": ["api"],
        "projectsRelationship": "independent",
        "docker": {
          // Only set this to true if you are not using {versionActionsVersion} in your docker version scheme
          "skipVersionActions": true
          // Run a script before tagging Docker version
          "groupPreVersionCommand": "echo Preparing backend release",
        },
        "changelog": {
          "projectChangelogs": true
        }
      }
    }
  }
}
```

This allows you to have other releases such as [NPM](/docs/guides/nx-release/release-npm-packages) or [Rust crates](/docs/guides/nx-release/publish-rust-crates) in the same workspace.

## Sync

These are global configuration options for the [`nx sync`](/docs/reference/nx-commands#nx-sync) command. The `nx sync` command runs all global and task-specific [sync generators](/docs/concepts/sync-generators) to ensure that your files are in the correct state to run tasks or start the CI process.

```jsonc
// nx.json
{
  "sync": {
    "applyChanges": true,
    "globalGenerators": ["my-plugin:my-sync-generator"],
    "generatorOptions": {
      "my-plugin:my-sync-generator": {
        "verbose": true,
      },
    },
    "disabledTaskSyncGenerators": ["other-plugin:problematic-generator"],
  },
}
```

| Property                       | Description                                                                                                                                                                                                                                                                                  |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **applyChanges**               | Whether to automatically apply task sync generator changes when running tasks. If not set, the user will be prompted. If set to `true`, the user will not be prompted and the changes will be applied. If set to `false`, the user will not be prompted and the changes will not be applied. |
| **globalGenerators**           | Sync generators that are only run when the `nx sync` command is executed. These are not associated with a particular task.                                                                                                                                                                   |
| **generatorOptions**           | Options to be passed to sync generators                                                                                                                                                                                                                                                      |
| **disabledTaskSyncGenerators** | Globally disable specific task sync generators                                                                                                                                                                                                                                               |

## Generators

Default generator options can be configured in `nx.json`. For instance, the following tells Nx to always
pass `--buildable=true` when creating new libraries with the `@nx/js` plugin.

```json
// nx.json
{
  "generators": {
    "@nx/js:library": {
      "buildable": true
    }
  }
}
```

## Extends

Some presets use the `extends` property to hide some default options in a separate json file. The json file specified in the `extends` property is located in your `node_modules` folder. The Nx preset files are specified in [the `nx` package](https://github.com/nrwl/nx/tree/master/packages/nx/presets).

## Nx Cloud

There are also options for [Nx Cloud](https://nx.app) that are set in the `nx.json` file. For instance, you connect to the Nx Cloud service using an `nxCloudId` like this:

```json
// nx.json
{
  "nxCloudId": "SOMEID"
}
```

If connecting to a different Nx Cloud instance, you can define the `nxCloudUrl`:

> The default is `https://cloud.nx.app`

```json
// nx.json
"nxCloudUrl": "https://nx.custom-company-domain.net"
```

For more details on configuring Nx Cloud, see the [Nx Cloud Configuration Options page](/docs/reference/nx-cloud-cli).

## Max cache size

The `maxCacheSize` property in `nx.json` allows you to set a limit on the size of the local cache. If it is not set, Nx defaults to a maximum size of 10% of the size of the disk where the cache is stored, up to a maximum of 10GB. This means that if your disk is 100GB, the maximum cache size will be 10GB. If the cache exceeds the specified size, Nx removes the least recently used cache entries until the total size is below 90% of the specified limit.

You can also override this value using the `NX_MAX_CACHE_SIZE` environment variable, which accepts the same units and takes precedence over the `maxCacheSize` option in `nx.json`.

This behavior can be opted out by setting `maxCacheSize` to `0`.

Valid values for `maxCacheSize` can be specified in bytes, kilobytes (KB), megabytes (MB), or gigabytes (GB). For example, any of the following would be valid values:

| Value    | Description                                                      |
| -------- | ---------------------------------------------------------------- |
| `819200` | 819200 bytes (800 KB)                                            |
| `100MB`  | 100 megabytes (100 \* 1024 \* 1024 bytes)                        |
| `1GB`    | 1 gigabyte (1024 \* 1024 \* 1024 bytes)                          |
| `0`      | No limit on the local cache size (disables the cache size limit) |

```json
// nx.json
{
  "maxCacheSize": "0" // No limit on the local cache size
}
```

```json
// nx.json
{
  "maxCacheSize": "10GB" // Set the maximum cache size to 10 gigabytes
}
```

Regardless of the `maxCacheSize` setting, Nx will remove cache entries that have not been accessed in the last 7 days.

## TUI

The `tui` property in `nx.json` configures the [Terminal UI](/docs/guides/tasks--caching/terminal-ui). It allows you to enable or disable the TUI and configure its behavior.

```json
// nx.json
{
  "tui": {
    // Enable the Nx TUI
    "enabled": true,
    // Automatically exit the TUI when completed
    // Use a number to specify the seconds to keep the TUI open for after completion
    "autoExit": true
  }
}
```

## Conformance

The `conformance` property in `nx.json` configures the usage of [Nx Conformance](/docs/enterprise/conformance).

```jsonc
// nx.json
{
  "conformance": {
    "outputPath": "dist/conformance-result.json",
    "rules": [
      {
        "rule": "@nx/conformance/enforce-module-boundaries",
        "status": "evaluated",
        "explanation": "This rule ensures proper module boundaries are maintained across the workspace",
      },
      {
        "rule": "./tools/local-conformance-rules/check-project.ts",
        "projects": ["*"],
        "options": {
          "strictMode": true,
        },
      },
      {
        "rule": "nx-cloud://my-custom-rule",
        "projects": [
          "frontend-*",
          {
            "matcher": "backend-legacy",
            "explanation": "Legacy backend project is exempt until migration is complete",
          },
        ],
        "status": "enforced",
      },
    ],
  },
}
```

### Configuration options

| Property       | Type                | Description                                                                                                                                           |
| -------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **outputPath** | `string \| false`   | Optional path to write the conformance results to. Defaults to `"dist/conformance-result.json"`. Set to `false` to disable writing results to a file. |
| **rules**      | `Array<RuleConfig>` | List of conformance rules to apply to your workspace.                                                                                                 |

### Rule configuration

Each rule in the `rules` array can have the following properties:

| Property        | Type                                                        | Required | Description                                                                                                                                                                                              |
| --------------- | ----------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **rule**        | `string`                                                    | Yes      | Relative path to a local rule implementation, node_module path, or nx-cloud rule ID for Nx Cloud Enterprise (e.g., `"nx-cloud://my-rule"`).                                                              |
| **options**     | `Record<string, unknown>`                                   | No       | Rule-specific configuration options. The available options depend on the specific rule being used.                                                                                                       |
| **projects**    | `Array<string \| { matcher: string; explanation: string }>` | No       | Projects to apply the rule to. See [Projects](#projects-conformance) section below.                                                                                                                      |
| **explanation** | `string`                                                    | No       | Optional explanation to communicate to colleagues why this rule is enabled and important to the workspace.                                                                                               |
| **status**      | `"enforced" \| "evaluated" \| "disabled"`                   | No       | Override the default status of the rule (defaults to `"enforced"`). If set to `"evaluated"`, violations are reported but don't cause failures. If set to `"disabled"`, the rule is not evaluated at all. |

### Projects (Conformance)

If you want to limit the projects that a conformance rule applies to, you can use the `projects` property. This property accepts an array of strings which can be project names, glob patterns, directories, tag references or anything else that is supported by the `--projects` filter you may know from other commands such as `nx run`.

By default, the implied value is `["*"]` (all projects).

You can also use objects with `matcher` and `explanation` properties to document why specific projects are included or excluded from the rule.

```jsonc
{
  "rule": "my-rule",
  // Here we are configuring the rule to apply to all frontend projects
  // except the one called "frontend-legacy"
  "projects": ["frontend-*", "!frontend-legacy"],
}
```

```jsonc
{
  "rule": "my-rule",
  "projects": [
    "frontend-*",
    {
      "matcher": "!frontend-legacy",
      "explanation": "Exempt until migration to new architecture is complete",
    },
  ],
}
```

### Rule status values

- **enforced** (default): Rule violations will cause the conformance check to fail (exit code 1)
- **evaluated**: Rule violations are reported but don't cause failures (exit code 0)
- **disabled**: Rule is not evaluated at all

## Analytics

The `analytics` property controls whether Nx collects usage telemetry. When not set, Nx prompts you on first run in an interactive terminal.

```json
// nx.json
{
  "analytics": true
}
```

For more information, see [telemetry](/docs/reference/telemetry).

---
<!-- source: https://nx.dev/docs/reference/nx-mcp.md -->
## Nx MCP Server Reference

The Nx MCP server is a [Model Context Protocol](https://modelcontextprotocol.io/introduction) implementation that connects AI agents to systems they can't easily reach on their own: Nx Cloud CI pipelines, self-healing fixes, task monitoring, and up-to-date Nx documentation.

{% aside type="tip" title="Quick Setup" %}
To configure your Nx workspace for AI agents (MCP, skills, and more), run `npx nx configure-ai-agents`. See the [AI Integration guide](/docs/getting-started/ai-setup) for details.
{% /aside %}

{% aside type="note" title="MCP + Skills" %}
The Nx MCP server works best alongside [agent skills](/docs/features/enhance-ai). Skills handle domain knowledge — workspace exploration, code generation, task execution — while the MCP server provides connectivity to Nx Cloud and task monitoring. For background on this approach, see our blog post on [why we deleted most of our MCP tools](/blog/why-we-deleted-most-of-our-mcp-tools).
{% /aside %}

For an overview of how Nx enhances AI assistants and powerful use cases, see the [Enhance Your LLM](/docs/features/enhance-ai) guide.

## Installation

There are a few ways to setup the Nx MCP server.

### via .mcp.json

{% tabs syncKey="nx-version" %}
{% tabitem label="Nx >= 21.4" %}

```json
// .mcp.json
{
  "servers": {
    "nx-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["nx", "mcp"]
    }
  }
}
```

{% /tabitem %}
{% tabitem label="Nx < 21.4" %}

```json
// .mcp.json
{
  "servers": {
    "nx-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["nx-mcp@latest"]
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

### Via Nx Console extension

If you're using Cursor or VS Code, install the [Nx Console extension](/docs/getting-started/editor-setup) which automatically manages the MCP server for you.

## Client-specific setup

> If your preferred client is not listed, configure your client to run `npx nx mcp` (Nx >= 21.4) or `npx nx-mcp@latest` (older versions) to start the Nx MCP server.

### Claude code

{% tabs syncKey="nx-version" %}
{% tabitem label="Nx >= 21.4" %}

```shell
claude mcp add nx-mcp npx nx mcp
```

{% /tabitem %}
{% tabitem label="Nx < 21.4" %}

```shell
claude mcp add nx-mcp npx nx-mcp@latest
```

{% /tabitem %}
{% /tabs %}

### VS Code

{% tabs syncKey="nx-version" %}
{% tabitem label="Nx >= 21.4" %}

```shell
code --add-mcp '{"name":"nx-mcp","command":"npx","args":["nx","mcp"]}'
```

{% /tabitem %}
{% tabitem label="Nx < 21.4" %}

```shell
code --add-mcp '{"name":"nx-mcp","command":"npx","args":["nx-mcp"]}'
```

{% /tabitem %}
{% /tabs %}

Alternatively, configure it in your VS Code settings or use the Nx Console extension for automatic setup.

### Cursor

1. Install [Nx Console](/docs/getting-started/editor-setup) from the marketplace
2. You'll receive a notification to "Improve Copilot/AI agent with Nx-specific context"
3. Click "Yes" to configure the MCP server

If you miss the notification, run the `nx.configureMcpServer` command from the command palette (`Ctrl/Cmd + Shift + P`).

### JetBrains IDEs

1. Install [Nx Console](/docs/getting-started/editor-setup) from the marketplace
2. You'll receive a notification to "Improve Copilot/AI agent with Nx-specific context"
3. Click "Yes" to configure the MCP server

If you miss the notification, run the `Nx: Setup MCP Server` command from the command palette (`Ctrl/Cmd + Shift + A`).

## Command-line options

The `nx mcp` command (or `npx nx-mcp` for older versions) accepts the following options:

| Option                  | Alias | Description                                                                                                                         |
| ----------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `[workspacePath]`       | `-w`  | Path to the Nx workspace root. Defaults to the current working directory if not provided.                                           |
| `--transport <type>`    |       | Transport protocol to use: `stdio` (default), `sse`, or `http`                                                                      |
| `--port <port>`         | `-p`  | Port to use for the HTTP/SSE server (default: 9921). Only valid with `--transport sse` or `--transport http`.                       |
| `--tools <patterns...>` | `-t`  | Filter which tools are enabled. Accepts glob patterns including negation (e.g., `"*"`, `"!nx_docs"`, `"cloud_*"`)                   |
| `--minimal`             |       | Hide workspace analysis tools (default: `true`). Use `--no-minimal` to expose all tools. See [Minimal Mode](#minimal-mode-default). |
| `--disableTelemetry`    |       | Disable sending of telemetry data                                                                                                   |
| `--debugLogs`           |       | Enable debug logging                                                                                                                |
| `--help`                |       | Display help information                                                                                                            |

### HTTP transport

If you want to host the server instead of communicating via `stdio`, use the `--transport` and `--port` flags:

{% tabs syncKey="nx-version" %}
{% tabitem label="Nx >= 21.4" %}

```shell
npx nx mcp --transport sse --port 9921
```

{% /tabitem %}
{% tabitem label="Nx < 21.4" %}

```shell
npx nx-mcp@latest --transport sse --port 9921
```

{% /tabitem %}
{% /tabs %}

The HTTP transport supports multiple concurrent connections, allowing different clients to connect simultaneously with independent sessions.

### Filtering tools

You can limit which tools are available using the `--tools` option with glob patterns:

{% tabs syncKey="nx-version" %}
{% tabitem label="Nx >= 21.4" %}

```shell
# Enable all tools (default)
npx nx mcp --tools "*"

# Disable specific tools
npx nx mcp --tools "*" "!nx_docs"

# Enable only cloud analytics tools
npx nx mcp --tools "cloud_*"

# Enable workspace tools only
npx nx mcp --tools "nx_workspace" "nx_project_details" "nx_docs"
```

{% /tabitem %}
{% tabitem label="Nx < 21.4" %}

```shell
# Enable all tools (default)
npx nx-mcp@latest --tools "*"

# Disable specific tools
npx nx-mcp@latest --tools "*" "!nx_docs"

# Enable only cloud analytics tools
npx nx-mcp@latest --tools "cloud_*"

# Enable workspace tools only
npx nx-mcp@latest --tools "nx_workspace" "nx_project_details" "nx_docs"
```

{% /tabitem %}
{% /tabs %}

This is useful when you want to restrict the LLM's capabilities or reduce noise in the tool list.

### Minimal mode (Default)

By default, the MCP server runs in **minimal mode** (`--minimal`), which hides workspace analysis and generator tools. These capabilities are now handled more efficiently by [agent skills](/docs/features/enhance-ai), which provide domain knowledge as incrementally-loaded instructions rather than tool-call-based data dumps. This reduces token usage and keeps the tool list focused on what MCP does best: connectivity to Nx Cloud and running processes.

To restore all tools (e.g., for clients that don't support skills), pass `--no-minimal`:

{% tabs syncKey="nx-version" %}
{% tabitem label="Nx >= 21.4" %}

```shell
npx nx mcp --no-minimal
```

{% /tabitem %}
{% tabitem label="Nx < 21.4" %}

```shell
npx nx-mcp@latest --no-minimal
```

{% /tabitem %}
{% /tabs %}

When the Nx Console extension manages the MCP server in VS Code or Cursor, it automatically enables minimal mode if it detects that agent skills are installed in the workspace.

## Available tools

### Documentation tools

| Tool      | Description                                                                                       |
| --------- | ------------------------------------------------------------------------------------------------- |
| `nx_docs` | Returns documentation sections relevant to user queries about Nx configuration and best practices |

### Task monitoring tools

| Tool                               | Description                                                      |
| ---------------------------------- | ---------------------------------------------------------------- |
| `nx_current_running_tasks_details` | Lists currently running Nx TUI processes and their task statuses |
| `nx_current_running_task_output`   | Returns terminal output for specific running tasks               |

### Visualization tools

| Tool                 | Description                                                                                              |
| -------------------- | -------------------------------------------------------------------------------------------------------- |
| `nx_visualize_graph` | Opens interactive project or task graph visualizations (requires a running IDE instance with Nx Console) |

### Nx Cloud CI tools

These tools enable AI agents to interact with CI pipelines and self-healing capabilities:

| Tool                      | Description                                                                                                                                       |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ci_information`          | Retrieves CI pipeline execution information from Nx Cloud for the current branch. Returns pipeline status, failed tasks, and self-healing status. |
| `update_self_healing_fix` | Apply or reject a self-healing CI fix from Nx Cloud. Records the decision on the suggested fix.                                                   |

### Nx Cloud analytics tools

These tools provide analytics and insights into your CI/CD data:

| Tool                                         | Description                                                                                      |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `cloud_analytics_pipeline_executions_search` | Analyzes historical pipeline execution data to identify trends and patterns in CI/CD workflows   |
| `cloud_analytics_pipeline_execution_details` | Retrieves detailed data for a specific pipeline execution to investigate performance bottlenecks |
| `cloud_analytics_runs_search`                | Analyzes historical run data to track performance trends and team productivity patterns          |
| `cloud_analytics_run_details`                | Retrieves detailed data for a specific run to investigate command execution performance          |
| `cloud_analytics_tasks_search`               | Analyzes aggregated task performance statistics including success rates and cache hit rates      |
| `cloud_analytics_task_executions_search`     | Analyzes individual task execution data to investigate performance trends over time              |

### Extended tools (--no-minimal)

The following tools are hidden by default in minimal mode. They're available when running with `--no-minimal`, which is useful for AI clients that don't support skills or instruction files.

#### Workspace tools

| Tool                   | Description                                                                                                                         |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `nx_workspace`         | Returns a readable representation of the project graph and nx.json configuration. Also returns any project graph errors if present. |
| `nx_workspace_path`    | Returns the path to the Nx workspace root                                                                                           |
| `nx_project_details`   | Returns complete project configuration in JSON format for a specific project, including targets, dependencies, and metadata         |
| `nx_available_plugins` | Lists available Nx plugins from the core team and local workspace plugins                                                           |

#### Generator tools

| Tool                  | Description                                                                                               |
| --------------------- | --------------------------------------------------------------------------------------------------------- |
| `nx_generators`       | Returns a list of available code generators in your workspace                                             |
| `nx_generator_schema` | Returns the detailed JSON schema for a specific Nx generator, including all available options             |
| `nx_run_generator`    | Opens the Nx Console Generate UI with prefilled options (requires a running IDE instance with Nx Console) |

{% aside type="note" title="Tool Availability" %}
When no workspace path is specified, only the `nx_docs` tool will be available. Nx Cloud tools require a workspace connected to Nx Cloud.
{% /aside %}

## Available resources

When connected to an Nx Cloud-enabled workspace, the Nx MCP server automatically exposes recent CI Pipeline Executions (CIPEs) as MCP resources. Resources appear in your AI tool's resource picker, allowing the LLM to access detailed information about CI runs including:

- Failed tasks and their error messages
- Terminal output from task executions
- Affected files in the pipeline run
- Build timing and performance data

## Tool usage examples

### Accessing documentation

Get accurate guidance without hallucinations:

```text
How do I configure Nx release for conventional commits?
What are the caching options for tasks?
```

The `nx_docs` tool retrieves relevant, up-to-date documentation based on your query.

### Analyzing CI failures

When a CI build fails, your AI assistant can:

```text
What failed in my last CI run?
Help me fix the build error
```

Using the Nx Cloud tools, the AI can:

1. Access detailed information about the failed build
2. Retrieve terminal output from failed tasks
3. Understand what changed and suggest fixes

### Autonomous CI monitoring

With the `ci_information` and `update_self_healing_fix` tools, AI agents can monitor CI pipelines and interact with self-healing. For a ready-to-use implementation, see the [CI monitoring skill](/docs/features/enhance-ai#self-healing-ci-integration) in Claude Code:

```text
Monitor CI and fix any failures
```

The AI agent can:

1. Poll CI pipeline status via `ci_information`
2. Receive failure context and self-healing suggestions
3. Apply verified fixes via `update_self_healing_fix`
4. Continue iterating until CI passes

### Workspace exploration and code generation

For workspace exploration, code generation, and task execution, agents use [skills](/docs/features/enhance-ai) rather than MCP tools. Skills teach agents how to use the Nx CLI directly — running commands like `nx show projects`, `nx show project myapp`, and `nx generate` — which is more token-efficient than fetching large JSON payloads via MCP.

If your AI client doesn't support skills, use `--no-minimal` to expose the full set of workspace and generator tools via MCP.

---
<!-- source: https://nx.dev/docs/reference/nxignore.md -->
## .nxignore Reference

You may optionally add an `.nxignore` file to the root. This file is used to specify files in your workspace that should
be completely ignored by Nx.

The syntax is the same as
a [`.gitignore` file](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring).

**When a file is specified in the `.nxignore` file**, changes to that file are not taken into account in the `affected` calculations.

---
<!-- source: https://nx.dev/docs/reference/owners.md -->
## Code Owners

{% index_page_cards path="reference/owners" /%}

---
<!-- source: https://nx.dev/docs/reference/owners/generators.md -->
## @nx/owners - Generators

## `init`

Initialize the owners plugin

**Usage:**

```shell
nx g @nx/owners:init

```

## `sync-codeowners-file`

Sync Nx Owners config to a `CODEOWNERS` file

**Usage:**

```shell
nx g @nx/owners:sync-codeowners-file
```

---
<!-- source: https://nx.dev/docs/reference/owners/overview.md -->
## Overview of the Nx Owners Plugin

The `@nx/owners` plugin extends the CODEOWNERS functionality to allow you to define code ownership based on projects in addition to the standard file-based definitions. It leverages the [`nx sync`](/docs/concepts/sync-generators) command to compile `owners` configuration settings from `nx.json` and project configuration files into valid CODEOWNERS files for [GitHub](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners), [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/set-up-and-use-code-owners/) or [GitLab](https://docs.gitlab.com/ee/user/project/codeowners/).

With this plugin, you can specify code ownership using the same project matcher syntax as [`nx run-many`](/docs/reference/nx-commands#nx-run-many). This allows you to easily define rules for multiple projects that may not be located in the same directory. Also, the CODEOWNERS rules will not need to be revisited if a project location is changed or a new project is added.

{% aside type="note" title="This plugin requires an active Nx Enterprise license" %}
In order to use `@nx/owners`, you need to have an active Nx Enterprise license. If you don't have a license or it has expired, the syncing process will stop working and you'll need to manually maintain your CODEOWNERS file.
{% /aside %}

## Set up @nx/owners

1. [Activate your license](/docs/enterprise/activate-license) if you haven't already
2. Install the package

   ```shell
   nx add @nx/owners
   ```

3. Configure Ownership

   Configure the `@nx/owners` plugin in the `nx.json` file or in individual project configuration files. Consult the [Owners Configuration Reference](#owners-configuration-reference) section for more details.

4. Configure the [Sync Generator](/docs/concepts/sync-generators) and CI

The `nx add @nx/owners` command should have registered the `@nx/owners:sync-codeowners-file` generator as a `globalGenerator` in `nx.json`. You can double check to make sure:

```jsonc
// nx.json
{
  "sync": {
    "globalGenerators": ["@nx/owners:sync-codeowners-file"],
  },
}
```

Add `nx sync:check` to the beginning of the CI process.

```yaml
- name: Ensure the workspace configuration is in sync
  run: npx nx sync:check
```

It is also often helpful to add `nx sync` as a git push hook or git commit hook.

## Owners configuration reference

{% tabs %}
{% tabitem label="GitHub" %}

```jsonc
// nx.json
{
  // Can be set to true instead of an object to accept all defaults
  "owners": {
    // Options are `github`, `bitbucket` or `gitlab`. (Optional) Defaults to `github`
    "format": "github",
    // (Optional) Default changes based on format: `.github/CODEOWNERS`, `.bitbucket/CODEOWNERS`, `.gitlab/CODEOWNERS`
    "outputPath": "CODEOWNERS",
    // (Optional)
    "patterns": [
      {
        "description": "A description of the rule",
        "owners": ["@joelovesrust"],
        // specify either projects or files, not both
        // Can be any project specifier that could be used in `nx run-many`
        // See https://nx.dev/docs/reference/nx-commands#nx-run-many
        "projects": ["my-rust-app", "rust-*", "tag:rust"],
        // File globs
        "files": [".github/workflows/**/*"],
      },
    ],
  },
}
```

{% /tabitem %}
{% tabitem label="Bitbucket" %}

```jsonc
// nx.json
{
  // Can be set to true instead of an object to accept all defaults
  "owners": {
    // Options are `github`, `bitbucket` or `gitlab`. (Optional) Defaults to `github`
    "format": "bitbucket",
    // (Optional) Default changes based on format: `.github/CODEOWNERS`, `.bitbucket/CODEOWNERS`, `.gitlab/CODEOWNERS`
    "outputPath": "CODEOWNERS",
    // (Optional)
    "patterns": [
      {
        "description": "A description of the rule",
        "owners": ["@joelovesrust"],
        // specify either projects or files, not both
        // Can be any project specifier that could be used in `nx run-many`
        // See https://nx.dev/docs/reference/nx-commands#nx-run-many
        "projects": ["my-rust-app", "rust-*", "tag:rust"],
        // File globs
        "files": [".github/workflows/**/*"],
      },
    ],
  },
}
```

{% /tabitem %}
{% tabitem label="GitLab" %}

If you are using GitLab, you can specify CODEOWNERS [sections](https://docs.gitlab.com/ee/user/project/codeowners/#organize-code-owners-by-putting-them-into-sections) which give you a little more control over the PR process.

```jsonc
// nx.json
{
  // Can be set to true instead of an object to accept all defaults
  "owners": {
    // Options are `github`, `bitbucket` or `gitlab`. (Optional) Defaults to `github`
    "format": "gitlab",
    // (Optional) Default changes based on format: `.github/CODEOWNERS`, `.bitbucket/CODEOWNERS`, `.gitlab/CODEOWNERS`
    "outputPath": "CODEOWNERS",
    // (Optional)
    "patterns": [
      {
        "description": "A description of the rule",
        "owners": ["@joelovesrust"],
        // Specify either `projects` or `files`, not both
        // Can be any project specifier that could be used in `nx run-many`
        // See https://nx.dev/docs/reference/nx-commands#nx-run-many
        "projects": ["my-rust-app", "rust-*", "tag:rust"],
        // File globs
        "files": [".github/workflows/**/*"],
      },
    ],
    // (Optional)
    "sections": [
      {
        // Labels the section
        "name": "My section",
        // (Optional) The owners to use if a pattern does not specify a set of owners
        "defaultOwners": ["@cheddar"],
        // Specify either `numberOfRequiredApprovals` or `optional`, not both
        // (Optional) Require more than one person to approve the PR
        "numberOfRequiredApprovals": 2,
        // (Optional) Do not require any approvals, just notify the owners
        "optional": true,
        // Same format as the root patterns
        "patterns": [],
      },
    ],
  },
}
```

```jsonc
// path/to/project/project.json
{
  "owners": {
    // Keys are file globs relative to the root of the project
    // Owners can be listed as a string array
    "**/*": ["@ahmed", "@petra"],
    // Owners can be listed as an object with a description
    "README.md": {
      "description": "Jared is very particular about the README file",
      "owners": ["@jared"]
    }
  }
};
```

{% /tabitem %}
{% /tabs %}

**Examples:**

{% tabs %}
{% tabitem label="GitHub" %}

```jsonc
// nx.json
{
  "owners": {
    // defaults to "github"
    "format": "github",
    // defaults to ".github/CODEOWNERS"
    "outputPath": "CODEOWNERS",
    "patterns": [
      {
        "description": "Joe should double check all changes to rust code",
        "projects": ["tag:rust"],
        "owners": ["@joelovesrust"],
      },
      {
        "description": "The Finance team owns these projects",
        "projects": ["finance-*"],
        "owners": ["@finance-team"],
      },
      {
        "description": "Alice, Bob and Cecil work together on these projects",
        "projects": ["admin", "booking", "cart"],
        "owners": ["@alice", "@bob", "@cecil"],
      },
      {
        "description": "CI Workflows",
        "files": [".github/workflows/**/*"],
        "owners": ["@devops"],
      },
    ],
  },
}
```

```jsonc
// packages/my-project/project.json
{
  "owners": {
    "**/*": ["@ahmed", "@petra"],
    "package.json": ["@ahmed"],
    "README.md": {
      "owners": ["@jared"],
      "description": "Jared is very particular about the README file"
    }
  },
};
```

{% /tabitem %}
{% tabitem label="Bitbucket" %}

```jsonc
// nx.json
{
  "owners": {
    "format": "bitbucket",
    // defaults to ".bitbucket/CODEOWNERS"
    "outputPath": "CODEOWNERS",
    "patterns": [
      {
        "description": "Joe should double check all changes to rust code",
        "projects": ["tag:rust"],
        "owners": ["@joelovesrust"],
      },
      {
        "description": "The Finance team owns these projects",
        "projects": ["finance-*"],
        "owners": ["@finance-team"],
      },
      {
        "description": "Alice, Bob and Cecil work together on these projects",
        "projects": ["admin", "booking", "cart"],
        "owners": ["@alice", "@bob", "@cecil"],
      },
      {
        "description": "CI Workflows",
        "files": [".github/workflows/**/*"],
        "owners": ["@devops"],
      },
    ],
  },
}
```

```jsonc
// packages/my-project/project.json
{
  "owners": {
    "**/*": ["@ahmed", "@petra"],
    "package.json": ["@ahmed"],
    "README.md": {
      "owners": ["@jared"],
      "description": "Jared is very particular about the README file"
    }
  },
};
```

{% /tabitem %}
{% tabitem label="GitLab" %}

```jsonc
// nx.json
{
  "owners": {
    "format": "gitlab",
    // defaults to ".gitlab/CODEOWNERS"
    "outputPath": "CODEOWNERS",
    "patterns": [
      {
        "description": "Joe should double check all changes to rust code",
        "projects": ["tag:rust"],
        "owners": ["@joelovesrust"],
      },
      {
        "description": "CI Workflows",
        "files": [".github/workflows/**/*"],
        "owners": ["@devops"],
      },
    ],
    "sections": [
      {
        "name": "Finance",
        "defaultOwners": ["@finance-team"],
        "numberOfRequiredApprovals": 2,
        "patterns": [
          {
            "description": "The Finance team owns these projects",
            "projects": ["finance-*"],
          },
          {
            "description": "Alice, Bob and Cecil work together on these projects",
            "projects": ["admin", "booking", "cart"],
            "owners": ["@alice", "@bob", "@cecil"],
          },
        ],
      },
    ],
  },
}
```

```jsonc
// packages/my-project/project.json
{
  "owners": {
    "**/*": ["@ahmed", "@petra"],
    "package.json": ["@ahmed"],
    "README.md": {
      "owners": ["@jared"],
      "description": "Jared is very particular about the README file"
    }
  },
};
```

{% /tabitem %}
{% /tabs %}

---
<!-- source: https://nx.dev/docs/reference/playwright.md -->
## Playwright

{% sidebar_group_cards group="Reference/Playwright" /%}

---
<!-- source: https://nx.dev/docs/reference/project-configuration.md -->
## Project Configuration

A project's configuration is constructed by Nx from three sources:

1. [Tasks inferred by Nx plugins](/docs/concepts/inferred-tasks) from tooling configuration
2. [Workspace `targetDefaults`](/docs/reference/nx-json#target-defaults) defined in the `nx.json` file
3. Individual project level configuration files (`package.json` and `project.json`)

Each source will [overwrite the previous source](/docs/guides/tasks--caching/pass-args-to-commands). That means `targetDefaults` will overwrite inferred tasks and project level configuration will overwrite both `targetDefaults` and inferred tasks. The combined project configuration can be viewed in the project details view by using [Nx Console](/docs/getting-started/editor-setup) in your IDE or by running:

```shell
nx show project myproject --web
```

{% project_details title="Project Details View" %}

```json
{
  "project": {
    "name": "demo",
    "data": {
      "root": " packages/demo",
      "projectType": "application",
      "targets": {
        "dev": {
          "executor": "nx:run-commands",
          "options": {
            "command": "vite dev",
            "continuous": true
          },
          "metadata": {
            "technologies": ["vite"]
          }
        },
        "build": {
          "executor": "nx:run-commands",
          "inputs": ["production", "^production"],
          "outputs": ["{projectRoot}/dist"],
          "options": {
            "command": "vite build"
          },
          "metadata": {
            "technologies": ["vite"]
          }
        }
      }
    }
  },
  "sourceMap": {
    "targets": ["packages/demo/vite.config.ts", "@nx/vite"],
    "targets.dev": ["packages/demo/vite.config.ts", "@nx/vite"],
    "targets.build": ["packages/demo/vite.config.ts", "@nx/vite"]
  }
}
```

{% /project_details %}

The project details view also shows where each setting is defined so that you know where to change it.

## Project level configuration files

If you need to edit your project settings or modify an inferred task, you can do so in either `package.json` or `project.json` files. The examples on this page show both styles. Nx merges the two files to get each project's configuration. The full [machine readable schema](https://github.com/nrwl/nx/blob/master/packages/nx/schemas/project-schema.json) is available on GitHub.

### When to Use package.json vs project.json

Both `package.json` and `project.json` can be used to configure Nx targets, and both support the same configuration options including executors:

- **package.json**: Use the `"nx"` property to define targets with executors, options, and other Nx-specific configuration
- **project.json**: A dedicated Nx configuration file that keeps your `package.json` focused on package metadata

The choice between `package.json` and `project.json` is primarily a matter of preference. The `package.json` is standard for JavaScript projects, so you may prefer to use that over the Nx-specific `project.json` file.

The following configuration creates `build` and `test` targets for Nx.

{% tabs syncKey="project-config-file" %}
{% tabitem label="package.json" %}

```jsonc
// package.json
{
  "name": "mylib",
  "scripts": {
    "test": "jest",
  },
  "nx": {
    // you could also do this in "scripts", but this "targets" configuration also supports Nx executors
    "targets": {
      "build": {
        "command": "tsc -p tsconfig.lib.json",
      },
    },
  },
}
```

{% /tabitem %}
{% tabitem label="project.json" %}

```jsonc
// project.json
{
  "root": "libs/mylib/",
  "targets": {
    "test": {
      "executor": "@nx/jest:jest",
      "options": {
        /* ... */
      },
    },
    "build": {
      "executor": "@nx/js:tsc",
      "options": {
        /* ... */
      },
    },
  },
}
```

{% /tabitem %}
{% /tabs %}

You can invoke `nx build mylib` or `nx test mylib` without any extra configuration.

Below are some more complete examples of project configuration files. For a more intuitive understanding of the roles of each option, you can highlight the options in the excerpt below that relate to different categories. Orchestration settings control the way [Nx runs tasks](/docs/features/run-tasks). Execution settings control the actual task that is run. Caching settings control when [Nx caches a task](/docs/features/cache-task-results) and what is actually cached.

{% tabs syncKey="project-config-file" %}
{% tabitem label="package.json" %}

```jsonc {% meta="{ Orchestration:[15,18,20,23,26],Execution:[5,6,7],Caching:[10-13,16,17,21,22] }" %}
// package.json
{
  "name": "mylib",
  "scripts": {
    "test": "jest",
    "build": "tsc -p tsconfig.lib.json", // the actual command here is arbitrary
    "ignored": "exit 1",
  },
  "nx": {
    "namedInputs": {
      "default": ["{projectRoot}/**/*"],
      "production": ["!{projectRoot}/**/*.spec.tsx"],
    },
    "targets": {
      "build": {
        "inputs": ["production", "^production"],
        "outputs": ["{workspaceRoot}/dist/libs/mylib"],
        "dependsOn": ["^build"],
      },
      "test": {
        "inputs": ["default", "^production"],
        "outputs": [],
        "dependsOn": ["build"],
      },
    },
    "includedScripts": ["test", "build"], // If you want to limit the scripts Nx sees, you can specify a list here.
  },
}
```

{% /tabitem %}
{% tabitem label="project.json" %}

```json {% meta="{ Orchestration: [6,7,13,14,20,23], Execution: [13,17-20,23,24], Caching: [8-11,14,15,21,22] }" %}
// project.json
{
  "root": "libs/mylib/",
  "sourceRoot": "libs/mylib/src",
  "projectType": "library",
  "tags": ["scope:myteam"],
  "implicitDependencies": ["anotherlib"],
  "namedInputs": {
    "default": ["{projectRoot}/**/*"],
    "production": ["!{projectRoot}/**/*.spec.tsx"]
  },
  "targets": {
    "test": {
      "inputs": ["default", "^production"],
      "outputs": [],
      "dependsOn": ["build"],
      "executor": "@nx/jest:jest",
      "options": {}
    },
    "build": {
      "inputs": ["production", "^production"],
      "outputs": ["{workspaceRoot}/dist/libs/mylib"],
      "dependsOn": ["^build"],
      "executor": "@nx/js:tsc",
      "options": {}
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

## Task definitions (Targets)

A large portion of project configuration is related to defining the tasks for the project. In addition, to defining what the task actually does, a task definition also has properties that define the way that Nx should run that task. Those properties are described in detail below.

### Cache

In Nx 17 and higher, caching is configured by specifying `"cache": true` in a target's configuration. This will tell Nx that it's ok to cache the results of a given target. For instance, if you have a target that runs tests, you can specify `"cache": true` in the target default configuration for `test` and Nx will cache the results of running tests.

```json
// project.json
{
  "targets": {
    "test": {
      "cache": true
    }
  }
}
```

{% aside type="caution" title="Per Project Caching + Distribution" %}

If you are using distributed task execution and disable caching for a given target, you will not be able to use distributed task execution for that target. This is because distributed task execution requires caching to be enabled. This means that the target you have disabled caching for, and any targets which depend on that target will fail the pipeline if you try to run them with Nx Agents enabled.

{% /aside %}

### Parallelism

In Nx 19.5.0+, tasks can be configured to support parallelism or not. By default, tasks are run in parallel with other tasks on a given machine. However, in some cases, tasks can require a shared resource such as a port or memory. For these cases, setting `"parallelism": false`, will ensure that those tasks will not run in parallel with other tasks on a single machine. For example, if the `e2e` tasks all require port 4200, running them in parallel will conflict so the targets can specify to not support parallelism:

```json
// project.json
{
  "targets": {
    "e2e": {
      "parallelism": false
    }
  }
}
```

{% aside type="caution" title="Note: Parallelism is only per machine" %}

If you are using distributed task execution, tasks will still be run simultaneously on different machines. Because different agents do not share resources with one another, it is perfectly fine for multiple agents to run tasks which do not support parallelism at the same time. Therefore, using Nx Agents is key to running tasks which do not support parallelism quickly and efficiently.

{% /aside %}

### Inputs and named inputs

Each cacheable task needs to define `inputs` which determine whether the task outputs can be retrieved from the cache or the task needs to be re-run. The `namedInputs` defined in `nx.json` or project level configuration are sets of reusable input definitions.

A typical set of inputs may look like this:

```jsonc
{
  "namedInputs": {
    "default": ["{projectRoot}/**/*"], // every file in the project
    "production": ["default", "!{projectRoot}/**/*.spec.tsx"], // except test files
  },
  "targets": {
    "build": {
      "inputs": [
        "production", // this project's production files
        { "externalDependencies": ["vite"] }, // the version of the vite package
      ],
    },
  },
}
```

{% cardgrid %}
{% linkcard title="Inputs and Named Inputs Reference" description="Learn about all the possible settings for `inputs` and `namedInputs`" href="/docs/reference/inputs" /%}
{% linkcard title="Configure Inputs for Task Caching" description="This recipes walks you through a few examples of how to configure `inputs` and `namedInputs`" href="/docs/guides/tasks--caching/configure-inputs" /%}
{% /cardgrid %}

### Outputs

Targets may define outputs to tell Nx where the target is going to create file artifacts that Nx should cache. `"outputs": ["{workspaceRoot}/dist/libs/mylib"]` tells Nx where the `build` target is going to create file artifacts.

This configuration is usually not needed. Nx comes with reasonable defaults (imported in `nx.json`) which implement the configuration above.

Specifically, by default, the following locations are cached for builds:

- `{workspaceRoot}/dist/{projectRoot}`,
- `{projectRoot}/build`,
- `{projectRoot}/dist`,
- `{projectRoot}/public`

{% cardgrid %}
{% linkcard title="Configure Outputs for Task Caching" description="This recipes walks gives helpful tips to configure `outputs` for tasks" href="/docs/guides/tasks--caching/configure-outputs" /%}
{% /cardgrid  %}

Read the [configure outputs for task caching](/docs/guides/tasks--caching/configure-outputs) recipe for helpful tips for setting outputs.

#### Basic example

Usually, a target writes to a specific directory or a file. The following instructs Nx to cache `dist/libs/mylib` and `build/libs/mylib/main.js`:

```json
{
  "targets": {
    "build": {
      "outputs": [
        "{workspaceRoot}/dist/libs/mylib",
        "{workspaceRoot}/build/libs/mylib/main.js"
      ]
    }
  }
}
```

#### Specifying globs

Sometimes, multiple targets might write to the same directory. When possible it is recommended to direct these targets into separate directories.

```json
{
  "targets": {
    "build-js": {
      "outputs": ["{workspaceRoot}/dist/libs/mylib/js"]
    },
    "build-css": {
      "outputs": ["{workspaceRoot}/dist/libs/mylib/css"]
    }
  }
}
```

But if the above is not possible, globs (parsed by the [GlobSet](https://docs.rs/globset/0.4.5/globset/#syntax) Rust library) can be specified as outputs to only cache a set of files rather than the whole directory.

```json
{
  "targets": {
    "build-js": {
      "outputs": ["{workspaceRoot}/dist/libs/mylib/**/*.{js,map}"]
    },
    "build-css": {
      "outputs": ["{workspaceRoot}/dist/libs/mylib/**/*.css"]
    }
  }
}
```

More advanced patterns can be used to exclude files and folders in a single line

```json
{
  "targets": {
    "build-js": {
      "outputs": ["{workspaceRoot}/dist/libs/!(cache|.next)/**/*.{js,map}"]
    },
    "build-css": {
      "outputs": ["{workspaceRoot}/dist/libs/mylib/**/!(secondary).css"]
    }
  }
}
```

### dependsOn

Targets can depend on other targets. This is the relevant portion of the configuration file:

```json
{
  "targets": {
    "build": {
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["build"]
    }
  }
}
```

A common scenario is having to build dependencies of a project first before building the project. This is what
the `"dependsOn": ["^build"]` property of the `build` target configures. It tells Nx that before it can build `mylib` it
needs to make
sure that `mylib`'s dependencies are built as well. This doesn't mean Nx is going to rerun those builds. If the right
artifacts are already in the right place, Nx will do nothing. If they aren't in the right place, but they are available
in the cache, Nx will retrieve them from the cache.

Another common scenario is for a target to depend on another target of the same project. For
instance, `"dependsOn": ["build"]` of
the `test` target tells Nx that before it can test `mylib` it needs to make sure that `mylib` is built, which will
result in `mylib`'s dependencies being built as well.

{% aside type="note" title="Dependencies that do not exit" %}
If you specify a task in `dependsOn` that never exits, then the dependent task will never start. Label such dependencies as [continuous](#continuous) tasks, which tells Nx to not wait for the process to end before starting the dependent task.
{% /aside %}

You can also express task dependencies with an object syntax:

{% tabs %}
{% tabitem label="Dependencies on self" %}

```json
{
  "targets": {
    "test": {
      "dependsOn": [
        {
          "target": "build", // target name
          "params": "ignore" // "forward" or "ignore", defaults to "ignore"
        }
      ]
    }
  }
}
```

{% /tabitem %}
{% tabitem label="Dependencies on other projects" %}

```json
{
  "targets": {
    "build": {
      "dependsOn": [
        {
          "dependencies": true, // Run this target on all dependencies first
          "target": "build", // target name
          "params": "ignore" // "forward" or "ignore", defaults to "ignore"
        }
      ]
    }
  }
}
```

{% /tabitem %}
{% tabitem label="Dependencies on specific projects" %}

```json
{
  "targets": {
    "build": {
      "dependsOn": [
        {
          "projects": ["my-app"], // Run build on "my-app" first
          "target": "build", // target name
          "params": "ignore" // "forward" or "ignore", defaults to "ignore"
        }
      ]
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

Starting from v19.5.0, wildcards can be used to define dependencies in the `dependsOn` field.

```json
{
  "targets": {
    "test": {
      "dependsOn": [
        {
          "target": "build", // target name
          "params": "ignore" // "forward" or "ignore", defaults to "ignore"
        },
        "build-*", // support for using wildcards in dependsOn, matches: "build-css", "build-js" targets of current project
        "^build-*", // matches tasks: "build-css", "build-js" targets of dependencies
        "*build-*", // matches tasks: "build-css", "build-js" as well as "task-with-build-in-middle" targets of current project
        "^*build-*" // matches tasks: "build-css", "build-js" as well as "task-with-build-in-middle" targets of dependencies
      ]
    }
  }
}
```

#### Examples

You can write the shorthand configuration above in the object syntax like this:

```json
{
  "targets": {
    "build": {
      "dependsOn": [{ "dependencies": true, "target": "build" }] // Run build on my dependencies first
    },
    "test": {
      "dependsOn": [{ "target": "build" }] // Run build on myself first
    }
  }
}
```

With the expanded syntax, you also have a third option available to configure how to handle the params passed to the target. You can either forward them or you can ignore them (default).

```json
{
  "targets": {
    "build": {
      // forward params passed to this target to the dependency targets
      "dependsOn": [
        { "projects": "{dependencies}", "target": "build", "params": "forward" }
      ]
    },
    "test": {
      // ignore params passed to this target, won't be forwarded to the dependency targets
      "dependsOn": [
        { "projects": "{dependencies}", "target": "build", "params": "ignore" }
      ]
    },
    "lint": {
      // ignore params passed to this target, won't be forwarded to the dependency targets
      "dependsOn": [{ "projects": "{dependencies}", "target": "build" }]
    }
  }
}
```

This also works when defining a relation for the target of the project itself using `"projects": "self"`:

```json
{
  "targets": {
    "build": {
      // forward params passed to this target to the project target
      "dependsOn": [{ "target": "pre-build", "params": "forward" }]
    }
  }
}
```

Additionally, when using the expanded object syntax, you can specify individual projects in version 16 or greater.

```json
{
  "targets": {
    "build": {
      // Run is-even:pre-build and is-odd:pre-build before this target
      "dependsOn": [
        { "projects": ["is-even", "is-odd"], "target": "pre-build" }
      ]
    }
  }
}
```

This configuration is usually not needed. Nx comes with reasonable defaults (imported in `nx.json`) which implement the
configuration above.

### Continuous

In Nx 21+, tasks that never exit (sometimes called long-running processes) can be configured with `"continuous": true` to prevent their dependent tasks from waiting for task completion. For example, the `e2e` task depends on a continuous `serve` task to ensure that the development server is running.

In this example, application's configuration labels the `serve` task as continuous.

```json
// apps/myapp/project.json
{
  "targets": {
    "serve": {
      "continuous": true
    }
  }
}
```

And the E2E project's `e2e` task has a dependency on the `serve` task, which ensures that the server is running when we run the `e2e` task.

```json
// apps/myapp-e2e/project.json
{
  "targets": {
    "e2e": {
      "dependsOn": [
        {
          "projects": "myapp",
          "target": "serve"
        }
      ]
    }
  }
}
```

### Sync generators

In the same way that `dependsOn` tells Nx to run another task before running this task, the `syncGenerator` property tells Nx to run a generator to ensure that your files are in the correct state before this task is run. [Sync generators](/docs/concepts/sync-generators) are especially useful for keeping configuration files up to date with the project graph. Sync generators are available in Nx 19.8+.

```json
{
  "targets": {
    "build": {
      "syncGenerators": ["some-plugin:my-sync-generator"]
    }
  }
}
```

### Executor/command options

To define what a task does, you must configure which command or executor will run when the task is executed. In the case of [inferred tasks](/docs/concepts/inferred-tasks) you can provide project-specific overrides. As an example, if your repo has projects with a `build` inferred target running the `vite build` command, you can provide some extra options as follows:

```json
{
  "targets": {
    "build": {
      "options": {
        "assetsInlineLimit": 2048,
        "assetsDir": "static/assets"
      }
    }
  }
}
```

For more details on how to pass args to the underlying command see the [Pass Args to Commands recipe](/docs/guides/tasks--caching/pass-args-to-commands).

In the case of an explicit target using an executor, you can specify the executor and the options specific to that executor as follows:

```json
{
  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "options": {
        "generateExportsField": true
      }
    }
  }
}
```

### Target metadata

You can add additional metadata to be attached to a target. For example, you can provide a description stating what the
target does:

```jsonc
// project.json
{
  "targets": {
    "build": {
      "metadata": {
        "description": "Build the application for production",
      },
    },
  },
}
```

## Project metadata

The following properties describe the project as a whole.

### tags

You can annotate your projects with `tags` as follows:

{% tabs syncKey="project-config-file" %}
{% tabitem label="package.json" %}

```jsonc
// package.json
{
  "name": "mylib",
  "nx": {
    "tags": ["scope:myteam"],
  },
}
```

{% /tabitem %}
{% tabitem label="project.json" %}

```jsonc
// project.json
{
  "root": "libs/mylib",
  "tags": ["scope:myteam"],
}
```

{% /tabitem %}
{% /tabs %}

You can [configure lint rules using these tags](/docs/features/enforce-module-boundaries) to, for instance, ensure that libraries
belonging to `myteam` are not depended on by libraries belong to `theirteam`.

### implicitDependencies

Nx uses powerful source-code analysis to figure out your workspace's project graph. Some dependencies cannot be deduced statically, so you can set them manually like this. The `implicitDependencies` property is parsed with the [minimatch](https://github.com/isaacs/minimatch) library, so you can review that syntax for more advanced use cases.

{% tabs syncKey="project-config-file"  %}
{% tabitem label="package.json" %}

```jsonc
// package.json
{
  "name": "mylib",
  "nx": {
    "implicitDependencies": ["anotherlib"],
  },
}
```

{% /tabitem %}
{% tabitem label="project.json" %}

```jsonc
// project.json
{
  "root": "libs/mylib",
  "implicitDependencies": ["anotherlib"],
}
```

{% /tabitem %}
{% /tabs %}

You can also remove a dependency as follows:

{% tabs syncKey="project-config-file"  %}
{% tabitem label="package.json" %}

```jsonc
// package.json
{
  "name": "mylib",
  "nx": {
    "implicitDependencies": ["!anotherlib"] # regardless of what Nx thinks, "mylib" doesn't depend on "anotherlib"
  }
}
```

{% /tabitem %}
{% tabitem label="project.json" %}

```jsonc
// project.json
{
  "root": "libs/mylib",
  "implicitDependencies": ["!anotherlib"] # regardless of what Nx thinks, "mylib" doesn't depend on "anotherlib"
}
```

{% /tabitem %}
{% /tabs %}

An implicit dependency could also be a glob pattern:

{% tabs syncKey="project-config-file"  %}
{% tabitem label="package.json" %}

```jsonc
// package.json
{
  "name": "mylib",
  "nx": {
    "implicitDependencies": ["shop-*"] # "mylib" depends on all projects beginning with "shop-"
  }
}
```

{% /tabitem %}
{% tabitem label="project.json" %}

```jsonc
// project.json
{
  "root": "libs/mylib",
  "implicitDependencies": ["shop-*"] # "mylib" depends on all projects beginning with "shop-"
}
```

{% /tabitem %}
{% /tabs %}

### Release

The `release` property allows project-level overrides for the [nx release](/docs/features/manage-releases) command. This is particularly useful for configuring Docker image publishing.

#### Docker configuration {% badge text="experimental" /%}

{% aside type="caution" title="Experimental Feature" %}
Docker support in Nx is currently experimental and may undergo breaking changes without following semantic versioning.
{% /aside %}

Projects with Docker images can override the global Docker configuration:

```jsonc
// project.json
{
  "name": "api",
  "release": {
    "docker": {
      // Override the repository name for this specific project
      "repositoryName": "acme/api",
    },
  },
}
```

The `repositoryName` specified here will override any global or group-level Docker repository configuration when publishing this project's Docker image.

### Metadata

You can add additional metadata to be attached to the project. For example, you can provide a description for your
project:

```jsonc
// project.json
{
  "name": "admin",
  "metadata": {
    "description": "This is the admin application",
  },
}
```

## Including package.json files as projects in the graph

Any `package.json` file that is referenced by the `workspaces` property in the root `package.json` file will be included as a project in the graph. If you are using Lerna, projects defined in `lerna.json` will be included. If you are using pnpm, projects defined in `pnpm-workspace.yml` will be included.

If you want to ignore a particular `package.json` file, exclude it from those tools. For example, you can add `!packages/myproject` to the `workspaces` property.

### Ignoring package.json scripts

Nx merges `package.json` scripts with any targets defined in `project.json`.
If you only wish for some scripts to be used as Nx targets, you can specify them in the `includedScripts` property of the project's `package.json`.

```json
// packages/my-library/package.json
{
  "name": "my-library",
  "version": "0.0.1",
  "scripts": {
    "build": "tsc",
    "postinstall": "node ./tasks/postinstall"
  },
  "nx": {
    "includedScripts": ["build"]
  }
}
```

---
<!-- source: https://nx.dev/docs/reference/react.md -->
## React

{% sidebar_group_cards group="Reference/React" /%}

---
<!-- source: https://nx.dev/docs/reference/releases.md -->
## Nx Release Schedule and Support Policy

{% aside type="note" title="Looking for guidance on releasing your projects with Nx Release?" %}
The releases of the Nx tooling itself. If you are looking for guidance on releasing your project with Nx Release, [see the documentation on managing releases](/docs/features/manage-releases).
{% /aside %}

The `nx` package, and all packages under the `@nx` namespace which live alongside each other in the [https://github.com/nrwl/nx](https://github.com/nrwl/nx) repository, are released together in lockstep. You should always use matching versions of the `nx` package and the `@nx` packages, e.g. `nx@22.2.0` and `@nx/js@22.2.0` should be used together.

Major Nx versions are released as the _latest_ every six months, typically around April and October.
After each major version release, the _previous_ major version moves to long-term support (LTS) for 12 months, after
which it becomes unsupported.
Each major version has 18 total months of support from when it is first released to when it falls out of LTS. Users
should use `nx migrate` to ensure that they stay on a supported version.

### Major, minor, and patch versions

- **Patch** versions include security or bug fixes, and are released as needed.
- **Minor** versions include new features and fixes, and are released less frequently. It is a good idea to regularly
  update to the latest minor version.
- **Major** versions may contain [breaking changes](#breaking-changes-and-migration-path), and are released twice a
  year.

## Supported versions

The following are the currently supported major versions of Nx.

| Version | Support Type | Release Date |
| :-----: | :----------: | :----------: |
|   v22   |   Current    |  2025-10-22  |
|   v21   |     LTS      |  2025-05-05  |
|   v20   |     LTS      |  2024-10-06  |

### Current vs LTS

The current version of Nx will receive new features as well as any fixes to any unintentional behavior.
When a new major version of Nx is released, previous versions will go into LTS.
LTS versions of Nx will receive security patches as well as critical fixes.

## Deprecation policy

When the Nx team intends to remove an API or feature, it will be marked as _deprecated_. Deprecation warnings can
surface in documentation, terminal output, or in TSDoc. The deprecated API will remain
functional for a whole major version, after which they will be removed.

For example, if a feature is deprecated in v21.1.0, it will be removed in v23.0.0 (two major versions later).

## Breaking changes and migration path

Breaking changes, including the removal of deprecated APIs, will be highlighted under _Breaking Changes_ in
the [changelog](https://nx.dev/changelog).

Whenever possible, the Nx team will provide automatic migrations
through [`nx migrate`](/docs/reference/nx-commands#nx-migrate).

---
<!-- source: https://nx.dev/docs/reference/remote-cache-plugins.md -->
## Remote Cache Plugins

{% index_page_cards path="reference/remote-cache-plugins" /%}

---
<!-- source: https://nx.dev/docs/reference/remote-cache-plugins/azure-cache.md -->
## Azure Cache

{% index_page_cards path="reference/remote-cache-plugins/azure-cache" /%}

---
<!-- source: https://nx.dev/docs/reference/remote-cache-plugins/azure-cache/overview.md -->
## Overview of the Nx Azure Cache Plugin

The `@nx/azure-cache` plugin enables you to self-host your remote cache on [Azure Storage](https://azure.microsoft.com/en-us/products/storage/blobs).

{% aside type="caution" title="Bucket-based caches are vulnerable to poisoning and often prohibited in organizations" %}

CREEP (CVE-2025-36852) is a critical vulnerability in bucket-based self-hosted remote caches that allows anyone with PR access to poison production builds. Many organizations are unaware of this security risk. [Learn more](https://nx.dev/blog/creep-vulnerability-build-cache-security)

`@nx/azure-cache` (along with other bucket-based remote cache implementations) is listed in the CVE, and is not allowed in many organizations.

{% /aside %}

{% aside type="tip" title="Nx Cloud: Managed Multi-Tier Remote Cache [Secure]" %}

Recommended for everyone.

- [Fully managed multi-tier remote caching with Nx Replay](/docs/features/ci-features/remote-cache)
- [Both secure and fast](https://nx.dev/enterprise/security)
- Generous free plan

You'll also get access to advanced CI features:

- [Automated distribution of tasks across machines with Nx Agents](/docs/features/ci-features/distribute-task-execution)
- [Automated splitting of tasks (including e2e tests) with Nx Atomizer](/docs/features/ci-features/split-e2e-tasks)
- [Detection and re-running of flaky tasks](/docs/features/ci-features/flaky-tasks)
- [Self-healing CI and other AI features](https://nx.dev/ai)

[Get Started](https://cloud.nx.app)
{% /aside %}

{% aside type="tip" title="Nx Enterprise [Secure]" %}

Recommended for large organizations.

Includes everything from Nx Cloud, plus:

- Work hand-in-hand with the Nx team for continual improvement
- Run on the Nx Cloud servers in any region or run fully self-contained, on-prem
- SOC 2 type 1 and 2 compliant and comes with single-tenant, dedicated EU region hosting as well as on-premise

[Reach out for an Enterprise trial](https://nx.dev/enterprise/trial)

{% /aside %}

## Set up @nx/azure-cache

### 1. Install the package

Run the following command:

```shell
nx add @nx/azure-cache
```

This will add the `@nx/azure-cache` NPM package and automatically configure it for your workspace. As part of this process, you'll be guided to **generate a new activation key**. This is a fully automated process to register your plugin.

The key will be saved in your repository (`.nx/key/key.ini`) and should be committed so that every developer has access to it. If your repository is public (or in CI), you can also use an environment variable:

```dotenv
// .env
NX_KEY=YOUR_ACTIVATION_KEY
```

> Why require an activation key? It simply helps us know and support our users. If you prefer not to provide this information, you can also build your own cache server. [Learn more.](/docs/guides/tasks--caching/self-hosted-caching)

### 2. Authenticate with Azure

There are several ways to [authenticate with Azure Storage](https://github.com/Azure/login#login-with-openid-connect-oidc-recommended), but the method recommended by Azure is to use OpenID Connect, like this:

```yaml
// .github/workflows/ci.yml
name: CI
...
permissions:
  id-token: write
  ...

jobs:
  main:
    env:
      NX_KEY: ${{ secrets.NX_KEY }}
    runs-on: ubuntu-latest
    steps:
        ...

      - name: Azure login
        uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
        ...

      - run: pnpm exec nx affected -t lint test build
```

You need to set the `AZURE_CLIENT_ID`, `AZURE_TENANT_ID` and `AZURE_SUBSCRIPTION_ID` secrets as defined in the [Azure documentation](https://github.com/Azure/login#login-with-openid-connect-oidc-recommended).

Note: Any authentication method that [sets up the `DefaultAzureCredentials`](https://learn.microsoft.com/en-us/azure/developer/javascript/sdk/credential-chains#use-defaultazurecredential-for-flexibility) will enable the plugin to work.

{% aside type="note" title="Custom Azure Endpoint" %}
If you are using a custom Azure endpoint, you will need to authenticate by [setting the `AZURE_STORAGE_CONNECTION_STRING` environment variable](https://learn.microsoft.com/en-us/azure/storage/common/storage-configure-connection-string). The `@nx/azure-cache` plugin will detect the environment variable and automatically use it to connect to Azure.
{% /aside %}

### 3. configure the Nx cache to use Azure storage

Finally, you need to configure your Nx cache in the `nx.json` file. The `container` that you specify needs to already exist - Nx doesn't create it for you.

```jsonc
// nx.json
{
  "azure": {
    "container": "mycontainer",
    "accountName": "myaccount",
  },
}
```

| **Property**    | **Description**                  |
| --------------- | -------------------------------- |
| **container**   | The name of the container to use |
| **accountName** | The name of blob storage account |

### Migrating from custom tasks runners

Many people who are interested in Nx caching plugins have previously used custom task runners. Nx offers a new and simpler extension API designed to meet the same use cases as the now-deprecated custom task runners.

To learn more about migrating from custom task runners, [please refer to this detailed guide](/docs/reference/deprecated/custom-tasks-runner).

By default, Nx will try to write and read from the remote cache while running locally. This means that permissions must be set for users who are expected to access the remote cache.

Nx will only show warnings when the remote cache is not writable. You can disable these warnings by setting `localMode` to `read-only` or `no-cache` in the `nx.json` file.

```jsonc
// nx.json
{
  "azure": {
    // ...
    "localMode": "read-only",
  },
}
```

The cache mode in CI can also be configured by setting `ciMode` to `read-only` or `no-cache` in the `nx.json` file. Or setting `NX_POWERPACK_CACHE_MODE` to `read-only` or `no-cache` in the CI environment.

```jsonc
// nx.json
{
  "azure": {
    // ...
    "ciMode": "read-only",
  },
}
```

---
<!-- source: https://nx.dev/docs/reference/remote-cache-plugins/gcs-cache.md -->
## GCS Cache

{% index_page_cards path="reference/remote-cache-plugins/gcs-cache" /%}

---
<!-- source: https://nx.dev/docs/reference/remote-cache-plugins/gcs-cache/overview.md -->
## Overview of the Nx GCS Cache Plugin

The `@nx/gcs-cache` plugin enables you to self-host your remote cache on [Google Cloud Storage](https://cloud.google.com/storage).

{% aside type="caution" title="Bucket-based caches are vulnerable to poisoning and often prohibited in organizations" %}

CREEP (CVE-2025-36852) is a critical vulnerability in bucket-based self-hosted remote caches that allows anyone with PR access to poison production builds. Many organizations are unaware of this security risk. [Learn more](https://nx.dev/blog/creep-vulnerability-build-cache-security)

`@nx/gcs-cache` (along with other bucket-based remote cache implementations) is listed in the CVE, and is not allowed in many organizations.

{% /aside %}

{% aside type="tip" title="Nx Cloud: Managed Multi-Tier Remote Cache [Secure]" %}

Recommended for everyone.

- [Fully managed multi-tier remote caching with Nx Replay](/docs/features/ci-features/remote-cache)
- [Both secure and fast](https://nx.dev/enterprise/security)
- Generous free plan

You'll also get access to advanced CI features:

- [Automated distribution of tasks across machines with Nx Agents](/docs/features/ci-features/distribute-task-execution)
- [Automated splitting of tasks (including e2e tests) with Nx Atomizer](/docs/features/ci-features/split-e2e-tasks)
- [Detection and re-running of flaky tasks](/docs/features/ci-features/flaky-tasks)
- [Self-healing CI and other AI features](https://nx.dev/ai)

[Get Started](https://cloud.nx.app)
{% /aside %}

{% aside type="tip" title="Nx Enterprise [Secure]" %}

Recommended for large organizations.

Includes everything from Nx Cloud, plus:

- Work hand-in-hand with the Nx team for continual improvement
- Run on the Nx Cloud servers in any region or run fully self-contained, on-prem
- SOC 2 type 1 and 2 compliant and comes with single-tenant, dedicated EU region hosting as well as on-premise

[Reach out for an Enterprise trial](https://nx.dev/enterprise/trial)

{% /aside %}

## Set up @nx/gcs-cache

### 1. Install the package

Run the following command:

```shell
nx add @nx/gcs-cache
```

This will add the `@nx/gcs-cache` NPM package and automatically configure it for your workspace. As part of this process, you'll be guided to **generate a new activation key**. This is a fully automated process to register your plugin.

The key will be saved in your repository (`.nx/key/key.ini`) and should be committed so that every developer has access to it. If your repository is public (or in CI), you can also use an environment variable:

```dotenv
// .env
NX_KEY=YOUR_ACTIVATION_KEY
```

> Why require an activation key? It simply helps us know and support our users. If you prefer not to provide this information, you can also build your own cache server. [Learn more.](/docs/guides/tasks--caching/self-hosted-caching)

### 2. authenticate with google cloud

There are several ways to [authenticate with Google Cloud Storage](https://github.com/google-github-actions/setup-gcloud#authorization), but the method recommended by Google is to use Workload Identity Federation, like this:

```yaml
// .github/workflows/ci.yml
name: CI
...
permissions:
  id-token: write
  ...

jobs:
  main:
    env:
      NX_KEY: ${{ secrets.NX_KEY }}
    runs-on: ubuntu-latest
    steps:
        ...

      - id: 'auth'
        name: 'Authenticate to Google Cloud'
        uses: 'google-github-actions/auth@v2'
        with:
          token_format: 'access_token'
          workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
          service_account: 'my-service-account@my-project.iam.gserviceaccount.com'

      - name: 'Set up Cloud SDK'
        uses: 'google-github-actions/setup-gcloud@v2'
        with:
          version: '>= 363.0.0'

        ...

      - run: pnpm exec nx affected -t lint test build
```

Note: Any authentication method that [sets up the Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials) will enable the plugin to work.

### 3. configure the Nx cache to use google cloud storage

Finally, you need to configure your Nx cache in the `nx.json` file. The `bucket` that you specify needs to already exist - Nx doesn't create it for you.

```jsonc
// nx.json
{
  "gcs": {
    "bucket": "my-bucket",
  },
}
```

| **Property** | **Description**               |
| ------------ | ----------------------------- |
| **bucket**   | The name of the bucket to use |

### Migrating from custom tasks runners

Many people who are interested in Nx caching plugins have previously used custom task runners. Nx offers a new and simpler extension API designed to meet the same use cases as the now-deprecated custom task runners.

To learn more about migrating from custom task runners, [please refer to this detailed guide](/docs/reference/deprecated/custom-tasks-runner).

By default, Nx will try to write and read from the remote cache while running locally. This means that permissions must be set for users who are expected to access the remote cache.

Nx will only show warnings when the remote cache is not writable. You can disable these warnings by setting `localMode` to `read-only` or `no-cache` in the `nx.json` file.

```jsonc
// nx.json
{
  "gcs": {
    // ...
    "localMode": "read-only",
  },
}
```

The cache mode in CI can also be configured by setting `ciMode` to `read-only` or `no-cache` in the `nx.json` file. Or by setting `NX_POWERPACK_CACHE_MODE` to `read-only` or `no-cache` in the CI environment.

```jsonc
// nx.json
{
  "gcs": {
    // ...
    "ciMode": "read-only",
  },
}
```

---
<!-- source: https://nx.dev/docs/reference/remote-cache-plugins/s3-cache.md -->
## S3 Cache

{% index_page_cards path="reference/remote-cache-plugins/s3-cache" /%}

---
<!-- source: https://nx.dev/docs/reference/remote-cache-plugins/s3-cache/overview.md -->
## Overview of the Nx S3 Cache Plugin

The `@nx/s3-cache` plugin enables you to self-host your remote cache on an [Amazon S3](https://aws.amazon.com/s3) bucket.

{% aside type="caution" title="Bucket-based caches are vulnerable to poisoning and often prohibited in organizations" %}

CREEP (CVE-2025-36852) is a critical vulnerability in bucket-based self-hosted remote caches that allows anyone with PR access to poison production builds. Many organizations are unaware of this security risk. [Learn more](https://nx.dev/blog/creep-vulnerability-build-cache-security)

`@nx/s3-cache` (along with other bucket-based remote cache implementations) is listed in the CVE, and is not allowed in many organizations.

{% /aside %}

{% aside type="tip" title="Nx Cloud: Managed Multi-Tier Remote Cache [Secure]" %}

Recommended for everyone.

- [Fully managed multi-tier remote caching with Nx Replay](/docs/features/ci-features/remote-cache)
- [Both secure and fast](https://nx.dev/enterprise/security)
- Generous free plan

You'll also get access to advanced CI features:

- [Automated distribution of tasks across machines with Nx Agents](/docs/features/ci-features/distribute-task-execution)
- [Automated splitting of tasks (including e2e tests) with Nx Atomizer](/docs/features/ci-features/split-e2e-tasks)
- [Detection and re-running of flaky tasks](/docs/features/ci-features/flaky-tasks)
- [Self-healing CI and other AI features](https://nx.dev/ai)

[Get Started](https://cloud.nx.app)
{% /aside %}

{% aside type="tip" title="Nx Enterprise [Secure]" %}

Recommended for large organizations.

Includes everything from Nx Cloud, plus:

- Work hand-in-hand with the Nx team for continual improvement
- Run on the Nx Cloud servers in any region or run fully self-contained, on-prem
- SOC 2 type 1 and 2 compliant and comes with single-tenant, dedicated EU region hosting as well as on-premise

[Reach out for an Enterprise trial](https://nx.dev/enterprise/trial)

{% /aside %}

## Set up @nx/s3-cache

### 1. Install the package

Run the following command:

```shell
nx add @nx/s3-cache
```

This will add the `@nx/s3-cache` NPM package and automatically configure it for your workspace. As part of this process you'll be guided to **generate a new activation key**. This is a fully automated process to register your plugin.

The key will be saved in your repository (`.nx/key/key.ini`) and should be committed so that every developer has access to it. If your repository is public (or in CI) you can also use an environment variable:

```dotenv
// .env
NX_KEY=YOUR_ACTIVATION_KEY
```

If you didn't get an activation key or skipped that step, you can easily generate one at any time by running `nx register` in your terminal.

> Why require an activation key? It simply helps us know and support our users. If you prefer not to provide this information, you can also build your own cache server. [Learn more.](/docs/guides/tasks--caching/self-hosted-caching)

### 2. Authenticate with AWS

There are four different ways to authenticate with AWS. They will be attempted in this order:

1. Environment variables
2. INI config files
3. Single sign-on
4. `nx.json` settings

#### Environment variables

[AWS provides environment variables](https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html) that can be used to authenticate:

| **Environment Variable**    | **Description**                                                                                                                                                                                                                                                            |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AWS_ACCESS_KEY_ID`         | The access key for your AWS account.                                                                                                                                                                                                                                       |
| `AWS_SECRET_ACCESS_KEY`     | The secret key for your AWS account.                                                                                                                                                                                                                                       |
| `AWS_SESSION_TOKEN`         | The session key for your AWS account. This is only needed when you are using temporary credentials.                                                                                                                                                                        |
| `AWS_CREDENTIAL_EXPIRATION` | The expiration time of the credentials contained in the environment variables described above. This value must be in a format compatible with the [ISO-8601 standard](https://en.wikipedia.org/wiki/ISO_8601) and is only needed when you are using temporary credentials. |

Both the `AWS_ACCESS_KEY_ID` and the `AWS_SECRET_ACCESS_KEY` environment variables are required to use the environment variable authentication method.

Here's an example of using OIDC in GitHub Actions to set the environment variables in CI:

```yaml
// .github/workflows/ci.yml
name: CI
...
permissions:
  id-token: write
  ...

jobs:
  main:
    env:
      NX_KEY: ${{ secrets.NX_KEY }}
    runs-on: ubuntu-latest
    steps:
        ...

      - name: 'Configure AWS Credentials'
        uses: aws-actions/configure-aws-credentials@v4.0.2
        with:
          role-to-assume: arn:aws:iam::123456789123:role/GhAIBucketUserRole
          aws-region: us-east-1

        ...

      - run: pnpm exec nx affected -t lint test build
```

#### INI config files

AWS can read your authentication credentials from [shared INI config files](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html). The files are located at `~/.aws/credentials` and `~/.aws/config`. Both files are expected to be INI formatted with section names corresponding to profiles. Sections in the credentials file are treated as profile names, whereas profile sections in the config file must have the format of `[profile profile-name]`, except for the default profile. Profiles that appear in both files will not be merged, and the version that appears in the credentials file will be given precedence over the profile found in the config file.

#### Single sign-on

Nx can read the active access token [created after running `aws sso login`](https://docs.aws.amazon.com/sdkref/latest/guide/understanding-sso.html) then request temporary AWS credentials. You can create the `AwsCredentialIdentityProvider` functions using the inline SSO parameters (`ssoStartUrl`, `ssoAccountId`, `ssoRegion`, `ssoRoleName`) or load them from [AWS SDKs and Tools shared configuration and credentials files](https://docs.aws.amazon.com/credref/latest/refdocs/creds-config-files.html). Profiles in the `credentials` file are given precedence over profiles in the `config` file.

#### Credentials in `nx.json` file

Storing your credentials in the `nx.json` file is the least secure of the 4 authentication options, since anyone with read access to your codebase will have access to your AWS credentials.

```jsonc
// nx.json
{
  "s3": {
    "ssoProfile": "default",
    "accessKeyId": "MYACCESSKEYID",
    "secretAccessKey": "MYSECRETACCESSKEY",
  },
}
```

| **Property**        | **Description**                                                               |
| ------------------- | ----------------------------------------------------------------------------- |
| **ssoProfile**      | The name of the profile to use from your AWS CLI SSO Configuration (optional) |
| **endpoint**        | The AWS endpoint URL (optional)                                               |
| **accessKeyId**     | AWS Access Key ID (optional)                                                  |
| **secretAccessKey** | AWS secret access key (optional)                                              |

### 3. Configure S3 cache

Regardless of how you manage your AWS authentication, you need to configure your Nx cache in the `nx.json` file. The `bucket` that you specify needs to already exist - Nx doesn't create it for you.

```jsonc
// nx.json
{
  "s3": {
    "region": "us-east-1",
    "bucket": "my-bucket",
    "encryptionKey": "create-your-own-key",
  },
}
```

| **Property**      | **Description**                                                                   |
| ----------------- | --------------------------------------------------------------------------------- |
| **region**        | The ID of the AWS region to use                                                   |
| **bucket**        | The name of the S3 bucket to use                                                  |
| **encryptionKey** | Nx encryption key used to encrypt and decrypt artifacts from the cache (optional) |

#### S3 compatible providers

To use `@nx/s3-cache` with S3 compatible providers ([MinIO](https://min.io/product/s3-compatibility), [LocalStack](https://www.localstack.cloud), [DigitalOcean Spaces](https://www.digitalocean.com/products/spaces), [Cloudflare](https://www.cloudflare.com/developer-platform/solutions/s3-compatible-object-storage), etc.), `endpoint` will need to be provided. Some providers also need to have `forcePathStyle` set to true in the configuration.

Below is an example on how to connect to MinIO:

```jsonc
// nx.json
{
  "s3": {
    "region": "us-east-1",
    "bucket": "my-bucket",
    "endpoint": "https://play.min.io",
    "forcePathStyle": true,
    "accessKeyId": "abc1234",
    "secretAccessKey": "4321cba",
    "disableChecksum": true,
  },
}
```

{% aside type="note" title="Minio and checksum validation" %}
If you are using MinIO earlier than `2024-07-04T14-25-45Z` it is recommended to enable `disabledChecksum` else you may trigger aws-sdk checksum errors such as `x-amz-checksum-crc32`.
{% /aside %}

| **Property**        | **Description**                                                                                           |
| ------------------- | --------------------------------------------------------------------------------------------------------- |
| **region**          | The ID of the S3 compatible storage region to use                                                         |
| **bucket**          | The name of the S3 compatible storage bucket to use                                                       |
| **forcePathStyle**  | Changes the way artifacts are uploaded. Usually used for S3 compatible providers (MinIO, LocalStack, etc) |
| **endpoint**        | The custom endpoint to upload artifacts to. If endpoint is not defined, the default AWS endpoint is used  |
| **accessKeyId**     | AWS Access Key ID (optional if `AWS_ACCESS_KEY_ID` is set in the environment)                             |
| **secretAccessKey** | AWS secret access key (optional if `AWS_SECRET_ACCESS_KEY` is set in the environment)                     |
| **disableChecksum** | This disables AWS' checksum validation for cache entries                                                  |
| **cacheKeyPrefix**  | Prefix added to cache keys                                                                                |

By default, Nx will try to write and read from the remote cache while running locally. This means that permissions must be set for users who are expected to access the remote cache.

Nx will only show warnings when the remote cache is not writable. You can disable these warnings by setting `localMode` to `read-only` or `no-cache` in the `nx.json` file.

```jsonc
// nx.json
{
  "s3": {
    "region": "us-east-1",
    "bucket": "my-bucket",
    "localMode": "read-only",
  },
}
```

The cache mode in CI can also be configured by setting `ciMode` to `read-only` or `no-cache` in the `nx.json` file. Or by setting `NX_POWERPACK_CACHE_MODE` to `read-only` or `no-cache` in the CI environment.

```jsonc
// nx.json
{
  "s3": {
    "region": "us-east-1",
    "bucket": "my-bucket",
    "ciMode": "read-only",
  },
}
```

# Cache key prefix

The `cacheKeyPrefix` setting enables you to add a prefix to your cache keys, making it possible to store multiple projects or environments within the same storage bucket.

```jsonc
// nx.json
{
  "s3": {
    "cacheKeyPrefix": "designSystem",
  },
}
```

### Migrating from custom tasks runners

Many people who are interested in Nx caching plugins have previously used custom task runners. Nx offers a new and simpler extension API designed to meet the same use cases as the now-deprecated custom task runners.

To learn more about migrating from custom task runners, [please refer to this detailed guide](/docs/reference/deprecated/custom-tasks-runner).

---
<!-- source: https://nx.dev/docs/reference/remote-cache-plugins/shared-fs-cache.md -->
## Shared FS Cache

{% index_page_cards path="reference/remote-cache-plugins/shared-fs-cache" /%}

---
<!-- source: https://nx.dev/docs/reference/remote-cache-plugins/shared-fs-cache/generators.md -->
## @nx/shared-fs-cache - Generators

## `init`

Initialize the shared-fs-cache plugin

**Usage:**

```shell
nx g @nx/shared-fs-cache:init

```

---
<!-- source: https://nx.dev/docs/reference/remote-cache-plugins/shared-fs-cache/overview.md -->
## Overview of the Nx Shared File System Cache Plugin

The `@nx/shared-fs-cache` plugin enables you to host your remote cache on a shared file system directory. While you're responsible for implementing the actual directory sharing mechanism, the plugin configures Nx to read from both your local cache and the shared directory.

{% aside type="tip" title="Free managed remote cache with Nx Cloud" %}

Note, you can get started for free with a **fully managed remote caching powered by Nx Cloud**. It comes with a generous Hobby plan that is enough for most small teams. [Learn more here](https://nx.dev/nx-cloud).

If you are an enterprise and **data privacy and security is a concern**, [reach out for an Enterprise trial](https://nx.dev/enterprise/trial). It is fully SOC 2 type 1 and 2 compliant and comes with single-tenant, dedicated EU region hosting as well as on-premise.

**Are you an OSS project?** Nx Cloud is free for OSS. [Reach out here](https://nx.dev/pricing#oss).

{% /aside %}

{% aside type="caution" title="Bucket-based caches are vulnerable to poisoning and often prohibited in organizations" %}

CREEP (CVE-2025-36852) is a critical vulnerability in bucket-based self-hosted remote caches. It lets attackers with PR access poison production builds via a race condition during artifact creation—before security checks can catch it. [Learn more](https://nx.dev/blog/cve-2025-36852-critical-cache-poisoning-vulnerability-creep)

{% /aside %}

## Set up @nx/shared-fs-cache

### 1. Install the package

Run the following command:

```shell
nx add @nx/shared-fs-cache
```

This will add the `@nx/shared-fs-cache` NPM package and automatically configure it for your workspace. As part of this process, you'll be guided to **generate a new activation key**. This is a fully automated process to register your plugin.

The key will be saved in your repository (`.nx/key/key.ini`) and should be committed so that every developer has access to it. If your repository is public (or in CI), you can also use an environment variable:

```dotenv
// .env
NX_KEY=YOUR_ACTIVATION_KEY
```

> Why require an activation key? It simply helps us know and support our users. If you prefer not to provide this information, you can also build your own cache server. [Learn more.](/docs/guides/tasks--caching/self-hosted-caching)

### 2. configure the cache directory

The `@nx/shared-fs-cache` plugin treats your local cache directory as if it is also a remote cache directory. The local cache directory can be set using `cacheDirectory` in the `nx.json` file or the `NX_CACHE_DIRECTORY` environment variable. The default local cache directory is `.nx/cache`.

### 3. share the cache directory

The `@nx/shared-fs-cache` plugin does not actually share the cache directory across your organization. You are responsible for enabling the actual sharing mechanism. If you want Nx to handle the sharing, use [Nx Replay](/docs/features/ci-features/remote-cache) instead. Your shared file system directory might be a directory that is saved and restored by a CI provider or it could be a shared network drive.

---
<!-- source: https://nx.dev/docs/reference/rollup.md -->
## Rollup

{% sidebar_group_cards group="Reference/Rollup" /%}

---
<!-- source: https://nx.dev/docs/reference/rsbuild.md -->
## Rsbuild

{% sidebar_group_cards group="Reference/Rsbuild" /%}

---
<!-- source: https://nx.dev/docs/reference/rspack.md -->
## Rspack

{% sidebar_group_cards group="Reference/Rspack" /%}

---
<!-- source: https://nx.dev/docs/reference/storybook.md -->
## Storybook

{% sidebar_group_cards group="Reference/Storybook" /%}

---
<!-- source: https://nx.dev/docs/reference/telemetry.md -->
## Telemetry

Nx collects usage data to help improve the developer experience. Telemetry is completely optional and can be disabled at any time.

## Why Nx collects telemetry

Telemetry helps the Nx team understand how Nx is used in practice. This data guides decisions about which features to prioritize, identifies common issues, and helps improve performance. No project-specific or personally identifiable information is collected.

## What is collected

Nx collects general usage data in the following categories:

- **Command usage**: which Nx commands are run (e.g., `build`, `test`, `generate`), how long they take, and how many tasks were executed or cached.
- **Environment info**: operating system, CPU architecture, Node.js version, package manager and version, Nx version, and whether the command runs in CI.
- **General configuration**: whether [Nx Cloud](https://nx.dev/nx-cloud) is connected.

## What about sensitive data?

Nx does **not** collect any metrics that may contain sensitive data.
This includes, but is not limited to: environment variables, personally identifiable information, file paths, contents of files, logs, or git remote information.

For more information, see the [privacy policy](https://cloud.nx.app/privacy).

## How to opt out

When you first run an Nx command in an interactive terminal, Nx asks whether you'd like to share usage data.
If you decline, telemetry is disabled for that workspace.

You can also disable telemetry at any time by setting `analytics` to `false` in your `nx.json`:

```json
// nx.json
{
  "analytics": false
}
```

In CI environments, Nx does not prompt for telemetry. Telemetry only runs in CI if `analytics` is explicitly set to `true` in `nx.json`.

## How to re-enable

To re-enable telemetry, set `analytics` to `true` in your `nx.json`:

```json
// nx.json
{
  "analytics": true
}
```

## Nx Console telemetry

The Nx Console editor extensions (VS Code and JetBrains) collect their own telemetry, separate from the Nx CLI.
For more information, see [Nx Console telemetry](/docs/guides/nx-console/console-telemetry).

---
<!-- source: https://nx.dev/docs/reference/typescript.md -->
## TypeScript

{% sidebar_group_cards group="Reference/TypeScript" /%}

---
<!-- source: https://nx.dev/docs/reference/vite.md -->
## Vite

{% sidebar_group_cards group="Reference/Vite" /%}

---
<!-- source: https://nx.dev/docs/reference/vitest.md -->
## Vitest

{% sidebar_group_cards group="Reference/Vitest" /%}

---
<!-- source: https://nx.dev/docs/reference/vue.md -->
## Vue

{% sidebar_group_cards group="Reference/Vue" /%}

---
<!-- source: https://nx.dev/docs/reference/webpack.md -->
## Webpack

{% sidebar_group_cards group="Reference/Webpack" /%}


# Enterprise

---
<!-- source: https://nx.dev/docs/enterprise.md -->
## Enterprise

{% index_page_cards path="enterprise" /%}

---
<!-- source: https://nx.dev/docs/enterprise/activate-license.md -->
## Activate Enterprise License

{% aside type="caution" title="Enterprise Plan Required" %}
The enterprise features, including Conformance and Owners, require an Nx Enterprise license.
{% /aside %}

Nx Enterprise plan includes features of Nx that are particularly useful for larger organizations. The features include the ability to:

- [Run language-agnostic conformance rules](/docs/enterprise/conformance)
- [Define code ownership at the project level](/docs/enterprise/owners)

{% callout type="deepdive" title="Looking for self-hosted caching?" %}

Self-hosted caching is now free for everyone. [Read more about remote caching options here](/docs/guides/tasks--caching/self-hosted-caching).

{% /callout %}

Activating your enterprise license is a two-step process.

## Step 1: get an activation key

Talk to your Developer Productivity Engineer to get a license key for your workspaces.

## Step 2: register the activation key

{% tabs %}
{% tabitem label="Closed Source Repository" %}

To register the activation key in your repository, run the `nx register` command.

```shell
nx register YOUR_ACTIVATION_KEY
```

The key will be saved in your repository and should be committed so that every developer has access to the enterprise features. **Only one developer needs to run this. The rest of the team will gain access to Nx Enterprise plan features once they pull the changes including the checked-in file.**

Another option is to use an environment variable in CI.

```ini
// .env
NX_KEY=YOUR_ACTIVATION_KEY
```

**Whether you use the `nx register <your-key>` command or set the environment variable, Nx does not make any requests to external APIs. No data is collected or sent anywhere.**

{% /tabitem %}
{% tabitem label="Open Source Repository" %}

Use an environment variable for your activation key such that it is not committed to the repository.

```ini
// .env
NX_KEY=YOUR_ACTIVATION_KEY
```

{% /tabitem %}
{% /tabs %}

---
<!-- source: https://nx.dev/docs/enterprise/configure-conformance-rules-in-nx-cloud.md -->
## Configure Conformance Rules in Nx Cloud

[Nx Cloud Enterprise](https://nx.dev/enterprise) allows you to publish your organization's [Nx Conformance](/docs/enterprise/conformance) rules to your Nx Cloud Organization, and consume them in any of your other Nx Workspaces without having to deal with the complexity and friction of dealing with a private NPM registry or similar. Authentication is handled automatically through your Nx Cloud connection and rules are downloaded and applied based on your preferences configured in the Nx Cloud UI.

To learn about how to create and publish custom rules to your Nx Cloud Organization, please refer to the [Publish Conformance Rules to Nx Cloud](/docs/enterprise/publish-conformance-rules-to-nx-cloud) recipe.

Once you have one or more rules published to your Nx Cloud Organization, you can configure your Nx Cloud Organization to use them in the Nx Cloud UI by visiting:

[https://cloud.nx.app/go/organization/conformance-rules](https://cloud.nx.app/go/organization/conformance-rules)

## Understanding the conformance rules dashboard

The conformance rules dashboard provides comprehensive visibility into your organization's rule adoption and compliance across all workspaces. The interface is designed with two main views to help platform and engineering leaders track and manage conformance standards effectively.

### Rule overview

The **Rule Overview** screen provides a summary of all conformance rules that have been applied across your organization's workspaces. This view displays:

- The current status of each rule (such as "evaluate" or "enforced")
- Which workspaces the rule is active in
- Any violations detected across your repositories
- Overall compliance metrics at a glance

This overview enables you to quickly track adoption and compliance with organizational standards across both Nx and non-Nx repositories.

### Rule metadata overview

The **Rule Metadata Overview** screen gives you a detailed dive into the technical and organizational metadata attached to each rule. This comprehensive view includes:

- Information about the rule's purpose and description
- History of changes and rule evolution
- Current evaluation mode and enforcement status
- Enforcement schedule and timeline information
- Detailed breakdown of which specific workspaces or repositories are in or out of compliance
- Audit trail and rule lifecycle management details

This detailed view supports thorough auditing and makes it easier to manage the lifecycle of rules across a large set of codebases. Both screens are designed to streamline governance and visibility, allowing you to evaluate rollout effectiveness and adoption patterns across your entire organization.

## Choose the scope of configured rules

The value in the dropdown will determine what workspace(s) the rules will be applied to. By default, "All Workspaces" is the selected value, but you can change this to focus on a specific workspace instead.

## Configure a rule for the chosen workspace scope

After choosing the target workspace(s), click on the "Configure rule" to open the rule configuration dialog.

Here you will choose which of the rules published to your Nx Cloud Organization should be applied to the chosen workspace(s), and configure any options that the chosen rule supports.

### Rule options

{% aside type="note" title="Rule Options UI" %}
The rule options are currently provided via JSON, but in the near future we will dynamically generate a UI for configuring the options of each rule.
{% /aside %}

The rule options will be validated against the rule's JSON schema definition before being saved, and you will be notified of any validation errors.

### Rule status

Here you will choose whether or not the rule should be:

- **Enabled**
  - The rule will be executed in the chosen workspace(s) when `nx-cloud conformance` or `nx-cloud conformance:check` is run and any violations will cause the process to fail (exit with a non-zero exit code).
- **Evaluated**
  - The rule will be executed in the chosen workspace(s) when `nx-cloud conformance` or `nx-cloud conformance:check` is run, but any violations will not cause the process to fail (i.e. the process will exit with a zero exit code).
  - This status is useful for exposing violations to allow them to be addressed but without blocking the CI process in the meantime.
  - You can combine this with the [Scheduled Status](#scheduled-status) feature to set a deadline for the chosen workspace(s) to become compliant with the rule.
- **Disabled**
  - The rule will not be executed at all in the chosen workspace(s) and violations will therefore not be reported.

### Scheduled status

By toggling on the "Schedule configuration", you can choose to set a future date on which the rule should be automatically transitioned to an alternate status.

Most commonly this would be used to transition a rule from **Evaluated** to **Enabled** after a grace period, to allow contributors to address the violations before enforcement begins, but any combination of current and scheduled statuses is supported.

## Notes on the application of rules at runtime

When `nx-cloud conformance` or `nx-cloud conformance:check` are run, any configured rules for the current workspace will be dynamically downloaded from your Nx Cloud Organization and applied to the resolved conformance configuration. This means that the conformance configuration itself is completely optional when using it with Nx Cloud, but it can still be useful if the workspace wants to combine cloud rules with other locally-defined rules.

{% aside type="note" title="Organization Rules Override Local Rules" %}
By design, the workspace cannot choose to disable the rules configured in Nx Cloud - any conflict between local and cloud rules will result in the local configuration being overridden by the cloud configuration.
{% /aside %}

If the cloud rules were written to depend on a different version of Nx than is installed within the current workspace, Nx Cloud will handle installing applicable versions dynamically at runtime.

---
<!-- source: https://nx.dev/docs/enterprise/conformance.md -->
## Run Language-Agnostic Conformance Rules

{% youtube src="https://youtu.be/6wg23sLveTQ" title="Nx Conformance" /%}

The [`@nx/conformance`](/docs/reference/conformance/overview) plugin allows [Nx Enterprise plan](https://nx.dev/enterprise) users to write and apply rules for your entire workspace that help with **consistency**, **maintainability**, **reliability** and **security**.

## Why conformance?

Large organizations struggle with maintaining consistency across teams and projects. Manual audits don't scale and developers can't remember every standard. Conformance provides **automated governance** that catches issues before they reach production and enforces policies without manual intervention.

## What does conformance do?

The `@nx/conformance` plugin lets you write custom rules in TypeScript that enforce your organization's standards across **any language or technology** in your codebase. Rules can complement existing linting tools by verifying proper configuration, or enforce entirely new policies around security, architecture, or documentation requirements.

The plugin also provides the following pre-written rules:

- **Enforce Project Boundaries**: Similar to the Nx [ESLint Enforce Module Boundaries rule](/docs/technologies/eslint/eslint-plugin/guides/enforce-module-boundaries), but enforces the boundaries on every project dependency, not just those created from TypeScript imports or `package.json` dependencies.
- **Ensure Owners**: Require every project to have an owner defined for the [`@nx/owners` plugin](/docs/reference/owners)

## Setup

The `@nx/conformance` plugin requires an [Nx Enterprise plan](https://nx.dev/enterprise) to function. [Activating your license](/docs/enterprise/activate-license) is a simple process.

{% call_to_action title="Get a License and Activate Nx Enterprise" icon="nx" description="Unlock all the features of the Nx CLI" url="/docs/enterprise/activate-license" /%}

Then, add the Conformance plugin to your workspace.

{% linkcard title="Conformance Overview"  href="/docs/reference/conformance/overview" /%}

## Configure conformance rules

Conformance rules are configured in the `conformance` property of the `nx.json` file. You can use the pre-defined rules or reference [your own custom rule](/docs/reference/conformance#custom-conformance-rules). See the [plugin documentation](/docs/reference/conformance) for more details.

```jsonc
// nx.json
{
  "conformance": {
    "rules": [
      {
        "rule": "@nx/conformance/enforce-project-boundaries",
        "options": {
          "depConstraints": [
            {
              "sourceTag": "scope:shared",
              "onlyDependOnProjectsWithTags": ["scope:shared"],
            },
          ],
        },
      },
      {
        "rule": "@nx/conformance/ensure-owners",
        "projects": ["!experimental-app"],
      },
      {
        "rule": "./tools/local-conformance-rule.ts",
      },
    ],
  },
}
```

## Enforce rules with the `nx conformance` and `nx conformance:check` commands

The `@nx/conformance` plugin enables two commands:

- **`nx conformance`**: Evaluates rules and applies any available fix generators. Changes are written to disk and rules are evaluated once more to calculate how many violations were fixed. Use this locally while working on feature branches.
- **`nx conformance:check`**: Evaluates rules only. Fix generators are not applied (useful for CI).

Fix generators are only applied for rules whose final status is not `disabled`.

{% tabs %}
{% tabitem label="Nx CLI" %}

```yaml
- name: Enforce all conformance rules
  run: npx nx conformance:check
```

{% /tabitem %}
{% tabitem label="Nx Cloud" %}

```yaml
- name: Enforce all conformance rules
  run: npx nx record -- npx nx conformance:check
```

Use `npx nx record --` to capture the logs for `nx conformance:check` in the Nx Cloud dashboard.

{% /tabitem %}
{% tabitem label="Nx Cloud w/ Enterprise Plan" %}

```yaml
- name: Enforce all conformance rules
  run: npx nx record -- npx nx conformance:check
```

Here we are using the `nx` CLI to run the `conformance:check` command so that we can hook into the power of Conformance rules configured in your Nx Cloud Enterprise organization. Learn more about [conformance rules in Nx Cloud](/docs/enterprise/configure-conformance-rules-in-nx-cloud).

{% /tabitem %}
{% /tabs %}

If a valid license is not available to the workspace (either locally or via Nx Cloud), the `nx conformance` and `nx conformance:check` commands will fail without checking any rules.

## Taking things further with Nx Cloud Enterprise

Organizations on the Nx Cloud Enterprise plan can [publish custom conformance rules](/docs/enterprise/publish-conformance-rules-to-nx-cloud) to their Nx Cloud organization without the friction of a custom registry, and then [configure the rules](/docs/enterprise/configure-conformance-rules-in-nx-cloud) to apply to the workspaces in their organization automatically when `nx conformance` or `nx conformance:check` is run (note that the `nx-cloud` CLI is used in this case in order to handle the authentication with Nx Cloud).

The license will be applied automatically via Nx Cloud in all contexts, and so there is zero setup required for the end developer.

Simply add an appropriate invocation of the `nx conformance:check` command to your CI process and all cloud configured rules will be applied and merged with any local rules:

```yaml
- name: Enforce all conformance rules
  run: npx nx record -- npx nx conformance:check
```

Learn more about [publishing](/docs/enterprise/publish-conformance-rules-to-nx-cloud) and [configuring conformance rules in Nx Cloud](/docs/enterprise/configure-conformance-rules-in-nx-cloud).

## Learn more

- [Conformance Plugin API Reference](/docs/reference/conformance/overview) - Detailed documentation on configuration options and provided rules
- [Create a Custom Conformance Rule](/docs/reference/conformance/create-conformance-rule) - Step-by-step guide to writing your own rules
- [Testing Conformance Rules](/docs/reference/conformance/test-conformance-rule) - Learn how to test your conformance rules
- [Publish Conformance Rules to Nx Cloud](/docs/enterprise/publish-conformance-rules-to-nx-cloud) - Share rules across your organization
- [Configure Conformance Rules in Nx Cloud](/docs/enterprise/configure-conformance-rules-in-nx-cloud) - Manage rules via the Nx Cloud dashboard
- [Blog: Automating Consistency with Nx Cloud Conformance](https://nx.dev/blog/nx-cloud-conformance-automate-consistency) - Learn about the philosophy and benefits of conformance

---
<!-- source: https://nx.dev/docs/enterprise/custom-workflows.md -->
## Custom Workflows

Custom Workflows enable you to run scheduled tasks and automated checks across all or a selection of repositories in your organization. This powerful feature extends beyond traditional CI/CD by creating an avenue to proactively monitor and automate compliance checking, ensuring your organization's standards are maintained consistently.

Custom Workflows are scheduled automation that run independently of your CI/CD pipelines. Unlike traditional workflows that only trigger when code changes, Custom Workflows run on your schedule—whether that's daily, weekly, or at any interval you define. This is especially valuable for repositories that are rarely updated but still need regular monitoring for security vulnerabilities, compliance checks, or organizational standards.

### Real-world value

Some companies have repositories that don't have CI pipelines, or changes are so infrequent that security data would be seriously out of date. For example, running a security audit daily gives you peace of mind in a repository you haven't touched in 6 months—just because you didn't make a code change doesn't mean it's not vulnerable to newly discovered threats.

## Key use cases

- **Security monitoring**: Run `npm audit` or third-party security tools on regular intervals to detect vulnerabilities
- **Compliance tracking**: Ensure all repositories meet organizational standards for linting, testing, or documentation
- **Dependency management**: Track library versions and identify outdated dependencies across your organization
- **Data collection**: Gather metrics and insights from repositories that rarely see code changes
- **Proactive maintenance**: Identify technical debt and maintenance issues before they become critical

{% aside type="note" title="Nx Enterprise Required" %}
Custom Workflows are available as part of Nx Enterprise and [consume compute credits](https://nx.dev/pricing#resource-classes). [Reach out to learn more about Nx Enterprise](https://nx.dev/enterprise)
{%/aside %}

## Access custom workflows

Navigate to your organization's Custom Workflows page in Nx Cloud. You'll see an overview of all the current workflows. Polygraph and Conformance based workflows are currently available. In a future release of Nx Cloud, custom workflow creation will be released.

![Org Overview](../../../assets/enterprise/custom-workflows/org-overview.avif)

## Apply a workflow

{% tabs %}
{% tabitem label="Polygraph workflows" %}
Polygraph workflows are designed to grab the latest graph information from Nx to keep the Workspace graph up to date for your organization.
{% /tabitem %}
{% tabitem label="Conformance workflows" %}
Conformance based workflows allow running the pre-defined conformance rules for a given workspace. Once setup you can also force a rerun of these conformance rules as desired.
{% /tabitem %}
{% /tabs %}

1. Click **Polygraph** or **Conformance** for your repeating workflows provided by Nx Cloud

- if using **Conformance** action, then make sure you've already configured and [published a conformance rule](/docs/enterprise/publish-conformance-rules-to-nx-cloud)
  ![Polygraph overview](../../../assets/enterprise/custom-workflows/org-polygraph-overview.avif)

2. Click **Apply workflow** and select the workspace you wish to use for the custom workflow.
   ![Apply Workflow](../../../assets/enterprise/custom-workflows/apply-workflow.avif)

## Configure workflow settings

In the custom workflows overview, select the **Launch Templates** tab, and assign the launch template you wish to use for the given workspace.

![Custom Workflow Template Assignment](../../../assets/enterprise/custom-workflows/custom-workflow-assign-template.avif)

You can also upload your own custom launch template by clicking **Configure templates**. Read more about [custom launch templates](/docs/reference/nx-cloud/launch-templates)

![Configure custom launch template](../../../assets/enterprise/custom-workflows/custom-workflow-configure-launch-template.avif)

## Perform first run

Back in the custom workflow action page, you can manually trigger a run via clicking **Force**
![Polygraph overview](../../../assets/enterprise/custom-workflows/org-polygraph-overview.avif)

Once your workflow has run, you can view its most recent execution via clicking **View Latest Execution**. If you've used with [Nx Agents](/docs/features/ci-features/distribute-task-execution), then this interface will be familiar. The execution shows each step taken by the workflow and the logs associated with each step.

![Custom Workflow Conformance Run](../../../assets/enterprise/custom-workflows/custom-workflow-conformance-run.avif)

---
<!-- source: https://nx.dev/docs/enterprise/metadata-only-workspace.md -->
## Metadata-Only Workspaces

Metadata-only workspaces are a way to connect repositories to Nx Cloud that don't have Nx installed or configured. Unlike traditional Nx Cloud workspaces that require Nx to be set up in the repository, metadata-only workspaces can be connected with minimal configuration, allowing you to:

- Include any repository in the Workspace Graph
- Run Conformance rules across all repositories
- Use Custom Workflows for automated compliance checking
- Track dependencies and relationships between repositories

The key benefit is **zero changes required to existing repositories** - you can start using [Polygraph features](/docs/enterprise/polygraph) immediately without requiring team buy-in or significant migration effort.

## When to use metadata-Only workspaces

Metadata-only workspaces are ideal for:

1. **Legacy Repository Integration**
   - Gain visibility into previously "dark" areas of your codebase
   - Enforce organizational standards across all repositories, not just new ones
2. **Mixed Technology Stacks**
   - Organizations using multiple frameworks and build tools
   - Teams that prefer their existing tooling but want organizational oversight
3. **Gradual Nx Adoption Strategy**
   - Start with organizational visibility before full Nx migration
   - Allow teams to see the benefits of Nx tooling without immediate commitment
4. **Large-Scale Organizations**
   - Companies with hundreds of repositories across different teams
   - Situations where immediate value is needed without waiting for complete migration

## Connecting

{% aside type="note" title="Onboarding Assistance" %}
Reach out to your assigned developer productivity engineer, if you need any assistance in getting set up with polygraph and metadata-only workspaces.
{%/aside %}

{% tabs %}
{% tabitem label="GitHub Integration" %}

When using the [GitHub VCS Integration](/docs/features/ci-features/github-integration#access-control), you can easily bulk onboard your existing repositories into polygraph.

1. Start with visiting your organization overview in Nx Cloud
2. Click the **Connect a repository** button
3. Click **Connect repositories to polygraph**
4. Follow the prompts to onboard your repositories
   ![Bulk onboard GitHub repositories](../../../assets/enterprise/polygraph/connect-polygraph-to-repos.avif)
5. Click **Connect repositories** to finish

{% /tabitem %}
{% tabitem label="Manual" %}

Manual onboarding is done via the normal workspace onboarding process inside Nx Cloud and enable **polygraph features** before finishing the connection.

1. Start with visiting your organization overview in Nx Cloud
2. Click the **Connect a repository** button
3. Follow the prompts to connect your workspace
4. Enable polygraph features as metadata-only workspace
5. Click **Connect workspace** to finish

Repeat process for each workspace you want to connect as metadata-only workspace.

{% /tabitem %}
{% /tabs %}

---
<!-- source: https://nx.dev/docs/enterprise/owners.md -->
## Define Code Ownership at the Project Level

{% youtube src="https://youtu.be/mor6urvw-L0" title="Nx Codeowners" /%}

This plugin provides [Nx Enterprise plan](https://nx.dev/enterprise) users the ability to configure and maintain code owners for projects in an Nx workspace.

The atomic unit of code in an Nx workspace is a project. Tasks, module boundaries and the Nx graph all train us to conceptualize the workspace as a collection of projects. The CODEOWNERS file, however, requires you to switch from a project mental model to a more low-level definition based on the folder structure of your workspace. The `@nx/owners` plugin enables you to stay in the mental model that your workspace is a collection of projects as you define the ownership rules for your workspace. Nx will take care of compiling the project ownership rules into file-based ownership rules that [GitHub](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners), [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/set-up-and-use-code-owners/) or [GitLab](https://docs.gitlab.com/ee/user/project/codeowners/) can understand in the CODEOWNERS file.

## Setup

The `@nx/owners` plugin requires an Nx Enterprise plan to function. [Activating your license](/docs/enterprise/activate-license) is a simple process.

{% call_to_action title="Get a License and Activate Nx Enterprise plan extensions" icon="nx" description="Unlock all the features of the Nx CLI" url="/docs/enterprise/activate-license" /%}

Then, add the Owners plugin to your workspace.

{% linkcard title="Owners Overview" href="/docs/reference/owners/overview"  /%}

## Project or file-based configuration

The ownership configuration is defined in the `nx.json` file or in individual project configuration files. Nx then uses a [sync generator](/docs/concepts/sync-generators) to automatically compile those settings into a valid CODEOWNERS file for GitHub, Bitbucket or GitLab. See the [plugin documentation](/docs/reference/owners) for more details.

**Define Project Owners**:

```json
// nx.json
{
  "owners": {
    "format": "github",
    "patterns": [
      {
        "description": "Joe's Rust projects",
        "projects": ["tag:rust"],
        "owners": ["@joelovesrust"]
      },
      {
        "description": "Finance projects",
        "projects": ["finance-*"],
        "owners": ["@finance-team"]
      },
      {
        "description": "Alphabet soup",
        "projects": ["admin", "books", "cart"],
        "owners": ["@alice", "@bob", "@cecil"]
      },
      {
        "description": "CI Workflows",
        "files": [".github/workflows/**/*"],
        "owners": ["@devops"]
      }
    ]
  }
}
```

```json
// packages/my-project/project.json
{
  "owners": {
    "**/*": ["@ahmed", "@petra"],
    "package.json": ["@ahmed"]
  },
};
```

**Nx Generates the CODEOWNERS file**

```yaml {% title=".github/CODEOWNERS" %}
# Joe's Rust projects
/packages/rust-api @joelovesrust
/packages/experimental-rust @joelovesrust

# Finance projects
/packages/finance-ui @finance-team
/packages/finance-data @finance-team

# Alphabet soup
/packages/admin @alice @bob @cecil
/packages/books @alice @bob @cecil
/packages/cart @alice @bob @cecil

# CI Workflows
.github/workflows/**/* @devops

/packages/my-project/ @ahmed @petra
/packages/my-project/package.json @ahmed
```

---
<!-- source: https://nx.dev/docs/enterprise/polygraph.md -->
## Nx Enterprise - What is Polygraph?

No longer needing to choose between monorepo or poly-repo.
Polygraph is Nx Cloud's suite of enterprise features designed to help organizations scale their development practices across multiple repositories. These features extend the powerful benefits of an Nx workspace to multi-workspace environments and take Nx Cloud beyond CI.

## Features

- **Cross-repository visibility** through the [Workspace Graph](#workspace-graph)
- **Organizational standards enforcement** via [Conformance](#conformance) rules
- **Automated compliance checking** across all repositories powered by [Custom Workflows](#custom-workflows)

All of this can be enabled with **Zero-friction adoption** for existing repositories without requiring teams to adopt Nx or modify their workflows. With these tools, a platform engineering team is able to affect positive change across 100+ repos quickly in automated fashion, instead of being stuck with manual processes taking multiple months.

{% aside type="note" title="Nx Enterprise" %}
Polygraph features require an Nx Enterprise license. [Reach out to the team](https://nx.dev/contact/sales?utm_source=nx.dev&utm_campaign=polygraph) if you're interested in exploring enterprise!
{%/aside %}

## Use cases

- **🔍 See the Big Picture**: Visualize dependencies across your entire organization, not just within individual repos. Understand organizational structure at a glance and make informed decisions about architecture and team boundaries.

- **📋 Enforce Standards at Scale**: Define and automatically enforce coding standards, tooling requirements, and best practices across 10s or 100s of repositories. Eliminate manual audits and spreadsheet tracking, saving platform teams hundreds of hours per quarter.

- **🛡️ Proactive Auditing and Monitoring**: Run your security tools, or any tool you prefer, on regular intervals to detect and address vulnerabilities quickly, even in repositories that haven't been touched in months.

## Workspace graph

Visualizes dependencies between all repositories in your organization, providing visibility into what repos depend on other repos within the organization.

- **Identify consumers of shared libraries**: Enable confident API changes and deprecations by knowing exactly who will be affected
- **Understand organizational code structure at a glance**: Help leadership make informed decisions about architecture and team boundaries
- **Impact analysis before breaking changes**: See the blast radius of changes across your entire tech stack

![Polygraph Workspace Graph](../../../assets/enterprise/polygraph/workspace-graph.avif)

Quickly onboard new workspaces with the [GitHub VCS integration](/docs/features/ci-features/github-integration#access-control)

![GitHub VCS onboarding](../../../assets/enterprise/polygraph/connect-polygraph-to-repos.avif)

## Conformance

Define and enforce consistency, maintainability, reliability and security standards across your organization.

- **Gradual rule rollout**: Give teams time to fix issues, at a scheduled time, change a rule from _evaluated_ to _enforced_ automatically.
- **Workspace coverage**: Understand which repositories and teams are subject to which rules
- **Compliance control**: Make sure teams are keeping up with organization wide standards that they can't disable when using Nx Cloud as the registry for rules.

![CIPE conformance table view](../../../assets/enterprise/polygraph/cipe-conformance-report.avif)

See an overview of all rules set for the workspace and their current status

![Conformance rules run Table](../../../assets/enterprise/polygraph/conformance-rule-results-table.avif)
![Conformance rules meta table](../../../assets/enterprise/polygraph/conformance-rules-table-run-meta.avif)

You can setup notifications for teams, so they're always kept in the loop

![Conformance notifications](../../../assets/enterprise/polygraph/conformance-notifications.avif)

Ready to write your first conformance rule? [See our conformance guide](/docs/enterprise/conformance) to start.

## Custom workflows

Run scheduled tasks for your needs across all or a selection of repositories.

- **Scheduled execution**: Run checks on your schedule, not just when code changes—especially valuable for rarely updated repositories
- **Notifications for failures**: Keeps responsible parties informed without requiring them to constantly check dashboards
- **Regular compliance monitoring**: Keep security audits current even for repositories with infrequent changes
- **Automated data collection**: Ensures your dashboards and reports always reflect current state without manual intervention

Custom workflows enable proactive monitoring and automated compliance checking, ensuring your dashboards always reflect the current state without manual intervention.

![custom workflows page](../../../assets/enterprise/polygraph/custom-workflow-repeating-workflows.avif)

## Metadata only workspaces

Gain quick visibility across your organization's repositories without needing to migrate each repository as an Nx Workspace.
Easily onboard any repository as a **metadata-only** to immediately start contributing to the [Workspace Graph](#workspace-graph).
Metadata-only workspaces can still leverage [custom workflows](/docs/enterprise/polygraph#custom-workflows) and [conformance rules](/docs/enterprise/conformance).

Read more about [onboarding a workspace as metadata-only](/docs/enterprise/metadata-only-workspace).

## FAQ

**Q: Do I need to migrate other teams to Nx to use Polygraph?**

No, Polygraph works with any repository through [metadata-only workspaces](/docs/enterprise/metadata-only-workspace).

**Q: How does pricing work?**

Existing Nx Cloud Enterprise workspaces include Polygraph at no extra cost. Additional fees apply only for metadata-only workspaces and when consuming compute credits.

**Q: Can I enforce rules gradually?**

Yes, rules can be set to _evaluate_ mode before enforcement, and you can schedule future enforcement dates or outright disable the rule.

**Q: What are the different conformance rule statuses?**

- **Evaluated**: Rule runs and reports violations in dashboards and notifications, but won't fail CI builds; therefore, it's perfect for introducing new standards gradually or giving teams time to prepare for upcoming changes.

- **Enforced**: Rule runs and creates errors that will fail CI builds when violations are found, ensuring immediate compliance. You can schedule rules to automatically transition from evaluated to enforced on a specific date.

- **Disabled**: Rule is turned off and won't run in any workspaces.

**Q: Can I use Conformance with Nx Cloud?**

Yes! Nx Enterprise plan enable conformance rules within individual workspaces. Polygraph extends this by publishing rules across your entire organization, configuring them across multiple workspaces, and tracking results at the organizational level. An Nx Cloud Enterprise license is required for Polygraph features.

{% aside type="tip" title="Ready to start using Polygraph? " %}
Existing enterprise customers should contact their assigned developer productivity engineer to get setup. Otherwise, reach out to us about [Nx Enterprise](https://nx.dev/enterprise) to unlock Polygraph's organizational scaling features.
{%/aside %}

---
<!-- source: https://nx.dev/docs/enterprise/publish-conformance-rules-to-nx-cloud.md -->
## Publish Conformance Rules to Nx Cloud

[Nx Cloud Enterprise](https://nx.dev/enterprise) lets you publish custom [Nx Conformance](/docs/enterprise/conformance) rules to your Nx Cloud Organization and consume them across workspaces — no private NPM registry needed. See [Configure Conformance Rules in Nx Cloud](/docs/enterprise/configure-conformance-rules-in-nx-cloud) for how to manage published rules in the UI.

Let's create a custom rule which we can then publish to Nx Cloud. We will first create a new library project to contain our rule (and any others we might create in the future):

```shell
nx generate @nx/js:library cloud-conformance-rules
```

The Nx Cloud distribution mechanism expects each rule to be created in a named subdirectory in the `src/` directory of our new project, and each rule directory to contain an `index.ts` and a `schema.json` file. You can read more about [creating a conformance rule](/docs/reference/conformance/create-conformance-rule) in the dedicated guide. For this recipe, we'll generate a default rule to use in the publishing process.

```shell
nx g @nx/conformance:create-rule --name=test-cloud-rule --directory=cloud-conformance-rules/src --category=reliability --description="A test cloud rule" --reporter=non-project-files-reporter
```

{% aside type="caution" title="Adding the @nx/conformance plugin" %}
If you get an error resolving the `@nx/conformance` plugin, you may need to add it. You can do this by running `nx add @nx/conformance` in your workspace.
{% /aside %}

We now have a valid implementation of a rule and we are ready to build it and publish it to Nx Cloud. The [`@nx/conformance` plugin](/docs/reference/conformance) provides a [dedicated executor called `bundle-rules`](/docs/reference/conformance/executors#bundle-rules) for creating appropriate build artifacts for this purpose. We will replace the existing build target and wire up that executor in our `cloud-conformance-rules` project's `project.json` file:

```jsonc
// cloud-conformance-rules/project.json
{
  // ...any existing project.json content
  "targets": {
    // ...any other existing targets
    // new build target:
    "build": {
      "executor": "@nx/conformance:bundle-rules",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "{projectRoot}/dist",
      },
    },
  },
}
```

{% aside type="note"  %}
Remove the existing `lib` directory within the `cloud-conformance-rules` project, as it is no longer needed. Each rule will have its own directory, which is generated by the `create-rule` generator, and will need to always have `index.ts` and `schema.json` files.
{% /aside %}

We can now run `nx build cloud-conformance-rules` to build our rule and create the build artifacts in the `cloud-conformance-rules/dist` directory (or wherever you prefer to configure that `outputPath` location). If we take a look at the output path location we will see the same structure of one named subdirectory per rule, now containing the (bundled) `index.js` and `schema.json` files.

Our final step is to publish the rule artifacts to Nx Cloud. We achieve this by running the `publish-conformance-rules` command on the `nx-cloud` CLI, passing the output path location as the first positional argument:

```shell
nx-cloud publish-conformance-rules cloud-conformance-rules/dist
```

Subsequent calls to this command will overwrite the previously published rule artifacts for that rule, including implementation and schema changes. Effectively, the rules are always "at HEAD" and do not therefore have explicit versioning. If you need to support different versions of various setups, you should write the rule implementation to handle it at runtime. This approach helps reduce a lot of complexity and friction when managing Nx Conformance configurations across your organization.

Because publishing the rules is a relatively common operation, you can also wire up a target in your `cloud-conformance-rules` project to wrap the CLI command. Therefore, including our build target from before, our `project.json` file now looks like this:

```jsonc
// cloud-conformance-rules/project.json
{
  // ...any existing project.json content
  "targets": {
    "build": {
      "executor": "@nx/conformance:bundle-rules",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "{projectRoot}/dist",
      },
    },
    "publish": {
      "dependsOn": ["build"],
      "command": "npx nx-cloud publish-conformance-rules {projectRoot}/dist",
    },
  },
}
```

We can now run `nx publish cloud-conformance-rules` to both build and publish our rule (and any future rules in this project) to Nx Cloud.

---
<!-- source: https://nx.dev/docs/enterprise/single-tenant.md -->
## Single Tenant

{% index_page_cards path="enterprise/single-tenant" /%}

---
<!-- source: https://nx.dev/docs/enterprise/single-tenant/auth-bitbucket.md -->
## BitBucket Cloud Auth

This page is only for BitBucket Cloud (bitbucket.org). If you have an on-premise version of BitBucket Data Center please refer to the docs [here](/docs/enterprise/single-tenant/auth-bitbucket-data-center).

First, you'll need to create a BitBucket "OAuth consumer" for your organisation.

## Creating a BitBucket oAuth consumer

From BitBucket, click on your profile picture and select your workspace:

![Step 1](../../../../assets/enterprise/single-tenant/bitbucket_1.png)

Then "Settings":

![Step 2](../../../../assets/enterprise/single-tenant/bitbucket_2.png)

Then "OAuth consumers":

![Step 3](../../../../assets/enterprise/single-tenant/bitbucket_3.png)

And create a new consumer.

Give the app a name. The callback URL is the important bit. It needs to be in this form:

```text
[your-nx-cloud-url]/auth-callback

# for example
https://my.nx-enterprise.url:8080/auth-callback
```

**Important:** Ensure there is **no backslash at the end of the "Callback URL"** (i.e. it matches the above pattern)

![Step 4](../../../../assets/enterprise/single-tenant/bitbucket_4.png)

Ensure you grant it the `account:read` and `account:email` scopes:

![Step 5](../../../../assets/enterprise/single-tenant/bitbucket_5.png)

Save your changes.

Once you create, keep a note of the Key and the Secret:

![Step 6](../../../../assets/enterprise/single-tenant/bitbucket_6.png)

## Connect your Nx Cloud installation to your BitBucket oAuth consumer

Contact your developer productivity engineer to connect your Nx Cloud instance to the newly created BitBucket OAuth consumer.

---
<!-- source: https://nx.dev/docs/enterprise/single-tenant/auth-bitbucket-data-center.md -->
## BitBucket Data Center Auth

This page is for configuring auth via BitBucket Data Center (on-prem). If you are using BitBucket Cloud please refer to the docs [here](/docs/enterprise/single-tenant/auth-bitbucket).

Before creating your container, your Bitbucket Data Center admin will need to create an "Application Link".

## Creating an application link

Your BitBucket installation admin will need to navigate to their installation settings:

![Step 1](../../../../assets/enterprise/single-tenant/bitbucket_onprem_1.png)

Then "Application Links":

![Step 2](../../../../assets/enterprise/single-tenant/bitbucket_onprem_2.png)

And create a new link using the settings below (make sure the callback URL is pointed to your BitBucket installation):

![Step 3](../../../../assets/enterprise/single-tenant/bitbucket_onprem_3.png)

## Connect your Nx Cloud installation to your new app

Contact your developer productivity engineer to connect your Nx Cloud instance to the newly created BitBucket data center app.

---
<!-- source: https://nx.dev/docs/enterprise/single-tenant/auth-github.md -->
## GitHub Auth

First, you'll need to create a GitHub OAuth app for your organisation.

## Creating a GitHub OAuth app

From GitHub, click on your profile picture and chose "Settings":

![Step 1](../../../../assets/enterprise/single-tenant/github_auth_step_1.png)

Then "Developer settings" from the left-hand menu:

![Step 2](../../../../assets/enterprise/single-tenant/github_auth_step_2.png)

Then "OAuth Apps":

![Step 3](../../../../assets/enterprise/single-tenant/github_auth_step_3.png)

And create a new OAuth app:

![Step 4](../../../../assets/enterprise/single-tenant/github_auth_step_4.png)

Give it a name, and a homepage URL. The authorization callback is the important bit. It needs to be in this form:

```text
[your-nx-cloud-url]/auth-callback

# for example
https://my.nx-enterprise.url:8080/auth-callback
```

![Step 5](../../../../assets/enterprise/single-tenant/github_auth_step_5.png)

Once you create, keep a note of the Client ID:

![Step 6](../../../../assets/enterprise/single-tenant/github_auth_step_6.png)

And then generate a new client secret, and save it somewhere secure (we'll use it in a bit):

![Step 7](../../../../assets/enterprise/single-tenant/github_auth_step_7.png)

## Configure Nx Cloud installation

Contact your developer productivity engineer to connect your Nx Cloud instance to the newly created GitHub OAuth app.

---
<!-- source: https://nx.dev/docs/enterprise/single-tenant/auth-gitlab.md -->
## GitLab Auth

Before creating your container, you'll need to create a GitLab app for your organisation.

## Creating a GitLab app

From GitLab, click on your profile picture and chose "Preferences":

![Step 1](../../../../assets/enterprise/single-tenant/gitlab_step_1.png)

Then "Applications" from the left-hand menu:

![Step 2](../../../../assets/enterprise/single-tenant/gitlab_step_2.png)

Give the app a name. The authorization callback is the important bit. It needs to be in this form:

```text
[your-nx-cloud-url]/auth-callback

# for example
https://my.nx-enterprise.url:8080/auth-callback
```

**Important:** Ensure there is **no backslash at the end of the "Redirect URI"** (i.e. it matches the above pattern)

![Step 3](../../../../assets/enterprise/single-tenant/gitlab_step_3.png)

Ensure you grant it the "`read_user`" scope:

![Step 4](../../../../assets/enterprise/single-tenant/gitlab_step_4.png)

Click "Save application".

Once you create, keep a note of the Client ID and the Secret:

![Step 5](../../../../assets/enterprise/single-tenant/gitlab_step_5.png)

## Connect your Nx Cloud installation to your new app

Contact your developer productivity engineer to connect your Nx Cloud instance to the newly created GitLab app.

---
<!-- source: https://nx.dev/docs/enterprise/single-tenant/azure-saml.md -->
## Azure SAML Auth

1. Create a new enterprise app

   ![Create new enterprise application in Azure](../../../../assets/enterprise/single-tenant/saml/azure_1.png)

   ![Select create your own application](../../../../assets/enterprise/single-tenant/saml/azure_2.png)

2. Choose "Create your own":

   ![Choose create your own application option](../../../../assets/enterprise/single-tenant/saml/azure_3.png)

3. Give it a name

   ![Enter enterprise application name](../../../../assets/enterprise/single-tenant/saml/azure_4.png)

4. Assign your users and/or groups to it:

   ![Assign users and groups to application](../../../../assets/enterprise/single-tenant/saml/azure_5.png)

5. Then set-up SSO

   ![Set up single sign-on](../../../../assets/enterprise/single-tenant/saml/azure_6.png)

6. And choose SAML:

   ![Select SAML authentication method](../../../../assets/enterprise/single-tenant/saml/azure_7.png)

7. Add these configuration options
   1. Configure the Identifier **exactly** as `nx-private-cloud`
   2. For the **Reply URL**, it should point to your Private Cloud instance URL. Make sure it ends with `/auth-callback`

   ![Configure SAML identifier and reply URL](../../../../assets/enterprise/single-tenant/saml/azure_8.png)

8. Scroll down and manage claims:

   ![Manage SAML attribute claims](../../../../assets/enterprise/single-tenant/saml/azure_9.png)

9. The first row should be the `email` claim, click to Edit it:

   ![Edit email claim configuration](../../../../assets/enterprise/single-tenant/saml/azure_10.png)

10. Configure it as per below
    1. **"Namespace"** needs to be blank
    2. **"Name:"** needs to be "email"
    3. See screenshot below. This is an important step, because Nx Cloud will expect the "email" property on each profile that logs in.

    ![Set email claim name and namespace](../../../../assets/enterprise/single-tenant/saml/azure_11.png)

    Make sure your application user profile exposes the email address under `user.mail`. This can be configured in `Users and Groups` in the Azure portal. Alternatively, you can always configure the `email` claim to use a different property under the `user` object.

11. Under `SAML Certificates`, click the pencil icon to edit

    ![Edit SAML certificate signing options](../../../../assets/enterprise/single-tenant/saml/azure_12.png)

    For **Signing Option**, select **Sign SAML response and assertion**

    ![Select sign SAML response and assertion](../../../../assets/enterprise/single-tenant/saml/azure_13.png)

    Then click **Save** and close the popover.

12. Download the certificate in **Base64**:

    ![Download Base64 certificate](../../../../assets/enterprise/single-tenant/saml/azure_14.png)

13. Extract the downloaded certificate value as a one-line string:
    1. `awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' azure_cert_file.cer`
    2. We'll use this later
14. Copy the Login URL:

    ![Copy login URL from Azure portal](../../../../assets/enterprise/single-tenant/saml/azure_15.png)

15. Save the following information to send to your DPE:
    1. `SAML_CERT=<your-cert-string-from-above>`
    2. `SAML_ENTRY_POINT=<your-login-url-from-above>`

## Connect your Nx Cloud installation to your sAML set up

Contact your developer productivity engineer to connect your Nx Cloud instance to the SAML configuration.

---
<!-- source: https://nx.dev/docs/enterprise/single-tenant/custom-github-app.md -->
## Custom GitHub App

Before creating your container, you'll need to create a GitHub app for your organisation.

## Creating a GitHub app

From GitHub, click on your profile picture and chose "Settings":

![Step 1](../../../../assets/enterprise/single-tenant/github_auth_step_1.png)

Then "Developer settings" from the left-hand menu:

![Step 2](../../../../assets/enterprise/single-tenant/github_auth_step_2.png)

Then "GitHub Apps":

![Step 3](../../../../assets/enterprise/single-tenant/github_custom_app_step_3.avif)

And create a new GitHub app:

![Step 4](../../../../assets/enterprise/single-tenant/github_custom_app_step_5.avif)

Give it a name, and a homepage URL. The callback URL is the important bit. It needs to be in this form:

```text
[your-nx-cloud-url]/callbacks/github-user

# for example
https://my.nx-enterprise.url:8080/callbacks/github-user
```

Configure a webhook and give it a secret:
(the URL needs to match `https://<your-NxCloud-instance-URL>/nx-cloud/github-webhook-handler`)

![Step 5](../../../../assets/enterprise/single-tenant/webhook.png)

Make sure you subscribe to the "Organization" events:

![Step 5.1](../../../../assets/enterprise/single-tenant/webhook_events.png)

Once you create the app, keep a note of the Client ID and App ID:

![Step 6](../../../../assets/enterprise/single-tenant/github_custom_app_step_6.avif)

Then generate a new client secret, and save it somewhere secure (we'll use it in a bit):

![Step 7](../../../../assets/enterprise/single-tenant/github_auth_step_7.png)

Finally, scroll down and download a private key:

![Step 7](../../../../assets/enterprise/single-tenant/private-key.png)

Then navigate to your download location locally and stringify the contents of the private key:

```bash
awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' your-key.pem # keep a note of the output
```

Save the output of the above, as we'll also use it in a bit.

## Configure permissions for the GitHub app

See the [GitHub App Permissions](/docs/guides/nx-cloud/source-control-integration/github-app-permissions) reference for the full list of required permissions and a detailed breakdown of what each one is used for.

## Connect your Nx Cloud installation

Provide the following values to your developer productivity engineer so they can help connect Nx Cloud to your custom GitHub app:

- Github App Client ID
- Github App Client Secret
- Github App App ID
- Github App Private Key
- GitHub App Webhook Secret

---
<!-- source: https://nx.dev/docs/enterprise/single-tenant/okta-saml.md -->
## Okta SAML Auth

1.  Create a new Okta App Integration:

    ![Create new app integration in Okta admin console](../../../../assets/enterprise/single-tenant/saml/okta_1.png)

    ![Select SAML 2.0 integration type](../../../../assets/enterprise/single-tenant/saml/okta_2.png)

2.  Give it a name:

    ![Enter SAML application name](../../../../assets/enterprise/single-tenant/saml/okta_3.png)

3.  On the Next page, configure it as below:
    1. The Single Sign On URL needs to point to your Nx Cloud instance URL and ends with `/auth-callback`
    2. The Audience should be `nx-private-cloud`

    ![Configure Single Sign On URL and Audience settings](../../../../assets/enterprise/single-tenant/saml/okta_4.png)

4.  Under **Advanced Settings**, make sure both **Response** and **Assertion** are set to **Signed**

    ![Set Response and Assertion signature settings to Signed](../../../../assets/enterprise/single-tenant/saml/okta_11.png)

5.  Scroll down to attribute statements and configure them as per below:

    ![Configure SAML attribute statements](../../../../assets/enterprise/single-tenant/saml/okta_5.png)

6.  Click “Next”, and select the first option on the next screen.
7.  Go to the assignments tab and assign the users that can login to the Nx Cloud WebApp:
    1. **Note:** This just gives them permission to use the Nx Cloud web app with their own workspace. Users will still need to be invited manually through the web app to your main workspace.

    ![Assign users to SAML application](../../../../assets/enterprise/single-tenant/saml/okta_6.png)

8.  Then in the Sign-On tab scroll down:

    ![Navigate to Sign-On tab for certificate download](../../../../assets/enterprise/single-tenant/saml/okta_7.png)

9.  Scroll down and from the list of certificates, download the one with the "Active" status:

    ![Download active SAML signing certificate](../../../../assets/enterprise/single-tenant/saml/okta_8.png)

10. Extract the downloaded certificate value as a one-line string:
    1. `awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' okta.cert`
    2. We'll use this later
11. Then view the ldP metadata:

    ![View identity provider metadata](../../../../assets/enterprise/single-tenant/saml/okta_9.png)

12. Then find the row similar to the below, and copy the highlighted URL (see screenshot as well):

        1. ```html
           <md:SingleSignOnService
             Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
             Location="https://trial-xxxxx.okta.com/app/trial-xxxxx_nxcloudtest_1/xxxxxxxxx/sso/saml"
           />
           ```

        ![Copy SingleSignOnService location URL from metadata](../../../../assets/enterprise/single-tenant/saml/okta_10.png)

## SCIM provisioning

SCIM (System for Cross-domain Identity Management) provisioning enables automatic user lifecycle management for Nx Cloud through Okta.
Once configured, Okta will automatically:

- **Provision new users** when they're added to designated groups
- **Update user permissions** when group memberships change
- **Deprovision users** when they're removed from groups or deactivated

### Enable SCIM provisioning

Select the SAML application you created in the above setup steps.

1. Navigate to **General** then click **Edit**
2. Check **Enable SCIM Provisioning**
3. Click **Save**

![Enable SCIM provisioning in general settings](../../../../assets/enterprise/single-tenant/saml/okta_scim_1.jpg)

### Configure SCIM

After SCIM provisioning is enabled, **Provisioning** tab will become available for the SAML application.

1. Navigate to **Provisioning** then click **Edit**
2. Enter `{NX_CLOUD_APP_URL}/v1/scim` for connector base URL
   - `NX_CLOUD_APP_URL` is provided by your DPE
3. Enter `email` for unique identifier field
4. Check **Push New Users** and **Push Profile Updates**
5. Select **HTTP Header** for authentication mode
6. Enter the JWT token
   - JWT token is provided by your DPE
7. Click **Save**

![Configure SCIM connector base URL and authentication](../../../../assets/enterprise/single-tenant/saml/okta_scim_2.jpg)

After SCIM provision is configured, **To App** settings will become available under **Provisioning** tab

1. Navigate to **Provisioning**
2. Click **To App** then click **Edit**
3. Enable **Create Users**
4. Enable **Update User Attributes**
5. Enable **Deactivate Users**
6. Click **Save**

![Enable SCIM provisioning features to app](../../../../assets/enterprise/single-tenant/saml/okta_scim_3.jpg)

### Add custom attribute for access specification

1. Under **Directory** section, navigate to **Profile Editor**
2. Select your SAML application

![Select SAML application in Profile Editor](../../../../assets/enterprise/single-tenant/saml/okta_scim_4.jpg)

1. Click **Add Attribute**

![Click Add Attribute button](../../../../assets/enterprise/single-tenant/saml/okta_scim_5.jpg)

1. Select `string array` for data type
2. Enter `Nx Cloud Access Spec` for display name
3. Enter `nxCloudAccessSpec` for variable name
   - External name will be populated automatically
4. Enter `urn:ietf:params:scim:schemas:extension:nxcloud:2.0:User` for external namespace
5. Check **Enum**
6. Define enum values
   - `Read` with `nxcloud:organization:{organization_id}:read`
   - `Write` with `nxcloud:organization:{organization_id}:write`
   - `organization_id` can be provided by your DPE
7. Check **Attribute required**
8. Select **Group** for attribute type
9. Click **Save**

![Configure Nx Cloud access specification attribute](../../../../assets/enterprise/single-tenant/saml/okta_scim_6.jpg)

### Provision users

Select the appropriate `nxCloudAccessSpec` value when you assign your SAML application to your Groups.

![Select access specification when assigning application to groups](../../../../assets/enterprise/single-tenant/saml/okta_scim_7.jpg)

## Information to exchange with your DPE

Your DPE will provide the following values up front so you can complete both the SAML and SCIM configuration:

### From your DPE

1. **Nx Cloud App URL** (`NX_CLOUD_APP_URL`) — used as the Single Sign On URL (step 3) and the SCIM connector base URL
2. **JWT Token** — used for SCIM authentication
3. **Organization ID** (`organization_id`) — used when defining the `nxCloudAccessSpec` enum values

### Send back to your DPE

After completing the setup, send the following so your DPE can finish connecting your Nx Cloud instance:

1. **SAML Certificate** — the one-line certificate string extracted in step 10: `SAML_CERT=<your-cert-string>`
2. **SAML Entry Point** — the SingleSignOnService URL copied in step 12: `SAML_ENTRY_POINT=<your-sso-url>`

---
<!-- source: https://nx.dev/docs/enterprise/single-tenant/overview.md -->
## Single Tenant Nx Cloud Hosting

We offer multiple ways of running Nx Cloud for our Enterprise customers. The below options are listed in recommended order, from easiest to most complex in terms of set-up and maintenance for your team. Please carefully consider your organization's requirements and level of infrastructure expertise before deciding on a deployment option.

{% aside title="Get in Touch" type="tip" %}
Get the package that [best fits your needs](https://nx.dev/enterprise)
{% /aside %}

## Multi-tenant

The quickest and easiest way to start using Nx Cloud is by utilizing our pre-existing secure, multi-tenant managed clusters:

- [https://nx.app/](https://nx.app/)
- Enterprise customers can contact their developer productivity engineer (DPE) to configure the EU hosted version of Nx Cloud.

We also offer an uptime SLA guarantee of 99.98% for our Enterprise customers, SOC certificates on request, and we're happy to meet with your security teams if they have questions, or fill in security questionnaires. We also maintain a [Status Page here](https://status.nx.app/).

To start with this option, it's as easy as creating an account on [nx.app](https://cloud.nx.app) and connecting your repository.

## Single tenant instance

If you have very specific requirements, then we can also offer to host Nx Cloud for you in an isolated/single-tenant cluster.

We'll be able to discuss specific requirements such as:

- SAML/SSO
- Specific regions you want your data to be in
- Network isolation / dedicated VPCs
- Dedicated instances
- Different storage encryption than what is available on our multi-tenant instances
- Custom storage replication / redundancy requirements
- Custom Node types for Nx Agents
- Static IPs (if you need to open up connections in your corporate network)
- VPC peering on GCloud or AWS Private Link

This option allows you to define specific parameters of how the instance should run.
Your data and the Nx Cloud will run in complete isolation and will only serve your company. There will be no external API calls to any services outside of the clusters we set-up for you.

Once you let us know you'd like this option, depending on the agreed requirements, it might take a few days to get it set up.

### More stable version of Nx Cloud

The Nx Cloud software that is used in single tenant instances trails the version used in the multi-tenant instance by about month. This allows single tenant customers to benefit from an extra month of real world validation of any new features before enabling those features.

### Easy set up

While the multi-tenant option requires no set up at all, single tenant Nx Cloud still has a simple set up process from your perspective. Since the Nx Cloud team manages the instance, your infrastructure team members do not need to become experts in the specific configuration required to make sure all the parts of Nx Cloud work together correctly. Our team will provision and configure all the hardware required to get your Nx Cloud instance ready. This process usually takes a few days.

### Nx maintenance team

Our team will also manage changes to the Nx Cloud instance.

- As your usage grows, we will take care of allocating and scaling resources.
- When new features are available for Nx Cloud, our team will automatically enable them for you so that you can always have access to the best version of Nx Cloud.
- If you encounter issues with your Nx Cloud instance, we have full access to the set up and can diagnose the problems for you.

{% aside title="Get in Touch" type="tip" %}
Get the package that [best fits your needs](https://nx.dev/enterprise)
{% /aside %}


# Troubleshooting

---
<!-- source: https://nx.dev/docs/troubleshooting.md -->
## Troubleshooting

{% index_page_cards path="troubleshooting" /%}

---
<!-- source: https://nx.dev/docs/troubleshooting/ci-execution-failed.md -->
## Understanding "CI Execution Failed"

## Task runner-related

### No additional tasks detected

Nx Cloud is not aware of any more tasks to distribute. This can occur if Nx Cloud thinks it is done receiving tasks to distribute and all existing tasks have been completed.

If you are receiving this error before your full pipeline has completed, consider using [--stop-agents-after](/docs/reference/nx-cloud-cli#stopagentsafter) with the target set to the last target run in your pipeline.

### The Nx Cloud heartbeat process failed to report its status in time

While running in CI environments, Nx Cloud spawns a background process called the "heartbeat" to help maintain status synchronization between itself and external platforms. When the heartbeat process does not report to Nx Cloud for 30 seconds or longer, Nx Cloud assumes something has gone wrong and terminates the current CI Pipeline Execution.

This behavior can be disabled by setting the [--require-explicit-completion](/docs/reference/nx-cloud-cli#requireexplicitcompletion) flag to `true` on your `nx start-ci-run` command.

### A command was issued to stop all Nx Cloud agents

Nx Cloud provides two commands to forcibly stop agents, [stop-all-agents and complete-ci-run](/docs/reference/nx-cloud-cli#npx-nxcloud-stopallagents). The two command options are functionally equivalent, but the `complete-ci-run` command is preferred.

Once these commands are invoked, the current CI Pipeline Execution is closed and can no longer receive new work.

If this error occurs at the beginning of a CI Pipeline Execution it could be caused by a non-unique [NX_CI_EXECUTION_ID](/docs/reference/environment-variables#nxbranch-and-nxciexecutionid) that is causing Nx Cloud to associate this CIPE with a CIPE that has already concluded.

### Nx Cloud agents were stopped due to an error

Nx Cloud detected a failed task in the current CI Pipeline Execution and has halted further execution.

This behavior can be disabled by setting the [--stop-agents-on-failure](/docs/reference/nx-cloud-cli#stopagentsonfailure) flag to `false` on your `nx start-ci-run` command.

## Nx Agents-related

### Failed to start Nx Agents workflow

Nx Cloud was unable to start the agents workflow with the configuration provided to `nx start-ci-run`. View the CI Pipeline Execution in the Nx Cloud UI for additional details.

### Unable to get workflow status from Nx Agents

Nx Cloud was unable to communicate with the Nx Agents assigned to a workflow for the current CI Pipeline Execution. View the CI Pipeline Execution in the Nx Cloud UI for additional details.

## Status reconciliation-related

### One or more workflows were cancelled

The current CI Pipeline Execution had a workflow cancelled due to either:

- a manual request in the Nx Cloud UI, or
- a push to the same branch that already had a running workflow.

### One or more workflows encountered a critical error

The current CI Pipeline Execution encountered a critical error in a child execution environment. View the CI Pipeline Execution in the Nx Cloud UI for additional details.

### One or more workflows failed

The current CI Pipeline Execution had at least one workflow with failed steps.

### One or more workflows encountered an error

The current CI Pipeline Execution had at least one workflow that executed tasks which failed. See also: [Nx Cloud agents were stopped due to an error](#nx-cloud-agents-were-stopped-due-to-an-error)

### One or more workflows timed out

The current CI Pipeline Execution had at least one workflow that exceeded the timeout duration. View the CI Pipeline Execution in the Nx Cloud UI for additional details.

---
<!-- source: https://nx.dev/docs/troubleshooting/console-troubleshooting.md -->
## Troubleshoot Nx Console Issues

Often, issues with Nx Console are the result of underlying issues with Nx. Make sure to read the [Nx installation troubleshooting docs](/docs/troubleshooting/troubleshoot-nx-install-issues) for more help.

## VSCode + nvm issues

VSCode loads a version of Node when it starts. It can use versions set via [`nvm`](https://github.com/nvm-sh/nvm) but there are some caveats.

- If you've installed Node outside of `nvm` (for example using the Node installer or `brew` on Mac), VSCode will always use that version. You can check by running `nvm list` and looking for a `system` alias. To enable VSCode to pick up your `nvm` version, make sure to uninstall the version of Node that was installed outside of `nvm`.
- VSCode will load the `default` alias from `nvm` at startup. You can set it by running `nvm alias default [version]`. The `default` alias needs to be set in your OS' default terminal for VSCode to pick it up. Setting it in a VSCode-integrated terminal won't persist after it's closed. Similarly, setting it in a third-party app like iTerm won't influence VSCode by default.
- VSCode only loads the `default` version when the app is first started. This means that in order to change it, you need to close all VSCode windows and restart the app - running `Reload Window` won't work.
- If you work with lots of different Node versions, there are various VSCode extensions available to dynamically run `nvm use` whenever you open a new integrated terminal. Search for `nvm`.
- You can set a static version by using a launch configuration with `runtimeVersion` set. Refer to [this guide](https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_multi-version-support).

We try to make noticing discrepancies easier by showing you the currently loaded Node version on startup. To enable this, toggle the `nxConsole.showNodeVersionOnStartup` setting in VSCode.

## JetBrains WSL support

The Node interpreter under Languages & Frameworks > Node.js needs to be configured to use the Node executable within the WSL distribution. You can read more on the [official Jetbrains docs](https://www.jetbrains.com/help/webstorm/how-to-use-wsl-development-environment-in-product.html#ws_wsl_node_interpreter_configure).

---
<!-- source: https://nx.dev/docs/troubleshooting/performance-profiling.md -->
## Profiling Performance

When running an Nx command, many tasks are run at different times in different processes.
Visualizing where and when the tasks were executed can help optimize the entire run to be quicker.

## How to profile the performance of running tasks

{% youtube src="https://youtu.be/Esx-P1Zf1-E" title="Performance Profiling Nx Tasks with Chrome Devtools" /%}

1. Prepend `NX_PROFILE=profile.json` before running targets with Nx. For example,

```shell
# This builds the "cart" application and creates a profile.json file
NX_PROFILE=profile.json nx build cart

# This builds affected projects and creates a profile.json file
NX_PROFILE=profile.json nx affected --target build
```

2. Open the Performance Tab in Chrome Devtools
   ![Performance Profiling with Chrome Devtools](../../../assets/troubleshooting/performance-profiling-devtools.png)
3. Click the upload button and open the `profile.json` that was created. (Or drag the file into the window)
4. Expand each group to see the names of the tasks which were run

### Optimizing the performance of running tasks

Now that you have visualized how the tasks were run, you can try tweaking things to make the process faster. Generate profiles after each tweak and compare the results.

1. Are there tasks that you did not expect to be necessary? Sometimes, more tasks are captured by a command than expected. Excluding them could free up workers for other tasks.
2. Try adding more workers. Did the new workers handle tasks while other workers were busy? This will likely result in faster runs.
3. Are a lot of the tasks waiting on a single task to be completed? Splitting that project into smaller projects may allow fewer projects and therefore tasks to depend on a single project/task. This will allow for more room to parallelize the tasks.

## Profiling Nx commands

{% youtube src="https://youtu.be/olkVyoc2MAQ" title="Performance Profiling Nx" /%}

Nx offloads much of the heavy lifting to the [Nx Daemon](/docs/concepts/nx-daemon), which helps speed up task execution. However, you might still encounter slowdowns, not during the task execution itself, but in the moments leading up to it when invoking tasks through Nx. This can often happen when you're using a large number of [Nx Plugins](/docs/plugin-registry), whether they come from the core team or the community.

To investigate and optimize these slowdowns, you can use the `NX_PERF_LOGGING` [environment variable](/docs/reference/environment-variables). This will give you detailed performance logs and more precise timings, allowing you to pinpoint where the delays occur.

Here's an example of running the `build` of the `admin` project with performance logging enabled:

```shell
NX_PERF_LOGGING=true NX_DAEMON=false npx nx build admin
```

---
<!-- source: https://nx.dev/docs/troubleshooting/resolve-circular-dependencies.md -->
## Resolve Circular Dependencies

A circular dependency is when a project transitively depends on itself. This can cause problems in the design of your software and also makes Nx affected algorithm less effective. The lint rule, `@nx/enforce-module-boundaries`, will produce an error if any circular dependencies are created and ensures that any `import` statements going across projects only `import` from the defined public apis in a project's root `index.ts` file.

When migrating a new codebase into an nx workspace, you'll likely begin to uncover existing circular dependencies. Let's look at the simplest possible circular dependency, where `projectA` depends on `projectB` and vice versa.

**To resolve circular dependencies:**

First, identify the `import` statements causing the dependency. Search in the source folder of `projectA` for references to `@myorg/projectB` and search in the source folder of `projectB` for references to `@myorg/projectA`.

Then there are three strategies you can use:

1. Look for small pieces of code that can be moved from one project to the other.
2. Look for code that both libraries depend on and move that code into a new shared library.
3. Combine `projectA` and `projectB` into one library.

---
<!-- source: https://nx.dev/docs/troubleshooting/troubleshoot-cache-misses.md -->
## Troubleshoot Cache Misses

Problem: A task is being executed when you expect it to be replayed from the cache.

## Check 1: Check if your task is marked as cacheable:

- Check the task has a "Cacheable" label in the Project Details View. You can do so by running `nx show project <project-name> --web` or by checking it in [Nx Console](/docs/guides/nx-console/console-project-details).
- If you're using a version lower than Nx 17.2.0, check:
  - the target configuration in the project's `project.json` file has `"cache": true` set, or
  - the target configuration in `nx.json#targetDefaults` has `"cache": true` set, or

## Check 2: Check if the output of your task is changing the inputs of your task

- Check the `inputs` and `namedInputs` defined in the project configuration and root `nx.json`. The `inputs` control whether a task will execute or replay from cache.
- Check to see if there is an output file that is not being captured by the `outputs` for the task. The `outputs` property only controls what files are replayed from the cache, it doesn't dictate whether the cache is replayed, but an unaccounted output file could be modifying one of the inputs of the task.
- To check your input glob patterns file-by-file, you can get a list of all the files associated with each project by running `nx graph --file=output.json` or by clicking on a task in the task graph in the `nx graph` visualization.

## Check 3: Use the Nx Cloud troubleshooting tools

{% youtube src="https://youtu.be/zJmhW1iIxpc" title="Debug remote cache misses with Nx Cloud" /%}

1. Make sure your repo is [connected to Nx Cloud](/docs/features/ci-features/remote-cache)
2. Click on the run details link that is printed in the terminal after you run a task. You can search for and filter tasks by cache status to find the task with the cache miss you want to investigate.

![Run details page showing task list filtered by cache miss status](../../../assets/guides/nx-cloud/run-details.jpg)

3. Click on the task with the cache miss to open the task details panel, then click the "Compare to similar tasks" button.

![Task details panel showing the Compare to similar tasks button](../../../assets/guides/nx-cloud/run-details-task-details.jpg)

4. Select one of the similar tasks from the list in the "Compared to" section, or paste a run URL to compare against a specific run.

![Compare tasks view showing the run selection panel](../../../assets/guides/nx-cloud/compare-tasks-select-run.jpg)

5. Nx Cloud will compare the hash inputs of both tasks and highlight all the differences, making it easy to identify which inputs changed.

![Compare tasks diff view showing hash input differences between two task runs](../../../assets/guides/nx-cloud/compare-tasks-diff.jpg)

{% aside type="note" title="Note" %}
Nx Cloud cannot access your source code, so it can only tell you which inputs are different based on their saved content hash, but not the exact git diff of the source code.
{% /aside %}

---
<!-- source: https://nx.dev/docs/troubleshooting/troubleshoot-convert-to-inferred.md -->
## Troubleshoot Convert to Inferred Migration

Nx comes with plugins that automatically [infer tasks](/docs/concepts/inferred-tasks) (i.e. Project Crystal) for your
projects based on the configuration of different tools. Inference plugins come with many benefits, such as reduced
boilerplate and access to features such as [task splitting](/docs/features/ci-features/split-e2e-tasks). To make the transition easier
for existing projects that are not yet using inference plugins, many plugins provide the `convert-to-inferred` generator
that will switch from executor-based tasks to inferred tasks.

To see a list of the available migration generators, run:

```shell
nx g convert-to-inferred
```

This will prompt you to choose a plugin to run the migration for.

Although the `convert-to-inferred` generator should work for most projects, there are situations that require additional
changes to be done by hand. If you run into issues that are not covered on this page, please open an issue
on [GitHub](https://github.com/nrwl/nx/issues).

## Error: The nx plugin did not find a project inside...

This error occurs when a configuration file matching the tooling cannot be found. For example, Vite works
with `vite.config.ts` (or `.js`, `.cts`, `.mts`, etc.). If you've named your configuration file to something
unconventional, you must rename it back to the standard naming convention before running the migration generator again.

For example, if you have a `apps/demo/vite.custom.ts` file and are running `nx g @nx/vite:convert-to-inferred`, you must
first rename the file to `apps/demo/vite.config.ts` before running the generator.

## Next.js: unable to migrate `outputPath`, `generateLockfile` and `includeDevDependenciesInPackageJson` options

The [`outputPath`](/docs/technologies/react/remix/executors#build) option from `@nx/next:build` is ignored because it
conflicts with Next.js' requirement that [`distDir`](https://nextjs.org/docs/app/api-reference/next-config-js/distDir)
remain inside the project directory. Previously, the `@nx/next:build` executor performed workarounds to bring it outside
the project root, but those workarounds lead to other issues, such as Turbopack not working.

To customize the output directory, set `distDir` in your Next.js config file.

```js
const configuration = process.env.NX_TASK_TARGET_CONFIGURATION || 'default';
// ...
const nextConfig = {
  nx: {
    ...options,
  },
  // Differentiate production and development builds. You can also use the `configuration` variable that will match the `--configuration` option passed to Nx.
  distDir: process.env.NODE_ENV === 'production' ? 'dist' : 'dist-dev',
};
const plugins = [withNx];
module.exports = composePlugins(...plugins)(nextConfig);
```

Since the output directory is now inside the project, we do not generate `package.json` since it is already present. The
lockfile generation support also no longer exists, which does not affect deployments to Vercel, Netlify, or similar
environments. However, it could affect deployments via Docker images where you do not copy the whole monorepo, but
rather just the build artifacts.

These removals are necessary to align with Next.js recommendations.

## Next.js: Nx `serve` only starts dev server

To better align with Next.js CLI, projects after the migration have two targets to start the server:

1. `serve` - Starts the dev server (same as `next dev`)
2. `start` - Starts the prod server (same as `next start`)

Note that `serve` could be different depending on what you used for `@nx/next:server` previously. After the
migration, `nx run <proj>:serve --prod` not longer starts the prod server. Use `nx run <proj>:start` instead.

## Remix: unable to migrate `outputPath` option

The [`outputPath`](/docs/technologies/react/remix/executors#build) option from `@nx/remix:build` is ignored because it often
leads to ESM errors when the output path is outside the project root. The ESM error occurs because the
root `package.json` may not have `"type": "module"` set, which means that the compiled ESM code will fail to run. To
guarantee that `serve` works, we migrate the outputs to the Remix defaults (`build` and `public/build` inside the
project root). If you have custom directories already defined in your Remix config, it will continue to be used.

To change the outputs after the migration, edit the remix config file, and look for `serverBuildPath`
and `assetsBuildDirectory` and set it to the locations you want.

```ts
// ...
export default {
  assetsBuildDirectory: '../../dist/apps/demo/public/build',
  serverBuildPath: '../../dist/apps/demo/build/index.js',
  // ...
};
```

Note that you will need to address potential ESM issues that may arise. For example, change the root `package.json`
to `"type": "module"`.

## Remix: unsupported `generatePackageJson` and `generateLockFile` options

The `generatePackageJson` and `generateLockFile` options in [`@nx/remix:build`](/docs/technologies/react/remix/executors#build) cannot
currently be migrated. There is support for this feature in
the [Nx Vite plugin](/docs/technologies/build-tools/vite/guides/configure-vite#typescript-paths), so in the future we may be able to support it if
using Remix+Vite.

## Storybook: conflicting `staticDir` options

Using `staticDir` for both `@nx/storybook:build-storybook` and `@nx/storybook:storybook` executor options will result in
the one from `build-storybook` being used in the resulting `.storybook/main.ts` file. It is not possible for us to
support both automatically.

If you need to differentiate `staticDir` between build and serve, then consider putting logic into your `main.ts` file
directly.

```ts
// ...
const config: StorybookConfig = {
  // ...
  staticDirs:
    process.env.NODE_ENV === 'production'
      ? ['../static-prod']
      : ['../static-dev'],
};

export default config;
```

## Vite: unsupported `proxyConfig` option

Projects that used the [`proxyConfig`](/docs/technologies/build-tools/vite/executors#dev-server) option of `@nx/vite:dev-server`
will need to inline the proxy configuration from the original file into `vite.config.ts`.

For example, if you previously used this in `proxy.config.json`:

```json
{
  "/api/*": {
    "target": "http://localhost:3333"
  }
}
```

Then, you will need to add this entry to your `vite.config.ts` file:

```ts
export default defineConfig({
  //...
  server: {
    // ...
    proxy: {
      '/api': {
        target: 'http://localhost:3333',
      },
    },
  },
});
```

## Webpack: project cannot be migrated

Projects that
use [Nx-enhanced Webpack configuration](/docs/technologies/build-tools/webpack/guides/webpack-config-setup#nxenhanced-configuration-with-composable-plugins)
files cannot be migrated to use Webpack CLI. Nx-enhanced configuration files that contain `composePlugins` and `withNx`
require the `@nx/webpack:webpack` executor to work.

To solve this issue, run `nx g @nx/webpack:convert-config-to-webpack-plugin` first, and then try again.

## Webpack: usage of `useLegacyNxPlugin`

When converting
from [Nx-enhanced](/docs/technologies/build-tools/webpack/guides/webpack-config-setup#nxenhanced-configuration-with-composable-plugins) to basic
Webpack configuration, we add the `useLegacyNxPlugin` utility function to
ensure that your build tasks behave the same after the migration. We recommend that you refactor the configuration such
that `useLegacyNxPlugin` is not needed.

For example, if you previously added plugins using the configuration function.

```js
// webpack.config.old.js
modules.exports = (config) => {
  config.plugins.push(new SomePlugin());
  return config;
};
```

Then, we recommend that you move the plugin entry to the new configuration file, in the `plugins` option.

```js
module.exports = async () => ({
  devServer: devServerOptions,
  plugins: [new NxAppWebpackPlugin(pluginOptions), new SomePlugin()],
});
```

If you need to apply configuration changes after `NxAppWebpackPlugin` is applied, then you can create a plugin object as
follows.

```js
module.exports = async () => ({
  devServer: devServerOptions,
  plugins: [
    new NxAppWebpackPlugin(pluginOptions),
    {
      apply(compiler) {
        const babelLoader = compiler.options.module.rules.find(
          (rule) =>
            rule &&
            typeof rule !== 'string' &&
            rule.loader?.toString().includes('babel-loader')
        );

        // do something with `babelLoader...
      },
    },
  ],
});
```

---
<!-- source: https://nx.dev/docs/troubleshooting/troubleshoot-nx-install-issues.md -->
## Troubleshoot Nx Installations

Here are some common scenarios we came across while trying to run Nx on CIs

## Native modules

Nx publishes native binaries that should be automatically downloaded and installed when Nx is used.

If you see a message saying that your platform is not supported (or that Nx cannot find a `@nx/nx-platform` module for versions of Nx between 15.8 and 16.4), there
are a few reasons why this could potentially happen:

1. Running your install command with `--no-optional` (or the relative flag in yarn, pnpm, etc)
1. Running your install with `--dev` for pnpm.
1. The package-lock.json file was not correctly updated by npm, and missed optional dependencies used by Nx.
   You can read more about this [issue on the npm repository.](https://github.com/npm/cli/issues/4828)
1. [Your platform is not supported](#supported-native-module-platforms)
1. [Node.js wasn't installed for the proper architecture ](#nodejs-installation-issues)

{% aside type="note" title="Updating Nx" %}
When updating Nx that is already on 15.8, the package-lock.json should continue to be updated properly with all the proper optional dependencies.
{% /aside %}

### How to fix

1. If you are running your install command with `--no-optional`, try again without the flag.
1. Delete your node_modules and `package-lock.json` (or other lock files) and re-run your package manager's install command.
1. If running on Windows, make sure that the [installed Microsoft Visual C++ Redistributable is up-to-date](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads).

Confirm that you see `@nx/nx-<platform-arch>` in your `node_modules` folder (e.g. `@nx/nx-darwin-arm64`, `@nx/nx-win32-x64-msvc`, etc).

If you are still experiencing issues after following the previous steps, please [open an issue on GitHub](https://github.com/nrwl/nx/issues/new?assignees=&labels=type:+bug&projects=&template=1-bug.yml) and we will help you troubleshoot.
Be prepared to give as much detail as possible about your system, we will need the following information at a minimum, the contents of `nx report` plus

- Operating system version
- The package manager (npm, yarn, pnpm, etc) install command

### Supported native module platforms

We publish modules for the following platforms:

- macOS 11+ (arm64, x64)
- Windows (arm64, x64)
  - We use the `msvc` target, so as long as Microsoft supports your Windows version, it should work on it
- Linux (arm64, x64)
  - We use `gnu` ang `musl` targets, which are used by the most popular Linux distributions
- FreeBSD (x64)

If you're running a machine that isn't part of the list above, then Nx does not support it at this time. [Please open an issue on GitHub](https://github.com/nrwl/nx/issues/new/choose) if you feel Nx should support that platform and we will assess what can be done, please make sure to include your platform and architecture in the issue.

### Node.js installation issues

Ensure that the architecture of your Node.js installation matches your hardware. Run `nx report` and check that the `OS` property is correct (e.g. `darwin-arm64` for MacOS on Apple silicon). If it contains `x64` even though you're on an `arm64` chip, then something is wrong. A mismatch in architecture can lead to errors loading Nx native binary.

Often, the culprit of the mismatch is a faulty installation of your toolchain: Homebrew (MacOS), Node.js or VSCode (if using Nx Console). You should reinstall your toolchain with the correct architecture. Run `nx report` again to validate the installation.

For issues inside VSCode or Nx Console, also refer to the [Nx Console troubleshooting docs](/docs/guides/nx-console/console-troubleshooting)

---
<!-- source: https://nx.dev/docs/troubleshooting/unknown-local-cache.md -->
## Unknown Local Cache Error

This document will explain why the following errors happen and how to address them.

```text
NX Invalid Cache Directory for Task "myapp:build"

The local cache artifact in ".nx/cache/nx/786524780459028195" was not generated on this machine.
As a result, the cache's content integrity cannot be confirmed, which may make cache restoration potentially unsafe.
If your machine ID has changed since the artifact was cached, run "nx reset" to fix this issue.
Read about the error and how to address it here: https://nx.dev/troubleshooting/unknown-local-cache
```

```text
NX Unrecognized Cache Artifacts

Nx found unrecognized artifacts in the cache directory and will not be able to use them.
Nx can only restore artifacts it has metadata about.
Read about this warning and how to address it here: https://nx.dev/troubleshooting/unknown-local-cache
```

## Nx tracks cache source

Nx can cache tasks, which can drastically speed up your CI and local builds. However, this comes with the potential risk
of "cache poisoning", where cache artifacts could be intentionally or inadvertently overwritten. If another user
executes a task that matches the hash of the tainted artifact, they could retrieve the corrupted artifact and use it as
the outcome of the task. Nx and Nx Cloud contain several safeguards to minimize the likelihood of cache poisoning or, in
the case of Nx Cloud, completely prevent it.

The errors above are some of these safeguards.

Nx trusts the local cache. If you executed a task and stored the corresponding cached artifact on your machine, you can
safely restore it on the same machine without worrying about cache poisoning. After all, in order to tamper with the
cache artifact, the actor would need access to the machine itself.

However, when artifacts in the local cache are created by a different machine, we cannot make such assumption. By
default, Nx will refuse to use such artifacts and will throw the "Invalid Cache Directory" error or "Unrecognized Cache Artifacts" error.

## Your machineId has changed

Upgrading your computer's hardware may alter its Machine ID, yielding one of the errors above. To fix it execute `nx reset` to
remove all the cache directories created under the previous Machine ID. After doing so, you should no longer see the
error.

## You share cache with another machine using a network drive

When using the legacy file system cache ([deprecated in Nx 20](/docs/reference/deprecated/legacy-cache)), you can prefix any Nx command with `NX_REJECT_UNKNOWN_LOCAL_CACHE=0` to ignore the errors (
e.g., `NX_REJECT_UNKNOWN_LOCAL_CACHE=0 nx run-many -t build test`). This is similar to
setting `NODE_TLS_REJECT_UNAUTHORIZED=0` to ignore any errors stemming form self-signed certificates. Even though it
will make it work, this approach is discouraged.

Storing Nx local cache on a network drive presents security risks, so we prevent you from doing so. When a network drive is shared, every CI run has access to all the previously created Nx cache artifacts. Hence, it is plausible for every single artifact - for every
single task hash - to be accessed without leaving any trace. This is possible due to the network drive's capability to
allow overwrites.

## How Nx Replay makes sure sharing cache is safe

[Nx Replay](/docs/features/ci-features/remote-cache), the Nx Cloud hosted remote cache, does the following things to make sharing the cache safe:

1. **Immutable Artifacts:** Nx Cloud allows you to create and store new artifacts without the ability to override the
   existing ones. This prevents any possibility of poisoning an existing artifact. This is achieved by managing the
   cache using short-lived signed URLs.

2. **Artifact Accessibility:** Nx Cloud provides access to the cache artifact specifically for the task that is
   currently being executed. It restricts the ability to list all cache artifacts.

3. **Visibility Control:** Nx Cloud comes with options to manage the visibility of your cache artifacts. For instance,
   the cache artifacts created in `main` might be accessible by anyone across any branch, whereas the artifacts created
   in your PR could be shared only within your PR runs.

4. **Access Token Traceability:** Nx Cloud keeps a record of the access token used to create a cache artifact. In case an access token gets compromised it can be easily removed, in turn deleting all the cache artifacts that were created using it.


# how-nx-works

---
<!-- source: https://nx.dev/docs/how-nx-works.md -->
## How Nx Works

{% sidebar_group_cards group="How Nx Works" /%}


# knowledge-base

---
<!-- source: https://nx.dev/docs/knowledge-base.md -->
## Knowledge Base

{% sidebar_group_cards group="Knowledge Base" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/angular.md -->
## Angular

{% sidebar_group_cards group="Knowledge Base/Angular" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/benchmarks.md -->
## Benchmarks

{% sidebar_group_cards group="Knowledge Base/Benchmarks" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/continuous-integration.md -->
## Continuous Integration

{% sidebar_group_cards group="Knowledge Base/Continuous Integration" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/creating-releases.md -->
## Creating Releases

{% sidebar_group_cards group="Knowledge Base/Creating Releases" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/cypress.md -->
## Cypress

{% sidebar_group_cards group="Knowledge Base/Cypress" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/dotnet.md -->
## .NET

{% sidebar_group_cards group="Knowledge Base/.NET" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/eslint.md -->
## ESLint

{% sidebar_group_cards group="Knowledge Base/ESLint" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/extending-nx.md -->
## Extending Nx

{% sidebar_group_cards group="Knowledge Base/Extending Nx" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/installation.md -->
## Installation

{% sidebar_group_cards group="Knowledge Base/Installation" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/module-federation.md -->
## Module Federation

{% sidebar_group_cards group="Knowledge Base/Module Federation" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/node.md -->
## Node

{% sidebar_group_cards group="Knowledge Base/Node" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/nx-console.md -->
## Nx Console

{% sidebar_group_cards group="Knowledge Base/Nx Console" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/organizational-decisions.md -->
## Organizational Decisions

{% sidebar_group_cards group="Knowledge Base/Organizational Decisions" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/playwright.md -->
## Playwright

{% sidebar_group_cards group="Knowledge Base/Playwright" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/react.md -->
## React

{% sidebar_group_cards group="Knowledge Base/React" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/recipes.md -->
## Recipes

{% sidebar_group_cards group="Knowledge Base/Recipes" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/storybook.md -->
## Storybook

{% sidebar_group_cards group="Knowledge Base/Storybook" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/tasks-caching.md -->
## Tasks & Caching

{% sidebar_group_cards group="Knowledge Base/Tasks & Caching" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/troubleshooting.md -->
## Troubleshooting

{% sidebar_group_cards group="Knowledge Base/Troubleshooting" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/typescript.md -->
## TypeScript

{% sidebar_group_cards group="Knowledge Base/TypeScript" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/vite.md -->
## Vite

{% sidebar_group_cards group="Knowledge Base/Vite" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/vitest.md -->
## Vitest

{% sidebar_group_cards group="Knowledge Base/Vitest" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/vue.md -->
## Vue

{% sidebar_group_cards group="Knowledge Base/Vue" /%}

---
<!-- source: https://nx.dev/docs/knowledge-base/webpack.md -->
## Webpack

{% sidebar_group_cards group="Knowledge Base/Webpack" /%}


# platform-features

---
<!-- source: https://nx.dev/docs/platform-features.md -->
## Platform Features

{% sidebar_group_cards group="Platform Features" /%}

---
<!-- source: https://nx.dev/docs/platform-features/code-organization.md -->
## Code Organization

{% sidebar_group_cards group="Platform Features/Code Organization" /%}

---
<!-- source: https://nx.dev/docs/platform-features/code-organization/enforce-module-boundaries.md -->
## Enforce Module Boundaries

{% sidebar_group_cards group="Platform Features/Code Organization/Enforce Module Boundaries" /%}

---
<!-- source: https://nx.dev/docs/platform-features/enterprise.md -->
## Enterprise

{% sidebar_group_cards group="Platform Features/Enterprise" /%}

---
<!-- source: https://nx.dev/docs/platform-features/enterprise/conformance-reference.md -->
## Conformance Reference

{% sidebar_group_cards group="Platform Features/Enterprise/Conformance Reference" /%}

---
<!-- source: https://nx.dev/docs/platform-features/enterprise/single-tenant.md -->
## Single Tenant

{% sidebar_group_cards group="Platform Features/Enterprise/Single Tenant" /%}

---
<!-- source: https://nx.dev/docs/platform-features/maintenance.md -->
## Maintenance

{% sidebar_group_cards group="Platform Features/Maintenance" /%}

---
<!-- source: https://nx.dev/docs/platform-features/orchestration-ci.md -->
## Orchestration & CI

{% sidebar_group_cards group="Platform Features/Orchestration & CI" /%}

---
<!-- source: https://nx.dev/docs/platform-features/release-publishing.md -->
## Release & Publishing

{% sidebar_group_cards group="Platform Features/Release & Publishing" /%}


# technologies-tools

---
<!-- source: https://nx.dev/docs/technologies-tools.md -->
## Technologies & Tools

{% sidebar_group_cards group="Technologies & Tools" /%}

---
<!-- source: https://nx.dev/docs/technologies-tools/build-tools.md -->
## Build Tools

{% sidebar_group_cards group="Technologies & Tools/Build Tools" /%}

---
<!-- source: https://nx.dev/docs/technologies-tools/frameworks-libraries.md -->
## Frameworks & Libraries

{% sidebar_group_cards group="Technologies & Tools/Frameworks & Libraries" /%}

---
<!-- source: https://nx.dev/docs/technologies-tools/test-tools.md -->
## Test Tools

{% sidebar_group_cards group="Technologies & Tools/Test Tools" /%}