diff --git a/docs/map.json b/docs/map.json index 5f0f18db647ba..74358dca2cbc7 100644 --- a/docs/map.json +++ b/docs/map.json @@ -959,20 +959,24 @@ "id": "other", "description": "Other recipes you will find useful.", "itemList": [ + { + "name": "Run Root-Level NPM Scripts with Nx", + "id": "root-level-scripts", + "tags": ["run-tasks"], + "file": "shared/recipes/root-level-scripts" + }, { "name": "Disable Graph Links Created from Analyzing Source Files", "id": "analyze-source-files", "tags": ["explore-graph"], "file": "shared/recipes/analyze-source-files" }, - { "name": "Advanced Update Nx", "id": "advanced-update", "tags": ["automate-updating-dependencies"], "file": "shared/recipes/advanced-update" }, - { "name": "JavaScript and TypeScript", "id": "js-and-ts", diff --git a/docs/shared/recipes/root-level-scripts.md b/docs/shared/recipes/root-level-scripts.md new file mode 100644 index 0000000000000..07cb5adcb1c4c --- /dev/null +++ b/docs/shared/recipes/root-level-scripts.md @@ -0,0 +1,94 @@ +# 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: + +```json {% fileName="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` + +```json {% fileName="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: + +```{% command="nx docs" path="~/myorg" %} +> 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: + +```jsonc {% fileName="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 + "outpus": ["{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: + +```{% command="nx docs" path="~/myorg" %} +> 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. +```