nx.json

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. Below is an expanded example showing all common options. Your actual nx.json will be much shorter.

nx.json

{
  "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.

parallel

number

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

cacheDirectory

string

Directory where the local task output cache is stored. Defaults to .nx/cache. Override with the NX_CACHE_DIRECTORY environment variable.

defaultBase

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.

defaultProject

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.

useDaemonProcess

boolean

Whether to use the Nx daemon for computing the project graph. Defaults to true. Disable with NX_DAEMON=false.

extends

string

Specifies a base configuration file to extend. Nx preset files live in node_modules/nx/presets/, e.g. "nx/presets/npm.json".

maxCacheSize

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.

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.

nx.json

{
  "plugins": [
    "@my-org/graph-plugin",
    {
      "plugin": "@nx/eslint/plugin",
      "options": {
        "targetName": "lint"
      }
    }
  ]
}

plugin

string

required

The npm package or local path of the plugin module to load.

options

object

Plugin-specific options passed when the plugin creates nodes and dependencies. Consult each plugin’s documentation for available options.

include

array

Glob patterns for configuration files the plugin should process. Only projects whose config file path matches will have tasks inferred by this plugin.

exclude

array

Glob patterns for configuration files the plugin should ignore. Supports negation patterns (prefixed with !). Patterns are applied in order.

Scoping plugins to specific projects

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

nx.json

{
  "plugins": [
    {
      "plugin": "@nx/jest/plugin",
      "include": ["packages/**/*"],
      "exclude": ["**/*-e2e/**/*"]
    }
  ]
}

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

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.

nx.json

{
  "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.

Inputs reference

Full documentation of all input types: filesets, env vars, runtime commands, external dependencies, and more.

Task caching guide

Walkthrough of common caching configurations and how to tune inputs.

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:

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

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.

Supported target default properties

executor

string

The executor to invoke when this target runs.

options

object

Default options merged into every matching target’s options. Use {projectRoot} and {workspaceRoot} tokens for path values.

configurations

object

Named configuration overrides merged into the target’s configurations map.

defaultConfiguration

string

The configuration name used when none is specified on the command line.

inputs

array

Overrides the inputs used to compute the cache hash for every matching target. Accepts named inputs, file globs, and input objects.

outputs

array

Paths (relative to workspace root) where the target writes artifacts that should be cached. Supports {projectRoot} and {workspaceRoot} tokens.

dependsOn

array

Tasks that must complete before this target runs. Use "^build" to mean “build all dependencies first”.

cache

boolean

Whether Nx should cache the results of this target. Set to true to enable caching (required in Nx 17+).

continuous

boolean

default:"false"

Mark a target as long-running (never exits). Dependent tasks will start without waiting for this target to finish.

parallelism

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.

syncGenerators

array

Sync generators to run before this target executes to ensure the workspace is in a consistent state.

Examples

Build dependency ordering

Ensure dependencies are built before the current project:

nx.json

{
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "cache": true
    }
  }
}

Executor-specific options

Apply default options only to targets using a specific executor:

nx.json

{
  "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
    }
  }
}

Task atomizer glob key

Apply options to all targets generated by an atomizer plugin:

nx.json

{
  "targetDefaults": {
    "e2e-ci--**/**": {
      "options": {
        "headless": true
      }
    }
  }
}

workspaceLayout

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

nx.json

{
  "workspaceLayout": {
    "appsDir": "apps",
    "libsDir": "libs"
  }
}

appsDir

string

Default directory for new applications generated by nx g.

libsDir

string

Default directory for new libraries generated by nx g.

generators

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

nx.json

