docs: rewrite ivy page, add template typecheck doc (#33152)
PR Close #33152
This commit is contained in:
Judy Bogart
Andrew Kushnir
parent
5666d11633
commit
fba72f0d4d
|
|
@ -471,7 +471,6 @@
|
|||
/aio/content/guide/web-worker.md @angular/tools-cli @angular/framework-global-approvers @angular/framework-global-approvers-for-docs-only-changes
|
||||
|
||||
|
||||
|
||||
# ================================================
|
||||
# @angular/core
|
||||
# @angular/common (except @angular/common/http)
|
||||
|
|
|
|||
|
|
@ -564,10 +564,25 @@ It does not, however, rewrite the `.d.ts` file, so TypeScript doesn't recognize
|
|||
{@a binding-expression-validation}
|
||||
## Phase 3: Template type checking
|
||||
|
||||
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.
|
||||
In the template type-checking phase, the Angular template compiler uses the TypeScript compiler to validate the binding expressions in templates.
|
||||
|
||||
Enable this phase explicitly by adding the compiler option `"fullTemplateTypeCheck"` in the `"angularCompilerOptions"` of the project's `tsconfig.json`
|
||||
(see [Angular Compiler Options](guide/angular-compiler-options)).
|
||||
|
||||
<div class="alert is-helpful>
|
||||
|
||||
In [Angular Ivy](guide/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.
|
||||
|
||||
As 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.
|
||||
|
||||
This stricter type checking is not enabled by default in version 9, but can be enabled by setting the `strictTemplates` configuration option.
|
||||
We 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](guide/template-type-checking). -->
|
||||
|
||||
</div>
|
||||
|
||||
Template validation produces error messages when a type error is detected in a template binding
|
||||
expression, similar to how type errors are reported by the TypeScript compiler against code in a `.ts`
|
||||
file.
|
||||
|
|
|
|||
|
|
@ -1,26 +1,23 @@
|
|||
# Opting out of Angular Ivy
|
||||
# Angular Ivy
|
||||
|
||||
Ivy is the code name for Angular's [next-generation compilation and rendering pipeline](https://blog.angular.io/a-plan-for-version-8-0-and-ivy-b3318dfc19f7).
|
||||
Starting with Angular version 9, Ivy compilation and rendering pipeline is enabled by default.
|
||||
The previous compilation and rendering pipeline, View Engine, is deprecated in version 9, and will be removed at a later date.
|
||||
You can choose to opt out of Ivy and continue using View Engine while making the transition.
|
||||
With the version 9 release of Angular, the new compiler and runtime instructions are used by default instead of the older compiler and runtime, known as View Engine.
|
||||
|
||||
To opt out of Ivy and continue using View Engine for an existing project, set the `enableIvy` option in the `angularCompilerOptions` in your project's `tsconfig.json` to `false`.
|
||||
<code-example language="json" header="tsconfig.json">
|
||||
{
|
||||
"compilerOptions": { ... },
|
||||
"angularCompilerOptions": {
|
||||
"enableIvy": false
|
||||
}
|
||||
}
|
||||
</code-example>
|
||||
<div class="alert is-helpful">
|
||||
|
||||
AOT compilation with Ivy is faster than with View Engine, and can be used for development.
|
||||
If you opt out of Ivy, AOT compilation will be slower, and should not be used for development in large projects.
|
||||
When Ivy is disabled for a large project, make sure that the `aot` build option in that project configuration is
|
||||
set to `false` and it's only set to `true` in the `production` configuration.
|
||||
Learn more about the [Compiler](https://www.youtube.com/watch?v=anphffaCZrQ) and [Runtime](https://www.youtube.com/watch?v=S0o-4yc2n-8) in these videos from our team.
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
{@a aot-and-ivy}
|
||||
## AOT and Ivy
|
||||
|
||||
AOT compilation with Ivy is faster and should be used by default.
|
||||
In the `angular.json` workspace configuration file, set the default build options for your project to always use AOT compilation.
|
||||
|
||||
<code-example language="json" header="angular.json">
|
||||
|
||||
{
|
||||
"projects": {
|
||||
"my-existing-project": {
|
||||
|
|
@ -28,13 +25,7 @@ set to `false` and it's only set to `true` in the `production` configuration.
|
|||
"build": {
|
||||
"options": {
|
||||
...
|
||||
"aot": false,
|
||||
},
|
||||
"configurations": {
|
||||
"production": {
|
||||
...
|
||||
"aot": true
|
||||
}
|
||||
"aot": true,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -43,13 +34,53 @@ set to `false` and it's only set to `true` in the `production` configuration.
|
|||
}
|
||||
</code-example>
|
||||
|
||||
Ivy projects usually contain a `postinstall` script in the `scripts` section of `package.json` that converts packages in `node_modules` to use Ivy as well.
|
||||
When you opt out of Ivy, remove this script. Remove the following line in package.json.
|
||||
## Ivy and libraries
|
||||
|
||||
<code-example language="json" header="package.json">
|
||||
Ivy applications can be built with libraries that were created with the View Engine compiler.
|
||||
This compatibility is provided by a tool known as the Angular compatibility compiler (`ngcc`).
|
||||
CLI commands run `ngcc` as needed, either after npm installation of dependencies or when performing an Angular build.
|
||||
|
||||
If you are a library author, you should keep using the View Engine compiler as of version 9.
|
||||
By having all libraries continue to use View Engine, you will maintain compatibility with default v9 applications that use Ivy, as well as with applications that have opted to continue using View Engine.
|
||||
|
||||
See the [Creating Libraries](guide/creating-libraries) guide for more on how to compile or bundle your Angular library.
|
||||
When you use the tools integrated into the Angular CLI or `ng-packagr`, your library will always be built the right way automatically.
|
||||
|
||||
{@a opting-out-of-angular-ivy}
|
||||
## Opting out of Ivy in version 9
|
||||
|
||||
In version 9, Ivy is the default.
|
||||
For compatibility with current workflows during the update process, you can choose to opt out of Ivy and continue using the previous compiler, View Engine.
|
||||
|
||||
<div class="alert is-helpful>
|
||||
|
||||
Before disabling Ivy, check out the debugging recommendations in the [Ivy Compatibility Guide](guide/ivy-compatibility#debugging).
|
||||
|
||||
</div>
|
||||
|
||||
To opt out of Ivy, change the `angularCompilerOptions` in your project's TypeScript configuration, most commonly located at `tsconfig.app.json` at the root of the workspace.
|
||||
|
||||
The value of the `enableIvy` flag is set to `true` by default, as of version 9.
|
||||
The following example shows how to set the `enableIvy` option to `false` in order to opt out of Ivy.
|
||||
|
||||
<code-example language="json" header="tsconfig.app.json">
|
||||
{
|
||||
"scripts": {
|
||||
"postinstall": "ngcc --properties es2015 browser module main --first-only --create-ivy-entry-points"
|
||||
"extends": "./tsconfig.json",
|
||||
"compilerOptions": {
|
||||
"outDir": "./out-tsc/app",
|
||||
"types": []
|
||||
},
|
||||
"include": [
|
||||
"src/**/*.ts"
|
||||
],
|
||||
"exclude": [
|
||||
"src/test.ts",
|
||||
"src/**/*.spec.ts"
|
||||
],
|
||||
"angularCompilerOptions": {
|
||||
"enableIvy": false
|
||||
}
|
||||
}
|
||||
</code-example>
|
||||
|
||||
If you disable Ivy, you might also want to reconsider whether to make AOT compilation the default for your application development, as described [above](#aot-and-ivy). To revert the compiler default, set the build option `aot: false` in the `angular.json` configuration file.
|
||||
|
|
@ -576,11 +576,6 @@
|
|||
"title": "CLI Builders",
|
||||
"tooltip": "Using builders to customize Angular CLI."
|
||||
},
|
||||
{
|
||||
"url": "guide/ivy",
|
||||
"title": "Angular Ivy",
|
||||
"tooltip": "Opting out of Angular Ivy with Angular CLI."
|
||||
},
|
||||
{
|
||||
"url": "guide/web-worker",
|
||||
"title": "Web Workers",
|
||||
|
|
@ -712,6 +707,11 @@
|
|||
"url": "guide/deprecations",
|
||||
"title": "Deprecations",
|
||||
"tooltip": "Summary of Angular APIs and features that are deprecated."
|
||||
},
|
||||
{
|
||||
"url": "guide/ivy",
|
||||
"title": "Angular Ivy",
|
||||
"tooltip": "About the Angular Ivy compilation and rendering pipeline."
|
||||
}
|
||||
]
|
||||
},
|
||||
|
|
|
|||
Loading…
Reference in New Issue