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.

rootDir

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).

outDir

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.

files

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.

angularCompilerOptions

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

Parameter Name	Value	Description
genDir	"dist"	The output generation directory
debug	false	Production Mode
skipTemplateCodegen	true	NGC does not produce .ngfactory and .ngstyle.js files
skipMetadataEmit	false	NGC produces .metadata.json files
strictMetadataEmit	true	Produce an error if the metadata written for a class would produce an error if used
fullTemplateTypeCheck	true	NGC enables the binding expression validation
strictInjectionParameters	true	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: https://angular.io/guide/aot-compiler#angular-compiler-options

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) {
    runSequence(
        '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.

const INLINE_TEMPLATES = {
    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)
        .pipe(inlineTemplates(INLINE_TEMPLATES.CONFIG))
        .pipe(gulp.dest(INLINE_TEMPLATES.DIST));
});

• 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);
        cb(err);
    });
});

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.

src
temp
!dist
tsconfig.json
tsconfig-aot.json

Notes

• In the AOT/JIT compilation process errors does not visible in the TSC compilation process could appear. A good guide to resolve AOT/JIT errors can be found here: https://blog.angularindepth.com/making-your-angular-2-library-statically-analyzable-for-aot-e1c6f3ebedd5

• The index.ts file must be located inside the src folder.

• The strictMetadataEmit could produces errors with the static classes, @dynamic instruction can helps in these cases, write the instruction above of the class definition:

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