Angular 13 to Angular 14 Upgrade

Purpose

Use this skill to upgrade an Angular 13.x application to Angular 14.x in one bounded major hop.

This hop is a high-control migration boundary because Angular 14 introduces typed forms and several Angular Material/CDK, Router, JSONP, animation, testing, and lazy-loading behavior changes. It upgrades only from Angular 13 to Angular 14 and must not continue to Angular 15 or later. The next hop must be handled by a dedicated follow-up skill.

When to Use

Use this skill when:

• The project is currently on Angular 13.x.
• The target hop is Angular 14.x.
• The route planner selected 13 -> 14 as the next step.
• The Angular 12 -> 13 validation gate passed.
• IE11 is not a hard requirement.
• Ivy is enabled.
• Angular Material usage is known.
• Angular Forms usage is known.
• Router usage is known.
• Test strategy is known.
• The workspace uses angular.json.

When Not to Use This Skill

Do not use this skill when:

• The project is AngularJS 1.x.
• The project is Angular 12.x or lower.
• The project is already Angular 14 or later.
• The previous Angular 12 -> 13 validation gate failed.
• IE11 is still a hard requirement.
• Ivy is disabled.
• Angular Material version is unknown in a Material project.
• Angular Forms usage is unknown in a form-heavy application.
• Router behavior is unknown in a routing-heavy application.
• The task is only Typed Forms migration without Angular version upgrade.
• The task is only Angular Material migration without Angular core upgrade.
• The requested change is Angular 14 to Angular 15.

For Angular 14 to Angular 15, route to:

skills/angular/upgrades/hops/angular-14-to-15/SKILL.md

Recommended Cross-Skill Routing

Typed Forms can become a large migration by itself.

If the project has many Angular Reactive Forms, route detailed form migration to:

skills/angular/upgrades/forms/angular-typed-forms-migration/SKILL.md

Default enterprise stance:

Do not migrate all forms to typed forms in the same commit as the Angular 14 upgrade unless the app is small and well tested.

Inputs Expected

• package.json
• lock file: package-lock.json, yarn.lock, or pnpm-lock.yaml
• Angular package versions
• Angular CLI version
• Angular Material version
• Angular CDK version
• TypeScript version
• RxJS version
• zone.js version
• Node.js version
• package manager version
• angular.json
• tsconfig.json
• tsconfig.app.json
• tsconfig.spec.json
• Angular Forms usage:
  • FormControl
  • FormGroup
  • FormArray
  • FormBuilder
  • AbstractControl
  • custom validators
  • async validators
  • custom form abstractions
• existing untyped forms usage
• custom classes extending FormControl, FormGroup, FormArray
• TestBed usage
• aotSummaries
• Angular Material Stepper usage
• Angular Material Chips usage
• Material mixin abstractions
• Material list usage
• Material SelectionList usage
• Material Harness usage
• JSONP usage
• router resolvers
• lazy-loaded routes
• initialNavigation
• pathMatch
• custom LocationStrategy
• custom AnimationDriver
• RouterOutletContract
• Router.initialUrl
• query params with plus sign
• Protractor/CDK testing usage
• current build/test/lint/e2e scripts
• screenshot/golden test scripts if present

Compatibility by Version

Area	Recommended strategy	Observations
Angular 13.x source	Upgrade to Angular 14.x only	Do not jump to a later major in this skill.
Angular CLI	Upgrade to CLI 14	Keep workspace validation explicit.
TypeScript	Align to Angular 14-compatible TypeScript 4.6	Verify against project evidence.
Angular Material	Upgrade to Material 14 only if used	Do not go beyond Angular 14 in this hop.
Forms	Choose typed or untyped bridge explicitly	Do not migrate all forms mechanically.

If a version cannot be confirmed from the project files, mark it as verify in project.

Procedure

1. Inspect dependency versions and lockfile evidence.
2. Check Node.js, CLI, workspace, and validation-gate status.
3. Review the Typed Forms strategy before changing code.
4. Scan the codebase for Angular 13-era deprecated or risky APIs.
5. Classify each occurrence by impact and required change.
6. Apply the bounded dependency upgrade to Angular 14.
7. Convert only the code required by the hop.
8. Run validation commands that exist in the repository.
9. Set the gate result explicitly.
10. Stop after Angular 14. Do not begin the next hop.

Do

• Keep the hop bounded to Angular 13 -> Angular 14.
• Review forms strategy, Material/CDK, router, JSONP, resolvers, harnesses, lazy loading, and test behavior.
• Use the Typed Forms migration skill for detailed form conversion when the diff is large.
• Use the previous validation gate as a hard gate condition.
• Stop after validation and report the next hop.

Recommended Patterns

Upgrade Angular packages to Angular 14-compatible versions using the project-supported package manager and CLI workflow.

Use ng update or the repository-supported equivalent for Angular CLI 14 and Angular core 14.

Keep typed forms strategy explicit:

• small, isolated forms -> typed forms
• large legacy forms -> untyped bridge
• mixed migration -> only when isolated and documented

