Executors and Configurations

Executors are pre-packaged node scripts that can be used to run tasks in a consistent way.

In order to use an executor, you need to install the plugin that contains the executor and then configure the executor in the project's project.json file.

apps/cart/project.json
1{ 2 "root": "apps/cart", 3 "sourceRoot": "apps/cart/src", 4 "projectType": "application", 5 "generators": {}, 6 "targets": { 7 "build": { 8 "executor": "@nx/webpack:webpack", 9 "options": { 10 "outputPath": "dist/apps/cart", 11 ... 12 } 13 }, 14 "test": { 15 "executor": "@nx/jest:jest", 16 "options": { 17 ... 18 } 19 } 20 } 21} 22

Each project has targets configured to run an executor with a specific set of options. In this snippet, cart has two targets defined - build and test.

Each executor definition has an executor property and, optionally, an options and a configurations property.

  • executor is a string of the form [package name]:[executor name]. For the build executor, the package name is @nx/webpack and the executor name is webpack.
  • options is an object that contains any configuration defaults for the executor. These options vary from executor to executor.
  • configurations allows you to create presets of options for different scenarios. All the configurations start with the properties defined in options as a baseline and then overwrite those options. In the example, there is a production configuration that overrides the default options to set sourceMap to false.

Once configured, you can run an executor the same way you would run any target:

nx [command] [project]

nx build cart

Browse the executors that are available in the plugin registry.

Run a Terminal Command from an Executor

If defining a new target that needs to run a single shell command, there is a shorthand for the nx:run-commands executor that can be used.

project.json
1{ 2 "root": "apps/cart", 3 "sourceRoot": "apps/cart/src", 4 "projectType": "application", 5 "generators": {}, 6 "targets": { 7 "echo": { 8 "command": "echo 'hello world'" 9 } 10 } 11} 12

For more info, see the run-commands documentation

Build your own Executor

Nx comes with a Devkit that allows you to build your own executor to automate your Nx workspace. Learn more about it in the docs page about creating a local executor.

Running executors with a configuration

You can use a specific configuration preset like this:

nx [command] [project] --configuration=[configuration]

nx build cart --configuration=production

Use Task Configurations

The configurations property provides extra sets of values that will be merged into the options map.

project.json
1{ 2 "build": { 3 "executor": "@nx/js:tsc", 4 "outputs": ["{workspaceRoot}/dist/libs/mylib"], 5 "dependsOn": ["^build"], 6 "options": { 7 "tsConfig": "libs/mylib/tsconfig.lib.json", 8 "main": "libs/mylib/src/main.ts" 9 }, 10 "configurations": { 11 "production": { 12 "tsConfig": "libs/mylib/tsconfig-prod.lib.json" 13 } 14 } 15 } 16} 17

You can select a configuration like this: nx build mylib --configuration=production or nx run mylib:build:production.

The following code snippet shows how the executor options get constructed:

1require(`@nx/jest`).executors['jest']({ 2 ...options, 3 ...selectedConfiguration, 4 ...commandLineArgs, 5}); // Pseudocode 6

The selected configuration adds/overrides the default options, and the provided command line args add/override the configuration options.

Default Configuration

When using multiple configurations for a given target, it's helpful to provide a default configuration. For example, running e2e tests for multiple environments. By default it would make sense to use a dev configuration for day to day work, but having the ability to run against an internal staging environment for the QA team.

project.json
1{ 2 "e2e": { 3 "executor": "@nx/cypress:cypress", 4 "options": { 5 "cypressConfig": "apps/my-app-e2e/cypress.config.ts" 6 }, 7 "configurations": { 8 "dev": { 9 "devServerTarget": "my-app:serve" 10 }, 11 "qa": { 12 "baseUrl": "https://some-internal-url.example.com" 13 } 14 }, 15 "defaultConfiguration": "dev" 16 } 17} 18

When running nx e2e my-app-e2e, the dev configuration will be used. In this case using the local dev server for my-app. You can always run the other configurations by explicitly providing the configuration i.e. nx e2e my-app-e2e --configuration=qa or nx run my-app-e2e:e2e:qa