Skip to content

Update Ivy opt-in doc #29955

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 4 commits into from
Closed

Update Ivy opt-in doc #29955

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
69fbbb1
docs: remove aot step from Ivy opt-in
filipesilva Apr 17, 2019
c1a19b5
docs: remove lazy route step from Ivy opt-in
filipesilva Apr 19, 2019
8289257
docs: remove enumeration of one in Ivy opt-in
filipesilva Apr 19, 2019
c3d0cd3
docs: copy edits to Ivy opt-in
filipesilva Apr 22, 2019
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
57 changes: 6 additions & 51 deletions aio/content/guide/ivy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,26 +1,22 @@
# Opting into Angular Ivy with Angular CLI
# Opting into 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 8, you can choose to opt in to start using Ivy now, and help in its continuing develpment and tuning.


## Starting a new project using Ivy
## Using Ivy in a new project

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

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

@jenniferfell jenniferfell Apr 19, 2019

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re "Starting a new project in Ivy." We talk about ng new as "creating" a project. "Starting" can mean many things, including running or serving.

Idea 1: this pair of headings...
Creating a new project to use Ivy
Updating an existing project to use Ivy

Idea 2: this pair of headings...
Using Ivy in a new project
Using Ivy in an existing project

@filipesilva filipesilva Apr 22, 2019

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Went with Idea 2, but have no strong opinion either way.

@jenniferfell jenniferfell Apr 19, 2019

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A thought on the page title. We have mostly stopped highlighting "with the CLI" because 1) it's just how you do things now, it's not a special add-on 2) we don't describe other ways to the tasks. The current page title begs the question: Can I opt into Ivy without the CLI?

I think the page title can just be: Opting into Angular Ivy

If the point is that Ivy isn't yet supported in non-CLI applications, then I would add an alert box with that note near the top of this document.

@filipesilva filipesilva Apr 22, 2019

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed title to be just Opting into Angular Ivy. Ivy is supported in other toolchain, but it is more complicated to use.

The new project is automatically configured for Ivy.
- The `enableIvy` option is set to `true` in `tsconfig.app.json`.
- The `"aot": true` option is added to your default build options.
The new project is automatically configured for Ivy. Specifically, the enableIvy option is set to `true` in the project's `tsconfig.app.json` file.

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

You can update an existing project to use Ivy by making the following configuration changes.
## Using Ivy in an existing project

- Add the `enableIvy` option in the `angularCompilerOptions` in your project's `tsconfig.app.json`.
To update an existing project to use Ivy, set the `enableIvy` option in the `angularCompilerOptions` in your project's `tsconfig.app.json`.
```json
{
"compilerOptions": { ... },
Expand All @@ -29,46 +25,5 @@ You can update an existing project to use Ivy by making the following configurat
}
}
```
- Set `"module": "esnext"` inside `compilerOptions` in your `tsconfig.json` to support the [ES `import()` statement](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import).
```json
{
"compilerOptions": {
...
"module": "esnext",
}
}
```
- Update your lazy routes to use the `import()` statement. You can use [angular-lazy-routes-fix](https://github.com/phenomnomnominal/angular-lazy-routes-fix) to automatically transform them.
```typescript
const routes: Routes = [{
path: 'lazy',
// The string syntax for loadChildren is not supported in Ivy:
// loadChildren: './lazy/lazy.module#LazyModule'
// Instead use the import statement:
loadChildren: () => import('./lazy/lazy.module').then(m => m.LazyModule)
}];
```
- In the `angular.json` workspace configuration file, set the default build options for your project to always use AOT compilation.
```json
{
"projects": {
"my-existing-project": {
"architect": {
"build": {
"options": {
...
"aot": true,
}
}
}
}
}
}
```

## 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 `tsconfig.app.json`, or remove it completely.
- Add `"experimentalImportFactories": true` to your default build options in `angular.json` to support the import statement in `loadChildren` outside Ivy.
- Remove `"aot": true` from your default build options if you didn't have it there before.
To stop using the Ivy compiler, set `enableIvy` to `false` in `tsconfig.app.json`, or remove it completely.