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": ["^build"]
12 },
13 "test": {
14 "outputs": [],
15 "dependsOn": ["build"]
16 }
17 }
18 }
19}
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. This is the relevant portion of the configuration file:
1"build": {
2 "dependsOn": ["^build"]
3},
4"test": {
5 "dependsOn": ["build"]
6}
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}
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 theworkspace.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 "targetDefaults": {
20 "build": {
21 "dependsOn": ["^build"]
22 }
23 },
24 "cli": {
25 "defaultCollection": "@nrwl/js"
26 },
27 "generators": {
28 "@nrwl/js:library": {
29 "buildable": true
30 }
31 },
32 "tasksRunnerOptions": {
33 "default": {
34 "runner": "nx/tasks-runners/default",
35 "options": {
36 "cacheableOperations": ["build", "lint", "test", "e2e"]
37 }
38 }
39 }
40}
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
.
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 inpackage.json
affects every project. - Changing the
mypackage
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
.
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 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 targetDefaults
in nx.json
is helpful.
1{
2 "targetDefaults": {
3 "build": {
4 "dependsOn": ["^build"]
5 }
6 }
7}
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}
Previous versions of Nx (before 14.3.4) supported
targetDependencies
to configure dependencies innx.json
.targetDefaults
is the same mechanism but generalized to support other properties.
CLI Options
The following command generates a new library: nx g @nrwl/js:lib mylib
. After setting the defaultCollection
property,
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 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": "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:
- 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.