Skip to content

Nx Affected Commands: A Comprehensive Guide

Overview

This guide demonstrates how to use Nx's powerful "affected" commands to efficiently run tasks only for projects affected by changes. Using affected commands properly can dramatically reduce CI/CD times and make local development more efficient.

Understanding "Affected"

In Nx, a project is considered "affected" by a change if:

  1. The project itself has changes
  2. The project depends on another project that has changes
  3. A file that the project depends on has changes (via named inputs)

Basic Syntax

The basic syntax for affected commands is:

nx affected --target=<target> [options]

Where:

  • <target> is the task to run (e.g., build, test, lint)
  • [options] are additional parameters

Common Affected Commands

Affected Build

Build all projects affected by changes:

# Compare to origin/master
nx affected --target=build

# Compare to specific branch
nx affected --target=build --base=origin/feature-branch

Affected Test

Run tests for all affected projects:

# Run tests for affected projects
nx affected --target=test

# Run tests with code coverage
nx affected --target=test --configuration=coverage

Affected Lint

Lint all affected projects:

# Lint affected projects
nx affected --target=lint

# Lint and fix issues
nx affected --target=lint --fix

Affected Apps

List affected applications without running any tasks:

nx affected:apps

Affected Libs

List affected libraries without running any tasks:

nx affected:libs

Advanced Usage

Specifying Base and Head

You can specify the base and head commits to determine what has changed:

# Compare changes between base and head
nx affected --target=test --base=origin/master --head=HEAD

Running Multiple Targets

Run multiple targets for affected projects:

# Run lint, test, and build
nx affected --target=lint,test,build

Parallel Execution

Run tasks in parallel to improve performance:

# Run with 4 parallel processes
nx affected --target=test --parallel=4

Using Tags

Filter affected projects by tags:

# Only run for projects with specific tags
nx affected --target=test --projects=tag:type:application

Skip Projects

Skip specific projects when running affected commands:

# Skip projects matching the pattern
nx affected --target=build --skip-nx-cache --exclude="*api*,*web*"

CI/CD Integration

GitHub Actions Example

- name: Set SHAs for affected
  uses: nrwl/nx-set-shas@v4

- name: Run affected tests
  run: nx affected --target=test --parallel=3

- name: Run affected builds
  run: nx affected --target=build --parallel=3

CircleCI Example

- run:
    name: Set SHAs for comparison
    command: |
      echo 'export NX_BASE=$(git rev-parse HEAD~1)' >> $BASH_ENV
      echo 'export NX_HEAD=$(git rev-parse HEAD)' >> $BASH_ENV

- run:
    name: Run affected tests
    command: nx affected --target=test --base=$NX_BASE --head=$NX_HEAD

Performance Tips

  1. Cache Results: Use the Nx cache to avoid re-running tasks
nx affected --target=build --parallel=3
  1. Use Nx Cloud: Consider using Nx Cloud for distributed caching
nx affected --target=build --parallel=3 --with-cloud

  1. Optimize Dependency Graph: Keep your project dependencies clean to minimize unnecessary affected projects

  2. Run Cheaper Tasks First: Run quick tasks first, then more expensive ones

nx affected --target=lint,test,build --parallel=3
  1. Use Named Inputs: Configure namedInputs in nx.json to better define what affects a project

Practical Examples

Pre-commit Check

# Check only what's changed in your branch
nx affected --target=lint,test --base=origin/master --head=HEAD

CI Build Pipeline

# First run format checking and linting
nx affected --target=format:check,lint --parallel=3

# Then run tests if linting passes
nx affected --target=test --parallel=3

# Finally build if tests pass
nx affected --target=build --parallel=3

Feature Development

# Watch mode for affected projects during development
nx affected --target=test --watch

Troubleshooting

Common Issues

  1. Unexpected projects affected: Check your dependency graph using nx graph
  2. Build stuck: Use --verbose flag to see detailed output
  3. Cache not working: Check configuration in nx.json and try --skip-nx-cache

Conclusion

Using Nx affected commands effectively can significantly improve your development and CI/CD workflows by ensuring that only necessary tasks are run on changed projects. This leads to faster feedback cycles and more efficient resource usage.