From 3a99403aaa46bceab5845bfd4e817e8381f00bbc Mon Sep 17 00:00:00 2001 From: Victor Savkin Date: Thu, 6 Jan 2022 13:08:37 -0500 Subject: [PATCH] docs(misc): minor changes in configuration guides --- .circleci/config.yml | 21 +- docs/map.json | 12 +- docs/shared/configuration/angularjson.md | 473 ------------------ docs/shared/configuration/projectjson.md | 3 + docs/shared/getting-started/nx-and-angular.md | 10 +- .../public/documentation/latest/map.json | 12 +- .../shared/configuration/angularjson.md | 473 ------------------ .../shared/configuration/projectjson.md | 3 + .../shared/getting-started/nx-and-angular.md | 10 +- 9 files changed, 24 insertions(+), 993 deletions(-) delete mode 100644 docs/shared/configuration/angularjson.md delete mode 100644 nx-dev/nx-dev/public/documentation/latest/shared/configuration/angularjson.md diff --git a/.circleci/config.yml b/.circleci/config.yml index eeb24267d518ad..ea75302233f1f4 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -171,23 +171,10 @@ jobs: os: linux - nx/set-shas: main-branch-name: 'master' - - run: - name: Check repository - command: | - pids=() - - yarn check-imports & - pids+=($!) - yarn nx format:check --base=$NX_BASE --head=$NX_HEAD & - pids+=($!) - yarn check-commit & - pids+=($!) - yarn depcheck & - pids+=($!) - - for pid in "${pids[@]}"; do - wait "$pid" - done + - run: yarn check-imports + - run: yarn nx format:check --base=$NX_BASE --head=$NX_HEAD + - run: yarn check-commit + - run: yarn depcheck - run: name: Check Documentation command: yarn documentation diff --git a/docs/map.json b/docs/map.json index 2e4300055d337f..5cbb4f8702d7a1 100644 --- a/docs/map.json +++ b/docs/map.json @@ -45,7 +45,7 @@ ] }, { - "name": "Configuration", + "name": "Configuration Choices", "id": "configuration", "itemList": [ { @@ -57,11 +57,6 @@ "name": "project.json and nx.json", "id": "projectjson", "file": "shared/configuration/projectjson" - }, - { - "name": "angular.json and nx.json", - "id": "angularjson", - "file": "shared/configuration/angularjson" } ] }, @@ -1667,11 +1662,6 @@ "name": "Configuration", "id": "configuration", "itemList": [ - { - "name": "angular.json and nx.json", - "id": "angularjson", - "file": "shared/configuration/angularjson" - }, { "name": "package.json and nx.json", "id": "packagejson", diff --git a/docs/shared/configuration/angularjson.md b/docs/shared/configuration/angularjson.md deleted file mode 100644 index dd571fddb532f0..00000000000000 --- a/docs/shared/configuration/angularjson.md +++ /dev/null @@ -1,473 +0,0 @@ -# Configuration: angular.json and nx.json - -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 -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. - -## Angular CLI and Angular.json - -We encourage folks to use separate `project.json` for each project instead of inlining all of them into `angular.json` -or `workspace.json`. Some other tools (for instance some editors) may require you to inline all the configuration -into `angular.json`. Nx will work exactly the same way whether the configuration is inlined or not. Everything in this -guide that talks about `project.json` applies in exactly the same way to `angular.json` if the configuration is inlined. - -## Project Configuration - -The `project.json` file contains configuration specific to its project. This file is often created when you use Nx -Plugins. Everything you can configure in `package.json` you can also configure in `project.json`. In addition, you can -configure custom executors, which are used instead of npm scripts. Custom executors are typed, toolable and provide a -lot more flexibility for running long-live processes. They are also more composable. - -If you satisfied with npm scripts though, you will never see a `project.json` file in your workspace. But we encourage -you to explore Nx Plugins and the power they bring. - -Let's look at the following `project.json`: - -```json -{ - "root": "libs/mylib/", - "sourceRoot": "libs/mylib/src", - "projectType": "library", - "targets": { - "test": { - "executor": "@nrwl/jest:jest", - "outputs": [], - "dependsOn": [ - { - "target": "build", - "projects": "self" - } - ], - "options": { - "jestConfig": "libs/mylib/jest.config.js", - "tsConfig": "libs/mylib/tsconfig.spec.json" - } - }, - "build": { - "executor": "@nrwl/js:tsc", - "outputs": [ - "dist/libs/mylib" - ], - "dependsOn": [ - { - "target": "build", - "projects": "dependencies" - } - ], - "options": { - "tsConfig": "libs/mylib/tsconfig.lib.json", - "main": "libs/mylib/src/main.ts" - }, - "configurations": { - "production": { - "tsConfig": "libs/mylib/tsconfig-prod.lib.json" - } - } - } - }, - "tags": [ - "scope:myteam" - ], - "implicitDependencies": [ - "anotherlib" - ] - ] -} -``` - -- `root` tells Nx the location of the library including its sources and configuration files. -- `sourceRoot` tells Nx the location of the library's source files. -- `projectType` is either 'application' or 'library'. The project type is used in dep graph viz and in a few aux - commands. - -### Targets - -Let's look at a sample test target: - -```json -{ - "test": { - "executor": "@nrwl/jest:jest", - "outputs": [], - "dependsOn": [ - { - "target": "build", - "projects": "self" - } - ], - "options": { - "jestConfig": "libs/mylib/jest.config.js", - "tsConfig": "libs/mylib/tsconfig.spec.json" - } - } -} -``` - -**Target Name** - -The name of the target `test` means that you can invoke it as follows: `nx test mylib` or `nx run mylib:test`. The name -isn't significant in any other way. If you rename it to, for example, `mytest`, you will be able to run as -follows: `nx mytest mylib` or `nx run mylib:mytest`. - -**Executor** - -The `executor` property tells Nx what function to invoke when you run the target. `"@nrwl/jest:jest"` tells Nx to find -the `@nrwl/jest` package, find the executor named `jest` and invoke it with the options. - -**Options** - -The `options` provides a map of values that will be passed to the executor. The provided command line args will be -merged into this map. I.e., `nx test mylib --jestConfig=libs/mylib/another-jest.config.js` will pass the following to -the executor: - -```json -{ - "jestConfig": "libs/mylib/another-jest.config.js", - "tsConfig": "libs/mylib/tsconfig.spec.json" -} -``` - -**Configurations** - -The `configurations` property provides extra sets of values that will be merged into the options map. - -```json -{ - "build": { - "executor": "@nrwl/js:tsc", - "outputs": ["dist/libs/mylib"], - "dependsOn": [ - { - "target": "build", - "projects": "dependencies" - } - ], - "options": { - "tsConfig": "libs/mylib/tsconfig.lib.json", - "main": "libs/mylib/src/main.ts" - }, - "configurations": { - "production": { - "tsConfig": "libs/mylib/tsconfig-prod.lib.json" - } - } - } -} -``` - -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: - -```javascript -require(`@nrwl/jest`).executors['jest']({ ...options, ...selectedConfiguration, ...commandLineArgs } -}) // Pseudocode -``` - -The selected configuration adds/overrides the default options, and the provided command line args add/override the -configuration options. - -### Outputs - -`"outputs": ["dist/libs/mylib"]` tells Nx where the `build` target is going to create file artifacts. The provided value -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. - -### dependsOn - -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. - -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 -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. - -### implicitDependencies - -Nx uses powerful source-code analysis to figure out your workspace's project graph. Some dependencies cannot be deduced -statically, so you can set them manually like this: - -```json -{ - "root": "libs/mylib/", - "sourceRoot": "libs/mylib/src", - "projectType": "library", - "targets": {}, - "implicitDependencies": ["anotherlib"] -} -``` - -### angular json / workspace json - -The `angular.json`/`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. - -```json -{ - "version": 2, - "projects": { - "myapp": "apps/myapp" - } -} -``` - -- `"version": 2` tells Nx that we are using Nx's format for the `workspace.json` file. -- `projects` is a map of project names to their locations. - -You could inline `project.json` files into `workspace.json`. This used to be the default, but it's no longer -recommended. If you have an existing workspace where the configuration is inlined, -run `nx g convert-to-nx-project --all`. - -If you have an old workspace where the configuration version is set to 1, change the version number to 2 and -run `nx format`. - -## CLI Configuration - -The `nx.json` file contains extra configuration options mostly related to the project graph. - -The following is an expanded version showing all options. Your `nx.json` will likely be much shorter. - -```json -{ - "npmScope": "happyorg", - "affected": { - "defaultBase": "main" - }, - "workspaceLayout": { - "appsDir": "demos", - "libsDir": "packages" - }, - "implicitDependencies": { - "workspace.json": "*", - "package.json": { - "dependencies": "*", - "devDependencies": "*" - }, - "tsconfig.base.json": "*", - "nx.json": "*" - }, - "targetDependencies": { - "build": [ - { - "target": "build", - "projects": "dependencies" - } - ] - }, - "cli": { - "defaultCollection": "@nrwl/js" - }, - "generators": { - "@nrwl/js:library": { - "buildable": true - } - }, - "tasksRunnerOptions": { - "default": { - "runner": "@nrwl/workspace/tasks-runners", - "options": { - "cacheableOperations": ["build", "lint", "test", "e2e"] - } - } - } -} -``` - -### NPM Scope - -Tells Nx what prefix to use when generating library imports. - -### Affected - -Tells Nx which branch and HEAD to use when calculating affected projects. - -- `defaultBase` defines the default base branch, defaulted to `main`. - -### Workspace Layout - -You can add a `workspaceLayout` property to modify where libraries and apps are located. - -```json -{ - "workspaceLayout": { - "appsDir": "demos", - "libsDir": "packages" - } -} -``` - -These settings would store apps in `/demos/` and libraries in `/packages/`. The paths specified are relative to the -workspace root. - -### Files & Implicit Dependencies - -Nx performs advanced source-code analysis to figure out the project graph of the workspace. So when you make a change, -Nx can deduce what can be broken by this change. Some dependencies between projects and shared files cannot be inferred -statically. You can configure those using `implicitDependencies`. - -```json -{ - "implicitDependencies": { - "workspace.json": "*", - "package.json": { - "dependencies": "*", - "devDependencies": { - "mypackage": ["mylib"] - }, - "scripts": { - "check:*": "*" - } - }, - "globalFile": ["myapp"], - "styles/**/*.css": ["myapp"] - } -} -``` - -In the example above: - -- Changing `workspace.json` affects every project. -- Changing the `dependencies` property in `package.json` affects every project. -- Changing the `mypackage` property in `package.json` only affects `mylib`. -- Changing any of the custom check `scripts` in `package.json` affects every project. -- Changing `globalFile` only affects `myapp`. -- Changing any CSS file inside the `styles` directory only affects `myapp`. - -### Target Dependencies - -Targets can depend on other targets. A common scenario is having to build dependencies of a project first before -building the project. The `dependsOn` property in `package.json` can be used to define the list of dependencies of an -individual target. - -Often the same `dependsOn` configuration has to be defined for every project in the repo, and that's when -defining `targetDependencies` in `nx.json` is helpful. - -```json -{ - "targetDependencies": { - "build": [ - { - "target": "build", - "projects": "dependencies" - } - ] - } -} -``` - -The configuration above is identical to adding `{"dependsOn": [{"target": "build", "projects": "dependencies"]}` to -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`. - -```json -{ - "cli": { - "defaultCollection": "@nrwl/js" - } -} -``` - -### Generators - -Default generator options are configured in `nx.json` as well. For instance, the following tells Nx to always -pass `--buildable=true` when creating new libraries. - -```json -{ - "generators": { - "@nrwl/js:library": { - "buildable": true - } - } -} -``` - -### Tasks Runner Options - -> A task is an invocation of a target. - -Tasks runners are invoked when you run `nx test`, `nx build`, `nx run-many`, `nx affected`, and so on. The tasks runner -named "default" is used by default. Specify a different one like -this `nx run-many --target=build --all --runner=another`. - -Tasks runners can accept different options. The following are the options supported -by `"@nrwl/workspace/tasks-runners"` and `"@nrwl/nx-cloud"`. - -- `cacheableOperations` defines the list of targets/operations that are cached by Nx. -- `parallel` defines the max number of targets ran in parallel (in older versions of Nx you had to - pass `--parallel --maxParallel=3` instead of `--parallel=3`). -- `captureStderr` defines whether the cache captures stderr or just stdout. -- `skipNxCache` defines whether the Nx Cache should be skipped. Defaults to `false`. -- `cacheDirectory` defines where the local cache is stored, which is `node_modules/.cache/nx` by default. -- `encryptionKey` (when using `"@nrwl/nx-cloud"` only) defines an encryption key to support end-to-end encryption of - your cloud cache. You may also provide an environment variable with the key `NX_CLOUD_ENCRYPTION_KEY` that contains an - encryption key as its value. The Nx Cloud task runner normalizes the key length, so any length of key is acceptable. -- `runtimeCacheInputs` defines the list of commands that are run by the runner to include into the computation hash - value. -- `selectivelyHashTsConfig` only hash the path mapping of the active project in the `tsconfig.base.json` (e.g., - adding/removing projects doesn't affect the hash of existing projects). Defaults to `false` - -`runtimeCacheInputs` are set as follows: - -```json -{ - "tasksRunnerOptions": { - "default": { - "runner": "@nrwl/workspace/tasks-runners", - "options": { - "cacheableOperations": ["build", "lint", "test", "e2e"], - "runtimeCacheInputs": ["node -v"] - } - } - } -} -``` - -You can configure `parallel` in `nx.json`, but you can also pass them in the -terminal `nx run-many --target=test --parallel=5`. - -## .nxignore - -You may optionally add an `.nxignore` file to the root. This file is used to specify files in your workspace that should -be completely ignored by Nx. - -The syntax is the same as -a [`.gitignore` file](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring). - -**When a file is specified in the `.nxignore` file:** - -1. Changes to that file are not taken into account in the `affected` calculations. -2. Even if the file is outside an app or library, `nx workspace-lint` won't warn about it. - -## Validating the configuration - -If at any point in time you want to check if your configuration is in sync, you can use -the [workspace-lint]({{framework}}/cli/workspace-lint) executor: - -```bash -nx workspace-lint -``` - -This will identify any projects with no files in the configured project root folder, as well as any file that's not part -of any project configured in the workspace. diff --git a/docs/shared/configuration/projectjson.md b/docs/shared/configuration/projectjson.md index b56a82520bdf7d..f67987275c59a7 100644 --- a/docs/shared/configuration/projectjson.md +++ b/docs/shared/configuration/projectjson.md @@ -7,6 +7,9 @@ Projects can be configured in `package.json` (if you use npm scripts and not Nx 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. + +> Angular developers can also configure projects in angular.json. Read [this guide](/getting-started/nx-and-angular#angularjson) for more information. + ## Project Configuration The `project.json` file contains configuration specific to its project. This file is often created when you use Nx diff --git a/docs/shared/getting-started/nx-and-angular.md b/docs/shared/getting-started/nx-and-angular.md index 5f1d70a5216f31..fb4ed22fae65bd 100644 --- a/docs/shared/getting-started/nx-and-angular.md +++ b/docs/shared/getting-started/nx-and-angular.md @@ -45,18 +45,20 @@ Nx integrates well with the Angular CLI: This works so well that often folks don't even know they use Nx. -## Angular CLI, however, has some limitations, and Nx addresses them. +## Angular CLI has some limitations, and Nx addresses them. -### angular.json is too long +### angular.json -Nx allows you to split `angular.json` into multiple configuration files (one for each project). This is a big deal for large workspaces where `angular.json` can be thousands of lines long. +Nx supports using `angular.json` to configure projects and their targets, but it comes with a few limitations. For instance, `angular.json` can be many thousands of lines long for large workspaces. -This is how you do it: +What we recommend instead is to split `angular.json` into multiple `project.json` files (one for each project). This is how you do it: - Change the version number in `angular.json` to `2` - Run `nx format` - Run `nx generate @nrwl/workspace:convert-to-nx-project --all=true` +**But regardless of whether you use `angular.json` or `project.json`, the configuration remains the same. So anything written about `project.json` or `workspace.json` applies to `angular.json` in the same way. For instance, everything in [project.json and nx.json](/configuration/projectjson) applies to `angular.json` in the same way.** + Note that even though the configuration is split, everything works the same way. All migrations and schematics that expect a single `angular.json` file, will receive a single file. Nx is smart, so it merges all the files in memory to make those migrations and schematics work. ### 'ng update' and 'nx migrate' diff --git a/nx-dev/nx-dev/public/documentation/latest/map.json b/nx-dev/nx-dev/public/documentation/latest/map.json index 2e4300055d337f..5cbb4f8702d7a1 100644 --- a/nx-dev/nx-dev/public/documentation/latest/map.json +++ b/nx-dev/nx-dev/public/documentation/latest/map.json @@ -45,7 +45,7 @@ ] }, { - "name": "Configuration", + "name": "Configuration Choices", "id": "configuration", "itemList": [ { @@ -57,11 +57,6 @@ "name": "project.json and nx.json", "id": "projectjson", "file": "shared/configuration/projectjson" - }, - { - "name": "angular.json and nx.json", - "id": "angularjson", - "file": "shared/configuration/angularjson" } ] }, @@ -1667,11 +1662,6 @@ "name": "Configuration", "id": "configuration", "itemList": [ - { - "name": "angular.json and nx.json", - "id": "angularjson", - "file": "shared/configuration/angularjson" - }, { "name": "package.json and nx.json", "id": "packagejson", diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/configuration/angularjson.md b/nx-dev/nx-dev/public/documentation/latest/shared/configuration/angularjson.md deleted file mode 100644 index dd571fddb532f0..00000000000000 --- a/nx-dev/nx-dev/public/documentation/latest/shared/configuration/angularjson.md +++ /dev/null @@ -1,473 +0,0 @@ -# Configuration: angular.json and nx.json - -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 -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. - -## Angular CLI and Angular.json - -We encourage folks to use separate `project.json` for each project instead of inlining all of them into `angular.json` -or `workspace.json`. Some other tools (for instance some editors) may require you to inline all the configuration -into `angular.json`. Nx will work exactly the same way whether the configuration is inlined or not. Everything in this -guide that talks about `project.json` applies in exactly the same way to `angular.json` if the configuration is inlined. - -## Project Configuration - -The `project.json` file contains configuration specific to its project. This file is often created when you use Nx -Plugins. Everything you can configure in `package.json` you can also configure in `project.json`. In addition, you can -configure custom executors, which are used instead of npm scripts. Custom executors are typed, toolable and provide a -lot more flexibility for running long-live processes. They are also more composable. - -If you satisfied with npm scripts though, you will never see a `project.json` file in your workspace. But we encourage -you to explore Nx Plugins and the power they bring. - -Let's look at the following `project.json`: - -```json -{ - "root": "libs/mylib/", - "sourceRoot": "libs/mylib/src", - "projectType": "library", - "targets": { - "test": { - "executor": "@nrwl/jest:jest", - "outputs": [], - "dependsOn": [ - { - "target": "build", - "projects": "self" - } - ], - "options": { - "jestConfig": "libs/mylib/jest.config.js", - "tsConfig": "libs/mylib/tsconfig.spec.json" - } - }, - "build": { - "executor": "@nrwl/js:tsc", - "outputs": [ - "dist/libs/mylib" - ], - "dependsOn": [ - { - "target": "build", - "projects": "dependencies" - } - ], - "options": { - "tsConfig": "libs/mylib/tsconfig.lib.json", - "main": "libs/mylib/src/main.ts" - }, - "configurations": { - "production": { - "tsConfig": "libs/mylib/tsconfig-prod.lib.json" - } - } - } - }, - "tags": [ - "scope:myteam" - ], - "implicitDependencies": [ - "anotherlib" - ] - ] -} -``` - -- `root` tells Nx the location of the library including its sources and configuration files. -- `sourceRoot` tells Nx the location of the library's source files. -- `projectType` is either 'application' or 'library'. The project type is used in dep graph viz and in a few aux - commands. - -### Targets - -Let's look at a sample test target: - -```json -{ - "test": { - "executor": "@nrwl/jest:jest", - "outputs": [], - "dependsOn": [ - { - "target": "build", - "projects": "self" - } - ], - "options": { - "jestConfig": "libs/mylib/jest.config.js", - "tsConfig": "libs/mylib/tsconfig.spec.json" - } - } -} -``` - -**Target Name** - -The name of the target `test` means that you can invoke it as follows: `nx test mylib` or `nx run mylib:test`. The name -isn't significant in any other way. If you rename it to, for example, `mytest`, you will be able to run as -follows: `nx mytest mylib` or `nx run mylib:mytest`. - -**Executor** - -The `executor` property tells Nx what function to invoke when you run the target. `"@nrwl/jest:jest"` tells Nx to find -the `@nrwl/jest` package, find the executor named `jest` and invoke it with the options. - -**Options** - -The `options` provides a map of values that will be passed to the executor. The provided command line args will be -merged into this map. I.e., `nx test mylib --jestConfig=libs/mylib/another-jest.config.js` will pass the following to -the executor: - -```json -{ - "jestConfig": "libs/mylib/another-jest.config.js", - "tsConfig": "libs/mylib/tsconfig.spec.json" -} -``` - -**Configurations** - -The `configurations` property provides extra sets of values that will be merged into the options map. - -```json -{ - "build": { - "executor": "@nrwl/js:tsc", - "outputs": ["dist/libs/mylib"], - "dependsOn": [ - { - "target": "build", - "projects": "dependencies" - } - ], - "options": { - "tsConfig": "libs/mylib/tsconfig.lib.json", - "main": "libs/mylib/src/main.ts" - }, - "configurations": { - "production": { - "tsConfig": "libs/mylib/tsconfig-prod.lib.json" - } - } - } -} -``` - -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: - -```javascript -require(`@nrwl/jest`).executors['jest']({ ...options, ...selectedConfiguration, ...commandLineArgs } -}) // Pseudocode -``` - -The selected configuration adds/overrides the default options, and the provided command line args add/override the -configuration options. - -### Outputs - -`"outputs": ["dist/libs/mylib"]` tells Nx where the `build` target is going to create file artifacts. The provided value -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. - -### dependsOn - -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. - -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 -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. - -### implicitDependencies - -Nx uses powerful source-code analysis to figure out your workspace's project graph. Some dependencies cannot be deduced -statically, so you can set them manually like this: - -```json -{ - "root": "libs/mylib/", - "sourceRoot": "libs/mylib/src", - "projectType": "library", - "targets": {}, - "implicitDependencies": ["anotherlib"] -} -``` - -### angular json / workspace json - -The `angular.json`/`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. - -```json -{ - "version": 2, - "projects": { - "myapp": "apps/myapp" - } -} -``` - -- `"version": 2` tells Nx that we are using Nx's format for the `workspace.json` file. -- `projects` is a map of project names to their locations. - -You could inline `project.json` files into `workspace.json`. This used to be the default, but it's no longer -recommended. If you have an existing workspace where the configuration is inlined, -run `nx g convert-to-nx-project --all`. - -If you have an old workspace where the configuration version is set to 1, change the version number to 2 and -run `nx format`. - -## CLI Configuration - -The `nx.json` file contains extra configuration options mostly related to the project graph. - -The following is an expanded version showing all options. Your `nx.json` will likely be much shorter. - -```json -{ - "npmScope": "happyorg", - "affected": { - "defaultBase": "main" - }, - "workspaceLayout": { - "appsDir": "demos", - "libsDir": "packages" - }, - "implicitDependencies": { - "workspace.json": "*", - "package.json": { - "dependencies": "*", - "devDependencies": "*" - }, - "tsconfig.base.json": "*", - "nx.json": "*" - }, - "targetDependencies": { - "build": [ - { - "target": "build", - "projects": "dependencies" - } - ] - }, - "cli": { - "defaultCollection": "@nrwl/js" - }, - "generators": { - "@nrwl/js:library": { - "buildable": true - } - }, - "tasksRunnerOptions": { - "default": { - "runner": "@nrwl/workspace/tasks-runners", - "options": { - "cacheableOperations": ["build", "lint", "test", "e2e"] - } - } - } -} -``` - -### NPM Scope - -Tells Nx what prefix to use when generating library imports. - -### Affected - -Tells Nx which branch and HEAD to use when calculating affected projects. - -- `defaultBase` defines the default base branch, defaulted to `main`. - -### Workspace Layout - -You can add a `workspaceLayout` property to modify where libraries and apps are located. - -```json -{ - "workspaceLayout": { - "appsDir": "demos", - "libsDir": "packages" - } -} -``` - -These settings would store apps in `/demos/` and libraries in `/packages/`. The paths specified are relative to the -workspace root. - -### Files & Implicit Dependencies - -Nx performs advanced source-code analysis to figure out the project graph of the workspace. So when you make a change, -Nx can deduce what can be broken by this change. Some dependencies between projects and shared files cannot be inferred -statically. You can configure those using `implicitDependencies`. - -```json -{ - "implicitDependencies": { - "workspace.json": "*", - "package.json": { - "dependencies": "*", - "devDependencies": { - "mypackage": ["mylib"] - }, - "scripts": { - "check:*": "*" - } - }, - "globalFile": ["myapp"], - "styles/**/*.css": ["myapp"] - } -} -``` - -In the example above: - -- Changing `workspace.json` affects every project. -- Changing the `dependencies` property in `package.json` affects every project. -- Changing the `mypackage` property in `package.json` only affects `mylib`. -- Changing any of the custom check `scripts` in `package.json` affects every project. -- Changing `globalFile` only affects `myapp`. -- Changing any CSS file inside the `styles` directory only affects `myapp`. - -### Target Dependencies - -Targets can depend on other targets. A common scenario is having to build dependencies of a project first before -building the project. The `dependsOn` property in `package.json` can be used to define the list of dependencies of an -individual target. - -Often the same `dependsOn` configuration has to be defined for every project in the repo, and that's when -defining `targetDependencies` in `nx.json` is helpful. - -```json -{ - "targetDependencies": { - "build": [ - { - "target": "build", - "projects": "dependencies" - } - ] - } -} -``` - -The configuration above is identical to adding `{"dependsOn": [{"target": "build", "projects": "dependencies"]}` to -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`. - -```json -{ - "cli": { - "defaultCollection": "@nrwl/js" - } -} -``` - -### Generators - -Default generator options are configured in `nx.json` as well. For instance, the following tells Nx to always -pass `--buildable=true` when creating new libraries. - -```json -{ - "generators": { - "@nrwl/js:library": { - "buildable": true - } - } -} -``` - -### Tasks Runner Options - -> A task is an invocation of a target. - -Tasks runners are invoked when you run `nx test`, `nx build`, `nx run-many`, `nx affected`, and so on. The tasks runner -named "default" is used by default. Specify a different one like -this `nx run-many --target=build --all --runner=another`. - -Tasks runners can accept different options. The following are the options supported -by `"@nrwl/workspace/tasks-runners"` and `"@nrwl/nx-cloud"`. - -- `cacheableOperations` defines the list of targets/operations that are cached by Nx. -- `parallel` defines the max number of targets ran in parallel (in older versions of Nx you had to - pass `--parallel --maxParallel=3` instead of `--parallel=3`). -- `captureStderr` defines whether the cache captures stderr or just stdout. -- `skipNxCache` defines whether the Nx Cache should be skipped. Defaults to `false`. -- `cacheDirectory` defines where the local cache is stored, which is `node_modules/.cache/nx` by default. -- `encryptionKey` (when using `"@nrwl/nx-cloud"` only) defines an encryption key to support end-to-end encryption of - your cloud cache. You may also provide an environment variable with the key `NX_CLOUD_ENCRYPTION_KEY` that contains an - encryption key as its value. The Nx Cloud task runner normalizes the key length, so any length of key is acceptable. -- `runtimeCacheInputs` defines the list of commands that are run by the runner to include into the computation hash - value. -- `selectivelyHashTsConfig` only hash the path mapping of the active project in the `tsconfig.base.json` (e.g., - adding/removing projects doesn't affect the hash of existing projects). Defaults to `false` - -`runtimeCacheInputs` are set as follows: - -```json -{ - "tasksRunnerOptions": { - "default": { - "runner": "@nrwl/workspace/tasks-runners", - "options": { - "cacheableOperations": ["build", "lint", "test", "e2e"], - "runtimeCacheInputs": ["node -v"] - } - } - } -} -``` - -You can configure `parallel` in `nx.json`, but you can also pass them in the -terminal `nx run-many --target=test --parallel=5`. - -## .nxignore - -You may optionally add an `.nxignore` file to the root. This file is used to specify files in your workspace that should -be completely ignored by Nx. - -The syntax is the same as -a [`.gitignore` file](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring). - -**When a file is specified in the `.nxignore` file:** - -1. Changes to that file are not taken into account in the `affected` calculations. -2. Even if the file is outside an app or library, `nx workspace-lint` won't warn about it. - -## Validating the configuration - -If at any point in time you want to check if your configuration is in sync, you can use -the [workspace-lint]({{framework}}/cli/workspace-lint) executor: - -```bash -nx workspace-lint -``` - -This will identify any projects with no files in the configured project root folder, as well as any file that's not part -of any project configured in the workspace. diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/configuration/projectjson.md b/nx-dev/nx-dev/public/documentation/latest/shared/configuration/projectjson.md index b56a82520bdf7d..f67987275c59a7 100644 --- a/nx-dev/nx-dev/public/documentation/latest/shared/configuration/projectjson.md +++ b/nx-dev/nx-dev/public/documentation/latest/shared/configuration/projectjson.md @@ -7,6 +7,9 @@ Projects can be configured in `package.json` (if you use npm scripts and not Nx 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. + +> Angular developers can also configure projects in angular.json. Read [this guide](/getting-started/nx-and-angular#angularjson) for more information. + ## Project Configuration The `project.json` file contains configuration specific to its project. This file is often created when you use Nx diff --git a/nx-dev/nx-dev/public/documentation/latest/shared/getting-started/nx-and-angular.md b/nx-dev/nx-dev/public/documentation/latest/shared/getting-started/nx-and-angular.md index 5f1d70a5216f31..fb4ed22fae65bd 100644 --- a/nx-dev/nx-dev/public/documentation/latest/shared/getting-started/nx-and-angular.md +++ b/nx-dev/nx-dev/public/documentation/latest/shared/getting-started/nx-and-angular.md @@ -45,18 +45,20 @@ Nx integrates well with the Angular CLI: This works so well that often folks don't even know they use Nx. -## Angular CLI, however, has some limitations, and Nx addresses them. +## Angular CLI has some limitations, and Nx addresses them. -### angular.json is too long +### angular.json -Nx allows you to split `angular.json` into multiple configuration files (one for each project). This is a big deal for large workspaces where `angular.json` can be thousands of lines long. +Nx supports using `angular.json` to configure projects and their targets, but it comes with a few limitations. For instance, `angular.json` can be many thousands of lines long for large workspaces. -This is how you do it: +What we recommend instead is to split `angular.json` into multiple `project.json` files (one for each project). This is how you do it: - Change the version number in `angular.json` to `2` - Run `nx format` - Run `nx generate @nrwl/workspace:convert-to-nx-project --all=true` +**But regardless of whether you use `angular.json` or `project.json`, the configuration remains the same. So anything written about `project.json` or `workspace.json` applies to `angular.json` in the same way. For instance, everything in [project.json and nx.json](/configuration/projectjson) applies to `angular.json` in the same way.** + Note that even though the configuration is split, everything works the same way. All migrations and schematics that expect a single `angular.json` file, will receive a single file. Nx is smart, so it merges all the files in memory to make those migrations and schematics work. ### 'ng update' and 'nx migrate'