Configuration
There are three top-level configuration files every Nx workspace has: angular.json
, nx.json
, and tsconfig.base.json
. Many Nx plugins modify these files when generating new code, but you can also modify them manually.
angular.json
The angular.json
configuration file contains information about the targets and generators. Let's look at the following example:
1{
2 "projects": {
3 "myapp": {
4 "root": "apps/myapp/",
5 "sourceRoot": "apps/myapp/src",
6 "projectType": "application",
7 "architect": {
8 "build": {
9 "builder": "@nrwl/web:build",
10 "outputs": ["dist/apps/myapp"],
11 "dependsOn": [
12 {
13 "target": "build",
14 "projects": "dependencies"
15 }
16 ],
17 "options": {
18 "index": "apps/myapp/src/app.html",
19 "main": "apps/myapp/src/main.ts"
20 },
21 "configurations": {
22 "production": {
23 "optimization": true
24 }
25 }
26 },
27 "serve": {
28 "builder": "@nrwl/web:dev-server",
29 "options": {
30 "buildTarget": "myapp:build",
31 "proxyConfig": "apps/myapp/proxy.conf.json"
32 }
33 },
34 "test": {
35 "builder": "@nrwl/jest:jest",
36 "options": {
37 "jestConfig": "apps/myapp/jest.config.js",
38 "tsConfig": "apps/myapp/tsconfig.spec.json"
39 }
40 }
41 }
42 },
43 "mylib": {
44 "root": "libs/mylib/",
45 "sourceRoot": "libs/mylib/src",
46 "projectType": "library",
47 "architect": {
48 "test": {
49 "builder": "@nrwl/jest:jest",
50 "options": {
51 "jestConfig": "libs/mylib/jest.config.js",
52 "tsConfig": "libs/mylib/tsconfig.spec.json"
53 }
54 }
55 }
56 }
57 },
58 "cli": {
59 "defaultCollection": "@nrwl/web"
60 }
61}
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 "architect": {}
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'. The project type is used in dep graph viz and in a few aux commands.architect
configures all the targets which define what tasks you can run against the library.
Nx uses the architect library built by the Angular team at Google. The naming reflects that. Important to note: it's a general purpose library that does not have any dependency on Angular.
Projects utilizing
project.json
files are not present inangular.json
.
Targets
Let's look at the simple architect target:
1{
2 "test": {
3 "builder": "@nrwl/jest:jest",
4 "options": {
5 "jestConfig": "libs/mylib/jest.config.js",
6 "tsConfig": "libs/mylib/tsconfig.spec.json"
7 }
8 }
9}
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 mytest mylib
or nx run mylib:mytest
.
Builder
The builder
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 builder named jest
and invoke it with the options.
Options
The options
provides a map of values that will be passed to the builder. 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 builder:
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 builder creates files in. The property is optional. If not provided, Nx assumes it is dist/libs/mylib
.
1{
2 "build": {
3 "builder": "@nrwl/web:build",
4 "outputs": ["dist/apps/myapp"],
5 "options": {
6 "index": "apps/myapp/src/app.html",
7 "main": "apps/myapp/src/main.ts"
8 }
9 }
10}
Configurations
The configurations
property provides extra sets of values that will be merged into the options map.
1{
2 "build": {
3 "builder": "@nrwl/web:build",
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 builder options get constructed:
1require(`@nrwl/jest`).builders['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:build",
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
, and --max-parallel
flags have 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:build",
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. You can define it once in nx.json
(see below).
Generators
Generators that are created using @angular-devkit
are called schematics. Default generator options are configured angular.json
as well. For instance, the following will tell Nx to always pass --style=scss
when creating new libraries.
1{
2 "schematics": {
3 "@nrwl/angular:library": {
4 "style": "scss"
5 }
6 }
7}
CLI Options
The following command generates a new library: nx g @nrwl/angular: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/angular"
4 }
5}
workspace.json
Your angular.json
file can be renamed to workspace.json
and Nx will process it in the same way. The workspace.json
has one additional top level property version
. Setting version
to 1 means the workspace.json
file syntax is identical to angular.json
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
.
project.json
In version 2 workspaces, project configurations can also be independent files, referenced by angular.json
. For instance, an angular.json
may contain projects configured as below.
1{
2 "projects": {
3 "mylib": "libs/mylib"
4 }
5}
This tells Nx that all configuration for that project is found in the libs/mylib/project.json
file. This file contains a combination of the project's configuration from both angular.json
and nx.json
.
1{
2 "root": "libs/mylib/",
3 "sourceRoot": "libs/mylib/src",
4 "projectType": "library",
5 "targets": {},
6 "tags": [],
7 "implicitDependencies": []
8}
nx.json
The nx.json
file contains extra configuration options mostly related to the project graph.
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 "angular.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 "projects": {
32 "myapp": {
33 "tags": []
34 },
35 "mylib": {
36 "tags": []
37 },
38 "myapp-e2e": {
39 "tags": [],
40 "implicitDependencies": ["myapp"]
41 }
42 }
43}
Projects utilizing
project.json
files will not be present innx.json
.
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 tomain
.
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
.
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 are cached by Nx.parallel
defines whether to run targets in parallelmaxParallel
defines the max number of processes used.captureStderr
defines whether the cache captures stderr or just stdoutskipNxCache
defines whether the Nx Cache should be skipped. Defaults tofalse
cacheDirectory
defines where the local cache is stored, which isnode_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 keyNX_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 thetsconfig.base.json
(e.g., adding/removing projects doesn't affect the hash of existing projects). Defaults tofalse
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
and maxParallel
in nx.json
, but you can also pass them in the terminal nx run-many --target=test --parallel
.
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}
These settings would store apps in /demos/
and libraries in /packages/
. The paths specified are relative to the workspace root.
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 "angular.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
angular.json
affects every project. - Changing the
dependencies
property inpackage.json
affects every project. - Changing the
devDependencies
property inpackage.json
only affectsmylib
. - Changing any of the custom check
scripts
inpackage.json
affects every project. - Changing
globalFile
only affectsmyapp
. - Changing any CSS file inside the
styles
directory only affectsmyapp
.
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}
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
.
.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.
When a file is specified in the .nxignore
file:
- Changes to that file are not taken into account in the
affected
calculations. - 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/angular: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:
nx g @nrwl/angular: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.