9d20b031bb
* docs(docs): add the workspace section for nx.dev * Update docs/map.json Co-Authored-By: Brandon <robertsbt@gmail.com> Co-authored-by: Isaac Mann <isaacplmann+git@gmail.com> Co-authored-by: Brandon <robertsbt@gmail.com>
92 lines
3.3 KiB
Markdown
92 lines
3.3 KiB
Markdown
# Using Builders
|
|
|
|
Builders 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:
|
|
|
|
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.
|
|
|
|
## Builder Command Definitions
|
|
|
|
The builder commands that are available for each project are defined and configured in the `/workspace.json` file.
|
|
|
|
```json
|
|
{
|
|
"projects": {
|
|
"cart": {
|
|
"root": "apps/cart",
|
|
"sourceRoot": "apps/cart/src",
|
|
"projectType": "application",
|
|
"schematics": {},
|
|
"architect": {
|
|
"build": {
|
|
"builder": "@nrwl/web:build",
|
|
"options": {
|
|
"outputPath": "dist/apps/cart",
|
|
...
|
|
},
|
|
"configurations": {
|
|
"production": {
|
|
"sourceMap": false,
|
|
...
|
|
}
|
|
}
|
|
},
|
|
"test": {
|
|
"builder": "@nrwl/jest:jest",
|
|
"options": {
|
|
...
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Each project has its builder commands defined in the `architect` property. In this snippet, `cart` has two builder commands 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.
|
|
|
|
- `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.
|
|
- `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
|
|
|
|
The [`nx run`](/{{framework}}/cli/run) cli command (or the shorthand versions) can be used to execute builder commands.
|
|
|
|
```bash
|
|
nx run [project]:[command]
|
|
nx run cart:build
|
|
```
|
|
|
|
As long as your command name doesn't conflict with an existing nx cli command, you can use this short hand:
|
|
|
|
```bash
|
|
nx [command] [project]
|
|
nx build cart
|
|
```
|
|
|
|
You can also use a specific configuration preset like this:
|
|
|
|
```bash
|
|
nx [command] [project] --configuration=[configuration]
|
|
nx build cart --configuration=production
|
|
```
|
|
|
|
Or you can overwrite individual builder options like this:
|
|
|
|
```bash
|
|
nx [command] [project] --[optionNameInCamelCase]=[value]
|
|
nx build cart --outputPath=some/other/path
|
|
```
|
|
|
|
## See Also
|
|
|
|
- [`nx affected`](/{{framework}}/cli/affected)
|
|
- [`nx run-many`](/{{framework}}/cli/run-many)
|