5 lines
22 KiB
JSON
5 lines
22 KiB
JSON
{
|
|
"id": "guide/angular-compiler-options",
|
|
"title": "Angular compiler options",
|
|
"contents": "\n\n\n<div class=\"github-links\">\n <a href=\"https://github.com/angular/angular/edit/master/aio/content/guide/angular-compiler-options.md?message=docs%3A%20describe%20your%20change...\" aria-label=\"Suggest Edits\" title=\"Suggest Edits\"><i class=\"material-icons\" aria-hidden=\"true\" role=\"img\">mode_edit</i></a>\n</div>\n\n\n<div class=\"content\">\n <h1 id=\"angular-compiler-options\">Angular compiler options<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#angular-compiler-options\"><i class=\"material-icons\">link</i></a></h1>\n<p>When you use <a href=\"guide/aot-compiler\">AOT compilation</a>, you can control how your application is compiled by specifying <em>template</em> compiler options in the <a href=\"guide/typescript-configuration\">TypeScript configuration file</a>.</p>\n<p>The template options object, <code>angularCompilerOptions</code>, is a sibling to the <code>compilerOptions</code> object that supplies standard options to the TypeScript compiler.</p>\n<code-example language=\"json\">\n {\n \"compilerOptions\": {\n \"experimentalDecorators\": true,\n ...\n },\n \"angularCompilerOptions\": {\n \"fullTemplateTypeCheck\": true,\n \"preserveWhitespaces\": true,\n ...\n }\n }\n</code-example>\n<a id=\"tsconfig-extends\"></a>\n<h2 id=\"configuration-inheritance-with-extends\">Configuration inheritance with extends<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#configuration-inheritance-with-extends\"><i class=\"material-icons\">link</i></a></h2>\n<p>Like the TypeScript compiler, The Angular AOT compiler also supports <code>extends</code> in the <code>angularCompilerOptions</code> section of the TypeScript configuration file.\nThe <code>extends</code> property is at the top level, parallel to <code>compilerOptions</code> and <code>angularCompilerOptions</code>.</p>\n<p>A TypeScript configuration can inherit settings from another file using the <code>extends</code> property.\nThe configuration options from the base file are loaded first, then overridden by those in the inheriting configuration file.</p>\n<p>For example:</p>\n<code-example language=\"json\">\n{\n \"extends\": \"../tsconfig.json\",\n \"compilerOptions\": {\n \"experimentalDecorators\": true,\n ...\n },\n \"angularCompilerOptions\": {\n \"fullTemplateTypeCheck\": true,\n \"preserveWhitespaces\": true,\n ...\n }\n}\n</code-example>\n<p>For more information, see the <a href=\"https://www.typescriptlang.org/docs/handbook/tsconfig-json.html\">TypeScript Handbook</a>.</p>\n<h2 id=\"template-options\">Template options<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#template-options\"><i class=\"material-icons\">link</i></a></h2>\n<p>The following options are available for configuring the AOT template compiler.</p>\n<h3 id=\"allowemptycodegenfiles\"><code>allowEmptyCodegenFiles</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#allowemptycodegenfiles\"><i class=\"material-icons\">link</i></a></h3>\n<p>When <code>true</code>, generate all possible files even if they are empty. Default is <code>false</code>. Used by the Bazel build rules to simplify how Bazel rules track file dependencies. Do not use this option outside of the Bazel rules.</p>\n<h3 id=\"annotationsas\"><code>annotationsAs</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#annotationsas\"><i class=\"material-icons\">link</i></a></h3>\n<p>Modifies how Angular-specific annotations are emitted to improve tree-shaking. Non-Angular annotations are not affected. One of <code><a href=\"api/upgrade/static\" class=\"code-anchor\">static</a> fields</code> (the default) or <code>decorators</code>.</p>\n<ul>\n<li>\n<p>By default, the compiler replaces decorators with a static field in the class, which allows advanced tree-shakers like <a href=\"https://github.com/google/closure-compiler\">Closure compiler</a> to remove unused classes.</p>\n</li>\n<li>\n<p>The <code>decorators</code> value leaves the decorators in place, which makes compilation faster. TypeScript emits calls to the<code>__decorate</code> helper. Use <code>--emitDecoratorMetadata</code> for runtime reflection (but note that the resulting code will not properly tree-shake.</p>\n</li>\n</ul>\n<h3 id=\"annotateforclosurecompiler\"><code>annotateForClosureCompiler</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#annotateforclosurecompiler\"><i class=\"material-icons\">link</i></a></h3>\n<p>When <code>true</code>, use <a href=\"https://github.com/angular/tsickle\">Tsickle</a> to annotate the emitted JavaScript with <a href=\"https://jsdoc.app/\">JSDoc</a> comments needed by the\n<a href=\"https://github.com/google/closure-compiler\">Closure Compiler</a>. Default is <code>false</code>.</p>\n<h3 id=\"disableexpressionlowering\"><code>disableExpressionLowering</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#disableexpressionlowering\"><i class=\"material-icons\">link</i></a></h3>\n<p>When <code>true</code> (the default), transforms code that is or could be used in an annotation, to allow it to be imported from template factory modules. See <a href=\"guide/aot-compiler#metadata-rewriting\">metadata rewriting</a> for more information.</p>\n<p>When <code>false</code>, disables this rewriting, requiring the rewriting to be done manually.</p>\n<h3 id=\"disabletypescriptversioncheck\"><code>disableTypeScriptVersionCheck</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#disabletypescriptversioncheck\"><i class=\"material-icons\">link</i></a></h3>\n<p>When <code>true</code>, the compiler does not check 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 <code>false</code>.</p>\n<h3 id=\"enablei18nlegacymessageidformat\"><code>enableI18nLegacyMessageIdFormat</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#enablei18nlegacymessageidformat\"><i class=\"material-icons\">link</i></a></h3>\n<p>Instructs the Angular template compiler to generate legacy ids for messages that are tagged in templates by the <code>i18n</code> attribute.\nSee <a href=\"guide/i18n#mark-text-for-translations\">Localizing your app</a> for more information about marking messages for localization.</p>\n<p>Set this option to <code>false</code> unless your project relies upon translations that were previously generated using legacy ids. Default is <code>true</code>.</p>\n<p>The pre-Ivy message extraction tooling generated a variety of legacy formats for extracted message ids.\nThese message formats have a number of issues, such as whitespace handling and reliance upon information inside the original HTML of a template.</p>\n<p>The new message format is more resilient to whitespace changes, is the same across all translation file formats, and can be generated directly from calls to <code><a href=\"api/localize/init/$localize\" class=\"code-anchor\">$localize</a></code>.\nThis allows <code><a href=\"api/localize/init/$localize\" class=\"code-anchor\">$localize</a></code> messages in application code to use the same id as identical <code>i18n</code> messages in component templates.</p>\n<h3 id=\"enableivy\"><code>enableIvy</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#enableivy\"><i class=\"material-icons\">link</i></a></h3>\n<p>Enables the <a href=\"guide/ivy\">Ivy</a> compilation and rendering pipeline. Default is <code>true</code>, as of version 9. In version 9, you can <a href=\"guide/ivy#opting-out-of-angular-ivy\">opt out of Ivy</a> to continue using the previous compiler, View Engine.</p>\n<p>For library projects generated with the CLI, the <code>prod</code> configuration default is <code>false</code> in version 9.</p>\n<h3 id=\"enableresourceinlining\"><code>enableResourceInlining</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#enableresourceinlining\"><i class=\"material-icons\">link</i></a></h3>\n<p>When <code>true</code>, replaces the <code>templateUrl</code> and <code>styleUrls</code> property in all <code>@<a href=\"api/core/Component\" class=\"code-anchor\">Component</a></code> decorators with inlined contents in <code>template</code> and <code>styles</code> properties.</p>\n<p>When enabled, the <code>.js</code> output of <code>ngc</code> does not include any lazy-loaded template or style URLs.</p>\n<p>For library projects generated with the CLI, the dev configuration default is <code>true</code>.</p>\n<a id=\"enablelegacytemplate\"></a>\n<h3 id=\"enablelegacytemplate\"><code>enableLegacyTemplate</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#enablelegacytemplate\"><i class=\"material-icons\">link</i></a></h3>\n<p>When <code>true</code>, enables use of the <code><template></code> element, which was deprecated in Angular 4.0, in favor of <code><ng-template></code> (to avoid colliding with the DOM's element of the same name). Default is <code>false</code>. Might be required by some third-party Angular libraries.</p>\n<h3 id=\"flatmoduleid\"><code>flatModuleId</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#flatmoduleid\"><i class=\"material-icons\">link</i></a></h3>\n<p>The module ID to use for importing a flat module (when <code>flatModuleOutFile</code> is <code>true</code>). References generated by the template compiler use this module name when importing symbols\nfrom the flat module. Ignored if <code>flatModuleOutFile</code> is <code>false</code>.</p>\n<h3 id=\"flatmoduleoutfile\"><code>flatModuleOutFile</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#flatmoduleoutfile\"><i class=\"material-icons\">link</i></a></h3>\n<p>When <code>true</code>, generates a flat module index of the given file name and the corresponding flat module metadata. Use to create flat modules that are packaged similarly to <code>@angular/core</code> and <code>@angular/common</code>. When this option is used, the <code>package.json</code> for the library should refer\nto the generated flat module index instead of the library index file.</p>\n<p>Produces only one <code>.metadata.json</code> file, which contains all the metadata necessary\nfor symbols exported from the library index. In the generated <code>.ngfactory.js</code> files, the flat\nmodule index is used to import symbols that include both the public API from the library index\nas well as shrowded internal symbols.</p>\n<p>By default the <code>.ts</code> file supplied in the <code>files</code> field is assumed to be the library index.\nIf more than one <code>.ts</code> file is specified, <code>libraryIndex</code> is used to select the file to use.\nIf more than one <code>.ts</code> file is supplied without a <code>libraryIndex</code>, an error is produced.</p>\n<p>A flat module index <code>.d.ts</code> and <code>.js</code> is created with the given <code>flatModuleOutFile</code> name in the same location as the library index <code>.d.ts</code> file.</p>\n<p>For example, if a library uses the <code>public_api.ts</code> file as the library index of the module, the <code>tsconfig.json</code> <code>files</code> field would be <code>[\"public_api.ts\"]</code>.\nThe <code>flatModuleOutFile</code> option could then be set to (for example) <code>\"index.js\"</code>, which produces <code>index.d.ts</code> and <code>index.metadata.json</code> files.\nThe <code>module</code> field of the library's <code>package.json</code> would be <code>\"index.js\"</code> and the <code>typings</code> field\nwould be <code>\"index.d.ts\"</code>.</p>\n<h3 id=\"fulltemplatetypecheck\"><code>fullTemplateTypeCheck</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#fulltemplatetypecheck\"><i class=\"material-icons\">link</i></a></h3>\n<p>When <code>true</code> (recommended), enables the <a href=\"guide/aot-compiler#binding-expression-validation\">binding expression validation</a> phase of the template compiler, which uses TypeScript to validate binding expressions. For more information, see <a href=\"guide/template-typecheck\">Template type checking</a>.</p>\n<p>Default is <code>false</code>, but when you use the CLI command <code>ng new --strict</code>, it is set to <code>true</code> in the generated project's configuration.</p>\n<h3 id=\"generatecodeforlibraries\"><code>generateCodeForLibraries</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#generatecodeforlibraries\"><i class=\"material-icons\">link</i></a></h3>\n<p>When <code>true</code> (the default), generates factory files (<code>.ngfactory.js</code> and <code>.ngstyle.js</code>)\nfor <code>.d.ts</code> files with a corresponding <code>.metadata.json</code> file.</p>\n<p>When <code>false</code>, factory files are generated only for <code>.ts</code> files. Do this when using factory summaries.</p>\n<h3 id=\"preservewhitespaces\"><code>preserveWhitespaces</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#preservewhitespaces\"><i class=\"material-icons\">link</i></a></h3>\n<p>When <code>false</code> (the default), removes blank text nodes from compiled templates, which results in smaller emitted template factory modules. Set to <code>true</code> to preserve blank text nodes.</p>\n<h3 id=\"skipmetadataemit\"><code>skipMetadataEmit</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#skipmetadataemit\"><i class=\"material-icons\">link</i></a></h3>\n<p>When <code>true</code>, does not produce <code>.metadata.json</code> files. Default is <code>false</code>.</p>\n<p>The <code>.metadata.json</code> files contain information needed by the template compiler from a <code>.ts</code>\nfile that is not included in the <code>.d.ts</code> file produced by the TypeScript compiler.\nThis information includes, for example, the content of annotations (such as a component's template), which TypeScript emits to the <code>.js</code> file but not to the <code>.d.ts</code> file.</p>\n<p>You can set to <code>true</code> when using factory summaries, because the factory summaries\ninclude a copy of the information that is in the <code>.metadata.json</code> file.</p>\n<p>Set to <code>true</code> if you are using TypeScript's <code>--outFile</code> option, because the metadata files\nare not valid for this style of TypeScript output. However, we do not recommend using <code>--outFile</code> with Angular. Use a bundler, such as <a href=\"https://webpack.js.org/\">webpack</a>, instead.</p>\n<h3 id=\"skiptemplatecodegen\"><code>skipTemplateCodegen</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#skiptemplatecodegen\"><i class=\"material-icons\">link</i></a></h3>\n<p>When <code>true</code>, does not emit <code>.ngfactory.js</code> and <code>.ngstyle.js</code> files. This turns off most of the template compiler and disables the reporting of template diagnostics.</p>\n<p>Can be used to instruct the template compiler to produce <code>.metadata.json</code> files for distribution with an <code>npm</code> package while avoiding the production of <code>.ngfactory.js</code> and <code>.ngstyle.js</code> files that cannot be distributed to <code>npm</code>.</p>\n<p>For library projects generated with the CLI, the dev configuration default is <code>true</code>.</p>\n<h3 id=\"strictmetadataemit\"><code>strictMetadataEmit</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#strictmetadataemit\"><i class=\"material-icons\">link</i></a></h3>\n<p>When <code>true</code>, reports an error to the <code>.metadata.json</code> file if <code>\"skipMetadataEmit\"</code> is <code>false</code>.\nDefault is <code>false</code>. Use only when <code>\"skipMetadataEmit\"</code> is <code>false</code> and <code>\"skipTemplateCodegen\"</code> is <code>true</code>.</p>\n<p>This option is intended to validate the <code>.metadata.json</code> files emitted for bundling with an <code>npm</code> 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 <code>@dynamic</code> in the comment documenting the symbol.</p>\n<p>It is valid for <code>.metadata.json</code> files to contain errors.\nThe template compiler reports these errors if the metadata is used to determine the contents of an annotation.\nThe metadata collector cannot predict the symbols that are designed for use in an annotation, so it preemptively includes error nodes in the metadata for the exported symbols.\nThe template compiler can then use the error nodes to report an error if these symbols are used.</p>\n<p>If the client of a library intends to use a symbol in an annotation, the template compiler does not normally report this until the client uses the symbol.\nThis option allows detection of these errors during the build phase of\nthe library and is used, for example, in producing Angular libraries themselves.</p>\n<p>For library projects generated with the CLI, the dev configuration default is <code>true</code>.</p>\n<h3 id=\"strictinjectionparameters\"><code>strictInjectionParameters</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#strictinjectionparameters\"><i class=\"material-icons\">link</i></a></h3>\n<p>When <code>true</code> (recommended), reports an error for a supplied parameter whose injection type cannot be determined. When <code>false</code> (currently the default), constructor parameters of classes marked with <code>@<a href=\"api/core/Injectable\" class=\"code-anchor\">Injectable</a></code> whose type cannot be resolved produce a warning.</p>\n<p>When you use the CLI command <code>ng new --strict</code>, it is set to <code>true</code> in the generated project's configuration.</p>\n<h3 id=\"stricttemplates\"><code>strictTemplates</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#stricttemplates\"><i class=\"material-icons\">link</i></a></h3>\n<p>When <code>true</code>, enables <a href=\"guide/template-typecheck#strict-mode\">strict template type checking</a>. Strict mode is only available when using <a href=\"guide/ivy\">Ivy</a> (Angular version 9 and later).</p>\n<p>Additional strictness flags allow you to enable and disable specific types of strict template type checking. See <a href=\"guide/template-typecheck#troubleshooting-template-errors\">troubleshooting template errors</a>.</p>\n<p>When you use the CLI command <code>ng new --strict</code>, it is set to <code>true</code> in the generated project's configuration.</p>\n<h3 id=\"trace\"><code>trace</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/angular-compiler-options#trace\"><i class=\"material-icons\">link</i></a></h3>\n<p>When <code>true</code>, prints extra information while compiling templates. Default is <code>false</code>.</p>\n\n \n</div>\n\n<!-- links to this doc:\n - guide/aot-compiler\n - guide/deprecations\n - guide/file-structure\n - guide/strict-mode\n - guide/typescript-configuration\n-->\n<!-- links from this doc:\n - api/core/Component\n - api/core/Injectable\n - api/localize/init/$localize\n - api/upgrade/static\n - guide/angular-compiler-options#allowemptycodegenfiles\n - guide/angular-compiler-options#angular-compiler-options\n - guide/angular-compiler-options#annotateforclosurecompiler\n - guide/angular-compiler-options#annotationsas\n - guide/angular-compiler-options#configuration-inheritance-with-extends\n - guide/angular-compiler-options#disableexpressionlowering\n - guide/angular-compiler-options#disabletypescriptversioncheck\n - guide/angular-compiler-options#enablei18nlegacymessageidformat\n - guide/angular-compiler-options#enableivy\n - guide/angular-compiler-options#enablelegacytemplate\n - guide/angular-compiler-options#enableresourceinlining\n - guide/angular-compiler-options#flatmoduleid\n - guide/angular-compiler-options#flatmoduleoutfile\n - guide/angular-compiler-options#fulltemplatetypecheck\n - guide/angular-compiler-options#generatecodeforlibraries\n - guide/angular-compiler-options#preservewhitespaces\n - guide/angular-compiler-options#skipmetadataemit\n - guide/angular-compiler-options#skiptemplatecodegen\n - guide/angular-compiler-options#strictinjectionparameters\n - guide/angular-compiler-options#strictmetadataemit\n - guide/angular-compiler-options#stricttemplates\n - guide/angular-compiler-options#template-options\n - guide/angular-compiler-options#trace\n - guide/aot-compiler\n - guide/aot-compiler#binding-expression-validation\n - guide/aot-compiler#metadata-rewriting\n - guide/i18n#mark-text-for-translations\n - guide/ivy\n - guide/ivy#opting-out-of-angular-ivy\n - guide/template-typecheck\n - guide/template-typecheck#strict-mode\n - guide/template-typecheck#troubleshooting-template-errors\n - guide/typescript-configuration\n - https://github.com/angular/angular/edit/master/aio/content/guide/angular-compiler-options.md?message=docs%3A%20describe%20your%20change...\n - https://github.com/angular/tsickle\n - https://github.com/google/closure-compiler\n - https://jsdoc.app/\n - https://webpack.js.org/\n - https://www.typescriptlang.org/docs/handbook/tsconfig-json.html\n-->"
|
|
} |