nx affected

Run a target only for projects that have been changed and their dependents.

nx affected -t <target> [options]

nx affected determines which projects are affected by recent changes in your repository—both projects with modified files and any projects that depend on them—and runs the specified target only for those projects.

Use nx affected in CI to skip running tasks for unchanged code, reducing pipeline time and resource usage.

How affected works

Nx compares two git refs (--base and --head) to find which files have changed. It then walks the project dependency graph to identify every project that could be impacted by those file changes.

• --base — the earlier commit to compare from (commonly origin/main or a merge-base SHA)
• --head — the later commit to compare to (defaults to HEAD)

If neither is provided, Nx falls back to comparing against uncommitted and untracked changes in the working tree.

Options

Target selection

--targets · string · required

One or more targets to run for affected projects. Alias: --target, -t. Accepts comma-separated values.

nx affected -t build
nx affected -t build,test,lint

--configuration · string

The named configuration to use when running the target. Alias: -c.

Determining affected projects

--base · string

Base git ref to compare from (e.g., a branch name, tag, or commit SHA). Represents the earlier point in history.

--head · string

Later git ref to compare to. Defaults to HEAD. Requires --base to be set.

--files · string

Treat a specific list of files (comma or space separated) as changed, instead of deriving them from git. Conflicts with --uncommitted, --untracked, --base, and --head.

--uncommitted · boolean

Include uncommitted (staged and unstaged) file changes. Conflicts with --files, --untracked, --base, and --head.

--untracked · boolean

Include untracked files. Conflicts with --files, --uncommitted, --base, and --head.

--stdin · boolean

Read changed file paths from stdin (one per line). Useful for piping output from git diff. Conflicts with --uncommitted, --untracked, --base, and --head.

Filtering and scoping

--exclude · string

Comma-separated list of projects to exclude from the run, even if they are affected.

Execution

--parallel · string

Maximum number of parallel task processes. Defaults to 3. Set to false to run serially.

--output-style · string

Controls how task output is displayed. Choices: tui, dynamic, dynamic-legacy, static, stream, stream-without-prefixes.

--nx-bail · boolean · default: "false"

Stop after the first failed task.

--nx-ignore-cycles · boolean · default: "false"

Ignore cycles in the task graph.

--skip-nx-cache · boolean · default: "false"

Rerun tasks even when results are available in the cache.

--skip-remote-cache · boolean · default: "false"

Disable the remote cache for this run.

--exclude-task-dependencies · boolean · default: "false"

Skip running dependent tasks first.

--skip-sync · boolean · default: "false"

Skip running sync generators associated with the tasks.

--batch · boolean

Run tasks in batches for executors that support batch execution.

--graph · string

Show the task graph instead of running it. Pass a file path to save to a file, or stdout to print to the terminal.

--runner · string

The tasks runner to use, as configured in nx.json.

--tui · boolean

Enable or disable the Nx Terminal UI. Conflicts with --output-style.

--verbose · boolean

Print additional information about the command.

Examples

Run build for affected projects

nx affected -t build

CI example

A typical GitHub Actions step that runs tasks only for affected projects:

- name: Run affected tasks
  run: nx affected -t build test lint --base=origin/main --head=HEAD --parallel=4

The --all flag has been removed from nx affected. To run a target for all projects, use nx run-many instead.