In part 2 of my blog series on AngularJS migration, I’ll discuss the different methods for migrating an application and highlight the tools and resources that make it possible.
Tools and Resources
ngMigration Assistant
In August 2018 Elana Olson from the Angular Developer Relations team at Google announced the launch of the ngMigration-Assistant. When run this command line tool will analyse a code base and produce statistics on code complexity, size and patterns used in an app. The ngMigration Assistant will then offer advice on a migration path and preparation steps to take before beginning the migration.
The goal of the ngMigration Assistant is to supply simple, clear, and constructive guidance on how to migrate an application. Here is some example output from the tool:
Complexity: 86 controllers, 57 AngularJS components, 438 JavaScript files, and 0 Typescript files. * App size: 151998 lines of code * File Count: 943 total files/folders, 691 relevant files/folders * AngularJS Patterns: $rootScope, $compile, JavaScript, .controllerRecommendationPlease follow these preparation steps in the files identified before migrating with ngUpgrade. * App contains $rootScope, please refactor rootScope into services. * App contains $compile, please rewrite compile to eliminate dynamic feature of templates. * App contains 438 JavaScript files that need to be converted to TypeScript. To learn more, visit https://angular.io/guide/upgrade#migrating-to-typescript * App contains 86 controllers that need to be converted to AngularJS components. To learn more, visit https://docs.angularjs.org/guide/component |
The ngMigration Assistant tool is a great place to start when considering migrating an AngularJS project. The statistics and advice it gives will help quantify the effort the migration will take and can highlight particular patterns that will need to be addressed. Be warned that the tool doesn’t cover everything and there will be additional areas of the application external libraries and some logic for example that will need reworking during migration. It’s a good first step but not comprehensive.
ngMigration Forum
The ngMigration Forum gathers together resources, guides and tools for AngularJS migration. The forum allows developers to ask questions and get answers on their migration problems, it also collates all the common issues that occur during migration.
The angular.io Upgrade Guide
The angular.io Upgrade Guide contains a number of examples and walkthroughs on how to proceed with an AngularJS migration. Written by the Angular team the guide addresses the most common cases and has a complete example of migrating the Phone Catalogue example application.
Deciding How to Migrate
There are 3 major approaches to migrating an AngularJS application to Angular.
Complete Rewrite in Angular
The first decision to make when considering migrating your Angular application is whether you will do it incrementally or not. If you need to support an existing application or the application is too large to fully migrate in a reasonable timeframe then an incremental upgrade may be the only path open. However, if the application is small enough or if you are able to stop supporting the existing application or allocate enough resources then a complete rewrite is usually the most straightforward approach.
Migrate the whole application without supporting the AngularJS version:
Pros
- You don’t have to worry about upgrading or downgrading components
- No interoperability issues between AngularJS and Angular
- Opportunity to refactor areas of the code
- Can benefit from Angular features immediately
Cons
- The application will be offline during the migration or you will need to copy the code base to a new repository
- You don’t see the benefits until the whole application is migrated which could take some time depending on the overall size
- Since you will not see the whole application running until the end of the migration you may discover issues as you build more features
Hybrid Applications
ngUpgrade
ngUpgrade is an Angular library that allows you to build a hybrid Angular application. The library can bootstrap an AngularJS application from an Angular application allowing you to mix AngularJS and Angular components inside the same application.
I will go into more detail on the ngUpgrade library in Part 3: Implementing the Migration but for now, it’s important to know that ngUpgrade allows you to upgrade AngularJS directives to run in Angular and downgrade Angular components to run in AngularJS.
Horizontal Slicing
When migrating using a Hybrid approach there are two methods that will gradually move your application from AngularJS to Angular. Each has its advantages and disadvantages which I’ll discuss next.
Horizontal Slicing is a term used to describe the method of migrating building block components first (low-level components like user inputs, date pickers etc) and then all components that use these components and so on until you have upgraded the entire component tree.
Image: Victor Savkin
The term references the way that components are migrated in slices cutting across the whole application.
Pros
- The application can be upgraded without any downtime
- Benefits are realised quickly as each component is migrated
Cons
- It requires additional effort to upgrade and downgrade components
Vertical Slicing
Vertical Slicing describes the method of migrating each route or feature of the application at a time. Unlike horizontal slicing views won’t mix AngularJS and Angular components instead each view will consist entirely of components from one framework or the other. If services or components are shared across the application then they are duplicated for each version.
Image: Victor Savkin
Pros
- The application can be upgraded while in production
- Benefits are gained as each route is migrated
- You don’t have to worry about compatibility between AngularJS and Angular components
Cons
- It takes longer to migrate a route so benefits aren’t seen as quickly as horizontal slicing
- Components and services may need to be duplicated if required by AngularJS and Angular versions
Effort Needed to Migrate
Which method you adopt depends entirely on your business objectives and size of the application. In most cases, I’ve found that the hybrid approach is required and more often than not I’ve used vertical slicing during the migration. Maintaining a single working application at all times has always been a priority in my experience. Since the applications have also been very large the cleanest way to organise the migration across multiple teams has been to split the application up either by feature or by route and migrate each one in turn.
The amount of effort required again depends on your particular circumstances (size of the code base, number of people etc). I’ve found that putting everyone to work on migration at once leads to confusion and in turn wasted effort. What I’ve found is that by having a small team begin the work, bootstrap the hybrid application and produce some migrated components and services the rest of the team spends left effort getting started and instead begins scaling out the migration.
Part 3: Implementing the Migration
In part 3 I’ll go into fine detail on what code changes need to happen in preparation for the migration and how the actual migration is done.
Sources
- 2 New Tools to help with AngularJS to Angular Migrations: https://blog.angular.io/migrating-to-angular-fc9618d6fb04
- Upgrading from AngularJS to Angular: https://angular.io/guide/upgrade#upgrading-from-angularjs-to-angular
- ngMigration-Assistant: https://github.com/ellamaolson/ngMigration-Assistant
- ngMigration-Forum: https://github.com/angular/ngMigration-Forum/wiki
- Two Approaches to Upgrading Angular Apps: https://blog.nrwl.io/two-approaches-to-upgrading-angular-apps-6350b33384e3
You can read part 3 of this series here: https://gofore.com/en/migration-from-angularjs-part-3/
You can read part 1 of this series here: https://gofore.com/en/migrating-from-angularjs-part-1/
