Setup AOT/JIT Compilation

The Angular Ahead-of-Time (AOT) compiler converts the Angular HTML and Typescript code in an efficient JavaScript library, that means that the code is processed in the build phase, before the browser downloads and runs the code as the Just-in-Time (JIT) does. The WebMap 5 WebComponents library is compiled to be compatible with AOT/JIT compilation and some configuration is needed, therefore the following setup guideline has been created to show how the library can be configured:

1) Compiling with NGC instead TSC

To change TSC to NGC a new tsconfig file has to be created, the file is tsconfig-aot.json. This file has a different configuration, the rootDir is pointing to /tmp/src-inlined path, the outDir is pointing to dist folder, the section files is pointing to ./tmp/src-inlined/index.ts and the angularCompilerOptions section is new.


It is the root directory where NGC takes the files to compile. In this case the directory is pointing to /tmp/src-inlined that is a temporary path where a copy of source code is created with inline templates (in forward steps we are going to talk about it).


It is the output directory where NGC writes the compiled files. The dist folder is a common naming convention of NPM for distribution version that has been modified to perform better for users.


The files declaration defines which files are going to be included in the compile process. The ./tmp/src-inlined/index.ts is the root file for the entire WinformsComponents library.


This section defines how the NGC compiles the code, the tsconfig-aot.json has different parameters:

Parameter Name





The output generation directory



Production Mode



NGC does not produce .ngfactory and .ngstyle.js files



NGC produces .metadata.json files



Produce an error if the metadata written for a class would produce an error if used



NGC enables the binding expression validation



NGC reports an error for a parameter supplied whose injection type cannot be determined

Note : More documentation about Angular Compiler Options can be found in:

2) Adding compile instruction to package.json

In the package.json file a compilation instruction must be added to change the compilation process to NGC with the tsconfig-aot.json, this instruction goes in the scripts section:

"ngcompile": "node_modules/.bin/ngc -p tsconfig-aot.json",

Then some dependencies have to be added:

"node-sass": "^4.9.0",
"gulp-inline-ng2-template": "^4.1.0",

The first one is used to compile SASS and the second one is to create a copy of the current project with the HTML template of each component inline of its compiled JavaScript, this is important because it going to allow both configurations AOT and JIT.

Then the styles and scripts declarations should be cleaned, so every .css or .js referenced by styles or scripts has to be removed as is shown below:

"styles": [
"scripts": [

Finally at the end of package.json file the definitions for typings and main have to be pointing to dist/index.d.ts and dist/index.js

"typings": "dist/index.d.ts",
"main": "dist/index.js"

3) Gulp tasks configuration

The build task is composed of two compilation process, the AOT/JIT compilation and the usual compilation process and that is why there are two tsconfig.

gulp.task('build', function(done) {
        'clean_dist',     //Clean the dist folder and tmp folder
        'clean_dev',      //Clean the developer compilation
        'build-aot',      //Compile AOT/JIT
        'compile-typings' //Compile developer mode

The AOT/JIT compilation has three processes:

  • Compile SASS to CSS.

function compileSass(path, ext, file, callback) {
    let compiledCss = sass.renderSync({
      file: path,
      outputStyle: 'compressed',
    callback(null, compiledCss.css);
  • Inline external HTML and SCSS templates into Angular component files. Note that the gulp-inline-ng2-template package is referenced using inlineTemplates variable. The inline-templates task takes all Typescript, SASS, HTML inside the src folder and creates a temporal copy inside the ./tmp/src-inlined with all the content of the component together in an Angular component file.

    SRC: './src/**/*.ts',
    DIST: './tmp/src-inlined',
    CONFIG: {
        base: '/src',
        target: 'es6',
        useRelativePaths: true,
        styleProcessor: compileSass
gulp.task('inline-templates', () => {
    return gulp.src(INLINE_TEMPLATES.SRC)
  • Build the dist using NGC. It compiles the ./tmp/src-inlined and outputs the build in dist release folder.

gulp.task('build-aot', ['compile-sass', 'inline-templates'], function(cb) {
    exec('npm run ngcompile', function (err, stdout, stderr) {
        console.log(stdout, stderr);

4) Create the distribution package

Exclude the src and temp folders and the tsconfig.json and tsconfig-aot.json files from .npmignore and include the dist folder.



// @dynamic
export class RemoveAmpersand {
  static remove(value: string): string {
    return value ? value.replace(/&(.|$)/g, '$1') : value;