Angular Modernization and Version Upgrades
Why this matters
Section titled “Why this matters”There is a version of an Angular codebase that is technically on the latest release and has none of the benefits: modules everywhere, *ngIf throughout, constructor injection, no signals, ZoneJS still in the polyfills. The version number moved; nothing else did.
Modernisation is a separate job from upgrading, and both are worth doing deliberately. Falling behind is expensive in a specific way: Angular’s own first security best practice is to stay on recent releases, because updates fix security defects. A codebase three majors behind is not just missing features — it is running unpatched code.
The release and support model
Section titled “The release and support model”Angular ships one major per year, on a 12-month cadence, with 24 months of support per major: 12 months active and 12 months long-term support.
| Version | Status | Released | Active until | LTS until |
|---|---|---|---|---|
| 22.x | Active | 2026-06-03 | 2027-06 | 2028-06 |
| 21.x | LTS | 2025-11-19 | 2026-06-03 | 2027-06 |
| 20.x | LTS | 2025-05-28 | 2025-11-19 | 2026-11-28 |
The practical consequence: two majors behind is the edge of support. Three behind is unsupported, which means no security patches and an upgrade path that has to be walked one version at a time anyway. See Angular Versions and Release Cadence.
Running ng update
Section titled “Running ng update”ng update # lists what is availableng update @angular/cli@21 @angular/core@21Five rules that make this routine rather than eventful:
One major at a time. ng update is designed for single-major steps, and each major’s schematics run as part of that step. Jumping from 18 to 21 skips 19’s and 20’s migrations, which then never run.
Check Node and TypeScript first. Every major raises minimums, and an unsupported Node version produces confusing build errors rather than a clear message. Angular 20 requires Node 20.19+/22.12+/24.0+ and TypeScript 5.8+.
Commit with a clean tree. ng update rewrites source. You want git diff to show only its changes.
Read the update guide for your exact hop. angular.dev/update-guide generates instructions for a specific from/to pair, including manual steps the schematics cannot perform.
Update the ecosystem in the same step. Angular Material, the CDK, and any Angular-versioned library. A version mismatch between @angular/core and @angular/material produces errors that look like your code’s fault.
Expect the CI suite to be the thing that catches problems. Upgrading with a weak test suite is how a major becomes a multi-week project.
The migration schematics
Section titled “The migration schematics”These are independent of ng update and can be run whenever you are ready. Each is a codemod over your source.
| Command | Converts |
|---|---|
ng generate @angular/core:control-flow |
*ngIf/*ngFor/*ngSwitch → @if/@for/@switch |
ng generate @angular/core:standalone |
NgModules → standalone components |
ng generate @angular/core:inject |
Constructor DI → inject() |
ng generate @angular/core:signal-input-migration |
@Input() → input() |
ng generate @angular/core:signal-queries-migration |
@ViewChild()/@ContentChild() → viewChild()/contentChild() |
ng generate @angular/core:output-migration |
@Output()/EventEmitter → output() |
ng generate @angular/core:route-lazy-loading |
Eager route components → loadComponent |
ng generate @angular/core:cleanup-unused-imports |
Removes unused entries from imports arrays |
ng generate @angular/core:self-closing-tag |
<foo></foo> → <foo /> |
ng generate @angular/core:common-to-standalone |
CommonModule imports → the specific directives and pipes |
ng generate @angular/core:ngclass-to-class |
[ngClass] → [class] |
ng generate @angular/core:ngstyle-to-style |
[ngStyle] → [style] |
ng generate @angular/core:router-testing-module-migration |
RouterTestingModule → provideRouter |
Most accept --path to scope them to a subdirectory, which is how you run a large migration incrementally:
ng generate @angular/core:route-lazy-loading --path src/app/ordersRun one at a time and commit between each. A migration producing a four-thousand-line diff is not reviewable as a single commit, and when something breaks two weeks later you want to know which codemod did it.
What the schematics get wrong
Section titled “What the schematics get wrong”Codemods are behaviour-preserving, and sometimes the existing behaviour was the bug.
control-flow converts *ngFor without trackBy to track $index. That is exactly what the old code did — and $index tracking is correct only for static collections. For any list that can be reordered, filtered, or have items removed from the middle, it means the wrong DOM node holds the wrong data, with lost focus and scroll position. Grep for track $index after this migration and fix every list that is not genuinely static. This is the single highest-value review step in any modernisation.
standalone leaves SharedModule intact. After conversion, every component lists what it uses and the module is dead weight. Deleting it is manual — and resist the urge to convert it into a barrel of re-exports, which reintroduces the coupling with different syntax.
inject needs a review on inheritance and ordering. Field initialisers run in declaration order, so a field depending on another must come after it. Classes with base-class dependencies deserve a careful look.
common-to-standalone cannot know about dynamic usage. Anything referenced only from a string or a dynamic template is invisible to it.
Nothing converts an NgModule’s forRoot() providers to ApplicationConfig for you. Custom forRoot implementations are manual.
What no codemod can do
Section titled “What no codemod can do”The modernisation that actually changes how a codebase behaves is all manual:
Adopting signals. Converting BehaviorSubject-based state services to signals is a design change, not a syntax change. Where an observable was doing time-based work — debouncing, retry, switchMap — it should stay an observable, with toSignal at the boundary.
Going zoneless. Removing zone.js needs an audit: NgZone.onStable, onMicrotaskEmpty, onUnstable and isStable fail silently under zoneless, so grep for those names first. Then enable provideCheckNoChangesConfig({ exhaustive: true, interval }) in development and exercise the application — it converts silent staleness into thrown errors with a location. Audit reactive-forms-driven templates specifically, because form model updates do not schedule change detection. See Change Detection and Zoneless Angular.
Replacing resolvers with in-component resource. A design decision about whether navigation should block.
Splitting bundles. route-lazy-loading handles the mechanical part; deciding the feature boundaries is yours.
Fixing the test suite. Angular 20 rethrows uncaught listener errors in tests by default rather than logging them. Those failures are real bugs the suite was swallowing.
Karma to Vitest. The refactor-jasmine-vitest schematic is experimental, does not install dependencies, and does not change angular.json. See Angular Testing.
Sequencing a large modernisation
Section titled “Sequencing a large modernisation”Order matters, because some steps unlock others.
- Get to a supported version first. One major at a time, tests green between each. Nothing else is worth doing on an unsupported release.
- Standalone. It is the prerequisite for
@defer, forloadComponent, and for the wholeprovideXconfiguration model. - Control flow. Then immediately fix the
track $indexconversions. inject(). Low risk, and it makes the signal migrations cleaner.- Signal inputs, outputs and queries. Now components can be derived from rather than reacted to.
- Lazy routes. The largest bundle win, and easy once standalone.
- Signals for state, feature by feature. This is the expensive step and the one with real payoff.
- Zoneless. Do it after signals, because signal-driven components are already compatible.
@deferand performance work. Profile first; optimise what the profile shows.
Steps 1–6 are mostly mechanical and can move quickly. Steps 7–9 are genuine engineering and should be scheduled as such.
Keeping current afterwards
Section titled “Keeping current afterwards”Budget for upgrades. One major a year, with a known window, is far cheaper than three at once under pressure.
Enforce it in CI. Bundle budgets in angular.json, npm audit, ng update in a scheduled job that opens a pull request.
Adopt new APIs in new code. Modernisation that only happens as a project is modernisation that gets cancelled.
Do not fork Angular. Angular’s guidance is explicit: private customised versions fall behind and miss security fixes. Contribute the change upstream instead.
Watch releases. The Angular blog carries release announcements; the changelog carries the complete list.
Common mistakes
Section titled “Common mistakes”| Mistake | Consequence | Fix |
|---|---|---|
| Skipping majors | Migrations never run; obscure breakage | One at a time |
| Running every schematic at once | Unreviewable diff; unattributable regressions | One per commit |
Not reviewing track $index |
Lost focus, scroll, and row state | Fix every non-static list |
| Upgrading with a weak test suite | Regressions found in production | Invest in tests first |
SharedModule reborn as a barrel |
The original coupling returns | Import per component |
| Going zoneless without an audit | Silent staleness on some screens | Grep NgZone APIs; use provideCheckNoChangesConfig |
| Suppressing new test errors | Hides real bugs the suite was swallowing | Read each one first |
| Stale Node or TypeScript | Confusing build failures | Check minimums before starting |
| Treating a version bump as modernisation | New version, old patterns | Schedule the design work separately |
Related pages
Section titled “Related pages”- Angular Versions and Release Cadence
- Angular 20: What Actually Shipped
- Standalone Components
- Change Detection and Zoneless Angular
- Signals and Angular Reactivity
- Angular Testing: From First Test to Large Suites