nx.json
The nx.json file configures the Nx CLI and project defaults. The full machine readable schema is available on Github.
The following is an expanded example showing all options. Your nx.json will likely be much shorter. For a more intuitive understanding of the roles of each option, you can highlight the options in the excerpt below that relate to different categories.
1{
2 "extends": "nx/presets/npm.json",
3 "affected": {
4 "defaultBase": "main"
5 },
6 "workspaceLayout": {
7 "appsDir": "demos",
8 "libsDir": "packages"
9 },
10 "generators": {
11 "@nx/js:library": {
12 "buildable": true
13 }
14 },
15 "tasksRunnerOptions": {
16 "default": {
17 "runner": "nx/tasks-runners/default",
18 "options": {
19 "cacheableOperations": ["build", "lint", "test", "e2e"]
20 }
21 }
22 },
23 "namedInputs": {
24 "default": ["{projectRoot}/**/*"],
25 "production": ["!{projectRoot}/**/*.spec.tsx"]
26 },
27 "targetDefaults": {
28 "build": {
29 "inputs": ["production", "^production"],
30 "dependsOn": ["^build"],
31 "executor": "@nrwl/js:tsc",
32 "options": {
33 "main": "{projectRoot}/src/index.ts"
34 }
35 }
36 }
37}
38Extends
Some presets use the extends property to hide some default options in a separate json file. The json file specified in the extends property is located in your node_modules folder. The Nx preset files are specified in the nx package.
NPM Scope
The npmScope property of the nx.json file is deprecated as of version 16.2.0. npmScope was used as a prefix for the names of newly created projects. The new recommended way to define the organization prefix is to set the name property in the root package.json file to @my-org/root. Then @my-org/ will be used as a prefix for all newly created projects.
In Nx 16, if the npmScope property is present, it will be used as a prefix. If the npmScope property is not present, the name property of the root package.json file will be used to infer the prefix.
In Nx 17, the npmScope property will be ignored.
Affected
Tells Nx which branch and HEAD to use when calculating affected projects.
defaultBasedefines the default base branch, defaulted tomain.
Workspace Layout
You can add a workspaceLayout property to modify where libraries and apps are located.
1{
2 "workspaceLayout": {
3 "appsDir": "demos",
4 "libsDir": "packages"
5 }
6}
7These settings would store apps in /demos/ and libraries in /packages/. The paths specified are relative to the workspace root.
inputs & namedInputs
Named inputs defined in nx.json are merged with the named inputs defined in each project's project.json. In other words, every project has a set of named inputs, and it's defined as: {...namedInputsFromNxJson, ...namedInputsFromProjectsProjectJson}.
Defining inputs for a given target would replace the set of inputs for that target name defined in nx.json. Using pseudocode inputs = projectJson.targets.build.inputs || nxJson.targetDefaults.build.inputs.
You can also define and redefine named inputs. This enables one key use case, where your nx.json can define things like this (which applies to every project):
1"test": {
2 "inputs": [
3 "default",
4 "^production"
5 ]
6}
7And projects can define their production fileset, without having to redefine the inputs for the test target.
1{
2 "namedInputs": {
3 "production": ["default", "!{projectRoot}/**/*.test.js"]
4 }
5}
6In this case Nx will use the right production input for each project.
inputs and namedInputs are also described in the project configuration reference
This guide walks through a few examples of how to customize inputs and namedInputs
Target Defaults
Target defaults provide ways to set common options for a particular target in your workspace. When building your project's configuration, we merge it with up to 1 default from this map. For a given target, we look at its name and its executor. We then check target defaults for any of the following combinations:
`${executor}``${targetName}`
Whichever of these we find first, we use as the base for that target's configuration. Some common scenarios for this follow.
Targets can depend on other targets. A common scenario is having to build dependencies of a project first before building the project. The dependsOn property in project.json can be used to define the list of dependencies of an individual target.
Often the same dependsOn configuration has to be defined for every project in the repo, and that's when defining targetDefaults in nx.json is helpful.
1{
2 "targetDefaults": {
3 "build": {
4 "dependsOn": ["^build"]
5 }
6 }
7}
8The configuration above is identical to adding {"dependsOn": ["^build"]} to every build target of every project.
For full documentation of the dependsOn property, see the project configuration reference.
For full documentation of the `dependsOn` property, see the project configuration reference
Another target default you can configure is outputs:
1{
2 "targetDefaults": {
3 "build": {
4 "outputs": ["{projectRoot}/custom-dist"]
5 }
6 }
7}
8When defining any options or configurations inside of a target default, you may use the {workspaceRoot} and {projectRoot} tokens. This is useful for defining things like the outputPath or tsconfig for many build targets.
1{
2 "targetDefaults": {
3 "@nx/js:tsc": {
4 "options": {
5 "main": "{projectRoot}/src/index.ts"
6 },
7 "configurations": {
8 "prod": {
9 "tsconfig": "{projectRoot}/tsconfig.prod.json"
10 }
11 },
12 "inputs": ["prod"],
13 "outputs": ["{workspaceRoot}/{projectRoot}"]
14 },
15 "build": {
16 "inputs": ["prod"],
17 "outputs": ["{workspaceRoot}/{projectRoot}"]
18 }
19 }
20}
21Note that the inputs and outputs are respecified on the @nx/js:tsc default configuration. This is required, as when reading target defaults Nx will only ever look at one key. If there is a default configuration based on the executor used, it will be read first. If not, Nx will fall back to looking at the configuration based on target name. For instance, running nx build project will read the options from targetDefaults[@nx/js:tsc] if the target configuration for build uses the @nx/js:tsc executor. It would not read any of the configuration from the build target default configuration unless the executor does not match.
Generators
Default generator options are configured in nx.json as well. For instance, the following tells Nx to always pass --buildable=true when creating new libraries.
1{
2 "generators": {
3 "@nx/js:library": {
4 "buildable": true
5 }
6 }
7}
8Tasks Runner Options
A task is an invocation of a target.
Tasks runners are invoked when you run nx test, nx build, nx run-many, nx affected, and so on. The tasks runner named "default" is used by default. Specify a different one like this nx run-many -t build --runner=another.
Tasks runners can accept different options. The following are the options supported by "nx/tasks-runners/default" and "nx-cloud".
| Property | Description |
|---|---|
| cacheableOperations | defines the list of targets/operations that are cached by Nx |
| parallel | defines the max number of targets ran in parallel (in older versions of Nx you had to pass --parallel --maxParallel=3 instead of --parallel=3) |
| captureStderr | defines whether the cache captures stderr or just stdout |
| skipNxCache | defines whether the Nx Cache should be skipped (defaults to false) |
| cacheDirectory | defines where the local cache is stored (defaults to node_modules/.cache/nx) |
| encryptionKey | (when using "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 normalizes the key length, so any length of key is acceptable |
| selectivelyHashTsConfig | only hash the path mapping of the active project in the tsconfig.base.json (e.g., adding/removing projects doesn't affect the hash of existing projects) (defaults to false) |
You can configure parallel in nx.json, but you can also pass them in the terminal nx run-many -t test --parallel=5.