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.

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:

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--**/**")

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.