> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nrwl/nx/llms.txt
> Use this file to discover all available pages before exploring further.

# nx.json

> Complete reference for the nx.json configuration file, which controls Nx CLI behavior, project defaults, caching, plugins, and release settings.

The `nx.json` file configures the Nx CLI and workspace-wide project defaults. It lives at the root of your workspace. The full machine-readable schema is available at [`packages/nx/schemas/nx-schema.json`](https://github.com/nrwl/nx/blob/master/packages/nx/schemas/nx-schema.json).

Below is an expanded example showing all common options. Your actual `nx.json` will be much shorter.

```json nx.json theme={null}
{
  "plugins": [
    {
      "plugin": "@nx/eslint/plugin",
      "options": {
        "targetName": "lint"
      }
    }
  ],
  "parallel": 4,
  "cacheDirectory": "tmp/my-nx-cache",
  "defaultBase": "main",
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "sharedGlobals": [],
    "production": ["default", "!{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
    }
  },
  "generators": {
    "@nx/js:library": {
      "buildable": true
    }
  },
  "extends": "nx/presets/npm.json"
}
```

## Top-level task options

The following properties control how Nx runs tasks.

<ParamField body="parallel" type="number">
  Maximum number of tasks Nx runs in parallel. Defaults to `3`. Can also be
  overridden per-invocation with `--parallel=<n>`.
</ParamField>

<ParamField body="cacheDirectory" type="string">
  Directory where the local task output cache is stored. Defaults to
  `.nx/cache`. Override with the `NX_CACHE_DIRECTORY` environment variable.
</ParamField>

<ParamField body="defaultBase" type="string">
  The base branch used by `nx affected` to determine which projects changed.
  Defaults to `"main"`. Override with the `NX_BASE` environment variable or
  `--base` flag.
</ParamField>

<ParamField body="defaultProject" type="string">
  The project used when no project is specified on the command line, e.g. bare
  `nx build`. Override with the `NX_DEFAULT_PROJECT` environment variable.
</ParamField>

<ParamField body="useDaemonProcess" type="boolean">
  Whether to use the Nx daemon for computing the project graph. Defaults to
  `true`. Disable with `NX_DAEMON=false`.
</ParamField>

<ParamField body="extends" type="string">
  Specifies a base configuration file to extend. Nx preset files live in
  `node_modules/nx/presets/`, e.g. `"nx/presets/npm.json"`.
</ParamField>

<ParamField body="maxCacheSize" type="string">
  Maximum size of the local task cache. Accepts bytes or unit suffixes:
  `"819200"`, `"100MB"`, `"1GB"`, or `"0"` to disable the limit. When the cache
  exceeds this size, Nx evicts the least-recently-used entries. Defaults to 10%
  of disk size, up to 10 GB. Override with `NX_MAX_CACHE_SIZE`.
</ParamField>

## Plugins

Nx plugins extend the project graph and can automatically infer tasks from tooling configuration files. Register a plugin in the `plugins` array. Plugins with no options can be a plain string; plugins with options must be an object.

```json nx.json theme={null}
{
  "plugins": [
    "@my-org/graph-plugin",
    {
      "plugin": "@nx/eslint/plugin",
      "options": {
        "targetName": "lint"
      }
    }
  ]
}
```

<ParamField body="plugin" type="string" required>
  The npm package or local path of the plugin module to load.
</ParamField>

<ParamField body="options" type="object">
  Plugin-specific options passed when the plugin creates nodes and dependencies.
  Consult each plugin's documentation for available options.
</ParamField>

<ParamField body="include" type="array">
  Glob patterns for configuration files the plugin should process. Only projects
  whose config file path matches will have tasks inferred by this plugin.
</ParamField>

<ParamField body="exclude" type="array">
  Glob patterns for configuration files the plugin should ignore. Supports
  negation patterns (prefixed with `!`). Patterns are applied in order.
</ParamField>

### Scoping plugins to specific projects

Use `include` and `exclude` to control which projects a plugin processes.

```json nx.json theme={null}
{
  "plugins": [
    {
      "plugin": "@nx/jest/plugin",
      "include": ["packages/**/*"],
      "exclude": ["**/*-e2e/**/*"]
    }
  ]
}
```

<Tip>
  Negation patterns let you carve out exceptions. For example,
  `"exclude": ["**/*-e2e/**/*", "!**/toolkit-workspace-e2e/**/*"]` excludes all
  e2e projects except `toolkit-workspace-e2e`.
</Tip>

## namedInputs

Named inputs are reusable input definitions that can be referenced by name in `targetDefaults` and individual target configurations. They are defined as a map of name to input array.

```json nx.json theme={null}
{
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "sharedGlobals": [],
    "production": ["default", "!{projectRoot}/**/*.spec.tsx"]
  }
}
```

Named inputs defined in `nx.json` apply to all projects. Projects can override them in their own `project.json` or `package.json`.

<CardGroup cols={2}>
  <Card title="Inputs reference" href="/reference/inputs">
    Full documentation of all input types: filesets, env vars, runtime commands,
    external dependencies, and more.
  </Card>

  <Card title="Task caching guide" href="/features/cache-task-results">
    Walkthrough of common caching configurations and how to tune inputs.
  </Card>
</CardGroup>

## targetDefaults

Target defaults provide workspace-wide configuration that is applied to any target whose name or executor matches the key. Project-level configuration always takes precedence over target defaults.

Nx resolves a target default by checking, in order:

1. A key matching the target's executor (e.g. `"@nx/js:tsc"`)
2. A key matching the target name (e.g. `"build"`), provided the executor also matches if one is configured in the default
3. A glob key matching the target name (e.g. `"e2e-ci--**/**"`)

<Warning>
  When using a target name as the key, all targets with that name must share the
  same executor, or the defaults must make sense regardless of executor. Mismatched
  options can cause runtime errors.
</Warning>

### Supported target default properties

<ParamField body="executor" type="string">
  The executor to invoke when this target runs.
</ParamField>

<ParamField body="options" type="object">
  Default options merged into every matching target's options. Use
  `{projectRoot}` and `{workspaceRoot}` tokens for path values.
</ParamField>

<ParamField body="configurations" type="object">
  Named configuration overrides merged into the target's `configurations` map.
</ParamField>

<ParamField body="defaultConfiguration" type="string">
  The configuration name used when none is specified on the command line.
</ParamField>

<ParamField body="inputs" type="array">
  Overrides the `inputs` used to compute the cache hash for every matching
  target. Accepts named inputs, file globs, and input objects.
</ParamField>

<ParamField body="outputs" type="array">
  Paths (relative to workspace root) where the target writes artifacts that
  should be cached. Supports `{projectRoot}` and `{workspaceRoot}` tokens.
</ParamField>

<ParamField body="dependsOn" type="array">
  Tasks that must complete before this target runs. Use `"^build"` to mean
  "build all dependencies first".
</ParamField>

<ParamField body="cache" type="boolean">
  Whether Nx should cache the results of this target. Set to `true` to enable
  caching (required in Nx 17+).
</ParamField>

<ParamField body="continuous" type="boolean" default="false">
  Mark a target as long-running (never exits). Dependent tasks will start
  without waiting for this target to finish.
</ParamField>

<ParamField body="parallelism" type="boolean" default="true">
  Whether this target can run in parallel with other targets on the same
  machine. Set to `false` for targets that require exclusive access to a shared
  resource such as a port.
</ParamField>

<ParamField body="syncGenerators" type="array">
  Sync generators to run before this target executes to ensure the workspace is
  in a consistent state.
</ParamField>

### Examples

<AccordionGroup>
  <Accordion title="Build dependency ordering">
    Ensure dependencies are built before the current project:

    ```json nx.json theme={null}
    {
      "targetDefaults": {
        "build": {
          "dependsOn": ["^build"],
          "cache": true
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Executor-specific options">
    Apply default options only to targets using a specific executor:

    ```json nx.json theme={null}
    {
      "targetDefaults": {
        "@nx/js:tsc": {
          "options": {
            "main": "{projectRoot}/src/index.ts"
          },
          "configurations": {
            "prod": {
              "tsconfig": "{projectRoot}/tsconfig.prod.json"
            }
          },
          "inputs": ["production", "^production"],
          "outputs": ["{workspaceRoot}/{projectRoot}"],
          "cache": true
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Task atomizer glob key">
    Apply options to all targets generated by an atomizer plugin:

    ```json nx.json theme={null}
    {
      "targetDefaults": {
        "e2e-ci--**/**": {
          "options": {
            "headless": true
          }
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## workspaceLayout

Controls the default directories suggested when generating new applications and libraries.

```json nx.json theme={null}
{
  "workspaceLayout": {
    "appsDir": "apps",
    "libsDir": "libs"
  }
}
```

<ParamField body="appsDir" type="string">
  Default directory for new applications generated by `nx g`.
</ParamField>

<ParamField body="libsDir" type="string">
  Default directory for new libraries generated by `nx g`.
</ParamField>

## generators

Set default option values for code generators so you don't have to pass them every time.

```json nx.json theme={null}
{
  "generators": {
    "@nx/js:library": {
      "buildable": true
    }
  }
}
```

The key is `"<collection>:<generator>"` and the value is an object of default option values.

## release

Configures the `nx release` command, which orchestrates versioning, changelog generation, and publishing. All properties are optional — `nx release` works with zero config.

```json nx.json theme={null}
{
  "release": {
    "projects": ["*", "!ignore-me"],
    "projectsRelationship": "fixed",
    "version": {
      "conventionalCommits": true
    },
    "changelog": {
      "workspaceChangelog": {
        "createRelease": "github"
      },
      "projectChangelogs": true
    },
    "git": {
      "commit": true,
      "tag": true
    }
  }
}
```

### release.projects

<ParamField body="projects" type="string | string[]">
  Projects included in `nx release`. Accepts project names, glob patterns,
  directory paths, and tag references. Defaults to all projects.

  ```json theme={null}
  {
    "release": {
      "projects": ["*", "!ignore-me"]
    }
  }
  ```
</ParamField>

### release.projectsRelationship

<ParamField body="projectsRelationship" type="&#x22;fixed&#x22; | &#x22;independent&#x22;" default="&#x22;fixed&#x22;">
  Whether projects are released together at the same version (`"fixed"`) or
  each at their own version (`"independent"`).
</ParamField>

### release.version

<ParamField body="conventionalCommits" type="boolean" default="false">
  Derive the next version from commit messages following the Conventional
  Commits specification.
</ParamField>

<ParamField body="specifierSource" type="&#x22;prompt&#x22; | &#x22;conventional-commits&#x22; | &#x22;version-plans&#x22;" default="&#x22;prompt&#x22;">
  How to determine the version bump. `"prompt"` asks interactively;
  `"conventional-commits"` reads commit messages; `"version-plans"` reads
  version plan files on disk.
</ParamField>

<ParamField body="preVersionCommand" type="string">
  A shell command to run after configuration validation but before versioning
  begins. Useful for building artifacts. Runs even during `--dry-run` with
  `NX_DRY_RUN=true` set.
</ParamField>

<ParamField body="versionActionsOptions" type="object">
  Ecosystem-specific options passed to the version actions implementation (e.g.
  `{ "skipLockFileUpdate": true }` for `@nx/js`).
</ParamField>

### release.changelog

<ParamField body="workspaceChangelog" type="boolean | object">
  Configure the workspace-level `CHANGELOG.md`. Set to `false` to disable.
  When an object, supports `createRelease: "github"` to create a GitHub
  release, `file: false` to skip writing the file, and
  `replaceExistingContents: true` to overwrite rather than prepend.
</ParamField>

<ParamField body="projectChangelogs" type="boolean | object">
  Configure per-project `CHANGELOG.md` files. Set to `true` for defaults or
  provide an object with the same options as `workspaceChangelog`.
</ParamField>

### release.releaseTag

<Note>
  In Nx 22+, release tag settings use the nested `releaseTag` object. The older
  flat properties (`releaseTagPattern`, etc.) are deprecated and will be removed
  in Nx 23.
</Note>

<ParamField body="releaseTag.pattern" type="string">
  Git tag pattern. Supports `{version}`, `{projectName}`, and
  `{releaseGroupName}` interpolation. Defaults to `"v{version}"` for fixed
  releases and `"{projectName}@{version}"` for independent releases.
</ParamField>

<ParamField body="releaseTag.requireSemver" type="boolean" default="false">
  Require all tags to be valid semantic versions.
</ParamField>

<ParamField body="releaseTag.strictPreid" type="boolean">
  Ensure pre-release IDs are consistent across packages.
</ParamField>

<ParamField body="releaseTag.checkAllBranchesWhen" type="boolean | string[]">
  Controls whether Nx searches all branches for the latest matching tag.
  `true` always checks all branches; `false` only checks the current branch;
  an array of branch name patterns checks all branches only when on a matching
  branch.
</ParamField>

### release.git

<ParamField body="commit" type="boolean">
  Automatically commit version bumps and changelog changes.
</ParamField>

<ParamField body="commitMessage" type="string">
  Custom commit message. Defaults to `"chore(release): publish"`.
</ParamField>

<ParamField body="tag" type="boolean">
  Automatically create a git tag after releasing.
</ParamField>

<ParamField body="push" type="boolean" default="false">
  Automatically push commits and tags to the remote.
</ParamField>

## sync

Configuration for `nx sync`, which runs sync generators to keep workspace files consistent before tasks execute.

```json nx.json theme={null}
{
  "sync": {
    "applyChanges": true,
    "globalGenerators": ["my-plugin:my-sync-generator"],
    "generatorOptions": {
      "my-plugin:my-sync-generator": {
        "verbose": true
      }
    },
    "disabledTaskSyncGenerators": ["other-plugin:problematic-generator"]
  }
}
```

<ParamField body="globalGenerators" type="string[]">
  Sync generators run only when `nx sync` is called directly. Not associated
  with a specific task.
</ParamField>

<ParamField body="generatorOptions" type="object">
  Options keyed by generator name, passed to sync generators at runtime.
</ParamField>

<ParamField body="applyChanges" type="boolean">
  When `true`, sync generator changes are applied automatically before tasks
  run. When `false`, changes are skipped. When unset, Nx prompts interactively.
</ParamField>

<ParamField body="disabledTaskSyncGenerators" type="string[]">
  Globally disable specific task-attached sync generators.
</ParamField>

## Nx Cloud

Connect your workspace to Nx Cloud for remote caching and distributed task execution.

```json nx.json theme={null}
{
  "nxCloudId": "YOUR_CLOUD_ID"
}
```

<ParamField body="nxCloudId" type="string">
  Your Nx Cloud workspace ID. Generated when you connect via `nx connect`.
</ParamField>

<ParamField body="nxCloudUrl" type="string">
  URL of your Nx Cloud instance. Defaults to `https://cloud.nx.app`. Set for
  self-hosted deployments.
</ParamField>

<ParamField body="nxCloudEncryptionKey" type="string">
  Encryption key for end-to-end encryption of cached artifacts. Also
  configurable via `NX_CLOUD_ENCRYPTION_KEY`.
</ParamField>

## tui

Configuration for the Nx Terminal UI (TUI), which provides an interactive visual interface when running tasks.

```json nx.json theme={null}
{
  "tui": {
    "enabled": true,
    "autoExit": 3
  }
}
```

<ParamField body="enabled" type="boolean" default="true">
  Enable the TUI when the terminal supports it. Override with `NX_TUI=false`.
</ParamField>

<ParamField body="autoExit" type="boolean | number" default="3">
  Controls automatic exit after all tasks complete. `true` exits immediately;
  `false` keeps the TUI open; a number shows a countdown for that many seconds.
  Override with `NX_TUI_AUTO_EXIT`.
</ParamField>

<ParamField body="suppressHints" type="boolean" default="false">
  Suppress hint popups that appear for unhandled key presses.
</ParamField>