Manually Lazy Load Modules And Components In Angular

In Angular enterprise applications, it is often a requirement to load a configuration from a server via HTTP request which contains a UI configuration. Based on this configuration data, multiple modules and/or components need to be lazy-loaded and its routes dynamically added to the application.

In this blog post, I want to demonstrate how modules and components can be lazy-loaded at runtime using Angular 9+.

The following StackBlitz demo includes the code described in the following chapters:

The source code of the demo is available on GitHub.

Lazy Load Module Using Router

Lazy Loading: Load it when you need it

Since Angular 8 we can use the browser's built-in dynamic imports to load JavaScript modules asynchronous in Angular.

A lazy-loaded module can be defined in the routing configuration using the new import(...) syntax for loadChildren:

1@NgModule({
2  imports: [
3    RouterModule.forRoot([
4      {
5        path: 'lazy',
6        loadChildren: () => import('./lazy/lazy.module').then((m) => m.LazyModule),
7      },
8    ]),
9  ],
10})
11export class AppModule {}

::alert{type="warning} Using Angular 8 (or previous versions) you need to write loadChildren: './lazy/lazy.module#LazyModule to enable lazy loading of a module using the Angular router as it does not support the import(...) syntax. ::

Angular CLI will then automatically create a separate JavaScript bundle for this module which is only loaded from the server if the selected route gets activated.

::alert{type="warning} If you add LazyModule to any imports array of a module, it will be loaded eagerly (immediately). ::

Manually Lazy Load Module

Sometimes you want to have more control over the lazy loading process and trigger the loading process after a certain event occurred (e.g. a button press). Usually, after this event occurred, a resource is accessed asynchronous (e.g. via an HTTP call to a backend) to fetch a configuration file which includes information about the modules and/or components that should be lazy-loaded.

In my demo, I have implemented a LazyLoaderService to demonstrate that behaviour:

1@Injectable({
2  providedIn: 'root',
3})
4export class LazyLoaderService {
5  private lazyMap: Map<string, Promise<unknown>> = new Map()
6
7  constructor() {}
8
9  getLazyModule(key: string): Promise<unknown> {
10    return this.lazyMap.get(key)
11  }
12
13  loadLazyModules(): Observable<number | void> {
14    return of(1).pipe(
15      delay(2000),
16      tap(() => {
17        this.lazyMap.set(
18          'lazy',
19          import('./lazy/lazy.module').then((m) => m.LazyModule)
20        )
21      })
22    )
23  }
24}

The loadLazyModules method simulates a backend request. After a successful request, a module is registered using the import(...) syntax. If you now run the application you will see that a separate chunk for the module is created but it will not be loaded in the browser yet.

The module promise is stored in a Map with a key to be able to access it later.

We can now call this method in an onClick handler in our AppComponent and dynamically add a route to our router config:

1constructor(
2    private router: Router,
3    private lazyLoaderService: LazyLoaderService
4  ) {}
5
6  loadLazyModule(): void {
7    this.lazyLoaderService.loadLazyModules().subscribe(() => {
8      const config = this.router.config;
9      config.push({
10        path: 'lazy',
11        loadChildren: () => this.lazyLoaderService.getLazyModule('lazy')
12      });
13      this.router.resetConfig(config);
14      this.router.navigate(['lazy']);
15    });
16  }

We get the current router config from the Router via Dependency Injection and push our new routes into it.

::alert{type="warning} Be careful if you have a wildcard route (**) in your route configuration. The wildcard route always needs to be at the last index of your routes array because it matches every URL and should be selected only if no other routes are matched first. ::

Next, we need to reset the router configuration used for navigation and generating links by calling resetConfig with our new configuration that includes the lazy-loaded module route. Finally, we navigate to the new loaded route and see if it works:

We see three things happening after the "Load Lazy Module" button was clicked:

1. The chunk for the lazy module is requested from the server, a loading indicator is shown in the meantime
2. The browser URL changes to the new route /lazy after the loading has been finished
3. The lazy-loaded module is loaded and its LazyHomeComponent is rendered
4. The toolbar shows a new entry

Dynamically showing the available routes in the toolbar is done by iterating over the available routes from the router config in app.component.html:

1<mat-toolbar color="primary">
2  <mat-toolbar-row>
3    <a class="router-link" *ngFor="let route of routes" [routerLink]="route.path" routerLinkActive="active-link"
4      >{{ route.path | uppercase }}</a
5    >
6  </mat-toolbar-row>
7</mat-toolbar>

Bookmark The Lazy-Loaded Route

A typical requirement is that users want to create a bookmark for certain URLs in the application as they visit them very often. Let us try this with our current implementation:

Reloading the lazy route leads to an error: Error: Cannot match any routes. URL Segment: 'lazy'

In the current implementation, we only load the module by clicking the "Load Lazy Module" button but we also need a trigger depending on the currently activated route. Therefore, we need to add the following code block to the ngOnInit method of our AppComponent:

1ngOnInit(): void {
2    this.router.events.subscribe(async routerEvent => {
3      if (routerEvent instanceof NavigationStart) {
4        if (routerEvent.url.includes('lazy') && !this.isLazyRouteAvailable()) {
5          this.loadLazyModule(routerEvent.url);
6        }
7      }
8    });
9    this.routes = this.router.config;
10  }
11
12  private isLazyRouteAvailable(): boolean {
13    return this.router.config.filter(c => c.path === 'lazy').length > 0;
14  }

We subscribe to the NavigationStart events of the Angular router and if the URL includes our lazy route, we check if it is already inside the Router config, otherwise we load it.

Now it is possible to bookmark the URL and the application will lazy load the module after the route is activated.

Manually Load Angular Component

We can go one step further and dynamically load an Angular component in the manually lazy-loaded module.

In Angular version 2 to 8, it was quite complex to dynamically load a component, if you need a solution for one of these versions please take a look at the popular hero-loader package. Since Angular 9 it is much easier and I will describe the process for you.

Our LazyModule contains a child route with a placeholder component, that should show our dynamically loaded component:

1export const LAZY_ROUTES: Routes = [
2  {
3    path: '',
4    component: LazyHomeComponent,
5    children: [
6      {
7        path: 'dynamic-component',
8        component: PlaceholderComponent,
9      },
10    ],
11  },
12]

The template of the placeholder component consists only of a <ng-template> HTML tag:

<ng-template></ng-template>

Inside placeholder.component.ts we now dynamically load a DynamicLazyComponent after the PlaceholderComponent got initialized:

1@Component({
2  selector: 'app-placeholder',
3  templateUrl: './placeholder.component.html',
4  styleUrls: ['./placeholder.component.css'],
5})
6export class PlaceholderComponent implements OnInit {
7  @ViewChild(TemplateRef, { read: ViewContainerRef })
8  private templateViewContainerRef: ViewContainerRef
9
10  constructor(private readonly componentFactoryResolver: ComponentFactoryResolver) {}
11
12  async ngOnInit() {
13    import('../../dynamic-lazy/dynamic-lazy.component').then(({ DynamicLazyComponent }) => {
14      const component = this.componentFactoryResolver.resolveComponentFactory(DynamicLazyComponent)
15      const componentRef = this.templateViewContainerRef.createComponent(component)
16    })
17  }
18}

Some notes to this code block:

• We use the @ViewChild() decorator to be able to query the TemplateRef instance of our <ng-template> element.
• The optional second argument of the @ViewChild() decorator ({ read: ViewContainerRef }) is used to read the ViewContainerRef instance from the view query.
• The templateViewContainerRef is used to tell the rendering engine where the lazy-loaded component should be rendered.
• We use the same import(...) syntax to lazy-load components the same way we did it for modules.

::alert{type="warning} Since Angular 9, we do not need to register and add the DynamicLazyComponent inside any module as an entry component. If you want to dynamically load a component in Angular 8, please check out Manually Lazy load Components in Angular 8 ::

The following picture demonstrates the lazy loading process of this component:

Conclusion

Angular 9 provides a very clean and elegant solution to manually import modules and components at runtime using the import(...) syntax.

You should now be able to create very dynamic user interfaces, that can be configured in configuration files that are loaded at runtime and based on this information different modules and components are lazy-loaded with new routes.