An Angular application consists mainly of components and their HTML templates. Because the components and templates provided by Angular cannot be understood by the browser directly, Angular applications require a compilation process before they can run in a browser.
\nThe Angular ahead-of-time (AOT) compiler converts your Angular HTML and TypeScript code into efficient JavaScript code during the build phase before the browser downloads and runs that code. Compiling your application during the build process provides a faster rendering in the browser.
\nThis guide explains how to specify metadata and apply available compiler options to compile your applications efficiently using the AOT compiler.
\nWatch Alex Rickabaugh explain the Angular compiler at AngularConnect 2019.
\nHere are some reasons you might want to use AOT.
\nFaster rendering\nWith AOT, the browser downloads a pre-compiled version of the application.\nThe browser loads executable code so it can render the application immediately, without waiting to compile the app first.
\nFewer asynchronous requests\nThe compiler inlines external HTML templates and CSS style sheets within the application JavaScript,\neliminating separate ajax requests for those source files.
\nSmaller Angular framework download size\nThere's no need to download the Angular compiler if the app is already compiled.\nThe compiler is roughly half of Angular itself, so omitting it dramatically reduces the application payload.
\nDetect template errors earlier\nThe AOT compiler detects and reports template binding errors during the build step\nbefore users can see them.
\nBetter security\nAOT compiles HTML templates and components into JavaScript files long before they are served to the client.\nWith no templates to read and no risky client-side HTML or JavaScript evaluation,\nthere are fewer opportunities for injection attacks.
\nAngular offers two ways to compile your application:
\nWhen you run the ng build (build only) or ng serve (build and serve locally) CLI commands, the type of compilation (JIT or AOT) depends on the value of the aot property in your build configuration specified in angular.json. By default, aot is set to true for new CLI apps.
See the CLI command reference and Building and serving Angular apps for more information.
\nThe Angular AOT compiler extracts metadata to interpret the parts of the application that Angular is supposed to manage.\nYou can specify the metadata explicitly in decorators such as @Component() and @Input(), or implicitly in the constructor declarations of the decorated classes.\nThe metadata tells Angular how to construct instances of your application classes and interact with them at runtime.
In the following example, the @Component() metadata object and the class constructor tell Angular how to create and display an instance of TypicalComponent.
The Angular compiler extracts the metadata once and generates a factory for TypicalComponent.\nWhen it needs to create a TypicalComponent instance, Angular calls the factory, which produces a new visual element, bound to a new instance of the component class with its injected dependency.
There are three phases of AOT compilation.
\nPhase 1 is code analysis.\nIn this phase, the TypeScript compiler and AOT collector create a representation of the source. The collector does not attempt to interpret the metadata it collects. It represents the metadata as best it can and records errors when it detects a metadata syntax violation.
\nPhase 2 is code generation.\nIn this phase, the compiler's StaticReflector interprets the metadata collected in phase 1, performs additional validation of the metadata, and throws an error if it detects a metadata restriction violation.
Phase 3 is template type checking.\nIn this optional phase, the Angular template compiler uses the TypeScript compiler to validate the binding expressions in templates. You can enable this phase explicitly by setting the fullTemplateTypeCheck configuration option; see Angular compiler options.
You write metadata in a subset of TypeScript that must conform to the following general constraints:
\nFor additional guidelines and instructions on preparing an application for AOT compilation, see Angular: Writing AOT-friendly applications.
\nErrors in AOT compilation commonly occur because of metadata that does not conform to the compiler's requirements (as described more fully below).\nFor help in understanding and resolving these problems, see AOT Metadata Errors.
\nYou can provide options in the TypeScript configuration file that controls the compilation process. See Angular compiler options for a complete list of available options.
\nThe TypeScript compiler does some of the analytic work of the first phase. It emits the .d.ts type definition files with type information that the AOT compiler needs to generate application code.\nAt the same time, the AOT collector analyzes the metadata recorded in the Angular decorators and outputs metadata information in .metadata.json files, one per .d.ts file.
You can think of .metadata.json as a diagram of the overall structure of a decorator's metadata, represented as an abstract syntax tree (AST).
Angular's schema.ts\ndescribes the JSON format as a collection of TypeScript interfaces.
\nThe AOT collector only understands a subset of JavaScript.\nDefine metadata objects with the following limited syntax:
\n\n| Syntax | \nExample | \n
|---|---|
| Literal object | \n{cherry: true, apple: true, mincemeat: false} | \n
| Literal array | \n['cherries', 'flour', 'sugar'] | \n
| Spread in literal array | \n['apples', 'flour', ...the_rest] | \n
| Calls | \nbake(ingredients) | \n
| New | \nnew Oven() | \n
| Property access | \npie.slice | \n
| Array index | \ningredients[0] | \n
| Identity reference | \nComponent | \n
| A template string | \n`pie is ${multiplier} times better than cake` | \n
| Literal string | \npi | \n
| Literal number | \n3.14153265 | \n
| Literal boolean | \ntrue | \n
| Literal null | \nnull | \n
| Supported prefix operator | \n!cake | \n
| Supported binary operator | \na+b | \n
| Conditional operator | \na ? b : c | \n
| Parentheses | \n(a+b) | \n
If an expression uses unsupported syntax, the collector writes an error node to the .metadata.json file.\nThe compiler later reports the error if it needs that piece of metadata to generate the application code.
If you want ngc to report syntax errors immediately rather than produce a .metadata.json file with errors, set the strictMetadataEmit option in the TypeScript configuration file.
Angular libraries have this option to ensure that all Angular .metadata.json files are clean and it is a best practice to do the same when building your own libraries.
The AOT compiler does not support function expressions\nand arrow functions, also called lambda functions.
\nConsider the following component decorator:
\nThe AOT collector does not support the arrow function, () => new Server(), in a metadata expression.\nIt generates an error node in place of the function.\nWhen the compiler later interprets this node, it reports an error that invites you to turn the arrow function into an exported function.
You can fix the error by converting to this:
\nIn version 5 and later, the compiler automatically performs this rewriting while emitting the .js file.
The compiler can only resolve references to exported symbols.\nThe collector, however, can evaluate an expression during collection and record the result in the .metadata.json, rather than the original expression.\nThis allows you to make limited use of non-exported symbols within expressions.
For example, the collector can evaluate the expression 1 + 2 + 3 + 4 and replace it with the result, 10.\nThis process is called folding. An expression that can be reduced in this manner is foldable.
The collector can evaluate references to module-local const declarations and initialized var and let declarations, effectively removing them from the .metadata.json file.
Consider the following component definition:
\nThe compiler could not refer to the template constant because it isn't exported.\nThe collector, however, can fold the template constant into the metadata definition by in-lining its contents.\nThe effect is the same as if you had written:
There is no longer a reference to template and, therefore, nothing to trouble the compiler when it later interprets the collector's output in .metadata.json.
You can take this example a step further by including the template constant in another expression:
The collector reduces this expression to its equivalent folded string:
\nThe following table describes which expressions the collector can and cannot fold:
\n\n| Syntax | \nFoldable | \n
|---|---|
| Literal object | \nyes | \n
| Literal array | \nyes | \n
| Spread in literal array | \nno | \n
| Calls | \nno | \n
| New | \nno | \n
| Property access | \nyes, if target is foldable | \n
| Array index | \nyes, if target and index are foldable | \n
| Identity reference | \nyes, if it is a reference to a local | \n
| A template with no substitutions | \nyes | \n
| A template with substitutions | \nyes, if the substitutions are foldable | \n
| Literal string | \nyes | \n
| Literal number | \nyes | \n
| Literal boolean | \nyes | \n
| Literal null | \nyes | \n
| Supported prefix operator | \nyes, if operand is foldable | \n
| Supported binary operator | \nyes, if both left and right are foldable | \n
| Conditional operator | \nyes, if condition is foldable | \n
| Parentheses | \nyes, if the expression is foldable | \n
If an expression is not foldable, the collector writes it to .metadata.json as an AST for the compiler to resolve.
The collector makes no attempt to understand the metadata that it collects and outputs to .metadata.json.\nIt represents the metadata as best it can and records errors when it detects a metadata syntax violation.\nIt's the compiler's job to interpret the .metadata.json in the code generation phase.
The compiler understands all syntax forms that the collector supports, but it may reject syntactically correct metadata if the semantics violate compiler rules.
\nThe compiler can only reference exported symbols.
\n@Input() property private or protected.The collector can represent a function call or object creation with new as long as the syntax is valid.\nThe compiler, however, can later refuse to generate a call to a particular function or creation of a particular object.
The compiler can only create instances of certain classes, supports only core decorators, and only supports calls to macros (functions or static methods) that return expressions.
\nNew instances
\n The compiler only allows metadata that create instances of the class InjectionToken from @angular/core.
Supported decorators
\n The compiler only supports metadata for the Angular decorators in the @angular/core module.
Function calls
\nFactory functions must be exported, named functions.\nThe AOT compiler does not support lambda expressions (\"arrow functions\") for factory functions.
\nThe collector accepts any function or static method that contains a single return statement.\nThe compiler, however, only supports macros in the form of functions or static methods that return an expression.
For example, consider the following function:
\nYou can call the wrapInArray in a metadata definition because it returns the value of an expression that conforms to the compiler's restrictive JavaScript subset.
You might use wrapInArray() like this:
The compiler treats this usage as if you had written:
\nThe Angular RouterModule exports two macro static methods, forRoot and forChild, to help declare root and child routes.\nReview the source code\nfor these methods to see how macros can simplify configuration of complex NgModules.
The compiler treats object literals containing the fields useClass, useValue, useFactory, and data specially, converting the expression initializing one of these fields into an exported variable that replaces the expression.\nThis process of rewriting these expressions removes all the restrictions on what can be in them because\nthe compiler doesn't need to know the expression's value—it just needs to be able to generate a reference to the value.
You might write something like:
\nWithout rewriting, this would be invalid because lambdas are not supported and TypicalServer is not exported.\nTo allow this, the compiler automatically rewrites this to something like:
This allows the compiler to generate a reference to ɵ0 in the factory without having to know what the value of ɵ0 contains.
The compiler does the rewriting during the emit of the .js file.\nIt does not, however, rewrite the .d.ts file, so TypeScript doesn't recognize it as being an export. and it does not interfere with the ES module's exported API.
One of the Angular compiler's most helpful features is the ability to type-check expressions within templates, and catch any errors before they cause crashes at runtime.\nIn the template type-checking phase, the Angular template compiler uses the TypeScript compiler to validate the binding expressions in templates.
\nEnable this phase explicitly by adding the compiler option \"fullTemplateTypeCheck\" in the \"angularCompilerOptions\" of the project's TypeScript configuration file\n(see Angular Compiler Options).
In Angular Ivy, the template type checker has been completely rewritten to be more capable as well as stricter, meaning it can catch a variety of new errors that the previous type checker would not detect.
\nAs a result, templates that previously compiled under View Engine can fail type checking under Ivy. This can happen because Ivy's stricter checking catches genuine errors, or because application code is not typed correctly, or because the application uses libraries in which typings are inaccurate or not specific enough.
\nThis stricter type checking is not enabled by default in version 9, but can be enabled by setting the strictTemplates configuration option.\nWe do expect to make strict type checking the default in the future.
For more information about type-checking options, and about improvements to template type checking in version 9 and above, see Template type checking.
\nTemplate validation produces error messages when a type error is detected in a template binding\nexpression, similar to how type errors are reported by the TypeScript compiler against code in a .ts\nfile.
For example, consider the following component:
\nThis produces the following error:
\nThe file name reported in the error message, my.component.ts.MyComponent.html, is a synthetic file\ngenerated by the template compiler that holds contents of the MyComponent class template.\nThe compiler never writes this file to disk.\nThe line and column numbers are relative to the template string in the @Component annotation of the class, MyComponent in this case.\nIf a component uses templateUrl instead of template, the errors are reported in the HTML file referenced by the templateUrl instead of a synthetic file.
The error location is the beginning of the text node that contains the interpolation expression with the error.\nIf the error is in an attribute binding such as [value]=\"person.address.street\", the error\nlocation is the location of the attribute that contains the error.
The validation uses the TypeScript type checker and the options supplied to the TypeScript compiler to control how detailed the type validation is.\nFor example, if the strictTypeChecks is specified, the error\nmy.component.ts.MyComponent.html(1,1): : Object is possibly 'undefined'\nis reported as well as the above error message.
The expression used in an ngIf directive is used to narrow type unions in the Angular\ntemplate compiler, the same way the if expression does in TypeScript.\nFor example, to avoid Object is possibly 'undefined' error in the template above, modify it to only emit the interpolation if the value of person is initialized as shown below:
Using *ngIf allows the TypeScript compiler to infer that the person used in the binding expression will never be undefined.
For more information about input type narrowing, see Input setter coercion and Improving template type checking for custom directives.
\nUse the non-null type assertion operator to suppress the Object is possibly 'undefined' error when it is inconvenient to use *ngIf or when some constraint in the component ensures that the expression is always non-null when the binding expression is interpolated.
In the following example, the person and address properties are always set together, implying that address is always non-null if person is non-null.\nThere is no convenient way to describe this constraint to TypeScript and the template compiler, but the error is suppressed in the example by using address!.street.
The non-null assertion operator should be used sparingly as refactoring of the component might break this constraint.
\nIn this example it is recommended to include the checking of address in the *ngIf as shown below: