Using Nrwl/Nx to Upgrade You AngularJS Applications to Angular

Many organizations have large AngularJS 1.x applications deployed to production. These applications may be built by multiple teams from different lines of business. They may use different routers and state management strategies. Rewriting such applications all at once, or big bang migrations, is not just impractical, it is often impossible, and mainly for business reasons. We need to be able to upgrade gradually.

To upgrade an AngularJS 1.x application to Angular gradually, we need to bootstrap it in a hybrid mode, where we can mix and match AngularJS and Angular components and services. Doing this right is nuanced, so a lot of folks get frustrated with it.

At Nrwl, after helping many teams set it up, we created a few generators to make this process easier. We open sourced them as part of Nrwl Nx a few weeks ago. Using these generators we can set up a hybrid application in seconds.

Two Ways to Bootstrap a Hybrid App

Some folks value the dev ergonomics and the flexibility of the upgrade process more than the performance of the hybrid applications. Others value the performance. That’s why there are two ways to bootstrap a hybrid application.

• UpgradeModule bootstraps both the AngularJS and Angular frameworks in the Angular zone and wires up the two change detection systems, so it feels like we are running one application. When using UpgradeModule, we always start with an Angular application, which “contains” the AngularJS application, hence the name UpgradeModule — we upgrade the AngularJS application.
• downgradeModule bootstraps AngularJS outside of the Angular zone and keeps the two change detection systems separate. When using downgradeModule, we always start with an AngularJS application, which “contains” an Angular application, hence the name downgradeModule — we downgrade the new application.

Misko Hevery explains the difference between the two in this talk.

Regardless of the way we choose to do it, we can can set it up in seconds using Nrwl/Nx.

Nrwl/Nx

Nrwl Extensions for Angular (Nx) is an open source toolkit for enterprise Angular applications. One of the things Nx provides is the generators to set up UpgradeModule and downgradeModule.

Creating an Nx Workspace

The first thing we need to do is to create an Nx Workspace, which is an Angular CLI project with Nx in it.

The easiest way to do is by running the following command:

curl -fsSL https://raw.githubusercontent.com/nrwl/nx/master/packages/install/install.sh | bash -s tusk-desk

Next, let’s create an app in it, like this:

ng generate app new-tusk-desk

If we run ng serve, we will the following:

UpgradeModule

Let’s say we decided to use UpgradeModule for our hybrid app.

We can set it up by running ng generate upgrade-module tusk-desk, where tusk-desk is the name of the AngularJS module. We will end up see something like this:

create apps/new-tusk-desk/src/tusk-desk-setup.ts (890 bytes)
create apps/new-tusk-desk/src/hybrid.spec.ts (813 bytes)
update apps/new-tusk-desk/src/app/app.module.ts (712 bytes)
update package.json (1753 bytes)

Let’s look at each of the affected files.

package.json

The upgrade-module schematic updated package.json to add the @angular/upgrade and AngularJS packages. If you use a different version of AngularJS, or you don’t use npm to get it, update the package.json file accordingly.

app.module.ts

The schematic updated app.module.ts, to look like this:

It rewrote the bootstrap logic to use UpgradeModule.

tusk-desk-setup.ts

This file bridges the two frameworks. It imports AngularJS and the legacy tusk-desk application. (We can pass --angularJsImport to customize how the application gets imported. We can also remove the import altogether if the application is available globally.)

The schematic also downgraded AppComponent.

So it is actually AngularJS that will bootstrap that component in place of the <app-root> element on index.html.

Running the App

If we run npm install and then run ng serve, we will see the familiar “Welcome to an Angular CLI app build with Nrwl Nx!”.

It appears that nothing has changed, but the application is actually running in the hybrid mode. We can upgrade an AngularJS component and use it inside AppComponent. We can update index.html to bootstrap an existing AngularJS component, and we can use the downgraded AppComponent in it.

downgradeModule

Now let’s say we want to use downgradeModule for our hybrid app.

We can set it up by running ng generate downgrade-module tusk-desk, where tusk-desk is the name of the AngularJS module. We will end up seeing something like this:

update apps/new-tusk-desk/src/main.ts (956 bytes)
update apps/new-tusk-desk/src/app/app.module.ts (370 bytes)
update package.json (1757 bytes)

Let’s look at each of the affected files.

package.json

Similar to the previous schematic, downgrade-module updated package.json to add the @angular/upgrade and AngularJS packages.

app.module.ts

Similar to upgrade-module, this schematic rewrote AppModule not to bootstrap AppComponent. All the bootstrapping logic has been moved to main.ts.

main.ts

There is a lot to unpack here.

First, we are importing the AngularJS and the existing tusk-desk application. We can adjust the way we import the two. For instance, if AngularJS is already present on the page, we can remove import * as angular from angular.

Second, we are converting AppModule into an AngularJS module by using downgradeModule.

Next, we are downgrading AppComponent.

And, finally, we are bootstrapping the existing tusk-desk application with the downgraded module.

Running the App

If we run npm install and then run ng serve, we will see “Welcome to an Angular CLI app build with Nrwl Nx!”.

As with UpgradeModule, it looks like nothing has changed, but the application is actually running in the hybrid mode. This means that we can upgrade an AngularJS component and use it inside AppComponent. We can update index.html to bootstrap an existing AngularJS component, where we can use the downgraded AppComponent.

Learn More About Nx

Nrwl/Nx helps you set up a hybrid application in seconds, but it can do a lot more. It can help you build reusable libraries, set up state management and lazy loading. Check out Nrwl/Nx for more information.

You can also attend my workshop at AngularConnect to learn how to use Nx to upgrade AngularJS applications to Angular:

Victor Savkin is a co-founder of Nrwl — Enterprise Angular Consulting.

Follow @victorsavkin to read more about Angular.