diff --git a/adev-es/src/content/reference/configs/angular-compiler-options.en.md b/adev-es/src/content/reference/configs/angular-compiler-options.en.md new file mode 100644 index 0000000..d036086 --- /dev/null +++ b/adev-es/src/content/reference/configs/angular-compiler-options.en.md @@ -0,0 +1,234 @@ +# Angular compiler options + +When you use [ahead-of-time compilation (AOT)](tools/cli/aot-compiler), you can control how your application is compiled by specifying Angular compiler options in the [TypeScript configuration file](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html). + +The Angular options object, `angularCompilerOptions`, is a sibling to the `compilerOptions` object that supplies standard options to the TypeScript compiler. + + + +## Configuration inheritance with `extends` + +Like the TypeScript compiler, the Angular AOT compiler also supports `extends` in the `angularCompilerOptions` section of the TypeScript configuration file. +The `extends` property is at the top level, parallel to `compilerOptions` and `angularCompilerOptions`. + +A TypeScript configuration can inherit settings from another file using the `extends` property. +The configuration options from the base file are loaded first, then overridden by those in the inheriting configuration file. + +For example: + + + +For more information, see the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html). + +## Template options + +The following options are available for configuring the Angular AOT compiler. + +### `annotationsAs` + +Modifies how Angular-specific annotations are emitted to improve tree-shaking. +Non-Angular annotations are not affected. +One of `static fields` or `decorators`. The default value is `static fields`. + +- By default, the compiler replaces decorators with a static field in the class, which allows advanced tree-shakers like [Closure compiler](https://github.com/google/closure-compiler) to remove unused classes +- The `decorators` value leaves the decorators in place, which makes compilation faster. + TypeScript emits calls to the `__decorate` helper. + Use `--emitDecoratorMetadata` for runtime reflection. + + HELPFUL: That the resulting code cannot tree-shake properly. + +### `annotateForClosureCompiler` + + + +When `true`, use [Tsickle](https://github.com/angular/tsickle) to annotate the emitted JavaScript with [JSDoc](https://jsdoc.app) comments needed by the [Closure Compiler](https://github.com/google/closure-compiler). +Default is `false`. + + + +### `compilationMode` + +Specifies the compilation mode to use. +The following modes are available: + +| Modes | Details | +| :---------- | :-------------------------------------------------------------------------------------------------- | +| `'full'` | Generates fully AOT-compiled code according to the version of Angular that is currently being used. | +| `'partial'` | Generates code in a stable, but intermediate form suitable for a published library. | + +The default value is `'full'`. + +For most applications, `'full'` is the correct compilation mode. + +Use `'partial'` for independently published libraries, such as NPM packages. +`'partial'` compilations output a stable, intermediate format which better supports usage by applications built at different Angular versions from the library. +Libraries built at "HEAD" alongside their applications and using the same version of Angular such as in a mono-repository can use `'full'` since there is no risk of version skew. + +### `disableExpressionLowering` + +When `true`, the default, transforms code that is or could be used in an annotation, to allow it to be imported from template factory modules. +See [metadata rewriting](tools/cli/aot-compiler#metadata-rewriting) for more information. + +When `false`, disables this rewriting, requiring the rewriting to be done manually. + +### `disableTypeScriptVersionCheck` + +When `true`, the compiler does not look at the TypeScript version and does not report an error when an unsupported version of TypeScript is used. +Not recommended, as unsupported versions of TypeScript might have undefined behavior. +Default is `false`. + +### `enableI18nLegacyMessageIdFormat` + +Instructs the Angular template compiler to create legacy ids for messages that are tagged in templates by the `i18n` attribute. +See [Mark text for translations][GuideI18nCommonPrepareMarkTextInComponentTemplate] for more information about marking messages for localization. + +Set this option to `false` unless your project relies upon translations that were created earlier using legacy IDs. +Default is `true`. + +The pre-Ivy message extraction tooling created a variety of legacy formats for extracted message IDs. +These message formats have some issues, such as whitespace handling and reliance upon information inside the original HTML of a template. + +The new message format is more resilient to whitespace changes, is the same across all translation file formats, and can be created directly from calls to `$localize`. +This allows `$localize` messages in application code to use the same ID as identical `i18n` messages in component templates. + +### `enableResourceInlining` + +When `true`, replaces the `templateUrl` and `styleUrls` properties in all `@Component` decorators with inline content in the `template` and `styles` properties. + +When enabled, the `.js` output of `ngc` does not include any lazy-loaded template or style URLs. + +For library projects created with the Angular CLI, the development configuration default is `true`. + +### `enableLegacyTemplate` + +When `true`, enables the deprecated `