Skip to content

Angular Modernization and Version Upgrades

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.

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.

Terminal window
ng update # lists what is available
ng update @angular/cli@21 @angular/core@21

Five 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.

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:

Terminal window
ng generate @angular/core:route-lazy-loading --path src/app/orders

Run 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.

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.

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.

Order matters, because some steps unlock others.

  1. Get to a supported version first. One major at a time, tests green between each. Nothing else is worth doing on an unsupported release.
  2. Standalone. It is the prerequisite for @defer, for loadComponent, and for the whole provideX configuration model.
  3. Control flow. Then immediately fix the track $index conversions.
  4. inject(). Low risk, and it makes the signal migrations cleaner.
  5. Signal inputs, outputs and queries. Now components can be derived from rather than reacted to.
  6. Lazy routes. The largest bundle win, and easy once standalone.
  7. Signals for state, feature by feature. This is the expensive step and the one with real payoff.
  8. Zoneless. Do it after signals, because signal-driven components are already compatible.
  9. @defer and 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.

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.

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