Project configuration

Reference for project.json and the nx property in package.json, including targets, inputs, outputs, dependsOn, tags, and all other project-level settings.

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

1. Tasks inferred by Nx plugins from tooling configuration files
2. Workspace targetDefaults in nx.json
3. 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

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

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

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

root · string · required

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

sourceRoot

sourceRoot · string

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

projectType

projectType · "application" | "library"

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

tags

tags · string[]

Labels attached to the project. Used by module boundary lint rules to enforce dependency constraints across teams or domains.

project.json

{
  "tags": ["scope:myteam", "type:feature"]
}

implicitDependencies

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

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

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

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

options · object

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

configurations

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

defaultConfiguration · string

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

cache

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

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

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

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

project.json

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

Object form

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

Specific projects

project.json

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

continuous

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

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

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:

1. Inferred tasks

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

2. 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.

3. 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"]
  }
}