Module Import Changes in Angular Material 9.x.x: From @angular/material to Secondary Entry Points

Introduction

In the Angular ecosystem, Angular Material is a widely used UI component library that provides rich Material Design components for developers. However, with version updates, Angular Material 9.x.x introduced a significant breaking change, causing many developers to encounter errors during project builds. Specifically, the error message often appears as: app/modules/admin-module/pages/editor/editor.component.ts:6:27 - error TS2306: File ...node_modules/@angular/material/index.d.ts' is not a module. This error stems from changes in module import methods, and this article will delve into the background, reasons, and solutions for this change.

Problem Analysis

Prior to Angular Material 9.x.x, developers typically imported modules via the main entry point @angular/material, for example: import { MatDialogModule } from "@angular/material";. This approach simplified the import process but could lead to performance issues, especially in large applications. Starting from Angular Material 9.x.x, the official support for the main entry point was removed, requiring imports via secondary entry points, such as import { MatDialogModule } from "@angular/material/dialog";. This change is documented as a breaking change in the official changelog, aiming to improve tree-shaking optimization efficiency.

Tree-shaking is a build-time technique used to remove unused code, thereby reducing application bundle size. In older versions, importing all modules via the main entry point might prevent build tools from accurately identifying which components are actually used, leading to the inclusion of the entire library in the final bundle. By enforcing secondary entry points, each module can be imported independently, allowing build tools to perform tree-shaking more precisely and eliminate unnecessary code. For instance, if an application only uses button and dialog components, the build will only include these two modules, not the entire Angular Material library.

Solutions

To address this change, developers can adopt multiple solutions. First, the most direct method is to update all import statements from the main entry point to secondary entry points. For example, replace import { MatButtonModule } from "@angular/material"; with import { MatButtonModule } from "@angular/material/button";. This requires traversing all relevant files in the project to ensure each import points to the correct path. Below is a code snippet example demonstrating how to update imports:

// Old import method (Angular Material 8.x.x and earlier)
import { MatDialogModule } from "@angular/material";

// New import method (Angular Material 9.x.x and later)
import { MatDialogModule } from "@angular/material/dialog";

Second, developers can consider using shared modules to organize imports. For example, create a MaterialModule that centrally imports and exports all required Angular Material modules, then import this shared module in other modules. This approach can improve code maintainability, but note that overusing shared modules may impact tree-shaking effectiveness. Based on community feedback, in some cases, using shared modules can lead to increased bundle sizes because build tools might not fully remove unused components. Therefore, it is recommended to weigh the use of shared modules versus direct imports of individual modules based on project needs.

Below is an example code for a MaterialModule, showing how to import and export multiple Angular Material modules:

import { NgModule } from "@angular/core";
import { MatButtonModule } from "@angular/material/button";
import { MatDialogModule } from "@angular/material/dialog";
import { MatInputModule } from "@angular/material/input";

@NgModule({
    imports: [
        MatButtonModule,
        MatDialogModule,
        MatInputModule
    ],
    exports: [
        MatButtonModule,
        MatDialogModule,
        MatInputModule
    ]
})
export class MaterialModule {}

If a project cannot migrate to the new version immediately, downgrading to an older version (e.g., Angular Material 7.3.2) can serve as a temporary solution. However, this is not recommended as a long-term strategy, as older versions may lack security updates and new features. When downgrading, ensure compatibility with other Angular libraries to avoid introducing additional errors.

Real-World Cases and Performance Impact

In practical projects, this change has a significant impact on performance. For example, a developer reported that after replacing a shared module with direct imports of individual modules, the build bundle size decreased by approximately 200KB. This highlights the potential of tree-shaking in reducing application size. However, it also reminds developers that build tool optimizations may not be perfect, requiring manual adjustments to import strategies for optimal results.

To further illustrate, consider an Angular application using lazy-loaded feature modules. If each feature module imports a shared module containing all Angular Material components, build tools might not distinguish which components are used in specific modules, leading to all components being included in the final bundle. Conversely, if each feature module only imports the components it actually needs, build tools can perform tree-shaking more effectively. Below is an example code for lazy-loaded modules:

// Feature module A, only uses button component
import { NgModule } from "@angular/core";
import { MatButtonModule } from "@angular/material/button";

@NgModule({
    imports: [MatButtonModule],
    exports: [MatButtonModule]
})
export class FeatureAModule {}

// Feature module B, only uses dialog component
import { NgModule } from "@angular/core";
import { MatDialogModule } from "@angular/material/dialog";

@NgModule({
    imports: [MatDialogModule],
    exports: [MatDialogModule]
})
export class FeatureBModule {}

Conclusion

The module import change in Angular Material 9.x.x aims to improve tree-shaking efficiency and reduce application bundle size. Developers should update import paths to secondary entry points and choose between using shared modules or direct imports based on project needs. Although this change incurs initial migration costs, in the long run, it enhances application performance. It is advisable to refer to official documentation and community resources to ensure a smooth transition. In the future, as the Angular ecosystem evolves, similar optimizations may continue to emerge, and developers should stay informed to maintain project health.