cleanup(docs): update terminology for docs related to nx/devkit

This commit is contained in:
Isaac Mann 2020-12-04 12:29:11 -05:00 committed by Victor Savkin
parent 056f4eb20e
commit 35015dd891
34 changed files with 143 additions and 139 deletions

View File

@ -24,7 +24,7 @@ Source code and documentation are included in the top-level folders listed below
- `docs` - Markdown and configuration files for documentation including tutorials, guides for each supported platform, and API docs.
- `e2e` - E2E tests.
- `packages` - Source code for Nx packages such as Angular, React, Web, NestJS, Next and others including schematics and builders.
- `packages` - Source code for Nx packages such as Angular, React, Web, NestJS, Next and others including generators and executors (or builders).
- `scripts` - Miscellaneous scripts for project tasks such as building documentation, testing, and code formatting.
- `tmp` - Folder used by e2e tests. If you are a WebStorm user, make sure to mark this folder as excluded.
@ -185,7 +185,7 @@ Including the issue number that the PR relates to also helps with tracking.
#### Example
```
feat(schematics): add an option to generate lazy-loadable modules
feat(generators): add an option to generate lazy-loadable modules
`nx generate lib mylib --lazy` provisions the mylib project in tslint.json

View File

@ -1,15 +1,15 @@
# generate
Runs a schematic that generates and/or modifies files based on a schematic from a collection.
Runs a generator that creates and/or modifies files based on a generator from a collection.
## Usage
```bash
nx generate <collection:schematic>
nx generate <collection:generator>
```
```bash
nx g <schematic>
nx g <generator>
```
Install the `nx` package globally to invoke the command directly using `nx`, or use `npm run nx` or `yarn nx`.
@ -86,7 +86,7 @@ When false, disables interactive input prompts.
### help
Show help and display available schematics in the default collection.
Show help and display available generators in the default collection.
### version

View File

@ -42,7 +42,7 @@ Nx provides tools to give you the benefits of a monorepo without the drawbacks o
### Scaling Your Organization
- **Controlled Code Sharing** - You can define libraries with specific enforced APIs and put rules in place to define how those libraries can depend on each other. A CODEOWNERS file can be used to restrict who is allowed to change files in each project.
- **Consistent Code Generation** - Schematics allow you to automate code creation and modification tasks. Instead of writing a 7 step guide in a readme file, you can create a schematic to prompt the developer for inputs and then modify the code directly. Nrwl provides plugins which contain useful builders and schematics for a lot of popular tools. Also, there is a growing number of community provided plugins.
- **Consistent Code Generation** - Generators allow you to automate code creation and modification tasks. Instead of writing a 7 step guide in a readme file, you can create a generator to prompt the developer for inputs and then modify the code directly. Nrwl provides plugins which contain useful executors and generators for a lot of popular tools. Also, there is a growing number of community provided plugins.
- **Accurate Architecture Diagram** - Most architecture diagrams are wrong the moment they are written down. And every diagram becomes out of date as soon as the code changes. Since Nx understands your code, it can generate an up-to-date and accurate diagram of how projects depend on each other. And for cases where dependencies are not explicit in the code, you can manually tell Nx about project dependencies.
## Next Steps

View File

@ -53,26 +53,26 @@ If you don't have the Nx CLI installed globally, you can invoke `nx` using `yarn
The Nx CLI has an advanced code generator. With it, you can generate new applications, libraries, components, state management utilities. You can change existing applications. And, because the Nx CLI comes with an implementation of a virtual file system, you can preview the changes without affecting anything on disk.
The code generation recipes are called schematics. Schematics provide the underlying APIs for scaffolding, and utilities to automate changes to your filesystem. The example below is the command to generate a new application.
The code generation recipes are called generators. Generators provide the underlying APIs for scaffolding, and utilities to automate changes to your filesystem. The example below is the command to generate a new application.
```sh
nx generate @nrwl/angular:application myapp
```
The `@nrwl/angular` package contains a collection of schematics, with `application` being the one used in this example. The Nx CLI applies the schematic to your workspace, verifying that the provided options are valid, and the destination files don't already exist. Once the validations are passed, the new files are generated, or existing files are updated. You can also customize the output of the generated application, by passing options to the schematic.
The `@nrwl/angular` package contains a collection of generators, with `application` being the one used in this example. The Nx CLI applies the generator to your workspace, verifying that the provided options are valid, and the destination files don't already exist. Once the validations are passed, the new files are generated, or existing files are updated. You can also customize the output of the generated application, by passing options to the generator.
```sh
nx generate @nrwl/angular:application myapp --style=scss
```
You can preview the changes a schematic makes by using the `--dry-run` option. It will output the potential files created, and/or updated during the execution of the schematic.
You can preview the changes a generator makes by using the `--dry-run` option. It will output the potential files created, and/or updated during the execution of the generator.
**Generate command:**
`nx generate` runs schematics to create or modify code given some inputs from the developer.
`nx generate` runs generators to create or modify code given some inputs from the developer.
- [nx generate](/{{framework}}/cli/generate)
Syntax: `nx generate [plugin]:[schematic-name] [options]`
Syntax: `nx generate [plugin]:[generator-name] [options]`
Example: `nx generate @nrwl/angular:component mycmp --project=myapp`
## Running Tasks

