From ef8986df471d4e139f604dd152b9e8975596fddc Mon Sep 17 00:00:00 2001 From: Isaac Mann Date: Fri, 7 Jan 2022 23:01:40 -0500 Subject: [PATCH] docs(nxdev): updates --- docs/shared/configuration/packagejson.md | 18 ++++++++---------- docs/shared/configuration/projectjson.md | 24 +++++++++++++++--------- docs/shared/using-nx/nx-cli.md | 4 ++-- 3 files changed, 25 insertions(+), 21 deletions(-) diff --git a/docs/shared/configuration/packagejson.md b/docs/shared/configuration/packagejson.md index 36cef2331d..7b8b8b03d8 100644 --- a/docs/shared/configuration/packagejson.md +++ b/docs/shared/configuration/packagejson.md @@ -3,7 +3,7 @@ There are two main types of configuration in every Nx workspace: [project configuration](#project-configuration) and [the global Nx CLI configuration](#cli-configuration). -Projects can be configured in `package.json` (if you use npm scripts and not Nx executors) and `project.json` (when you +Projects can be configured in `package.json` (if you use npm scripts and not Nx executors) and `project.json` (if you use Nx executors). Both `package.json` and `project.json` files are located in each project's folder. Nx merges the two files to get each project's configuration. This guide covers the `package.json` case. @@ -62,7 +62,7 @@ You can add Nx-specific configuration as follows: is actually the default, so we can omit it in this case. `"outputs": []` tells Nx that the `test` target doesn't create any artifacts on disk. -This configuration is actually not needed. Nx comes with reasonable defaults (imported in `nx.json`) which implement the +This configuration is usually not needed. Nx comes with reasonable defaults (imported in `nx.json`) which implement the configuration above. ### dependsOn @@ -72,14 +72,14 @@ Targets can depend on other targets. A common scenario is having to build dependencies of a project first before building the project. This is what the `dependsOn` property of the `build` target configures. It tells Nx that before it can build `mylib` it needs to make sure that `mylib`'s dependencies are built as well. This doesn't mean Nx is going to rerun those builds. If the right -artifacts are already in the right place, Nx will do nothing. If they aren't in the right place, but there are available -in cache, Nx will retrieve them from the cache. +artifacts are already in the right place, Nx will do nothing. If they aren't in the right place, but they are available +in the cache, Nx will retrieve them from the cache. Another common scenario is for a target to depend on another target of the same project. For instance, `dependsOn` of the `test` target tells Nx that before it can test `mylib` it needs to make sure that `mylib` is built, which will result in `mylib`'s dependencies being built as well. -This configuration is actually not needed. Nx comes with reasonable defaults (imported in `nx.json`) which implement the +This configuration is usually not needed. Nx comes with reasonable defaults (imported in `nx.json`) which implement the configuration above. ### tags @@ -95,8 +95,7 @@ You can annotate your projects with `tags` as follows: } ``` -Nx uses tags for linting to, for instance, ensure that private libraries aren't depended on by the team who don't own -them. +You can [configure lint rules using these tags](/structure/monorepo-tags) to, for instance, ensure that libraries belonging to `myteam` are not depended on by libraries belong to `theirteam`. ### implicitDependencies @@ -128,8 +127,7 @@ project, add the following to its `package.json`: ### workspace json -The `workspace.json` is optional. It's used if you want to list the projects in your workspace explicitly instead of Nx -scanning the file tree for all `project.json` and `package.json` files. +The `workspace.json` file in the root directory is optional. It's used if you want to list the projects in your workspace explicitly instead of Nx scanning the file tree for all `project.json` and `package.json` files. ```json { @@ -283,7 +281,7 @@ every build target of every project. ### CLI Options The following command generates a new library: `nx g @nrwl/js:lib mylib`. After setting the `defaultCollection`property, -the lib is generated without mentioning the collection name: `nx g lib mylib`. +the lib is generated without mentioning the plugin name: `nx g lib mylib`. ```json { diff --git a/docs/shared/configuration/projectjson.md b/docs/shared/configuration/projectjson.md index 7c90cb9226..9053f4022a 100644 --- a/docs/shared/configuration/projectjson.md +++ b/docs/shared/configuration/projectjson.md @@ -3,7 +3,7 @@ There are two main types of configuration in every Nx workspace: [project configuration](#project-configuration) and [the global Nx CLI configuration](#cli-configuration). -Projects can be configured in `package.json` (if you use npm scripts and not Nx executors) and `project.json` (when you +Projects can be configured in `package.json` (if you use npm scripts and not Nx executors) and `project.json` (if you use Nx executors). Both `package.json` and `project.json` files are located in each project's folder. Nx merges the two files to get each project's configuration. This guide covers the `project.json` case. @@ -149,7 +149,7 @@ The `configurations` property provides extra sets of values that will be merged You can select a configuration like this: `nx build mylib --configuration=production` or `nx run mylib:build:configuration=production`. -The following show how the executor options get constructed: +The following code snippet shows how the executor options get constructed: ```javascript require(`@nrwl/jest`).executors['jest']({ ...options, ...selectedConfiguration, ...commandLineArgs } @@ -172,20 +172,27 @@ Targets can depend on other targets. A common scenario is having to build dependencies of a project first before building the project. This is what the `dependsOn` property of the `build` target configures. It tells Nx that before it can build `mylib` it needs to make sure that `mylib`'s dependencies are built as well. This doesn't mean Nx is going to rerun those builds. If the right -artifacts are already in the right place, Nx will do nothing. If they aren't in the right place, but there are available -in cache, Nx will retrieve them from the cache. +artifacts are already in the right place, Nx will do nothing. If they aren't in the right place, but they are available +in the cache, Nx will retrieve them from the cache. Another common scenario is for a target to depend on another target of the same project. For instance, `dependsOn` of the `test` target tells Nx that before it can test `mylib` it needs to make sure that `mylib` is built, which will result in `mylib`'s dependencies being built as well. -This configuration is actually not needed. Nx comes with reasonable defaults (imported in `nx.json`) which implement the +This configuration is usually not needed. Nx comes with reasonable defaults (imported in `nx.json`) which implement the configuration above. ### tags -Nx uses tags for linting to, for instance, ensure that private libraries aren't depended on by the team who don't own -them. +You can annotate your projects with `tags` as follows: + +```jsonc +{ + "tags": ["scope:myteam"] +} +``` + +You can [configure lint rules using these tags](/structure/monorepo-tags) to, for instance, ensure that libraries belonging to `myteam` are not depended on by libraries belong to `theirteam`. ### implicitDependencies @@ -204,8 +211,7 @@ statically, so you can set them manually like this: ### workspace json -The `workspace.json` is optional. It's used if you want to list the projects in your workspace explicitly instead of Nx -scanning the file tree for all `project.json` and `package.json` files. +The `workspace.json` file in the root directory is optional. It's used if you want to list the projects in your workspace explicitly instead of Nx scanning the file tree for all `project.json` and `package.json` files. ```json { diff --git a/docs/shared/using-nx/nx-cli.md b/docs/shared/using-nx/nx-cli.md index ca97461e9f..a38978faba 100644 --- a/docs/shared/using-nx/nx-cli.md +++ b/docs/shared/using-nx/nx-cli.md @@ -63,7 +63,7 @@ Again, like `nx run`, `nx generate` is only an abstraction over generating code. want via **generators**. **[Generators](/generators/using-schematics)** can be installed as part of a plugin or developed locally within an Nx workspace to fit the needs of your organization. -A [Workspace Generator](/generators/workspace-generators) is custom generator for your +A [Workspace Generator](/generators/workspace-generators) is a custom generator for your workspace. `nx generate workspace-generator my-generator` generates a workspace generator which can be run with the [`nx workspace-generator` command](/cli/workspace-generator). This can be useful to allow your organization to consistently generate projects according to your own standards. @@ -86,7 +86,7 @@ nx migrate --run-migrations # Runs the migrations scheduled by the previous comm Nx creates and maintains a dependency graph between projects based on import statements in your code and uses that information to run executors only on the [affected](/cli/affected) projects in a codebase. A visual -version of the [dependency graph](/structure/dependency-graph) is also available to help developers +version of the [project dependency graph](/structure/dependency-graph) is also available to help developers understand the architecture of the codebase. The [`nx dep-graph` command](/cli/dep-graph) displays this dependency graph in a web browser for you to