Skip to content

docs: add ivy opt-in docs #28569

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
filipesilva wants to merge 1 commit into from
Closed

docs: add ivy opt-in docs #28569

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 90 additions & 0 deletions aio/content/guide/ivy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
# Opting into Angular Ivy with Angular CLI

[Starting with Angular version 8](https://blog.angular.io/a-plan-for-version-8-0-and-ivy-b3318dfc19f7) you can opt-in to the new [Angular Ivy compilation and rendering pipeline].


## Starting a new project using Ivy

To start a new project with Ivy enabled, use the `--experimental-ivy` flag with the [`ng new`](cli/new) command:

```sh
ng new shiny-ivy-app --experimental-ivy
```

Everything will be configured for you:
- `enableIvy` set to `true` in `src/tsconfig.app.json`.
- `"aot": true` added to your default build options.
- `postinstall` script for the [Angular Compatibility Compiler](#ngcc).

{@a updating}
## Updating an existing project to use Ivy

By configuring a few key files, you can also update your existing project(s) to use Ivy.

- Add the `allowEmptyCodegenFiles` (needed only before version 8 final) and `enableIvy` options in the `angularCompilerOptions` in your project's `src/tsconfig.app.json`:
```json
{
"compilerOptions": { ... },
"angularCompilerOptions": {
"enableIvy": true,
"allowEmptyCodegenFiles": true,
}
}
```
- Set the default build options for your project to always use AOT compilation if it isn't already:
```json
{
"projects": {
"my-existing-project": {
"architect": {
"build": {
"options": {
...
"aot": true,
}
}
}
}
}
}
```
- Add a `postinstall` script to the workspace `package.json` file to run the [Angular Compatibility Compiler](#ngcc):
```json
{
"scripts": {
...
"postinstall": "ivy-ngcc"
}
}
```
- Reinstall your `package.json` dependencies to run the newly added script:

```
npm install
```

## Switching back to the current compiler

To stop using the Ivy compiler you need to undo the steps taken when [updating to use Ivy](#updating).
- Set `enableIvy` to false in `src/tsconfig.app.json`, or remove it completely.
- Remove `"aot": true` from your default build options if you didn't have it there before.
- Remove the `postinstall` script.
- Delete and reinstall your node modules.


{@a ngcc}
## The Angular Compatibility Compiler

Your third party libraries also need to be compiled with Ivy for you to use them in your Ivy application.
That's where the Angular Compatibility (`ngcc`) compiler comes into play.

We set it as a postinstall script in your `package.json` so that it always runs when you install
your `package.json` dependencies.

Using a postinstall hook to run `ngcc` is just a temporary integration.
We expect `ngcc` to be seamlessly integrated into the Angular CLI build pipeline in the future before the full Ivy rollout.
Once that's implemented `ngcc` will not be visible to developers.

Until that happens, opting into Ivy means that all projects in a single CLI workspace will be compiled with Ivy.

Note: we are aware of build-time performance issues with ngcc. Please bear with us while we improve the tooling and build integration in the Angular CLI.
91 changes: 42 additions & 49 deletions aio/content/navigation.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,6 @@
"title": "Blog"
}
],

"TopBarNarrow": [
{
"title": "About Angular",
Expand All @@ -45,28 +44,24 @@
]
}
],

"SideNav": [
{
"url": "docs",
"title": "Docs",
"tooltip": "Angular Documentation",
"hidden": true
},

{
"url": "guide/docs-style-guide",
"title": "Doc authors style guide",
"tooltip": "Style guide for documentation authors.",
"hidden": true
},

{
"url": "guide/quickstart",
"title": "Getting Started",
"tooltip": "A brief introduction to Angular and Angular CLI essentials."
},

{
"title": "Tutorial",
"tooltip": "The Tour of Heroes tutorial takes you through the steps of creating an Angular application in TypeScript.",
Expand Down Expand Up @@ -113,7 +108,6 @@
}
]
},

{
"title": "Fundamentals",
"tooltip": "The fundamentals of Angular",
Expand Down Expand Up @@ -240,8 +234,8 @@
"tooltip": "Render dynamic forms with FormGroup."
}
]
},
{
},
{
"title": "Observables & RxJS",
"tooltip": "Observables & RxJS",
"children": [
Expand Down Expand Up @@ -272,14 +266,12 @@
}
]
},

