mirror of
https://github.com/angular/angular
synced 2026-05-24 09:28:37 +00:00
3598d212a6
This commit covers several changes: - routing enabled by default - standalone by default PR Close #52293
249 lines
13 KiB
Markdown
249 lines
13 KiB
Markdown
# Angular compiler options
|
|
|
|
When you use [ahead-of-time compilation (AOT)](guide/aot-compiler), you can control how your application is compiled by specifying *template* compiler options in the [TypeScript configuration file](guide/typescript-configuration).
|
|
|
|
The template options object, `angularCompilerOptions`, is a sibling to the `compilerOptions` object that supplies standard options to the TypeScript compiler.
|
|
|
|
<code-example header="tsconfig.json" path="angular-compiler-options/tsconfig.json" region="angular-compiler-options"></code-example>
|
|
|
|
<a id="tsconfig-extends"></a>
|
|
|
|
## 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:
|
|
|
|
<code-example header="tsconfig.app.json" path="angular-compiler-options/tsconfig.app.json" region="angular-compiler-options-app"></code-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 AOT template 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.
|
|
|
|
<div class="alert is-helpful">
|
|
|
|
**NOTE**: <br />
|
|
That the resulting code cannot tree-shake properly.
|
|
|
|
</div>
|
|
|
|
### `annotateForClosureCompiler`
|
|
|
|
<!-- vale Angular.Angular_Spelling = NO -->
|
|
|
|
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`.
|
|
|
|
<!-- vale Angular.Angular_Spelling = YES -->
|
|
|
|
### `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'`.
|
|
|
|
### `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](guide/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][AioGuideI18nCommonPrepareMarkTextInComponentTemplate] 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`.
|
|
|
|
<a id="enablelegacytemplate"></a>
|
|
|
|
### `enableLegacyTemplate`
|
|
|
|
When `true`, enables the deprecated `<template>` element in place of `<ng-template>`.
|
|
Default is `false`.
|
|
Might be required by some third-party Angular libraries.
|
|
|
|
### `flatModuleId`
|
|
|
|
The module ID to use for importing a flat module \(when `flatModuleOutFile` is `true`\).
|
|
References created by the template compiler use this module name when importing symbols from the flat module.
|
|
Ignored if `flatModuleOutFile` is `false`.
|
|
|
|
### `flatModuleOutFile`
|
|
|
|
When `true`, generates a flat module index of the given filename and the corresponding flat module metadata.
|
|
Use to create flat modules that are packaged similarly to `@angular/core` and `@angular/common`.
|
|
When this option is used, the `package.json` for the library should refer to the created flat module index instead of the library index file.
|
|
|
|
Produces only one `.metadata.json` file, which contains all the metadata necessary for symbols exported from the library index.
|
|
In the created `.ngfactory.js` files, the flat module index is used to import symbols. Symbols that include both the public API from the library index and shrouded internal symbols.
|
|
|
|
By default, the `.ts` file supplied in the `files` field is assumed to be the library index.
|
|
If more than one `.ts` file is specified, `libraryIndex` is used to select the file to use.
|
|
If more than one `.ts` file is supplied without a `libraryIndex`, an error is produced.
|
|
|
|
A flat module index `.d.ts` and `.js` is created with the given `flatModuleOutFile` name in the same location as the library index `.d.ts` file.
|
|
|
|
For example, if a library uses the `public_api.ts` file as the library index of the module, the `tsconfig.json` `files` field would be `["public_api.ts"]`.
|
|
The `flatModuleOutFile` option could then be set, for example, to `"index.js"`, which produces `index.d.ts` and `index.metadata.json` files.
|
|
The `module` field of the library's `package.json` would be `"index.js"` and the `typings` field would be `"index.d.ts"`.
|
|
|
|
### `fullTemplateTypeCheck`
|
|
|
|
When `true`, the recommended value, enables the [binding expression validation](guide/aot-compiler#binding-expression-validation) phase of the template compiler. This phase uses TypeScript to verify binding expressions.
|
|
For more information, see [Template type checking](guide/template-typecheck).
|
|
|
|
Default is `false`, but set to `true` in the created workspace configuration when creating a project using the Angular CLI.
|
|
|
|
<div class="alert is-important">
|
|
|
|
The `fullTemplateTypeCheck` option has been deprecated in Angular 13 in favor of the `strictTemplates` family of compiler options.
|
|
|
|
</div>
|
|
|
|
### `generateCodeForLibraries`
|
|
|
|
When `true`, creates factory files \(`.ngfactory.js` and `.ngstyle.js`\) for `.d.ts` files with a corresponding `.metadata.json` file. The default value is `true`.
|
|
|
|
When `false`, factory files are created only for `.ts` files.
|
|
Do this when using factory summaries.
|
|
|
|
### `preserveWhitespaces`
|
|
|
|
When `false`, the default, removes blank text nodes from compiled templates, which results in smaller emitted template factory modules.
|
|
Set to `true` to preserve blank text nodes.
|
|
|
|
<div class="alert is-helpful">
|
|
|
|
When using hydration, it is recommended that you use `preserveWhitespaces: false`, which is the default value. If you choose to enable preserving whitespaces by adding `preserveWhitespaces: true` to your tsconfig, it is possible you may encounter issues with hydration. This is not yet a fully supported configuration. Ensure this is also consistently set between the server and client tsconfig files. See the [hydration guide](guide/hydration#preserve-whitespaces) for more details.
|
|
|
|
</div>
|
|
|
|
### `skipMetadataEmit`
|
|
|
|
When `true`, does not produce `.metadata.json` files.
|
|
Default is `false`.
|
|
|
|
The `.metadata.json` files contain information needed by the template compiler from a `.ts` file that is not included in the `.d.ts` file produced by the TypeScript compiler.
|
|
This information includes, for example, the content of annotations, such as a component's template, which TypeScript emits to the `.js` file but not to the `.d.ts` file.
|
|
|
|
You can set to `true` when using factory summaries, because the factory summaries include a copy of the information that is in the `.metadata.json` file.
|
|
|
|
Set to `true` if you are using TypeScript's `--outFile` option, because the metadata files are not valid for this style of TypeScript output.
|
|
The Angular community does not recommend using `--outFile` with Angular.
|
|
Use a bundler, such as [webpack](https://webpack.js.org), instead.
|
|
|
|
### `skipTemplateCodegen`
|
|
|
|
When `true`, does not emit `.ngfactory.js` and `.ngstyle.js` files.
|
|
This turns off most of the template compiler and disables the reporting of template diagnostics.
|
|
|
|
Can be used to instruct the template compiler to produce `.metadata.json` files for distribution with an `npm` package. This avoids the production of `.ngfactory.js` and `.ngstyle.js` files that cannot be distributed to `npm`.
|
|
|
|
For library projects created with the Angular CLI, the development configuration default is `true`.
|
|
|
|
### `strictMetadataEmit`
|
|
|
|
When `true`, reports an error to the `.metadata.json` file if `"skipMetadataEmit"` is `false`.
|
|
Default is `false`.
|
|
Use only when `"skipMetadataEmit"` is `false` and `"skipTemplateCodegen"` is `true`.
|
|
|
|
This option is intended to verify the `.metadata.json` files emitted for bundling with an `npm` package.
|
|
The validation is strict and can emit errors for metadata that would never produce an error when used by the template compiler.
|
|
You can choose to suppress the error emitted by this option for an exported symbol by including `@dynamic` in the comment documenting the symbol.
|
|
|
|
It is valid for `.metadata.json` files to contain errors.
|
|
The template compiler reports these errors if the metadata is used to determine the contents of an annotation.
|
|
The metadata collector cannot predict the symbols that are designed for use in an annotation. It preemptively includes error nodes in the metadata for the exported symbols.
|
|
The template compiler can then use the error nodes to report an error if these symbols are used.
|
|
|
|
If the client of a library intends to use a symbol in an annotation, the template compiler does not normally report this. It gets reported after the client actually uses the symbol.
|
|
This option allows detection of these errors during the build phase of the library and is used, for example, in producing Angular libraries themselves.
|
|
|
|
For library projects created with the Angular CLI, the development configuration default is `true`.
|
|
|
|
### `strictInjectionParameters`
|
|
|
|
When `true`, reports an error for a supplied parameter whose injection type cannot be determined.
|
|
When `false`, constructor parameters of classes marked with `@Injectable` whose type cannot be resolved produce a warning.
|
|
The recommended value is `true`, but the default value is `false`.
|
|
|
|
Set to `true` in the created workspace configuration when creating a project using the Angular CLI.
|
|
|
|
### `strictTemplates`
|
|
|
|
When `true`, enables [strict template type checking](guide/template-typecheck#strict-mode).
|
|
|
|
The strictness flags that this option enables allow you to turn on and off specific types of strict template type checking.
|
|
See [troubleshooting template errors](guide/template-typecheck#troubleshooting-template-errors).
|
|
|
|
Set to `true` in the created workspace configuration when creating a project using the Angular CLI.
|
|
|
|
### `trace`
|
|
|
|
When `true`, prints extra information while compiling templates.
|
|
Default is `false`.
|
|
|
|
<a id="cli-options"></a>
|
|
|
|
## Command line options
|
|
|
|
Most of the time you interact with the Angular Compiler indirectly using Angular CLI. When debugging certain issues, you might find it useful to invoke the Angular Compiler directly.
|
|
You can use the `ngc` command provided by the `@angular/compiler-cli` npm package to call the compiler from the command line.
|
|
|
|
The `ngc` command is just a wrapper around TypeScript's `tsc` compiler command and is primarily configured via the `tsconfig.json` configuration options documented in [the previous sections](#angular-compiler-options).
|
|
|
|
Besides the configuration file, you can also use [`tsc` command line options](https://www.typescriptlang.org/docs/handbook/compiler-options.html) to configure `ngc`.
|
|
|
|
<!-- links -->
|
|
|
|
[AioGuideI18nCommonPrepareMarkTextInComponentTemplate]: guide/i18n-common-prepare#mark-text-in-component-template "Mark text in component template - Prepare component for translation | Angular"
|
|
|
|
<!-- end links -->
|
|
|
|
@reviewed 2023-10-24
|