Angular v17 → v22: The Migration Guide That Includes the Breakages

The rule I give teams: during a version hop, do only the first table. Everything in the second gets its own ticket, shipped independently. A migration PR that also converts four hundred templates to @if is a PR nobody can review, and unreviewed migration PRs are how regressions reach production.

The plan

Five phases. Each one ships to production on its own. If a phase cannot ship alone, it is too big.

Phase 0 - Assessment (one sprint, no code changes)

Inventory every third-party Angular dependency and map its supported version window. This determines your ceiling before you write a line of code. Flag PrimeNG, NgRx, Material theming, @angular-builders/custom-webpack, ngx-build-plus, Module Federation, i18n, and anything still on @nguniversal/*.

Then audit your test coverage honestly. If the suite is thin or flaky, stop and fix that first. The team at OctoPerf put it well after their migration: their bottleneck was validation, not transformation. They relied on 10,919 unit tests to verify 5,221 changed files, because reviewing those files by hand was never going to happen.

Check Node and TypeScript versions in four places, not one: local dev, CI images, Dockerfiles, and the engines field.

Phase 1 - Get to a supported version (v17 → v20)

v17 → v18 is the quiet hop. Mostly deprecations. You will be prompted to migrate the builder - decline for now if you have a custom Webpack config, and handle it separately in Phase 2.

v18 → v19 is the standalone flip, and the most consequential single change in the range. The migration adds standalone: false to everything currently declared in an NgModule. It mostly works. Afterwards, manually verify every dynamic component load and every template that used this.foo, because v19 changed what that means and the compiler will not warn you.

v19 → v20 requires two manual renames the schematic will not do for you: afterRender() becomes afterEveryRender(), and TestBed.flushEffects() is gone.

Ship this. You are now on supported software, and the security argument is satisfied. Everything past this point is engineering value rather than risk mitigation, which makes it a much easier conversation with whoever holds the budget.

Phase 2 - The hard workstreams (separately, any order)

The builder migration. Material M2 → M3. The control flow migration. Any third-party overhaul like PrimeNG's theming rewrite or @nguniversal/* → @angular/ssr.

Each of these is its own project with its own QA. Bundling them into the version hops is how migrations stall out and get quietly abandoned.

Phase 3 - v20 → v22

v20 → v21 makes zoneless and Vitest the defaults for new apps. Your existing app keeps zone.js and Karma. Do not change both at once.

v21 → v22 requires Node 22+ and TypeScript 6.0+ before you run ng update, not after. The build fails immediately otherwise. Check your CI images and Dockerfiles, not just your laptop.

Let the Eager migration run and do not fight it. Then audit anything reading route params, because the router now inherits params from all parent routes by default.

Phase 4 - Modernization (ongoing, forever)

Peel components off Eager onto OnPush. Move hot paths to signals. Enable zoneless once OnPush coverage is good. Migrate Karma to Vitest. Adopt Signal Forms in new code.

None of this is urgent. All of it is worth doing eventually.

What breaks, version by version

v18 → v19

standalone: true became the default. Every component, directive, and pipe is standalone unless you say otherwise.

The migration handles most of it, but two issues on the Angular tracker are worth knowing about. In #58747, ng update failed to remove the flag from components without imports. In #57829, dynamic component loading via ViewContainerRef.createComponent and createNgModule broke for components relying on the implicit old default.

The one that costs people real debugging time: this.foo in a template no longer refers to a template context variable. If you meant the template variable, drop the this.. Nothing errors. The value is just wrong.

Also in v19: TypeScript below 5.5 dropped, effect() timing changed to run as part of change detection rather than as a microtask, and event replay became stable and on by default for new SSR apps.

v19 → v20

Signals largely finished. effect(), linkedSignal(), and toSignal() all went stable.

Two manual fixes, no schematic: afterRender() renamed to afterEveryRender(), and TestBed.flushEffects() removed.

*ngIf, *ngFor, and *ngSwitch were officially deprecated in favour of control flow. Structural directives in general were not deprecated, only those three. The style guide also changed filename conventions and started recommending [class.x] over ngClass. All of that is optional.

TypeScript 5.8 and Node 20 became required.

v20 → v21

Zoneless became the default for new apps, and zone.js is no longer shipped with them. Existing apps are not forced off it. Vitest replaced Karma and Jasmine as the default runner, though Karma still works. Signal Forms arrived as experimental, Angular Aria as developer preview, and the CLI gained a built-in MCP server with an onpush_zoneless_migration tool.

The trap: because Vitest always runs zoneless in Angular, fakeAsync and tick cannot be used with it. There is also a documented regression (angular-cli#32121) where fakeAsync tests fail with zone-testing.js is needed for the fakeAsync() test helper but could not be found under the new unit-test builder, even when you are still using Karma.

v21 → v22

Released 3 June 2026. Four things break.

OnPush is now the default change detection strategy. A component that does not set changeDetection means OnPush, not check-always. Nothing in your existing code breaks if you let the migration work - ng update stamps the new ChangeDetectionStrategy.Eager value onto every component that relied on the old default. What changes is that every new component your team generates is OnPush. If people still write code assuming mutation-based updates will show up, v22 is where that habit stops working.

Route params now inherit from all parent routes. The paramsInheritanceStrategy default changed from 'emptyOnly' to 'always'. A child route reading a param name that also exists on a parent may now resolve to a value it never saw before, and code with defensive "if this param is undefined" branches may silently take the other path.

You can revert it globally

provideRouter(routes, withRouterConfig({
  paramsInheritanceStrategy: 'emptyOnly',
}))

But renaming colliding params (:userId instead of a second :id) is the better fix. The new default is genuinely more useful for deep-linked detail pages.

Node 22 and TypeScript 6.0 are mandatory. Node 20 is dropped. Node 26 is supported.

And three smaller edges: duplicate input bindings on one element are now a compile error rather than silently tolerated, data-* attributes bind as attributes instead of property bindings, and the HTTP transfer cache skips credentialed requests by default so authenticated responses cannot leak across SSR sessions.

On the plus side, v22 is where the modern stack stops being experimental. Signal Forms, resource() and httpResource(), Angular Aria, injectAsync(), and HttpClient with Fetch all went stable. Incremental hydration became the default. Selectorless components arrived.

Where ng update leaves you on your own

The schematics handle maybe seventy percent of this mechanically. The remaining thirty is where the budget goes.

Control flow migration is good but needs a human reading every diff. It drops i18n attributes on ng-template (#53289, #52517), which silently breaks translations with no error. It mishandles ng-template combined with [ngIf] and let- (#53291). It leaves orphaned named templates behind (#58850). And it introduces whitespace around inline elements, which corrupts rendered text in ways that only show up when someone reads the page.

Peer dependency conflicts stop ng update cold, usually with Migration failed: Incompatible peer dependencies found. Your options, ranked honestly:

1. overrides in package.json. Explicit, reviewable, documented. Use this.
2. --legacy-peer-deps. Acceptable. Leaves the conflict unresolved but breaks nothing.
3. --force. Avoid. It can leave you with duplicate package versions in node_modules and runtime errors that make no sense.

Whatever you use, follow it with a full build, a serve, and the test suite.

Material M2 → M3 is the worst gap between what the docs promise and what you get. It has its own post in this series, because it deserves one.

What you actually get

The build speed argument is the easiest one to make to a CTO, because Angular measured it themselves. The v17 release reported up to 87% faster ng build, an 80% faster edit-refresh loop, and enterprise partners seeing 67% build-time improvements on the esbuild pipeline.

Beyond that: dropping zone.js removes roughly 33KB raw from the bundle and eliminates a large share of unnecessary change-detection cycles. Incremental hydration and event replay improve Time to Interactive without losing interactions that happen before hydration. And modern Angular is what people you hire already know - a codebase full of NgModule wiring takes longer to onboard into, every single time.

The honest summary

Angular's release notes describe v18 as having few breaking changes and present the standalone and Material migrations as automated. The issue trackers tell a different story, particularly for M3 theming, where the official documentation was internally contradictory enough that developers filed issues about the documentation itself.

That gap is the whole point of this article. ng update is genuinely good. It is not the plan.

If you are on 17, 18, or 19, the first move is not "adopt signals" or "go zoneless." It is Phase 1: get to a supported version, ship it, and stop being an audit finding. Everything else can wait for a quarter when it fits.

We do this work. If you have an Angular codebase that has fallen behind and you want a realistic scope before you commit budget to it, contact us.