Configuring the Angular Compiler (ngc)

Why it exists

Browsers don't understand Angular templates, decorators, or dependency injection syntax. The Angular Compiler (ngc) exists to translate this Angular-specific code into plain, efficient JavaScript that the browser can execute directly. This process, known as Ahead-of-Time (AOT) compilation, avoids shipping the entire compiler to the user's browser and performing this work at runtime.

The mental model

Think of ngc as a highly configurable translator. Just as a human translator might choose different words for different audiences, ngc can be configured to produce different kinds of JavaScript output depending on the goal. You are not just compiling TypeScript; you are compiling Angular's abstractions into something universally understood by browsers. Your instructions for this translation live in the angularCompilerOptions section of your tsconfig.json file.

How it works

When you run a build, ngc analyzes your component templates and the metadata in your decorators (like @Component). It then generates TypeScript code that represents your components as factories. This generated code is then compiled along with the rest of your application by the standard TypeScript compiler. Key settings in angularCompilerOptions control this process, such as how decorators are handled (annotationsAs) or the output format (compilationMode).

When to use it

You are always using the Angular Compiler when building an Angular app with the CLI. The key is knowing when to configure it. You should edit angularCompilerOptions when you need to optimize your build for a specific purpose. For example, setting compilationMode to 'partial' is essential when building a library for distribution on npm, as it creates a version-agnostic intermediate format. For a normal application build, the default 'full' mode is correct.

When not to use it

Avoid disabling important safety checks without a very good reason. For instance, setting disableTypeScriptVersionCheck to true is highly discouraged. It silences errors about using an unsupported TypeScript version, which can lead to unpredictable behavior and subtle bugs in your compiled output. Stick to the defaults unless you are solving a specific, well-understood problem like library authoring.

One canonical example

A common scenario is building a shared component library. To ensure it works across different applications that might use slightly different Angular versions, you would configure its tsconfig.json with "compilationMode": "partial". This tells ngc to generate a stable, intermediate code format that the consuming applications' compilers can then finalize, avoiding version mismatches. For a standard application, the default "compilationMode": "full" is used.