Angular 20 to 21 upgrade plan audit

High-priority findings

1. High · command path

   overrides cannot repair the peer conflicts that may block ng update

   Phase 2 says to add an overrides block for @cotufa82/ng-ivs, @khajegan/ngx-audio-player, and ngx-stripe instead of using --force. npm overrides change dependency resolution. They do not rewrite a package's declared peer range, and Angular CLI performs its own compatibility check.

   The Material update has the same issue. @khajegan/ngx-audio-player@17.1.0 declares @angular/material ^17.0.4, so ng update @angular/material@21 can fail its reverse peer check.

   Correction: record the known exceptions, run both Angular update commands with --force when the CLI reports those exact stale peers, and prove runtime compatibility afterward. A fork or patched package manifest is the stricter alternative. npm 12's packageExtensions can change peer metadata for npm resolution, but it ties the repository to npm 12 and does not replace the Angular CLI decision.

   npx ng update @angular/core@^21 @angular/cli@^21 --force
   npx ng update @angular/material@^21 --force

2. High · toolchain

   npm 12.0.1 does not support the installed Node 24.5.0

   Angular 21 accepts Node ^24.0.0, but npm 12.0.1 requires ^24.15.0 on the Node 24 line. Every registry and install command emitted that warning. Calling it unrelated and safe to ignore is the wrong policy for a migration that rewrites package-lock.json.

   Correction: make Node 24.15.0 or newer the Phase 0 prerequisite, or use an npm release that supports Node 24.5. Pin the choice in the repository and CI with the team's normal Node-version file plus engines or packageManager.

3. High · Firebase acceptance

   The push test only covers a fresh token and can miss a returning-user failure

   The plan expects every login to POST a push token and then attach onMessage. Current code only calls setToken(), and therefore onMessage(), when the token differs from fc_token in local storage. A returning user with an unchanged token produces no POST and may get no foreground listener.

   Correction: test both states. First clear fc_token and verify registration. Then reload with the saved token, verify that duplicate registration is avoided, and still prove an inbound foreground notification reaches the toast. The Firebase rewrite should attach one listener independently of whether the backend token POST is needed and retain its unsubscribe handle.

Medium-priority findings

1. Medium · Firebase

   Remote Config needs its own support check

   The plan calls isSupported() before Messaging, but the Remote Config Web SDK also exposes isSupported() because IndexedDB can exist yet reject open(), including private browsing contexts. Alias the two imports and check each product before initialization. Browser-only guards alone are insufficient.

2. Medium · change detection

   Zone.js does not prove that raw Firebase callbacks update Angular views

   AngularFire wraps SDK callbacks to re-enter Angular and schedule change detection. The plan removes those wrappers, then assumes Zone.js promise patching is enough. That is not a reliable contract for Messaging callbacks or future native async behavior.

   Correction: explicitly use NgZone.run() around toast and template-state mutations, or move the state to signals and test updates without an unrelated click or navigation.

3. Medium · validation

   "Every build that ships" does not run every shipping script

   Phase 5 runs dev, QA, production, QA prerender, QA serverless, and one white-label build. It skips staging, production and staging full-prerender scripts, and the other serverless configurations present in package.json.

   Correction: identify the scripts actually called by CI and deployment, then run those exact commands. At minimum, account for build-stage, prerender-all-staging, prerender-all-production, and each deployed serverless configuration. Keep one generated white-label build in the gate.

4. Medium · scope

   "Bump every library that has a v21 release" is not the plan's real rule

   The matrix intentionally retains libraries with open Angular peer ranges. It also leaves ngx-scrollbar@9.0.2 even though ngx-scrollbar@19.1.5 is its Angular 21 line. That may be the right scope choice because the newer package has API changes, but it contradicts the stated outcome.

   Correction: state the actual rule: upgrade Angular-coupled packages whose installed release rejects Angular 21, and explicitly defer broad API migrations. Put ngx-scrollbar, ngx-image-cropper, ngx-sharebuttons, and similar open-range packages in a named deferral table.

