Configuration

There are three top-level configuration files every Nx workspace has: workspace.json, nx.json, and tsconfig.json. Many Nx plugins will modify these files when generating new code, but you can also modify them manually.

workspace.json

The workspace.json configuration file contains information about the targets and generators. Let's look at the following example:

1{
2  "version": 2,
3  "projects": {
4    "myapp": {
5      "root": "apps/myapp/",
6      "sourceRoot": "apps/myapp/src",
7      "projectType": "application",
8      "targets": {
9        "build": {
10          "executor": "@nrwl/node:build",
11          "outputs": ["dist/apps/myapp"],
12          "options": {
13            "outputPath": "dist/packages/myapp",
14            "main": "packages/myapp/src/main.ts",
15            "tsConfig": "packages/myapp/tsconfig.app.json",
16            "assets": ["packages/myapp/src/assets"]
17          },
18          "configurations": {
19            "production": {
20              "optimization": true
21            }
22          }
23        },
24        "serve": {
25          "executor": "@nrwl/node:execute",
26          "options": {
27            "buildTarget": "myapp:build"
28          }
29        },
30        "test": {
31          "executor": "@nrwl/jest:jest",
32          "options": {
33            "jestConfig": "apps/myapp/jest.config.js"
34          }
35        }
36      }
37    },
38    "mylib": {
39      "root": "libs/mylib/",
40      "sourceRoot": "libs/mylib/src",
41      "projectType": "library",
42      "targets": {
43        "test": {
44          "executor": "@nrwl/jest:jest",
45          "options": {
46            "jestConfig": "libs/mylib/jest.config.js",
47            "tsConfig": "libs/mylib/tsconfig.spec.json"
48          }
49        },
50        "build": {
51          "executor": "@nrwl/node:package",
52          "options": {
53            "outputPath": "dist/libs/mylib",
54            "tsConfig": "libs/mylib/tsconfig.lib.json",
55            "packageJson": "libs/mylib/package.json",
56            "main": "libs/mylib/src/index.ts",
57            "assets": ["libs/mylib/*.md"]
58          }
59        }
60      }
61    }
62  },
63  "cli": {
64    "defaultCollection": "@nrwl/node"
65  },
66  "generators": {
67    "@nrwl/node:library": {
68      "js": true
69    }
70  }
71}

Projects

The projects property configures all apps and libs.

For instance, the following configures mylib.

1{
2  "mylib": {
3    "root": "libs/mylib/",
4    "sourceRoot": "libs/mylib/src",
5    "projectType": "library",
6    "targets": {}
7  }
8}
  • root tells Nx the location of the library including its sources and configuration files.
  • sourceRoot tells Nx the location of the library's source files.
  • projectType is either 'application' or 'library'.
  • targets configures all the targets which define what tasks you can run against the library.

Targets

Let's look at the simple target:

1{
2  "test": {
3    "executor": "@nrwl/jest:jest",
4    "options": {
5      "jestConfig": "libs/mylib/jest.config.js"
6    }
7  }
8}

Target Name

The name of the target test means that you can invoke it as follows: nx test mylib or nx run mylib:test. The name isn't significant in any other way. If you rename it to, for example, mytest, you will be able to run as follows: nx run mylib:mytest.

Executor

The executor property tells Nx what function to invoke when you run the target. "@nrwl/jest:jest" tells Nx to find the @nrwl/jest package, find the executor named jest and invoke it with the options.

Options

The options provides a map of values that will be passed to the executor. The provided command line args will be merged into this map. I.e., nx test mylib --jestConfig=libs/mylib/another-jest.config.js will pass the following to the executor:

1{
2  "jestConfig": "libs/mylib/another-jest.config.js"
3}

Outputs

The outputs property lists the folders the executor will create files in. The property is optional. If not provided, Nx will assume it is dist/libs/mylib.

1{
2  "build": {
3    "executor": "@nrwl/node:package",
4    "options": {
5      "outputPath": "dist/libs/mylib",
6      "tsConfig": "libs/mylib/tsconfig.lib.json",
7      "packageJson": "libs/mylib/package.json",
8      "main": "libs/mylib/src/index.ts",
9      "assets": ["libs/mylib/*.md"]
10    }
11  }
12}

Configurations

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

1{
2  "build": {
3    "executor": "@nrwl/node:package",
4    "options": {
5      "outputPath": "dist/libs/mylib",
6      "tsConfig": "libs/mylib/tsconfig.lib.json",
7      "packageJson": "libs/mylib/package.json",
8      "main": "libs/mylib/src/index.ts",
9      "assets": ["libs/mylib/*.md"]
10    }
11  },
12  "configurations": {
13    "production": {
14      "packageJson": "libs/mylib/package.prod.json"
15    }
16  }
17}

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

The following show how the executor options get constructed:

require(`@nrwl/jest`).executors['jest']({...options, ...selectedConfiguration, ...commandLineArgs}}) // Pseudocode

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

Generators

You can configure default generator options in workspace.json as well. For instance, the following will tell Nx to always pass --js when creating new libraries.

