Skip to content

Ivy guide update #29506

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

Ivy guide update #29506

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ce4562e
docs: add Ivy lazy load opt-in
filipesilva Mar 25, 2019
ac5bc0f
docs: remove ngcc steps from Ivy opt-in
filipesilva Mar 25, 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
64 changes: 24 additions & 40 deletions aio/content/guide/ivy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,26 +12,42 @@ ng new shiny-ivy-app --enable-ivy
```

The new project is automatically configured for Ivy.
- The `enableIvy` option is set to `true` in `src/tsconfig.app.json`.
- The `enableIvy` option is set to `true` in `tsconfig.app.json`.
- The `"aot": true` option is added to your default build options.
- A `postinstall` script is provided for the [Angular Compatibility Compiler](#ngcc).

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

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

- Add the `enableIvy` option in the `angularCompilerOptions` in your project's `src/tsconfig.app.json`.
To use Ivy before version 8 is final, add the `allowEmptyCodegenFiles`as well.
- Add the `enableIvy` option in the `angularCompilerOptions` in your project's `tsconfig.app.json`.
```json
{
"compilerOptions": { ... },
"angularCompilerOptions": {
"enableIvy": true,
"allowEmptyCodegenFiles": true,
"enableIvy": true
}
}
```
- 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
{
Expand All @@ -49,42 +65,10 @@ To use Ivy before version 8 is final, add the `allowEmptyCodegenFiles`as well.
}
}
```
- 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
```

@gkalpak gkalpak Mar 29, 2019

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Don't you still need to restore node_modules/ to clean up typings modified by ngcc?

@filipesilva filipesilva Mar 29, 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.

AFAIK it's ok to leave it there for VE compilations because the typings were additive. So if you want to switch back and forth there is no need to reinstall. Also if you want to switch, and you reinstall, the first build will again take longer.

Is there any real risk that new typings will be used by accident?

@gkalpak gkalpak Mar 29, 2019

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Well, even if additive, the typings will be wrong. (For example, certain classes will claim thay have some properties that they don't.)
I don't know of any reason for people to want to use or care about those properties, so they are probably harmless, but I might miss something.


## 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.
- 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.
- Remove the `postinstall` script.
- Delete and reinstall your node modules.


{@a ngcc}
## The Angular Compatibility Compiler

The Angular Compatibility (`ngcc`) compiler helps you compile third-party libraries with Ivy so that you can use them in your Ivy application.
Use a postinstall script in your `package.json` to always run `ngcc` when you install your `package.json` dependencies, so that all projects in the workspace are compiled with Ivy.

<div class="alert is-helpful">

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.

Note that there are currently some build-time performance issues with `ngcc`. Please bear with us while we improve the tooling and build integration in the Angular CLI.

</div>