Angular 17 to Angular 18 Upgrade

Purpose

Upgrade an Angular application from Angular 17.x to Angular 18.x using a controlled major-hop process.

When to Use

• The project uses Angular 17.x.
• The target next hop is Angular 18.x.
• The Angular 16 -> 17 validation gate passed.
• Angular Material usage is known.
• SSR/platform-server usage is known.
• TransferState usage is known.
• Router guards/resolvers usage is known.
• Forms usage is known.
• Test strategy is known.

When Not to Use

• The project is AngularJS 1.x.
• The project is Angular 16.x or lower.
• The project is already Angular 18 or later.
• The previous Angular 16 -> 17 validation gate failed.
• Node.js version is unsupported.
• Angular Material v17 migration has unresolved critical blockers.
• SSR behavior is unknown in an SSR app.
• Router redirect behavior is unknown in a routing-heavy app.
• The task is only testing cleanup without Angular upgrade.
• The task is only SSR migration without Angular upgrade.

Mandatory Cross-Skill Routing

Before upgrading from Angular 17 to Angular 18, run:

skills/angular/upgrades/changelog/angular-major-changelog-risk-review/SKILL.md

If the changelog review returns FAIL_BLOCK_NEXT_HOP, do not continue to Angular 18.

Recommended Cross-Skill Routing

• skills/angular/upgrades/testing/angular-v18-test-stability-change-detection/SKILL.md
• skills/angular/upgrades/ssr/angular-platform-server-v18-migration/SKILL.md
• skills/angular/upgrades/router/angular-router-redirect-command-v18/SKILL.md
• skills/angular/upgrades/http/angular-http-transfer-cache-v18/SKILL.md
• skills/angular/upgrades/forms/angular-ngmodel-template-write-cleanup-v18/SKILL.md
• skills/angular/upgrades/change-detection/angular-onpush-host-bindings-v18/SKILL.md

Required Inputs

• package.json
• lock file
• Angular package versions
• Angular CLI version
• Angular Material version
• Angular CDK version
• TypeScript version
• RxJS version
• Zone.js version
• Node.js version
• angular.json
• tsconfig.json
• tsconfig.app.json
• tsconfig.spec.json
• test setup files
• polyfills.ts
• SSR files
• TransferState usage
• HTTP transfer cache usage
• Angular Forms usage
• [(ngModel)] templates
• router guards
• router resolvers
• RedirectCommand
• UrlTree
• Route.redirectTo
• platformDynamicServer
• platformServer
• @angular/compiler
• PlatformConfig
• useAbsoluteUrl
• baseUrl
• ServerTransferStateModule
• RESOURCE_CACHE_PROVIDER
• isPlatformWorkerUi
• isPlatformWorkerApp
• AnimationDriver
• matchesElement
• Testability
• increasePendingRequestCount
• decreasePendingRequestCount
• getPendingRequestCount
• environment providers
• routed components
• OnPush components
• host bindings
• dynamic views
• ComponentFixture.whenStable
• ApplicationRef.isStable
• ComponentFixture.autoDetectChanges
• current build/test/lint/e2e scripts
• production build scripts
• SSR/prerender scripts
• screenshot/golden tests

Dependency Upgrade

Node.js

Angular 18 supports Node.js 18.19.0 and newer.

Block the upgrade when Node.js is lower than 18.19.0.

TypeScript

Angular 18 requires TypeScript 5.4 or newer.

Angular Core and CLI

Run:

ng update @angular/core@18 @angular/cli@18

If local CLI is unreliable, use:

npx @angular/cli@18 update @angular/core@18 @angular/cli@18

Angular Material

If the project uses Angular Material, update to v18 after Angular core and CLI succeed.

ng update @angular/material@18

or:

npx @angular/cli@18 update @angular/material@18

Required Code Changes

1. Replace async from Angular testing with waitForAsync

Use waitForAsync instead of async from @angular/core/testing.

2. Remove AnimationDriver.matchesElement

Remove uses of matchesElement from AnimationDriver.

3. TransferState imports

Import StateKey and TransferState from @angular/core.

4. HTTP transfer cache with authorization headers

Only enable includeRequestsWithAuthHeaders with a security review.

5. Remove WebWorker platform APIs

Remove isPlatformWorkerUi and isPlatformWorkerApp.

6. Test change detection behavior

Review tests that rely on exact change detection order or stabilization timing.

7. Remove template write expressions with [(ngModel)]

Move writes out of the template and into handlers.

8. Remove Testability pending request APIs

Remove increasePendingRequestCount, decreasePendingRequestCount, and getPendingRequestCount.