1{
2  "generators": {
3    "@nrwl/node:library": {
4      "buildable": true
5    }
6  }
7}

You can also do it on the project level:

1{
2  "mylib": {
3    "root": "libs/mylib/",
4    "sourceRoot": "libs/mylib/src",
5    "projectType": "library",
6    "generators": {
7      "@nrwl/node:lib": {
8        "moreOptions": true
9      }
10    },
11    "targets": {}
12  }
13}

CLI Options

The following command will generate a new library: nx g @nrwl/node:lib mylib. If you set the defaultCollection property, you can generate the lib without mentioning the collection name: nx g lib mylib.

1{
2  "cli": {
3    "defaultCollection": "@nrwl/node"
4  }
5}

Version

When the version of workspace.json is set to 2, targets, generators and executor properties are used instead of the version 1 properties architect, schematics and builder.

nx.json

The nx.json file contains extra configuration options mostly related to the project graph.

1{
2  "npmScope": "happyorg",
3  "affected": {
4    "defaultBase": "master"
5  },
6  "tasksRunnerOptions": {
7    "default": {
8      "runner": "@nrwl/workspace/tasks-runners/default",
9      "options": {
10        "cacheableOperations": ["build", "lint", "test", "e2e"]
11      }
12    }
13  },
14  "implicitDependencies": {
15    "workspace.json": "*",
16    "package.json": {
17      "dependencies": "*",
18      "devDependencies": "*"
19    },
20    "tsconfig.json": "*",
21    "nx.json": "*"
22  },
23  "projects": {
24    "myapp": {
25      "tags": []
26    },
27    "mylib": {
28      "tags": []
29    },
30    "myapp-e2e": {
31      "tags": [],
32      "implicitDependencies": ["myapp"]
33    }
34  }
35}

NPM Scope

Tells Nx what prefix to use when generating library imports.

Affected

Tells Nx which branch and HEAD to use when calculating affected projects.

  • defaultBase defines the default base branch, defaulted to master.

Tasks Runner Options

Tasks runners are invoked when you run nx test, nx build, nx run-many, nx affected, etc.. The tasks runner named "default" will be, unsurprisingly, used by default. But you can specify a different one by passing --runner.

A task is an invocation of a target.

Tasks runners can accept different options. The following are the options supported by "@nrwl/workspace/tasks-runners/default" and "@nrwl/nx-cloud".

  • cacheableOperations defines the list of targets/operations that will be cached by Nx.
  • strictlyOrderedTargets defines the list of targets that need to be executed in the order defined by the dependency graph. Defaults to ['build']
  • parallel defines whether to run targets in parallel
  • maxParallel defines the max number of processes used.
  • captureStderr defines whether the cache will capture stderr or just stdout
  • skipNxCache defines whether the Nx Cache should be skipped. Defaults to false
  • cacheDirectory defines where the local cache is stored, which is node_modules/.cache/nx by default.
  • encryptionKey (when using "@nrwl/nx-cloud" only) defines an encryption key to support end-to-end encryption of your cloud cache. You may also provide an environment variable with the key NX_CLOUD_ENCRYPTION_KEY that contains an encryption key as its value. The Nx Cloud task runner will normalize the key length, so any length of key is acceptable.
  • runtimeCacheInputs defines the list of commands that will be run by the runner to include into the computation hash value.

runtimeCacheInputs can be set as follows:

1{
2  "tasksRunnerOptions": {
3    "default": {
4      "runner": "@nrwl/workspace/tasks-runners/default",
5      "options": {
6        "cacheableOperations": ["build", "lint", "test", "e2e"],
7        "runtimeCacheInputs": ["node -v"]
8      }
9    }
10  }
11}

You can configure parallel and maxParallel in nx.json, but you can also pass them in the terminal nx run-many --target=test --parallel.

Implicit Dependencies

Nx performs advanced source-code analysis to figure out the project graph of the workspace. So when you make a change, Nx can deduce what can be broken by this change. Some dependencies between projects and dependencies between shared files and projects cannot be inferred statically. You can configure those using implicitDependencies.

1{
2  "implicitDependencies": {
3    "workspace.json": "*",
4    "package.json": {
5      "dependencies": "*",
6      "devDependencies": {
7        "mypackage": ["mylib"]
8      },
9      "scripts": {
10        "check:*": "*"
11      }
12    },
13    "globalFile": ["myapp"],
14    "styles/**/*.css": ["myapp"]
15  }
16}

In the example above:

  • Changing workspace.json will affect every project.
  • Changing the dependencies property in package.json will affect every project.
  • Changing the devDependencies property in package.json will only affect mylib.
  • Changing any of the custom check scripts in package.json will affect every project.
  • Changing globalFile will only affect myapp.
  • Changing any CSS file inside the styles directory will only affect myapp.

You can also add dependencies between projects. For instance, the example below defines a dependency from myapp-e2e to myapp, such that every time myapp is affected, myapp-e2e is affected as well.

1{
2  "projects": {
3    "myapp": {
4      "tags": []
5    },
6    "myapp-e2e": {
7      "tags": [],
8      "implicitDependencies": ["myapp"]
9    }
10  }
11}