Distributed Task Execution

Nx Cloud provides config-free distributed task execution (DTE). When using the distributed task execution, Nx is able to run any task graph on many agents instead of running them on a single machine.

Imagine you are running nx affected --build --parallel. Normally this command runs the build target for the affected projects in parallel on the same machine. However, if you enable distributed task execution, the command will send the Task Graph to Nx Cloud. Nx Cloud Agents will then pick up the tasks to run and execute them.

Note that this happens transparently. If an agent builds app1, it will fetch the outputs for libs it needs if it doesn’t have it already. As agents complete tasks, the main job where you invoked nx affected --build will start receiving created files and terminal outputs. After nx affected --build completes, the machine will have the build files and all the terminal outputs as if it ran it locally.

Enabling Distributed Task Execution

Even though DTE does not have to run on CI, let's use Circle CI as an example.

version: 2.1 jobs:   agent: steps: - checkout - run: npm install - run: npx nx-cloud start-agent pr-main: environment: NX_CLOUD_DISTRIBUTED_EXECUTION: 'true' steps: - checkout - run: npm install - run: npx nx affected --target=build --parallel --max-parallel=3 - run: npx nx affected --target=test --parallel --max-parallel=2 - run: npx nx affected --target=lint --parallel --max-parallel=4 - run: npx nx-cloud stop-all-agents workflows:   build: jobs: - agent: name: 'agent1' - agent: name: 'agent2' - agent: name: 'agent3' - pr-main

To enable distributed task execution, the following must be true:

  1. The workspace has to use a read-write access token. It can either be configured in nx.json or set via NX_CLOUD_ACCESS_TOKEN env variable in CI.

  2. NX_CLOUD_DISTRIBUTED_EXECUTION has to be set to true.

  3. You need to start agents using the nx-cloud start-agent command, and you need to stop them at the end using nx-cloud stop-all-agents.

The configuration above will use 3 agents to run all builds, tests and lints.

Note that only cacheable operations can be distributed because they have to be replayed on the main job.

You don't have to distribute every single command. For instance, it's pretty common to send coverage reports from a single machine. You can do it as follows:

- run: npx nx affected --target=test --parallel --max-parallel=2 - run: NX_CLOUD_DISTRIBUTED_EXECUTION=false npx nx affected --target=send-coverage-reports --parallel

Distributed task execution will copy all artifacts from agents to the main job, so after the affected --target=test command completes, all the coverage reports will be on the main job.

Incremental Builds

If you are using a version of Nx prior to 12.5, and if you have buildable projects (e.g., applications) that depends on other buildable projects, and you have to define the relationship in nx.json, as follows:

{ "targetDependencies": { "build": [ { "target": "build", "projects": "dependencies" } ] } }

Read More

Read more about Distributed Task Execution and how it compares to binning/sharding.

Select an article to learn more about Nx Cloud