# 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:

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

Then some dependencies have to be added:

```javascript
"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:

```javascript
"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*

```javascript
"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.

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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:

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gapvelocity.ai/webmap/general/frontend/documentation/winforms-angular-components/setup/setup-aot-jit-compilation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.