From dcb3d176a6f70fc8df03c051e33e884d5d4b63be Mon Sep 17 00:00:00 2001 From: Alan Agius Date: Wed, 9 Dec 2020 13:10:02 +0100 Subject: [PATCH] docs: update optimization and source map section (#40037) With this change we split the optimization and source map configuration section section into two, improve it overall by adding theoptions a table and add the new options (`inlineCritical` and `minify`) that have been introduced in CLI version 11.1 PR Close #40037 --- aio/content/guide/workspace-config.md | 150 +++++++++++++++++++++++--- 1 file changed, 137 insertions(+), 13 deletions(-) diff --git a/aio/content/guide/workspace-config.md b/aio/content/guide/workspace-config.md index 128313cf1c..fea2e84547 100644 --- a/aio/content/guide/workspace-config.md +++ b/aio/content/guide/workspace-config.md @@ -361,34 +361,161 @@ Files in that folder, such as `src/style-paths/_variables.scss`, can be imported 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). +### Optimization configuration -{@a optimize-and-srcmap} +The `optimization` browser builder option can be either a Boolean or an Object for more fine-tune configuration. This option enables various optimizations of the build output, including: -### Optimization and source map configuration +- Minification of scripts and styles +- Tree-shaking +- Dead-code elimination +- Inlining of critical CSS +- Fonts inlining -The `optimization` and `sourceMap` browser builder options can be either a Boolean or an Object for more fine-grained configuration. -In this section we will explain how to fine tune these options. +There are several options that can be used to fine-tune the optimization of an application. -* The `optimization` option applies to scripts, styles and fonts. You can supply a value such as the following to apply optimization to one or the other: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionDescriptionValue TypeDefault Value
scriptsEnables optimization of the scripts output.booleantrue
stylesEnables optimization of the scripts output.boolean|Styles optimization optionstrue
fontsEnables optimization for fonts.
Note: This requires internet access.		boolean|Fonts optimization optionstrue
+ +#### Styles optimization options + + + + + + + + + + + + + + + + + + + + + + + +
OptionDescriptionValue TypeDefault Value
minifyMinify CSS definitions by removing extraneous whitespace and comments, merging identifiers and minimizing values.booleantrue
inlineCriticalExtract and inline critical CSS definitions to improve First Contentful Paint.booleanfalse
+ +#### Fonts optimization options + + + + + + + + + + + + + + + + + +
OptionDescriptionValue TypeDefault Value
inlineReduce render blocking requests by inlining external Google fonts and icons CSS definitions in the application's HTML index file.
Note:This requires internet access.		booleantrue
+ + +You can supply a value such as the following to apply optimization to one or the other: "optimization": { "scripts": true, - "styles": false, + "styles": { + "minify": true, + "inlineCritical": true + }, "fonts": true } -
+
- Fonts optimization requires internet access. - When enabled, render blocking requests will be reduced by inlining external Google fonts and icons CSS definitions in the application's HTML index file. + For [Universal](guide/glossary#universal), you can reduce the code rendered in the HTML page by + setting styles optimization to `true`.
-* The `sourceMap` option applies for both scripts and styles. You can also choose to output hidden source maps, or resolve vendor package source maps: +### Source map configuration + +The `sourceMap` browser builder option can be either a Boolean or an Object for more fine-tune configuration to control the source maps of an application. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionDescriptionValue TypeDefault Value
scriptsOutput source maps for all scripts.booleantrue
stylesOutput source maps for all styles.booleantrue
vendorResolve vendor packages source maps.booleanfalse
hiddenOutput source maps used for error reporting tools.booleanfalse
+ + +The example below shows how to toggle one or more values to configure the source map outputs: @@ -407,7 +534,4 @@ In this section we will explain how to fine tune these options. 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. - For [Universal](guide/glossary#universal), you can reduce the code rendered in the HTML page by - setting styles optimization to `true` and styles source maps to `false`. -