Using AngularJS Upgrade (ng-upgrade) for migration

Migrating from AngularJS to Angular can be challenging, especially for large applications. ngUpgrade is a hybrid approach that allows running AngularJS and Angular together during migration. This enables a step-by-step transition instead of a full rewrite.

1. What is ngUpgrade?

ngUpgrade is a library that allows AngularJS and Angular components to coexist in the same application.
It provides APIs for bootstrapping and communication between both frameworks.
Ideal for gradual migration instead of rewriting everything at once.

Best suited for large applications that can’t be migrated in one step.

2. Migration Strategies Using ngUpgrade

There are two primary approaches:

A. Downgrade Angular Components in AngularJS

Convert Angular components to work inside AngularJS.
Use ngUpgrade to bootstrap Angular in AngularJS.
Slowly replace AngularJS components with Angular components.

Allows using modern Angular features in an AngularJS app.

B. Upgrade AngularJS Components in Angular

Convert AngularJS components into Angular-compatible components.
Use ngUpgrade to bootstrap AngularJS in Angular.
Slowly refactor AngularJS components and services to Angular.

Preferred for transitioning to a fully Angular-based app.

3. Step-by-Step Migration Using ngUpgrade

Step 1: Install Angular and ngUpgrade

In your AngularJS project, install Angular and ngUpgrade:

npm install @angular/core @angular/upgrade @angular/common @angular/compiler --save

Step 2: Bootstrap Angular Inside AngularJS

Modify index.html to bootstrap both AngularJS and Angular.

<html ng-app="myApp">
  <body>
    <app-root></app-root>
  </body>
</html>

In main.ts:

import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { UpgradeModule } from '@angular/upgrade/static';
import { NgModule } from '@angular/core';

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

  ngDoBootstrap() {
    this.upgrade.bootstrap(document.body, ['myApp']);
  }
}

platformBrowserDynamic().bootstrapModule(AppModule);

This allows AngularJS and Angular to run together.

Step 3: Upgrade AngularJS Services to Angular

Convert an AngularJS service to Angular service:

AngularJS Service (Before)

angular.module('myApp').service('myService', function () {
  this.getData = function () {
    return 'Hello from AngularJS';
  };
});

Angular Service (After)

import { Injectable } from '@angular/core';

@Injectable({ providedIn: 'root' })
export class MyService {
  getData() {
    return 'Hello from Angular';
  }
}

Refactoring services makes migration easier.

Step 4: Use Angular Components in AngularJS

Convert an Angular component into an AngularJS directive.

Angular Component

import { Component } from '@angular/core';

@Component({
  selector: 'my-angular-component',
  template: `<h2>Angular Component in AngularJS</h2>`,
})
export class MyAngularComponent {}

Expose it to AngularJS

import { downgradeComponent } from '@angular/upgrade/static';

angular.module('myApp').directive('myAngularComponent', downgradeComponent({
  component: MyAngularComponent,
}));

Now, <my-angular-component> can be used inside AngularJS templates.

Step 5: Replace AngularJS Components with Angular

Start migrating small, reusable components to Angular.
Gradually move to services, directives, and controllers.
Finally, remove AngularJS bootstrap and switch to full Angular.

4. When to Use ngUpgrade?

Large applications that need gradual migration.
Critical production apps where a full rewrite is risky.
Hybrid development teams working with both AngularJS and Angular.

Avoid ngUpgrade if:
Your app is small and can be rewritten quickly.
You don’t want to maintain both frameworks together.

5. Final Steps After Migration

Remove ngUpgrade and AngularJS dependencies.
Fully switch to Angular routing.
Use Angular CLI for better build performance.

Now, your app is fully migrated to Angular!