Updating an Angular application with ng update, one major at a time

Release cadence and support windows

Angular now announces one major version every 12 months, with four to six minor releases per major. Until Angular 22 the cycle was six months. Each major is normally supported for 24 months: 12 months of active support, then 12 months of long-term support (LTS), which only receives critical fixes and security patches.

The versions still supported on 27 October 2026, according to angular.dev:

Versions 2 to 19 are no longer supported. Angular 23 is expected around June 2027; angular.dev notes that all future dates are approximate. Versions released under the old cycle had shorter support: Angular 20 will have been supported for 18 months.

The rule: one major at a time

angular.dev sets two conditions for ng update: the target version must be supported, and your current version must be within one major of the target. To go from 19 to 21, you go through 20.

This is not a formality. ng update runs automatic migrations (schematics) that rewrite your code for the next version. They are written to chain from one major to the next, hence the rule. If you edit the version numbers in package.json and run npm install, no migration runs at all.

Before you run ng update

1. A clean Git working tree. By default ng update refuses to run when the repository contains modified or untracked files. The --allow-dirty option removes that safeguard; avoid it. Work on a dedicated branch.
2. Green checks: lint, unit tests, production build, and end-to-end tests if you have them. Without a green baseline you cannot tell whether a failure comes from the update.
3. Node.js and TypeScript at the versions the target requires, per the angular.dev compatibility table:

Angular 22 drops Node.js 20. Remember the image of your CI agents, your build containers and the developers' machines.

1. The official guide for your jump: the Update Guide on angular.dev generates the list of changes to make from your current version, your target version and the complexity of your application.

The steps for one major jump

Example, from Angular 20 to 21:

git switch -c upgrade/angular-21
npx ng update @angular/core@21 @angular/cli@21 --create-commits

--create-commits creates a commit for each update and each migration. Review is easier, and you can revert one specific migration.

Then, in this order:

1. Packages that follow Angular: ng update @angular/material@21 if you use Material and the CDK, then the tooling, for example ng update angular-eslint.
2. Third-party libraries: each one needs a release compatible with the new major (see below).
3. The checks: types, lint, tests, build, end-to-end tests. Fix them in that order, because one type error often causes a cascade of failures further down.
4. Dependencies: review npm audit and the overrides section of package.json. An override added for an old vulnerability may have become useless, or may now block a resolution.
5. Merge, then start the next jump if you are aiming further. Do not stack two majors in a single merge request.

Minor and patch updates can be done at any time between majors, with the same checks.

The most common traps

Third-party libraries that block

This is the most frequent reason an ng update fails on peer dependencies: a component library requires the CDK of the same major, a state library requires the same Angular version. Before you start, check that each library has a release compatible with the target. If it does, update it in the same command as the framework so peer dependencies resolve together:

npx ng update @angular/core@21 @angular/cli@21 @ngrx/store

If a library has no compatible release yet, wait for it or replace it. Forcing only moves the error to runtime.

The --force option

--force ignores peer dependency version mismatches. It makes the command succeed, not the application: a library built for the previous major can break at compile time or, worse, at runtime. Keep it for cases where you know exactly why the conflict is harmless.

Migrations that never ran

If someone already bumped the packages by hand, the migrations can be run on their own:

npx ng update @angular/core --migrate-only --from=20 --to=21

--from and --to only work with --migrate-only, and only for a single package.

Node.js, npm and CI

An update that passes locally and fails in CI almost always comes down to a different Node.js version. Pin the version (an .nvmrc file, the engines field, the CI image) in the same branch as the update. On the npm side, a Cannot read properties of null (reading 'edgesOut') error has been observed with npm 10 during a move to Angular 21; upgrading to npm 11 resolved it.

Accumulated deprecations

A deprecated API stays available for at least the next major release, roughly 12 months, and is only removed in a major. Deal with deprecation warnings at each jump: they are the compile errors of the next one.

Planning maintenance over time

With one major a year and 24 months of support, an application updated once a year always stays on a supported version. The risk comes from falling behind: the more majors you have to catch up, the more third-party libraries diverge and the more each jump costs. Put the major upgrade on the calendar when a new major ships, and apply minor releases as they come.

A short checklist for each jump:

Starting a new project on Angular 22

If you are starting a new application rather than updating one, Socle is an Angular 22 starter (zoneless, signals, standalone components) whose npm run verify command chains 13 checks, including lint, strict typing, unit and end-to-end tests, build budgets, accessibility and dependency audit. Its upgrading guide follows the procedure above and relies on those checks to show what an update broke. It does not update an existing application, has no back end, and requires Node.js 22.22.3 or later, or Node.js 24.

Sources

• angular.dev, Angular versioning and releases
• angular.dev, Version compatibility
• angular.dev, ng update
• angular.dev, Update Guide
• Socle, upgrading guide (docs/upgrading.md)
• Pages checked on 2026-10-27