From f01247f0a4211e24f131ce324e1375dc4382a330 Mon Sep 17 00:00:00 2001 From: Filipe Silva Date: Wed, 6 Feb 2019 15:32:32 +0000 Subject: [PATCH] docs: add ivy opt-in docs (#28569) PR Close #28569 --- aio/content/guide/ivy.md | 90 ++++++++++++++++++++++++++++++++++++ aio/content/navigation.json | 91 +++++++++++++++++-------------------- 2 files changed, 132 insertions(+), 49 deletions(-) create mode 100644 aio/content/guide/ivy.md diff --git a/aio/content/guide/ivy.md b/aio/content/guide/ivy.md new file mode 100644 index 0000000000..f2e8982e0f --- /dev/null +++ b/aio/content/guide/ivy.md @@ -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. diff --git a/aio/content/navigation.json b/aio/content/navigation.json index 82605123e8..0171498018 100644 --- a/aio/content/navigation.json +++ b/aio/content/navigation.json @@ -21,7 +21,6 @@ "title": "Blog" } ], - "TopBarNarrow": [ { "title": "About Angular", @@ -45,7 +44,6 @@ ] } ], - "SideNav": [ { "url": "docs", @@ -53,20 +51,17 @@ "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.", @@ -113,7 +108,6 @@ } ] }, - { "title": "Fundamentals", "tooltip": "The fundamentals of Angular", @@ -240,8 +234,8 @@ "tooltip": "Render dynamic forms with FormGroup." } ] - }, - { + }, + { "title": "Observables & RxJS", "tooltip": "Observables & RxJS", "children": [ @@ -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": [ @@ -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", @@ -376,7 +368,6 @@ } ] }, - { "url": "guide/http", "title": "HttpClient", @@ -418,15 +409,12 @@ } ] } - ] - }, - - + ] + }, { "title": "Techniques", "tooltip": "Techniques for putting Angular to work in your environment", "children": [ - { "url": "guide/security", "title": "Security", @@ -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.", @@ -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", @@ -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", @@ -577,37 +565,34 @@ "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", @@ -615,12 +600,10 @@ } ] }, - { "title": "Quick Reference", "tooltip": "Summaries of Angular syntax, coding, and terminology.", "children": [ - { "url": "guide/cheatsheet", "title": "Cheat Sheet", @@ -661,7 +644,6 @@ "hidden": true } ], - "Footer": [ { "title": "Resources", @@ -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" + } ] }