Configuration

Two configuration files you see in most Nx workspaces are nx.json and workspace.json. Many Nx plugins modify these files when generating new code, but you can also modify them manually.

• nx.json contains the global configuration. It contains the configuration of the Nx CLI itself: what is cached, how to execute your tasks. That's where you configure global implicit dependencies, default base branch etc.
• workspace.json lists the workspace projects either alongside with their configuration or pointing to project.json files contains that configuration.

nx.json

This is an example of the nx.json file. Most items configured are optional and your nx.json is likely to be shorter.

1{
2  "npmScope": "happyorg",
3  "affected": {
4    "defaultBase": "main"
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.base.json": "*",
21    "nx.json": "*"
22  },
23  "targetDependencies": {
24    "build": [
25      {
26        "target": "build",
27        "projects": "dependencies"
28      }
29    ]
30  },
31  "cli": {
32    "defaultCollection": "@nrwl/react"
33  },
34  "generators": {
35    "@nrwl/react:library": {
36      "js": true
37    }
38  }
39}

NPM Scope

Tells Nx what prefix to use when generating imports.

Affected

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

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

Tasks Runner Options

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 by passing --runner.

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 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, 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 normalizes the key length, so any length of key is acceptable.
• runtimeCacheInputs defines the list of commands that are run by the runner to include into the computation hash value.
• 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

runtimeCacheInputs are 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 in nx.json, but you can also pass it when invoking a command nx run-many --target=test --parallel=5.

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 affects every project.
• Changing the dependencies property in package.json affects every project.
• Changing the devDependencies property in package.json only affects mylib.
• Changing any of the custom check scripts in package.json affects every project.
• Changing globalFile only affects myapp.
• Changing any CSS file inside the styles directory only affects myapp.

You can also add dependencies between projects in workspace.json or project.json. 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      //... other project config
5      "tags": []
6    },
7    "myapp-e2e": {
8      //... other project config
9      "tags": [],
10      "implicitDependencies": ["myapp"]
11    }
12  }
13}

Target Dependencies

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 workspace.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 targetDependencies in nx.json is helpful.

1{
2  "targetDependencies": {
3    "build": [
4      {
5        "target": "build",
6        "projects": "dependencies"
7      }
8    ]
9  }
10}

The configuration above is identical to adding {"dependsOn": [{"target": "build", "projects": "dependencies"]} to every build target in workspace.json.

The dependsOn property in workspace.json takes precedence over the targetDependencies in nx.json.

Generators

Default generator options are configured in workspace.json as well. For instance, the following tells Nx to always pass --js when creating new libraries.

1{
2  "generators": {
3    "@nrwl/react:library": {
4      "js": 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/react:component": {
8        "classComponent": true
9      }
10    },
11    "targets": {}
12  }
13}

CLI Options

The following command generates a new library: nx g @nrwl/react:lib mylib. After setting the defaultCollection property, the lib is generated without mentioning the collection name: nx g lib mylib.

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

workspace.json and project.json

The workspace.json lists the workspace projects. Let's look at an example:

1{
2  "version": 2,
3  "projects": {
4    "myapp": "apps/myapp",
5    "mylib": "libs/mylib"
6  }
7}

This tells Nx that all configuration for the myapp project is found in the apps/myapp/project.json file, and the configuration for mylib is found in the libs/mylib/project.json.

This is an example of apps/myapp/project.json:

1{
2  "root": "apps/myapp/",
3  "sourceRoot": "apps/myapp/src",
4  "projectType": "application",
5  "targets": {
6    "build": {
7      "executor": "@nrwl/web:webpack",
8      "outputs": ["dist/apps/myapp"],
9      "dependsOn": [
10        {
11          "target": "build",
12          "projects": "dependencies"
13        }
14      ],
15      "options": {
16        "index": "apps/myapp/src/app.html",
17        "main": "apps/myapp/src/main.ts"
18      },
19      "configurations": {
20        "production": {
21          "optimization": true
22        }
23      }
24    },
25    "serve": {
26      "executor": "@nrwl/web:dev-server",
27      "options": {
28        "buildTarget": "myapp:build",
29        "proxyConfig": "apps/myapp/proxy.conf.json"
30      }
31    },
32    "test": {
33      "executor": "@nrwl/jest:jest",
34      "options": {
35        "jestConfig": "apps/myapp/jest.config.js",
36        "tsConfig": "apps/myapp/tsconfig.spec.json"
37      }
38    }
39  }
40}

Note, the targets section is there because we use the @nrwl/web and @nwrl/jest plugins. If we choose to use Nx Core without plugins, the targets section will not there. Often targets replace other config files we would have had otherwise. For instance, the build and serve targets above replace ad-hoc webpack configuration files and corresponding npm scripts.

Options

