docs: add Differential Loading section to deployment guide (#29932)
PR Close #29932
This commit is contained in:
Brandon Roberts
Ben Lesh
parent
8c80b851c8
commit
57c8f78c8f
|
|
@ -369,3 +369,131 @@ the subfolder is `my/app/` and you should add `<base href="/my/app/">` to the se
|
|||
|
||||
When the `base` tag is mis-configured, the app fails to load and the browser console displays `404 - Not Found` errors
|
||||
for the missing files. Look at where it _tried_ to find those files and adjust the base tag appropriately.
|
||||
|
||||
## Differential Loading
|
||||
|
||||
When building web applications, making sure your application is compatible with the majority of browsers is a goal. Even as JavaScript continues to evolve, with new features being introduced, not all browsers are updated with support for these new features at the same pace. This is where compilation and [polyfills](guide/browser-support#polyfills) come in. The code you write in development using TypeScript is compiled and bundled into a format that is compatible with most browsers, commonly known as ES5. Polyfills are used bridge the gap, providing functionality that simply doesn't exist in some legacy browsers.
|
||||
|
||||
There is a cost to ensure this browser compatibility, and it comes in the form of larger bundle size. All modern browsers support ES2015 and beyond, but in most cases, you still have to account for users accessing your application from a browser that doesn't. To maximize compatibility, you ship a single bundle that includes all your compiled code, plus any polyfills that may be needed. Users with modern browsers shouldn't pay the price of increased bundle size when used in a modern browser that supports many of the latest features in JavaScript. This is where differential loading comes into play.
|
||||
|
||||
Differential loading is a strategy where the CLI builds two separate bundles as part of your deployed application. The modern bundle contains modern syntax, takes advantage of built-in support in modern browsers, ships less polyfills, and results in a smaller bundle size. The second bundle, includes the additional compiled code, all necessary polyfills, and results in a larger bundle size. This strategy allows you to continue to build your web application to support multiple browsers, but only load the necessary code that the browser needs.
|
||||
|
||||
### Differential builds
|
||||
|
||||
The Angular CLI handles differential loading for you as part of the _build_ process for deployment. The Angular CLI will produce the necessary bundles used for differential loading, based on your browser support requirements and compilation target.
|
||||
|
||||
The Angular CLI uses two configurations for differential loading:
|
||||
|
||||
- Browserslist - The `browserslist` configuration file is included in your application [project structure](guide/file-structure#application-configuration-files) and provides the minimum browsers your application supports. See the [Browserslist spec](https://github.com/browserslist/browserslist) for complete configuration options.
|
||||
- tsconfig.json - The `target` in the TypeScript `compilerOptions` determines the ECMAScript target version that the code is compiled to. Modern browsers support ES2015 natively, while ES5 is more commonly used to support legacy browsers.
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
**Note:** Differential loading is currently only supported when using `es2015` as a compilation `target`. When used with targets higher than `es2015`, a warning is emitted during build time.
|
||||
|
||||
</div>
|
||||
|
||||
The CLI queries the Browserslist configuration, and checks the `target` to determine if support for legacy browsers is required. The combination of these two configurations determines whether multiple bundles are produced when you create a _build_. When you create a development build using [`ng build`](cli/build) and differential loading is enabled, the output produced is simpler and easier to debug, allowing you to rely less on sourcemaps of compiled code. When you create a production build using [`ng build --prod`](cli/build), the CLI uses the defined configurations above to determine the bundles to build for deployment of your application.
|
||||
|
||||
The `index.html` file is also modified during the build process to include script tags that enable differential loading. See the sample output below from the `index.html` file produced during a build using `ng build`.
|
||||
|
||||
```html
|
||||
<!-- ... -->
|
||||
<body>
|
||||
<app-root></app-root>
|
||||
<script src="runtime-es2015.js" type="module"></script>
|
||||
<script src="runtime-es5.js" nomodule></script>
|
||||
<script src="polyfills-es2015.js" type="module"></script>
|
||||
<script src="polyfills-es5.js" nomodule></script>
|
||||
<script src="styles-es2015.js" type="module"></script>
|
||||
<script src="styles-es5.js" nomodule></script>
|
||||
<script src="vendor-es2015.js" type="module"></script>
|
||||
<script src="vendor-es5.js" nomodule></script>
|
||||
<script src="main-es2015.js" type="module"></script>
|
||||
<script src="main-es5.js" nomodule></script>
|
||||
</body>
|
||||
<!-- ... -->
|
||||
```
|
||||
|
||||
Each script tag has a `type="module"` or `nomodule` attribute. Browsers with native support for ES modules only load the scripts with the `module` type attribute and ignore scripts with the `nomodule` attribute. Legacy browsers only load the scripts with the `nomodule` attribute, and ignore the script tags with the `module` type that load ES modules.
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
**Note:** Some legacy browsers still download both bundles, but only execute the appropriate scripts based on the attributes mentioned above. You can read more on the issue [here](https://github.com/philipwalton/webpack-esnext-boilerplate/issues/1).
|
||||
|
||||
</div>
|
||||
|
||||
See the [configuration table](#configuration-table) below for the configurations for enabling differential loading.
|
||||
|
||||
### Configuring differential loading
|
||||
|
||||
Differential loading for creating builds is already supported with version 8 and later of the Angular CLI. For each application project in your workspace, you can configure how builds are produced based on the mentioned `browserslist` and `tsconfig.json` files in your application project.
|
||||
|
||||
Look at the default configuration for a newly created Angular application:
|
||||
|
||||
The `browserslist` looks like this:
|
||||
|
||||
```
|
||||
> 0.5%
|
||||
last 2 versions
|
||||
Firefox ESR
|
||||
Chrome 41 # Support for Googlebot
|
||||
not dead
|
||||
not IE 9-11 # For IE 9-11 support, remove 'not'.
|
||||
```
|
||||
|
||||
The `tsconfig.json` looks like this:
|
||||
|
||||
|
||||
```
|
||||
{
|
||||
"compileOnSave": false,
|
||||
"compilerOptions": {
|
||||
"baseUrl": "./",
|
||||
"outDir": "./dist/out-tsc",
|
||||
"sourceMap": true,
|
||||
"declaration": false,
|
||||
"module": "esnext",
|
||||
"moduleResolution": "node",
|
||||
"emitDecoratorMetadata": true,
|
||||
"experimentalDecorators": true,
|
||||
"importHelpers": true,
|
||||
"target": "es2015",
|
||||
"typeRoots": [
|
||||
"node_modules/@types"
|
||||
],
|
||||
"lib": [
|
||||
"es2018",
|
||||
"dom"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
By default, legacy browsers such as IE 9-11 are ignored, Chrome 41 is included for search engine optimization (SEO) support, and the compilation target is ES2015. As a result, this produces two builds, and differential loading is enabled. If you ignore browsers without ES2015 support, a single build is produced. To see the build result for differential loading based on different configurations, refer to the table below.
|
||||
|
||||
<div class="alert is-important">
|
||||
|
||||
**Note:** To see which browsers are supported with the above configuration, see which settings meet to your browser support requirements, see the [Browserslist compatibility page](https://browserl.ist/?q=%3E+0.5%25%2C+last+2+versions%2C+Firefox+ESR%2C+Chrome+41%2C+not+dead%2C+not+IE+9-11).
|
||||
|
||||
</div>
|
||||
|
||||
{@a configuration-table }
|
||||
|
||||
| ES5 Browserslist Result | ES Target | Build Result |
|
||||
| -------- | -------- | -------- |
|
||||
| disabled | es5 | Single build |
|
||||
| enabled | es5 | Single build w/Conditional Polyfills |
|
||||
| disabled | es2015 | Single build |
|
||||
| enabled | es2015 | Differential Loading (Two builds w/Conditional Polyfills |
|
||||
|
||||
When the ES5 Browserslist result is `disabled`, then ES5 browser support is not required. Otherwise, ES5 browser support is required.
|
||||
|
||||
### Opting out of differential loading
|
||||
|
||||
Differential loading can be explicitly disabled if it causes unexpected issues or you need to target ES5 specifically for legacy browser support.
|
||||
|
||||
To explicitly disable differential loading:
|
||||
|
||||
- Enable the `dead` or `IE` browsers in the `browserslist` config file by removing the `not` keyword in front of them.
|
||||
- Set the `target` in the `compilerOptions` to `es5`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue