Angular 22 Upgrade Guide: What Changed and How to Fix Common Issues

# Verify Node version
node -v  # Must be >= 22.0.0

# Update TypeScript in devDependencies
npm install -D typescript@6

{
  "engines": {
    "node": ">=22.0.0"
  },
  "devDependencies": {
    "typescript": "^6.0.0"
  }
}

// Deprecated
constructor(private resolver: ComponentFactoryResolver) {}

loadMetricPanel() {
  const factory = this.resolver.resolveComponentFactory(MetricPanelComponent);
  this.container.createComponent(factory);
}

// Angular 22
import { ViewContainerRef, ComponentRef } from '@angular/core';

export class DashboardHostComponent {
  private container = inject(ViewContainerRef);
  private panelRef: ComponentRef<MetricPanelComponent> | null = null;

  loadMetricPanel() {
    // Direct creation; no factory resolution needed
    this.panelRef = this.container.createComponent(MetricPanelComponent);
    
    // Optional: Pass inputs immediately
    this.panelRef.setInput('metricId', 'cpu_usage_01');
  }
}

rmance management.

Implementation:

import { ChangeDetectionStrategy, Component } from '@angular/core';

@Component({
  selector: 'app-live-chart',
  template: `...`,
  // Renamed from Default to Eager
  changeDetection: ChangeDetectionStrategy.Eager 
})
export class LiveChartComponent {}

Best Practice: For data-intensive components like charts or tables, migrate to OnPush. This reduces change detection cycles by only checking the component when input references change.

@Component({
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class OptimizedTableComponent {
  // Ensure inputs are immutable or use signals
  @Input() set data(value: Metric[]) {
    this._data = value;
    this.changeDetectorRef.markForCheck();
  }
}

4. Router Configuration and Guards

Angular 22 removes provideRoutes in favor of provideRouter. Additionally, the default parameter inheritance strategy changes to always, and CanMatchFn guards require an updated signature.

Router Provider:

// Angular 22
import { provideRouter } from '@angular/router';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter([
      { path: 'metrics', component: MetricsComponent },
      { path: 'settings', component: SettingsComponent }
    ])
  ]
};

Parameter Inheritance Strategy: If your application relies on the previous behavior where child routes only inherited parameters when the parent had no path parameters, you must explicitly configure this.

provideRouter(routes, {
  // Restore legacy behavior if needed
  paramsInheritanceStrategy: 'emptyOnly' 
})

Guard Signature Update: CanMatchFn now receives the currentSnapshot as the third argument.

import { CanMatchFn, Route, UrlSegment, ActivatedRouteSnapshot } from '@angular/router';

export const authGuard: CanMatchFn = (
  route: Route, 
  segments: UrlSegment[], 
  currentSnapshot: ActivatedRouteSnapshot // New argument
) => {
  const isAuthenticated = checkAuth(currentSnapshot);
  return isAuthenticated;
};

5. HTTP Client and Fetch API

Angular 22 switches the internal HTTP engine to the Fetch API. The provideHttpClient() function remains the entry point, but the underlying transport changes.

Implementation:

import { provideHttpClient } from '@angular/common/http';

export const appConfig: ApplicationConfig = {
  providers: [provideHttpClient()]
};

Critical Note on File Uploads: The Fetch API does not support upload.progress events in the same way XHR does. If your application tracks file upload progress, you may need to implement a custom interceptor or use XMLHttpRequest directly for those specific requests until the Angular team provides a Fetch-compatible progress solution.

6. Template Strictness

The template compiler now enforces strict rules for attribute bindings. data-* attributes must use the attr. prefix.

Legacy Pattern:

<!-- Angular 21: This worked but is now invalid -->
<div [data-tracking-id]="metric.id"></div>

Modern Pattern:

<!-- Angular 22: Use attr. prefix -->
<div [attr.data-tracking-id]="metric.id"></div>

Duplicate input bindings are also flagged as errors. Ensure each input is bound only once per element.

Pitfall Guide

1. Node.js Version Mismatch

   • Explanation: Angular 22 requires Node 22+. Building with Node 20 or 21 will cause CLI errors or unexpected compilation failures.
   • Fix: Use nvm to switch to Node 22 and verify with node -v before running any Angular commands.

