nx.json

The nx.json file configures the Nx CLI and project defaults.

The following is an expanded version showing all options. Your nx.json will likely be much shorter.

1{
2  "npmScope": "happyorg",
3  "affected": {
4    "defaultBase": "main"
5  },
6  "workspaceLayout": {
7    "appsDir": "demos",
8    "libsDir": "packages"
9  },
10  "implicitDependencies": {
11    "package.json": {
12      "dependencies": "*",
13      "devDependencies": "*"
14    },
15    "tsconfig.base.json": "*",
16    "nx.json": "*"
17  },
18  "namedInputs": {
19    "default": ["{projectRoot}/**/*"],
20    "production": ["!{projectRoot}/**/*.spec.tsx"]
21  },
22  "targetDefaults": {
23    "build": {
24      "inputs": ["production", "^production"],
25      "dependsOn": ["^build"]
26    }
27  },
28  "generators": {
29    "@nrwl/js:library": {
30      "buildable": true
31    }
32  },
33  "tasksRunnerOptions": {
34    "default": {
35      "runner": "nx/tasks-runners/default",
36      "options": {
37        "cacheableOperations": ["build", "lint", "test", "e2e"]
38      }
39    }
40  }
41}
42

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 main.

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}
7

These settings would store apps in /demos/ and libraries in /packages/. The paths specified are relative to the workspace root.

Files & 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 shared files cannot be inferred statically. You can configure those using implicitDependencies.

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

In the example above:

• Changing the dependencies property in package.json affects every project.
• Changing the mypackage 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.

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}
7

And projects can define their prod fileset, without having to redefine the inputs for the test target.

1{
2  "namedInputs": {
3    "production": [
4      "!{projectRoot}/**/*.test.js",
5      "{workspacRoot}/jest.config.js"
6    ]
7  }
8}
9

In this case Nx will use the right prod input for each project.

Target Defaults

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}
8

The configuration above is identical to adding {"dependsOn": ["^build"]} to every build target of every project.

Another target default you can configure is outputs:

1{
2  "targetDefaults": {
3    "build": {
4      "outputs": ["./custom-dist"]
5    }
6  }
7}
8

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    "@nrwl/js:library": {
4      "buildable": true
5    }
6  }
7}
8

Tasks 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 --target=build --all --runner=another.

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

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