Run Root-Level NPM Scripts with Nx
There are often tasks in a codebase that apply to the whole codebase rather than a single project. Starting with version 15.3.0 of Nx, you can run npm scripts directly from the root package.json.
Let's say your root package.json looks like this:
1{
2 "name": "myorg",
3 "scripts": {
4 "docs": "node ./generateDocsSite.js"
5 }
6}
7We want to be able to run the docs script using Nx to get caching and other benefits.
Setup
To make Nx aware of the root package.json scripts, add an "nx": {} property to the root package.json
1{
2 "name": "myorg",
3 "nx": {},
4 "scripts": {
5 "docs": "node ./generateDocsSite.js"
6 }
7}
8Running a Root-Level Target
Once Nx is aware of your root-level scripts, you can run them the same way you would run any other target. Just use the name of your root package.json as the project name, or you can omit the project name and Nx will use the project in the current working directory as the default.
For our example, you would run:
~/myorg❯
nx docs
1> nx run myorg:docs
2
3yarn run v1.22.19
4$ node ./generateDocsSite.js
5Documentation site generated in /docs
6
7 ————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————
8
9 NX Successfully ran target docs for project myorg (5s)
10Configuring a Root-Level Target
You can also configure the inputs and outputs or task pipelines for root-level targets the same way you would for any other target.
Our fully configured example would look like this:
1{
2 "name": "myorg",
3 "nx": {
4 // Nx can't infer the project dependency from the docs script,
5 // so we manually create a dependency on the store app
6 "implicitDependencies": ["store"],
7 "targets": {
8 "docs": {
9 // generates docs from source code of all dependencies
10 "inputs": ["^production"],
11 // the docs site is created under /docs
12 "outputs": ["{workspaceRoot}/docs"]
13 }
14 }
15 },
16 "scripts": {
17 "docs": "node ./generateDocsSite.js"
18 }
19}
20To cache the docs target, you can add docs to the cacheableOperations in nx.json and then your output would look like this:
~/myorg❯
nx docs
1> nx run myorg:docs [existing outputs match the cache, left as is]
2
3yarn run v1.22.19
4$ node ./generateDocsSite.js
5Documentation site generated in /docs
6
7 ————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————
8
9 NX Successfully ran target docs for project myorg (31ms)
10
11 Nx read the output from the cache instead of running the command for 1 out of 1 tasks.
12Read more about cacheableOperations and fine-tuning caching with task inputs.
Keep using NPM to run scripts rather than Nx
You can keep using npm run docs instead of the new npx nx docs version and still leverage the caching. To achieve this you need to wrap your command with nx exec s.t. it can be piped through Nx.
1{
2 "name": "myorg",
3 "nx": {},
4 "scripts": {
5 "docs": "nx exec -- node ./generateDocsSite.js"
6 }
7}
8Read more in the Nx exec docs.