Angular Upgrade Hops Angular 16 To 17

---
id: angular.upgrade.hops.angular-16-to-17
name: Angular 16 to Angular 17 Upgrade
description: >
  Upgrade an Angular application from Angular 16.x to Angular 17.x using a controlled major-hop process. Use when the project is ready to move from Angular 16 to Angular 17 and needs explicit handling for changelog baseline review, Node.js/TypeScript/Zone.js requirements, router configuration, hydration, Signals, destroyed component styles, NgSwitch, Zone.js imports, and dynamic component behavior.
stack:
  - Angular
  - TypeScript
category: upgrade
status: stable
version: 0.10.0
owner: NgAutoPilot
triggers:
  - Angular 16 to 17
  - Angular 17 upgrade
  - Angular 16 changelog review
  - Zone.js imports
compatibility:
  angular:
    min: "16"
---

# Angular 16 to Angular 17 Upgrade

## Purpose

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

## When to Use

- The project uses Angular 16.x.
- The target next hop is Angular 17.x.
- The Angular 15 -> 16 validation gate passed.
- The Angular 16 changelog risk review passed.
- View Engine and ngcc risks are already resolved.
- Angular Material usage is known.
- Router usage is known.
- Hydration usage is known.
- Signals usage is known.
- Zone.js usage is known.

## When Not to Use

- The project is AngularJS 1.x.
- The project is Angular 15.x or lower.
- The project is already Angular 17 or later.
- The previous Angular 15 -> 16 validation gate failed.
- Angular 16 changelog risk review failed.
- ngcc or View Engine dependency risk remains unresolved.
- The task is only control-flow migration.
- The task is only Signals refactoring.
- The task is only standalone migration.

## Mandatory Cross-Skill Routing

Before upgrading from Angular 16 to Angular 17, run:

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

For Angular 16, prefer stabilizing on the latest allowed Angular 16.2.x patch before moving to Angular 17.

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

## Recommended Cross-Skill Routing

Run these focused skills when detected:

- `skills/angular/upgrades/router/angular-router-v17-public-api-migration/SKILL.md`
- `skills/angular/upgrades/zone/angular-zonejs-imports-v17-migration/SKILL.md`
- `skills/angular/upgrades/hydration/angular-hydration-v17-risk-gate/SKILL.md`
- `skills/angular/upgrades/signals/angular-signals-mutate-to-update-v17/SKILL.md`
- `skills/angular/upgrades/styles/angular-remove-styles-on-destroy-v17/SKILL.md`
- `skills/angular/upgrades/components/angular-dynamic-component-docheck-v17/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`
- router configuration
- custom `UrlSerializer`
- absolute redirects
- `loadComponent` routes
- child routes of `loadComponent`
- Zone.js imports
- hydration config
- Signals usage
- `NgSwitch` usage
- `REMOVE_STYLES_ON_COMPONENT_DESTROY`
- dynamic component creation
- animation usage
- tests using router navigation
- tests using redirects
- tests using dynamic components
- tests using Zone.js imports
- tests using hydration/SSR
- current build/test/lint/e2e scripts
- production build scripts
- SSR/prerender scripts
- screenshot/golden test scripts

## Dependency Upgrade

### Node.js

Angular 17 supports Node.js 18.13.0 and newer.

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

### TypeScript

Angular 17 supports TypeScript 5.2 or later.

### Zone.js

Angular 17 supports Zone.js 0.14.x or later.

### Angular Core and CLI

Run:

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

If local CLI is unreliable, use:

```bash
npx @angular/cli@17 update @angular/core@17 @angular/cli@17
```

### Angular Material

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

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

or:

```bash
npx @angular/cli@17 update @angular/material@17
```

## Required Code Changes

### 1. Zone.js deep imports

Replace deep imports:

```ts
import 'zone.js/dist/zone';
import 'zone.js/bundles/zone-testing.js';
```

with:

```ts
import 'zone.js';
import 'zone.js/testing';
```

### 2. Router public API configuration

Move router configuration to `provideRouter` or `RouterModule.forRoot`.

