Configuration: project.json and nx.json

There are two main types of configuration in every Nx workspace: project configuration and the global Nx CLI configuration.

Projects can be configured in package.json (if you use npm scripts and not Nx executors) and project.json (if you use Nx executors). Both package.json and project.json files are located in each project's folder. Nx merges the two files to get each project's configuration. This guide covers the project.json case.

Project Configuration

The project.json file contains configuration specific to its project. This file is often created when you use Nx Plugins. It configures custom executors, which are used instead of npm scripts. Custom executors are typed, toolable and provide a lot more flexibility for running long-live processes. They are also more composable.

If you're satisfied with npm scripts though, you will never see a project.json file in your workspace. But we encourage you to explore Nx Plugins and the power they bring.

Let's look at the following project.json:

1{
2  "root": "libs/mylib/",
3  "sourceRoot": "libs/mylib/src",
4  "projectType": "library",
5  "namedInputs": {
6    "default": ["{projectRoot}/**/*"],
7    "prod": ["!{projectRoot}/**/*.spec.tsx"]
8  },
9  "targets": {
10    "test": {
11      "executor": "@nrwl/jest:jest",
12      "inputs": ["default", "^prod"],
13      "outputs": [],
14      "dependsOn": ["build"],
15      "options": {
16        "jestConfig": "libs/mylib/jest.config.js",
17        "tsConfig": "libs/mylib/tsconfig.spec.json"
18      }
19    },
20    "build": {
21      "executor": "@nrwl/js:tsc",
22      "inputs": ["prod", "^prod"],
23      "outputs": ["dist/libs/mylib"],
24      "dependsOn": ["^build"],
25      "options": {
26        "tsConfig": "libs/mylib/tsconfig.lib.json",
27        "main": "libs/mylib/src/main.ts"
28      },
29      "configurations": {
30        "production": {
31          "tsConfig": "libs/mylib/tsconfig-prod.lib.json"
32        }
33      }
34    }
35  },
36  "tags": ["scope:myteam"],
37  "implicitDependencies": ["anotherlib"]
38}
39

• 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 project graph viz and in a few aux commands.

inputs & namedInputs

The inputs array tells Nx what to consider to determine whether a particular invocation of a script should be a cache hit or not. There are three types of inputs:

Filesets

Examples:

• {projectRoot}/**.*.ts
• same as {fileset: "{projectRoot}/**/*.ts"}
• {workspaceRoot}/jest.config.ts
• same as {fileset: "{workspaceRoot}/jest.config.ts}

Runtime Inputs

Examples:

• {runtime: "node -v"}

Node the result value is hashed, so it is never displayed.

Env Variables

Examples:

• {env: "MY_ENV_VAR"}

Node the result value is hashed, so it is never displayed.

Named Inputs

Examples:

• inputs: ["prod"]
• same as inputs: [{input: "prod", projects: "self"}]

Often the same glob will appear in many places (e.g., prod fileset will exclude spec files for all projects). Because keeping them in sync is error-prone, we recommend defining named inputs, which you can then reference in all of those places.

Using ^

Examples:

• inputs: ["^prod"]
• same as inputs: [{input: "prod", projects: "dependencies"}]

Similar to dependsOn, the "^" symbols means "dependencies". This is a very important idea, so let's illustrate it with an example.

1"test": {
2  "inputs": [ "default", "^prod" ]
3}
4

The configuration above means that the test target depends on all source files of a given project and only prod sources (non-test sources) of its dependencies. In other words, it treats test sources as private.

Targets

Let's look at a sample test target:

1{
2  "test": {
3    "executor": "@nrwl/jest:jest",
4    "outputs": [],
5    "dependsOn": ["build"],
6    "options": {
7      "jestConfig": "libs/mylib/jest.config.js",
8      "tsConfig": "libs/mylib/tsconfig.spec.json"
9    }
10  }
11}
12

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.

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  "tsConfig": "libs/mylib/tsconfig.spec.json"
4}
5

Configurations

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

1{
2  "build": {
3    "executor": "@nrwl/js:tsc",
4    "outputs": ["dist/libs/mylib"],
5    "dependsOn": ["^build"],
6    "options": {
7      "tsConfig": "libs/mylib/tsconfig.lib.json",
8      "main": "libs/mylib/src/main.ts"
9    },
10    "configurations": {
11      "production": {
12        "tsConfig": "libs/mylib/tsconfig-prod.lib.json"
13      }
14    }
15  }
16}
17

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

