AngularJS to Angular Blueprint
Migrate AngularJS 1.x to modern Angular using the ngUpgrade hybrid bridge, converting components and services leaf-first before removing the legacy framework. Reduces security exposure and unlocks TypeScript and RxJS.
What and Why
AngularJS (Angular 1.x) reached end of long-term support in December 2021. Its scope-based digest cycle, two-way binding, and $controller model differ fundamentally from modern Angular (2+), which uses TypeScript, components, dependency injection tokens, and RxJS. Running an unsupported framework leaves you without security patches and unable to hire. This blueprint migrates incrementally using the official @angular/upgrade (ngUpgrade) bridge so the two frameworks run side by side during the transition.
Phases
Assessment. Inventory directives, controllers, services, and $http calls. Catalogue third-party AngularJS modules (ui-router, angular-translate) and find Angular equivalents. Measure test coverage; AngularJS apps often rely on Karma/Jasmine, which carries forward.
Hybrid bootstrap. Introduce a build toolchain (Angular CLI or a Webpack setup) and bootstrap the app with UpgradeModule. Both frameworks now share the DOM and digest/zone lifecycles. Add TypeScript and route the app through Angular's bootstrap.
Component migration. Convert AngularJS components leaf-first using downgradeComponent to embed new Angular components inside AngularJS templates, and UpgradeComponent for the reverse. Replace $scope bindings with @Input/@Output. Migrate ui-router states to the Angular Router incrementally.
Service migration. Downgrade and upgrade injectables so a single instance is shared. Replace $http with HttpClient and promises with RxJS Observables. Centralize API typing with interfaces generated from OpenAPI.
Cutover. Once all components and services are Angular, remove UpgradeModule, AngularJS, and jQuery (often a transitive dependency). Bootstrap purely with Angular, enable strict mode, and tree-shake.
Key Risks and Mitigations
- Skills gap: RxJS and DI tokens are unfamiliar to AngularJS developers. Pair-program and run internal workshops before scaling migration.
- Dual change-detection cost: Hybrid mode runs both digest and Zone.js; keep the hybrid window short and watch performance.
- Regression: Lock behavior with end-to-end tests (Cypress/Playwright) before converting each route.
Recommended Tooling
Angular CLI, @angular/upgrade, TypeScript in allowJs mode during transition, Karma/Jasmine for unit tests, Playwright for end-to-end coverage. Use Angular's ng update schematics once fully migrated to stay current.
Success Metrics
Reduced bundle size after dropping AngularJS and jQuery, faster lead time for new features, rising TypeScript coverage, and elimination of unsupported-dependency findings.
Prerequisites
A reliable end-to-end test suite, a Node.js build pipeline, and a component inventory. Freeze large feature work in modules being actively migrated to limit churn.