s

thelgevold · thelgevold · commit a92330e4bf88 · 2016-10-04T00:52:47.000-04:00
s

s

s
diff --git a/public/docs/_examples/package.json b/public/docs/_examples/package.json
@@ -39,7 +39,6 @@
     "@angular/platform-server": "~2.0.1",
     "@angular/router": "~3.0.1",
     "@angular/upgrade": "~2.0.1",
-
     "angular-in-memory-web-api": "~0.1.3",
     "bootstrap": "^3.3.7",
     "core-js": "^2.4.1",
@@ -81,6 +80,7 @@
     "raw-loader": "^0.5.1",
     "rimraf": "^2.5.4",
     "rollup-plugin-commonjs": "^4.1.0",
+    "source-map-explorer": "^1.3.2",
     "style-loader": "^0.13.1",
     "ts-loader": "^0.8.2",
     "ts-node": "^1.3.0",
diff --git a/public/docs/_examples/toh-6-aot/ts/dist/build.js.gz b/public/docs/_examples/toh-6-aot/ts/dist/build.js.gz
diff --git a/public/docs/_examples/toh-6-aot/ts/index.html b/public/docs/_examples/toh-6-aot/ts/index.html
@@ -1,3 +1,4 @@
+<!-- #docregion -->
 <!DOCTYPE html>
 <html>
   <head>
@@ -10,10 +11,12 @@
     <script src="node_modules/core-js/client/shim.min.js"></script>
 
     <script src="node_modules/zone.js/dist/zone.js"></script>
- 
+    
+    <!-- #docregion moduleId -->
     <script>
         window.module = 'aot';
     </script>
+    <!-- #enddocregion moduleId -->
   </head>
 
   <body>
diff --git a/public/docs/_examples/toh-6/ts/index.html b/public/docs/_examples/toh-6/ts/index.html
@@ -1,3 +1,4 @@
+<!-- #docregion -->
 <!DOCTYPE html>
 <html>
   <head>
