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.
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}
22Each 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.
executoris a string of the form[package name]:[executor name]. For thebuildexecutor, the package name is@nx/webpackand the executor name iswebpack.optionsis an object that contains any configuration defaults for the executor. These options vary from executor to executor.configurationsallows you to create presets of options for different scenarios. All the configurations start with the properties defined inoptionsas a baseline and then overwrite those options. In the example, there is aproductionconfiguration that overrides the default options to setsourceMaptofalse.
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.
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}
12For 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.
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}
17You 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
6The 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.
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}
18When 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