{
  "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.

nx.json

{
  "release": {
    "projects": ["*", "!ignore-me"],
    "projectsRelationship": "fixed",
    "version": {
      "conventionalCommits": true
    },
    "changelog": {
      "workspaceChangelog": {
        "createRelease": "github"
      },
      "projectChangelogs": true
    },
    "git": {
      "commit": true,
      "tag": true
    }
  }
}

release.projects

projects

string | string[]

Projects included in nx release. Accepts project names, glob patterns, directory paths, and tag references. Defaults to all projects.

{
  "release": {
    "projects": ["*", "!ignore-me"]
  }
}

release.projectsRelationship

projectsRelationship

"fixed" | "independent"

default:"\"fixed\""

Whether projects are released together at the same version ("fixed") or each at their own version ("independent").

release.version

conventionalCommits

boolean

default:"false"

Derive the next version from commit messages following the Conventional Commits specification.

specifierSource

"prompt" | "conventional-commits" | "version-plans"

default:"\"prompt\""

How to determine the version bump. "prompt" asks interactively; "conventional-commits" reads commit messages; "version-plans" reads version plan files on disk.

preVersionCommand

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.

versionActionsOptions

object

Ecosystem-specific options passed to the version actions implementation (e.g. { "skipLockFileUpdate": true } for @nx/js).

release.changelog

workspaceChangelog

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.

projectChangelogs

boolean | object

Configure per-project CHANGELOG.md files. Set to true for defaults or provide an object with the same options as workspaceChangelog.

release.releaseTag

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.

releaseTag.pattern

string

Git tag pattern. Supports {version}, {projectName}, and {releaseGroupName} interpolation. Defaults to "v{version}" for fixed releases and "{projectName}@{version}" for independent releases.

releaseTag.requireSemver

boolean

default:"false"

Require all tags to be valid semantic versions.

releaseTag.strictPreid

boolean

Ensure pre-release IDs are consistent across packages.

releaseTag.checkAllBranchesWhen

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.

release.git

commit

boolean

Automatically commit version bumps and changelog changes.

commitMessage

string

Custom commit message. Defaults to "chore(release): publish".

tag

boolean

Automatically create a git tag after releasing.

push

boolean

default:"false"

Automatically push commits and tags to the remote.

sync

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

nx.json

{
  "sync": {
    "applyChanges": true,
    "globalGenerators": ["my-plugin:my-sync-generator"],
    "generatorOptions": {
      "my-plugin:my-sync-generator": {
        "verbose": true
      }
    },
    "disabledTaskSyncGenerators": ["other-plugin:problematic-generator"]
  }
}

globalGenerators

string[]

Sync generators run only when nx sync is called directly. Not associated with a specific task.

generatorOptions

object

Options keyed by generator name, passed to sync generators at runtime.

applyChanges

boolean

When true, sync generator changes are applied automatically before tasks run. When false, changes are skipped. When unset, Nx prompts interactively.

disabledTaskSyncGenerators

string[]

Globally disable specific task-attached sync generators.

Nx Cloud

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

nx.json

{
  "nxCloudId": "YOUR_CLOUD_ID"
}

nxCloudId

string

Your Nx Cloud workspace ID. Generated when you connect via nx connect.

nxCloudUrl

string

URL of your Nx Cloud instance. Defaults to https://cloud.nx.app. Set for self-hosted deployments.

nxCloudEncryptionKey

string

Encryption key for end-to-end encryption of cached artifacts. Also configurable via NX_CLOUD_ENCRYPTION_KEY.

tui

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

nx.json

{
  "tui": {
    "enabled": true,
    "autoExit": 3
  }
}

enabled

boolean

default:"true"

Enable the TUI when the terminal supports it. Override with NX_TUI=false.

autoExit

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.

suppressHints

boolean

default:"false"

Suppress hint popups that appear for unhandled key presses.

CLI Commands

Configuration

Plugin Index

Top-level task options

Plugins

Scoping plugins to specific projects

namedInputs

Inputs reference

Task caching guide

targetDefaults

Supported target default properties

Examples

workspaceLayout

generators

release

release.projects

release.projectsRelationship

release.version

release.changelog

release.releaseTag

release.git

sync

Nx Cloud

tui

CLI Commands

Configuration

Plugin Index

Documentation Index

​Top-level task options

​Plugins

​Scoping plugins to specific projects

​namedInputs

Inputs reference

Task caching guide

​targetDefaults

​Supported target default properties

​Examples

​workspaceLayout

​generators

​release

​release.projects

​release.projectsRelationship

​release.version

​release.changelog

​release.releaseTag

​release.git

​sync

​Nx Cloud

​tui

Top-level task options

Plugins

Scoping plugins to specific projects

namedInputs

targetDefaults

Supported target default properties

Examples

workspaceLayout

generators

release

release.projects

release.projectsRelationship

release.version

release.changelog

release.releaseTag

release.git

sync

Nx Cloud

tui