View File

@ -4,7 +4,7 @@ There are three top-level configuration files every Nx workspace has: `angular.j
## angular.json
The `angular.json` configuration file contains information about the targets and schematics. Let's look at the following example:
The `angular.json` configuration file contains information about the targets and generators. Let's look at the following example:
```json
{
@ -172,9 +172,9 @@ require(`@nrwl/jest`).builders['jest']({...options, ...selectedConfiguration, ..
The selected configuration adds/overrides the default options, and the provided command line args add/override the configuration options.
### Schematics
### Generators
You can configure default schematic options in `angular.json` as well. For instance, the following will tell Nx to always pass `--style=scss` when creating new libraries.
You can configure default generator options in `angular.json` as well. For instance, the following will tell Nx to always pass `--style=scss` when creating new libraries.
```json
{

View File

@ -1,6 +1,6 @@
# Migrating from Protractor to Cypress
Nx helps configure your e2e tests for you. When running the Nx schematic to create a new app, you can choose Protractor as an option, but the default is Cypress. If you have an existing set of e2e tests using Protractor and would like to switch to using Cypress, you can follow these steps.
Nx helps configure your e2e tests for you. When running the Nx generator to create a new app, you can choose Protractor as an option, but the default is Cypress. If you have an existing set of e2e tests using Protractor and would like to switch to using Cypress, you can follow these steps.
Let's say your existing app is named `my-awesome-app` and the e2e Protractor tests are located in `my-awesome-app-e2e`.

View File

@ -500,7 +500,7 @@ This change loads the HTML code directly and sets it to the template attribute o
Now, go through each component of the application and make this change. To make sure that youve really modified every component correctly, delete the template cache file (`config/app.templates.js`) that gulp generated earlier.
> In an example like this, its easy enough to make this kind of change by hand. In a larger codebase, doing this manually could be very time-intensive. Youll want to look into an automated tool to do this for you, such as js-codemod or schematics.
> In an example like this, its easy enough to make this kind of change by hand. In a larger codebase, doing this manually could be very time-intensive. Youll want to look into an automated tool to do this for you, such as js-codemod or generators.
Run the application the same way as before:

View File

@ -868,7 +868,7 @@
"file": "angular/api-nx-plugin/generators/plugin"
},
{
"name": "schematic",
"name": "generator",
"id": "schematic",
"file": "angular/api-nx-plugin/generators/generator"
}
@ -909,12 +909,12 @@
"id": "executors",
"itemList": [
{
"name": "Using Builders",
"name": "Using Executors / Builders",
"id": "using-builders",
"file": "shared/using-builders"
},
{
"name": "Run Commands Builder",
"name": "Running Custom Commands",
"id": "run-commands-builder",
"file": "shared/running-custom-commands"
},
@ -935,12 +935,12 @@
"id": "generators",
"itemList": [
{
"name": "Using Schematics",
"name": "Using Generators",
"id": "using-schematics",
"file": "shared/using-schematics"
},
{
"name": "Workspace Schematics",
"name": "Workspace Generators",
"id": "workspace-generators",
"file": "shared/tools-workspace-generators"
}
@ -1961,7 +1961,7 @@
"file": "react/api-nx-plugin/generators/plugin"
},
{
"name": "schematic",
"name": "generator",
"id": "schematic",
"file": "react/api-nx-plugin/generators/generator"
}
@ -2002,12 +2002,12 @@
"id": "executors",
"itemList": [
{
"name": "Using Builders",
"name": "Using Executors / Builders",
"id": "using-builders",
"file": "shared/using-builders"
},
{
"name": "Run Commands Builder",
"name": "Running Custom Commands",
"id": "run-commands-builder",
"file": "shared/running-custom-commands"
},
@ -2028,12 +2028,12 @@
"id": "generators",
"itemList": [
{
"name": "Using Schematics",
"name": "Using Generators",
"id": "using-schematics",
"file": "shared/using-schematics"
},
{
"name": "Workspace Schematics",
"name": "Workspace Generators",
"id": "workspace-generators",
"file": "shared/tools-workspace-generators"
}
@ -3001,7 +3001,7 @@
"file": "node/api-nx-plugin/generators/plugin"
},
{
"name": "schematic",
"name": "generator",
"id": "schematic",
"file": "node/api-nx-plugin/generators/generator"
}
@ -3042,12 +3042,12 @@
"id": "executors",
"itemList": [
{
"name": "Using Builders",
"name": "Using Executors / Builders",
"id": "using-builders",
"file": "shared/using-builders"
},
{
"name": "Run Commands Builder",
"name": "Running Custom Commands",
"id": "run-commands-builder",
"file": "shared/running-custom-commands"
},
@ -3068,12 +3068,12 @@
"id": "generators",
"itemList": [
{
"name": "Using Schematics",
"name": "Using Generators",
"id": "using-schematics",
"file": "shared/using-schematics"
},
{
"name": "Workspace Schematics",
"name": "Workspace Generators",
"id": "workspace-generators",
"file": "shared/tools-workspace-generators"
}

View File

@ -1,15 +1,15 @@
# generate
Runs a schematic that generates and/or modifies files based on a schematic from a collection.
Runs a generator that creates and/or modifies files based on a generator from a collection.
## Usage
```bash
nx generate <collection:schematic>
nx generate <collection:generator>
```
```bash
nx g <schematic>
nx g <generator>
```
Install the `nx` package globally to invoke the command directly using `nx`, or use `npm run nx` or `yarn nx`.
@ -86,7 +86,7 @@ When false, disables interactive input prompts.
### help
Show help and display available schematics in the default collection.
Show help and display available generators in the default collection.
### version

View File

@ -42,7 +42,7 @@ Nx provides tools to give you the benefits of a monorepo without the drawbacks o
### Scaling Your Organization
- **Controlled Code Sharing** - You can define libraries with specific enforced APIs and put rules in place to define how those libraries can depend on each other. A CODEOWNERS file can be used to restrict who is allowed to change files in each project.
- **Consistent Code Generation** - Schematics allow you to automate code creation and modification tasks. Instead of writing a 7 step guide in a readme file, you can create a schematic to prompt the developer for inputs and then modify the code directly. Nrwl provides plugins which contain useful builders and schematics for a lot of popular tools. Also, there is a growing number of community provided plugins.
- **Consistent Code Generation** - Generators allow you to automate code creation and modification tasks. Instead of writing a 7 step guide in a readme file, you can create a generator to prompt the developer for inputs and then modify the code directly. Nrwl provides plugins which contain useful builders and generators for a lot of popular tools. Also, there is a growing number of community provided plugins.
- **Accurate Architecture Diagram** - Most architecture diagrams are wrong the moment they are written down. And every diagram becomes out of date as soon as the code changes. Since Nx understands your code, it can generate an up-to-date and accurate diagram of how projects depend on each other. And for cases where dependencies are not explicit in the code, you can manually tell Nx about project dependencies.
## Next Steps

View File

@ -39,26 +39,26 @@ If you don't have the Nx CLI installed globally, you can invoke `nx` using `yarn
The Nx CLI has an advanced code generator. With it, you can generate new applications, libraries, components, state management utilities. You can change existing applications. And, because the Nx CLI comes with an implementation of a virtual file system, you can preview the changes without affecting anything on disk.
The code generation recipes are called schematics. Schematics provide the underlying APIs for scaffolding, and utilities to automate changes to your filesystem. The example below is the command to generate a new application.
The code generation recipes are called generators. Generators provide the underlying APIs for scaffolding, and utilities to automate changes to your filesystem. The example below is the command to generate a new application.
```sh
nx generate @nrwl/node:application myapp
```
The `@nrwl/node` package contains a collection of schematics, with `application` being the one used in this example. The Nx CLI applies the schematic to your workspace, verifying that the provided options are valid, and the destination files don't already exist. Once the validations are passed, the new files are generated, or existing files are updated. You can also customize the output of the generated application, by passing options to the schematic.
The `@nrwl/node` package contains a collection of generators, with `application` being the one used in this example. The Nx CLI applies the generator to your workspace, verifying that the provided options are valid, and the destination files don't already exist. Once the validations are passed, the new files are generated, or existing files are updated. You can also customize the output of the generated application, by passing options to the generator.
```sh
nx generate @nrwl/node:application myapp --style=scss
```
You can preview the changes a schematic makes by using the `--dry-run` option. It will output the potential files created, and/or updated during the execution of the schematic.
You can preview the changes a generator makes by using the `--dry-run` option. It will output the potential files created, and/or updated during the execution of the generator.
**Generate command:**
`nx generate` runs schematics to create or modify code given some inputs from the developer.
`nx generate` runs generators to create or modify code given some inputs from the developer.
- [nx generate](/{{framework}}/cli/generate)
Syntax: `nx generate [plugin]:[schematic-name] [options]`
Syntax: `nx generate [plugin]:[generator-name] [options]`
Example: `nx generate @nrwl/node:library my-node-lib`
## Running Tasks

View File

@ -4,7 +4,7 @@ There are three top-level configuration files every Nx workspace has: `workspace
## workspace.json
The `workspace.json` configuration file contains information about the targets and schematics. Let's look at the following example:
The `workspace.json` configuration file contains information about the targets and generators. Let's look at the following example:
```json
{
@ -189,9 +189,9 @@ require(`@nrwl/jest`).builders['jest']({...options, ...selectedConfiguration, ..
The selected configuration adds/overrides the default options, and the provided command line args add/override the configuration options.
### Schematics
### Generators
You can configure default schematic options in `workspace.json` as well. For instance, the following will tell Nx to always pass `--js` when creating new libraries.
You can configure default generator options in `workspace.json` as well. For instance, the following will tell Nx to always pass `--js` when creating new libraries.
```json
{

View File

@ -1,15 +1,15 @@
# generate
Runs a schematic that generates and/or modifies files based on a schematic from a collection.
Runs a generator that creates and/or modifies files based on a generator from a collection.
## Usage
```bash
nx generate <collection:schematic>
nx generate <collection:generator>
```
```bash
nx g <schematic>
nx g <generator>
```
Install the `nx` package globally to invoke the command directly using `nx`, or use `npm run nx` or `yarn nx`.
@ -86,7 +86,7 @@ When false, disables interactive input prompts.
### help
Show help and display available schematics in the default collection.
Show help and display available generators in the default collection.
### version

View File

@ -37,12 +37,12 @@ Nx provides tools to give you the benefits of a monorepo without the drawbacks o
### Scaling Your Repo
- **Faster Command Execution** - Builders allow for consistent commands to test, serve, build, lint, etc, each project. [Nxs affected command]() helps run commands only on code that is affected by the current change. Nx provides local and distributed caching of builder commands so when someone on your team runs a command, everyone else will use their artifacts to speed up their own command executions, often bringing them down from minutes to seconds. This, in combination with support for distributed and incremental builds helps you scale your development to massive applications and repositories.
- **Faster Command Execution** - Executors (or builders) allow for consistent commands to test, serve, build, lint, etc, each project. [Nxs affected command]() helps run commands only on code that is affected by the current change. Nx provides local and distributed caching of executors so when someone on your team runs a command, everyone else will use their artifacts to speed up their own command executions, often bringing them down from minutes to seconds. This, in combination with support for distributed and incremental builds helps you scale your development to massive applications and repositories.
### Scaling Your Organization
- **Controlled Code Sharing** - You can define libraries with specific enforced APIs and put rules in place to define how those libraries can depend on each other. A CODEOWNERS file can be used to restrict who is allowed to change files in each project.
- **Consistent Code Generation** - Schematics allow you to automate code creation and modification tasks. Instead of writing a 7 step guide in a readme file, you can create a schematic to prompt the developer for inputs and then modify the code directly. Nrwl provides plugins which contain useful builders and schematics for a lot of popular tools. Also, there is a growing number of community provided plugins.
- **Consistent Code Generation** - Generators allow you to automate code creation and modification tasks. Instead of writing a 7 step guide in a readme file, you can create a generator to prompt the developer for inputs and then modify the code directly. Nrwl provides plugins which contain useful executors and generators for a lot of popular tools. Also, there is a growing number of community provided plugins.
- **Accurate Architecture Diagram** - Most architecture diagrams are wrong the moment they are written down. And every diagram becomes out of date as soon as the code changes. Since Nx understands your code, it can generate an up-to-date and accurate diagram of how projects depend on each other. And for cases where dependencies are not explicit in the code, you can manually tell Nx about project dependencies.
## Next Steps

View File

@ -39,26 +39,26 @@ If you don't have the Nx CLI installed globally, you can invoke `nx` using `yarn
The Nx CLI has an advanced code generator. With it, you can generate new applications, libraries, components, state management utilities. You can change existing applications. And, because the Nx CLI comes with an implementation of a virtual file system, you can preview the changes without affecting anything on disk.
The code generation recipes are called schematics. Schematics provide the underlying APIs for scaffolding, and utilities to automate changes to your filesystem. The example below is the command to generate a new application.
The code generation recipes are called generators. Generators provide the underlying APIs for scaffolding, and utilities to automate changes to your filesystem. The example below is the command to generate a new application.
```sh
nx generate @nrwl/react:application myapp
```
The `@nrwl/react` package contains a collection of schematics, with `application` being the one used in this example. The Nx CLI applies the schematic to your workspace, verifying that the provided options are valid, and the destination files don't already exist. Once the validations are passed, the new files are generated, or existing files are updated. You can also customize the output of the generated application, by passing options to the schematic.
The `@nrwl/react` package contains a collection of generators, with `application` being the one used in this example. The Nx CLI applies the generator to your workspace, verifying that the provided options are valid, and the destination files don't already exist. Once the validations are passed, the new files are generated, or existing files are updated. You can also customize the output of the generated application, by passing options to the generator.
```sh
nx generate @nrwl/react:application myapp --style=scss
```
You can preview the changes a schematic makes by using the `--dry-run` option. It will output the potential files created, and/or updated during the execution of the schematic.
You can preview the changes a generator makes by using the `--dry-run` option. It will output the potential files created, and/or updated during the execution of the generator.
**Generate command:**
`nx generate` runs schematics to create or modify code given some inputs from the developer.
`nx generate` runs generators to create or modify code given some inputs from the developer.
- [nx generate](/{{framework}}/cli/generate)
Syntax: `nx generate [plugin]:[schematic-name] [options]`
Syntax: `nx generate [plugin]:[generator-name] [options]`
Example: `nx generate @nrwl/react:component mycmp --project=myapp`
## Running Tasks

View File

@ -4,7 +4,7 @@ There are three top-level configuration files every Nx workspace has: `workspace
## workspace.json
The `workspace.json` configuration file contains information about the targets and schematics. Let's look at the following example:
The `workspace.json` configuration file contains information about the targets and generators. Let's look at the following example:
```json
{
@ -177,9 +177,9 @@ require(`@nrwl/jest`).builders['jest']({...options, ...selectedConfiguration, ..
The selected configuration adds/overrides the default options, and the provided command line args add/override the configuration options.
### Schematics
### Generators
You can configure default schematic options in `workspace.json` as well. For instance, the following will tell Nx to always pass `--js` when creating new libraries.
You can configure default generator options in `workspace.json` as well. For instance, the following will tell Nx to always pass `--js` when creating new libraries.
```json
{

View File

@ -1,15 +1,15 @@
# generate
Runs a schematic that generates and/or modifies files based on a schematic from a collection.
Runs a generator that creates and/or modifies files based on a generator from a collection.
## Usage
```bash
nx generate <collection:schematic>
nx generate <collection:generator>
```
```bash
nx g <schematic>
nx g <generator>
```
Install the `nx` package globally to invoke the command directly using `nx`, or use `npm run nx` or `yarn nx`.
@ -86,7 +86,7 @@ When false, disables interactive input prompts.
### help
Show help and display available schematics in the default collection.
Show help and display available generators in the default collection.
### version

View File

@ -4,7 +4,7 @@ The official Nx plugins rely on [browserslist](https://github.com/browserslist/b
In general, the more modern your applications browser support is, the smaller the filesize as the code can rely on modern API's being present and not have to ship polyfills or shimmed code.
By default, applications generated from official Nx schematics ship an aggressively modern browser support config, in the form of a `.browserlistrc` file in the root of the application with the following contents.
By default, applications generated from official Nx generators ship an aggressively modern browser support config, in the form of a `.browserlistrc` file in the root of the application with the following contents.
```
last 1 Chrome version

View File

@ -155,15 +155,15 @@ Since Nx allows us to group apps and libs in directories, those directories can
When we have 10 people working on an app in the same room, we can agree on best practices over lunch. We can also make sure the team follows them by reviewing each other's PRs. For a team of a hundred located in different cities, this no longer works.
With Nx, we can help teams adopt best practices by using workspace schematics and workspace lint checks.
With Nx, we can help teams adopt best practices by using workspace generators and workspace lint checks.
### Workspace Schematics
### Workspace Generators
Schematics is a library used by Nx to do code generation. `nx g lib mylib` invokes the lib schematic from the default collection. Schematics are a great way to codify conventions and best practices. Unfortunately, creating a custom schematics collection is not very straightforward, so few do it.
Generators is a library used by Nx to do code generation. `nx g lib mylib` invokes the lib generator from the default collection. Generators are a great way to codify conventions and best practices. Unfortunately, creating a custom generators collection is not very straightforward, so few do it.
Nx simplifies it. With Nx, we can create custom schematics in the `tools/schematics` and invoke them without having to do compile, build, deploy anything.
Nx simplifies it. With Nx, we can create custom generators in the `tools/generators` folder and invoke them without having to do compile, build, deploy anything.
Read more about workspace schematics in the Workspace Schematics guide.
Read more about workspace generators in the Workspace Generators guide.
### Workspace Lint Checks

View File

@ -1,6 +1,6 @@
# Plugins
Nx plugins are npm packages that contain schematics and builders to extend a Nx workspace. Schematics are blueprints to create or modify code, and builders perform actions on the code.
Nx plugins are npm packages that contain generators and executors (or builders) to extend a Nx workspace. Generators are blueprints to create or modify code, and executors perform actions on the code.
## nx list

View File

@ -26,9 +26,9 @@ For each project for which you want to enable `make`, add a target in `workspace
```json
// ...
"my-app": {
"architect": {
"targets": {
"make": {
"builder": "@nrwl/workspace:run-commands",
"executor": "@nrwl/workspace:run-commands",
"options": {
"commands": [
{
@ -44,15 +44,15 @@ For each project for which you want to enable `make`, add a target in `workspace
For more information, see the [run-commands api doc](/{{framework}}/plugins/workspace/builders/run-commands).
##### 3. Trigger the builder from the terminal
##### 3. Trigger the executor from the terminal
To run the builder for a single project:
To run the executor for a single project:
```bash
nx run my-app:make
```
To run the builder for all affected projects:
To run the executor for all affected projects:
```bash
nx affected --target=make

View File

@ -1,19 +1,21 @@
# Creating Builders in Your Nx Workspace
# Creating Executors in Your Nx Workspace
Creating builders for your workspace is a way to standardize scripts that you may run during your development/building/deploying tasks to enable Nx's `affected` command and caching capabilities.
Creating executors for your workspace standardizes scripts that are run during your development/building/deploying tasks in order to enable Nx's `affected` command and caching capabilities.
This guide will show you how to create, run, and customize builders within your Nx workspace. In the examples, we'll use the trivial use-case of an `echo` command.
This guide will show you how to create, run, and customize executors within your Nx workspace. In the examples, we'll use the trivial use-case of an `echo` command.
## Creating a Builder
## Creating an Executor with @angular/devkit
Your builder should be created within the `tools` directory of your Nx workspace like so:
Note: Executors that use the `@angular/devkit` are called builders.
Your executor should be created within the `tools` directory of your Nx workspace like so:
```treeview
happynrwl/
├── apps/
├── libs/
├── tools/
│ └── builders/
│ └── executors/
│ └── echo/
│ ├── builder.json
│ ├── impl.ts

View File

@ -1,24 +1,24 @@
# Workspace Schematics
# Workspace Generators
Workspace schematics provide a way to automate many tasks you regularly perform as part of your development workflow. Whether it is scaffolding out components, features, or ensuring libraries are generated and structured in a certain way, schematics help you standardize these tasks in a consistent, and predictable manner. Nx provides tooling around creating, and running custom schematics from within your workspace. This guide shows you how to create, run, and customize workspace schematics within your Nx workspace.
Workspace generators provide a way to automate many tasks you regularly perform as part of your development workflow. Whether it is scaffolding out components, features, or ensuring libraries are generated and structured in a certain way, generators help you standardize these tasks in a consistent, and predictable manner. Nx provides tooling around creating, and running custom generators from within your workspace. This guide shows you how to create, run, and customize workspace generators within your Nx workspace.
## Creating a workspace schematic
## Creating a workspace generator using @angular/devkit
Use the Nx CLI to generate the initial files needed for your workspace schematic.
Use the Nx CLI to generate the initial files needed for your workspace generator.
```sh
nx generate @nrwl/workspace:workspace-schematic my-schematic
nx generate @nrwl/workspace:workspace-generator my-generator
```
After the command is finished, the workspace schematic is created under the `tools/schematics` folder.
After the command is finished, the workspace generator is created under the `tools/generators` folder.
```treeview
happynrwl/
├── apps/
├── libs/
├── tools/
│ ├── schematics
│ | └── my-schematic/
│ ├── generators
│ | └── my-generator/
│ | | ├── index.ts
│ | | └── schema.json
├── nx.json
@ -78,7 +78,7 @@ nx workspace-schematic my-schematic mylib
## Creating custom rules
Schematics provide an API for managing files within your workspace. You can use schematics to do things such as create, update, move, and delete files. Files with static or dynamic content can also be created.
Generators provide an API for managing files within your workspace. You can use schematics to do things such as create, update, move, and delete files. Files with static or dynamic content can also be created.
The schematic below shows you how to generate a library, and then scaffold out additional files with the newly created library.

View File

@ -1,15 +1,17 @@
# Using Builders
# Using Executors / Builders
Builders perform actions on your code. This can include building, linting, testing, serving and many other actions.
Executors perform actions on your code. This can include building, linting, testing, serving and many other actions.
There are two main differences between a builder and a shell script or an npm script:
Executors can be written using `@nx/devkit` or `@angular/devkit`. Executors written with the `@angular/devkit` are called Builders.
1. Builders encourage a consistent methodology for performing similar actions on unrelated projects. i.e. A developer switching between teams can be confident that `nx build project2` will build `project2` with the default settings, just like `nx build project1` built `project1`.
2. Nx can leverage this consistency to perform the same builder command across multiple projects. i.e. `nx affected --target==test` will run the `test` builder command on every project that is affected by the current code change.
There are two main differences between an executor and a shell script or an npm script:
## Builder Command Definitions
1. Executors encourage a consistent methodology for performing similar actions on unrelated projects. i.e. A developer switching between teams can be confident that `nx build project2` will build `project2` with the default settings, just like `nx build project1` built `project1`.
2. Nx can leverage this consistency to perform the same executor across multiple projects. i.e. `nx affected --target==test` will run the `test` executor on every project that is affected by the current code change.
The builder commands that are available for each project are defined and configured in the `/workspace.json` file.
## Executor Definitions
The executors that are available for each project are defined and configured in the `/workspace.json` file.
```json
{
@ -18,10 +20,10 @@ The builder commands that are available for each project are defined and configu
"root": "apps/cart",
"sourceRoot": "apps/cart/src",
"projectType": "application",
"schematics": {},
"architect": {
"generators": {},
"targets": {
"build": {
"builder": "@nrwl/web:build",
"executor": "@nrwl/web:build",
"options": {
"outputPath": "dist/apps/cart",
...
@ -34,7 +36,7 @@ The builder commands that are available for each project are defined and configu
}
},
"test": {
"builder": "@nrwl/jest:jest",
"executor": "@nrwl/jest:jest",
"options": {
...
}
@ -45,19 +47,21 @@ The builder commands that are available for each project are defined and configu
}
```
Each project has its builder commands defined in the `architect` property. In this snippet, `cart` has two builder commands defined - `build` and `test`.
Note: There are a few property keys in `workspace.json` that have interchangeable aliases. You can replace `generators` with `schematics`, `targets` with `architect` or `executor` with `builder`.
Each project has its executors defined in the `targets` property. In this snippet, `cart` has two executors defined - `build` and `test`.
**Note:** `build` and `test` can be any strings you choose. For the sake of consistency, we make `test` run unit tests for every project and `build` produce compiled code for the projects which can be built.
Each builder command definition has a `builder` property and, optionally, an `options` and a `configurations` property.
Each executor definition has an `executor` property and, optionally, an `options` and a `configurations` property.
- `builder` is a string of the from `[package name]:[builder name]`. For the `build` builder, the package name is `@nrwl/web` and the builder name is `build`.
- `options` is an object that contains any configuration defaults for the builder. These options vary from builder to builder.
- `executor` is a string of the from `[package name]:[executor name]`. For the `build` executor, the package name is `@nrwl/web` and the executor name is `build`.
- `options` is an object that contains any configuration defaults for the executor. These options vary from executor to executor.
- `configurations` allows you to create presets of options for different scenarios. All the configurations start with the properties defined in `options` as a baseline and then overwrite those options. In the example, there is a `production` configuration that overrides the default options to set `sourceMap` to `false`.
## Executing Builder Commands
## Running Executors
The [`nx run`](/{{framework}}/cli/run) cli command (or the shorthand versions) can be used to execute builder commands.
The [`nx run`](/{{framework}}/cli/run) cli command (or the shorthand versions) can be used to run executors.
```bash
nx run [project]:[command]
@ -78,7 +82,7 @@ nx [command] [project] --configuration=[configuration]
nx build cart --configuration=production
```
Or you can overwrite individual builder options like this:
Or you can overwrite individual executor options like this:
```bash
nx [command] [project] --[optionNameInCamelCase]=[value]

View File

@ -1,30 +1,28 @@
# Using Schematics
# Using Generators
## Overview
Schematics provide a way to automate many tasks you regularly perform as part of your development workflow. Whether it is scaffolding out components, features, ensuring libraries are generated and structured in a certain way, or updating your configuration files, schematics help you standardize these tasks in a consistent, and predictable manner.
Generators provide a way to automate many tasks you regularly perform as part of your development workflow. Whether it is scaffolding out components, features, ensuring libraries are generated and structured in a certain way, or updating your configuration files, generators help you standardize these tasks in a consistent, and predictable manner.
Schematics are developed by the Angular Team at Google as part of the Angular DevKit, but are provided independently of the Angular framework. The DevKit packages are provided under the [@angular-devkit](https://npmjs.com/~angular-devkit) scope on npm. Nx provides additional tooling around creating, and running custom schematics from within your workspace.
Generators can be written using `@nx/devkit` or `@angular/devkit`. Generators written with the `@angular/devkit` are called schematics. To read more about the concepts of `@angular/devkit` schematics, and building an example schematic, see the [Schematics Authoring Guide](https://angular.io/guide/generators-authoring).
To read more about the concepts of Schematics, and building an example schematic, see the [Schematics Authoring Guide](https://angular.io/guide/schematics-authoring).
The [Workspace Generators](/{{framework}}/workspace/generators/workspace-generators) guide shows you how to create, run, and customize workspace generators within your Nx workspace.
The [Workspace Schematics](/{{framework}}/workspace/generators/workspace-generators) guide shows you how to create, run, and customize workspace schematics within your Nx workspace.
## Types of Generators
## Types of Schematics
There are three main types of generators:
There are three main types of schematics:
1. **Plugin Generators** are available when an Nx plugin has been installed in your workspace.
2. **Workspace Generators** are generators that you can create for your own workspace. [Workspace generators](/{{framework}}/workspace/generators/workspace-generators) allow you to codify the processes that are unique to your own organization.
3. **Update Generators** are invoked by Nx plugins when you [update Nx](/{{framework}}/workspace/update) to keep your config files in sync with the latest versions of third party tools.
1. **Plugin Schematics** are available when an Nx plugin has been installed in your workspace.
2. **Workspace Schematics** are schematics that you can create for your own workspace. [Workspace schematics](/{{framework}}/workspace/generators/workspace-generators) allow you to codify the processes that are unique to your own organization.
3. **Update Schematics** are invoked by Nx plugins when you [update Nx](/{{framework}}/workspace/update) to keep your config files in sync with the latest versions of third party tools.
## Invoking Plugin Generators
## Invoking Plugin Schematics
Schematics allow you to create or modify your codebase in a simple and repeatable way. Schematics are invoked using the [`nx generate`](/{{framework}}/cli/generate) command.
Generators allow you to create or modify your codebase in a simple and repeatable way. Generators are invoked using the [`nx generate`](/{{framework}}/cli/generate) command.
```bash
nx generate [plugin]:[schematic-name] [options]
nx generate [plugin]:[generator-name] [options]
nx generate @nrwl/react:component mycmp --project=myapp
```
It is important to have a clean git working directory before invoking a schematic so that you can easily revert changes and re-invoke the schematic with different inputs.
It is important to have a clean git working directory before invoking a generator so that you can easily revert changes and re-invoke the generator with different inputs.

View File

@ -21,9 +21,9 @@ Nx makes it easy to split up your code into separate projects. Projects come in
`/libs/` contains the library projects. There are many different kinds of libraries, and each library defines its own external api so that boundaries between libraries remain clear.
`/tools/` contains scripts that act on your code base. This could be database scripts, custom builders or workspace schematics.
`/tools/` contains scripts that act on your code base. This could be database scripts, custom executors (or builders) or workspace generators.
`/workspace.json` defines each project in your workspace and the builder commands that can be run on those projects.
`/workspace.json` defines each project in your workspace and the executors that can be run on those projects.
`/nx.json` adds extra information about projects, including manually defined dependencies and tags that can be used to restrict the ways projects are allowed to depend on each other.

View File

@ -7,7 +7,7 @@ The workspace plugin contains executors and generators that are useful for any N
- [library](/angular/plugins/workspace/generators/library) - Create a plain typescript library
- [move](/angular/plugins/workspace/generators/move) - Move a project to another directory and update all references
- [remove](/angular/plugins/workspace/generators/remove) - Remove a project from the workspace
- [workspace-schematic](/angular/plugins/workspace/generators/workspace-schematic) - Scaffold a custom schematic for use within your workspace
- [workspace-generator](/angular/plugins/workspace/generators/workspace-schematic) - Scaffold a custom generator for use within your workspace
## Executors / Builders

View File

@ -1,13 +1,13 @@
# Publishable and Buildable Nx Libraries
The `--buildable` and `--publishable` options are available on the Nx library generation schematics for the following plugins:
The `--buildable` and `--publishable` options are available on the Nx library generators for the following plugins:
- Angular
- React
- NestJs
- Node
This document will look to explain the motivations for why you would use either the `--buildable` or `--publishable` option, as well as the mechanics of how they adjust the result when you add them to your schematic.
This document will look to explain the motivations for why you would use either the `--buildable` or `--publishable` option, as well as the mechanics of how they adjust the result when you add them to your generator.
## Publishable libraries
@ -23,7 +23,7 @@ One particularity when generating a library with `--publishable` is that it requ
To publish the library (for example to npm) you can run the CLI command: `npm publish` from the artifact located in the `dist` directory. Setting up some automated script in Nxs `tools` folder may also come in handy.
For more details on the mechanics, remember that Nx is an open source project, so you can see the actual impact of the schematic by looking at the source code (the best starting point is probably `packages/<framework>/src/generators/library/library.ts`).
For more details on the mechanics, remember that Nx is an open source project, so you can see the actual impact of the generator by looking at the source code (the best starting point is probably `packages/<framework>/src/generators/library/library.ts`).
## Buildable libraries
@ -31,4 +31,4 @@ Buildable libraries are similar to "publishable libraries" described above. Thei
Buildable libraries are mostly used for producing some pre-compiled output that can be directly referenced from an Nx workspace application without the need to again compile it. A typical scenario is to leverage Nxs [incremental building](https://nx.dev/latest/angular/guides/ci/incremental-builds) capabilities.
For more details on the mechanics, remember that Nx is an open source project, so you can see the actual impact of the schematic by looking at the source code (the best starting point is probably `packages/<framework>/src/generators/library/library.ts`).
For more details on the mechanics, remember that Nx is an open source project, so you can see the actual impact of the generator by looking at the source code (the best starting point is probably `packages/<framework>/src/generators/library/library.ts`).

View File

@ -2,9 +2,9 @@
Libraries should be grouped by _scope_. A library's scope is either application to which it belongs or (for larger applications) a section within that application.
## Move Schematic
## Move Generator
Don't be too anxious about choosing the exact right folder structure from the beginning. Libraries can be moved or renamed using the [`@nrwl/workspace:move` schematic](/{{framework}}/plugins/workspace/generators/move).
Don't be too anxious about choosing the exact right folder structure from the beginning. Libraries can be moved or renamed using the [`@nrwl/workspace:move` generator](/{{framework}}/plugins/workspace/generators/move).
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:
@ -12,9 +12,9 @@ For instance, if a library under the `booking` folder is now being shared by mul
nx g move --project booking-some-library shared/some-library
```
## Remove Schematic
## Remove Generator
Similarly, if you no longer need a library, you can remove it with the [`@nrwl/workspace:remove` schematic](/{{framework}}/plugins/workspace/generators/remove).
Similarly, if you no longer need a library, you can remove it with the [`@nrwl/workspace:remove` generator](/{{framework}}/plugins/workspace/generators/remove).
```bash
nx g remove booking-some-library

View File

@ -10,7 +10,7 @@
## What is It?
Builders and schematics adding Cypress tests for frontend applications.
Executors and generators adding Cypress tests for frontend applications.
## How to Use

View File

@ -10,7 +10,7 @@
## What is It?
Builders and schematics adding Jest tests to applications and libraries.
Executors and generators adding Jest tests to applications and libraries.
## How to Use

View File

@ -10,7 +10,7 @@
## What is It?
Builders and schematics adding TS and JS lint checks to applications and libraries.
Executors and generators adding TS and JS lint checks to applications and libraries.
## How to Use

View File

@ -10,7 +10,7 @@
## What is It?
Builders and schematics adding basic functionality for building, testing and linting node applications and libraries.
Executors and generators adding basic functionality for building, testing and linting node applications and libraries.
## How to Use

View File

@ -10,7 +10,7 @@
## What is It?
Builders and schematics adding Storybook support for frontend applications.
Executors and generators adding Storybook support for frontend applications.
## How to Use