Developers who hail from the AngularJS camp usually all react the same way when they start exploring newer versions of the popular framework.
What becomes of my old code, and how much work is it going to be to switch?
Devotees of AngularJS (Angular 1.x.x) are right to have conerns over migration. Luckily, however, their fears are unfounded.

The Angular Team Has Your Back

If you’re exploring the idea of switching to Angular (Angular 2.x.x, and Angular 4.x.x), you probably have all sorts of questions and concerns, beginning with:

  • Do I need to migrate my working app to the latest Angular version?
  • How much impact and effort will I have to put into migration?

You’ll be glad to know that, just because Angular is now an option, doesn’t mean AngularJS is totally obsolete. But if you’re thinking of holding on until the very last moment with old Angular JS, then consider this: the Angular team spent a considerable amount of time and resources to fix and improve the framework. Shouldn’t that be a sign that, at the very least, you need to consider a migration plan sometime in the near future?

Consider Starting Fresh

Since Angular has a completely new way of thinking about the architecture of an application, the best approach will be to migrate any existing AngularJS application and start from scratch. This will allow you to better define the project structure, following all the new standards and conventions provided by Angular.

But what happens if you want to migrate but the effort is so daunting that it prevents you from starting at zero? Sometimes the client has other priorities or the application is so complex that it will take lot of time to complete the migration.

In cases like these, you can do a gradual migration, performing small changes until you’re at the point where you can remove AngularJS and run completely on Angular.

A Guide to Gradual Migration

In this post we will take a look at the process that a developer can follow to gradually migrate an AngularJS application to its new Angular form.

Changes in the Latest Angular versions

Before you start thinking about the upgrade process, we need to understand the main changes that have come about with Angular. Those changes are not going to be covered in this post, but if you want an in-depth understanding of Angular, you may want to check out this previous article.

But a quick summary might help. Here’s a list of what’s new in Angular. It’s crucial to consider these changes when thinking about upgrading:

  • Components: Components are the new building blocks when creating applications with Angular. Almost everything is a component, even the application itself.
  • Content Projection: This is the new transclusion, but aligned with the Web Components standard.
  • Dependency Injection: Instead of having a single injector for our entire application, in Angular each component comes with its own injector.
  • Dynamic Loading: The main idea is to allow developers to add new directives or controllers on the fly.

Steps to Take for Upgrading to Angular

1. Prepare Your Application
Some applications will be easier to migrate than others. A good approach is to begin by preparing your AngularJS application to be more fully aligned with Angular. We can perform the upgrade in an incremental way, by running the two frameworks side-by-side in the same application. Then, we’d move the AngularJS components to Angular one by one. For this, Angular provides an upgrade module that has been designed to allow incremental upgrading.

In order to start preparing our application, we can follow these steps. They should make the migration much easier:

  • Implement good practices provided by the Angular Style Guide: This guide provides patterns and practices that have proved to be successful in a variety of applications. The guide also contains good examples of how to organize your Angular code
  • Use a Module Loader: Using a module loader like SystemJS, Webpack, or Browserify. This will allow you to follow the same module pattern provided by the TypeScript or ES2015 and will also load files in big applications.
  • Migrate to TypeScript: We can start using TypeScript in our existing app by installing the compiler and renaming our files from *.js to *.ts. Doing this, we will have one less thing to do during the migration process. The added benefit is that we can start learning TypeScript before the actual migration process.
  • Use components directives: We’ve already mentioned that in Angular, everything is a component. We can start using this approach in our app with the components directives. That way, we can start reducing the number of controllers and try to transform duplicated code into directives.

2. Understand and Use the Upgrade Adapter
The upgrade module in Angular will allow you to start using it in your application and with frameworks coexisting at the same time. You can upgrade components and services in an incremental way, which can be really helpful if you have a big application that looks like it will take lots of effort to migrate. This means you can pick a component or a service and upgrade it to Angular without touching the rest of your code.

3. Upgrade the Components
Components in AngularJS applications must be modified in a certain way in order for the upgrade module to make them work with Angular. The components directives in AngularJS need to contains the following properties:

  • restrict: ‘E’
  • scope: {}
  • bindToController: {}
  • controllerAs
  • template or templateUrl
  • transclude (optional)
  • require (optional)

The components directives does not have to contain the following properties:

  • compile
  • replace: true
  • priority/terminal

4. Look at a Sample Migration in Action
Based on these properties, let’s try to migrate an AngularJS directive to Angular:

This example is a basic directive that displays a message. Let’s see how we can use it on Angular:

First, let’s take a look at the UpgradeAdapter class. This allows AngularJS and Angular to coexist in a single application. Using the method upgradeNg1Component, you can pass the directive name as a parameter (defined in the controllerAs property) and it will return an instance of the component directive that’s the same type as the Angular component. Now, our directive has been upgraded to Angular so we can pass it into the directives field of another Angular component decorator.Since the application is using both AngularJS and Angular , we still need to register the component using the old Angular way:

5. Upgrade the Services
Upgrading an AngularJS service to Angular is really simple: simply inject the AngularJS service into an Angular component as a provider, and then upgrade the provider.

Let’s try to upgrade the following AngularJS service:

Now, we have to inject this into an Angular component. This can be done using the UpgradeAdapter to make the service available to the Angular dependency injection system:

Now, we are able to use the service in an Angular component:

Recap: the Application Upgrade Process

Here are the steps that the Angular team suggests for upgrading an application to Angular:

  1. Include the Angular and ng-upgrade libraries with your existing application
  2. Pick a component which you would like to migrate
    – Edit the AngularJS directive’s template to conform to Angular syntax
    – Convert the directive’s controller/linking function into Angular syntax/semantics
  3. Use ng-upgrade to export the directive (now a Component) as an AngularJS component (this is needed if you wish to call the new Angular component from an AngularJS template)
  4. Pick a service which you would would like to migrate
    – Most services should require minimal to no change
    – Configure the service in Angular
    – (Optional) Re-export the service into AngularJS using ng-upgrade if it’s still used by other parts of your AngularJS code
  5. Repeat steps #2 and #3 in an order convenient for your application development
  6. Once no more services/components need to be converted, drop the top level AngularJS bootstrap and replace with Angular bootstrap

You can read more about these steps on this Angular team post or you can check the Angular Official Upgrade Guide.

It would be very difficult to migrate a large AngularJS application to Angular all at once. Also, you have to consider the cost and the effort for the migration, as well as the time your team has to spend making it happen.

The better way: a gradual migration using the approaches we’ve outlined here. This will help you to clean up your code and start implementing the improvements made possible by the new Angular features. Don’t be afraid to go for it and discover how great Angular can be.