docs: add ivy opt-in docs (#28569)

PR Close #28569

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.

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",
@@ -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",
@@ -420,13 +411,10 @@
         }
       ]
     },
-
-
     {
       "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,7 +565,6 @@
           "title": "Browser Support",
           "tooltip": "Browser support and polyfills guide."
         },
-
         {
           "title": "Dev Tool Integration",
           "tooltip": "Integrate with your development environment and tools.",
@@ -597,8 +584,6 @@
         }
       ]
     },
-
-
     {
       "title": "Release Information",
       "tooltip": "Angular release practices, updating, and upgrading.",
@@ -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"
+    }
   ]
 }