Do not mutate router internals directly.

### 3. malformedUriErrorHandler migration

Handle URL parsing errors through `UrlSerializer.parse` instead of relying on `malformedUriErrorHandler`.

### 4. Absolute redirect behavior

Review routes with absolute redirects because Angular 17 no longer prevents additional redirects after them.

### 5. loadComponent child route inheritance

Review `loadComponent` child routes and `paramsInheritanceStrategy` when parent data must flow down.

### 6. Dynamic components and ngDoCheck

Review dynamic component creation if `ngDoCheck` side effects are involved.

### 7. Destroyed component styles removal

Review screens that may have relied on styles leaking after component destruction.

### 8. AnimationDriver.NOOP migration

Replace `AnimationDriver.NOOP` with `NoopAnimationDriver`.

### 9. NgSwitch strict equality

Review `NgSwitch` cases because comparison is now strict.

### 10. Signals mutate to update

Replace `mutate(...)` with immutable `update(...)` patterns where Signals are used.

### 11. Hydration API changes

Use supported hydration APIs only.

### 12. Optional modernizations not included

Do not automatically migrate to built-in control flow, deferrable views, standalone architecture, signals refactors, or zoneless experimentation during this hop.

## Do

- Run the Angular 16 changelog risk review before changing package versions.
- Keep changelog baseline, runtime requirements, and router/hydration risk explicit.
- Validate SSR and hydration when used.
- Validate dynamic components, NgSwitch, and style cleanup where present.
- Keep Material/MDC validation explicit if Material is used.

## Do Not

- Do not continue if Angular 16 changelog review failed.
- Do not keep Zone.js deep imports.
- Do not mutate router internals directly.
- Do not ignore absolute redirect loops.
- Do not mix control flow or Signals modernization into the hop.
- Do not rely on leaked component styles as architecture.

## Review Checklist

- [ ] Angular 16 changelog review passed.
- [ ] Node.js, TypeScript, and Zone.js are compatible.
- [ ] Zone.js deep imports are removed.
- [ ] Router configuration is public-API-based.
- [ ] Absolute redirects are reviewed.
- [ ] `loadComponent` inheritance is reviewed.
- [ ] Hydration behavior is validated where used.
- [ ] `NgSwitch` strict equality cases are reviewed.
- [ ] Signals `mutate` usage is removed or documented.
- [ ] Dynamic component behavior is validated.
- [ ] Destroyed component style cleanup 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.13.0
- TypeScript version is unsupported
- Zone.js version is unsupported
- build fails
- tests fail
- production build fails
- Angular CLI update is incomplete
- Angular Material update is incomplete in a Material project
- Zone.js deep imports remain
- router internals are still mutated directly
- malformed URI handling is unresolved
- absolute redirect loops are possible or untested
- critical `loadComponent` inheritance is broken
- dynamic component `ngDoCheck` side effects are unresolved
- component style removal breaks critical screens
- `AnimationDriver.NOOP` remains
- critical `NgSwitch` loose equality cases remain
- Signals `mutate` remains
- hydration behavior is unknown in SSR/hydrated apps
- Material/style regressions are unreviewed
- workspace config is unstable

## Expected Output

1. Upgrade summary.
2. Changelog baseline summary.
3. Router and hydration migration summary.
4. Validation result.
5. Gate decision.

## Exit Criteria

- Angular 16 changelog risk review has passed.
- Angular dependencies are upgraded to Angular 17-compatible versions.
- Angular CLI is upgraded to v17.
- Angular Material/CDK are upgraded to v17 only if used.
- Node.js 18.13.0+ compatibility is confirmed.
- TypeScript 5.2+ compatibility is confirmed.
- Zone.js 0.14.x+ compatibility is confirmed.
- Zone.js deep imports are migrated.
- Router configuration does not rely on removed direct mutation patterns.
- Hydration is validated where used.
- NgSwitch strict equality cases are reviewed.
- Signals mutate usage is removed or documented.
- Angular Material and style regressions are reviewed.
- Production build has been validated.
- Validation gate result is explicit.
- The next hop is not started automatically.