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. With version 15.3.0 of Nx, you can run npm scripts directly from the root package.json.

Example

Let's say your root package.json looks like this:

package.json
{
  "name": "myorg",
  "scripts": {
    "docs": "node ./generateDocsSite.js"
  }
}

We want to be able to run the docs script using Nx.

Setup

To make Nx aware of the root package.json scripts, add an "nx": {} property to the root package.json

package.json
{
  "name": "myorg",
  "nx": {},
  "scripts": {
    "docs": "node ./generateDocsSite.js"
  }
}

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

Terminal

~/myorg❯

nx docs

> nx run myorg:docs

yarn run v1.22.19
$ node ./generateDocsSite.js
Documentation site generated in /docs

 ————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

 >  NX   Successfully ran target docs for project myorg (5s)

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

package.json
{
  "name": "myorg",
  "nx": {
    // Nx can't infer the project dependency from the docs script,
    // so we manually create a dependency on the store app
    "implicitDependencies": ["store"],
    "targets": {
      "docs": {
        // generates docs from source code of all dependencies
        "inputs": ["^production"],
        // the docs site is created under /docs
        "outputs": ["{workspaceRoot}/docs"]
      }
    }
  },
  "scripts": {
    "docs": "node ./generateDocsSite.js"
  }
}

To cache the docs target, you can add docs to the cacheableOperations in nx.json and then your output would look like this:

Terminal

~/myorg❯

nx docs

> nx run myorg:docs  [existing outputs match the cache, left as is]

yarn run v1.22.19
$ node ./generateDocsSite.js
Documentation site generated in /docs

 ————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

 >  NX   Successfully ran target docs for project myorg (31ms)

   Nx read the output from the cache instead of running the command for 1 out of 1 tasks.

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

package.json
{
  "name": "myorg",
  "nx": {},
  "scripts": {
    "docs": "nx exec -- node ./generateDocsSite.js"
  }
}