From e3d6e97050ef7637b7dd80d5c018a24cabb9caee Mon Sep 17 00:00:00 2001 From: Andrew Kushnir Date: Mon, 4 Oct 2021 18:27:04 -0700 Subject: [PATCH] docs: deprecate ViewEngine-based JIT Compiler symbols (#43710) DEPRECATION: In ViewEngine, [JIT compilation](https://angular.io/guide/glossary#jit) required special providers (like `Compiler`, `CompilerFactory`, etc) to be injected in the app and corresponding methods to be invoked. With Ivy, JIT compilation takes place implicitly if the Component, NgModule, etc have not already been [AOT compiled](https://angular.io/guide/glossary#aot). Those special providers were made available in Ivy for backwards-compatibility with ViewEngine to make the transition to Ivy smoother. Since ViewEngine is deprecated and will soon be removed, those symbols are now deprecated as well: - `ModuleWithComponentFactories` - `Compiler` - `CompilerFactory` - `JitCompilerFactory` - `NgModuleFactory` Important note: this deprecation doesn't affect JIT mode in Ivy (JIT remains available with Ivy). PR Close #43710 --- aio/content/guide/deprecations.md | 26 +++++++++++++++++++ goldens/public-api/core/core.md | 8 +++--- .../platform-browser-dynamic.md | 5 ++-- packages/core/src/linker/compiler.ts | 15 +++++++++++ packages/core/src/linker/ng_module_factory.ts | 8 ++++++ .../src/compiler_factory.ts | 5 ++++ 6 files changed, 60 insertions(+), 7 deletions(-) diff --git a/aio/content/guide/deprecations.md b/aio/content/guide/deprecations.md index 3c58fc0daa9..0065cd4b498 100644 --- a/aio/content/guide/deprecations.md +++ b/aio/content/guide/deprecations.md @@ -44,6 +44,11 @@ v13 -> v16 | `@angular/core` | [Factory-based signature of `ApplicationRef.bootstrap`](#core) | v15 | | `@angular/core` | [`PlatformRef.bootstrapModuleFactory`](#core) | v15 | | `@angular/core` | [`getModuleFactory`](#core) | v16 | +| `@angular/core` | [`ModuleWithComponentFactories`](#core) | v16 | +| `@angular/core` | [`Compiler`](#core) | v16 | +| `@angular/core` | [`CompilerFactory`](#core) | v16 | +| `@angular/core` | [`NgModuleFactory`](#core) | v16 | +| `@angular/platform-browser-dynamic` | [`JitCompilerFactory`](#platform-browser-dynamic) | v16 | | `@angular/forms` | [`ngModel` with reactive forms](#ngmodel-reactive) | v11 | | `@angular/upgrade` | [`@angular/upgrade`](#upgrade) | v11 | | `@angular/upgrade` | [`getAngularLib`](#upgrade-static) | v11 | @@ -113,8 +118,20 @@ This section contains a complete list all of the currently-deprecated APIs, with | `ViewChildren.emitDistinctChangesOnly` / `ContentChildren.emitDistinctChangesOnly` | none (was part of [issue #40091](https://github.com/angular/angular/issues/40091)) | | This is a temporary flag introduced as part of bugfix of [issue #40091](https://github.com/angular/angular/issues/40091) and will be removed. | | Factory-based signature of [`ApplicationRef.bootstrap`](api/core/ApplicationRef#bootstrap) | Type-based signature of [`ApplicationRef.bootstrap`](api/core/ApplicationRef#bootstrap) | v13 | With Ivy, there is no need to resolve Component factory and Component Type can be provided directly. | | [`PlatformRef.bootstrapModuleFactory`](api/core/PlatformRef#bootstrapModuleFactory) | [`PlatformRef.bootstrapModule`](api/core/PlatformRef#bootstrapModule) | v13 | With Ivy, there is no need to resolve NgModule factory and NgModule Type can be provided directly. | +| [`ModuleWithComponentFactories`](api/core/ModuleWithComponentFactories) | none | v13 | Ivy JIT mode doesn't require accessing this symbol. See [JIT API changes due to ViewEngine deprecation](#jit-api-changes) for additional context. | +| [`Compiler`](api/core/Compiler) | none | v13 | Ivy JIT mode doesn't require accessing this symbol. See [JIT API changes due to ViewEngine deprecation](#jit-api-changes) for additional context. | +| [`CompilerFactory`](api/core/CompilerFactory) | none | v13 | Ivy JIT mode doesn't require accessing this symbol. See [JIT API changes due to ViewEngine deprecation](#jit-api-changes) for additional context. | +| [`NgModuleFactory`](api/core/NgModuleFactory) | Use non-factory based framework APIs like [PlatformRef.bootstrapModule](api/core/PlatformRef#bootstrapModule) and [createNgModuleRef](api/core/createNgModuleRef) | v13 | Ivy JIT mode doesn't require accessing this symbol. See [JIT API changes due to ViewEngine deprecation](#jit-api-changes) for additional context. | | [Factory-based signature of `ViewContainerRef.createComponent`](api/core/ViewContainerRef#createComponent) | [Type-based signature of `ViewContainerRef.createComponent`](api/core/ViewContainerRef#createComponent) | v13 | Angular no longer requires component factories to dynamically create components. Use different signature of the `createComponent` method, which allows passing Component class directly. | +{@a platform-browser-dynamic} + +### @angular/platform-browser-dynamic + +| API | Replacement | Deprecation announced | Notes | +|:--- |:--- |:--- |:--- | +| [`JitCompilerFactory`](api/platform-browser-dynamic/JitCompilerFactory) | none | v13 | Ivy JIT mode doesn't require accessing this symbol. See [JIT API changes due to ViewEngine deprecation](#jit-api-changes) for additional context. | + {@a testing} ### @angular/core/testing @@ -576,6 +593,15 @@ Projects that currently have `fullTemplateTypeCheck: true` configured can migrat +{@a jit-api-changes} + +## JIT API changes due to ViewEngine deprecation + +In ViewEngine, [JIT compilation](https://angular.io/guide/glossary#jit) required special providers (like `Compiler`, `CompilerFactory`, etc) to be injected in the app and corresponding methods to be invoked. With Ivy, JIT compilation takes place implicitly if the Component, NgModule, etc have not already been [AOT compiled](https://angular.io/guide/glossary#aot). Those special providers were made available in Ivy for backwards-compatibility with ViewEngine to make the transition to Ivy smoother. Since ViewEngine is deprecated and will soon be removed, those symbols are now deprecated as well. + +Important note: this deprecation doesn't affect JIT mode in Ivy (JIT remains available with Ivy, however we are exploring a possibility of deprecating it in the future. See [RFC: Exploration of use-cases for Angular JIT compilation mode](https://github.com/angular/angular/issues/43133)). + + {@a deprecated-cli-flags} ## Deprecated CLI APIs and Options diff --git a/goldens/public-api/core/core.md b/goldens/public-api/core/core.md index fd51ba98bf3..859d307915f 100644 --- a/goldens/public-api/core/core.md +++ b/goldens/public-api/core/core.md @@ -135,7 +135,7 @@ export interface ClassSansProvider { useClass: Type; } -// @public +// @public @deprecated export class Compiler { clearCache(): void; clearCacheFor(type: Type): void; @@ -153,7 +153,7 @@ export class Compiler { // @public export const COMPILER_OPTIONS: InjectionToken; -// @public +// @public @deprecated export abstract class CompilerFactory { // (undocumented) abstract createCompiler(options?: CompilerOptions[]): Compiler; @@ -785,7 +785,7 @@ export enum MissingTranslationStrategy { Warning = 1 } -// @public +// @public @deprecated export class ModuleWithComponentFactories { constructor(ngModuleFactory: NgModuleFactory, componentFactories: ComponentFactory[]); // (undocumented) @@ -829,7 +829,7 @@ export interface NgModuleDecorator { new (obj?: NgModule): NgModule; } -// @public (undocumented) +// @public @deprecated (undocumented) export abstract class NgModuleFactory { // (undocumented) abstract create(parentInjector: Injector | null): NgModuleRef; diff --git a/goldens/public-api/platform-browser-dynamic/platform-browser-dynamic.md b/goldens/public-api/platform-browser-dynamic/platform-browser-dynamic.md index 378f5ca2b7c..fba86e3777e 100644 --- a/goldens/public-api/platform-browser-dynamic/platform-browser-dynamic.md +++ b/goldens/public-api/platform-browser-dynamic/platform-browser-dynamic.md @@ -12,11 +12,11 @@ import { Provider } from '@angular/core'; import { StaticProvider } from '@angular/core'; import { Version } from '@angular/core'; -// @public (undocumented) +// @public @deprecated (undocumented) export class JitCompilerFactory implements CompilerFactory { // (undocumented) createCompiler(options?: CompilerOptions[]): Compiler; - } +} // @public (undocumented) export const platformBrowserDynamic: (extraProviders?: StaticProvider[] | undefined) => PlatformRef; @@ -27,7 +27,6 @@ export const RESOURCE_CACHE_PROVIDER: Provider[]; // @public (undocumented) export const VERSION: Version; - // (No @packageDocumentation comment for this package) ``` diff --git a/packages/core/src/linker/compiler.ts b/packages/core/src/linker/compiler.ts index 77a64ed8e36..599d3c57c9d 100644 --- a/packages/core/src/linker/compiler.ts +++ b/packages/core/src/linker/compiler.ts @@ -26,6 +26,11 @@ import {NgModuleFactory} from './ng_module_factory'; * Combination of NgModuleFactory and ComponentFactories. * * @publicApi + * + * @deprecated + * Ivy JIT mode doesn't require accessing this symbol. + * See [JIT API changes due to ViewEngine deprecation](guide/deprecations#jit-api-changes) for + * additional context. */ export class ModuleWithComponentFactories { constructor( @@ -93,6 +98,11 @@ const Compiler_compileModuleAndAllComponentsAsync = * of components. * * @publicApi + * + * @deprecated + * Ivy JIT mode doesn't require accessing this symbol. + * See [JIT API changes due to ViewEngine deprecation](guide/deprecations#jit-api-changes) for + * additional context. */ @Injectable() export class Compiler { @@ -162,6 +172,11 @@ export const COMPILER_OPTIONS = new InjectionToken('compilerO * A factory for creating a Compiler * * @publicApi + * + * @deprecated + * Ivy JIT mode doesn't require accessing this symbol. + * See [JIT API changes due to ViewEngine deprecation](guide/deprecations#jit-api-changes) for + * additional context. */ export abstract class CompilerFactory { abstract createCompiler(options?: CompilerOptions[]): Compiler; diff --git a/packages/core/src/linker/ng_module_factory.ts b/packages/core/src/linker/ng_module_factory.ts index 05e4c430e04..6dc5b6fd6fa 100644 --- a/packages/core/src/linker/ng_module_factory.ts +++ b/packages/core/src/linker/ng_module_factory.ts @@ -54,6 +54,14 @@ export interface InternalNgModuleRef extends NgModuleRef { /** * @publicApi + * + * @deprecated + * This class was mostly used as a part of ViewEngine-based JIT API and is no longer needed in Ivy + * JIT mode. See [JIT API changes due to ViewEngine deprecation](guide/deprecations#jit-api-changes) + * for additional context. Angular provides APIs that accept NgModule classes directly (such as + * [PlatformRef.bootstrapModule](api/core/PlatformRef#bootstrapModule) and + * [createNgModuleRef](api/core/createNgModuleRef)), consider switching to those APIs instead of + * using factory-based ones. */ export abstract class NgModuleFactory { abstract get moduleType(): Type; diff --git a/packages/platform-browser-dynamic/src/compiler_factory.ts b/packages/platform-browser-dynamic/src/compiler_factory.ts index 148ff45d29b..6c6bbd5e7a2 100644 --- a/packages/platform-browser-dynamic/src/compiler_factory.ts +++ b/packages/platform-browser-dynamic/src/compiler_factory.ts @@ -171,6 +171,11 @@ export const COMPILER_PROVIDERS__POST_R3__ = export const COMPILER_PROVIDERS = COMPILER_PROVIDERS__PRE_R3__; /** * @publicApi + * + * @deprecated + * Ivy JIT mode doesn't require accessing this symbol. + * See [JIT API changes due to ViewEngine deprecation](guide/deprecations#jit-api-changes) for + * additional context. */ export class JitCompilerFactory implements CompilerFactory { private _defaultOptions: CompilerOptions[];