From 66ab5735c0a05d40d5eefe211ba01caa48de1775 Mon Sep 17 00:00:00 2001 From: Georgios Tzourmpakis Date: Fri, 11 Nov 2016 22:30:21 +0200 Subject: [PATCH 1/2] docs(cookbook-aot-compiler): improve Ahead-of-Time compilation cookbook Add additions/clarification: * Add `main-aot.ts` and `main.ts` comparison in the key differences. * Add a sub note below `tsconfig-aot.json` and `tsconfig.json` comparison to highlight and explain the usage of `../../node_modules/@types/` instead of `node_modules/@types/`. --- .../docs/ts/latest/cookbook/aot-compiler.jade | 29 ++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/public/docs/ts/latest/cookbook/aot-compiler.jade b/public/docs/ts/latest/cookbook/aot-compiler.jade index dbf6c1c7b9..9c8e40994a 100644 --- a/public/docs/ts/latest/cookbook/aot-compiler.jade +++ b/public/docs/ts/latest/cookbook/aot-compiler.jade @@ -341,7 +341,7 @@ a#toh 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 are setup and launched so differently that they require their own `index.html` files. Here they are for comparison: @@ -363,6 +363,26 @@ a#toh 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` + + ***main.ts*** + + The JiT and AoT apps are also bootstraped differently that they require their own `main.ts` files. + Here they are for comparison: + ++makeTabs( + `toh-6/ts/app/main-aot.ts, + toh-6/ts/app/main.ts`, + null, + `app/main-aot.ts (AoT), + app/main.ts (JiT)` +) + +:marked + They can and should exist in the same folder. + + The `app/main-aot.ts` file is used by the AoT config scripts (`tsconfig-aot.json` and `rollup-config.js`). + + Key differences are discussed in the [Bootstrap](#bootstrap) section, above. *Component-relative Template URLS* @@ -396,6 +416,13 @@ a#toh tsconfig.json (JiT)` ) +.l-sub-section + :marked + _Note_ that the specific file structure of this project needs `typeRoots` to include `../../node_modules/@types/`, + whereas in a typical setting it should include `node_modules/@types/` instead. + + Make sure to edit accordingly to your project needs. + :marked ### Tree Shaking From bb4ee3313cd9247f4089b09d6ad12e60e819c22a Mon Sep 17 00:00:00 2001 From: Ward Bell Date: Mon, 14 Nov 2016 09:59:54 -0800 Subject: [PATCH 2/2] docs(cookbook-aot-compiler): ward's tweaks to #2790 --- public/docs/_examples/toh-6/ts/app/main.ts | 2 +- .../docs/ts/latest/cookbook/aot-compiler.jade | 46 +++++++++---------- 2 files changed, 23 insertions(+), 25 deletions(-) diff --git a/public/docs/_examples/toh-6/ts/app/main.ts b/public/docs/_examples/toh-6/ts/app/main.ts index 091a7d82a7..961a226688 100644 --- a/public/docs/_examples/toh-6/ts/app/main.ts +++ b/public/docs/_examples/toh-6/ts/app/main.ts @@ -1,6 +1,6 @@ // #docregion -// main entry point import { platformBrowserDynamic } from '@angular/platform-browser-dynamic'; + import { AppModule } from './app.module'; platformBrowserDynamic().bootstrapModule(AppModule); diff --git a/public/docs/ts/latest/cookbook/aot-compiler.jade b/public/docs/ts/latest/cookbook/aot-compiler.jade index 9c8e40994a..e59218f4fc 100644 --- a/public/docs/ts/latest/cookbook/aot-compiler.jade +++ b/public/docs/ts/latest/cookbook/aot-compiler.jade @@ -343,7 +343,9 @@ a#toh ***index.html*** - The JiT and AoT apps are setup and launched so differently that they require their own `index.html` files. + 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. + Here they are for comparison: +makeTabs( @@ -355,9 +357,6 @@ a#toh ) :marked - They can't be in the same folder. - ***Put the AoT version in the `/aot` folder***. - The JiT version relies on `SystemJS` to load individual modules and requires the `reflect-metadata` shim. Both scripts appear in its `index.html`. @@ -366,8 +365,9 @@ a#toh ***main.ts*** - The JiT and AoT apps are also bootstraped differently that they require their own `main.ts` files. - Here they are for comparison: + 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, + are evident in these `main` files which can and should reside in the same folder: +makeTabs( `toh-6/ts/app/main-aot.ts, @@ -378,32 +378,26 @@ a#toh ) :marked - They can and should exist in the same folder. - - The `app/main-aot.ts` file is used by the AoT config scripts (`tsconfig-aot.json` and `rollup-config.js`). - - Key differences are discussed in the [Bootstrap](#bootstrap) section, above. - - *Component-relative Template URLS* + ***Component-relative Template URLS*** 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: - `foo.component.html` no matter where `foo.component.ts` sits in the project folder structure. + That means that the value of `@Component.templateUrl` is a URL value _relative_ to the component class file. + For example, a `'hero.component.html'` URL means that the template file is a sibling of its companion `hero.component.ts` file. While JiT app URLs are more flexible, stick with _component-relative_ URLs for compatibility with AoT compilation. - JiT-compiled apps, using 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 app fails 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('toh-6/ts/aot/index.html','moduleId')(format='.') .l-sub-section :marked Setting a global `module` is a temporary expedient. :marked - *TypeScript configuration* + ***TypeScript configuration*** - JiT-compiled apps transpile to `commonjs` modules. - AoT-compiled apps transpile to _ES2015_/_ES6_ modules to facilitate Tree Shaking. + JiT-compiled applications transpile to `commonjs` modules. + AoT-compiled applications transpile to _ES2015_/_ES6_ modules to facilitate Tree Shaking. AoT requires its own TypeScript configuration settings as well. You'll need separate TypeScript configuration files such as these: @@ -416,12 +410,16 @@ a#toh tsconfig.json (JiT)` ) -.l-sub-section +.callout.is-helpful + header @Types and node modules :marked - _Note_ that the specific file structure of this project needs `typeRoots` to include `../../node_modules/@types/`, - whereas in a typical setting it should include `node_modules/@types/` instead. + In the file structure of _this particular sample project_, + the `node_modules` folder happens to be two levels up from the project root. + Therefore, `"typeRoots"` must be set to `"../../node_modules/@types/"`. - Make sure to edit accordingly to your project needs. + In a more typical project, `node_modules` would be a sibling of `tsconfig-aot.json` + and `"typeRoots"` would be set to `"node_modules/@types/"`. + Edit your `tsconfig-aot.json` to fit your project's file structure. :marked ### Tree Shaking