Inputs and named inputs

Reference for all Nx input types used to compute task cache hashes: filesets, environment variables, runtime commands, external dependencies, and named inputs.

When Nx computes the hash for a task, it considers the task’s inputs. If any input changes, the cache is invalidated and the task re-runs. Inputs are defined on individual targets or in namedInputs for reuse across the workspace.

Input types

Nx supports the following input types. Each can appear as an element in an inputs array.

Fileset

File path globs that determine which files contribute to the cache hash. Patterns must be prefixed with {projectRoot} or {workspaceRoot}.

{
  "inputs": [
    "{projectRoot}/**/*",
    "{workspaceRoot}/.gitignore",
    "{projectRoot}/**/*.ts",
    "!{projectRoot}/**/*.spec.ts"
  ]
}

Or in object form using the fileset property:

{
  "inputs": [
    { "fileset": "{projectRoot}/**/*.ts" },
    { "fileset": "{projectRoot}/**/*.ts", "dependencies": true }
  ]
}

fileset · string · required

A glob pattern prefixed with {projectRoot} or {workspaceRoot} that selects files to include in the hash.

dependencies · boolean

When true, the fileset is applied to each of the project’s dependencies rather than the project itself.

Token behavior:

• {projectRoot}/**/* — matches only files assigned to the specific project. Files in nested projects are excluded.
• {workspaceRoot}/path/**/* — matches all files in the workspace including nested projects.
• Prefix with ! to exclude matching files from the hash.
• Prefix with ^ to apply the pattern to dependency projects (e.g. "^{projectRoot}/**/*.ts").

Directory paths used as inputs must include a trailing slash or glob pattern. "{projectRoot}/src" is treated as a file path and will match nothing. Use "{projectRoot}/src/" or "{projectRoot}/src/**/*" instead.

This is different from outputs, which accept bare directory paths.

Files listed in .gitignore are automatically excluded from inputs and never invalidate the cache.

Environment variable

Include the value of an environment variable in the cache hash. If the variable’s value changes, the task re-runs.

{
  "inputs": [
    { "env": "API_URL" },
    { "env": "NODE_ENV" }
  ]
}

env · string · required

The name of the environment variable whose value is included in the hash.

Runtime command

Run a shell command and include its output in the cache hash. Use this to capture tool versions or other dynamic values.

{
  "inputs": [
    { "runtime": "node --version" },
    { "runtime": "go version" }
  ]
}

runtime · string · required

A shell command whose stdout output is included in the hash. Avoid platform-specific scripts (.sh, .bat) — use cross-platform commands instead.

External dependencies

Include the resolved version of one or more npm packages in the cache hash. When a listed package is updated, the task re-runs.

{
  "inputs": [
    { "externalDependencies": ["jest", "@jest/globals"] },
    { "externalDependencies": ["eslint", "eslint-config-airbnb"] }
  ]
}

externalDependencies · string[] · required

Package names to include in the hash. If this property is omitted from a target’s inputs entirely, Nx hashes all external dependencies in the workspace (conservative default). Specifying at least one externalDependencies entry restricts hashing to only the listed packages.

Nx plugins maintained by the Nx team automatically configure the correct externalDependencies for their executors. You only need to configure this manually for nx:run-commands targets and community plugins.

Outputs of dependent tasks

Consider files produced by dependency tasks as inputs to this task. Useful when a build task consumes type definitions generated upstream.

{
  "inputs": [
    { "dependentTasksOutputFiles": "**/*.d.ts" },
    { "dependentTasksOutputFiles": "**/*.d.ts", "transitive": true }
  ]
}

dependentTasksOutputFiles · string · required

A glob pattern matched against output file paths (resolved from workspace root) of dependent tasks.

transitive · boolean

When true, also includes outputs from transitive dependencies (all tasks in the dependency chain), not only direct dependencies.

Working directory

Include the current working directory in the hash. Use this when task behavior depends on which directory the command is invoked from.

{
  "inputs": [
    { "workingDirectory": "relative" }
  ]
}

workingDirectory · "relative" | "absolute"

"relative" hashes the path from workspace root to the current directory. "absolute" hashes the full filesystem path, which invalidates cache entries when the repository is cloned to a different location.

Named inputs

Named inputs are reusable sets of inputs defined in namedInputs. They act as variables you can reference by name in target inputs arrays instead of repeating the same definition everywhere.

Defining named inputs

Workspace level — available to all projects:

nx.json

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

Project level — overrides the workspace definition for this project only:

project.json

project.json

{
  "namedInputs": {
    "production": ["default", "!{projectRoot}/jest.config.ts"]
  }
}

package.json

package.json

{
  "nx": {
    "namedInputs": {
      "production": ["default", "!{projectRoot}/jest.config.ts"]
    }
  }
}

Referencing named inputs

Named inputs are referenced by string in any inputs array:

project.json

{
  "targets": {
    "test": {
      "inputs": [
        "default",
        "^production",
        "{projectRoot}/jest.config.js"
      ]
    }
  }
}

Reference	Meaning
"default"	Apply the default named input for the current project
"^production"	Apply the production named input for each dependency project
{ "input": "production", "projects": "mylib" }	Apply the production named input defined in a specific project

The ^ prefix behaves differently depending on what follows it:

• "^production" — resolves the production named input per dependency
• "^{projectRoot}/**/*.ts" — applies the fileset to each dependency project’s root

Built-in named input conventions

Nx workspaces are generated with these named inputs by default:

nx.json

{
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "sharedGlobals": [],
    "production": ["default", "!{projectRoot}/jest.config.ts"]
  }
}

default

All files in the project root plus shared global inputs. Using default for a target means any file change in the project invalidates the cache — the safest choice.

sharedGlobals

Inputs that apply to every task in the workspace, such as the OS type or Node.js version. Empty by default; populate with { "runtime": "node --version" } style entries if needed.

production

A subset of default that excludes developer-only files (test files, lint configs, etc.) that don’t affect production output. Define production inputs on each project so that test tasks on downstream projects are not invalidated when test files change.

Configuring inputs for build vs. test

A common pattern is to use production inputs for builds and default inputs for tests, so that changes to test files don’t invalidate downstream build caches:

nx.json

{
  "targetDefaults": {
    "build": {
      "inputs": ["production", "^production"],
      "cache": true
    },
    "test": {
      "inputs": ["default", "^production"],
      "cache": true
    }
  }
}

With this setup:

• Changing a *.spec.ts file invalidates test (because default includes all files) but not build (because production excludes spec files).
• Changing a source file in a library invalidates both the library’s build and any application’s build that depends on it, because ^production propagates the library’s production inputs upstream.

nx.json reference

Define namedInputs at the workspace level.

Project configuration reference

Override namedInputs and set inputs per target.