Judy Bogart
Alex Rickabaugh
parent
44c6534f3c
commit
5039faff8d
|
|
@ -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":
|
||||
|
||||
<code-example format="." language="json" linenums="false">
|
||||
|
||||
"projects": {
|
||||
"app_name": {
|
||||
...
|
||||
}
|
||||
...
|
||||
}
|
||||
|
||||
</code-example>
|
||||
|
||||
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:<project_name>`.
|
||||
|
||||
<code-example format="." language="json" linenums="false">
|
||||
|
||||
"my-app": {
|
||||
"root": "",
|
||||
"sourceRoot": "src",
|
||||
|
|
@ -52,6 +55,7 @@ The following top-level configuration properties are available for each project,
|
|||
"schematics": {},
|
||||
"architect": {}
|
||||
}
|
||||
|
||||
</code-example>
|
||||
|
||||
| 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.
|
||||
|
||||
<code-example format="." language="json" linenums="false">
|
||||
|
||||
"architect": {
|
||||
"build": { },
|
||||
"serve": { },
|
||||
|
|
@ -101,6 +130,7 @@ See the example in [Build target](#build-target) below.
|
|||
"server": { },
|
||||
"app-shell": { }
|
||||
}
|
||||
|
||||
</code-example>
|
||||
|
||||
* 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 `<script>` tag inside `index.html`. |
|
||||
| `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 in [Assets configuration](#asset-config) below. |
|
||||
| `styles` | An array of 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/). See more in [Styles and scripts configuration](#style-script-config) below. |
|
||||
| `stylePreprocessorOptions` | An object containing option-value pairs to pass to style preprocessors. See more in [Styles and scripts configuration](#style-script-config) below. |
|
||||
| `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 `<script>` tag inside `index.html`. See more in [Styles and scripts configuration](#style-script-config) below. |
|
||||
| `budgets` | Default size-budget type and threshholds for all or parts of your app. You can configure the builder to report a warning or an error when the output reaches or exceeds a threshold size. See [Configure size budgets](guide/build#configure-size-budgets). (Not available in `test` section.) |
|
||||
| `fileReplacements` | An object containing files and their compile-time replacements. See more in [Configure target-specific file replacements](guide/build#configure-target-specific-file-replacements).|
|
||||
|
||||
## Project asset configuration
|
||||
{@a complex-config}
|
||||
|
||||
## Complex configuration values
|
||||
|
||||
The options `assets`, `styles`, and `scripts` can have either simple path string values, or object values with specific fields.
|
||||
The `sourceMap` and `optimization` options can be set to a simple Boolean value with a command flag, but can also be given a complex value using the configuration file.
|
||||
The following sections provide more details of how these complex values are used in each case.
|
||||
|
||||
{@a asset-config}
|
||||
|
||||
### Assets configuration
|
||||
|
||||
Each `build` target configuration can include an `assets` array that lists files or folders you want to copy as-is when building your project.
|
||||
By default, the `src/assets/` folder and `src/favicon.ico` are copied over.
|
||||
|
||||
<code-example format="." language="json" linenums="false">
|
||||
|
||||
"assets": [
|
||||
"src/assets",
|
||||
"src/favicon.ico"
|
||||
]
|
||||
|
||||
</code-example>
|
||||
|
||||
To exclude an asset, you can remove it from the assets configuration.
|
||||
|
|
@ -203,19 +228,23 @@ A asset specification object can have the following fields.
|
|||
For example, the default asset paths can be represented in more detail using the following objects.
|
||||
|
||||
<code-example format="." language="json" linenums="false">
|
||||
|
||||
"assets": [
|
||||
{ "glob": "**/*", "input": "src/assets/", "output": "/assets/" },
|
||||
{ "glob": "favicon.ico", "input": "src/", "output": "/" },
|
||||
{ "glob": "favicon.ico", "input": "src/", "output": "/" }
|
||||
]
|
||||
|
||||
</code-example>
|
||||
|
||||
You can use this extended configuration to copy assets from outside your project.
|
||||
For example, the following configuration copies assets from a node package:
|
||||
|
||||
<code-example format="." language="json" linenums="false">
|
||||
|
||||
"assets": [
|
||||
{ "glob": "**/*", "input": "./node_modules/some-package/images", "output": "/some-package/" },
|
||||
]
|
||||
|
||||
</code-example>
|
||||
|
||||
The contents of `node_modules/some-package/images/` will be available in `dist/some-package/`.
|
||||
|
|
@ -223,7 +252,106 @@ The contents of `node_modules/some-package/images/` will be available in `dist/s
|
|||
The following example uses the `ignore` field to exclude certain files in the assets folder from being copied into the build:
|
||||
|
||||
<code-example format="." language="json" linenums="false">
|
||||
|
||||
"assets": [
|
||||
{ "glob": "**/*", "input": "src/assets/", "ignore": ["**/*.svg"], "output": "/assets/" },
|
||||
]
|
||||
|
||||
</code-example>
|
||||
|
||||
{@a style-script-config}
|
||||
|
||||
### Styles and scripts configuration
|
||||
|
||||
An array entry for the `styles` and `scripts` options can be a simple path string, or an object that points to an extra entry-point file.
|
||||
The associated builder will load that file and its dependencies as a separate bundle during the build.
|
||||
With a configuration object, you have the option of naming the bundle for the entry point, using a `bundleName` field.
|
||||
|
||||
The bundle is injected by default, but you can set `inject` to false to exclude the bundle from injection.
|
||||
For example, the following object values create and name a bundle that contains styles and scripts, and excludes it from injection:
|
||||
|
||||
<code-example format="." language="json" linenums="false">
|
||||
|
||||
"styles": [
|
||||
{"input": "src/external-module/styles.scss", "inject": false, "bundleName: "external-module"}
|
||||
]
|
||||
"scripts": [{
|
||||
"input": "src/external-module/main.ts", "inject": false, "bundleName: "external-module"}
|
||||
]
|
||||
|
||||
</code-example>
|
||||
|
||||
You can mix simple and complex file references for styles and scripts.
|
||||
|
||||
<code-example format="." language="json" linenums="false">
|
||||
|
||||
"styles": [
|
||||
"src/styles.css",
|
||||
"src/more-styles.css",
|
||||
{ "input": "src/lazy-style.scss", "lazy": true },
|
||||
{ "input": "src/pre-rename-style.scss", "bundleName": "renamed-style" },
|
||||
],
|
||||
|
||||
</code-example>
|
||||
|
||||
{@a style-preprocessor}
|
||||
|
||||
#### Style preprocessor options
|
||||
|
||||
In Sass and Stylus you can make use of the `includePaths` functionality for both component and global styles, which allows you to add extra base paths that will be checked for imports.
|
||||
|
||||
To add paths, use the `stylePreprocessorOptions` option:
|
||||
|
||||
"stylePreprocessorOptions": {
|
||||
"includePaths": [
|
||||
"src/style-paths"
|
||||
]
|
||||
},
|
||||
|
||||
Files in that folder, such as `src/style-paths/_variables.scss`, can be imported from anywhere in your project without the need for a relative path:
|
||||
|
||||
```ts
|
||||
// src/app/app.component.scss
|
||||
// A relative path works
|
||||
@import '../style-paths/variables';
|
||||
// But now this works as well
|
||||
@import 'variables';
|
||||
```
|
||||
|
||||
Note that you will also need to add any styles or scripts to the `test` builder if you need them for unit tests.
|
||||
See also [Using runtime-global libraries inside your app](guide/using-libraries#using-runtime-global-libraries-inside-your-app).
|
||||
|
||||
|
||||
{@a optimize-and-srcmap}
|
||||
|
||||
### Optimization and source map configuration
|
||||
|
||||
The `optimization` and `sourceMap` command options are simple Boolean flags.
|
||||
You can supply an object as a configuration value for either of these to provide more detailed instruction.
|
||||
|
||||
* The flag `--optimization="true"` applies to both scripts and styles. You can supply a value such as the following to apply optimization to one or the other:
|
||||
|
||||
<code-example format="." language="json" linenums="false">
|
||||
|
||||
"optimization": {"scripts": true, "styles": false}
|
||||
|
||||
</code-example>
|
||||
|
||||
* The flag `--sourceMap="true"` outputs source maps for both scripts and styles.
|
||||
You can configure the option to apply to one or the other.
|
||||
You can also choose to output hidden source maps, or resolve vendor package source maps.
|
||||
For example:
|
||||
|
||||
<code-example format="." language="json" linenums="false">
|
||||
|
||||
"sourceMaps": {"scripts": true, "styles": false, "hidden": true, "vendor": true}
|
||||
|
||||
</code-example>
|
||||
|
||||
<div class="alert is-helpful>
|
||||
|
||||
When using hidden source maps, source maps will not be referenced in the bundle.
|
||||
These are useful if you only want source maps to map error stack traces in error reporting tools,
|
||||
but don't want to expose your source maps in the browser developer tools.
|
||||
|
||||
</div>
|
||||
Loading…
Reference in New Issue