feat(router): deprecate loadChildren:string (#30073)

alxhub · AndrewKushnir · commit c61df3932376 · 2019-04-24T17:06:05.000-07:00
The proposed ES dynamic import() is now supported by the Angular CLI and the larger toolchain. This renders the `loadChildren: string` API largely redundant, as import() is far more natural, is less error-prone, and is standards compliant. This commit deprecates the `string` form of `loadChildren` in favor of dynamic import(). DEPRECATION: When defining lazy-loaded route, Angular previously offered two options for configuring the module to be loaded, both via the `loadChildren` parameter of the route. Most Angular developers are familiar withthe `string` form of this API. For example, the following route definition configures Angular to load a `LazyModule` NgModule from `lazy-route/lazy.module.ts`: ``` [{ path: 'lazy', loadChildren: 'lazy-route/lazy.module#LazyModule', }] ``` This "magic string" configuration was previously necessary as there was no dynamic module loading standard on the web. This has changed with the pending standardization of dynamic `import()` expressions, which are now supported in the Angular CLI and in web tooling in general. `import()` offers a more natural and robust solution to dynamic module loading. The above example can be rewritten to use dynamic `import()`: ``` [{ path: 'lazy', loadChildren: () => import('./lazy-route/lazy.module').then(mod => mod.LazyModule), }] ``` This form of lazy loading offers significant advantages in terms of: * type checking via TypeScript * simplicity of generated code * future potential to run natively in supporting browsers (see: [caniuse: dynamic import()](https://caniuse.com/#feat=es6-module-dynamic-import)) As a result, Angular is deprecating the `loadChildren: string` syntax in favor of ES dynamic `import()`. An automatic migration will run during `ng upgrade` to convert your existing Angular code to the new syntax. PR Close #30073
diff --git a/packages/core/src/linker/ng_module_factory_loader.ts b/packages/core/src/linker/ng_module_factory_loader.ts
@@ -17,6 +17,8 @@ import {NgModuleFactory} from './ng_module_factory';
  * Used to load ng module factories.
  *
  * @publicApi
+ * @deprecated the `string` form of `loadChildren` is deprecated, and `NgModuleFactoryLoader` is
+ * part of its implementation. See `LoadChildren` for more details.
  */
 export abstract class NgModuleFactoryLoader {
   abstract load(path: string): Promise<NgModuleFactory<any>>;
diff --git a/packages/core/src/linker/system_js_ng_module_factory_loader.ts b/packages/core/src/linker/system_js_ng_module_factory_loader.ts
@@ -24,6 +24,8 @@ declare var System: any;
  * token.
  *
  * @publicApi
+ * @deprecated the `string` form of `loadChildren` is deprecated, and `SystemJsNgModuleLoaderConfig`
+ * is part of its implementation. See `LoadChildren` for more details.
  */
 export abstract class SystemJsNgModuleLoaderConfig {
   /**
@@ -47,6 +49,8 @@ const DEFAULT_CONFIG: SystemJsNgModuleLoaderConfig = {
 /**
  * NgModuleFactoryLoader that uses SystemJS to load NgModuleFactory
  * @publicApi
+ * @deprecated the `string` form of `loadChildren` is deprecated, and `SystemJsNgModuleLoader` is
+ * part of its implementation. See `LoadChildren` for more details.
  */
 @Injectable()
 export class SystemJsNgModuleLoader implements NgModuleFactoryLoader {
diff --git a/packages/router/src/config.ts b/packages/router/src/config.ts
@@ -93,6 +93,18 @@ export type ResolveData = {
 /**
  *
  * A function that is called to resolve a collection of lazy-loaded routes.
+ * 
+ * Often this function will be implemented using an ES dynamic `import()` expression. For example:
+ * 
+ * ```
+ * [{
+ *   path: 'lazy',
+ *   loadChildren: () => import('./lazy-route/lazy.module').then(mod => mod.LazyModule),
+ * }];
+ * ```
+ * 
+ * This function _must_ match the form above: an arrow function of the form
+ * `() => import('...').then(mod => mod.MODULE)`.
  *
  * @see `Route#loadChildren`.
  * @publicApi
@@ -105,10 +117,24 @@ export type LoadChildrenCallback = () => Type<any>| NgModuleFactory<any>| Observ
  * A string of the form `path/to/file#exportName` that acts as a URL for a set of routes to load,
  * or a function that returns such a set.
  *
+ * The string form of `LoadChildren` is deprecated (see `DeprecatedLoadChildren`). The function
+ * form (`LoadChildrenCallback`) should be used instead.
+ *
  * @see `Route#loadChildren`.
  * @publicApi
  */
-export type LoadChildren = string | LoadChildrenCallback;
+export type LoadChildren = LoadChildrenCallback | DeprecatedLoadChildren;
+
+/**
+ * A string of the form `path/to/file#exportName` that acts as a URL for a set of routes to load.
+ *
+ * @see `Route#loadChildren`
+ * @publicApi
+ * @deprecated the `string` form of `loadChildren` is deprecated in favor of the proposed ES dynamic
+ * `import()` expression, which offers a more natural and standards-based mechanism to dynamically
+ * load an ES module at runtime.
+ */
+export type DeprecatedLoadChildren = string;
 
 /**
  *
diff --git a/packages/router/src/index.ts b/packages/router/src/index.ts
@@ -7,7 +7,7 @@
  */
 
 
-export {Data, LoadChildren, LoadChildrenCallback, ResolveData, Route, Routes, RunGuardsAndResolvers, UrlMatchResult, UrlMatcher} from './config';
+export {Data, DeprecatedLoadChildren, LoadChildren, LoadChildrenCallback, ResolveData, Route, Routes, RunGuardsAndResolvers, UrlMatchResult, UrlMatcher} from './config';
 export {RouterLink, RouterLinkWithHref} from './directives/router_link';
 export {RouterLinkActive} from './directives/router_link_active';
 export {RouterOutlet} from './directives/router_outlet';
diff --git a/tools/public_api_guard/core/core.d.ts b/tools/public_api_guard/core/core.d.ts
@@ -586,6 +586,7 @@ export declare abstract class NgModuleFactory<T> {
     abstract create(parentInjector: Injector | null): NgModuleRef<T>;
 }
 
+/** @deprecated */
 export declare abstract class NgModuleFactoryLoader {
     abstract load(path: string): Promise<NgModuleFactory<any>>;
 }
@@ -1297,11 +1298,13 @@ export interface SkipSelfDecorator {
 
 export declare type StaticProvider = ValueProvider | ExistingProvider | StaticClassProvider | ConstructorProvider | FactoryProvider | any[];
 
+/** @deprecated */
 export declare class SystemJsNgModuleLoader implements NgModuleFactoryLoader {
     constructor(_compiler: Compiler, config?: SystemJsNgModuleLoaderConfig);
     load(path: string): Promise<NgModuleFactory<any>>;
 }
 
+/** @deprecated */
 export declare abstract class SystemJsNgModuleLoaderConfig {
     factoryPathPrefix: string;
     factoryPathSuffix: string;
diff --git a/tools/public_api_guard/router/router.d.ts b/tools/public_api_guard/router/router.d.ts
@@ -101,6 +101,9 @@ export declare class DefaultUrlSerializer implements UrlSerializer {
     serialize(tree: UrlTree): string;
 }
 
+/** @deprecated */
+export declare type DeprecatedLoadChildren = string;
+
 export declare type DetachedRouteHandle = {};
 
 export declare type Event = RouterEvent | RouteConfigLoadStart | RouteConfigLoadEnd | ChildActivationStart | ChildActivationEnd | ActivationStart | ActivationEnd | Scroll;
@@ -145,7 +148,7 @@ export declare class GuardsCheckStart extends RouterEvent {
     toString(): string;
 }
 
-export declare type LoadChildren = string | LoadChildrenCallback;
+export declare type LoadChildren = LoadChildrenCallback | DeprecatedLoadChildren;
 
 export declare type LoadChildrenCallback = () => Type<any> | NgModuleFactory<any> | Observable<Type<any>> | Promise<NgModuleFactory<any> | Type<any> | any>;
 

Original file line number	Diff line number	Diff line change
`@@ -17,6 +17,8 @@ import {NgModuleFactory} from './ng_module_factory';`
`17`	`17`	`* Used to load ng module factories.`
`18`	`18`	`*`
`19`	`19`	`* @publicApi`
	`20`	+ * @deprecated the `string` form of `loadChildren` is deprecated, and `NgModuleFactoryLoader` is
	`21`	+ * part of its implementation. See `LoadChildren` for more details.
`20`	`22`	`*/`
`21`	`23`	`export abstract class NgModuleFactoryLoader {`
`22`	`24`	`abstract load(path: string): Promise<NgModuleFactory<any>>;`
Original file line number	Diff line number	Diff line change
`@@ -586,6 +586,7 @@ export declare abstract class NgModuleFactory<T> {`
`586`	`586`	`abstract create(parentInjector: Injector \| null): NgModuleRef<T>;`
`587`	`587`	`}`
`588`	`588`
	`589`	`+/** @deprecated */`
`589`	`590`	`export declare abstract class NgModuleFactoryLoader {`
`590`	`591`	`abstract load(path: string): Promise<NgModuleFactory<any>>;`
`591`	`592`	`}`
`@@ -1297,11 +1298,13 @@ export interface SkipSelfDecorator {`
`1297`	`1298`
`1298`	`1299`	`export declare type StaticProvider = ValueProvider \| ExistingProvider \| StaticClassProvider \| ConstructorProvider \| FactoryProvider \| any[];`
`1299`	`1300`
	`1301`	`+/** @deprecated */`
`1300`	`1302`	`export declare class SystemJsNgModuleLoader implements NgModuleFactoryLoader {`
`1301`	`1303`	`constructor(_compiler: Compiler, config?: SystemJsNgModuleLoaderConfig);`
`1302`	`1304`	`load(path: string): Promise<NgModuleFactory<any>>;`
`1303`	`1305`	`}`
`1304`	`1306`
	`1307`	`+/** @deprecated */`
`1305`	`1308`	`export declare abstract class SystemJsNgModuleLoaderConfig {`
`1306`	`1309`	`factoryPathPrefix: string;`
`1307`	`1310`	`factoryPathSuffix: string;`
Original file line number	Diff line number	Diff line change
`@@ -101,6 +101,9 @@ export declare class DefaultUrlSerializer implements UrlSerializer {`
`101`	`101`	`serialize(tree: UrlTree): string;`
`102`	`102`	`}`
`103`	`103`
	`104`	`+/** @deprecated */`
	`105`	`+export declare type DeprecatedLoadChildren = string;`
	`106`	`+`
`104`	`107`	`export declare type DetachedRouteHandle = {};`
`105`	`108`
`106`	`109`	`export declare type Event = RouterEvent \| RouteConfigLoadStart \| RouteConfigLoadEnd \| ChildActivationStart \| ChildActivationEnd \| ActivationStart \| ActivationEnd \| Scroll;`
`@@ -145,7 +148,7 @@ export declare class GuardsCheckStart extends RouterEvent {`
`145`	`148`	`toString(): string;`
`146`	`149`	`}`
`147`	`150`
`148`		`-export declare type LoadChildren = string \| LoadChildrenCallback;`
	`151`	`+export declare type LoadChildren = LoadChildrenCallback \| DeprecatedLoadChildren;`
`149`	`152`
`150`	`153`	`export declare type LoadChildrenCallback = () => Type<any> \| NgModuleFactory<any> \| Observable<Type<any>> \| Promise<NgModuleFactory<any> \| Type<any> \| any>;`
`151`	`154`