Project configuration

A project’s configuration in Nx is assembled from three sources, each overriding the previous:

Tasks inferred by Nx plugins from tooling configuration files
Workspace targetDefaults in nx.json
Project-level configuration in project.json or package.json

You can inspect the merged configuration for any project with:

nx show project <project-name> --web

The full machine-readable schema is at packages/nx/schemas/project-schema.json.

Configuration files

Nx merges project.json and the "nx" property in package.json to produce each project’s final configuration. Both support identical configuration options, including executors.

project.json
package.json

project.json

{
  "name": "mylib",
  "root": "libs/mylib",
  "sourceRoot": "libs/mylib/src",
  "projectType": "library",
  "tags": ["scope:myteam"],
  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "inputs": ["production", "^production"],
      "outputs": ["{workspaceRoot}/dist/libs/mylib"],
      "dependsOn": ["^build"],
      "cache": true,
      "options": {
        "main": "{projectRoot}/src/index.ts",
        "tsConfig": "{projectRoot}/tsconfig.lib.json"
      },
      "configurations": {
        "production": {
          "tsConfig": "{projectRoot}/tsconfig.lib.prod.json"
        }
      }
    },
    "test": {
      "executor": "@nx/jest:jest",
      "inputs": ["default", "^production"],
      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
      "cache": true,
      "options": {}
    }
  }
}

package.json

{
  "name": "mylib",
  "scripts": {
    "test": "jest"
  },
  "nx": {
    "tags": ["scope:myteam"],
    "namedInputs": {
      "production": ["default", "!{projectRoot}/**/*.spec.tsx"]
    },
    "targets": {
      "build": {
        "command": "tsc -p tsconfig.lib.json",
        "inputs": ["production", "^production"],
        "outputs": ["{workspaceRoot}/dist/libs/mylib"],
        "dependsOn": ["^build"],
        "cache": true
      }
    },
    "includedScripts": ["test"]
  }
}

Project metadata fields

name

string

The project’s identifier used in Nx commands, e.g. nx build mylib. Optional if the project is discovered via package.json "name" field.

root

string

required

Path to the project directory relative to the workspace root. Nx uses this to scope file inputs and resolve paths.

sourceRoot

string

Path to the project’s source files relative to the workspace root. Used by some executors and lint rules.

projectType

"application" | "library"

Classifies the project. "application" projects are deployable artifacts; "library" projects are reusable code consumed by other projects.

implicitDependencies

string[]

Manually declare dependencies that Nx cannot detect from source code. Prefix a project name with ! to explicitly remove a dependency. Glob patterns are supported.

project.json

{
  "implicitDependencies": ["anotherlib", "!unrelated-lib", "shop-*"]
}

namedInputs

object

Project-level named input definitions. These override workspace-level named inputs of the same name for this project’s tasks only.

project.json

{
  "namedInputs": {
    "production": ["default", "!{projectRoot}/**/*.spec.tsx"]
  }
}

metadata

metadata.description

string

A human-readable description of the project, visible in the project graph UI.

project.json

{
  "metadata": {
    "description": "Shared UI component library"
  }
}

targets

Targets define the tasks you can run against a project. Each key in targets becomes a runnable command: nx <target> <project>.

project.json

{
  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "cache": true,
      "inputs": ["production", "^production"],
      "outputs": ["{workspaceRoot}/dist/{projectRoot}"],
      "dependsOn": ["^build"],
      "options": {
        "main": "{projectRoot}/src/index.ts"
      }
    }
  }
}

executor

string

The Nx executor that runs this target, in "<plugin>:<executor>" format. Use "nx:run-commands" to run an arbitrary shell command. Omit this field when using the command shorthand.

command

string

Shorthand for running a shell command via nx:run-commands. Equivalent to setting executor: "nx:run-commands" and options.command.

project.json

{
  "targets": {
    "build": {
      "command": "tsc -p tsconfig.lib.json"
    }
  }
}

options

object

Default options passed to the executor or command. The available properties depend on the executor being used.

configurations

object

Named sets of option overrides. Activate a configuration with nx build mylib --configuration=production.

project.json

{
  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "options": {
        "tsConfig": "{projectRoot}/tsconfig.lib.json"
      },
      "configurations": {
        "production": {
          "tsConfig": "{projectRoot}/tsconfig.lib.prod.json"
        }
      }
    }
  }
}

defaultConfiguration

string

The configuration name used when no --configuration flag is supplied.

cache

boolean

Whether Nx should cache task results. Set to true to enable caching for a target (required as of Nx 17).

project.json

{
  "targets": {
    "test": {
      "cache": true
    }
  }
}

Disabling caching for a target prevents it from being distributed via Nx Agents. Any targets that depend on it will also fail to distribute.

inputs

array

File sets, environment variables, and other inputs used to compute the cache hash. If any input changes, the task re-runs. Accepts named input strings and input objects.

project.json

{
  "targets": {
    "build": {
      "inputs": [
        "production",
        "^production",
        { "externalDependencies": ["vite"] }
      ]
    }
  }
}

