From 5039faff8ddaad04f25deef87e9cb63307ae7150 Mon Sep 17 00:00:00 2001 From: Judy Bogart Date: Wed, 12 Jun 2019 11:31:19 -0700 Subject: [PATCH] docs: add doc for complex config values (#31010) PR Close #31010 --- aio/content/guide/workspace-config.md | 184 ++++++++++++++++++++++---- 1 file changed, 156 insertions(+), 28 deletions(-) diff --git a/aio/content/guide/workspace-config.md b/aio/content/guide/workspace-config.md index a5dbf58769..dee563cdde 100644 --- a/aio/content/guide/workspace-config.md +++ b/aio/content/guide/workspace-config.md @@ -18,12 +18,14 @@ The following properties, at the top level of the file, configure the workspace. The initial app that you create with `ng new app_name` is listed under "projects": + "projects": { "app_name": { ... } ... } + Each additional app that you create with `ng generate application` has a corresponding end-to-end test project, with its own configuration section. @@ -44,6 +46,7 @@ When you create a library project with `ng generate library`, the library projec The following top-level configuration properties are available for each project, under `projects:`. + "my-app": { "root": "", "sourceRoot": "src", @@ -52,6 +55,7 @@ The following top-level configuration properties are available for each project, "schematics": {}, "architect": {} } + | PROPERTY | DESCRIPTION | @@ -64,6 +68,7 @@ The following top-level configuration properties are available for each project, | `architect` | Configuration defaults for Architect builder targets for this project. | {@a schematics} + ## Generation schematics Angular generation [schematics](guide/glossary#schematic) are instructions for modifying a project by adding files or modifying existing files. @@ -81,8 +86,31 @@ You can update your workspace schema file to set a different default for a sub-c ## Project tool configuration options -Architect is the tool that the CLI uses to perform complex tasks, such as compilation and test running, according to provided configurations. -The `architect` section of `angular.json` contains a set of Architect *targets*. +Architect is the tool that the CLI uses to perform complex tasks, such as compilation and test running. +Architect is a shell that runs a specified [builder](guide/glossary#builder) to perform a given task, according to a [target](guide/glossary#target) configuration. +You can define and configure new builders and targets to extend the CLI. +See [Angular CLI Builders](guide/cli-builder). + +{@a default-build-targets} + +### Default Architect builders and targets + +Angular defines default builders for use with specific CLI commands, or with the general `ng run` command. +The JSON schemas that the define the options and defaults for each of these default builders are collected in the [`@angular-devkit/build-angular`](https://github.com/angular/angular-cli/blob/8.0.x/packages/angular/cli/lib/config/schema.json) package. +The schemas configure options for the following builders. + +* app-shell +* browser +* dev-server +* extract-i18n +* karma +* protractor +* server +* tslint + +### Configuring builder targets + +The `architect` section of `angular.json` contains a set of Architect targets. Many of the targets correspond to the CLI commands that run them. Some additional predefined targets can be run using the `ng run` command, and you can define your own targets. @@ -91,6 +119,7 @@ In addition, each target has an `options` section that configures default option See the example in [Build target](#build-target) below. + "architect": { "build": { }, "serve": { }, @@ -101,6 +130,7 @@ See the example in [Build target](#build-target) below. "server": { }, "app-shell": { } } + * The `architect/build` section configures defaults for options of the `ng build` command. @@ -131,27 +161,10 @@ The `architect/build` section configures defaults for options of the `ng build` | PROPERTY | DESCRIPTION | | :-------------- | :---------------------------- | -| `builder` | The npm package for the build tool used to create this target. The default is `@angular-devkit/build-angular:browser`, which uses the [webpack](https://webpack.js.org/) package bundler. | +| `builder` | The npm package for the build tool used to create this target. The default builder for an application (`ng build myApp`) is `@angular-devkit/build-angular:browser`, which uses the [webpack](https://webpack.js.org/) package bundler. Note that a different builder is used for building a library (`ng build myLib`). | | `options` | This section contains default build target options, used when no named alternative configuration is specified. See [Default build targets](#default-build-targets) below. | | `configurations`| This section defines and names alternative configurations for different intended destinations. It contains a section for each named configuration, which sets the default options for that intended environment. See [Alternate build configurations](#build-configs) below. | -{@a default-build-targets} - -### Default build targets - -Angular defines default builders for use with the Architect tool and `ng run` command. -The default builders provide implementations that use a particular tool to perform a complex operation. - -The JSON schemas that the define the options and defaults for each of these default builders are collected in the [`@angular-devkit/build-angular`](https://github.com/angular/angular-cli/blob/7.0.x/packages/angular/cli/lib/config/schema.json) package. The schemas configure options for the following Architect build targets: - -* app-shell -* browser -* dev-server -* extract-i18n -* karma -* protractor -* server -* tslint {@a build-configs} @@ -167,27 +180,39 @@ You can define and name additional alternate configurations (such as `stage`, fo The configurable options for a default or targeted build generally correspond to the options available for the [`ng build`](cli/build), [`ng serve`](cli/serve), and [`ng test`](cli/test) commands. For details of those options and their possible values, see the [CLI Reference](cli). -Some additional options (listed below) can only be set through the configuration file, either by direct editing or with the [`ng config`](cli/config) command. +Some additional options can only be set through the configuration file, either by direct editing or with the [`ng config`](cli/config) command. | OPTIONS PROPERTIES | DESCRIPTION | | :------------------------- | :---------------------------- | -| `fileReplacements` | An object containing files and their compile-time replacements. | -| `stylePreprocessorOptions` | An object containing option-value pairs to pass to style preprocessors. | -| `assets` | An object containing paths to static assets to add to the global context of the project. The default paths point to the project's icon file and its `assets` folder. See more below. | -| `styles` | An object containing style files to add to the global context of the project. Angular CLI supports CSS imports and all major CSS preprocessors: [sass/scss](http://sass-lang.com/), [less](http://lesscss.org/), and [stylus](http://stylus-lang.com/). | -| `scripts` | An object containing JavaScript script files to add to the global context of the project. The scripts are loaded exactly as if you had added them in a `