ngUpgrade (UpgradeModule)

ngUpgrade is the official Angular package, @angular/upgrade, that lets AngularJS and Angular run in one application and use each other's components and services.

ngUpgrade is the common name for the @angular/upgrade/static package. Its central piece is UpgradeModule. You import it into the root Angular module and use it to bootstrap the existing AngularJS application from inside Angular. From then on both frameworks run together, with dependency injection and change detection connected.

The package gives you tools in both directions:

• downgradeComponent and downgradeInjectable make Angular code usable from AngularJS.
• UpgradeComponent wraps an AngularJS component so that an Angular template can use it.
• AngularJS services can be provided to Angular through a factory that reads them from $injector.

Example

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() {
    this.upgrade.bootstrap(document.body, ['legacyApp'], { strictDi: true });
  }
}

The ng-app attribute has to be removed from the HTML, because Angular now starts AngularJS.

Common misunderstanding

ngUpgrade does not convert code. It is a runtime bridge, and every controller, directive and service still has to be rewritten by a person or with a tool.

It also expects a certain shape from the AngularJS code. Applications that use components, controllerAs and a module bundler are much easier to bridge than applications built on $scope inheritance and script tags. Some preparation work usually comes first. The steps are in How to migrate AngularJS to Angular without downtime.

Related terms

• Hybrid application (AngularJS + Angular)
• Downgrade (downgradeComponent / downgradeInjectable)
• Incremental migration