Configuration: package.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 package.json case.

Project Configuration

Every npm script defined in package.json is a target you can invoke via Nx. For instance, if your project has the following package.json:

1{
2  "name": "mylib",
3  "scripts": {
4    "test": "jest",
5    "build": "tsc -p tsconfig.lib.json" // the actual command here is arbitrary
6  }
7}

you can invoke nx build mylib or nx test mylib without any extra configuration.

You can add Nx-specific configuration as follows:

1{
2  "name": "mylib",
3  "scripts": {
4    "test: "jest",
5    "build": "tsc -p tsconfig.lib.json" // the actual command here is arbitrary
6  },
7  "nx": {
8    "targets": {
9      "build": {
10        "outputs": ["dist/libs/mylib"],
11        "dependsOn": [
12          {
13            "target": "build",
14            "projects": "dependencies"
15          }
16        ]
17      },
18      "test": {
19        "outputs": [],
20        "dependsOn": [
21          {
22            "target": "build",
23            "projects": "self"
24          }
25        ]
26      }
27    }
28  }
29}

outputs

"outputs": ["dist/libs/mylib"] tells Nx where the build target is going to create file artifacts. The provided value is actually the default, so we can omit it in this case. "outputs": [] tells Nx that the test target doesn't create any artifacts on disk.

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

dependsOn

Targets can depend on other targets.

A common scenario is having to build dependencies of a project first before building the project. This is what the dependsOn 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.

Depending on another target of the same project is very common. That's why we provide some syntax sugar, so "dependsOn": [{"target": "build", "projects": "self"}] can be shortened to "dependsOn": ["build"].

Another common scenario is for a target to depend on another target of the same project. For instance, dependsOn 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.

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  "name": "mylib",
3  "nx": {
4    "tags": ["scope:myteam"]
5  }
6}

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  "name": "mylib",
3  "nx": {
4    "implicitDependencies": ["anotherlib"]
5  }
6}

You can also remove a dependency as follows:

1{
2  "name": "mylib",
3  "nx": {
4    "implicitDependencies": ["!anotherlib"] # regardless of what Nx thinks, "mylib" doesn't depend on "anotherlib"
5  }
6}

Ignoring a project

Nx will add every project with a package.json file in it to its project graph. If you want to ignore a particular project, add the following to its package.json:

1{
2  "name": "mylib",
3  "nx": {
4    "ignore": true
5  }
6}

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 that match the globs specified in the workspaces property of the root package.json.

1{
2  "version": 2,
3  "projects": {
4    "myapp": "apps/myapp"
5  }
6}
  • "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.

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  "targetDependencies": {
20    "build": [
21      {
22        "target": "build",
23        "projects": "dependencies"
24      }
25    ]
26  },
27  "cli": {
28    "defaultCollection": "@nrwl/js"
29  },
30  "generators": {
31    "@nrwl/js:library": {
32      "buildable": true
33    }
34  },
35  "tasksRunnerOptions": {
36    "default": {
37      "runner": "nx/tasks-runners/default",
38      "options": {
39        "cacheableOperations": ["build", "lint", "test", "e2e"]
40      }
41    }
42  }
43}

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}

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}

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.

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 package.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 of every project.

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 plugin name: nx g lib mylib.

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

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}

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

  • 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": "nx/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 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.