Angular Upgrade Hops Angular 17 To 18

---
id: angular.upgrade.hops.angular-17-to-18
name: Angular 17 to Angular 18 Upgrade
description: >
  Upgrade an Angular application from Angular 17.x to Angular 18.x using a controlled major-hop process. Use when the project is ready to move from Angular 17 to Angular 18 and needs explicit handling for Node.js/TypeScript requirements, tests, SSR/platform-server, TransferState, HTTP transfer cache, router redirects, forms, OnPush, and change detection behavior.
stack:
  - Angular
  - TypeScript
category: upgrade
status: stable
version: 0.10.0
owner: NgAutoPilot
triggers:
  - Angular 17 to 18
  - Angular 18 upgrade
  - test stability
  - SSR platform-server
compatibility:
  angular:
    min: "17"
---

# 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:

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

If local CLI is unreliable, use:

```bash
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.

```bash
ng update @angular/material@18
```

or:

```bash
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.