From 31989c4d1e19d54d4c8226989c40b397e56deefd Mon Sep 17 00:00:00 2001 From: Jack Hsu Date: Fri, 28 Jun 2024 11:15:44 -0400 Subject: [PATCH] docs(core): clean-up outdated content from docs and CNW readme (#26748) This PR: 1. Removes the `{{getting-started}}` template string from [CNW README.md](https://www.npmjs.com/package/create-nx-workspace), which was removed before from generation but this file missed an update. 2. Updates docs for `run-scripts` to show `project.json` examples, not `workspace.json` (we link to this from PDV and it's very awkward). 3. Removes unused run-script and run-commands example files from `packages/workspace/docs`. These were moved to `packages/nx/docs` but somehow the old files remained even though they aren't used. 4. Updates host/remotes React generators to mention `nx.json` not `workspace.json`. The option is already renamed `--skipNxJson` but the description does not match. ## Current Behavior ## Expected Behavior ## Related Issue(s) Fixes # --- .../packages/nx/executors/run-commands.json | 2 +- .../packages/nx/executors/run-script.json | 2 +- .../packages/react/generators/host.json | 2 +- .../packages/react/generators/remote.json | 2 +- packages/create-nx-workspace/README.md | 2 - packages/nx/docs/run-commands-examples.md | 14 +- packages/nx/docs/run-script-examples.md | 32 ++-- .../react/src/generators/host/schema.json | 2 +- .../react/src/generators/remote/schema.json | 2 +- .../workspace/docs/run-commands-examples.md | 157 ------------------ .../workspace/docs/run-script-examples.md | 40 ----- 11 files changed, 26 insertions(+), 231 deletions(-) delete mode 100644 packages/workspace/docs/run-commands-examples.md delete mode 100644 packages/workspace/docs/run-script-examples.md diff --git a/docs/generated/packages/nx/executors/run-commands.json b/docs/generated/packages/nx/executors/run-commands.json index ff2a1c424f33d..783ed814baa76 100644 --- a/docs/generated/packages/nx/executors/run-commands.json +++ b/docs/generated/packages/nx/executors/run-commands.json @@ -150,7 +150,7 @@ }, "additionalProperties": true, "oneOf": [{ "required": ["commands"] }, { "required": ["command"] }], - "examplesFile": "`project.json`:\n\n```json\n{\n // ...\n \"targets\": {\n //...\n \"ls-project-root\": {\n \"executor\": \"nx:run-commands\",\n \"options\": {\n \"command\": \"ls apps/frontend/src\"\n }\n }\n }\n}\n```\n\n```bash\nnx run frontend:ls-project-root\n```\n\n## Examples\n\n{% tabs %}\n{% tab label=\"Chaining commands\" %}\n\nThe `commands` option accepts as many commands as you want. By default, they all run in parallel.\nYou can run them sequentially by setting `parallel: false`:\n\n```json\n\"create-script\": {\n \"executor\": \"nx:run-commands\",\n \"options\": {\n \"commands\": [\n \"mkdir -p apps/frontend/scripts\",\n \"touch apps/frontend/scripts/my-script.sh\",\n \"chmod +x apps/frontend/scripts/my-script.sh\"\n ],\n \"parallel\": false\n }\n}\n```\n\n{% /tab %}\n{% tab label=\"Setting the cwd\" %}\n\nBy setting the `cwd` option, each command will run in the `apps/frontend` folder.\n\n```json\n\"create-script\": {\n \"executor\": \"nx:run-commands\",\n \"options\": {\n \"cwd\": \"apps/frontend\",\n \"commands\": [\n \"mkdir -p scripts\",\n \"touch scripts/my-script.sh\",\n \"chmod +x scripts/my-script.sh\"\n ],\n \"parallel\": false\n }\n}\n```\n\n{% /tab %}\n{% tab label=\"Interpolating Args\" %}\n\nYou can use custom arguments in your scripts with `{args.[someFlag]}`:\n\n```json\n\"create-script\": {\n \"executor\": \"nx:run-commands\",\n \"options\": {\n \"cwd\": \"apps/frontend\",\n \"commands\": [\n \"mkdir -p scripts\",\n \"touch scripts/{args.name}.sh\",\n \"chmod +x scripts/{args.name}.sh\"\n ],\n \"parallel\": false\n }\n}\n```\n\nWe run the above with:\n\n```bash\nnx run frontend:create-script --args=\"--name=example\"\n```\n\nor simply with:\n\n```bash\nnx run frontend:create-script --name=example\n```\n\n{% /tab %}\n{% tab label=\"Arguments forwarding\" %}\nWhen interpolation is not present in the command, all arguments are forwarded to the command by default.\n\nThis is useful when you need to pass raw argument strings to your command.\n\nFor example, when you run:\n\n```bash\nnx run frontend:webpack --args=\"--config=example.config.js\"\n```\n\n```json\n\"webpack\": {\n \"executor\": \"nx:run-commands\",\n \"options\": {\n \"command\": \"webpack\"\n }\n}\n```\n\nThe above command will execute: `webpack --config=example.config.js`\n\nThis functionality can be disabled by using `commands` and expanding each `command` into an object\nthat sets the `forwardAllArgs` option to `false` as shown below:\n\n```json\n\"webpack\": {\n \"executor\": \"nx:run-commands\",\n \"options\": {\n \"commands\": [\n {\n \"command\": \"webpack\",\n \"forwardAllArgs\": false\n }\n ]\n }\n}\n```\n\n{% /tab %}\n{% tab label=\"Shorthand\" %}\nWhen you only need to run a single command, you can use a shorthand for nx:run-commands:\n\n```json\n\"webpack\": {\n \"command\": \"webpack\"\n}\n```\n\n{% /tab %}\n{% tab label=\"Custom done conditions\" %}\n\nNormally, `run-commands` considers the commands done when all of them have finished running. If you don't need to wait until they're all done, you can set a special string that considers the commands finished the moment the string appears in `stdout` or `stderr`:\n\n```json\n\"finish-when-ready\": {\n \"executor\": \"nx:run-commands\",\n \"options\": {\n \"commands\": [\n \"sleep 5 && echo 'FINISHED'\",\n \"echo 'READY'\"\n ],\n \"readyWhen\": \"READY\",\n \"parallel\": true\n }\n}\n```\n\n```bash\nnx run frontend:finish-when-ready\n```\n\nThe above commands will finish immediately, instead of waiting for 5 seconds.\n\nWhen we have multiple commands running in parallel, there is a possibility that we want to wait for more than 1 string to appear in stdout or stderr.\nFor example, imagine a case where we are running multiple commands to start multiple dev servers in parallel.\n\n```json\n\"finish-when-multiple-ready\": {\n \"executor\": \"nx:run-commands\",\n \"options\": {\n \"commands\": [\n \"sleep $[ ( $RANDOM % 10 ) + 1 ] && echo 'READY1' && sleep 3600\",\n \"sleep $[ ( $RANDOM % 10 ) + 1 ] && echo 'READY2' && sleep 3600\",\n ],\n \"readyWhen\": [\"READY1\", \"READY2\"],\n \"parallel\": true\n }\n}\n```\n\n```bash\nnx run frontend:finish-when-multiple-ready\n```\n\nThe above commands will finish as soon as both the 1st and the 2nd command echoed \"READY\" (between 1 and 10 seconds), instead of waiting for the extra hour.\n\n{% /tab %}\n{% tab label=\"Nx Affected\" %}\n\nThe true power of `run-commands` comes from the fact that it runs through `nx`, which knows about your project graph. So you can run **custom commands** only for the projects that have been affected by a change.\n\nWe can create some configurations to generate docs, and if run using `nx affected`, it will only generate documentation for the projects that have been changed:\n\n```bash\nnx affected --target=generate-docs\n```\n\n```json\n//...\n\"frontend\": {\n \"targets\": {\n //...\n \"generate-docs\": {\n \"executor\": \"nx:run-commands\",\n \"options\": {\n \"command\": \"npx compodoc -p apps/frontend/tsconfig.app.json\"\n }\n }\n }\n},\n\"api\": {\n \"targets\": {\n //...\n \"generate-docs\": {\n \"executor\": \"nx:run-commands\",\n \"options\": {\n \"command\": \"npx compodoc -p apps/api/tsconfig.app.json\"\n }\n }\n }\n}\n```\n\n{% /tab %}\n{% /tabs %}\n\n---\n" + "examplesFile": "`project.json`:\n\n```json\n{\n // ...\n \"targets\": {\n //...\n \"ls-project-root\": {\n \"executor\": \"nx:run-commands\",\n \"options\": {\n \"command\": \"ls apps/frontend/src\"\n }\n }\n }\n}\n```\n\n```shell\nnx run frontend:ls-project-root\n```\n\n## Examples\n\n{% tabs %}\n{% tab label=\"Chaining commands\" %}\n\nThe `commands` option accepts as many commands as you want. By default, they all run in parallel.\nYou can run them sequentially by setting `parallel: false`:\n\n```json\n\"create-script\": {\n \"executor\": \"nx:run-commands\",\n \"options\": {\n \"commands\": [\n \"mkdir -p apps/frontend/scripts\",\n \"touch apps/frontend/scripts/my-script.sh\",\n \"chmod +x apps/frontend/scripts/my-script.sh\"\n ],\n \"parallel\": false\n }\n}\n```\n\n{% /tab %}\n{% tab label=\"Setting the cwd\" %}\n\nBy setting the `cwd` option, each command will run in the `apps/frontend` folder.\n\n```json\n\"create-script\": {\n \"executor\": \"nx:run-commands\",\n \"options\": {\n \"cwd\": \"apps/frontend\",\n \"commands\": [\n \"mkdir -p scripts\",\n \"touch scripts/my-script.sh\",\n \"chmod +x scripts/my-script.sh\"\n ],\n \"parallel\": false\n }\n}\n```\n\n{% /tab %}\n{% tab label=\"Interpolating Args\" %}\n\nYou can use custom arguments in your scripts with `{args.[someFlag]}`:\n\n```json\n\"create-script\": {\n \"executor\": \"nx:run-commands\",\n \"options\": {\n \"cwd\": \"apps/frontend\",\n \"commands\": [\n \"mkdir -p scripts\",\n \"touch scripts/{args.name}.sh\",\n \"chmod +x scripts/{args.name}.sh\"\n ],\n \"parallel\": false\n }\n}\n```\n\nWe run the above with:\n\n```shell\nnx run frontend:create-script --args=\"--name=example\"\n```\n\nor simply with:\n\n```shell\nnx run frontend:create-script --name=example\n```\n\n{% /tab %}\n{% tab label=\"Arguments forwarding\" %}\nWhen interpolation is not present in the command, all arguments are forwarded to the command by default.\n\nThis is useful when you need to pass raw argument strings to your command.\n\nFor example, when you run:\n\n```shell\nnx run frontend:webpack --args=\"--config=example.config.js\"\n```\n\n```json\n\"webpack\": {\n \"executor\": \"nx:run-commands\",\n \"options\": {\n \"command\": \"webpack\"\n }\n}\n```\n\nThe above command will execute: `webpack --config=example.config.js`\n\nThis functionality can be disabled by using `commands` and expanding each `command` into an object\nthat sets the `forwardAllArgs` option to `false` as shown below:\n\n```json\n\"webpack\": {\n \"executor\": \"nx:run-commands\",\n \"options\": {\n \"commands\": [\n {\n \"command\": \"webpack\",\n \"forwardAllArgs\": false\n }\n ]\n }\n}\n```\n\n{% /tab %}\n{% tab label=\"Shorthand\" %}\nWhen you only need to run a single command, you can use a shorthand for nx:run-commands:\n\n```json\n\"webpack\": {\n \"command\": \"webpack\"\n}\n```\n\n{% /tab %}\n{% tab label=\"Custom done conditions\" %}\n\nNormally, `run-commands` considers the commands done when all of them have finished running. If you don't need to wait until they're all done, you can set a special string that considers the commands finished the moment the string appears in `stdout` or `stderr`:\n\n```json\n\"finish-when-ready\": {\n \"executor\": \"nx:run-commands\",\n \"options\": {\n \"commands\": [\n \"sleep 5 && echo 'FINISHED'\",\n \"echo 'READY'\"\n ],\n \"readyWhen\": \"READY\",\n \"parallel\": true\n }\n}\n```\n\n```shell\nnx run frontend:finish-when-ready\n```\n\nThe above commands will finish immediately, instead of waiting for 5 seconds.\n\nWhen we have multiple commands running in parallel, there is a possibility that we want to wait for more than 1 string to appear in stdout or stderr.\nFor example, imagine a case where we are running multiple commands to start multiple dev servers in parallel.\n\n```json\n\"finish-when-multiple-ready\": {\n \"executor\": \"nx:run-commands\",\n \"options\": {\n \"commands\": [\n \"sleep $[ ( $RANDOM % 10 ) + 1 ] && echo 'READY1' && sleep 3600\",\n \"sleep $[ ( $RANDOM % 10 ) + 1 ] && echo 'READY2' && sleep 3600\",\n ],\n \"readyWhen\": [\"READY1\", \"READY2\"],\n \"parallel\": true\n }\n}\n```\n\n```shell\nnx run frontend:finish-when-multiple-ready\n```\n\nThe above commands will finish as soon as both the 1st and the 2nd command echoed \"READY\" (between 1 and 10 seconds), instead of waiting for the extra hour.\n\n{% /tab %}\n{% tab label=\"Nx Affected\" %}\n\nThe true power of `run-commands` comes from the fact that it runs through `nx`, which knows about your project graph. So you can run **custom commands** only for the projects that have been affected by a change.\n\nWe can create some configurations to generate docs, and if run using `nx affected`, it will only generate documentation for the projects that have been changed:\n\n```shell\nnx affected --target=generate-docs\n```\n\n```json\n//...\n\"frontend\": {\n \"targets\": {\n //...\n \"generate-docs\": {\n \"executor\": \"nx:run-commands\",\n \"options\": {\n \"command\": \"npx compodoc -p apps/frontend/tsconfig.app.json\"\n }\n }\n }\n},\n\"api\": {\n \"targets\": {\n //...\n \"generate-docs\": {\n \"executor\": \"nx:run-commands\",\n \"options\": {\n \"command\": \"npx compodoc -p apps/api/tsconfig.app.json\"\n }\n }\n }\n}\n```\n\n{% /tab %}\n{% /tabs %}\n\n---\n" }, "description": "Run any custom commands with Nx.", "aliases": [], diff --git a/docs/generated/packages/nx/executors/run-script.json b/docs/generated/packages/nx/executors/run-script.json index 04ba275016d75..03b0c93ed7b79 100644 --- a/docs/generated/packages/nx/executors/run-script.json +++ b/docs/generated/packages/nx/executors/run-script.json @@ -23,7 +23,7 @@ }, "additionalProperties": true, "required": ["script"], - "examplesFile": "`workspace.json`:\n\n```json\n\"frontend\": {\n \"root\": \"packages/frontend\",\n \"targets\": {\n \"build\": {\n \"executor\": \"nx:run-script\",\n \"options\": {\n \"script\": \"build-my-project\"\n }\n }\n }\n}\n```\n\n```bash\nnx run frontend:build\n```\n\nThe `build` target is going to run `npm run build-my-project` (or `yarn build-my-project`) in the `packages/frontend` directory.\n\n#### Caching Artifacts\n\nBy default, Nx is going to cache `dist/packages/frontend`, `packages/frontend/dist`, `packages/frontend/build`, `packages/frontend/public`. If your npm script writes files to other places, you can override the list of cached outputs as follows:\n\n```json\n\"frontend\": {\n \"root\": \"packages/frontend\",\n \"targets\": {\n \"build\": {\n \"executor\": \"nx:run-script\",\n \"outputs\": [\"{projectRoot}/dist\", \"{projectRoot}/docs\"],\n \"options\": {\n \"script\": \"build-my-project\"\n }\n }\n }\n}\n```\n", + "examplesFile": "`project.json`:\n\n```json\n\"targets\": {\n \"build\": {\n \"executor\": \"nx:run-script\",\n \"options\": {\n \"script\": \"build-my-project\"\n }\n }\n}\n```\n\n```shell\nnx run frontend:build\n```\n\nThe `build` target is going to run `npm run build-my-project` (or `yarn build-my-project`) in the `packages/frontend` directory.\n\n#### Caching Artifacts\n\nBy default, Nx is going to cache `dist/packages/frontend`, `packages/frontend/dist`, `packages/frontend/build`, `packages/frontend/public`. If your npm script writes files to other places, you can override the list of cached outputs as follows:\n\n```json\n\"targets\": {\n \"build\": {\n \"executor\": \"nx:run-script\",\n \"outputs\": [\"{projectRoot}/dist\", \"{projectRoot}/docs\"],\n \"options\": {\n \"script\": \"build-my-project\"\n }\n }\n}\n```\n", "presets": [] }, "description": "Run an NPM script using Nx.", diff --git a/docs/generated/packages/react/generators/host.json b/docs/generated/packages/react/generators/host.json index c667bcbdab827..700e419c6b577 100644 --- a/docs/generated/packages/react/generators/host.json +++ b/docs/generated/packages/react/generators/host.json @@ -84,7 +84,7 @@ "x-priority": "internal" }, "skipNxJson": { - "description": "Skip updating workspace.json with default options based on values provided to this app (e.g. babel, style).", + "description": "Skip updating nx.json with default options based on values provided to this app (e.g. babel, style).", "type": "boolean", "default": false, "x-priority": "internal" diff --git a/docs/generated/packages/react/generators/remote.json b/docs/generated/packages/react/generators/remote.json index d3a8a47e656ac..2ebdb978c46f7 100644 --- a/docs/generated/packages/react/generators/remote.json +++ b/docs/generated/packages/react/generators/remote.json @@ -90,7 +90,7 @@ "x-priority": "internal" }, "skipNxJson": { - "description": "Skip updating workspace.json with default options based on values provided to this app (e.g. babel, style).", + "description": "Skip updating nx.json with default options based on values provided to this app (e.g. babel, style).", "type": "boolean", "default": false, "x-priority": "internal" diff --git a/packages/create-nx-workspace/README.md b/packages/create-nx-workspace/README.md index 571c8ab00189d..f0a13fbd74ec8 100644 --- a/packages/create-nx-workspace/README.md +++ b/packages/create-nx-workspace/README.md @@ -13,8 +13,6 @@ Nx is a build system with built-in tooling and advanced CI capabilities. It helps you maintain and scale monorepos, both locally and on CI. -{{getting-started}} - ## What is It? It's a command to create a new Nx workspace. diff --git a/packages/nx/docs/run-commands-examples.md b/packages/nx/docs/run-commands-examples.md index 46c8866270073..21ee6087360dc 100644 --- a/packages/nx/docs/run-commands-examples.md +++ b/packages/nx/docs/run-commands-examples.md @@ -15,7 +15,7 @@ } ``` -```bash +```shell nx run frontend:ls-project-root ``` @@ -83,13 +83,13 @@ You can use custom arguments in your scripts with `{args.[someFlag]}`: We run the above with: -```bash +```shell nx run frontend:create-script --args="--name=example" ``` or simply with: -```bash +```shell nx run frontend:create-script --name=example ``` @@ -101,7 +101,7 @@ This is useful when you need to pass raw argument strings to your command. For example, when you run: -```bash +```shell nx run frontend:webpack --args="--config=example.config.js" ``` @@ -162,7 +162,7 @@ Normally, `run-commands` considers the commands done when all of them have finis } ``` -```bash +```shell nx run frontend:finish-when-ready ``` @@ -185,7 +185,7 @@ For example, imagine a case where we are running multiple commands to start mult } ``` -```bash +```shell nx run frontend:finish-when-multiple-ready ``` @@ -198,7 +198,7 @@ The true power of `run-commands` comes from the fact that it runs through `nx`, We can create some configurations to generate docs, and if run using `nx affected`, it will only generate documentation for the projects that have been changed: -```bash +```shell nx affected --target=generate-docs ``` diff --git a/packages/nx/docs/run-script-examples.md b/packages/nx/docs/run-script-examples.md index 9b33160d50211..515e3b0b3a914 100644 --- a/packages/nx/docs/run-script-examples.md +++ b/packages/nx/docs/run-script-examples.md @@ -1,20 +1,17 @@ -`workspace.json`: +`project.json`: ```json -"frontend": { - "root": "packages/frontend", - "targets": { - "build": { - "executor": "nx:run-script", - "options": { - "script": "build-my-project" - } +"targets": { + "build": { + "executor": "nx:run-script", + "options": { + "script": "build-my-project" } } } ``` -```bash +```shell nx run frontend:build ``` @@ -25,15 +22,12 @@ The `build` target is going to run `npm run build-my-project` (or `yarn build-my By default, Nx is going to cache `dist/packages/frontend`, `packages/frontend/dist`, `packages/frontend/build`, `packages/frontend/public`. If your npm script writes files to other places, you can override the list of cached outputs as follows: ```json -"frontend": { - "root": "packages/frontend", - "targets": { - "build": { - "executor": "nx:run-script", - "outputs": ["{projectRoot}/dist", "{projectRoot}/docs"], - "options": { - "script": "build-my-project" - } +"targets": { + "build": { + "executor": "nx:run-script", + "outputs": ["{projectRoot}/dist", "{projectRoot}/docs"], + "options": { + "script": "build-my-project" } } } diff --git a/packages/react/src/generators/host/schema.json b/packages/react/src/generators/host/schema.json index 5ba715d29202f..48b91cd1d670a 100644 --- a/packages/react/src/generators/host/schema.json +++ b/packages/react/src/generators/host/schema.json @@ -90,7 +90,7 @@ "x-priority": "internal" }, "skipNxJson": { - "description": "Skip updating workspace.json with default options based on values provided to this app (e.g. babel, style).", + "description": "Skip updating nx.json with default options based on values provided to this app (e.g. babel, style).", "type": "boolean", "default": false, "x-priority": "internal" diff --git a/packages/react/src/generators/remote/schema.json b/packages/react/src/generators/remote/schema.json index 2da45f3480fcc..b0e22410ca61d 100644 --- a/packages/react/src/generators/remote/schema.json +++ b/packages/react/src/generators/remote/schema.json @@ -96,7 +96,7 @@ "x-priority": "internal" }, "skipNxJson": { - "description": "Skip updating workspace.json with default options based on values provided to this app (e.g. babel, style).", + "description": "Skip updating nx.json with default options based on values provided to this app (e.g. babel, style).", "type": "boolean", "default": false, "x-priority": "internal" diff --git a/packages/workspace/docs/run-commands-examples.md b/packages/workspace/docs/run-commands-examples.md deleted file mode 100644 index 41d43eeff62e4..0000000000000 --- a/packages/workspace/docs/run-commands-examples.md +++ /dev/null @@ -1,157 +0,0 @@ -`workspace.json`: - -```json -//... -"frontend": { - "targets": { - //... - "ls-project-root": { - "executor": "nx:run-commands", - "options": { - "command": "ls apps/frontend/src" - } - } - } -} -``` - -```bash -nx run frontend:ls-project-root -``` - -##### Chaining commands, interpolating args and setting the cwd - -Let's say each of our workspace projects has some custom bash scripts in a `scripts` folder. -We want a simple way to create empty bash script files for a given project, that have the execute permissions already set. - -Given that Nx knows our workspace structure, we should be able to give it a project and the name of our script, and it should take care of the rest. - -The `commands` option accepts as many commands as you want. By default, they all run in parallel. -You can run them sequentially by setting `parallel: false`: - -```json -"create-script": { - "executor": "nx:run-commands", - "options": { - "commands": [ - "mkdir -p scripts", - "touch scripts/{args.name}.sh", - "chmod +x scripts/{args.name}.sh" - ], - "cwd": "apps/frontend", - "parallel": false - } -} -``` - -By setting the `cwd` option, each command will run in the `apps/frontend` folder. - -We run the above with: - -```bash -nx run frontend:create-script --args="--name=example" -``` - -or simply with: - -```bash -nx run frontend:create-script --name=example -``` - -##### Arguments forwarding - -When interpolation is not present in the command, all arguments are forwarded to the command by default. - -This is useful when you need to pass raw argument strings to your command. - -For example, when you run: - -nx run frontend:webpack --args="--config=example.config.js" - -```json -"webpack": { - "executor": "nx:run-commands", - "options": { - "command": "webpack" - } -} -``` - -The above command will execute: `webpack --config=example.config.js` - -This functionality can be disabled by using `commands` and expanding each `command` into an object -that sets the `forwardAllArgs` option to `false` as shown below: - -```json -"webpack": { - "executor": "nx:run-commands", - "options": { - "commands": [ - { - "command": "webpack", - "forwardAllArgs": false - } - ] - } -} -``` - -##### Custom **done** conditions - -Normally, `run-commands` considers the commands done when all of them have finished running. If you don't need to wait until they're all done, you can set a special string that considers the commands finished the moment the string appears in `stdout` or `stderr`: - -```json -"finish-when-ready": { - "executor": "nx:run-commands", - "options": { - "commands": [ - "sleep 5 && echo 'FINISHED'", - "echo 'READY'" - ], - "readyWhen": "READY", - "parallel": true - } -} -``` - -```bash -nx run frontend:finish-when-ready -``` - -The above commands will finish immediately, instead of waiting for 5 seconds. - -##### Nx Affected - -The true power of `run-commands` comes from the fact that it runs through `nx`, which knows about your project graph. So you can run **custom commands** only for the projects that have been affected by a change. - -We can create some configurations to generate docs, and if run using `nx affected`, it will only generate documentation for the projects that have been changed: - -```bash -nx affected --target=generate-docs -``` - -```json -//... -"frontend": { - "targets": { - //... - "generate-docs": { - "executor": "nx:run-commands", - "options": { - "command": "npx compodoc -p apps/frontend/tsconfig.app.json" - } - } - } -}, -"api": { - "targets": { - //... - "generate-docs": { - "executor": "nx:run-commands", - "options": { - "command": "npx compodoc -p apps/api/tsconfig.app.json" - } - } - } -} -``` diff --git a/packages/workspace/docs/run-script-examples.md b/packages/workspace/docs/run-script-examples.md deleted file mode 100644 index 9b33160d50211..0000000000000 --- a/packages/workspace/docs/run-script-examples.md +++ /dev/null @@ -1,40 +0,0 @@ -`workspace.json`: - -```json -"frontend": { - "root": "packages/frontend", - "targets": { - "build": { - "executor": "nx:run-script", - "options": { - "script": "build-my-project" - } - } - } -} -``` - -```bash -nx run frontend:build -``` - -The `build` target is going to run `npm run build-my-project` (or `yarn build-my-project`) in the `packages/frontend` directory. - -#### Caching Artifacts - -By default, Nx is going to cache `dist/packages/frontend`, `packages/frontend/dist`, `packages/frontend/build`, `packages/frontend/public`. If your npm script writes files to other places, you can override the list of cached outputs as follows: - -```json -"frontend": { - "root": "packages/frontend", - "targets": { - "build": { - "executor": "nx:run-script", - "outputs": ["{projectRoot}/dist", "{projectRoot}/docs"], - "options": { - "script": "build-my-project" - } - } - } -} -```