diff --git a/public/docs/ts/latest/cookbook/aot-compiler.jade b/public/docs/ts/latest/cookbook/aot-compiler.jade
@@ -15,6 +15,7 @@ a#toc
   * [Load the bundle](#load)
   * [Serve the app](#serve)
   * [Source Code](#source-code)
+  * [Tour of Heroes](#toh)
 
 a#overview
 .l-main-section
@@ -285,7 +286,7 @@ a#source-code
 :marked
   ## Source Code
 
-  Here is the pertinent AoT source code for this cookbook:
+  Here is the pertinent AoT source code for this cookbook so far:
 +makeTabs(
   `cb-aot-compiler/ts/app/app.component.html,
    cb-aot-compiler/ts/app/app.component.ts,
@@ -301,3 +302,130 @@ a#source-code
    tsconfig-aot.json,
    rollup.js`
 )
+
+a#toh
+.l-main-section
+:marked
+  ## Tour of Heroes
+
+  Our sample application has so far been trivial. In this section we want to apply what we have learned to a more realistic application.
+
+  We will show how to apply AoT compilation and Tree Shaking to our <a href="/docs/ts/latest/tutorial/toh-pt6.html">Tour of Heroes</a> application.
+
+  ### JiT vs AoT
+
+  We recommend using AoT in production, but the added compilation time in combination with Tree Shaking might make it impractical to do AoT during development.
+
+  Instead we have opted to do JiT compilation in our development environment and AoT compilation when deploying to production.
+
+  Our source code is for the most part agnostic of how we compile the application, but there are a few differences to keep in mind.
+
+  *Index.html*
+
+  The initial loading is different between JiT and AoT applications. In our case we have decided to use two different index.html files. 
+
+  Our JiT version relies on `SystemJS` for loading of individual modules, but our AoT version loads the entire application as a single script tag without a dependency on `SystemJS`. This means we can remove the `SystemJS` script tag when doing AoT. It turns out we can also remove the dependency on `reflect-metadata`.  
+
+  We have included the two index.html files below:
+
++makeTabs(
+  `toh-6/ts/index.html,
+   toh-6-aot/ts/index.html`,
+  null,
+  `index.html (JiT),
+   index.html (AoT)`
+)
+
+:marked
+  *External file paths*
+
+  The AoT compiler assumes component-relative paths when locating external templates and css files. This differs from JiT where the path is specified as either an absolute path from the application root, or a component-relative path in tandem with a `module.id`.  
+
+  To make our components compatible with both AoT and JiT we have added `module.id` and component-relative paths to all our components.
+
+  The AoT compiler will ignore `module.id` during compilation, but there is one caveat. `module.id` is included in the final JavaScript, but in the case of AoT, `module` will not be defined at runtime. This means we will get a runtime error when trying to access `id` on the undefined `module` object. 
+
+  The solution is simple. Since `module.id` has no meaning in an AoT application we can work around this by assigning `window.module` an arbitrary value at runtime.
+
+  The assigned value can be anything. The important part is to define `window.module` to avoid failure when `module.id` is referenced.
+
++makeExample('toh-6-aot/ts/index.html','moduleId','index.html (module.id)')(format='.')  
+
+:marked
+  Manually setting `module` to an arbitrary value may seem a bit hacky, but we expect this to be a temporary workaround. 
+
+:marked
+  *TypeScript configuration*
+
+  To prepare our code for Tree Shaking our AoT compiled application is targeting `ES2015` modules. This is not ideal for our JiT configuration since most browsers can't execute `ES2015` directly.
+
+  In order to output regular `ES5` JavaScript for out JiT setup, we have created a second `tsconfig.json` file.
+
+  The two TypeScript configuration files can be seen below:
+
++makeTabs(
+  `toh-6/ts/tsconfig.json,
+   toh-6/ts/tsconfig-aot.json`,
+  null,
+  `tsconfig.json (JiT),
+   tsconfig-aot.json (AoT)`
+)   
+
+:marked
+  ### External AoT Libraries
+
+  Tour of Heroes has an external dependency on the `angular-in-memory-web-api` library.
+
+  We can't expect all libraries to be released with AoT in mind, but `angular-in-memory-web-api` has already been AoT compiled and released with the necessary dependencies to integrate it with another AoT compiled application.
+
+  The key to releasing an AoT compatible version of a library is including the `.metadata.json` files generated by the AoT compiler. 
+  
+  The metadata files, the JavaScript source and .d.ts typings files are enough to integrate the AoT build of `angular-in-memory-web-api` with our AoT compiled version of Tour of Heroes.
+
+  It may seem surprising to some that we're not integrating with the TypeScript source from `angular-in-memory-web-api` when doing AoT. 
+  
+  Releasing TypeScript with external libraries is unnecessary, but also discouraged since it forces the consumer to recreate the compilation environment with typings and everything needed to compile the third party library.
+
+  ### Tree Shaking
+
+  Again we are using Rollup to do the Tree Shaking.
+
+  The Rollup configuration has not changed much from our previous example, but we have included `angular-in-memory-web-api` when calling the commonjs plugin. This is because `angular-in-memory-web-api` is released as `commonjs` and has to be converted to `ES2015` before Tree Shaking.
+
++makeExample('toh-6/ts/rollup.js',null,'rollup.js')(format='.')  
+
+:marked
+  ### Running the application
+
+  The JiT build can be run just like all our other JiT examples by running `npm start`.
+
+  To launch the AoT compiled version we execute the following command from the `toh-6-aot/ts` folder:
+
+  `npm run build:toh-aot && npm run lite`
+
+:marked
+  ### Inspect the Bundle
+
+  Now that we have a more substantial application it might be interesting to take a closer look at the generated JavaScript bundle. The code is minified, so we won't learn much from looking at the source code though.
+
+  Instead we use a handy tool called `source-map-explorer`. We install `source-map-explorer` by running `npm install source-map-explorer --save-dev`.
+
+  `source-map-explorer` uses this source map, generated with our bundle, to analyse and draw a map of all our dependencies.
+
+  We have include the map below. 
+
+figure.image-display
+   img(src="/resources/images/cookbooks/aot-compiler/toh6-bundle.png" alt="TOH-6-bundle")   
+
+:marked
+  From looking at the map we can know exactly which modules were included in our bundle. This includes everything from our application code to Angular framework code.
+
+  To generate the map we run the following command from the `toh-6-aot/ts` folder.
+
+  `node_modules/.bin/source-map-explorer dist/build.js`
+
+
+
+
+
+
diff --git a/public/resources/images/cookbooks/aot-compiler/toh6-bundle.png b/public/resources/images/cookbooks/aot-compiler/toh6-bundle.png

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+<!-- #docregion -->`
`1`	`2`	`<!DOCTYPE html>`
`2`	`3`	`<html>`
`3`	`4`	`<head>`