miel.truyen/nx
1
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity

docs(core): clean-up outdated content from docs and CNW readme (#26748)

Browse Source 
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.

<!-- If this is a particularly complex change or feature addition, you
can request a dedicated Nx release for this pull request branch. Mention
someone from the Nx team or the `@nrwl/nx-pipelines-reviewers` and they
will confirm if the PR warrants its own release for testing purposes,
and generate it for you if appropriate. -->

## Current Behavior
<!-- This is the behavior we have today -->

## Expected Behavior
<!-- This is the behavior we should expect with the changes in this PR
-->

## Related Issue(s)
<!-- Please link the issue being fixed so it gets closed when this is
merged. -->

Fixes #
This commit is contained in:
Jack Hsu 2024-06-28 11:15:44 -04:00 committed by GitHub
parent 412dade3b7
commit 31989c4d1e
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
11 changed files with 26 additions and 231 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/generated/packages/nx/executors/run-commands.json
View File

File diff suppressed because one or more lines are too long

2
docs/generated/packages/nx/executors/run-script.json
View File

@ -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.",

2
docs/generated/packages/react/generators/host.json
View File

@ -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"

2
docs/generated/packages/react/generators/remote.json
View File

@ -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"

2
packages/create-nx-workspace/README.md
View File

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

14
packages/nx/docs/run-commands-examples.md
View File

@ -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
```

32
packages/nx/docs/run-script-examples.md
View File

@ -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"
}
}
}

2
packages/react/src/generators/host/schema.json
View File

@ -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"

2
packages/react/src/generators/remote/schema.json
View File

@ -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"

157
packages/workspace/docs/run-commands-examples.md
View File

@ -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"
}
}
}
}
```

40
packages/workspace/docs/run-script-examples.md
View File

@ -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"
}
}
}
}
```