The following code snippet shows how the executor options get constructed:

1require(`@nrwl/jest`).executors['jest']({
2  ...options,
3  ...selectedConfiguration,
4  ...commandLineArgs,
5}); // Pseudocode
6

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

inputs & namedInputs

The inputs array tells Nx what to consider to determine whether a particular invocation of a script should be a cache hit or not. There are three types of inputs:

Filesets

Examples:

• {projectRoot}/**.*.ts
• same as {fileset: "{projectRoot}/**/*.ts"}
• {workspaceRoot}/jest.config.ts
• same as {fileset: "{workspaceRoot}/jest.config.ts}

Runtime Inputs

Examples:

• {runtime: "node -v"}

Node the result value is hashed, so it is never displayed.

Env Variables

Examples:

• {env: "MY_ENV_VAR"}

Node the result value is hashed, so it is never displayed.

Named Inputs

Examples:

• inputs: ["prod"]
• same as inputs: [{input: "prod", projects: "self"}]

Often the same glob will appear in many places (e.g., prod fileset will exclude spec files for all projects). Because keeping them in sync is error-prone, we recommend defining named inputs, which you can then reference in all of those places.

Using ^

Examples:

• inputs: ["^prod"]
• same as inputs: [{input: "prod", projects: "dependencies"}]

Similar to dependsOn, the "^" symbols means "dependencies". This is a very important idea, so let's illustrate it with an example.

1"test": {
2  "inputs": [ "default", "^prod" ]
3}
4

The configuration above means that the test target depends on all source files of a given project and only prod sources (non-test sources) of its dependencies. In other words, it treats test sources as private.

Outputs

Targets may define outputs to tell Nx where the target is going to create file artifacts that Nx should cache. "outputs": ["dist/libs/mylib"] tells Nx where the build target is going to create file artifacts.

Basic Example

Usually, a target writes to a specific directory or a file. The following instructs Nx to cache dist/libs/mylib and build/libs/mylib/main.js:

1  {
2    "build": {
3      ...,
4      "outputs": ["dist/libs/mylib", "build/libs/mylib/main.js"],
5      "options": {
6        ...
7      },
8    }
9  }
10

Referencing Options

Most commonly, targets have an option for an output file or directory. Rather than duplicating the information as seen above, options can be referenced using the below syntax:

When the outputPath option is changed, Nx will start caching the new path as well.

1{
2  "build": {
3    ...,
4    "outputs": ["{options.outputPath}"],
5    "options": {
6      "outputPath": "dist/libs/mylib"
7    }
8  }
9}
10

Specifying Globs

Sometimes, multiple targets might write to the same directory. When possible it is recommended to direct these targets into separate directories.

1{
2  "build-js": {
3    ...,
4    "outputs": ["dist/libs/mylib/js"],
5    "options": {
6      "outputPath": "dist/libs/mylib/js"
7    }
8  },
9  "build-css": {
10    ...,
11    "outputs": ["dist/libs/mylib/css"],
12    "options": {
13      "outputPath": "dist/libs/mylib/css"
14    }
15  }
16}
17

But if the above is not possible, globs can be specified as outputs to only cache a set of files rather than the whole directory.

1{
2  "build-js": {
3    ...,
4    "outputs": ["dist/libs/mylib/**/*.js"],
5    "options": {
6      "outputPath": "dist/libs/mylib"
7    }
8  },
9  "build-css": {
10    ...,
11    "outputs": ["dist/libs/mylib/**/*.css"],
12    "options": {
13      "outputPath": "dist/libs/mylib"
14    }
15  }
16}
17

dependsOn

Targets can depend on other targets. This is the relevant portion of the configuration file:

1"build": {
2  "dependsOn": ["^build"]
3},
4"test": {
5  "dependsOn": ["build"]
6}
7

A common scenario is having to build dependencies of a project first before building the project. This is what the "dependsOn": ["^build"] property of the build target configures. It tells Nx that before it can build mylib it needs to make sure that mylib's dependencies are built as well. This doesn't mean Nx is going to rerun those builds. If the right artifacts are already in the right place, Nx will do nothing. If they aren't in the right place, but they are available in the cache, Nx will retrieve them from the cache.

Another common scenario is for a target to depend on another target of the same project. For instance, "dependsOn": ["build"] of the test target tells Nx that before it can test mylib it needs to make sure that mylib is built, which will result in mylib's dependencies being built as well.

You can also express the same configuration using:

1"build": {
2  "dependsOn": [{ "projects": "dependencies", "target": "build" }]
3},
4"test": {
5  "dependsOn": [{ "projects": "self", "target": "build" }]
6}
7

With the expanded syntax, you also have a third option available to configure how to handle the params passed to the target. You can either forward them or you can ignore them (default).

1"build": {
2   // forward params passed to this target to the dependency targets
3  "dependsOn": [{ "projects": "dependencies", "target": "build", "params": "forward" }]
4},
5"test": {
6  // ignore params passed to this target, won't be forwarded to the dependency targets
7  "dependsOn": [{ "projects": "dependencies", "target": "build", "params": "ignore" }]
8}
9"lint": {
10  // ignore params passed to this target, won't be forwarded to the dependency targets
11  "dependsOn": [{ "projects": "dependencies", "target": "build" }]
12}
13

Obviously this also works when defining a relation for the target of the project itself using "projects": "self":

1"build": {
2   // forward params passed to this target to the project target
3  "dependsOn": [{ "projects": "self", "target": "pre-build", "params": "forward" }]
4}
5

This configuration is usually not needed. Nx comes with reasonable defaults (imported in nx.json) which implement the configuration above.

tags

You can annotate your projects with tags as follows:

1{
2  "tags": ["scope:myteam"]
3}
4

You can configure lint rules using these tags to, for instance, ensure that libraries belonging to myteam are not depended on by libraries belong to theirteam.

implicitDependencies

Nx uses powerful source-code analysis to figure out your workspace's project graph. Some dependencies cannot be deduced statically, so you can set them manually like this:

1{
2  "root": "libs/mylib/",
3  "sourceRoot": "libs/mylib/src",
4  "projectType": "library",
5  "targets": {},
6  "implicitDependencies": ["anotherlib"]
7}
8

You can also remove a dependency as follows:

1{
2  "root": "libs/mylib/",
3  "sourceRoot": "libs/mylib/src",
4  "projectType": "library",
5  "targets": {},
6  "implicitDependencies": ["!anotherlib"] # regardless of what Nx thinks, "mylib" doesn't depend on "anotherlib"
7}
8

workspace json

The workspace.json file in the root directory is optional. It's used if you want to list the projects in your workspace explicitly instead of Nx scanning the file tree for all project.json and package.json files.

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

• "version": 2 tells Nx that we are using Nx's format for the workspace.json file.
• projects is a map of project names to their locations.

You could inline project.json files into workspace.json. This used to be the default, but it's no longer recommended. If you have an existing workspace where the configuration is inlined, run nx g convert-to-nx-project --all.

If you have an old workspace where the configuration version is set to 1, change the version number to 2 and run nx format.

CLI Configuration

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    "workspace.json": "*",
12    "package.json": {
13      "dependencies": "*",
14      "devDependencies": "*"
15    },
16    "tsconfig.base.json": "*",
17    "nx.json": "*"
18  },
19  "namedInputs": {
20    "default": ["{projectRoot}/**/*"],
21    "prod": ["!{projectRoot}/**/*.spec.tsx"]
22  },
23  "targetDefaults": {
24    "build": {
25      "inputs": ["prod", "^prod"],
26      "dependsOn": ["^build"]
27    }
28  },
29  "cli": {
30    "defaultCollection": "@nrwl/js"
31  },
32  "generators": {
33    "@nrwl/js:library": {
34      "buildable": true
35    }
36  },
37  "tasksRunnerOptions": {
38    "default": {
39      "runner": "nx/tasks-runners/default",
40      "options": {
41        "cacheableOperations": ["build", "lint", "test", "e2e"]
42      }
43    }
44  }
45}
46

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

In the example above:

• Changing workspace.json affects every project.
• 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    "^prod"
5  ]
6}
7

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

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

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

CLI Options

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

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

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

runtimeCacheInputs are set as follows:

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

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

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

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.

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.