{
"url": "guide/bootstrapping",
"title": "Bootstrapping",
"tooltip": "Tell Angular how to construct and bootstrap the app in the root \"AppModule\"."
},
{

"title": "NgModules",
"tooltip": "NgModules.",
"children": [
Expand Down Expand Up @@ -343,8 +335,8 @@
"title": "NgModule FAQs",
"tooltip": "Answers to frequently asked questions about NgModules."
}
]},

]
},
{
"title": "Dependency Injection",
"tooltip": "Dependency Injection: creating and injecting services",
Expand Down Expand Up @@ -376,7 +368,6 @@
}
]
},

{
"url": "guide/http",
"title": "HttpClient",
Expand Down Expand Up @@ -418,15 +409,12 @@
}
]
}
]
},


]
},
{
"title": "Techniques",
"tooltip": "Techniques for putting Angular to work in your environment",
"children": [

{
"url": "guide/security",
"title": "Security",
Expand All @@ -437,7 +425,6 @@
"title": "Internationalization (i18n)",
"tooltip": "Translate the app's template text into multiple languages."
},

{
"title": "Service Workers & PWA",
"tooltip": "Angular service workers: Controlling caching of application resources.",
Expand Down Expand Up @@ -515,22 +502,24 @@
"tooltip": "Extend Angular by creating, publishing, and using your own libraries."
}
]
},
{
"url": "guide/ivy",
"title": "Angular Ivy",
"tooltip": "Opting into Angular Ivy with Angular CLI."
}
]
},

{
"title": "Setup & Deployment",
"tooltip": "Setup, build, testing, and deployment environment and tool information.",
"children": [

{
"url": "guide/setup",
"title": "Setup for local development",
"tooltip": "Install the Angular QuickStart seed for faster, more efficient development on your machine.",
"hidden": true
},

{
"url": "guide/file-structure",
"title": "Project File Structure",
Expand All @@ -541,7 +530,6 @@
"title": "Workspace Configuration",
"tooltip": "The \"angular.json\" file contains workspace and project configuration defaults for Angular CLI commands."
},

{
"url": "guide/npm-packages",
"title": "npm Dependencies",
Expand Down Expand Up @@ -577,50 +565,45 @@
"title": "Browser Support",
"tooltip": "Browser support and polyfills guide."
},

{
"title": "Dev Tool Integration",
"tooltip": "Integrate with your development environment and tools.",
"children": [
{
"url": "guide/language-service",
"title": "Language Service",
"tooltip": "Use Angular Language Service to speed up dev time."
},
{
"url": "guide/visual-studio-2015",
"title": "Visual Studio 2015",
"tooltip": "Using Angular with Visual Studio 2015.",
"hidden": true
}
{
"url": "guide/language-service",
"title": "Language Service",
"tooltip": "Use Angular Language Service to speed up dev time."
},
{
"url": "guide/visual-studio-2015",
"title": "Visual Studio 2015",
"tooltip": "Using Angular with Visual Studio 2015.",
"hidden": true
}
]
}
]
]
},


{
"title": "Release Information",
"tooltip": "Angular release practices, updating, and upgrading.",
"children": [
{
"url": "guide/updating",
"title": "Keeping Up-to-Date",
"tooltip": "Information about updating Angular applications and libraries to the latest version."
},
"title": "Keeping Up-to-Date",
"tooltip": "Information about updating Angular applications and libraries to the latest version."
},
{
"url": "guide/releases",
"title": "Angular Releases",
"tooltip": "Angular versioning, release, support, and deprecation policies and practices."
}
]
},

{
"title": "Quick Reference",
"tooltip": "Summaries of Angular syntax, coding, and terminology.",
"children": [

{
"url": "guide/cheatsheet",
"title": "Cheat Sheet",
Expand Down Expand Up @@ -661,7 +644,6 @@
"hidden": true
}
],

"Footer": [
{
"title": "Resources",
Expand Down Expand Up @@ -761,11 +743,22 @@
]
}
],

"docVersions": [
{ "title": "v6", "url": "https://v6.angular.io" },
{ "title": "v5", "url": "https://v5.angular.io" },
{ "title": "v4", "url": "https://v4.angular.io" },
{ "title": "v2", "url": "https://v2.angular.io" }
{
"title": "v6",
"url": "https://v6.angular.io"
},
{
"title": "v5",
"url": "https://v5.angular.io"
},
{
"title": "v4",
"url": "https://v4.angular.io"
},
{
"title": "v2",
"url": "https://v2.angular.io"
}
]
}