docs: convert AoT/JiT to approved spelling, AOT/JIT (#2969)
This commit is contained in:
parent
0d5073e74b
commit
0bdda1d358
|
@ -25,7 +25,7 @@ block includes
|
||||||
|
|
||||||
a#aot
|
a#aot
|
||||||
:marked
|
:marked
|
||||||
## Ahead-of-Time (AoT) compilation
|
## Ahead-of-time (AOT) compilation
|
||||||
.l-sub-section
|
.l-sub-section
|
||||||
:marked
|
:marked
|
||||||
You can compile Angular applications at build-time.
|
You can compile Angular applications at build-time.
|
||||||
|
@ -393,7 +393,7 @@ a#H
|
||||||
|
|
||||||
a#jit
|
a#jit
|
||||||
:marked
|
:marked
|
||||||
## Just-in-Time (JiT) compilation
|
## Just-in-time (JIT) compilation
|
||||||
.l-sub-section
|
.l-sub-section
|
||||||
:marked
|
:marked
|
||||||
With Angular _just-in-time_ bootstrapping you compile your components<span if-docs="ts"> and modules</span> in the browser
|
With Angular _just-in-time_ bootstrapping you compile your components<span if-docs="ts"> and modules</span> in the browser
|
||||||
|
|
|
@ -113,7 +113,7 @@ table(width="100%")
|
||||||
td <ngio-ex>main.ts</ngio-ex>
|
td <ngio-ex>main.ts</ngio-ex>
|
||||||
td
|
td
|
||||||
:marked
|
:marked
|
||||||
Compiles the application with the [JiT compiler](../glossary.html#jit)
|
Compiles the application with the [JIT compiler](../glossary.html#jit)
|
||||||
and [bootstraps](appmodule.html#main "bootstrap the application") the application to run in the browser.
|
and [bootstraps](appmodule.html#main "bootstrap the application") the application to run in the browser.
|
||||||
That's a reasonable choice for the development of most projects and
|
That's a reasonable choice for the development of most projects and
|
||||||
it's the only viable choice for a sample running in a _live-coding_ environment like Plunker.
|
it's the only viable choice for a sample running in a _live-coding_ environment like Plunker.
|
||||||
|
|
|
@ -1,7 +1,7 @@
|
||||||
include ../_util-fns
|
include ../_util-fns
|
||||||
|
|
||||||
:marked
|
:marked
|
||||||
This cookbook describes how to radically improve performance by compiling _Ahead of Time_ (AoT)
|
This cookbook describes how to radically improve performance by compiling _Ahead of Time_ (AOT)
|
||||||
during a build process.
|
during a build process.
|
||||||
|
|
||||||
a#toc
|
a#toc
|
||||||
|
@ -9,7 +9,7 @@ a#toc
|
||||||
## Table of Contents
|
## Table of Contents
|
||||||
* [Overview](#overview)
|
* [Overview](#overview)
|
||||||
* [_Ahead-of-Time_ vs _Just-in-Time_](#aot-jit)
|
* [_Ahead-of-Time_ vs _Just-in-Time_](#aot-jit)
|
||||||
* [Compile with AoT](#compile)
|
* [Compile with AOT](#compile)
|
||||||
* [Bootstrap](#bootstrap)
|
* [Bootstrap](#bootstrap)
|
||||||
* [Tree Shaking](#tree-shaking)
|
* [Tree Shaking](#tree-shaking)
|
||||||
* [Load the bundle](#load)
|
* [Load the bundle](#load)
|
||||||
|
@ -29,37 +29,37 @@ a#overview
|
||||||
:marked
|
:marked
|
||||||
<a href="https://www.youtube.com/watch?v=kW9cJsvcsGo" target="_blank">Watch compiler author Tobias Bosch explain the Angular Compiler</a> at AngularConnect 2016.
|
<a href="https://www.youtube.com/watch?v=kW9cJsvcsGo" target="_blank">Watch compiler author Tobias Bosch explain the Angular Compiler</a> at AngularConnect 2016.
|
||||||
:marked
|
:marked
|
||||||
You can compile the app in the browser, at runtime, as the application loads, using the **_Just-in-Time_ (JiT) compiler**.
|
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.
|
This is the standard development approach shown throughout the documentation.
|
||||||
It's great .. but it has shortcomings.
|
It's great .. but it has shortcomings.
|
||||||
|
|
||||||
JiT compilation incurs a runtime performance penalty.
|
JIT compilation incurs a runtime performance penalty.
|
||||||
Views take longer to render because of the in-browser compilation step.
|
Views take longer to render because of the in-browser compilation step.
|
||||||
The application is bigger because it includes the Angular compiler
|
The application is bigger because it includes the Angular compiler
|
||||||
and a lot of library code that the application won't actually need.
|
and a lot of library code that the application won't actually need.
|
||||||
Bigger apps take longer to transmit and are slower to load.
|
Bigger apps take longer to transmit and are slower to load.
|
||||||
|
|
||||||
Compilation can uncover many component-template binding errors.
|
Compilation can uncover many component-template binding errors.
|
||||||
JiT compilation discovers them at runtime which is later than we'd like.
|
JIT compilation discovers them at runtime which is later than we'd like.
|
||||||
|
|
||||||
The **_Ahead-of-Time_ (AoT) compiler** can catch template errors early and improve performance
|
The **_Ahead-of-Time_ (AOT) compiler** can catch template errors early and improve performance
|
||||||
by compiling at build time as you'll learn in this chapter.
|
by compiling at build time as you'll learn in this chapter.
|
||||||
|
|
||||||
|
|
||||||
a#aot-jit
|
a#aot-jit
|
||||||
.l-main-section
|
.l-main-section
|
||||||
:marked
|
:marked
|
||||||
## _Ahead-of-time_ (AoT) vs _Just-in-time_ (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.
|
There is actually only one Angular compiler. The difference between AOT and JIT is a matter of timing and tooling.
|
||||||
With AoT, the compiler runs once at build time using one set of libraries;
|
With AOT, the compiler runs once at build time using one set of libraries;
|
||||||
With JiT it runs every time for every user at runtime using a different set of libraries.
|
With JIT it runs every time for every user at runtime using a different set of libraries.
|
||||||
|
|
||||||
### Why do AoT compilation?
|
### Why do AOT compilation?
|
||||||
|
|
||||||
*Faster rendering*
|
*Faster rendering*
|
||||||
|
|
||||||
With AoT, the browser downloads a pre-compiled version of the application.
|
With AOT, the browser downloads a pre-compiled version of the application.
|
||||||
The browser loads executable code so it can render the application immediately, without waiting to compile the app first.
|
The browser loads executable code so it can render the application immediately, without waiting to compile the app first.
|
||||||
|
|
||||||
*Fewer asynchronous requests*
|
*Fewer asynchronous requests*
|
||||||
|
@ -75,20 +75,20 @@ a#aot-jit
|
||||||
|
|
||||||
*Detect template errors earlier*
|
*Detect template errors earlier*
|
||||||
|
|
||||||
The AoT compiler detects and reports template binding errors during the build step
|
The AOT compiler detects and reports template binding errors during the build step
|
||||||
before users can see them.
|
before users can see them.
|
||||||
|
|
||||||
|
|
||||||
*Better security*
|
*Better security*
|
||||||
|
|
||||||
AoT compiles HTML templates and components into JavaScript files long before they are served to the client.
|
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,
|
With no templates to read and no risky client-side HTML or JavaScript evaluation,
|
||||||
there are fewer opportunities for injection attacks.
|
there are fewer opportunities for injection attacks.
|
||||||
|
|
||||||
a#compile
|
a#compile
|
||||||
.l-main-section
|
.l-main-section
|
||||||
:marked
|
:marked
|
||||||
## Compile with AoT
|
## Compile with AOT
|
||||||
|
|
||||||
### Prepare for offline compilation
|
### Prepare for offline compilation
|
||||||
Take the <a href='../guide/setup.html'>Setup</a> as a starting point.
|
Take the <a href='../guide/setup.html'>Setup</a> as a starting point.
|
||||||
|
@ -112,7 +112,7 @@ code-example(format='.').
|
||||||
|
|
||||||
`ngc` is a drop-in replacement for `tsc` and is configured much the same way.
|
`ngc` is a drop-in replacement for `tsc` and is configured much the same way.
|
||||||
|
|
||||||
`ngc` requires its own `tsconfig.json` with AoT-oriented settings.
|
`ngc` requires its own `tsconfig.json` with AOT-oriented settings.
|
||||||
Copy the original `tsconfig.json` to a file called `tsconfig-aot.json`, then modify it to look as follows.
|
Copy the original `tsconfig.json` to a file called `tsconfig-aot.json`, then modify it to look as follows.
|
||||||
|
|
||||||
+makeExample('cb-aot-compiler/ts/tsconfig-aot.json', null, 'tsconfig-aot.json')(format='.')
|
+makeExample('cb-aot-compiler/ts/tsconfig-aot.json', null, 'tsconfig-aot.json')(format='.')
|
||||||
|
@ -132,14 +132,14 @@ code-example(format='.').
|
||||||
:marked
|
:marked
|
||||||
***Component-relative Template URLS***
|
***Component-relative Template URLS***
|
||||||
|
|
||||||
The AoT compiler requires that `@Component` URLS for external templates and css files be _component-relative_.
|
The AOT compiler requires that `@Component` URLS for external templates and css files be _component-relative_.
|
||||||
That means that the value of `@Component.templateUrl` is a URL value _relative_ to the component class file.
|
That means that the value of `@Component.templateUrl` is a URL value _relative_ to the component class file.
|
||||||
For example, an `'app.component.html'` URL means that the template file is a sibling of its companion `app.component.ts` file.
|
For example, an `'app.component.html'` URL means that the template file is a sibling of its companion `app.component.ts` file.
|
||||||
|
|
||||||
While JiT app URLs are more flexible, stick with _component-relative_ URLs for compatibility with AoT compilation.
|
While JIT app URLs are more flexible, stick with _component-relative_ URLs for compatibility with AOT compilation.
|
||||||
|
|
||||||
JiT-compiled applications that use the SystemJS loader and _component-relative_ URLs *must set the* `@Component.moduleId` *property to* `module.id`.
|
JIT-compiled applications that use the SystemJS loader and _component-relative_ URLs *must set the* `@Component.moduleId` *property to* `module.id`.
|
||||||
The `module` object is undefined when an AoT-compiled app runs.
|
The `module` object is undefined when an AOT-compiled app runs.
|
||||||
The app fails with a null reference error unless you assign a global `module` value in the `index.html` like this:
|
The app fails with a null reference error unless you assign a global `module` value in the `index.html` like this:
|
||||||
+makeExample('cb-aot-compiler/ts/index.html','moduleId')(format='.')
|
+makeExample('cb-aot-compiler/ts/index.html','moduleId')(format='.')
|
||||||
.l-sub-section
|
.l-sub-section
|
||||||
|
@ -149,7 +149,7 @@ code-example(format='.').
|
||||||
:marked
|
:marked
|
||||||
### Compiling the application
|
### Compiling the application
|
||||||
|
|
||||||
Initiate AoT compilation from the command line using the previously installed `ngc` compiler by executing:
|
Initiate AOT compilation from the command line using the previously installed `ngc` compiler by executing:
|
||||||
code-example(format='.').
|
code-example(format='.').
|
||||||
node_modules/.bin/ngc -p tsconfig-aot.json
|
node_modules/.bin/ngc -p tsconfig-aot.json
|
||||||
.l-sub-section
|
.l-sub-section
|
||||||
|
@ -171,8 +171,8 @@ code-example(format='.').
|
||||||
The curious can open the `aot/app.component.ngfactory.ts` to see the original Angular template syntax
|
The curious can open the `aot/app.component.ngfactory.ts` to see the original Angular template syntax
|
||||||
in its intermediate, compiled-to-TypeScript form.
|
in its intermediate, compiled-to-TypeScript form.
|
||||||
|
|
||||||
JiT compilation generates these same _NgFactories_ in memory where they are largely invisible.
|
JIT compilation generates these same _NgFactories_ in memory where they are largely invisible.
|
||||||
AoT compilation reveals them as separate, physical files.
|
AOT compilation reveals them as separate, physical files.
|
||||||
|
|
||||||
:marked
|
:marked
|
||||||
.alert.is-important
|
.alert.is-important
|
||||||
|
@ -184,21 +184,21 @@ a#bootstrap
|
||||||
:marked
|
:marked
|
||||||
## Bootstrap
|
## Bootstrap
|
||||||
|
|
||||||
The AoT path changes application bootstrapping.
|
The AOT path changes application bootstrapping.
|
||||||
|
|
||||||
Instead of bootstrapping `AppModule`, you bootstrap the application with the generated module factory, `AppModuleNgFactory`.
|
Instead of bootstrapping `AppModule`, you bootstrap the application with the generated module factory, `AppModuleNgFactory`.
|
||||||
|
|
||||||
Switch from the `platformBrowserDynamic.bootstrap` used in JiT compilation to
|
Switch from the `platformBrowserDynamic.bootstrap` used in JIT compilation to
|
||||||
`platformBrowser().bootstrapModuleFactory` and pass in the `AppModuleNgFactory`.
|
`platformBrowser().bootstrapModuleFactory` and pass in the `AppModuleNgFactory`.
|
||||||
|
|
||||||
Here is AoT bootstrap in `main.ts` next to the familiar JiT version:
|
Here is AOT bootstrap in `main.ts` next to the familiar JIT version:
|
||||||
|
|
||||||
+makeTabs(
|
+makeTabs(
|
||||||
`cb-aot-compiler/ts/app/main.ts,
|
`cb-aot-compiler/ts/app/main.ts,
|
||||||
cb-aot-compiler/ts/app/main-jit.ts`,
|
cb-aot-compiler/ts/app/main-jit.ts`,
|
||||||
null,
|
null,
|
||||||
`app/main.ts (AoT),
|
`app/main.ts (AOT),
|
||||||
app/main.ts (JiT)`
|
app/main.ts (JIT)`
|
||||||
)
|
)
|
||||||
|
|
||||||
:marked
|
:marked
|
||||||
|
@ -208,7 +208,7 @@ a#tree-shaking
|
||||||
:marked
|
:marked
|
||||||
## Tree Shaking
|
## Tree Shaking
|
||||||
|
|
||||||
AoT compilation sets the stage for further optimization through a process called _Tree Shaking_.
|
AOT compilation sets the stage for further optimization through a process called _Tree Shaking_.
|
||||||
A Tree Shaker walks the dependency graph, top to bottom, and _shakes out_ unused code like
|
A Tree Shaker walks the dependency graph, top to bottom, and _shakes out_ unused code like
|
||||||
dead needles in a Christmas tree.
|
dead needles in a Christmas tree.
|
||||||
|
|
||||||
|
@ -219,9 +219,9 @@ a#tree-shaking
|
||||||
For example, this demo application doesn't use anything from the `@angular/forms` library.
|
For example, this demo application doesn't use anything from the `@angular/forms` library.
|
||||||
There is no reason to download Forms-related Angular code and tree shaking ensures that you don't.
|
There is no reason to download Forms-related Angular code and tree shaking ensures that you don't.
|
||||||
|
|
||||||
Tree Shaking and AoT compilation are separate steps.
|
Tree Shaking and AOT compilation are separate steps.
|
||||||
Tree Shaking can only target JavaScript code.
|
Tree Shaking can only target JavaScript code.
|
||||||
AoT compilation converts more of the application to JavaScript,
|
AOT compilation converts more of the application to JavaScript,
|
||||||
which in turn makes more of the application "Tree Shakable".
|
which in turn makes more of the application "Tree Shakable".
|
||||||
|
|
||||||
### Rollup
|
### Rollup
|
||||||
|
@ -323,7 +323,7 @@ code-example(format='.').
|
||||||
a#source-code
|
a#source-code
|
||||||
.l-main-section
|
.l-main-section
|
||||||
:marked
|
:marked
|
||||||
## AoT QuickStart Source Code
|
## AOT QuickStart Source Code
|
||||||
|
|
||||||
Here's the pertinent source code:
|
Here's the pertinent source code:
|
||||||
+makeTabs(
|
+makeTabs(
|
||||||
|
@ -348,20 +348,20 @@ a#toh
|
||||||
## Tour of Heroes
|
## Tour of Heroes
|
||||||
|
|
||||||
The sample above is a trivial variation of the QuickStart app.
|
The sample above is a trivial variation of the QuickStart app.
|
||||||
In this section you apply what you've learned about AoT compilation and Tree Shaking
|
In this section you apply what you've learned about AOT compilation and Tree Shaking
|
||||||
to an app with more substance, the tutorial [_Tour of Heroes_](../tutorial/toh-pt6.html).
|
to an app with more substance, the tutorial [_Tour of Heroes_](../tutorial/toh-pt6.html).
|
||||||
|
|
||||||
### JiT in development, AoT in production
|
### JIT in development, AOT in production
|
||||||
|
|
||||||
Today AoT compilation and Tree Shaking take more time than is practical for development. That will change soon.
|
Today AOT compilation and Tree Shaking take more time than is practical for development. That will change soon.
|
||||||
For now, it's best to JiT compile in development and switch to AoT compilation before deploying to production.
|
For now, it's best to JIT compile in development and switch to AOT compilation before deploying to production.
|
||||||
|
|
||||||
Fortunately, the source code can be compiled either way without change _if_ you account for a few key differences.
|
Fortunately, the source code can be compiled either way without change _if_ you account for a few key differences.
|
||||||
|
|
||||||
***index.html***
|
***index.html***
|
||||||
|
|
||||||
The JiT and AoT apps require their own `index.html` files because they setup and launch so differently.
|
The JIT and AOT apps require their own `index.html` files because they setup and launch so differently.
|
||||||
**Put the AoT version in the `/aot` folder** because two `index.html` files can't be in the same folder.
|
**Put the AOT version in the `/aot` folder** because two `index.html` files can't be in the same folder.
|
||||||
|
|
||||||
Here they are for comparison:
|
Here they are for comparison:
|
||||||
|
|
||||||
|
@ -369,20 +369,20 @@ a#toh
|
||||||
`toh-6/ts/aot/index.html,
|
`toh-6/ts/aot/index.html,
|
||||||
toh-6/ts/index.html`,
|
toh-6/ts/index.html`,
|
||||||
null,
|
null,
|
||||||
`aot/index.html (AoT),
|
`aot/index.html (AOT),
|
||||||
index.html (JiT)`
|
index.html (JIT)`
|
||||||
)
|
)
|
||||||
|
|
||||||
:marked
|
:marked
|
||||||
The JiT version relies on `SystemJS` to load individual modules and requires the `reflect-metadata` shim.
|
The JIT version relies on `SystemJS` to load individual modules and requires the `reflect-metadata` shim.
|
||||||
Both scripts appear in its `index.html`.
|
Both scripts appear in its `index.html`.
|
||||||
|
|
||||||
The AoT version loads the entire application in a single script, `aot/dist/build.js`.
|
The AOT version loads the entire application in a single script, `aot/dist/build.js`.
|
||||||
It does not need `SystemJS` or the `reflect-metadata` shim; those scripts are absent from its `index.html`
|
It does not need `SystemJS` or the `reflect-metadata` shim; those scripts are absent from its `index.html`
|
||||||
|
|
||||||
***main.ts***
|
***main.ts***
|
||||||
|
|
||||||
JiT and AoT applications boot in much the same way but require different Angular libraries to do so.
|
JIT and AOT applications boot in much the same way but require different Angular libraries to do so.
|
||||||
The key differences, covered in the [Bootstrap](#bootstrap) section above,
|
The key differences, covered in the [Bootstrap](#bootstrap) section above,
|
||||||
are evident in these `main` files which can and should reside in the same folder:
|
are evident in these `main` files which can and should reside in the same folder:
|
||||||
|
|
||||||
|
@ -390,16 +390,16 @@ a#toh
|
||||||
`toh-6/ts/app/main-aot.ts,
|
`toh-6/ts/app/main-aot.ts,
|
||||||
toh-6/ts/app/main.ts`,
|
toh-6/ts/app/main.ts`,
|
||||||
null,
|
null,
|
||||||
`app/main-aot.ts (AoT),
|
`app/main-aot.ts (AOT),
|
||||||
app/main.ts (JiT)`
|
app/main.ts (JIT)`
|
||||||
)
|
)
|
||||||
|
|
||||||
:marked
|
:marked
|
||||||
***TypeScript configuration***
|
***TypeScript configuration***
|
||||||
|
|
||||||
JiT-compiled applications transpile to `commonjs` modules.
|
JIT-compiled applications transpile to `commonjs` modules.
|
||||||
AoT-compiled applications transpile to _ES2015_/_ES6_ modules to facilitate Tree Shaking.
|
AOT-compiled applications transpile to _ES2015_/_ES6_ modules to facilitate Tree Shaking.
|
||||||
AoT requires its own TypeScript configuration settings as well.
|
AOT requires its own TypeScript configuration settings as well.
|
||||||
|
|
||||||
You'll need separate TypeScript configuration files such as these:
|
You'll need separate TypeScript configuration files such as these:
|
||||||
|
|
||||||
|
@ -407,8 +407,8 @@ a#toh
|
||||||
`toh-6/ts/tsconfig-aot.json,
|
`toh-6/ts/tsconfig-aot.json,
|
||||||
toh-6/ts/tsconfig.json`,
|
toh-6/ts/tsconfig.json`,
|
||||||
null,
|
null,
|
||||||
`tsconfig-aot.json (AoT),
|
`tsconfig-aot.json (AOT),
|
||||||
tsconfig.json (JiT)`
|
tsconfig.json (JIT)`
|
||||||
)
|
)
|
||||||
|
|
||||||
.callout.is-helpful
|
.callout.is-helpful
|
||||||
|
@ -434,7 +434,7 @@ a#toh
|
||||||
|
|
||||||
.alert.is-important
|
.alert.is-important
|
||||||
:marked
|
:marked
|
||||||
The general audience instructions for running the AoT build of the Tour of Heroes app are not ready.
|
The general audience instructions for running the AOT build of the Tour of Heroes app are not ready.
|
||||||
|
|
||||||
The following instructions presuppose that you have cloned the
|
The following instructions presuppose that you have cloned the
|
||||||
<a href="https://github.com/angular/angular.io" target="_blank">angular.io</a>
|
<a href="https://github.com/angular/angular.io" target="_blank">angular.io</a>
|
||||||
|
@ -442,9 +442,9 @@ a#toh
|
||||||
|
|
||||||
The _Tour of Heroes_ source code is in the `public/docs/_examples/toh-6/ts` folder.
|
The _Tour of Heroes_ source code is in the `public/docs/_examples/toh-6/ts` folder.
|
||||||
:marked
|
:marked
|
||||||
Run the JiT-compiled app with `npm start` as for all other JiT examples.
|
Run the JIT-compiled app with `npm start` as for all other JIT examples.
|
||||||
|
|
||||||
Compiling with AoT presupposes certain supporting files, most of them discussed above.
|
Compiling with AOT presupposes certain supporting files, most of them discussed above.
|
||||||
+makeTabs(
|
+makeTabs(
|
||||||
`toh-6/ts/aot/index.html,
|
`toh-6/ts/aot/index.html,
|
||||||
toh-6/ts/aot/bs-config.json,
|
toh-6/ts/aot/bs-config.json,
|
||||||
|
@ -463,14 +463,14 @@ code-example(format='.').
|
||||||
"build:aot": "ngc -p tsconfig-aot.json && rollup -c rollup-config.js",
|
"build:aot": "ngc -p tsconfig-aot.json && rollup -c rollup-config.js",
|
||||||
"lite:aot": "lite-server -c aot/bs-config.json",
|
"lite:aot": "lite-server -c aot/bs-config.json",
|
||||||
:marked
|
:marked
|
||||||
Copy the AoT distribution files into the `/aot` folder with the node script:
|
Copy the AOT distribution files into the `/aot` folder with the node script:
|
||||||
code-example(format='.').
|
code-example(format='.').
|
||||||
node copy-dist-files
|
node copy-dist-files
|
||||||
.l-sub-section
|
.l-sub-section
|
||||||
:marked
|
:marked
|
||||||
You won't do that again until there are updates to `zone.js` or the `core-js` shim for old browsers.
|
You won't do that again until there are updates to `zone.js` or the `core-js` shim for old browsers.
|
||||||
:marked
|
:marked
|
||||||
Now AoT-compile the app and launch it with the `lite` server:
|
Now AOT-compile the app and launch it with the `lite` server:
|
||||||
code-example(format='.').
|
code-example(format='.').
|
||||||
npm run build:aot && npm run lite:aot
|
npm run build:aot && npm run lite:aot
|
||||||
|
|
||||||
|
|
|
@ -14,13 +14,13 @@ a#top
|
||||||
* [Use the **_ng-xi18n_ extraction tool** to create a translation source file](#ng-xi18n)
|
* [Use the **_ng-xi18n_ extraction tool** to create a translation source file](#ng-xi18n)
|
||||||
* [Translate](#translate)
|
* [Translate](#translate)
|
||||||
* [Merge the completed translation file into the app](#merge)
|
* [Merge the completed translation file into the app](#merge)
|
||||||
* [JiT configuration](#jit)
|
* [JIT configuration](#jit)
|
||||||
* [AoT configuration](#aot)
|
* [AOT configuration](#aot)
|
||||||
* [Translation file maintenance and _id_ changes](#maintenance)
|
* [Translation file maintenance and _id_ changes](#maintenance)
|
||||||
|
|
||||||
:marked
|
:marked
|
||||||
**Try this** <live-example name="cb-i18n" title="i18n Example in Spanish">live example</live-example>
|
**Try this** <live-example name="cb-i18n" title="i18n Example in Spanish">live example</live-example>
|
||||||
of a JiT-compiled app, translated into Spanish.
|
of a JIT-compiled app, translated into Spanish.
|
||||||
|
|
||||||
|
|
||||||
a#angular-i18n
|
a#angular-i18n
|
||||||
|
@ -417,22 +417,22 @@ a#merge
|
||||||
(`es` or `en-US` for instance)
|
(`es` or `en-US` for instance)
|
||||||
|
|
||||||
_How_ you provide this information depends upon whether you compile with
|
_How_ you provide this information depends upon whether you compile with
|
||||||
the JiT (_Just-in-Time_) compiler or the AoT (_Ahead-of-Time_) compiler.
|
the JIT (_Just-in-Time_) compiler or the AOT (_Ahead-of-Time_) compiler.
|
||||||
|
|
||||||
* with [JiT](#jit), you provide the information at bootstrap time.
|
* with [JIT](#jit), you provide the information at bootstrap time.
|
||||||
* with [AoT](#aot), you pass the information as `ngc` options.
|
* with [AOT](#aot), you pass the information as `ngc` options.
|
||||||
|
|
||||||
a#jit
|
a#jit
|
||||||
.l-main-section
|
.l-main-section
|
||||||
:marked
|
:marked
|
||||||
### Merge with the JiT compiler
|
### Merge with the JIT compiler
|
||||||
|
|
||||||
The JiT (_Just-in-Time_) compiler compiles the application in the browser as the application loads.
|
The JIT (_Just-in-Time_) compiler compiles the application in the browser as the application loads.
|
||||||
Translation with the JiT compiler is a dynamic process of ...
|
Translation with the JIT compiler is a dynamic process of ...
|
||||||
|
|
||||||
1. determining the language version for the current user,
|
1. determining the language version for the current user,
|
||||||
2. importing the appropriate language translation file as a string constant,
|
2. importing the appropriate language translation file as a string constant,
|
||||||
3. creating corresponding translation providers to guide the JiT compiler,
|
3. creating corresponding translation providers to guide the JIT compiler,
|
||||||
4. bootstrapping the application with those providers.
|
4. bootstrapping the application with those providers.
|
||||||
|
|
||||||
Open `index.html` and revise the launch script as shown here:
|
Open `index.html` and revise the launch script as shown here:
|
||||||
|
@ -456,7 +456,7 @@ a#text-plugin
|
||||||
:marked
|
:marked
|
||||||
### Create translation providers
|
### Create translation providers
|
||||||
|
|
||||||
Three providers tell the JiT compiler how to translate the template texts for a particular language
|
Three providers tell the JIT compiler how to translate the template texts for a particular language
|
||||||
while compiling the application:
|
while compiling the application:
|
||||||
|
|
||||||
* `TRANSLATIONS` is a string containing the content of the translation file.
|
* `TRANSLATIONS` is a string containing the content of the translation file.
|
||||||
|
@ -503,28 +503,28 @@ a#text-plugin
|
||||||
a#aot
|
a#aot
|
||||||
.l-main-section
|
.l-main-section
|
||||||
:marked
|
:marked
|
||||||
### _Internationalize_ with the AoT compiler
|
### _Internationalize_ with the AOT compiler
|
||||||
|
|
||||||
The JiT compiler translates the application into the target language while compiling dynamically in the browser.
|
The JIT compiler translates the application into the target language while compiling dynamically in the browser.
|
||||||
That's flexible but may not be fast enough for your users.
|
That's flexible but may not be fast enough for your users.
|
||||||
|
|
||||||
The AoT (_Ahead-of-Time_) compiler is part of a build process that produces a small, fast, ready-to-run application package.
|
The AOT (_Ahead-of-Time_) compiler is part of a build process that produces a small, fast, ready-to-run application package.
|
||||||
When you internationalize with the AoT compiler, you pre-build a separate application package for each
|
When you internationalize with the AOT compiler, you pre-build a separate application package for each
|
||||||
language. Then in the host web page (`index.html`), you determine which language the user needs
|
language. Then in the host web page (`index.html`), you determine which language the user needs
|
||||||
and serve the appropriate application package.
|
and serve the appropriate application package.
|
||||||
|
|
||||||
This cookbook doesn't cover how to build multiple application packages and
|
This cookbook doesn't cover how to build multiple application packages and
|
||||||
serve them according to the user's language preference.
|
serve them according to the user's language preference.
|
||||||
It does explain the few steps necessary to tell the AoT to apply a translations file.
|
It does explain the few steps necessary to tell the AOT to apply a translations file.
|
||||||
|
|
||||||
Internationalization with the AoT compiler requires some setup specifically for AoT.
|
Internationalization with the AOT compiler requires some setup specifically for AOT.
|
||||||
Start with application project as shown [just before merging the translation file](#app-pre-translationStart)
|
Start with application project as shown [just before merging the translation file](#app-pre-translationStart)
|
||||||
and refer to the [AoT cookbook](aot-compiler.html) to make it _AoT-ready_.
|
and refer to the [AOT cookbook](aot-compiler.html) to make it _AoT-ready_.
|
||||||
|
|
||||||
Next, issue an `ngc` compile command for each supported language (including English).
|
Next, issue an `ngc` compile command for each supported language (including English).
|
||||||
The result is a separate version of the application for each language.
|
The result is a separate version of the application for each language.
|
||||||
|
|
||||||
Tell AoT how to translate by adding three options to the `ngc` command:
|
Tell AOT how to translate by adding three options to the `ngc` command:
|
||||||
* `--i18nFile`: the path to the translation file
|
* `--i18nFile`: the path to the translation file
|
||||||
* `--locale`: the name of the locale
|
* `--locale`: the name of the locale
|
||||||
* `--i18nFormat`: the format of the localization file
|
* `--i18nFormat`: the format of the localization file
|
||||||
|
|
|
@ -24,7 +24,7 @@ a#toc
|
||||||
[Dependency Injection](#dependency-injection)<br>
|
[Dependency Injection](#dependency-injection)<br>
|
||||||
[Host Binding](#host-binding)<br>
|
[Host Binding](#host-binding)<br>
|
||||||
[View and Child Decorators](#view-child-decorators)<br>
|
[View and Child Decorators](#view-child-decorators)<br>
|
||||||
[AoT compilation in _TypeScript_ Only](#aot)<br>
|
[AOT compilation in _TypeScript_ Only](#aot)<br>
|
||||||
|
|
||||||
**Run and compare the live <live-example name="cb-ts-to-js">_TypeScript_</live-example> and <live-example name="cb-ts-to-js" lang="js">JavaScript</live-example>
|
**Run and compare the live <live-example name="cb-ts-to-js">_TypeScript_</live-example> and <live-example name="cb-ts-to-js" lang="js">JavaScript</live-example>
|
||||||
code shown in this cookbook.**
|
code shown in this cookbook.**
|
||||||
|
@ -660,10 +660,10 @@ a#view-child-decorators
|
||||||
a#aot
|
a#aot
|
||||||
.l-main-section
|
.l-main-section
|
||||||
:marked
|
:marked
|
||||||
## AoT Compilation in _TypeScript_ only
|
## AOT Compilation in _TypeScript_ only
|
||||||
|
|
||||||
Angular offers two modes of template compilation, JiT (_Just-in-Time_) and
|
Angular offers two modes of template compilation, JIT (_Just-in-Time_) and
|
||||||
[AoT (_Ahead-of-Time_)](aot-compiler.html).
|
[AOT (_Ahead-of-Time_)](aot-compiler.html).
|
||||||
Currently the AoT compiler only works with _TypeScript_ applications because, in part, it generates
|
Currently the AOT compiler only works with _TypeScript_ applications because, in part, it generates
|
||||||
_TypeScript_ files as an intermediate result.
|
_TypeScript_ files as an intermediate result.
|
||||||
**AoT is not an option for pure JavaScript applications** at this time.
|
**AOT is not an option for pure JavaScript applications** at this time.
|
||||||
|
|
|
@ -25,7 +25,7 @@ block includes
|
||||||
|
|
||||||
a#aot
|
a#aot
|
||||||
:marked
|
:marked
|
||||||
## Ahead-of-Time (AoT) compilation
|
## Ahead-of-time (AOT) compilation
|
||||||
.l-sub-section
|
.l-sub-section
|
||||||
:marked
|
:marked
|
||||||
You can compile Angular applications at build-time.
|
You can compile Angular applications at build-time.
|
||||||
|
@ -393,7 +393,7 @@ a#H
|
||||||
|
|
||||||
a#jit
|
a#jit
|
||||||
:marked
|
:marked
|
||||||
## Just-in-Time (JiT) compilation
|
## Just-in-time (JIT) compilation
|
||||||
.l-sub-section
|
.l-sub-section
|
||||||
:marked
|
:marked
|
||||||
With Angular _just-in-time_ bootstrapping you compile your components<span if-docs="ts"> and modules</span> in the browser
|
With Angular _just-in-time_ bootstrapping you compile your components<span if-docs="ts"> and modules</span> in the browser
|
||||||
|
|
|
@ -99,14 +99,14 @@ l-main-section
|
||||||
There are many ways to bootstrap an application.
|
There are many ways to bootstrap an application.
|
||||||
The variations depend upon how you want to compile the application and where you want to run it.
|
The variations depend upon how you want to compile the application and where you want to run it.
|
||||||
|
|
||||||
In the beginning, you will compile the application dynamically with the _Just-in-Time (JiT)_ compiler
|
In the beginning, you will compile the application dynamically with the _Just-in-Time (JIT)_ compiler
|
||||||
and you'll run it in a browser. You can learn about other options later.
|
and you'll run it in a browser. You can learn about other options later.
|
||||||
|
|
||||||
The recommended place to bootstrap a JiT-compiled browser application is in a separate file
|
The recommended place to bootstrap a JIT-compiled browser application is in a separate file
|
||||||
in the `app` folder named `app/main.ts`
|
in the `app` folder named `app/main.ts`
|
||||||
+makeExample('setup/ts/app/main.ts','','app/main.ts')(format='.')
|
+makeExample('setup/ts/app/main.ts','','app/main.ts')(format='.')
|
||||||
:marked
|
:marked
|
||||||
This code creates a browser platform for dynamic (JiT) compilation and
|
This code creates a browser platform for dynamic (JIT) compilation and
|
||||||
bootstraps the `AppModule` described above.
|
bootstraps the `AppModule` described above.
|
||||||
|
|
||||||
The _bootstrapping_ process sets up the execution environment,
|
The _bootstrapping_ process sets up the execution environment,
|
||||||
|
|
|
@ -29,9 +29,9 @@ block includes
|
||||||
## Sync with Angular v.2.2.0 (2016-11-14)
|
## Sync with Angular v.2.2.0 (2016-11-14)
|
||||||
Docs and code samples updated and tested with Angular v.2.2.0
|
Docs and code samples updated and tested with Angular v.2.2.0
|
||||||
|
|
||||||
## UPDATE: NgUpgrade Guide for the AoT friendly _upgrade/static_ module (2016-11-14)
|
## UPDATE: NgUpgrade Guide for the AOT friendly _upgrade/static_ module (2016-11-14)
|
||||||
The updated [NgUpgrade Guide](upgrade.html) guide covers the
|
The updated [NgUpgrade Guide](upgrade.html) guide covers the
|
||||||
new AoT friendly `upgrade/static` module
|
new AOT friendly `upgrade/static` module
|
||||||
released in v.2.2.0, which is the recommended
|
released in v.2.2.0, which is the recommended
|
||||||
facility for migrating from Angular 1 to Angular 2.
|
facility for migrating from Angular 1 to Angular 2.
|
||||||
The documentation for the version prior to v.2.2.0 has been removed.
|
The documentation for the version prior to v.2.2.0 has been removed.
|
||||||
|
@ -73,9 +73,9 @@ block includes
|
||||||
## Sync with Angular v.2.1.0 (2016-10-12)
|
## Sync with Angular v.2.1.0 (2016-10-12)
|
||||||
Docs and code samples updated and tested with Angular v.2.1.0
|
Docs and code samples updated and tested with Angular v.2.1.0
|
||||||
|
|
||||||
## NEW "Ahead of Time (AoT) Compilation" cookbook (2016-10-11)
|
## NEW "Ahead of time (AOT) Compilation" cookbook (2016-10-11)
|
||||||
The NEW [Ahead of Time (AoT) Compilation](../cookbook/aot-compiler.html) cookbook
|
The NEW [Ahead of time (AOT) Compilation](../cookbook/aot-compiler.html) cookbook
|
||||||
explains what AoT compilation is and why you'd want it.
|
explains what AOT compilation is and why you'd want it.
|
||||||
It demonstrates the basics with a QuickStart app
|
It demonstrates the basics with a QuickStart app
|
||||||
followed by the more advanced considerations of compiling and bundling the Tour of Heroes.
|
followed by the more advanced considerations of compiling and bundling the Tour of Heroes.
|
||||||
|
|
||||||
|
@ -118,7 +118,7 @@ block includes
|
||||||
have been converted to _module-relative_ URLs.
|
have been converted to _module-relative_ URLs.
|
||||||
We added the `moduleId: module.id` property-and-value to their `@Component` metadata.
|
We added the `moduleId: module.id` property-and-value to their `@Component` metadata.
|
||||||
|
|
||||||
This change is a requirement for compilation with AoT compiler when the app loads
|
This change is a requirement for compilation with AOT compiler when the app loads
|
||||||
modules with SystemJS as the samples currently do.
|
modules with SystemJS as the samples currently do.
|
||||||
|
|
||||||
## "Lifecycle Hooks" guide simplified (2016-09-24)
|
## "Lifecycle Hooks" guide simplified (2016-09-24)
|
||||||
|
|
|
@ -136,7 +136,7 @@ a#bootstrap
|
||||||
Angular offers a variety of bootstrapping options, targeting multiple platforms.
|
Angular offers a variety of bootstrapping options, targeting multiple platforms.
|
||||||
In this page we consider two options, both targeting the browser.
|
In this page we consider two options, both targeting the browser.
|
||||||
|
|
||||||
### Dynamic bootstrapping with the Just-in-time (JiT) compiler
|
### Dynamic bootstrapping with the Just-in-time (JIT) compiler
|
||||||
In the first, _dynamic_ option, the [Angular compiler](../cookbook/ngmodule-faq.html#q-angular-compiler "About the Angular Compiler")
|
In the first, _dynamic_ option, the [Angular compiler](../cookbook/ngmodule-faq.html#q-angular-compiler "About the Angular Compiler")
|
||||||
compiles the application in the browser and then launches the app.
|
compiles the application in the browser and then launches the app.
|
||||||
|
|
||||||
|
@ -147,7 +147,7 @@ a#bootstrap
|
||||||
<live-example embedded plnkr="minimal.0" img="devguide/ngmodule/minimal-plunker.png">Try the live example.</live-example>
|
<live-example embedded plnkr="minimal.0" img="devguide/ngmodule/minimal-plunker.png">Try the live example.</live-example>
|
||||||
|
|
||||||
|
|
||||||
### Static bootstrapping with the Ahead-Of-time (AoT) compiler
|
### Static bootstrapping with the Ahead-Of-time (AOT) compiler
|
||||||
|
|
||||||
Consider the static alternative which can produce a much smaller application that
|
Consider the static alternative which can produce a much smaller application that
|
||||||
launches faster, especially on mobile devices and high latency networks.
|
launches faster, especially on mobile devices and high latency networks.
|
||||||
|
@ -167,10 +167,10 @@ a#bootstrap
|
||||||
The application code downloaded to the browser is much smaller than the dynamic equivalent
|
The application code downloaded to the browser is much smaller than the dynamic equivalent
|
||||||
and it is ready to execute immediately. The performance boost can be significant.
|
and it is ready to execute immediately. The performance boost can be significant.
|
||||||
|
|
||||||
Both the JiT and AoT compilers generate an `AppModuleNgFactory` class from the same `AppModule`
|
Both the JIT and AOT compilers generate an `AppModuleNgFactory` class from the same `AppModule`
|
||||||
source code.
|
source code.
|
||||||
The JiT compiler creates that factory class on the fly, in memory, in the browser.
|
The JIT compiler creates that factory class on the fly, in memory, in the browser.
|
||||||
The AoT compiler outputs the factory to a physical file
|
The AOT compiler outputs the factory to a physical file
|
||||||
that we're importing here in the static version of `main.ts`.
|
that we're importing here in the static version of `main.ts`.
|
||||||
|
|
||||||
In general, the `AppModule` should neither know nor care how it is bootstrapped.
|
In general, the `AppModule` should neither know nor care how it is bootstrapped.
|
||||||
|
|
|
@ -113,7 +113,7 @@ table(width="100%")
|
||||||
td <ngio-ex>main.ts</ngio-ex>
|
td <ngio-ex>main.ts</ngio-ex>
|
||||||
td
|
td
|
||||||
:marked
|
:marked
|
||||||
Compiles the application with the [JiT compiler](../glossary.html#jit)
|
Compiles the application with the [JIT compiler](../glossary.html#jit)
|
||||||
and [bootstraps](appmodule.html#main "bootstrap the application") the application to run in the browser.
|
and [bootstraps](appmodule.html#main "bootstrap the application") the application to run in the browser.
|
||||||
That's a reasonable choice for the development of most projects and
|
That's a reasonable choice for the development of most projects and
|
||||||
it's the only viable choice for a sample running in a _live-coding_ environment like Plunker.
|
it's the only viable choice for a sample running in a _live-coding_ environment like Plunker.
|
||||||
|
|
|
@ -40,7 +40,7 @@
|
||||||
h4 Cookbook
|
h4 Cookbook
|
||||||
ul
|
ul
|
||||||
li
|
li
|
||||||
a(href="/docs/#{lang}/#{vers}/cookbook/aot-compiler.html") Ahead-of-Time Compilation
|
a(href="/docs/#{lang}/#{vers}/cookbook/aot-compiler.html") Ahead-of-time Compilation
|
||||||
li
|
li
|
||||||
a(href="/docs/#{lang}/#{vers}/cookbook/a1-a2-quick-reference.html") Angular 1 to Angular 2
|
a(href="/docs/#{lang}/#{vers}/cookbook/a1-a2-quick-reference.html") Angular 1 to Angular 2
|
||||||
li
|
li
|
||||||
|
|
Loading…
Reference in New Issue