Treat the validation gate as part of the hop, not a later concern.

Anti-Patterns

• Jumping from Angular 13 directly to Angular 21.
• Starting Angular 15 migration in the same change.
• Migrating all forms to typed forms in one huge diff.
• Updating Angular Material beyond v14.
• Updating TypeScript beyond Angular 14 compatibility.
• Removing form validation behavior while typing forms.
• Passing JSONP headers by moving secrets to query params.
• Keeping Protractor-only CDK testing APIs.
• Depending on private Material/CDK APIs.
• Ignoring Material list CSS changes.
• Ignoring router timing test failures.
• Casting all routes with as any.
• Ignoring invalid lazy route config errors.
• Rewriting router architecture during this hop.
• Removing AngularJS from hybrid apps during this hop.
• Claiming success without build/test/production validation.
• Passing the gate when Forms, Material/CDK, Router, JSONP, or tests are unknown.

Do Not

• Do not continue to Angular 15 or later.
• Do not change unrelated application architecture.
• Do not force later Angular patterns into this hop.
• Do not run commands that do not exist in package.json.
• Do not claim completion without validation evidence.

Review Checklist

• Angular 13.x source version was confirmed.
• Angular packages were aligned to Angular 14.x.
• Typed Forms strategy was selected.
• CLI workspace status was checked.
• TypeScript compatibility was checked.
• Angular library compatibility was checked.
• Deprecated APIs were classified and handled.
• Material and style regressions were reviewed.
• Router, JSONP, and test behavior were reviewed.
• Validation commands were run or explicitly unavailable.
• Validation gate result was explicit.
• The next hop was not started automatically.

Validation Minimum

Read package.json first. Only run scripts that exist.

Preferred order when available:

• build
• test
• lint
• e2e

For production build validation:

• ng build --configuration production

For Angular Material projects, run available visual checks.

For screenshot/golden tests, run them only if scripts exist.

If validation fails, report:

• command
• error summary
• likely cause
• safe next action
• whether the next hop is blocked

Validation Gate

This hop must close with an explicit gate decision.

Gate result must be one of:

PASS
PASS_WITH_WARNINGS
FAIL_BLOCK_NEXT_HOP

Use FAIL_BLOCK_NEXT_HOP when:

• Node.js is lower than 14.15.0
• build fails
• tests fail
• production build fails
• Angular CLI update is incomplete
• Angular Material update is incomplete in a Material project
• TypeScript 4.6 errors remain unresolved
• Typed Forms migration breaks critical forms
• form strategy is unknown in a forms-heavy app
• custom FormGroup/FormArray subclasses are incompatible
• JSONP uses headers and replacement strategy is unknown
• critical resolvers have multi-emission behavior unknown
• removed CDK Protractor APIs remain
• Material Stepper/Chips/List/SelectionList changes are unresolved
• custom Material/CDK subclasses are incompatible
• router initialNavigation uses removed values
• route pathMatch typing remains broken
• custom lazy loader typing is unresolved
• router redirect timing tests remain broken
• custom LocationStrategy lacks getState
• custom AnimationDriver lacks getParentElement
• invalid lazy route configs remain
• custom RouterOutlet integrations are unresolved
• Router.initialUrl string assignments remain
• Material/style regressions are unreviewed
• workspace config is unstable

Use PASS_WITH_WARNINGS when:

• untyped forms bridge is used with documented follow-up
• large typed forms migration is intentionally postponed
• non-critical resolver behavior requires follow-up
• non-critical Material harness changes are pending
• Protractor migration is planned but not blocking the app
• visual differences are documented and accepted

Risks

• Typed Forms can become a large migration if not separated.
• Material/CDK changes can surface visual or harness regressions.
• Router and testing changes can create subtle behavior shifts.
• JSONP, resolver, and lazy-load changes can break edge cases.
• Production build changes can expose CSS or optimization issues.

Expected Output

When this skill is used, return:

1. Source Angular version.
2. Target Angular version.
3. Typed Forms strategy.
4. Angular CLI and workspace status.
5. Applied dependency and code changes.
6. Validation commands and results.
7. Gate result.
8. Remaining risks.
9. Next hop skill.

Exit Criteria

This skill is complete only when:

• Angular packages are upgraded to Angular 14-compatible versions.
• Angular CLI is upgraded to v14.
• Angular Material/CDK are upgraded to v14 only if used.
• TypeScript is aligned to Angular 14-compatible TypeScript 4.6.
• Node.js 14.15.0+ compatibility is confirmed.
• Typed Forms strategy is explicit.
• Critical forms are tested.
• aotSummaries is removed from TestBed.
• Material stepper/chips/selection-list changes are handled or documented.
• JSONP requests do not send headers.
• Resolver first-emission behavior is reviewed.
• Removed CDK Protractor testing entry point is not used.
• mixinErrorState abstractions implement stateChanges.
• Router, lazy route, and timing changes are handled.
• Angular Material and style regressions are reviewed.
• Production build has been validated.
• validation gate result is explicit.
• the next hop is not started automatically.