Run Only Tasks Affected by a PR

As your workspace grows, re-testing, re-building and re-linting all projects becomes too slow. To address this, Nx is able to determine the minimum set of projects that were affected by the change, and only run tasks on those projects. This drastically improves the speed of your CI and the amount of compute that needs to be run, even before other features like remote caching and distributed task execution are taken into account.

Using Nx Affected Commands

To leverage this feature, use the following command when running your tasks, in particular on CI:

When you run nx affected -t test, Nx will

• use Git to determine the files you changed in your PR
• use the project graph to determine which projects the files belong to
• determine which projects depend on the projects you modified

Once the projects are identified, Nx runs the tasks you specified on that subset of projects.

You can also visualize the affected projects using the Nx graph. Simply run:

Just using Affected Might not be Enough

Using nx affected is a powerful tool to cut down the amount of compute that needs to be run. However, this might not be sufficient to significantly speed up your CI pipeline. For example:

• If you're modifying a project that is being used by a large portion of your monorepo projects, you might end up running tasks for almost all the projects in the workspace.
• If you have a set of 10 projects affected by a PR and you continue making changes, you will always end up running tasks for those 10 projects. The set of affected projects doesn't change but is always calculated with respect to your last successful run on the main branch.

This is why Nx Affected is best paired with remote caching and distributed task execution.

Configure Affected on CI

To understand which projects are affected, Nx uses the Git history and the project graph. Git knows which files changed, and the Nx project graph knows which projects those files belong to.

The affected command takes a base and head commit. The default base is your main branch and the default head is your current file system. This is generally what you want when developing locally, but in CI, you need to customize these values.

You can also set the base and head SHAs as env variables:

The recommmended approach is to set the base SHA to the latest successful commit on the main branch. This ensures that all changes since the last successful CI run are accounted for.

Depending on your CI provider this might differ:

• Get last successful commit for Azure Pipelines
• Get last successful commit for GitHub Actions
• Get last successful commit for CircleCI
• Get last successful commit for GitLab
• Get last successful commit for Jenkins

Ignoring Files from Affected Commands

Nx provides two methods to exclude glob patterns (files and folders) from affected:* commands.

• Glob patterns defined in your .gitignore file are ignored.
• Glob patterns defined in an optional .nxignore file are ignored.

Marking Projects Affected by Dependency Updates

By default, Nx will mark all projects as affected whenever your package manager's lock file changes. This behavior is a failsafe in case Nx misses a project that should be affected by a dependency update. If you'd like to opt in to a smarter behavior you can configure Nx to only mark projects as affected if they actually depend on the updated packages.

The flag projectsAffectedByDependencyUpdates can be set to auto, all, or an array that contains project specifiers. The default value is all.

Not Using Git

If you aren't using Git, you can pass --files to any affected command to indicate what files have been changed.