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

docs(nxdev): update doc content (#8080)

Browse Source
This commit is contained in:
Benjamin Cabanes 2021-12-09 13:06:37 -05:00 committed by GitHub
parent 0db7aedbd9
commit 0ee99dedb4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 1152 additions and 620 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

159
nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/scam.md Normal file
View File

@ -0,0 +1,159 @@
# @nrwl/angular:scam
Generate a component with an accompanying Single Angular Module Component (SCAM).
## Usage
```bash
nx generate scam ...
```
By default, Nx will search for `scam` in the default collection provisioned in `angular.json`.
You can specify the collection explicitly as follows:
```bash
nx g @nrwl/angular:scam ...
```
Show what will be generated without writing to disk:
```bash
nx g scam ... --dry-run
```
## Options
### name (_**required**_)
Type: `string`
The name of the component.
### changeDetection
Alias(es): c
Default: `Default`
Type: `string`
Possible values: `Default`, `OnPush`
The change detection strategy to use in the new component.
### displayBlock
Alias(es): b
Default: `false`
Type: `boolean`
Specifies if the style will contain `:host { display: block; }`.
### flat
Default: `false`
Type: `boolean`
Create the new files at the top level of the current project.
### inlineScam
Default: `true`
Type: `boolean`
Create the NgModule in the same file as the Component.
### inlineStyle
Alias(es): s
Default: `false`
Type: `boolean`
Include styles inline in the component.ts file. Only CSS styles can be included inline. By default, an external styles file is created and referenced in the component.ts file.
### inlineTemplate
Alias(es): t
Default: `false`
Type: `boolean`
Include template inline in the component.ts file. By default, an external template file is created and referenced in the component.ts file.
### path (**hidden**)
Type: `string`
The path at which to create the component file, relative to the current workspace. Default is a folder with the same name as the component in the project root.
### prefix
Alias(es): p
Type: `string`
The prefix to apply to the generated component selector.
### project
Type: `string`
The name of the project.
### selector
Type: `string`
The HTML selector to use for this component.
### skipSelector
Default: `false`
Type: `boolean`
Specifies if the component should have a selector or not.
### skipTests
Default: `false`
Type: `boolean`
Do not create "spec.ts" test files for the new component.
### style
Default: `css`
Type: `string`
Possible values: `css`, `scss`, `sass`, `less`, `none`
The file extension or preprocessor to use for style files, or 'none' to skip generating the style file.
### type
Default: `Component`
Type: `string`
Adds a developer-defined type to the filename, in the format "name.type.ts".
### viewEncapsulation
Alias(es): v
Type: `string`
Possible values: `Emulated`, `None`, `ShadowDom`
The view encapsulation strategy to use in the new component.

242
nx-dev/nx-dev/public/documentation/latest/angular/guides/configuration.md
View File

@ -1,88 +1,56 @@
# Configuration
There are three top-level configuration files every Nx workspace has: `angular.json`, `nx.json`, and `tsconfig.base.json`. Many Nx plugins modify these files when generating new code, but you can also modify them manually.
There are two main types of configuration in every Nx workspace: [project configuration](#project-configuration) and [workspace configuration](#workspace-configuration). Project configuration consists of `workspace.json`/`angular.json`, `**/project.json`, and `**/package.json`. Workspace configuration consists of `nx.json` and `tsconfig.base.json`.
## angular.json
Many Nx plugins modify these files when generating new code, but you can also modify them manually.
The `angular.json` configuration file contains information about the targets and generators. Let's look at the following example:
## Project Configuration
### workspace.json / angular.json
`workspace.json` is used in all Nx monorepos, regardless of framework. In repositories created from an existing angular project, the file
may be called `angular.json` instead. To transition, optionally rename the file.
Since `workspace.json` is used in most Nx repositories, we will refer to that from here on.
The `workspace.json` file contains a list of project configurations, as well as the version of your workspace. Let's look at the following example:
```json
{
"version": 2,
"projects": {
"myapp": {
"root": "apps/myapp/",
"sourceRoot": "apps/myapp/src",
"projectType": "application",
"architect": {
"build": {
"builder": "@nrwl/web:webpack",
"outputs": ["dist/apps/myapp"],
"dependsOn": [
{
"target": "build",
"projects": "dependencies"
}
],
"options": {
"index": "apps/myapp/src/app.html",
"main": "apps/myapp/src/main.ts"
},
"configurations": {
"production": {
"optimization": true
}
}
},
"serve": {
"builder": "@nrwl/web:dev-server",
"options": {
"buildTarget": "myapp:build",
"proxyConfig": "apps/myapp/proxy.conf.json"
}
},
"test": {
"builder": "@nrwl/jest:jest",
"options": {
"jestConfig": "apps/myapp/jest.config.js",
"tsConfig": "apps/myapp/tsconfig.spec.json"
}
}
}
},
"mylib": {
"root": "libs/mylib/",
"sourceRoot": "libs/mylib/src",
"projectType": "library",
"architect": {
"test": {
"builder": "@nrwl/jest:jest",
"options": {
"jestConfig": "libs/mylib/jest.config.js",
"tsConfig": "libs/mylib/tsconfig.spec.json"
}
}
}
}
"myapp": "apps/myapp"
}
}
```
### Projects
- `"version": 2` tells Nx that we are using Nx's format for the `workspace.json` file.
- `projects` is a map of project name to either the project location, or its configuration. (see `project.json`)[(#project-json)]
The `projects` property configures all apps and libs.
> This file is optional as of Nx v13.3.
> To convert an existing repository to use standalone configurations, run `nx g convert-to-nx-project --all`
For instance, the following configures `mylib`.
#### Version 1 vs Version 2
- Version 1 workspaces do not support standalone configuration (`project.json` files), so all of the entries in projects are inline configurations.
- In Version 1 workspaces the `targets` property is replaced with `architect` in project configuration
- In Version 1 workspaces the `executor` property on a target is replaced with `executor`
- In Version 1 workspaces the `generators` property used to define generator defaults for a project is replaced with `schematics`
> To upgrade to version 2, change the version number to 2 and run `nx format`.
### project.json
The `project.json` file contains configuration specific to it's project. Lets look at the following example:
```json
{
"mylib": {
"root": "libs/mylib/",
"sourceRoot": "libs/mylib/src",
"projectType": "library",
"architect": {},
"tags": [],
"implicitDependencies": []
}
"root": "libs/mylib/",
"sourceRoot": "libs/mylib/src",
"projectType": "library",
"targets": {},
"tags": [],
"implicitDependencies": []
}
```
@ -93,16 +61,31 @@ For instance, the following configures `mylib`.
- `tags` configures tags used for linting
- `implicitDependencies` configure implicit dependencies between projects in the workspace ([see below](#implicit-dependencies))
> Nx uses the architect library built by the Angular team at Google. The naming reflects that. Important to note: it's a general purpose library that **does not** have any dependency on Angular.
The contents of `project.json` can be inlined into workspace.json by replacing the project location with the contents file. For example, in `workspace.json`, you could have something like:
### Targets
```jsonc
{
// ... other configuration
"projects": {
// ... other (poterntially standalone) projects
"my-inline-project": {
"root": "apps/my-inline-project"
//... other project configuration
}
}
}
```
Let's look at the simple architect target:
> In workspaces without `workspace.json` or `angular.json`, a `project.json` is optional for your project if it already has a `package.json`. Instead, its configuration is inferred based on its `package.json` as described below.
#### Targets
Let's look at a sample test target:
```json
{
"test": {
"builder": "@nrwl/jest:jest",
"executor": "@nrwl/jest:jest",
"options": {
"jestConfig": "libs/mylib/jest.config.js",
"tsConfig": "libs/mylib/tsconfig.spec.json"
@ -115,13 +98,13 @@ Let's look at the simple architect target:
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`.
**Builder**
**Executor**
The `builder` 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 builder named `jest` and invoke it with the options.
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 builder. 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 builder:
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
{
@ -132,12 +115,12 @@ The `options` provides a map of values that will be passed to the builder. The p
**Outputs**
The `outputs` property lists the folders the builder creates files in. The property is optional. If not provided, Nx assumes it is `dist/libs/mylib`.
The `outputs` property lists the folders the executor creates files in. The property is optional. If not provided, Nx assumes it is `dist/libs/mylib`.
```json
{
"build": {
"builder": "@nrwl/web:webpack",
"executor": "@nrwl/web:webpack",
"outputs": ["dist/apps/myapp"],
"options": {
"index": "apps/myapp/src/app.html",
@ -154,7 +137,7 @@ The `configurations` property provides extra sets of values that will be merged
```json
{
"build": {
"builder": "@nrwl/web:webpack",
"executor": "@nrwl/web:webpack",
"outputs": ["dist/apps/myapp"],
"options": {
"index": "apps/myapp/src/app.html",
@ -171,10 +154,10 @@ The `configurations` property provides extra sets of values that will be merged
You can select a configuration like this: `nx build myapp --configuration=production` or `nx run myapp:build:configuration=production`.
The following show how the builder options get constructed:
The following show how the executor options get constructed:
```javascript
require(`@nrwl/jest`).builders['jest']({...options, ...selectedConfiguration, ...commandLineArgs}}) // Pseudocode
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.
@ -239,38 +222,48 @@ In the following example invoking `nx build myapp` builds all the libraries firs
Often the same `dependsOn` configuration has to be defined for every project in the repo. You can define it once in `nx.json` (see below).
````
### package.json
### workspace.json
Nx also infers additional project targets from scripts defined in it's `package.json` file, if it exists. For example, you may have a package.json in the root of your lib like this:
Your `angular.json` file can be renamed to `workspace.json` and Nx will process it in the same way. The `workspace.json` has one additional top level property `version`. Setting `version` to 1 means the `workspace.json` file syntax is identical to `angular.json` When the `version` of `workspace.json` is set to 2, `targets`, `generators` and `executor` properties are used instead of the version 1 properties `architect`, `schematics` and `builder`.
## project.json
In version 2 workspaces, project configurations can also be independent files, referenced by `angular.json`. For instance, an `angular.json` may contain projects configured as below.
```json
```jsonc
{
"projects": {
"mylib": "libs/mylib"
"name": "@company/my-lib",
"scripts": {
"clean": "echo 1" // the actual command here is arbitrary
}
}
````
This tells Nx that all configuration for that project is found in the `libs/mylib/project.json` file.
```json
{
"root": "libs/mylib/",
"sourceRoot": "libs/mylib/src",
"projectType": "library",
"targets": {},
"tags": [],
"implicitDependencies": []
}
```
## nx.json
This would lead to Nx being able to run the clean script, just like a target in `project.json`. You could run `nx clean my-lib` in this instance.
Targets inferred from `package.json` scripts are ran using the `@nrwl/workspace:run-script` executor, with the project's root as the current working directory.
> Targets inside `package.json` are overwritten if a target inside `project.json` has the same name.
Additional target configuration options such as those described in [targets](#targets) above can be defined for targets that are inferred from `package.json`. Here is an example for defining custom outputs to be able to cache an inferred test target:
```jsonc
{
"name": "@company/my-lib",
"scripts": {
"test": "run-my-tests"
},
"nx": {
"targets": {
"test": {
"outputs": ["packages/my-lib/coverage"]
}
}
}
}
```
All of the options except `executor` are availble here.
## Workspace Configuration
### nx.json
The `nx.json` file contains extra configuration options mostly related to the project graph.
@ -289,7 +282,7 @@ The `nx.json` file contains extra configuration options mostly related to the pr
}
},
"implicitDependencies": {
"angular.json": "*",
"workspace.json": "*",
"package.json": {
"dependencies": "*",
"devDependencies": "*"
@ -380,7 +373,7 @@ Nx performs advanced source-code analysis to figure out the project graph of the
```json
{
"implicitDependencies": {
"angular.json": "*",
"workspace.json": "*",
"package.json": {
"dependencies": "*",
"devDependencies": {
@ -398,14 +391,14 @@ Nx performs advanced source-code analysis to figure out the project graph of the
In the example above:
- Changing `angular.json` affects every project.
- Changing `workspace.json` affects every project.
- Changing the `dependencies` property in `package.json` affects every project.
- Changing the `devDependencies` 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`.
You can also add dependencies between projects in `angular.json`. For instance, the example below defines a dependency from `myapp-e2e` to `myapp`, such that every time `myapp` is affected, `myapp-e2e` is affected as well.
You can also add dependencies between projects in `workspace.json`. For instance, the example below defines a dependency from `myapp-e2e` to `myapp`, such that every time `myapp` is affected, `myapp-e2e` is affected as well.
```jsonc
{
@ -462,7 +455,7 @@ The following command generates a new library: `nx g @nrwl/angular:lib mylib`. A
Default generator options are configured in `nx.json` as well. For instance, the following tells Nx to always pass `--style=scss` when creating new libraries.
````json
```json
{
"generators": {
"@nrwl/angular:library": {
@ -470,6 +463,7 @@ Default generator options are configured in `nx.json` as well. For instance, the
}
}
}
```
## .nxignore
@ -513,4 +507,30 @@ 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.
````
```
```
## Recent Changes
### v13.3.0
- `workspace.json` is now optional
- projects can be inferred completely from `package.json` if `workspace.json` not present
- Targets are now merged from `package.json` instead of only being used if the project has no targets defined.
- Targets inferred from `package.json` can now have an extended configuration. See [above](#package-json)
### v13.0.0
Some settings were moved between `workspace.json`/`project.json` and `nx.json`.
- tags / implicit dependencies are no longer in `nx.json` were moved from `nx.json` to project configuration.
- `cli` and `defaultProject` moved to `nx.json` from `workspace.json`
- Non-project specific generator defaults in `workspace.json` via the `generators`/`schematics` property moved to `nx.json`
### v12.4.0
Standalone configuration and `project.json` introduced. See [above](#project-json)
- tags / implicit dependencies are no longer in `nx.json` for projects using `project.json`.

15
nx-dev/nx-dev/public/documentation/latest/map.json
View File

@ -468,6 +468,11 @@
"id": "ngrx",
"file": "angular/api-angular/generators/ngrx"
},
{
"name": "scam generator",
"id": "scam",
"file": "angular/api-angular/generators/scam"
},
{
"name": "setup-mfe generator",
"id": "setup-mfe",
@ -1797,6 +1802,11 @@
"id": "ngrx",
"file": "react/api-angular/generators/ngrx"
},
{
"name": "scam generator",
"id": "scam",
"file": "react/api-angular/generators/scam"
},
{
"name": "setup-mfe generator",
"id": "setup-mfe",
@ -3090,6 +3100,11 @@
"id": "ngrx",
"file": "node/api-angular/generators/ngrx"
},
{
"name": "scam generator",
"id": "scam",
"file": "node/api-angular/generators/scam"
},
{
"name": "setup-mfe generator",
"id": "setup-mfe",

159
nx-dev/nx-dev/public/documentation/latest/node/api-angular/generators/scam.md Normal file
View File

@ -0,0 +1,159 @@
# @nrwl/angular:scam
Generate a component with an accompanying Single Angular Module Component (SCAM).
## Usage
```bash
nx generate scam ...
```
By default, Nx will search for `scam` in the default collection provisioned in `workspace.json`.
You can specify the collection explicitly as follows:
```bash
nx g @nrwl/angular:scam ...
```
Show what will be generated without writing to disk:
```bash
nx g scam ... --dry-run
```
## Options
### name (_**required**_)
Type: `string`
The name of the component.
### changeDetection
Alias(es): c
Default: `Default`
Type: `string`
Possible values: `Default`, `OnPush`
The change detection strategy to use in the new component.
### displayBlock
Alias(es): b
Default: `false`
Type: `boolean`
Specifies if the style will contain `:host { display: block; }`.
### flat
Default: `false`
Type: `boolean`
Create the new files at the top level of the current project.
### inlineScam
Default: `true`
Type: `boolean`
Create the NgModule in the same file as the Component.
### inlineStyle
Alias(es): s
Default: `false`
Type: `boolean`
Include styles inline in the component.ts file. Only CSS styles can be included inline. By default, an external styles file is created and referenced in the component.ts file.
### inlineTemplate
Alias(es): t
Default: `false`
Type: `boolean`
Include template inline in the component.ts file. By default, an external template file is created and referenced in the component.ts file.
### path (**hidden**)
Type: `string`
The path at which to create the component file, relative to the current workspace. Default is a folder with the same name as the component in the project root.
### prefix
Alias(es): p
Type: `string`
The prefix to apply to the generated component selector.
### project
Type: `string`
The name of the project.
### selector
Type: `string`
The HTML selector to use for this component.
### skipSelector
Default: `false`
Type: `boolean`
Specifies if the component should have a selector or not.
### skipTests
Default: `false`
Type: `boolean`
Do not create "spec.ts" test files for the new component.
### style
Default: `css`
Type: `string`
Possible values: `css`, `scss`, `sass`, `less`, `none`
The file extension or preprocessor to use for style files, or 'none' to skip generating the style file.
### type
Default: `Component`
Type: `string`
Adds a developer-defined type to the filename, in the format "name.type.ts".
### viewEncapsulation
Alias(es): v
Type: `string`
Possible values: `Emulated`, `None`, `ShadowDom`
The view encapsulation strategy to use in the new component.

336
nx-dev/nx-dev/public/documentation/latest/node/guides/configuration.md
View File

@ -1,121 +1,89 @@
# Configuration
There are three top-level configuration files every Nx workspace has: `workspace.json`, `nx.json`, and `tsconfig.base.json`. Many Nx plugins modify these files when generating new code, but you can also modify them manually.
There are two main types of configuration in every Nx workspace: [project configuration](#project-configuration) and [workspace configuration](#workspace-configuration). Project configuration consists of `workspace.json`, `**/project.json`, and `**/package.json`. Workspace configuration consists of `nx.json` and `tsconfig.base.json`.
## workspace.json
Many Nx plugins modify these files when generating new code, but you can also modify them manually.
The `workspace.json` configuration file contains information about the targets and generators. Let's look at the following example:
## Project Configuration
### workspace.json
The `workspace.json` file contains a list of project configurations, as well as the version of your workspace. Let's look at the following example:
```json
{
"version": 2,
"projects": {
"myapp": {
"root": "apps/myapp/",
"sourceRoot": "apps/myapp/src",
"projectType": "application",
"targets": {
"build": {
"executor": "@nrwl/node:build",
"outputs": ["dist/apps/myapp"],
"dependsOn": [
{
"target": "build",
"projects": "dependencies"
}
],
"options": {
"outputPath": "dist/packages/myapp",
"main": "packages/myapp/src/main.ts",
"tsConfig": "packages/myapp/tsconfig.app.json",
"assets": ["packages/myapp/src/assets"]
},
"configurations": {
"production": {
"optimization": true
}
}
},
"serve": {
"executor": "@nrwl/node:execute",
"options": {
"buildTarget": "myapp:build"
}
},
"test": {
"executor": "@nrwl/jest:jest",
"options": {
"jestConfig": "apps/myapp/jest.config.js"
}
}
}
},
"mylib": {
"root": "libs/mylib/",
"sourceRoot": "libs/mylib/src",
"projectType": "library",
"targets": {
"test": {
"executor": "@nrwl/jest:jest",
"options": {
"jestConfig": "libs/mylib/jest.config.js",
"tsConfig": "libs/mylib/tsconfig.spec.json"
}
},
"build": {
"executor": "@nrwl/node:package",
"options": {
"outputPath": "dist/libs/mylib",
"tsConfig": "libs/mylib/tsconfig.lib.json",
"packageJson": "libs/mylib/package.json",
"main": "libs/mylib/src/index.ts",
"assets": ["libs/mylib/*.md"]
}
}
}
}
"myapp": "apps/myapp"
}
}
```
### Projects
- `"version": 2` tells Nx that we are using Nx's format for the `workspace.json` file.
- `projects` is a map of project name to either the project location, or its configuration. (see `project.json`)[(#project-json)]
The `projects` property configures all apps and libs.
> This file is optional as of Nx v13.3.
> To convert an existing repository to use standalone configurations, run `nx g convert-to-nx-project --all`
For instance, the following configures `mylib`.
#### Version 1 vs Version 2
- Version 1 workspaces do not support standalone configuration (`project.json` files), so all of the entries in projects are inline configurations.
- In Version 1 workspaces the `targets` property is replaced with `architect` in project configuration
- In Version 1 workspaces the `executor` property on a target is replaced with `executor`
- In Version 1 workspaces the `generators` property used to define generator defaults for a project is replaced with `schematics`
> To upgrade to version 2, change the version number to 2 and run `nx format`.
### project.json
The `project.json` file contains configuration specific to it's project. Lets look at the following example:
```json
{
"mylib": {
"root": "libs/mylib/",
"sourceRoot": "libs/mylib/src",
"projectType": "library",
"targets": {},
"tags": [],
"implicitDependencies": []
}
"root": "libs/mylib/",
"sourceRoot": "libs/mylib/src",
"projectType": "library",
"targets": {},
"tags": [],
"implicitDependencies": []
}
```
- `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` configures all the targets which define what tasks you can run against the library.
- `architect` configures all the targets which define what tasks you can run against the library.
- `tags` configures tags used for linting
- `implicitDependencies` configure implicit dependencies between projects in the workspace ([see below](#implicit-dependencies))
> Projects utilizing `project.json` files are not present in `workspace.json`.
The contents of `project.json` can be inlined into workspace.json by replacing the project location with the contents file. For example, in `workspace.json`, you could have something like:
### Targets
```jsonc
{
// ... other configuration
"projects": {
// ... other (poterntially standalone) projects
"my-inline-project": {
"root": "apps/my-inline-project"
//... other project configuration
}
}
}
```
Let's look at the simple target:
> In workspaces without `workspace.json` or `angular.json`, a `project.json` is optional for your project if it already has a `package.json`. Instead, its configuration is inferred based on its `package.json` as described below.
#### Targets
Let's look at a sample test target:
```json
{
"test": {
"executor": "@nrwl/jest:jest",
"options": {
"jestConfig": "libs/mylib/jest.config.js"
"jestConfig": "libs/mylib/jest.config.js",
"tsConfig": "libs/mylib/tsconfig.spec.json"
}
}
}
@ -123,7 +91,7 @@ Let's look at the simple target:
**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 run as follows: `nx mytest mylib` or `nx run mylib:mytest`.
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**
@ -131,11 +99,12 @@ The `executor` property tells Nx what function to invoke when you run the target
**Options**
The `options` provides a map of values that are passed to the executor. The provided command line args are merged into this map. For example, `nx test mylib --jestConfig=libs/mylib/another-jest.config.js` passes the following to the executor:
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"
"jestConfig": "libs/mylib/another-jest.config.js",
"tsConfig": "libs/mylib/tsconfig.spec.json"
}
```
@ -146,13 +115,11 @@ The `outputs` property lists the folders the executor creates files in. The prop
```json
{
"build": {
"executor": "@nrwl/node:package",
"executor": "@nrwl/web:webpack",
"outputs": ["dist/apps/myapp"],
"options": {
"outputPath": "dist/libs/mylib",
"tsConfig": "libs/mylib/tsconfig.lib.json",
"packageJson": "libs/mylib/package.json",
"main": "libs/mylib/src/index.ts",
"assets": ["libs/mylib/*.md"]
"index": "apps/myapp/src/app.html",
"main": "apps/myapp/src/main.ts"
}
}
}
@ -160,33 +127,31 @@ The `outputs` property lists the folders the executor creates files in. The prop
**Configurations**
The `configurations` property provides extra sets of values that are merged into the options map.
The `configurations` property provides extra sets of values that will be merged into the options map.
```json
{
"build": {
"executor": "@nrwl/node:package",
"executor": "@nrwl/web:webpack",
"outputs": ["dist/apps/myapp"],
"options": {
"outputPath": "dist/libs/mylib",
"tsConfig": "libs/mylib/tsconfig.lib.json",
"packageJson": "libs/mylib/package.json",
"main": "libs/mylib/src/index.ts",
"assets": ["libs/mylib/*.md"]
}
},
"configurations": {
"production": {
"packageJson": "libs/mylib/package.prod.json"
"index": "apps/myapp/src/app.html",
"main": "apps/myapp/src/main.ts"
},
"configurations": {
"production": {
"optimization": true
}
}
}
}
```
You can select a configuration like this: `nx build mylib --configuration=production` or `nx run mylib:build:configuration=production`.
You can select a configuration like this: `nx build myapp --configuration=production` or `nx run myapp:build:configuration=production`.
The following show how the executor options get constructed:
```bash
```javascript
require(`@nrwl/jest`).executors['jest']({...options, ...selectedConfiguration, ...commandLineArgs}}) // Pseudocode
```
@ -199,7 +164,7 @@ Targets can depend on other targets. A common scenario is having to build depend
```json
{
"build": {
"executor": "@nrwl/node:build",
"executor": "@nrwl/web:webpack",
"outputs": ["dist/apps/myapp"],
"options": {
"index": "apps/myapp/src/app.html",
@ -224,7 +189,7 @@ In the following example invoking `nx build myapp` builds all the libraries firs
```json
{
"build-base": {
"executor": "@nrwl/node:build",
"executor": "@nrwl/web:webpack",
"outputs": ["dist/apps/myapp"],
"options": {
"index": "apps/myapp/src/app.html",
@ -252,36 +217,48 @@ In the following example invoking `nx build myapp` builds all the libraries firs
Often the same `dependsOn` configuration has to be defined for every project in the repo. You can define it once in `nx.json` (see below).
### Version
### package.json
When the `version` of `workspace.json` is set to 2, `targets`, `generators` and `executor` properties are used instead of the version 1 properties `architect`, `schematics` and `builder`.
Nx also infers additional project targets from scripts defined in it's `package.json` file, if it exists. For example, you may have a package.json in the root of your lib like this:
## project.json
Project configurations can also be independent files, referenced by `workspace.json`. For instance, a `workspace.json` may contain projects configured as below.
```json
```jsonc
{
"projects": {
"mylib": "libs/mylib"
"name": "@company/my-lib",
"scripts": {
"clean": "echo 1" // the actual command here is arbitrary
}
}
```
This tells Nx that all configuration for that project is found in the `libs/mylib/project.json` file.
This would lead to Nx being able to run the clean script, just like a target in `project.json`. You could run `nx clean my-lib` in this instance.
```json
Targets inferred from `package.json` scripts are ran using the `@nrwl/workspace:run-script` executor, with the project's root as the current working directory.
> Targets inside `package.json` are overwritten if a target inside `project.json` has the same name.
Additional target configuration options such as those described in [targets](#targets) above can be defined for targets that are inferred from `package.json`. Here is an example for defining custom outputs to be able to cache an inferred test target:
```jsonc
{
"root": "libs/mylib/",
"sourceRoot": "libs/mylib/src",
"projectType": "library",
"targets": {},
"tags": [],
"implicitDependencies": []
"name": "@company/my-lib",
"scripts": {
"test": "run-my-tests"
},
"nx": {
"targets": {
"test": {
"outputs": ["packages/my-lib/coverage"]
}
}
}
}
```
## nx.json
All of the options except `executor` are availble here.
## Workspace Configuration
### nx.json
The `nx.json` file contains extra configuration options mostly related to the project graph.
@ -308,17 +285,22 @@ The `nx.json` file contains extra configuration options mostly related to the pr
"tsconfig.base.json": "*",
"nx.json": "*"
},
"cli": {
"defaultCollection": "@nrwl/node"
"targetDependencies": {
"build": [
{
"target": "build",
"projects": "dependencies"
}
]
},
"generators": {
"@nrwl/node:library": {
"js": true
}
"cli": {
"defaultCollection": "@nrwl/web"
}
}
```
> Projects utilizing `project.json` files will not be present in `nx.json`.
**NPM Scope**
Tells Nx what prefix to use when generating library imports.
@ -338,7 +320,7 @@ Tasks runners are invoked when you run `nx test`, `nx build`, `nx run-many`, `nx
Tasks runners can accept different options. The following are the options supported by `"@nrwl/workspace/tasks-runners/default"` 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`).
- `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.
@ -364,6 +346,21 @@ Tasks runners can accept different options. The following are the options suppor
You can configure `parallel` in `nx.json`, but you can also pass them in the terminal `nx run-many --target=test --parallel=5`.
### 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.
### 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 dependencies between shared files and projects cannot be inferred statically. You can configure those using `implicitDependencies`.
@ -414,8 +411,6 @@ You can also add dependencies between projects in `workspace.json`. For instance
}
```
> Projects utilizing `project.json` files are not present in `nx.json`.
### 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 `workspace.json` can be used to define the list of dependencies of an individual target.
@ -439,38 +434,6 @@ The configuration above is identical to adding `{"dependsOn": [{"target": "build
The `dependsOn` property in `workspace.json` takes precedence over the `targetDependencies` in `nx.json`.
### Generators
Default generator options are configured in `nx.json` as well. For instance, the following tells Nx to always pass `--js` when creating new libraries.
```json
{
"generators": {
"@nrwl/node:library": {
"buildable": true
}
}
}
```
You can also do it on the project level in workspace.json or project.json:
```json
{
"mylib": {
"root": "libs/mylib/",
"sourceRoot": "libs/mylib/src",
"projectType": "library",
"generators": {
"@nrwl/node:lib": {
"moreOptions": true
}
},
"targets": {}
}
}
```
### CLI Options
The following command generates a new library: `nx g @nrwl/node:lib mylib`. After setting the `defaultCollection` property, the lib is generated without mentioning the collection name: `nx g lib mylib`.
@ -483,6 +446,20 @@ The following command generates a new library: `nx g @nrwl/node:lib mylib`. Afte
}
```
### 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/node:library": {
"buildable": true
}
}
}
```
## .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.
@ -505,7 +482,7 @@ Projects can be moved or renamed using the [@nrwl/workspace:move](/{{framework}}
For instance, if a library under the booking folder is now being shared by multiple apps, you can move it to the shared folder like this:
```bash
nx g @nrwl/workspace:move --project booking-some-library shared/some-library
nx g @nrwl/node:move --project booking-some-library shared/some-library
```
### Removing projects
@ -525,3 +502,26 @@ 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.
## Recent Changes
### v13.3.0
- `workspace.json` is now optional
- projects can be inferred completely from `package.json` if `workspace.json` not present
- Targets are now merged from `package.json` instead of only being used if the project has no targets defined.
- Targets inferred from `package.json` can now have an extended configuration. See [above](#package-json)
### v13.0.0
Some settings were moved between `workspace.json`/`project.json` and `nx.json`.
- tags / implicit dependencies are no longer in `nx.json` were moved from `nx.json` to project configuration.
- `cli` and `defaultProject` moved to `nx.json` from `workspace.json`
- Non-project specific generator defaults in `workspace.json` via the `generators`/`schematics` property moved to `nx.json`
### v12.4.0
Standalone configuration and `project.json` introduced. See [above](#project-json)
- tags / implicit dependencies are no longer in `nx.json` for projects using `project.json`.

159
nx-dev/nx-dev/public/documentation/latest/react/api-angular/generators/scam.md Normal file
View File

@ -0,0 +1,159 @@
# @nrwl/angular:scam
Generate a component with an accompanying Single Angular Module Component (SCAM).
## Usage
```bash
nx generate scam ...
```
By default, Nx will search for `scam` in the default collection provisioned in `workspace.json`.
You can specify the collection explicitly as follows:
```bash
nx g @nrwl/angular:scam ...
```
Show what will be generated without writing to disk:
```bash
nx g scam ... --dry-run
```
## Options
### name (_**required**_)
Type: `string`
The name of the component.
### changeDetection
Alias(es): c
Default: `Default`
Type: `string`
Possible values: `Default`, `OnPush`
The change detection strategy to use in the new component.
### displayBlock
Alias(es): b
Default: `false`
Type: `boolean`
Specifies if the style will contain `:host { display: block; }`.
### flat
Default: `false`
Type: `boolean`
Create the new files at the top level of the current project.
### inlineScam
Default: `true`
Type: `boolean`
Create the NgModule in the same file as the Component.
### inlineStyle
Alias(es): s
Default: `false`
Type: `boolean`
Include styles inline in the component.ts file. Only CSS styles can be included inline. By default, an external styles file is created and referenced in the component.ts file.
### inlineTemplate
Alias(es): t
Default: `false`
Type: `boolean`
Include template inline in the component.ts file. By default, an external template file is created and referenced in the component.ts file.
### path (**hidden**)
Type: `string`
The path at which to create the component file, relative to the current workspace. Default is a folder with the same name as the component in the project root.
### prefix
Alias(es): p
Type: `string`
The prefix to apply to the generated component selector.
### project
Type: `string`
The name of the project.
### selector
Type: `string`
The HTML selector to use for this component.
### skipSelector
Default: `false`
Type: `boolean`
Specifies if the component should have a selector or not.
### skipTests
Default: `false`
Type: `boolean`
Do not create "spec.ts" test files for the new component.
### style
Default: `css`
Type: `string`
Possible values: `css`, `scss`, `sass`, `less`, `none`
The file extension or preprocessor to use for style files, or 'none' to skip generating the style file.
### type
Default: `Component`
Type: `string`
Adds a developer-defined type to the filename, in the format "name.type.ts".
### viewEncapsulation
Alias(es): v
Type: `string`
Possible values: `Emulated`, `None`, `ShadowDom`
The view encapsulation strategy to use in the new component.

674
nx-dev/nx-dev/public/documentation/latest/react/guides/configuration.md
View File

@ -1,16 +1,266 @@
# Configuration
Two configuration files you see in most Nx workspaces are `nx.json` and `workspace.json`. Many Nx plugins modify these
files when generating new code, but you can also modify them manually.
There are two main types of configuration in every Nx workspace: [project configuration](#project-configuration) and [workspace configuration](#workspace-configuration). Project configuration consists of `workspace.json`, `**/project.json`, and `**/package.json`. Workspace configuration consists of `nx.json` and `tsconfig.base.json`.
- `nx.json` contains the global configuration. It contains the configuration of the Nx CLI itself: what is cached, how
to execute your tasks. That's where you configure global implicit dependencies, default base branch etc.
- `workspace.json` lists the workspace projects either alongside with their configuration or pointing to `project.json`
files contains that configuration.
Many Nx plugins modify these files when generating new code, but you can also modify them manually.
## nx.json
## Project Configuration
This is an example of the `nx.json` file. Most items configured are optional and your `nx.json` is likely to be shorter.
### workspace.json
The `workspace.json` file contains a list of project configurations, as well as the version of your workspace. Let's look at the following example:
```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 name to either the project location, or its configuration. (see `project.json`)[(#project-json)]
> This file is optional as of Nx v13.3.
> To convert an existing repository to use standalone configurations, run `nx g convert-to-nx-project --all`
#### Version 1 vs Version 2
- Version 1 workspaces do not support standalone configuration (`project.json` files), so all of the entries in projects are inline configurations.
- In Version 1 workspaces the `targets` property is replaced with `architect` in project configuration
- In Version 1 workspaces the `executor` property on a target is replaced with `executor`
- In Version 1 workspaces the `generators` property used to define generator defaults for a project is replaced with `schematics`
> To upgrade to version 2, change the version number to 2 and run `nx format`.
### project.json
The `project.json` file contains configuration specific to it's project. Lets look at the following example:
```json
{
"root": "libs/mylib/",
"sourceRoot": "libs/mylib/src",
"projectType": "library",
"targets": {},
"tags": [],
"implicitDependencies": []
}
```
- `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.
- `architect` configures all the targets which define what tasks you can run against the library.
- `tags` configures tags used for linting
- `implicitDependencies` configure implicit dependencies between projects in the workspace ([see below](#implicit-dependencies))
The contents of `project.json` can be inlined into workspace.json by replacing the project location with the contents file. For example, in `workspace.json`, you could have something like:
```jsonc
{
// ... other configuration
"projects": {
// ... other (poterntially standalone) projects
"my-inline-project": {
"root": "apps/my-inline-project"
//... other project configuration
}
}
}
```
> In workspaces without `workspace.json` or `angular.json`, a `project.json` is optional for your project if it already has a `package.json`. Instead, its configuration is inferred based on its `package.json` as described below.
#### Targets
Let's look at a sample test target:
```json
{
"test": {
"executor": "@nrwl/jest:jest",
"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"
}
```
**Outputs**
The `outputs` property lists the folders the executor creates files in. The property is optional. If not provided, Nx assumes it is `dist/libs/mylib`.
```json
{
"build": {
"executor": "@nrwl/web:webpack",
"outputs": ["dist/apps/myapp"],
"options": {
"index": "apps/myapp/src/app.html",
"main": "apps/myapp/src/main.ts"
}
}
}
```
**Configurations**
The `configurations` property provides extra sets of values that will be merged into the options map.
```json
{
"build": {
"executor": "@nrwl/web:webpack",
"outputs": ["dist/apps/myapp"],
"options": {
"index": "apps/myapp/src/app.html",
"main": "apps/myapp/src/main.ts"
},
"configurations": {
"production": {
"optimization": true
}
}
}
}
```
You can select a configuration like this: `nx build myapp --configuration=production` or `nx run myapp: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.
**Target Dependencies**
Targets can depend on other targets. A common scenario is having to build dependencies of a project first before building the project. You can specify this using the `dependsOn`.
```json
{
"build": {
"executor": "@nrwl/web:webpack",
"outputs": ["dist/apps/myapp"],
"options": {
"index": "apps/myapp/src/app.html",
"main": "apps/myapp/src/main.ts"
},
"dependsOn": [
{
"target": "build",
"projects": "dependencies"
}
]
}
}
```
In this case, running `nx build myapp` builds all the buildable libraries `myapp` depends on first. In other words, `nx build myapp` results in multiple tasks executing. The `--parallel` flag has the same effect as they would with `run-many` or `affected`.
It is also possible to define dependencies between the targets of the same project.
In the following example invoking `nx build myapp` builds all the libraries first, then `nx build-base myapp` is executed and only then `nx build myapp` is executed.
```json
{
"build-base": {
"executor": "@nrwl/web:webpack",
"outputs": ["dist/apps/myapp"],
"options": {
"index": "apps/myapp/src/app.html",
"main": "apps/myapp/src/main.ts"
}
},
"build": {
"executor": "@nrwl/workspace:run-commands",
"dependsOn": [
{
"target": "build",
"projects": "dependencies"
},
{
"target": "build-base",
"projects": "self"
}
],
"options": {
"command": "./copy-readme-and-license.sh"
}
}
}
```
Often the same `dependsOn` configuration has to be defined for every project in the repo. You can define it once in `nx.json` (see below).
### package.json
Nx also infers additional project targets from scripts defined in it's `package.json` file, if it exists. For example, you may have a package.json in the root of your lib like this:
```jsonc
{
"name": "@company/my-lib",
"scripts": {
"clean": "echo 1" // the actual command here is arbitrary
}
}
```
This would lead to Nx being able to run the clean script, just like a target in `project.json`. You could run `nx clean my-lib` in this instance.
Targets inferred from `package.json` scripts are ran using the `@nrwl/workspace:run-script` executor, with the project's root as the current working directory.
> Targets inside `package.json` are overwritten if a target inside `project.json` has the same name.
Additional target configuration options such as those described in [targets](#targets) above can be defined for targets that are inferred from `package.json`. Here is an example for defining custom outputs to be able to cache an inferred test target:
```jsonc
{
"name": "@company/my-lib",
"scripts": {
"test": "run-my-tests"
},
"nx": {
"targets": {
"test": {
"outputs": ["packages/my-lib/coverage"]
}
}
}
}
```
All of the options except `executor` are availble here.
## Workspace Configuration
### nx.json
The `nx.json` file contains extra configuration options mostly related to the project graph.
```json
{
@ -44,21 +294,18 @@ This is an example of the `nx.json` file. Most items configured are optional and
]
},
"cli": {
"defaultCollection": "@nrwl/react"
},
"generators": {
"@nrwl/react:library": {
"js": true
}
"defaultCollection": "@nrwl/web"
}
}
```
### NPM Scope
> Projects utilizing `project.json` files will not be present in `nx.json`.
Tells Nx what prefix to use when generating imports.
**NPM Scope**
### Affected
Tells Nx what prefix to use when generating library imports.
**Affected**
Tells Nx which branch and HEAD to use when calculating affected projects.
@ -66,24 +313,20 @@ Tells Nx which branch and HEAD to use when calculating affected projects.
### Tasks Runner Options
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 by passing `--runner`.
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 by passing `--runner`.
Tasks runners can accept different options. The following are the options supported
by `"@nrwl/workspace/tasks-runners/default"` and `"@nrwl/nx-cloud"`.
> A task is an invocation of a target.
Tasks runners can accept different options. The following are the options supported by `"@nrwl/workspace/tasks-runners/default"` 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`
- `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:
@ -101,14 +344,26 @@ by `"@nrwl/workspace/tasks-runners/default"` and `"@nrwl/nx-cloud"`.
}
```
You can configure `parallel` in `nx.json`, but you can also pass it when invoking a
command `nx run-many --target=test --parallel=5`.
You can configure `parallel` in `nx.json`, but you can also pass them in the terminal `nx run-many --target=test --parallel=5`.
### 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.
### 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 dependencies between shared
files and projects cannot be inferred statically. You can configure those using `implicitDependencies`.
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 dependencies between shared files and projects cannot be inferred statically. You can configure those using `implicitDependencies`.
```json
{
@ -138,9 +393,7 @@ In the example above:
- Changing `globalFile` only affects `myapp`.
- Changing any CSS file inside the `styles` directory only affects `myapp`.
You can also add dependencies between projects in `workspace.json` or `project.json`. For instance, the example below
defines a dependency from `myapp-e2e` to `myapp`, such that every time `myapp` is affected, `myapp-e2e` is affected as
well.
You can also add dependencies between projects in `workspace.json`. For instance, the example below defines a dependency from `myapp-e2e` to `myapp`, such that every time `myapp` is affected, `myapp-e2e` is affected as well.
```jsonc
{
@ -160,12 +413,9 @@ well.
### 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 `workspace.json` can be used to define the list of dependencies of an
individual target.
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 `workspace.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.
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
{
@ -180,48 +430,13 @@ defining `targetDependencies` in `nx.json` is helpful.
}
```
The configuration above is identical to adding `{"dependsOn": [{"target": "build", "projects": "dependencies"]}` to
every build target in `workspace.json`.
The configuration above is identical to adding `{"dependsOn": [{"target": "build", "projects": "dependencies"]}` to every build target in `workspace.json`.
The `dependsOn` property in `workspace.json` takes precedence over the `targetDependencies` in `nx.json`.
### Generators
Default generator options are configured in `workspace.json` as well. For instance, the following tells Nx to always
pass `--js` when creating new libraries.
```json
{
"generators": {
"@nrwl/react:library": {
"js": true
}
}
}
```
You can also do it on the project level:
```json
{
"mylib": {
"root": "libs/mylib/",
"sourceRoot": "libs/mylib/src",
"projectType": "library",
"generators": {
"@nrwl/react:component": {
"classComponent": true
}
},
"targets": {}
}
}
```
### CLI Options
The following command generates a new library: `nx g @nrwl/react:lib mylib`. After setting the `defaultCollection`
property, the lib is generated without mentioning the collection name: `nx g lib mylib`.
The following command generates a new library: `nx g @nrwl/react:lib mylib`. After setting the `defaultCollection` property, the lib is generated without mentioning the collection name: `nx g lib mylib`.
```json
{
@ -231,256 +446,15 @@ property, the lib is generated without mentioning the collection name: `nx g lib
}
```
## workspace.json and project.json
### Generators
The `workspace.json` lists the workspace projects. Let's look at an example:
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
{
"version": 2,
"projects": {
"myapp": "apps/myapp",
"mylib": "libs/mylib"
}
}
```
This tells Nx that all configuration for the `myapp` project is found in the `apps/myapp/project.json` file, and the
configuration for `mylib` is found in the `libs/mylib/project.json`.
This is an example of `apps/myapp/project.json`:
```json
{
"root": "apps/myapp/",
"sourceRoot": "apps/myapp/src",
"projectType": "application",
"targets": {
"build": {
"executor": "@nrwl/web:webpack",
"outputs": ["dist/apps/myapp"],
"dependsOn": [
{
"target": "build",
"projects": "dependencies"
}
],
"options": {
"index": "apps/myapp/src/app.html",
"main": "apps/myapp/src/main.ts"
},
"configurations": {
"production": {
"optimization": true
}
}
},
"serve": {
"executor": "@nrwl/web:dev-server",
"options": {
"buildTarget": "myapp:build",
"proxyConfig": "apps/myapp/proxy.conf.json"
}
},
"test": {
"executor": "@nrwl/jest:jest",
"options": {
"jestConfig": "apps/myapp/jest.config.js",
"tsConfig": "apps/myapp/tsconfig.spec.json"
}
}
}
}
```
_Note, the `targets` section is there because we use the `@nrwl/web` and `@nwrl/jest` plugins. If we choose to use
[Nx Core without plugins](/{{framework}}/getting-started/nx-core), the `targets` section will not there. Often `targets`
replace other config files we would have had otherwise. For instance, the `build`
and `serve`
targets above replace ad-hoc webpack configuration files and corresponding npm scripts._
**Options**
- `root` tells Nx the location of the project including its sources and configuration files.
- `sourceRoot` tells Nx the location of the project'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` configures all the targets which define what tasks you can run against the project.
- `tags` configures tags used for linting
- `implicitDependencies` configure implicit dependencies between projects in the
workspace ([see below](#implicit-dependencies))
**Targets**
Let's look at the simple target:
```json
{
"test": {
"executor": "@nrwl/jest:jest",
"options": {
"jestConfig": "apps/myapp/jest.config.js",
"tsConfig": "apps/myapp/tsconfig.spec.json"
}
}
}
```
**Target Name**
The name of the target `test` means that you can invoke it as follows: `nx test myapp` or `nx run myapp:test`. The name
isn't significant in any other way. If you rename it to, for example, `mytest`, you run as follows: `nx mytest myapp`
or `nx run myapp: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 are passed to the executor. The provided command line args are merged into
this map. For example, `nx test myapp --jestConfig=libs/myapp/another-jest.config.js` passes the following to the
executor:
```json
{
"jestConfig": "libs/mylib/another-jest.config.js",
"tsConfig": "libs/mylib/tsconfig.spec.json"
}
```
**Outputs**
The `outputs` property lists the folders the executor creates files in. The property is optional. If not provided, Nx
assumes it is `dist/apps/myapp`.
**Configurations**
The `configurations` property provides extra sets of values that are merged into the options map.
```json
{
"build": {
"executor": "@nrwl/web:webpack",
"outputs": ["dist/apps/myapp"],
"options": {
"index": "apps/myapp/src/app.html",
"main": "apps/myapp/src/main.ts"
},
"configurations": {
"production": {
"optimization": true
}
}
}
}
```
You can select a configuration like this: `nx build myapp --configuration=production`
or `nx run myapp:build:configuration=production`.
The following show how the executor options get constructed:
```bash
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.
**Target Dependencies**
Targets can depend on other targets. A common scenario is having to build dependencies of a project first before
building the project. You can specify this using the `dependsOn`.
```json
{
"build": {
"executor": "@nrwl/web:webpack",
"outputs": ["dist/apps/myapp"],
"options": {
"index": "apps/myapp/src/app.html",
"main": "apps/myapp/src/main.ts"
},
"dependsOn": [
{
"target": "build",
"projects": "dependencies"
}
]
}
}
```
In this case, running `nx build myapp` builds all the buildable libraries `myapp` depends on first. In other
words, `nx build myapp` results in multiple tasks executing. The `--parallel` flag has the same
effect as they would with `run-many` or `affected`.
It is also possible to define dependencies between the targets of the same project.
In the following example invoking `nx build myapp` builds all the libraries first, then `nx build-base myapp` is
executed and only then `nx build myapp` is executed.
```json
{
"build-base": {
"executor": "@nrwl/web:webpack",
"outputs": ["dist/apps/myapp"],
"options": {
"index": "apps/myapp/src/app.html",
"main": "apps/myapp/src/main.ts"
}
},
"build": {
"executor": "@nrwl/workspace:run-commands",
"dependsOn": [
{
"target": "build",
"projects": "dependencies"
},
{
"target": "build-base",
"projects": "self"
}
],
"options": {
"command": "./copy-readme-and-license.sh"
}
}
}
```
Often the same `dependsOn` configuration has to be defined for every project in the repo. Define it globally once
in `nx.json` (see below).
### workspace.json without project.json
The `project.json` files can be inlined into `workspace.json`, and that was the default before Nx 13.
The `workspace.json` file above can look like this:
```json
{
"version": 2,
"projects": {
"myapp": {
"root": "apps/myapp/",
"sourceRoot": "apps/myapp/src",
"projectType": "application",
"targets": {
"build": {
//...
},
"serve": {
//...
},
"test": {
//...
}
},
"mylib": {
//...
}
"generators": {
"@nrwl/react:library": {
"buildable": true
}
}
}
@ -488,31 +462,28 @@ The `workspace.json` file above can look like this:
## .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.
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).
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: **
**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.
## Keeping the configuration in sync
When creating projects, the Nx generators make sure these configuration files are updated accordingly for the new
projects. While development continues and the workspace grows, you might need to refactor projects by renaming them,
moving them to a different folder, removing them, etc. When this is done manually, you need to ensure your configuration
files are kept in sync and that's a cumbersome task. Fortunately, Nx provides some generators and executors to help you
with these tasks.
When creating projects, the Nx generators make sure these configuration files are updated accordingly for the new projects. While development continues and the workspace grows, you might need to refactor projects by renaming them, moving them to a different folder, removing them, etc. When this is done manually, you need to ensure your configuration files are kept in sync and that's a cumbersome task. Fortunately, Nx provides some generators and executors to help you with these tasks.
### Moving projects
Projects can be moved or renamed using the [@nrwl/workspace: move](/{{framework}}/workspace/move) generator.
Projects can be moved or renamed using the [@nrwl/workspace:move](/{{framework}}/workspace/move) generator.
For instance, if a library under the booking folder is now being shared by multiple apps, you can move it to the shared
folder like this: `bash nx g @nrwl/workspace: move --project booking-some-library shared/some-library`
For instance, if a library under the booking folder is now being shared by multiple apps, you can move it to the shared folder like this:
```bash
nx g @nrwl/react:move --project booking-some-library shared/some-library
```
### Removing projects
@ -524,12 +495,33 @@ nx g @nrwl/workspace:remove booking-some-library
### 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:
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.
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.
## Recent Changes
### v13.3.0
- `workspace.json` is now optional
- projects can be inferred completely from `package.json` if `workspace.json` not present
- Targets are now merged from `package.json` instead of only being used if the project has no targets defined.
- Targets inferred from `package.json` can now have an extended configuration. See [above](#package-json)
### v13.0.0
Some settings were moved between `workspace.json`/`project.json` and `nx.json`.
- tags / implicit dependencies are no longer in `nx.json` were moved from `nx.json` to project configuration.
- `cli` and `defaultProject` moved to `nx.json` from `workspace.json`
- Non-project specific generator defaults in `workspace.json` via the `generators`/`schematics` property moved to `nx.json`
### v12.4.0
Standalone configuration and `project.json` introduced. See [above](#project-json)
- tags / implicit dependencies are no longer in `nx.json` for projects using `project.json`.

24
nx-dev/nx-dev/public/documentation/latest/shared/generators/composing-generators.md
View File

@ -16,3 +16,27 @@ export default async function (tree: Tree, schema: any) {
);
}
```
## Using jscodeshift Codemods
Codemods created for use with [`jscodeshift`](https://github.com/facebook/jscodeshift) can be used within Nx Devkit generators using the `visitNotIgnoredFiles` helper function. This way you can compose codemods with other generators while retaining `--dry-run` and Nx Console compatibilities.
```typescript
import { Tree, visitNotIgnoredFiles } from '@nrwl/devkit';
import { applyTransform } from 'jscodeshift/src/testUtils';
import arrowFunctionsTransform from './arrow-functions';
// The schema path can be an individual file or a directory
export default async function (tree: Tree, schema: { path: string }): any {
visitNotIgnoredFiles(tree, schema.path, (filePath) => {
const input = tree.read(filePath).toString();
const transformOptions = {};
const output = applyTransform(
{ default: arrowFunctionsTransform, parser: 'ts' },
transformOptions,
{ source: input, path: filePath }
);
tree.write(filePath, output);
});
}
```

4
nx-dev/nx-dev/public/documentation/latest/shared/guides/lerna-and-nx.md
View File

@ -208,6 +208,10 @@ The following 10-min video walks you through the steps of adding Nx to a Lerna r
offers. Although the video uses Lerna, everything said applies to Yarn Workspaces or PNPM. Basically, any time you
hear "Lerna" you can substitute it for Yarn or PNPM.
When running `npx add-nx-to-monorepo`, a `workspace.json` file is not required (nor created by default). Instead, Nx is able
to infer the projects in your repository by looking for existing `package.json` files. These can be mixed with `project.json`
files and traditional configuration settings described in the [configuration guide]({{framework}}/configuration).
<iframe width="560" height="315" src="https://www.youtube.com/embed/BO1rwynFBLM" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
## Clarifying Misconceptions