@angular/upgrade

Hybrid Angular.js (1.x) ↔ Angular interop. Lets a single page run both an Angular.js module and an Angular standalone application side-by-side, sharing change detection, DI, and the DOM.

Purpose

The package supports the long-tail migration story for apps that started in Angular.js 1.x and are gradually adopting Angular. It provides:

• UpgradeModule / downgradeComponent / downgradeInjectable — let an Angular.js app consume Angular components and services.
• upgradeAdapter (legacy) and the static counterparts — let an Angular app consume Angular.js components.
• A coordinated change-detection driver so that an Angular zone tick and an Angular.js $digest interleave correctly.

Directory layout

packages/upgrade/
├── src/
│   ├── common/         # Shared logic between dynamic and static adapters
│   ├── dynamic/        # Legacy dynamic adapter (UpgradeAdapter)
│   ├── static/         # Modern static adapter (UpgradeModule)
│   └── ...
└── static/
    └── testing/        # Test harness

Key abstractions

Type / function	File	What it is
UpgradeModule	packages/upgrade/src/static/upgrade_module.ts	The static adapter root.
downgradeComponent	packages/upgrade/src/common/downgrade_component.ts	Wraps an Angular component as an Angular.js directive.
downgradeInjectable	packages/upgrade/src/common/downgrade_injectable.ts	Wraps an Angular service as an Angular.js service.
UpgradeComponent	packages/upgrade/src/common/upgrade_component.ts	Wraps an Angular.js directive as an Angular component.

Interop model

graph TD
  Angular1["Angular.js 1.x app<br/>(angular.module)"] --> Adapter["UpgradeModule"]
  Adapter --> Angular2["Angular standalone app"]
  Angular1 -.->|downgradeComponent| Angular2
  Angular2 -.->|UpgradeComponent| Angular1
  Adapter --> CD["Coordinated change detection<br/>(ngZone + $digest)"]

The adapter ensures every $digest and every Angular tick sees the same DOM state. Mismatches cause infinite-loop or stale-state bugs that are hard to debug; the adapter has a published set of constraints that pnpm test enforces.

Integration points

• @angular/core — uses NgZone and ApplicationRef for tick coordination.
• @angular/platform-browser — uses the dynamic platform for JIT compilation when needed.
• AngularJS (1.x) — peer-listed in package.json (multiple 1.5/1.6/1.7/1.8 builds present for testing).

Status

The package is in maintenance — not actively expanding. The recommendation for new code is to stop using it; for existing hybrid apps, it's stable.

Entry points for modification

• A new upgrade adapter behavior: extend packages/upgrade/src/static/.
• A new test scenario: add an integration test under integration/ and a corresponding spec in test/.