5. Medium · dependency side effect

   Font Awesome 4 pulls SVG core 7, but the plan only names the Angular wrapper

   @fortawesome/angular-fontawesome@4.0.0 is the correct Angular 21 line, but it depends on @fortawesome/fontawesome-svg-core ^7.1.0. The project directly declares SVG core and icon packs from version 6. The install may leave duplicate core majors even though the wrapper supports version 6 icon definitions.

   Correction: decide whether to deduplicate on SVG core 7 or retain the mixed tree deliberately. Check the two icons registered in SharedModule, faXTwitter and faCommentSms, and compare bundle output.

6. Medium · deprecation

   The legacy server and Karma builders still exist, but Angular 21 deprecates them

   The plan correctly says @angular-devkit/build-angular:server and :karma still run in 21.2.24. It omits that Angular 21 marks the Webpack builders deprecated in favor of @angular/build. Keeping them is valid for this branch, but it does not fully clear the path to the next Angular major.

   Correction: add a dated follow-up to migrate the serverless target and test builder. Treat warnings from those builders as expected only for this release.

Low-priority corrections

1. Low · inventory

   The host-binding review misses two files

   There are eight @HostBinding uses in five files. The checklist omits signup-by-refer.component.ts and profile-skeleton.component.ts. It should also compile-check the dynamic host expressions in video-player-v2, as already noted.

2. Low · factual counts

   Two repository counts are stale

   The working tree has 8 modified files and 12 untracked HTML files, not 11. FirebaseService appears in 14 consumer files, not 15. Neither changes the migration strategy.

3. Low · npm evidence

   The three stale libraries do not currently fail npm ls --depth=0

   With the installed npm 12.0.1, both npm ci --dry-run and npm ls --depth=0 completed successfully. Their peer declarations are still incompatible and Angular CLI may reject the update, but the plan should not claim an observed npm ls failure.

4. Low · version notation

   One pin and one package version are described imprecisely

   firebase: ^11.10.0 is a range, not a pin. Use 11.10.0 if the intent is exact parity. @angular-devkit/architect follows the 0.2102.24 version scheme, not 21.2.24.

What the plan gets right

Recommended execution order

1. Normalize the toolchain and tree

   Use Node 24.15 or newer with npm 12, pin both for local and CI use, commit or stash unrelated changes, run a clean install, record current peer exceptions, and capture build sizes.

2. Replace AngularFire while still on Angular 20

   Pin Firebase 11.10.0, initialize lazily in the browser, check Messaging and Remote Config support separately, re-enter Angular for UI mutations, and own the Messaging unsubscribe lifecycle.

3. Test Firebase in two browser states

   Verify first registration with empty storage, then reload with the existing token and prove foreground messages still arrive without a duplicate backend POST. Check Remote Config in normal and restricted storage contexts.

4. Update Angular core and CLI

   Use the latest 21.x patches. Apply --force only for the documented stale peers. Verify provideZoneChangeDetection(), TypeScript 5.9, and generated configuration changes.

5. Update Material, then Angular-coupled libraries

   Update Material with the same peer exception policy. Upgrade the selected library set, account for Font Awesome SVG core 7, and put every retained old package in an explicit deferral table.

6. Compile and lint

   Fix TypeScript and all host-binding errors before library API errors. Run lint with Angular ESLint 21. Avoid the global host-binding escape hatch unless a specific library leaves no local fix.

7. Run the deployment build matrix

   Execute the scripts CI and deployment really use across QA, staging, production, prerender, SSR, serverless, and one generated white-label project. Check rendered HTML and server logs, not only exit codes.

8. Run focused browser smoke tests

   Cover Firebase, Remote Config, routing, service worker, Material/CDK, PrimeNG, Font Awesome, the upgraded form and carousel libraries, plus the deferred audio, IVS, Stripe, editor, cropper, and scrollbar paths.

Verified package facts