How to Successfully Upgrade Angular 16 to 17: Handling Legacy Angular Material Components

Upgrading Angular Applications: Angular 16 to Angular 17

Upgrading Angular applications to the latest version can sometimes be straightforward, but certain dependencies and legacy code can introduce challenges. In this blog, I’ll share my experience upgrading an Angular 16 project to Angular 17, focusing especially on the migration of Angular Material legacy components.

Prerequisites for Angular 17 Upgrade

Before starting the upgrade, ensure your environment meets the following requirements as per the official Angular update guide (angular.dev/update-guide):

• Node.js: Angular 17 supports Node.js version 18.13.0 or newer.
• TypeScript: Angular 17 requires TypeScript 5.2 or later.
• Zone.js: Angular 17 supports Zone.js version 0.14.x or later.

Make sure to update these dependencies before proceeding.

Step 1: Upgrade Angular Core and CLI

Run the following command to update Angular core and CLI to version 17:

ng update @angular/core@17 @angular/cli@17

This step should complete successfully without issues.

Step 2: Upgrade Angular Material and Handle Legacy Components

When upgrading Angular Material, you might encounter this error:

Cannot update to Angular Material v17 because the project is using the legacy Material components that have been deleted. While Angular Material v16 is compatible with Angular v17, it is recommended to switch away from the legacy components as soon as possible because they no longer receive bug fixes, accessibility improvements, and new features.

Read more about migrating away from legacy components: Migrating to MDC-based Angular Material Components

This happens because Angular Material v17 removes support for legacy components. To migrate, you need to run the MDC migration schematic:

ng generate @angular/material:mdc-migration

Common Issue: Partial Migration

In some cases, running the migration command only updates a single file (e.g., src/_common.scss) and leaves the rest of the legacy components unchanged.

How to Fix Partial Migration Issue

To ensure a complete migration, follow these steps:

1. Create a new Git branch to start the upgrade process fresh.
2. Run the MDC migration command before upgrading Angular Material:

   ng generate @angular/material:mdc-migration

3. The migration tool will prompt you with options:
   Limit the migration to a specific directory? (Enter the relative path such as src/app/shared or leave blank for all directories) Leave blank to migrate the entire project.
4. Then it will ask which components you want to migrate:
   What components do you want to migrate? Button, Card, Checkbox, Chips, Dialog, Form Field, Input, Select, Autocomplete, List, Menu, Paginator, Progress Bar, Progress Spinner, Radio, Slide Toggle, Slider, Snack Bar, Table, Tabs, Tooltip
   Select all components or the ones relevant to your project.
5. The migration will then run and update all legacy components across your project.

Step 3: Proceed with Angular Material Upgrade

After completing the migration, you can now safely upgrade Angular Material:

ng update @angular/material@17

This time, the update should complete successfully without errors.

Summary

• Verify Node.js, TypeScript, and Zone.js versions before upgrading.
• Upgrade Angular core and CLI first.
• Run the MDC migration schematic before upgrading Angular Material to avoid legacy component errors.
• If migration only partially updates your project, start fresh on a new branch and run the migration with full prompts.
• Finally, upgrade Angular Material to version 17.

Following these steps will help you smoothly upgrade your Angular project from version 16 to 17 while handling legacy Angular Material components effectively.

Thanks for reading! Feel free to share your experiences or ask questions in the comments.

Source: Read More