Angular 22.1.3: what changed and what to do

Angular 22.1.3: Upgrade Verdict

Angular 22.1.3 addresses a critical regression in NgOptimizedImage that affected Largest Contentful Paint (LCP) metrics. Previously, images loaded via ngSrc could experience delayed loading on Safari 17.x and Firefox 120+, leading to lower Lighthouse scores. This patch resolves the underlying race condition in the image preloader.

Applications using NgOptimizedImage and targeting strong Web Vitals performance are directly affected. Teams monitoring LCP on these browsers should see improvements after updating. This fix specifically targets an issue introduced in Angular 22.1.0.

The release also includes a fix for the Router’s queryParamsHandling: 'merge' strategy. In certain scenarios involving multiple navigation calls in quick succession, query parameters were incorrectly overwritten instead of merged. This occurred when navigating from a route with existing query parameters to a new route that also specified parameters to be merged.

Teams relying on queryParamsHandling: 'merge' for complex navigation flows, particularly those with dynamic query parameter updates, will benefit from this stability improvement. The fix ensures consistent behavior as documented, preventing unexpected parameter loss.

A minor performance enhancement for Ahead-of-Time (AOT) compilation is also part of this update. Build times for projects with over 500 components can see a marginal reduction, typically 0.5-1.5% depending on hardware and project structure. This improvement is a result of optimizing internal dependency graph processing during the compilation phase.

This change primarily benefits developers working on large enterprise applications, where even small reductions in build times can accumulate over daily CI/CD cycles. No configuration changes are required to use this optimization.

Given the nature of these fixes—addressing a critical performance regression and a router bug—the recommendation is to upgrade. The NgOptimizedImage fix alone provides a strong reason for immediate adoption, especially for public-facing applications. No new regressions have been reported post-release.

To upgrade your project:

ng update @angular/cli @angular/core

This command will update your Angular packages to 22.1.3. Review the ng update output for any migration prompts, though none are expected for this patch release.

Verdict: Upgrade Now.

Key Bug Fixes in 22.1.3

Angular 22.1.3 addresses two significant issues affecting UI stability and internationalization.

The first fix resolves a race condition in the animations package. Previously, elements removed by *ngIf with an exit animation could flicker or briefly reappear if another *ngIf condition added a new element to the same parent before the exit animation completed. This led to unstable visual transitions in dynamic UIs.

The animation engine now defers DOM removal of exiting elements until their animation state is void and no new elements are pending insertion at the same position. This ensures stable visual behavior for developers using *ngIf with animate transitions.

// Example of an affected component template
@Component({
  selector: 'my-animated-component',
  template: `
    <div *ngIf="showBox" @fade>Box Content</div>
    <button (click)="toggleBox()">Toggle</button>
  `,
  animations: [
    trigger('fade', [
      transition(':enter', [style({ opacity: 0 }), animate('300ms ease-out', style({ opacity: 1 }))]),
      transition(':leave', [animate('200ms ease-in', style({ opacity: 0 }))])
    ])
  ]
})
export class MyAnimatedComponent {
  showBox = true;
  toggleBox() {
    this.showBox = !this.showBox;
  }
}

The second fix targets an error in the common package’s DatePipe. It previously produced incorrect day values for dates near midnight in specific non-English locales, such as es-AR. This bug caused off-by-one day errors when formatting dates using presets like shortDate or mediumDate where the local time crossed a UTC day boundary.

The DatePipe now uses an improved Intl.DateTimeFormat configuration internally. This update resolves the timezone-related formatting inconsistencies, providing accurate date representations across all supported locales. Applications displaying localized dates, particularly those with users in affected regions, will now show correct values.

// Previously, in es-AR locale, for a date like 2023-11-01T03:00:00Z (UTC)
// depending on local timezone, DatePipe could incorrectly show October 31.
// Now, it will correctly show November 1 for 2023-11-01T03:00:00Z in es-AR.
const date = new Date('2023-11-01T03:00:00Z');
// In a component template: {{ date | date:'shortDate':'':'es-AR' }}
// Before (example): '31/10/2023' (incorrect for some timezones)
// After (example):  '1/11/2023' (correct)

Both fixes address critical stability and correctness issues. The DatePipe fix is particularly important for internationalized applications.

Verdict: Upgrade now.

Who is Affected by These Changes

This patch release addresses specific issues impacting applications with complex templates, dynamic routing, and large build configurations.

A compiler fix resolves an issue where template variables within ng-template elements, particularly when combined with *ngIf, could be incorrectly typed. This affected developers using strict type checking, potentially leading to build errors or incorrect runtime behavior in templates like:

<ng-template #detail let-data>
  <div *ngIf="data.status === 'active'">{{ data.name }}</div>
</ng-template>

Applications that rely on precise type inference for let- variables within structural directives will see improved type safety and reduced false-positive type errors.

The router received a fix for queryParamsHandling: 'merge' behavior. Previously, navigating with an empty queryParams object could fail to clear existing parameters when queryParamsHandling was set to 'merge'. This could cause unexpected URL states and application behavior in scenarios requiring a full reset of query parameters. Affected applications include those with dynamic filtering or search features that use this merge strategy to update or clear URL state.

For example, a navigation call like this.router.navigate(['/items'], { queryParams: {}, queryParamsHandling: 'merge' }) now correctly clears previous query parameters, rather than retaining them.

Lastly, the Angular CLI build process for projects using Web Workers has improved stability. A previous issue could cause build failures or high memory consumption during compilation of large applications implementing Web Workers. Teams with extensive Web Worker use in their applications, particularly in CI/CD environments, should see more consistent and reliable build outcomes. This change improves the developer experience for projects pushing the limits of client-side processing.

Upgrade Strategy: Now or Later

Angular 22.1.3 includes an essential fix for a memory leak within the HttpClient module. This issue primarily affected single-page applications that perform numerous HTTP requests or run for extended periods, causing memory consumption to grow steadily. Resolving this leak improves application stability and long-term performance, making the fix a high priority.

The release also introduces a change affecting NgOptimizedImage when used in development mode. Images configured with this directive now require explicit width and height attributes. Omitting these attributes will trigger a warning during development builds, guiding developers to specify dimensions and prevent cumulative layout shift (CLS) issues. This is a minor breaking change; it does not stop production builds, and the fix involves adding two attributes to affected <img> tags.

A compiler optimization for @defer blocks is also part of this release. This improvement reduces the bundle size for components loaded using deferred views, leading to faster initial load times for applications that use this feature. This is a non-disruptive performance gain that applies automatically after the upgrade.

Considering the critical HttpClient memory leak fix, an immediate upgrade to 22.1.3 is recommended for nearly all Angular projects. The stability improvements outweigh the minimal effort required to address the NgOptimizedImage warnings. The @defer optimization provides an additional, passive performance benefit.

Before deploying to production, run your full test suite. Pay particular attention to memory usage metrics in long-running integration tests if your application was affected by the HttpClient leak. Address any new NgOptimizedImage warnings in your development environment.

To upgrade your project, use the standard Angular CLI command:

ng update @angular/cli @angular/core

This command will guide you through the update process and report any specific migration tasks.

Verdict: Upgrade Now. The stability and performance benefits, driven by the HttpClient fix, make this an immediate priority.