2. Router Parameter Pollution

   • Explanation: With paramsInheritanceStrategy defaulting to always, child routes may receive parent parameters they don't expect. This can cause data services to fetch incorrect data based on stale or irrelevant IDs.
   • Fix: Audit nested routes. If the new behavior breaks your logic, explicitly set paramsInheritanceStrategy: 'emptyOnly' in provideRouter.

3. Fetch Upload Progress Failure

   • Explanation: Code relying on HttpEventType.UploadProgress may stop emitting events because Fetch lacks native upload progress support.
   • Fix: For file uploads, consider using XMLHttpRequest directly or check for community polyfills. Monitor Angular release notes for Fetch progress support updates.

4. data-* Binding Breakage

   • Explanation: Templates using [data-id] will fail compilation or render incorrectly. The compiler no longer treats these as property bindings.
   • Fix: Perform a global search for [data- and replace with [attr.data-.

5. Stale Change Detection Enums

   • Explanation: References to ChangeDetectionStrategy.Default will cause compilation errors due to the rename to Eager.
   • Fix: Run a global replace for ChangeDetectionStrategy.Default to ChangeDetectionStrategy.Eager. Consider migrating to OnPush for performance gains.

6. CanMatchFn Signature Mismatch

   • Explanation: Route guards using CanMatchFn will fail type checking if they do not accept the currentSnapshot parameter.
   • Fix: Update all guard functions to include the third argument: (route, segments, snapshot) => boolean.

7. Lingering ComponentFactoryResolver Imports

   • Explanation: Code that imports ComponentFactoryResolver will fail to compile as the class is removed.
   • Fix: Remove all imports of ComponentFactoryResolver and ComponentFactory. Refactor dynamic component creation to use viewContainerRef.createComponent().

Production Bundle

Action Checklist

• Environment Audit: Verify Node.js ≥ 22 and TypeScript ≥ 6 are installed and configured.
• CLI Update: Run ng update @angular/core@22 @angular/cli@22 to apply automated migrations.
• Dynamic Components: Search for ComponentFactoryResolver and refactor to direct createComponent calls.
• Router Audit: Check provideRouter usage and verify paramsInheritanceStrategy behavior for nested routes.
• Guard Update: Update all CanMatchFn signatures to include currentSnapshot.
• Template Scan: Fix all [data-*] bindings to use [attr.data-*] and resolve duplicate input errors.
• HTTP Testing: Validate file upload workflows; implement workarounds for progress events if necessary.
• Change Detection: Replace ChangeDetectionStrategy.Default with Eager or OnPush.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Legacy Nested Routes	paramsInheritanceStrategy: 'emptyOnly'	Prevents unexpected parameter leakage in complex route trees.	Low; config change only.
New Micro-frontend	paramsInheritanceStrategy: 'always'	Simplifies parameter passing; aligns with modern routing patterns.	None; default behavior.
High-Frequency Data UI	ChangeDetectionStrategy.OnPush	Reduces change detection cycles; improves rendering performance.	Medium; requires immutable data patterns.
Simple Static UI	ChangeDetectionStrategy.Eager	Minimal refactoring; maintains existing behavior with renamed enum.	Low; rename only.
File Upload Critical	Custom XHR Interceptor	Fetch API lacks progress events; XHR ensures reliability.	High; requires custom implementation.

Configuration Template

Use this template for app.config.ts to ensure correct provider setup in Angular 22.

import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
import { provideRouter, withComponentInputBinding } from '@angular/router';
import { provideHttpClient, withFetch } from '@angular/common/http';

import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideZoneChangeDetection({ eventCoalescing: true }),
    provideRouter(routes, withComponentInputBinding()),
    // Fetch is default in Angular 22, but explicit declaration is clear
    provideHttpClient(withFetch())
  ]
};

Quick Start Guide

1. Upgrade Node: Run nvm install 22 and nvm use 22.
2. Update TypeScript: Execute npm install -D typescript@6.
3. Run Migration: Execute ng update @angular/core@22 @angular/cli@22.
4. Fix Templates: Run ng build and resolve any data-* or duplicate binding errors.
5. Verify Runtime: Test router navigation and HTTP requests to ensure behavioral changes are handled.