diff --git a/aio/content/guide/aot-compiler.md b/aio/content/guide/aot-compiler.md index 5a6f83943c..1a1e6a3889 100644 --- a/aio/content/guide/aot-compiler.md +++ b/aio/content/guide/aot-compiler.md @@ -6,14 +6,11 @@ Learn how to use ahead-of-time compilation. @description - This cookbook describes how to radically improve performance by compiling _ahead-of-time_ (AOT) during a build process. - {@a toc} - # Contents * [Overview](guide/overview) @@ -22,31 +19,22 @@ during a build process. * [Compile with AOT](guide/aot-compiler#compile) * [Bootstrap](guide/aot-compiler#bootstrap) * [Tree shaking](guide/aot-compiler#tree-shaking) - - *[Rollup](guide/aot-compiler#rollup) - *[Rollup Plugins](guide/aot-compiler#rollup-plugins) - *[Run Rollup](guide/aot-compiler#run-rollup) - + * [Rollup](guide/aot-compiler#rollup) + * [Rollup Plugins](guide/aot-compiler#rollup-plugins) + * [Run Rollup](guide/aot-compiler#run-rollup) * [Load the bundle](guide/aot-compiler#load) * [Serve the app](guide/aot-compiler#serve) * [AOT QuickStart source code](guide/aot-compiler#source-code) * [Workflow and convenience script](guide/aot-compiler#workflow) - - *[Develop JIT along with AOT](guide/aot-compiler#run-jit) - + * [Develop JIT along with AOT](guide/aot-compiler#run-jit) * [Tour of Heroes](guide/aot-compiler#toh) - - *[JIT in development, AOT in production](guide/aot-compiler#jit-dev-aot-prod) - *[Tree shaking](guide/aot-compiler#shaking) - *[Running the application](guide/aot-compiler#running-app) - *[Inspect the Bundle](guide/aot-compiler#inspect-bundle) - - + * [JIT in development, AOT in production](guide/aot-compiler#jit-dev-aot-prod) + * [Tree shaking](guide/aot-compiler#shaking) + * [Running the application](guide/aot-compiler#running-app) + * [Inspect the Bundle](guide/aot-compiler#inspect-bundle) {@a overview} - - ## Overview An Angular application consists largely of components and their HTML templates. @@ -54,15 +42,9 @@ Before the browser can render the application, the components and templates must be converted to executable JavaScript by the _Angular compiler_.
- - - -Watch compiler author Tobias Bosch explain the Angular Compiler at AngularConnect 2016. - + Watch compiler author Tobias Bosch explain the Angular Compiler at AngularConnect 2016.
- - You can compile the app in the browser, at runtime, as the application loads, using the **_just-in-time_ (JIT) compiler**. This is the standard development approach shown throughout the documentation. It's great but it has shortcomings. @@ -79,12 +61,8 @@ JIT compilation discovers them at runtime, which is late in the process. The **_ahead-of-time_ (AOT) compiler** can catch template errors early and improve performance by compiling at build time. - - {@a aot-jit} - - ## _Ahead-of-time_ (AOT) vs _just-in-time_ (JIT) There is actually only one Angular compiler. The difference between AOT and JIT is a matter of timing and tooling. @@ -93,7 +71,6 @@ with JIT it runs every time for every user at runtime using a different set of l {@a why-aot} - ## Why do AOT compilation? *Faster rendering* @@ -117,47 +94,33 @@ The compiler is roughly half of Angular itself, so omitting it dramatically redu The AOT compiler detects and reports template binding errors during the build step before users can see them. - *Better security* AOT compiles HTML templates and components into JavaScript files long before they are served to the client. With no templates to read and no risky client-side HTML or JavaScript evaluation, there are fewer opportunities for injection attacks. - {@a compile} - - ## Compile with AOT Preparing for offline compilation takes a few simple steps. Take the Setup as a starting point. A few minor changes to the lone `app.component` lead to these two class and HTML files: - - - - - - - - Install a few new npm dependencies with the following command: npm install @angular/compiler-cli @angular/platform-server --save - - You will run the `ngc` compiler provided in the `@angular/compiler-cli` npm package instead of the TypeScript compiler (`tsc`). @@ -167,13 +130,9 @@ instead of the TypeScript compiler (`tsc`). Copy the original `src/tsconfig.json` to a file called `tsconfig-aot.json` on the project root, then modify it as follows. - - - - The `compilerOptions` section is unchanged except for one property. **Set the `module` to `es2015`**. This is important as explained later in the [Tree Shaking](guide/aot-compiler#tree-shaking) section. @@ -185,7 +144,6 @@ to store the compiled output files in a new `aot` folder. The `"skipMetadataEmit" : true` property prevents the compiler from generating metadata files with the compiled application. Metadata files are not necessary when targeting TypeScript files, so there is no reason to include them. - ***Component-relative template URLS*** The AOT compiler requires that `@Component` URLS for external templates and CSS files be _component-relative_. @@ -194,7 +152,6 @@ For example, an `'app.component.html'` URL means that the template file is a sib While JIT app URLs are more flexible, stick with _component-relative_ URLs for compatibility with AOT compilation. - ***Compiling the application*** Initiate AOT compilation from the command line using the previously installed `ngc` compiler by executing: @@ -203,24 +160,13 @@ Initiate AOT compilation from the command line using the previously installed `n node_modules/.bin/ngc -p tsconfig-aot.json - -
- - - -Windows users should surround the `ngc` command in double quotes: - - - "node_modules/.bin/ngc" -p tsconfig-aot.json - - - - + Windows users should surround the `ngc` command in double quotes: + + "node_modules/.bin/ngc" -p tsconfig-aot.json +
- - `ngc` expects the `-p` switch to point to a `tsconfig.json` file or a folder containing a `tsconfig.json` file. After `ngc` completes, look for a collection of _NgFactory_ files in the `aot` folder. @@ -232,37 +178,19 @@ and a JavaScript representation of the component's template. Note that the original component class is still referenced internally by the generated factory.
+ The curious can open `aot/app.component.ngfactory.ts` to see the original Angular template syntax + compiled to TypeScript, its intermediate form. - - -The curious can open `aot/app.component.ngfactory.ts` to see the original Angular template syntax -compiled to TypeScript, its intermediate form. - -JIT compilation generates these same _NgFactories_ in memory where they are largely invisible. -AOT compilation reveals them as separate, physical files. - - + JIT compilation generates these same _NgFactories_ in memory where they are largely invisible. + AOT compilation reveals them as separate, physical files.
- - - -
- - - -Do not edit the _NgFactories_! Re-compilation replaces these files and all edits will be lost. - - + Do not edit the _NgFactories_! Re-compilation replaces these files and all edits will be lost.
- - {@a bootstrap} - - ## Bootstrap The AOT approach changes application bootstrapping. @@ -278,27 +206,17 @@ Switch from the `platformBrowserDynamic.bootstrap` used in JIT compilation to Here is AOT bootstrap in `main.ts` next to the original JIT version: - - - - - - - - Be sure to [recompile](guide/aot-compiler#compiling-aot) with `ngc`! - {@a tree-shaking} - ## Tree shaking AOT compilation sets the stage for further optimization through a process called _tree shaking_. @@ -317,10 +235,8 @@ Tree shaking can only target JavaScript code. AOT compilation converts more of the application to JavaScript, which in turn makes more of the application "tree shakable". - {@a rollup} - ### Rollup This cookbook illustrates a tree shaking utility called _Rollup_. @@ -331,46 +247,32 @@ It produces a final code _bundle_ that excludes code that is exported, but never Rollup can only tree shake `ES2015` modules which have `import` and `export` statements.
- - - -Recall that `tsconfig-aot.json` is configured to produce `ES2015` modules. -It's not important that the code itself be written with `ES2015` syntax such as `class` and `const`. -What matters is that the code uses ES `import` and `export` statements rather than `require` statements. - + Recall that `tsconfig-aot.json` is configured to produce `ES2015` modules. + It's not important that the code itself be written with `ES2015` syntax such as `class` and `const`. + What matters is that the code uses ES `import` and `export` statements rather than `require` statements.
- - In the terminal window, install the Rollup dependencies with this command: npm install rollup rollup-plugin-node-resolve rollup-plugin-commonjs rollup-plugin-uglify --save-dev - - Next, create a configuration file (`rollup-config.js`) in the project root directory to tell Rollup how to process the application. The cookbook configuration file looks like this. - - - - This config file tells Rollup that the app entry point is `src/app/main.js` . The `dest` attribute tells Rollup to create a bundle called `build.js` in the `dist` folder. It overrides the default `onwarn` method in order to skip annoying messages about the AOT compiler's use of the `this` keyword. The next section covers the plugins in more depth. - {@a rollup-plugins} - ### Rollup Plugins Optional plugins filter and transform the Rollup inputs and output. @@ -389,89 +291,53 @@ Rollup then preserves the parts of `RxJS` referenced by the application in the final bundle. Using it is straigthforward. Add the following to the `plugins` array in `rollup-config.js`: - - - - *Minification* Rollup tree shaking reduces code size considerably. Minification makes it smaller still. This cookbook relies on the _uglify_ Rollup plugin to minify and mangle the code. Add the following to the `plugins` array: - - - -
- - - -In a production setting, you would also enable gzip on the web server to compress -the code into an even smaller package going over the wire. - - + In a production setting, you would also enable gzip on the web server to compress + the code into an even smaller package going over the wire.
- - {@a run-rollup} - ### Run Rollup + Execute the Rollup process with this command: node_modules/.bin/rollup -c rollup-config.js - -
- - - -Windows users should surround the `rollup` command in double quotes: - - - "node_modules/.bin/rollup" -c rollup-config.js - - - - + Windows users should surround the `rollup` command in double quotes: + + "node_modules/.bin/rollup" -c rollup-config.js +
- - - - {@a load} - - ## Load the bundle Loading the generated application bundle does not require a module loader like SystemJS. Remove the scripts that concern SystemJS. Instead, load the bundle file using a single `