/angular-migration

name: angular-migration
description: "Master AngularJS to Angular migration, including hybrid apps, component conversion, dependency injection changes, and routing migration."
risk: critical
source: community
date_added: "2026-02-27"

Supporting material availability

This catalog copy contains the inline guidance below, but does not include the following supporting paths. They are external prerequisites, not bundled files:

• `<support-root>/references/hybrid-mode.md`
• `<support-root>/references/component-migration.md`
• `<support-root>/references/dependency-injection.md`
• `<support-root>/references/routing.md`
• `<support-root>/assets/hybrid-bootstrap.ts`
• `<support-root>/assets/migration-timeline.md`
• `<support-root>/scripts/analyze-angular-app.sh`

Ask for the original supporting material or an existing installation before using a step that depends on these paths; this catalog does not identify a verified download source for them. Resolve each path relative to that installation, inspect its contents, and verify any applicable license and execution prerequisites. Do not run a command or claim a referenced procedure was followed until its required file exists. Do not fabricate the missing scripts or treat an unrelated file with the same name as equivalent. Independent steps fully documented here can proceed within the user’s authorized scope; report any dependent step as unavailable.

Angular Migration

Master AngularJS to Angular migration, including hybrid apps, component conversion, dependency injection changes, and routing migration.

Use this skill when

• Migrating AngularJS (1.x) applications to Angular (2+)
• Running hybrid AngularJS/Angular applications
• Converting directives to components
• Modernizing dependency injection
• Migrating routing systems
• Updating to latest Angular versions
• Implementing Angular best practices

Do not use this skill when

• You are not migrating from AngularJS to Angular
• The app is already on a modern Angular version
• You need only a small UI fix without framework changes

Instructions

1. Assess the AngularJS codebase, dependencies, and migration risks. 2. Choose a migration strategy (hybrid vs rewrite) and define milestones. 3. Set up ngUpgrade and migrate modules, components, and routing. 4. Validate with tests and plan a safe cutover.

Safety

• Avoid big-bang cutovers without rollback and staging validation.
• Keep hybrid compatibility testing during incremental migration.

Migration Strategies

1. Big Bang (Complete Rewrite)

• Rewrite entire app in Angular
• Parallel development
• Switch over at once
• **Best for:** Small apps, green field projects

2. Incremental (Hybrid Approach)

• Run AngularJS and Angular side-by-side
• Migrate feature by feature
• ngUpgrade for interop
• **Best for:** Large apps, continuous delivery

3. Vertical Slice

• Migrate one feature completely
• New features in Angular, maintain old in AngularJS
• Gradually replace
• **Best for:** Medium apps, distinct features

These are partial migration examples, not a complete bootstrap: align AngularJS module names (`myAngularJSApp` versus `myApp`), register/declaratively import components and forms, configure HttpClient, and select compatible Angular/TypeScript/Node versions. The DI decorator fragments require a real NgModule class and imports. AngularJS `$http` resolves a response wrapper while HttpClient resolves its body; preserve this semantic difference. Test routing ownership and change detection before switching traffic.

Hybrid App Setup

// main.ts - Bootstrap hybrid app
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { UpgradeModule } from '@angular/upgrade/static';
import { AppModule } from './app/app.module';

platformBrowserDynamic()
  .bootstrapModule(AppModule)
  .then(platformRef => {
    const upgrade = platformRef.injector.get(UpgradeModule);
    // Bootstrap AngularJS
    upgrade.bootstrap(document.body, ['myAngularJSApp'], { strictDi: true });
  });

// app.module.ts
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { UpgradeModule } from '@angular/upgrade/static';

@NgModule({
  imports: [
    BrowserModule,
    UpgradeModule
  ]
})
export class AppModule {
  constructor(private upgrade: UpgradeModule) {}

  ngDoBootstrap() {
    // Bootstrapped manually in main.ts
  }
}

Component Migration

AngularJS Controller → Angular Component

// Before: AngularJS controller
angular.module('myApp').controller('UserController', function($scope, UserService) {
  $scope.user = {};

  $scope.loadUser = function(id) {
    UserService.getUser(id).then(function(response) {
      $scope.user = response.data;
    });
  };

  $scope.saveUser = function() {
    UserService.saveUser($scope.user);
  };
});

// After: Angular component
import { Component, OnInit } from '@angular/core';
import { UserService } from './user.service';

@Component({
  selector: 'app-user',
  template: `
    <div>
      <h2>{{ user.name }}</h2>
      <button (click)="saveUser()">Save</button>
    </div>
  `
})
export class UserComponent implements OnInit {
  user: any = {};

  constructor(private userService: UserService) {}

  ngOnInit() {
    this.loadUser(1);
  }

  loadUser(id: number) {
    this.userService.getUser(id).subscribe(user => {
      this.user = user;
    });
  }

  saveUser() {
    this.userService.saveUser(this.user).subscribe({
      next: saved => { this.user = saved; },
      error: error => { /* Display an appropriate UI error; do not log user data. */ }
    });
  }
}

AngularJS Directive → Angular Component

// Before: AngularJS directive
angular.module('myApp').directive('userCard', function() {
  return {
    restrict: 'E',
    scope: {
      user: '=',
      onDelete: '&'
    },
    template: `
      <div class="card">
        <h3>{{ us