Run Tasks

Monorepos can have hundreds or even thousands of projects, so being able to run actions against all (or some) of them is a key feature of a tool like Nx.

Types of Tasks

Nx tasks can be created from existing package.json scripts, inferred from tooling configuration files, or defined in a project.json file. Nx will merge all three sources together to determine the tasks for a particular project.

Read the Project Configuration docs to see all the configuration options for a task.

Running Tasks

Nx uses the following syntax:

Syntax for Running Tasks in Nx

Run a Single Task

To run the test task for the header project run this command:

❯

npx nx test header

Run Tasks for Multiple Projects

You can use the run-many command to run a task for multiple projects. Here are a couple of examples.

Run the build task for all projects in the repo:

❯

npx nx run-many -t build

Run the build, lint and test task for all projects in the repo:

❯

npx nx run-many -t build lint test

Run the build, lint and test task just on the header and footer projects:

❯

npx nx run-many -t build lint test -p header footer

Note that Nx parallelizes all these tasks making sure they are also run in the right order based on their dependencies and the task pipeline configuration. You can also control how many tasks can run in parallel at once.

Learn more about the run-many command.

Run Tasks on Projects Affected by a PR

You can also run a command for all the projects affected by your PR like this:

❯

npx nx affected -t test

Learn more about the affected command here.

Defining a Task Pipeline

It is pretty common to have dependencies between tasks, requiring one task to be run before another. For example, you might want to run the build target on the header project before running the build target on the app project.

Nx is already able to automatically understand the dependencies between projects (see project graph).

However, you need to define for which targets such ordering matters. In the following example we are telling Nx that before running the build target it needs to run the build target on all the projects the current project depends on:

nx.json
{
  ...
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}

Meaning, if we run nx build myreactapp, Nx will first run build on modules-shared-ui and modules-products before running build on myreactapp. You can define these task dependencies globally for your workspace in nx.json or individually in each project's project.json file.

Learn all the details:

Run Root-Level Tasks

Sometimes you have tasks that apply to the entire codebase rather than to a single project. But you still want those tasks to go through the "Nx pipeline" in order to benefit from caching. You can define these in the root-level package.json or project.json as follows:

package.json
{
  "name": "myorg",
  "scripts": {
    "docs": "node ./generateDocsSite.js"
  },
  "nx": {}
}

Note the nx: {} property on the package.json. This is necessary to inform Nx about this root-level project. The property can also be expanded to specify cache inputs and outputs.

If you want Nx to cache the task, but prefer to use npm (or pnpm/yarn) to run the script (i.e. npm run docs) you can use the nx exec command:

package.json
{
  "name": "myorg",
  "scripts": {
    "docs": "nx exec -- node ./generateDocsSite.js"
  },
  "nx": {}
}

To invoke the task, use:

❯

npx nx docs

Learn more about root-level tasks in our dedicated recipe page.

Migration