• root tells Nx the location of the project including its sources and configuration files.
• sourceRoot tells Nx the location of the project's source files.
• projectType is either 'application' or 'library'. The project type is used in dep graph viz and in a few aux commands.
• targets configures all the targets which define what tasks you can run against the project.
• tags configures tags used for linting
• implicitDependencies configure implicit dependencies between projects in the workspace (see below)

Targets

Let's look at the simple target:

1{
2  "test": {
3    "executor": "@nrwl/jest:jest",
4    "options": {
5      "jestConfig": "apps/myapp/jest.config.js",
6      "tsConfig": "apps/myapp/tsconfig.spec.json"
7    }
8  }
9}

Target Name

The name of the target test means that you can invoke it as follows: nx test myapp or nx run myapp:test. The name isn't significant in any other way. If you rename it to, for example, mytest, you run as follows: nx mytest myapp or nx run myapp: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 are passed to the executor. The provided command line args are merged into this map. For example, nx test myapp --jestConfig=libs/myapp/another-jest.config.js passes the following to the executor:

1{
2  "jestConfig": "libs/mylib/another-jest.config.js",
3  "tsConfig": "libs/mylib/tsconfig.spec.json"
4}

Outputs

The outputs property lists the folders the executor creates files in. The property is optional. If not provided, Nx assumes it is dist/apps/myapp.

Configurations

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

1{
2  "build": {
3    "executor": "@nrwl/web:webpack",
4    "outputs": ["dist/apps/myapp"],
5    "options": {
6      "index": "apps/myapp/src/app.html",
7      "main": "apps/myapp/src/main.ts"
8    },
9    "configurations": {
10      "production": {
11        "optimization": true
12      }
13    }
14  }
15}

You can select a configuration like this: nx build myapp --configuration=production or nx run myapp: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.

Target Dependencies

Targets can depend on other targets. A common scenario is having to build dependencies of a project first before building the project. You can specify this using the dependsOn.

1{
2  "build": {
3    "executor": "@nrwl/web:webpack",
4    "outputs": ["dist/apps/myapp"],
5    "options": {
6      "index": "apps/myapp/src/app.html",
7      "main": "apps/myapp/src/main.ts"
8    },
9    "dependsOn": [
10      {
11        "target": "build",
12        "projects": "dependencies"
13      }
14    ]
15  }
16}

In this case, running nx build myapp builds all the buildable libraries myapp depends on first. In other words, nx build myapp results in multiple tasks executing. The --parallel flag has the same effect as they would with run-many or affected.

It is also possible to define dependencies between the targets of the same project.

In the following example invoking nx build myapp builds all the libraries first, then nx build-base myapp is executed and only then nx build myapp is executed.

1{
2  "build-base": {
3    "executor": "@nrwl/web:webpack",
4    "outputs": ["dist/apps/myapp"],
5    "options": {
6      "index": "apps/myapp/src/app.html",
7      "main": "apps/myapp/src/main.ts"
8    }
9  },
10  "build": {
11    "executor": "@nrwl/workspace:run-commands",
12    "dependsOn": [
13      {
14        "target": "build",
15        "projects": "dependencies"
16      },
17      {
18        "target": "build-base",
19        "projects": "self"
20      }
21    ],
22    "options": {
23      "command": "./copy-readme-and-license.sh"
24    }
25  }
26}

Often the same dependsOn configuration has to be defined for every project in the repo. Define it globally once in nx.json (see below).

workspace.json without project.json

The project.json files can be inlined into workspace.json, and that was the default before Nx 13. The workspace.json file above can look like this:

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          //...
11        },
12        "serve": {
13          //...
14        },
15        "test": {
16          //...
17        }
18      },
19      "mylib": {
20        //...
21      }
22    }
23  }
24}

.nxignore

You may optionally add an .nxignore file to the root. This file is used to specify files in your workspace that should be completely ignored by Nx.

The syntax is the same as a [.gitignore file](https: //git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring).

**When a file is specified in the .nxignore file: **

1. Changes to that file are not taken into account in the affected calculations.
2. Even if the file is outside an app or library, nx workspace-lint won't warn about it.

Keeping the configuration in sync

When creating projects, the Nx generators make sure these configuration files are updated accordingly for the new projects. While development continues and the workspace grows, you might need to refactor projects by renaming them, moving them to a different folder, removing them, etc. When this is done manually, you need to ensure your configuration files are kept in sync and that's a cumbersome task. Fortunately, Nx provides some generators and executors to help you with these tasks.

Moving projects

Projects can be moved or renamed using the @nrwl/workspace: move generator.

For instance, if a library under the booking folder is now being shared by multiple apps, you can move it to the shared folder like this: bash nx g @nrwl/workspace: move --project booking-some-library shared/some-library

Removing projects

Projects can be removed using the @nrwl/workspace:remove generator.

nx g @nrwl/workspace:remove booking-some-library

Validating the configuration

If at any point in time you want to check if your configuration is in sync, you can use the workspace-lint executor:

nx workspace-lint

This will identify any projects with no files in the configured project root folder, as well as any file that's not part of any project configured in the workspace.