feat(core): add the bootstrapApplication function (#45674)

AndrewKushnir · atscott · commit 5771b18a989c · 2022-04-21T17:47:54.000-07:00
This commit implements the `bootstrapApplication` function that allows bootstrapping an application and pass a standalone component as a root component. PR Close #45674
diff --git a/goldens/public-api/core/errors.md b/goldens/public-api/core/errors.md
@@ -45,6 +45,8 @@ export const enum RuntimeErrorCode {
     // (undocumented)
     INVALID_INJECTION_TOKEN = 204,
     // (undocumented)
+    MISSING_GENERATED_DEF = 906,
+    // (undocumented)
     MISSING_INJECTION_CONTEXT = 203,
     // (undocumented)
     MULTIPLE_COMPONENTS_MATCH = -300,
@@ -65,6 +67,8 @@ export const enum RuntimeErrorCode {
     // (undocumented)
     TEMPLATE_STRUCTURE_ERROR = 305,
     // (undocumented)
+    TYPE_IS_NOT_STANDALONE = 907,
+    // (undocumented)
     UNKNOWN_BINDING = 303,
     // (undocumented)
     UNKNOWN_ELEMENT = 304,
diff --git a/goldens/public-api/platform-browser/index.md b/goldens/public-api/platform-browser/index.md
@@ -4,6 +4,7 @@
 
 ```ts
 
+import { ApplicationRef } from '@angular/core';
 import { ComponentRef } from '@angular/core';
 import { DebugElement } from '@angular/core';
 import { DebugNode } from '@angular/core';
@@ -14,12 +15,21 @@ import { ModuleWithProviders } from '@angular/core';
 import { NgZone } from '@angular/core';
 import { PlatformRef } from '@angular/core';
 import { Predicate } from '@angular/core';
+import { Provider } from '@angular/core';
 import { Sanitizer } from '@angular/core';
 import { SecurityContext } from '@angular/core';
 import { StaticProvider } from '@angular/core';
 import { Type } from '@angular/core';
 import { Version } from '@angular/core';
 
+// @public
+export interface ApplicationConfig {
+    providers: Provider[];
+}
+
+// @public
+export function bootstrapApplication(rootComponent: Type<unknown>, options?: ApplicationConfig): Promise<ApplicationRef>;
+
 // @public
 export class BrowserModule {
     constructor(parentModule: BrowserModule | null);
diff --git a/packages/core/src/application_ref.ts b/packages/core/src/application_ref.ts
@@ -15,10 +15,12 @@ import {ApplicationInitStatus} from './application_init';
 import {APP_BOOTSTRAP_LISTENER, PLATFORM_INITIALIZER} from './application_tokens';
 import {getCompilerFacade, JitCompilerUsage} from './compiler/compiler_facade';
 import {Console} from './console';
+import {importProvidersFrom} from './di';
 import {Injectable} from './di/injectable';
 import {InjectionToken} from './di/injection_token';
 import {Injector} from './di/injector';
-import {StaticProvider} from './di/interface/provider';
+import {Provider, StaticProvider} from './di/interface/provider';
+import {EnvironmentInjector} from './di/r3_injector';
 import {INJECTOR_SCOPE} from './di/scope';
 import {ErrorHandler} from './error_handler';
 import {formatRuntimeError, RuntimeError, RuntimeErrorCode} from './errors';
@@ -33,9 +35,13 @@ import {InternalViewRef, ViewRef} from './linker/view_ref';
 import {isComponentResourceResolutionQueueEmpty, resolveComponentResources} from './metadata/resource_loading';
 import {assertNgModuleType} from './render3/assert';
 import {ComponentFactory as R3ComponentFactory} from './render3/component_ref';
+import {getComponentDef} from './render3/definition';
+import {assertStandaloneComponentType} from './render3/errors';
+import {StandaloneService} from './render3/features/standalone_feature';
 import {setLocaleId} from './render3/i18n/i18n_locale_id';
 import {setJitOptions} from './render3/jit/jit_options';
-import {NgModuleFactory as R3NgModuleFactory} from './render3/ng_module_ref';
+import {isStandalone} from './render3/jit/module';
+import {createEnvironmentInjector, NgModuleFactory as R3NgModuleFactory} from './render3/ng_module_ref';
 import {publishDefaultGlobalUtils as _publishDefaultGlobalUtils} from './render3/util/global_utils';
 import {Testability, TestabilityRegistry} from './testability/testability';
 import {isPromise} from './util/lang';
@@ -143,11 +149,107 @@ export function createPlatform(injector: Injector): PlatformRef {
   publishDefaultGlobalUtils();
   _platformInjector = injector;
   const platform = injector.get(PlatformRef);
-  const inits = injector.get(PLATFORM_INITIALIZER, null);
-  if (inits) inits.forEach(initFn => initFn());
+  runPlatformInitializers(injector);
   return platform;
 }
 
+/**
+ * The goal of this function is to bootstrap a platform injector,
+ * but avoid referencing `PlatformRef` class.
+ * This function is needed for bootstrapping a Standalone Component.
+ */
+export function createOrReusePlatformInjector(providers: StaticProvider[] = []): Injector {
+  // If a platform injector already exists, it means that the platform
+  // is already bootstrapped and no additional actions are required.
+  if (_platformInjector) return _platformInjector;
+
+  // Otherwise, setup a new platform injector and run platform initializers.
+  const injector = createPlatformInjector(providers);
+  _platformInjector = injector;
+  publishDefaultGlobalUtils();
+  runPlatformInitializers(injector);
+  return injector;
+}
+
+export function runPlatformInitializers(injector: Injector): void {
+  const inits = injector.get(PLATFORM_INITIALIZER, null);
+  if (inits) {
+    inits.forEach((init: any) => init());
+  }
+}
+
+/**
+ * Internal bootstrap application API that implements the core bootstrap logic.
+ *
+ * Platforms (such as `platform-browser`) may require different set of application and platform
+ * providers for an application to function correctly. As a result, platforms may use this function
+ * internally and supply the necessary providers during the bootstrap, while exposing
+ * platform-specific APIs as a part of their public API.
+ *
+ * @returns A promise that returns an `ApplicationRef` instance once resolved.
+ */
+export function bootstrapApplication(config: {
+  rootComponent: Type<unknown>,
+  appProviders?: Provider[],
+  platformProviders?: Provider[],
+}): Promise<ApplicationRef> {
+  const {rootComponent, appProviders, platformProviders} = config;
+  NG_DEV_MODE && assertStandaloneComponentType(rootComponent);
+
+  const platformInjector = createOrReusePlatformInjector(platformProviders as StaticProvider[]);
+
+  const ngZone = new NgZone(getNgZoneOptions());
+
+  return ngZone.run(() => {
+    // Create root application injector based on a set of providers configured at the platform
+    // bootstrap level as well as providers passed to the bootstrap call by a user.
+    const allAppProviders = [
+      {provide: NgZone, useValue: ngZone},  //
+      ...(appProviders || []),              //
+      // Collect providers from the root standalone component
+      // and all of its dependencies (NgModule, other standalone Components)
+      // and make those providers available in the DI tree.
+      ...importProvidersFrom(rootComponent),
+    ];
+    const appInjector = createEnvironmentInjector(
+        allAppProviders, platformInjector as EnvironmentInjector, 'Environment Injector');
+
+    // Instruct `StandaloneService` to use the `appInjector` as an injector for this
+    // root component, so that there is no extra injector instance created.
+    const componentDef = getComponentDef(rootComponent)!;
+    appInjector.get(StandaloneService).setInjector(componentDef, appInjector);
+
+    const exceptionHandler: ErrorHandler|null = appInjector.get(ErrorHandler, null);
+    if (NG_DEV_MODE && !exceptionHandler) {
+      throw new RuntimeError(
+          RuntimeErrorCode.ERROR_HANDLER_NOT_FOUND,
+          'No `ErrorHandler` found in the Dependency Injection tree.');
+    }
+
+    let onErrorSubscription: Subscription;
+    ngZone.runOutsideAngular(() => {
+      onErrorSubscription = ngZone.onError.subscribe({
+        next: (error: any) => {
+          exceptionHandler!.handleError(error);
+        }
+      });
+    });
+    return _callAndReportToErrorHandler(exceptionHandler!, ngZone, () => {
+      const initStatus = appInjector.get(ApplicationInitStatus);
+      initStatus.runInitializers();
+      return initStatus.donePromise.then(() => {
+        const localeId = appInjector.get(LOCALE_ID, DEFAULT_LOCALE_ID);
+        setLocaleId(localeId || DEFAULT_LOCALE_ID);
+
+        const appRef = appInjector.get(ApplicationRef);
+        appRef.onDestroy(() => onErrorSubscription.unsubscribe());
+        appRef.bootstrap(rootComponent);
+        return appRef;
+      });
+    });
+  });
+}
+
 /**
  * Creates a factory for a platform. Can be used to provide or override `Providers` specific to
  * your application's runtime needs, such as `PLATFORM_INITIALIZER` and `PLATFORM_ID`.
@@ -242,8 +344,6 @@ export function getPlatform(): PlatformRef|null {
 
 /**
  * Provides additional options to the bootstraping process.
- *
- *
  */
 export interface BootstrapOptions {
   /**
@@ -326,10 +426,7 @@ export class PlatformRef {
     // as instantiating the module creates some providers eagerly.
     // So we create a mini parent injector that just contains the new NgZone and
     // pass that as parent to the NgModuleFactory.
-    const ngZoneOption = options ? options.ngZone : undefined;
-    const ngZoneEventCoalescing = (options && options.ngZoneEventCoalescing) || false;
-    const ngZoneRunCoalescing = (options && options.ngZoneRunCoalescing) || false;
-    const ngZone = getNgZone(ngZoneOption, {ngZoneEventCoalescing, ngZoneRunCoalescing});
+    const ngZone = getNgZone(options?.ngZone, getNgZoneOptions(options));
     const providers: StaticProvider[] = [{provide: NgZone, useValue: ngZone}];
     // Note: Create ngZoneInjector within ngZone.run so that all of the instantiated services are
     // created within the Angular zone
@@ -456,19 +553,31 @@ export class PlatformRef {
   }
 }
 
-function getNgZone(
-    ngZoneOption: NgZone|'zone.js'|'noop'|undefined,
-    extra?: {ngZoneEventCoalescing: boolean, ngZoneRunCoalescing: boolean}): NgZone {
+// Set of options recognized by the NgZone.
+interface NgZoneOptions {
+  enableLongStackTrace: boolean;
+  shouldCoalesceEventChangeDetection: boolean;
+  shouldCoalesceRunChangeDetection: boolean;
+}
+
+// Transforms a set of `BootstrapOptions` (supported by the NgModule-based bootstrap APIs) ->
+// `NgZoneOptions` that are recognized by the NgZone constructor. Passing no options will result in
+// a set of default options returned.
+function getNgZoneOptions(options?: BootstrapOptions): NgZoneOptions {
+  return {
+    enableLongStackTrace: typeof ngDevMode === 'undefined' ? false : !!ngDevMode,
+    shouldCoalesceEventChangeDetection: !!(options && options.ngZoneEventCoalescing) || false,
+    shouldCoalesceRunChangeDetection: !!(options && options.ngZoneRunCoalescing) || false,
+  };
+}
+
+function getNgZone(ngZoneToUse: NgZone|'zone.js'|'noop'|undefined, options: NgZoneOptions): NgZone {
   let ngZone: NgZone;
 
-  if (ngZoneOption === 'noop') {
+  if (ngZoneToUse === 'noop') {
     ngZone = new NoopNgZone();
   } else {
-    ngZone = (ngZoneOption === 'zone.js' ? undefined : ngZoneOption) || new NgZone({
-               enableLongStackTrace: typeof ngDevMode === 'undefined' ? false : !!ngDevMode,
-               shouldCoalesceEventChangeDetection: !!extra?.ngZoneEventCoalescing,
-               shouldCoalesceRunChangeDetection: !!extra?.ngZoneRunCoalescing
-             });
+    ngZone = (ngZoneToUse === 'zone.js' ? undefined : ngZoneToUse) || new NgZone(options);
   }
   return ngZone;
 }
@@ -815,15 +924,20 @@ export class ApplicationRef {
   bootstrap<C>(componentOrFactory: ComponentFactory<C>|Type<C>, rootSelectorOrNode?: string|any):
       ComponentRef<C> {
     NG_DEV_MODE && this.warnIfDestroyed();
+    const isComponentFactory = componentOrFactory instanceof ComponentFactory;
+
     if (!this._initStatus.done) {
-      const errorMessage = (typeof ngDevMode === 'undefined' || ngDevMode) ?
-          'Cannot bootstrap as there are still asynchronous initializers running. ' +
-              'Bootstrap components in the `ngDoBootstrap` method of the root module.' :
-          '';
-      throw new RuntimeError(RuntimeErrorCode.ASYNC_INITIALIZERS_STILL_RUNNING, errorMessage);
+      const standalone = !isComponentFactory && isStandalone(componentOrFactory);
+      const errorMessage =
+          'Cannot bootstrap as there are still asynchronous initializers running.' +
+          (standalone ? '' :
+                        ' Bootstrap components in the `ngDoBootstrap` method of the root module.');
+      throw new RuntimeError(
+          RuntimeErrorCode.ASYNC_INITIALIZERS_STILL_RUNNING, NG_DEV_MODE && errorMessage);
     }
+
     let componentFactory: ComponentFactory<C>;
-    if (componentOrFactory instanceof ComponentFactory) {
+    if (isComponentFactory) {
       componentFactory = componentOrFactory;
     } else {
       const resolver = this._injector.get(ComponentFactoryResolver);
diff --git a/packages/core/src/core_private_export.ts b/packages/core/src/core_private_export.ts
@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-export {ALLOW_MULTIPLE_PLATFORMS as ɵALLOW_MULTIPLE_PLATFORMS} from './application_ref';
+export {ALLOW_MULTIPLE_PLATFORMS as ɵALLOW_MULTIPLE_PLATFORMS, bootstrapApplication as ɵbootstrapApplication} from './application_ref';
 export {APP_ID_RANDOM_PROVIDER as ɵAPP_ID_RANDOM_PROVIDER} from './application_tokens';
 export {defaultIterableDiffers as ɵdefaultIterableDiffers, defaultKeyValueDiffers as ɵdefaultKeyValueDiffers} from './change_detection/change_detection';
 export {ChangeDetectorStatus as ɵChangeDetectorStatus, isDefaultChangeDetectionStrategy as ɵisDefaultChangeDetectionStrategy} from './change_detection/constants';
diff --git a/packages/core/src/errors.ts b/packages/core/src/errors.ts
@@ -63,7 +63,9 @@ export const enum RuntimeErrorCode {
   VIEW_ALREADY_ATTACHED = 902,
   INVALID_INHERITANCE = 903,
   UNSAFE_VALUE_IN_RESOURCE_URL = 904,
-  UNSAFE_VALUE_IN_SCRIPT = 905
+  UNSAFE_VALUE_IN_SCRIPT = 905,
+  MISSING_GENERATED_DEF = 906,
+  TYPE_IS_NOT_STANDALONE = 907,
 }
 
 /**
diff --git a/packages/core/src/render3/errors.ts b/packages/core/src/render3/errors.ts
@@ -10,12 +10,30 @@
 import {RuntimeError, RuntimeErrorCode} from '../errors';
 import {Type} from '../interface/type';
 
+import {getComponentDef} from './definition';
 import {TNode} from './interfaces/node';
 import {LView, TVIEW} from './interfaces/view';
 import {INTERPOLATION_DELIMITER} from './util/misc_utils';
 import {stringifyForError} from './util/stringify_utils';
 
-
+/** Verifies that a given type is a Standalone Component. */
+export function assertStandaloneComponentType(type: Type<unknown>) {
+  const componentDef = getComponentDef(type);
+  if (!componentDef) {
+    throw new RuntimeError(
+        RuntimeErrorCode.MISSING_GENERATED_DEF,
+        `The ${stringifyForError(type)} is not an Angular component, ` +
+            `make sure it has the \`@Component\` decorator.`);
+  }
+  if (!componentDef.standalone) {
+    throw new RuntimeError(
+        RuntimeErrorCode.TYPE_IS_NOT_STANDALONE,
+        `The ${stringifyForError(type)} component is not marked as standalone, ` +
+            `but Angular expects to have a standalone component here. ` +
+            `Please make sure the ${stringifyForError(type)} component has ` +
+            `the \`standalone: true\` flag in the decorator.`);
+  }
+}
 
 /** Called when there are multiple component selectors that match a given node */
 export function throwMultipleComponentError(
diff --git a/packages/core/src/render3/features/standalone_feature.ts b/packages/core/src/render3/features/standalone_feature.ts
@@ -18,7 +18,7 @@ import {createEnvironmentInjector} from '../ng_module_ref';
  * created on demand in case of dynamic component instantiation and contain ambient providers
  * collected from the imports graph rooted at a given standalone component.
  */
-class StandaloneService implements OnDestroy {
+export class StandaloneService implements OnDestroy {
   cachedInjectors = new Map<ComponentDef<unknown>, EnvironmentInjector|null>();
 
   constructor(private _injector: EnvironmentInjector) {}
diff --git a/packages/core/src/render3/jit/module.ts b/packages/core/src/render3/jit/module.ts
@@ -195,7 +195,7 @@ export function compileNgModuleDefs(
   });
 }
 
-function isStandalone<T>(type: Type<T>) {
+export function isStandalone<T>(type: Type<T>) {
   const def = getComponentDef(type) || getDirectiveDef(type) || getPipeDef(type);
   return def !== null ? def.standalone : false;
 }
diff --git a/packages/core/test/bundling/animations/bundle.golden_symbols.json b/packages/core/test/bundling/animations/bundle.golden_symbols.json
@@ -812,6 +812,9 @@
   {
     "name": "getDeclarationTNode"
   },
+  {
+    "name": "getDirectiveDef"
+  },
   {
     "name": "getFactoryDef"
   },
diff --git a/packages/core/test/bundling/forms_reactive/bundle.golden_symbols.json b/packages/core/test/bundling/forms_reactive/bundle.golden_symbols.json
@@ -860,6 +860,9 @@
   {
     "name": "getDeclarationTNode"
   },
+  {
+    "name": "getDirectiveDef"
+  },
   {
     "name": "getFactoryDef"
   },
diff --git a/packages/core/test/bundling/forms_template_driven/bundle.golden_symbols.json b/packages/core/test/bundling/forms_template_driven/bundle.golden_symbols.json
@@ -824,6 +824,9 @@
   {
     "name": "getDeclarationTNode"
   },
+  {
+    "name": "getDirectiveDef"
+  },
   {
     "name": "getFactoryDef"
   },
diff --git a/packages/core/test/bundling/router/bundle.golden_symbols.json b/packages/core/test/bundling/router/bundle.golden_symbols.json
@@ -1178,6 +1178,9 @@
   {
     "name": "getDeclarationTNode"
   },
+  {
+    "name": "getDirectiveDef"
+  },
   {
     "name": "getFactoryDef"
   },
diff --git a/packages/platform-browser/src/browser.ts b/packages/platform-browser/src/browser.ts
diff --git a/packages/platform-browser/src/platform-browser.ts b/packages/platform-browser/src/platform-browser.ts
diff --git a/packages/platform-browser/src/private_export.ts b/packages/platform-browser/src/private_export.ts
diff --git a/packages/platform-browser/test/browser/bootstrap_spec.ts b/packages/platform-browser/test/browser/bootstrap_spec.ts

Original file line number	Diff line number	Diff line change
`@@ -195,7 +195,7 @@ export function compileNgModuleDefs(`
`195`	`195`	`});`
`196`	`196`	`}`
`197`	`197`
`198`		`-function isStandalone<T>(type: Type<T>) {`
	`198`	`+export function isStandalone<T>(type: Type<T>) {`
`199`	`199`	`const def = getComponentDef(type) \|\| getDirectiveDef(type) \|\| getPipeDef(type);`
`200`	`200`	`return def !== null ? def.standalone : false;`
`201`	`201`	`}`
Original file line number	Diff line number	Diff line change
`@@ -812,6 +812,9 @@`
`812`	`812`	`{`
`813`	`813`	`"name": "getDeclarationTNode"`
`814`	`814`	`},`
	`815`	`+ {`
	`816`	`+ "name": "getDirectiveDef"`
	`817`	`+ },`
`815`	`818`	`{`
`816`	`819`	`"name": "getFactoryDef"`
`817`	`820`	`},`
Original file line number	Diff line number	Diff line change
`@@ -860,6 +860,9 @@`
`860`	`860`	`{`
`861`	`861`	`"name": "getDeclarationTNode"`
`862`	`862`	`},`
	`863`	`+ {`
	`864`	`+ "name": "getDirectiveDef"`
	`865`	`+ },`
`863`	`866`	`{`
`864`	`867`	`"name": "getFactoryDef"`
`865`	`868`	`},`