See the Inputs reference for all input types.

outputs

string[]

Paths where the target writes file artifacts. Nx caches and restores these paths. Supports {projectRoot} and {workspaceRoot} tokens, glob patterns, and negation patterns.

project.json

{
  "targets": {
    "build": {
      "outputs": [
        "{workspaceRoot}/dist/libs/mylib",
        "{workspaceRoot}/build/libs/mylib/main.js"
      ]
    }
  }
}

Default output locations Nx caches when no outputs are specified:

{workspaceRoot}/dist/{projectRoot}
{projectRoot}/build
{projectRoot}/dist
{projectRoot}/public

dependsOn

array

Tasks that must complete before this target starts. Use string shorthand or the object form for advanced control.

Shorthand	Meaning
`"^build"`	Run `build` on all project dependencies first
`"build"`	Run `build` on the current project first
`"build-*"`	Run all targets matching the pattern on the current project first
`"^build-*"`	Run all matching targets on all dependencies first

String shorthand
Object form
Specific projects

project.json

{
  "targets": {
    "build": { "dependsOn": ["^build"] },
    "test": { "dependsOn": ["build"] }
  }
}

project.json

{
  "targets": {
    "build": {
      "dependsOn": [
        {
          "dependencies": true,
          "target": "build",
          "params": "ignore"
        }
      ]
    }
  }
}

The params field controls whether CLI flags are forwarded to dependency targets: "ignore" (default) or "forward".

project.json

{
  "targets": {
    "build": {
      "dependsOn": [
        { "projects": ["is-even", "is-odd"], "target": "pre-build" }
      ]
    }
  }
}

continuous

boolean

default:"false"

Mark this target as a long-running process that never exits (e.g. a dev server). Dependent tasks start without waiting for this target to finish. Available in Nx 21+.

project.json

{
  "targets": {
    "serve": {
      "continuous": true
    }
  }
}

parallelism

boolean

default:"true"

Whether this target may 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. Available in Nx 19.5+.

project.json

{
  "targets": {
    "e2e": {
      "parallelism": false
    }
  }
}

parallelism: false only prevents concurrent execution on a single machine. With Nx Agents, the same target can still run on multiple agents simultaneously because agents do not share resources.

syncGenerators

string[]

Sync generators to run before this target executes to ensure configuration files are up to date. Available in Nx 19.8+.

project.json

{
  "targets": {
    "build": {
      "syncGenerators": ["some-plugin:my-sync-generator"]
    }
  }
}

metadata

metadata.description

string

A human-readable description of what this target does, visible in nx show project output.

project.json

{
  "targets": {
    "build": {
      "metadata": {
        "description": "Compile TypeScript and bundle for production"
      }
    }
  }
}

How target configuration is merged

Nx builds a target’s effective configuration in this order, with later sources overriding earlier ones:

Inferred tasks

Nx plugins inspect tooling config files (e.g. vite.config.ts, jest.config.ts) and infer task definitions automatically.

targetDefaults in nx.json

Workspace-wide defaults keyed by executor or target name are merged on top of inferred tasks. Only one matching default is applied per target.

Project-level configuration

Settings in project.json or package.json override both inferred tasks and targetDefaults.

package.json integration

Nx automatically includes any package.json referenced by your package manager’s workspace configuration. Scripts defined in scripts become Nx targets.

Limiting which scripts become targets

Use includedScripts to opt in to specific scripts as Nx targets, ignoring the rest:

package.json

{
  "name": "my-library",
  "scripts": {
    "build": "tsc",
    "postinstall": "node ./tasks/postinstall"
  },
  "nx": {
    "includedScripts": ["build"]
  }
}

CLI Commands

Configuration

Plugin Index

Project configuration

Configuration files

Project metadata fields

name

root

sourceRoot

projectType

tags

implicitDependencies

namedInputs

metadata

targets

executor

command

options

configurations

defaultConfiguration

cache

inputs

outputs

dependsOn

continuous

parallelism

syncGenerators

metadata

How target configuration is merged

package.json integration

Limiting which scripts become targets

Build docs developers (and LLMs) love

CLI Commands

Configuration

Plugin Index

Documentation Index

​Configuration files

​Project metadata fields

​name

​root

​sourceRoot

​projectType

​tags

​implicitDependencies

​namedInputs

​metadata

​targets

​executor

​command

​options

​configurations

​defaultConfiguration

​cache

​inputs

​outputs

​dependsOn

​continuous

​parallelism

​syncGenerators

​metadata

​How target configuration is merged

​package.json integration

​Limiting which scripts become targets

Build docs developers (and LLMs) love

Configuration files

Project metadata fields

name

root

sourceRoot

projectType

tags

implicitDependencies

namedInputs

metadata

targets

executor

command

options

configurations

defaultConfiguration

cache

inputs

outputs

dependsOn

continuous

parallelism

syncGenerators

metadata

How target configuration is merged

package.json integration

Limiting which scripts become targets