9. Environment providers for routed components

Move providers needed by routed components to route-level or bootstrap-level providers.

10. Guard/resolver redirect behavior with replaceUrl

Use RedirectCommand when redirect history behavior must be explicit.

11. Remove RESOURCE_CACHE_PROVIDER

Remove dependencies on RESOURCE_CACHE_PROVIDER.

12. platform-server URL behavior

Review canonical URLs, redirects, and tests that compare exact SSR URLs.

13. Absolute URL handling

Replace useAbsoluteUrl and baseUrl with request/environment-aware absolute URL handling.

14. Replace platformDynamicServer with platformServer

Use platformServer and import @angular/compiler when JIT/server behavior requires it.

15. Remove ServerTransferStateModule

Remove ServerTransferStateModule usage.

16. Route.redirectTo can be a function

Update route readers that assume string-only redirects.

17. Guards and resolvers can return RedirectCommand

Update custom typing where needed.

18. OnPush host binding updates

Review OnPush components with host bindings and explicit dirty marking.

19. Newly created or reattached views refresh behavior

Review dynamic views, overlays, and portal-like behavior.

20. whenStable and ApplicationRef.isStable

Review test timing and stabilization assumptions.

21. ComponentFixture.autoDetectChanges

Review tests that rely on auto-detection order.

Do

• Run the Angular 16 changelog review before changing package versions.
• Keep tests, SSR, router, forms, and transfer cache behavior explicit.
• Validate production and SSR builds when they are used.
• Route risky test, SSR, and router behavior to the dedicated skills.
• Keep Material/MDC validation explicit if Material is used.

Do Not

• Do not continue if Angular 16 changelog review failed.
• Do not keep deprecated testing, transfer state, or webworker APIs.
• Do not enable authenticated transfer cache without security review.
• Do not mix this hop with control flow, defer, standalone, or zoneless modernization.
• Do not rely on leaked styles or unstable test timing.

Review Checklist

• Angular 16 changelog review passed.
• Node.js, TypeScript, and Zone.js are compatible.
• Testing helper usage is updated.
• SSR and transfer cache behavior are reviewed.
• Router redirect history behavior is reviewed.
• ngModel template writes are removed.
• Testability APIs are removed.
• OnPush host binding behavior is reviewed.
• Material/MDC regression risk is reviewed.
• Production build passes.

Validation

Run only existing scripts:

• npm run build
• npm run test
• npm run lint
• npm run e2e
• ng build --configuration production
• npm run build:ssr
• npm run prerender
• npm run serve:ssr

Validation Gate

Use FAIL_BLOCK_NEXT_HOP when:

• Angular 16 changelog risk review failed
• Node.js is lower than 18.19.0
• TypeScript version is unsupported
• build fails
• tests fail
• production build fails
• Angular CLI update is incomplete
• Angular Material update is incomplete in a Material project
• async from Angular testing remains
• AnimationDriver.matchesElement remains
• TransferState imports remain from @angular/platform-browser
• authenticated transfer cache is enabled without security review
• WebWorker platform APIs remain
• template write expressions with [(ngModel)] remain
• removed Testability APIs remain
• routed components depend on misplaced environment providers
• critical guard redirect history behavior is unknown
• RESOURCE_CACHE_PROVIDER remains
• SSR URL behavior is unvalidated
• platformDynamicServer remains in active SSR code
• ServerTransferStateModule remains
• custom route readers assume redirectTo is only string
• custom guard/resolver typing does not allow RedirectCommand
• critical OnPush host bindings are stale
• test stability issues remain unresolved
• Material/style regressions are unreviewed
• workspace config is unstable

Expected Output

1. Upgrade summary.
2. Changelog baseline summary.
3. SSR, router, and testing migration summary.
4. Validation result.
5. Gate decision.

Exit Criteria

• Angular 16 changelog review has passed.
• Angular dependencies are upgraded to Angular 18-compatible versions.
• Angular CLI is upgraded to v18.
• Angular Material/CDK are upgraded to v18 only if used.
• Node.js 18.19.0+ compatibility is confirmed.
• TypeScript 5.4+ compatibility is confirmed.
• Testing behavior is reviewed.
• SSR/platform-server behavior is reviewed.
• TransferState and transfer cache behavior are reviewed.
• Router redirect behavior is reviewed.
• ngModel template writes are removed.
• Testability APIs are removed.
• OnPush host binding behavior is reviewed.
• Angular Material and style regressions are reviewed.
• Validation gate result is explicit.
• The next hop is not started automatically.