Affected Builds

Run tasks only for projects affected by a code change. Nx uses the project graph and git history to determine the minimal set of work required.

As your workspace grows, running all tasks for all projects on every PR becomes too slow. The nx affected command solves this by:

• Determining the minimum set of projects affected by your change
• Running tasks only on those projects

This reduces CI compute significantly, and the benefit compounds when paired with remote caching and distributed task execution.

How Nx determines affected projects

Nx combines two sources of information:

1. Git diff — Nx checks which files changed between the base and head commits
2. Project graph — Nx maps those files to projects, then traverses the graph to find all downstream dependents

For example, if you change a shared utility library, every application and library that depends on it (directly or transitively) is marked as affected.

Run affected tasks

Replace run-many with affected in your commands:

# Run tests only for affected projects
npx nx affected -t test

# Run build and lint for affected projects
npx nx affected -t build lint

You can also visualize which projects are affected:

npx nx graph --affected

Control the comparison range with —base and —head

By default, Nx compares against your main branch. You can override this:

# Compare a PR branch to main
npx nx affected -t build --base=origin/main --head=$PR_BRANCH_NAME

# Re-run what was affected by the last commit on main
npx nx affected -t build --base=origin/main~1 --head=origin/main

You can also set these as environment variables:

NX_BASE=origin/main~1
NX_HEAD=origin/main

The recommended CI approach is to set --base to the latest successful commit on main. This ensures all changes since the last successful CI run are accounted for, even if multiple commits landed between runs.

Use affected in CI

Here is a GitHub Actions example using nrwl/nx-set-shas to automatically resolve the correct base SHA:

# .github/workflows/ci.yml
name: CI

jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          filter: tree:0

      - uses: nrwl/nx-set-shas@v4

      - run: npm ci

      - run: npx nx affected -t lint test build

The nrwl/nx-set-shas action sets NX_BASE to the last successful CI commit on the base branch, so only work that has not already passed is re-run.

Configure smart dependency update detection

By default, Nx marks all projects as affected when the package manager lock file changes. To opt into more precise behavior that only marks projects depending on the updated packages:

// nx.json
{
  "pluginsConfig": {
    "@nx/js": {
      "projectsAffectedByDependencyUpdates": "auto"
    }
  }
}

The projectsAffectedByDependencyUpdates option accepts "auto", "all", or an array of project specifiers.

Ignore files from affected detection

Nx respects two ignore files:

• .gitignore — any patterns listed here are excluded from affected detection
• .nxignore — an optional Nx-specific ignore file with the same glob syntax

Not using git?

Pass --files to specify changed files explicitly:

npx nx affected -t build --files=libs/mylib/src/index.ts