AngularJS migration — the roadmap

Cats love Eloquent JavaScript — photo from — credits goes to Michael Auer

If you are responsible of a legacy large scale AngularJS application, and have been thinking ways to migrate to Angular without breaking your boss’s heart, congratulations: We are in same boat!

Legacy it is hard to believe AngularJS(aka Angular 1.x) is legacy! It has been a heck of bumpy 6 years ride! With the rise of ES6/ES7, Web Component and renaissance of reactive paradigm, the threat for Angular to survive required a complete re-write. Now you are here managing the chaos, since the core team never planned a soft transition with this rewrite.

Large scale: It is fair to say that a ~20K LoC codebase is large. If your codebase is 5K LoC or less, Big Bang(re-write the whole damn thing) may an option for you(at your own peril). The scenario is different If you have 20K+ LoC codebase in production, with limited time and resources. A soft transition, also known as incremental suits better you needs. Incremental technique is non-obstructive as it fits in daily refactoring process. In process, you will be able to run your daily business as usual.

Scenario: You don’t need to learn TypeScript/Dart or ES6/ES7 to start the migration. Most parts of your codebase dependencies(libraries) may not be ready for migration yet. Moreover, you can write Angular with Good Ole JavaScript. In addition to upgrading to Angular 2, It is time you target multiple platforms(Web/Mobile/Desktop/TV and Things) using the same codebase, thinking in terms of PWA to make all your visitors happy regardless of browser/platform, eliminate scope soup+speedup your Angular 1.x by adding reactive(Rx or Redux) super powers. All of these, continuously shipping latest code with fixed bugs.


  • Beef up your tests — cover 100% of codebase, soft spots such as forms, functions/models/CSS classes used in templates.
  • Upgrade to latest AngularJS 1.x before Angular 2 (aka 4.x)
  • Upgrade dependencies(underscore, ui-router, etc) to latest versions
  • Move all inline CSS to standalone style sheets
  • Optional: adopt BEM CSS it will help when you start Componentization
  • Name all anonymous functions(Services/Filters/Directives/Events)
  • Decouple Angular constructs in favor of standalone JS functions(more on this to come).
  • Adopt Skinny Controllers, and move heavy lifting into your Services
  • Adopt ControllerAs syntax in your existing Controllers and Directives
  • Transfer DOM manipulation code from Directive Controllers to Linking functions(It is a good practice anyways)
  • Directive Componentization — all directives without Link function
  • Componentinzation of Controllers
  • Componentization of UI-Router(if used)
  • Update Component data-binding(is a bit different) and inter component data transfer(communication)
  • Replace $scope dependencies with reactive components(redux or rx)
  • Upgrade tooling to support babel(or any ES6/7 transpiler)
  • Rewrite functions, variable and classes per ES6/7 or TypeScript
  • Include Angular 2 (or 4.x) in your codebase
  • Rewrite Components(search+replace), Services(not required) per Angular 4.x specification(Annotations, etc)
  • Rewrite bootstrapping logic
  • Enhance UI-Router(to support Angular 2/4.x)
  • Remove Angular 1.x
  • Hooray! … may be not so fast!

Reading list

  1. When to refactor
  2. How often should you refactor? refactor early, refactor often!
  3. The Road to Angular 2.0 part 6: Migration
  4. ngMigrate cheat sheet to migrate to Angular
  5. Refactoring Angular Apps to Component Style
  6. How I’ve Improved My Angular Apps by Banning ng-controller
  7. ControllerAs
  8. “Fat model, skinny controller” is a load of rubbish
  9. Avoiding Anonymous JavaScript functions + Minimal Angular Module
  10. Angular 2 Core
  11. Why “Progressive Web Apps vs. native” is the wrong question to ask
  12. Code Reuse in Angular 2 Native Mobile Apps with NativeScript
  13. Building Mobile Apps with Angular 2 and NativeScript
  14. Some really large codebases
  15. Crazy Small Angular 2 Tutorial for everything you need right now

Gosh, You rock If you read all above goodness! Thank You! Your recommendation motivates me to follow up this post with techniques I use while upgrading — a platform that makes it possible for you to rent stuff from your friends and neighbours. It is green sharing economy, to curve consumerism and save you thousands in credit card debts ;-)