Upgrading an Angular application to a new major version can feel daunting, but the Angular team consistently strives to make the process as smooth as possible with robust ng update schematics. Angular v21 introduces significant internal changes (like zoneless change detection and Vitest), but many are handled automatically or are opt-in.

This chapter provides a comprehensive checklist and best practices for migrating your existing Angular application to v21.

Step 1: Prepare for Migration

Before you even touch the ng update command, it’s crucial to prepare your project:

  1. Backup Your Project: Always create a backup of your project before performing any major upgrade. You can commit your current state to Git or make a direct copy.
    git commit -am "Pre-Angular v21 Update Snapshot"
# Or simply: git checkout -b pre-angular-v21-update
  2. Ensure Current Version Compatibility: Make sure your application is on a compatible version to upgrade to v21. Generally, you should upgrade one major version at a time (e.g., v19 -> v20 -> v21). If you’re on a much older version, follow the official Angular Update Guide for incremental upgrades.
    ng version
    (Check if you’re on v20.x.x. If not, upgrade to v20 first).
  3. Update Node.js & npm/yarn: Ensure you’re using Node.js and npm/yarn versions compatible with Angular v21. Check the official Angular documentation for current requirements.
    node -v
npm -v
  4. Clean node_modules: Remove node_modules and package-lock.json (or yarn.lock) to ensure a fresh install of dependencies.
    rm -rf node_modules package-lock.json
npm install
# Or with yarn: rm -rf node_modules yarn.lock && yarn install
  5. Run All Tests: Ensure all your existing unit and end-to-end tests pass before the upgrade. This provides a baseline to quickly identify issues introduced by the update.
    ng test
ng e2e # if you have e2e tests configured
  6. Check for Deprecated APIs: Review your code for any deprecated APIs from previous versions that might be removed in v21. The Angular CLI usually provides warnings for these during development.

It’s often helpful to update your global Angular CLI to the latest major version before updating the project:

npm uninstall -g @angular/cli
npm install -g @angular/cli@next # Installs the latest v21 CLI

Step 3: Run the Angular Update Command

This is the core of the migration. The ng update command will analyze your project, update Angular packages, and run schematics to apply common code migrations.

cd your-project-folder
ng update @angular/core@21 @angular/cli@21

What happens during ng update:

  • Package Updates: @angular/core, @angular/cli, and other official Angular packages (@angular/common, @angular/router, @angular/forms, etc.) are updated to v21.
  • Automated Migrations: The CLI runs scripts to automatically:
    • Adjust app.config.ts (or AppModule) for new features.
    • If you had Zone.js, it might add provideZoneChangeDetection() to keep your app working. (Your goal is to remove this later!).
    • Update RxJS imports/operators if necessary.
    • Apply control flow migrations (*ngIf to @if) if you hadn’t done it manually in v17+.
    • Potentially migrate some CommonModule imports to standalone.
    • (New in v21) Optionally migrate NgClass to class bindings and NgStyle to style bindings.

Step 4: Address Post-Update Tasks and Manual Review

After ng update completes, there are typically a few things to check and potentially do manually:

  1. Review ng update Output: The CLI provides valuable output, highlighting any potential issues, warnings, or manual steps required. Read this carefully.
  2. Install Third-Party Updates: Update any third-party Angular libraries (e.g., Angular Material, NgRx, PrimeNG, etc.) to their v21 compatible versions. Check their official documentation for compatibility and migration guides.
    ng update @angular/material@21 @angular/cdk@21
# Repeat for other @angular/* libraries and major third-party libraries
npm install # Or yarn install after updating package.json dependencies
  3. Run ng serve and ng build --configuration production:
    • Start your development server (ng serve) and manually test your application. Check the browser console for any runtime errors or warnings.
    • Perform a production build to check for build errors and bundle size changes.
  4. Run Tests Again: Rerun all your unit and e2e tests.
    ng test
ng e2e
    • Vitest Transition: If you were on Karma/Jasmine, ng update typically won’t automatically switch you to Vitest. Your tests should still run. If you want to switch to Vitest, this will be a separate, manual migration effort (as discussed in Chapter 7).
    • Zone.js Removal: If ng update added provideZoneChangeDetection(), start gradually removing Zone.js dependencies (from polyfills.ts and angular.json) and the provideZoneChangeDetection() call itself. Test each step. This is where you fully embrace zoneless.
    • fixture.detectChanges() in Tests: In zoneless tests, replace explicit fixture.detectChanges() after async operations with await fixture.whenStable() if you were relying on Zone.js for auto-detection.
  5. Review Breaking Changes: Consult the official Angular CHANGELOG and breaking changes documentation for v21. Be aware of any changes that ng update couldn’t handle automatically.
  6. Adopt New Features Gradually:
    • Safe to Adopt Immediately: HttpClient by default (no code changes needed if already using it), enhanced template syntax (direct bindings), build optimizations (automatic).
    • Test Carefully: Zoneless change detection (after removing provideZoneChangeDetection()), AI tools (experiment in non-critical areas).
    • Wait for Stable: Signal Forms (still experimental).
  7. Review Optional Migrations (v21 specific):
    # Run these if you want to apply recommended style migrations
ng generate @angular/core:ngclass-to-class-migration
ng generate @angular/core:ngstyle-to-style-migration
ng generate @angular/core:common-to-standalone # For breaking up CommonModule imports
    Review the changes these migrations make carefully.

Common Migration Gotchas & Troubleshooting

  • Third-Party Library Incompatibility: The most common issue. Always update them and check their release notes. If an important library isn’t updated, you might need to wait or find an alternative.
  • Zone.js-Dependent Libraries: Some older libraries (e.g., certain animation libraries, datepickers) might implicitly rely on Zone.js. If you go fully zoneless and encounter issues, you might need to use markForCheck() or, as a last resort, temporarily keep provideZoneChangeDetection().
  • Polyfills: Ensure your polyfills.ts file still includes necessary polyfills for your target browsers, especially if you removed zone.js.
  • Strict Mode Issues: If you’re enabling stricter TypeScript configurations, you might encounter new compilation errors. Address them using TypeScript best practices.
  • CSS Global Leakage (if switching to ShadowDom or ExperimentalIsolatedShadowDom): If you’re experimenting with new encapsulation strategies, be aware of how they might affect global styles.

Summary/Key Takeaways

  • Preparation is Key: Backup, update dependencies, and run tests before upgrading.
  • The ng update @angular/core@21 @angular/cli@21 command automates most of the migration process.
  • Review CLI output and manually update third-party libraries.
  • Run all tests after migration to catch regressions.
  • Gradually adopt new features, starting with those that are immediately beneficial and stable.
  • Be deliberate about transitioning to fully zoneless, testing at each step of removing Zone.js dependencies.
  • Leverage the new optional migration scripts for NgClass/NgStyle and CommonModule.

Migration to Angular v21 is generally smooth thanks to the robust tooling. By following this checklist and understanding the new features, you can confidently bring your applications to the cutting edge of Angular development.