AngularJS 2.0 Migration Guide

Introduction

As of today, Angular is the most widely used web development framework. It's MV-whatever framework caught the eye of many web developers in recent years. It's a framework developed to support the end to end operations.

Angular 2.0 team has introduced new change detection system for faster rendering, promises to support isomorphic (server-side) rendering, and sets out to give tough competition to UI specific libraries such as ReactJS.

Having said that, it's a good time to learn about Angular 2.0 but it's more important to learn migration of Angular 1 applications to Angular 2.0.

Topics to be Covered

1. Migration phases and Levels
2. Migration Levels
3. Phase 1
   • Level 1 : Building the base
   • Level 2 : Angular 2.0 armory
4. Phase 2 : Upgrade to Angular 2.0
5. Learning Resources & References

Migration Process Phases

Migration Phases

The release of Angular 2.0 is quite possible by 2016. It’s a good time to learn about the migration process. There are two phases:

1. Preparation
2. Upgrade

This guide provides in-depth preparation steps for the migration. Actual upgrade and adding Angular 2.0 into the project build will be included with the release.

Migration Steps – Level 1

1. Follow the John Papa’s Styleguide for Angular 1 development
2. Update to the latest version of Angular 1
3. All new development using components
4. Switch controllers to components (component directives)
5. Remove incompatible features (specific to Angular 2) from directives
6. Implement manual bootstrapping (No more ng-app)

Migration Steps – Level 2

1. Add TypeScript transpilation and build
2. Start using ES6 or Javascript 2015
3. Switch controllers and services to ES6 Classes
4. Add Angular 2.0 to your project - (Not covered in this article)
5. Migrate one piece at a time - (Not covered in this article)

Level 1: Building the Base

Step 1: Follow the Angular recommended 1.0 styleguide by John Papa

• https://github.com/johnpapa/angular-styleguide/tree/master/a1
• Recommended course - https://app.pluralsight.com/library/courses/angularjs-patterns-clean-code/table-of-contents

Step 2: Update to the latest Angular 1 via dependency manager

• Bower
• Node packages

Step 3: All new development using Angular 1.5 components

Angular has three types of directives:

1. Component
   • Isolate scope
   • Contains template or view
   • Developed to divide the actual view into number of sub-sections
   • Can be referred as Web-components or Reusable views
2. Decorator
   • Derivation of JavaScript’s decorator pattern
   • Enhances containing component’s properties
   • In general, restricted as ‘A’ attribute directives
3. Structural
   • Manipulates DOM
   • Takes control of deleting DOM elements from the view
   • It is not recommended to develop custom structural directives

Angular 1.5 components are introduced to replace the component or element type directives in the application. This is a big step towards component driven application design because new components can be configured in the router to provide navigation.

New components can replace your views, sub-views and sub-sub-views which were written as states and element-directive respectively.

To learn more about the Angular 1.5 components, please refer to the documentation:

• https://docs.angularjs.org/guide/component

Step 4: Convert old controllers into Angular 1.5 components. Here's an example:

OLD CONTROLLER

var FirstModule = angular.module('FirstModule');
FirstModule.config(function(){
  // View and route configuration
})
FirstModule.controller(FirstModuleCtrl);
function FirstModuleCtrl(DataService) {
}

NEW COMPONENT

var app = angular.module('app')
var config = {
templateUrl : 'FirstComponent/FirstComponent.hmtl',
bindings: {
someAttribute: '='
},
controller: FirstComponentCtrl
}
app.component('FirstComponent', config)
function FirstComponentCtrl () {
this.data = 'This value should reflect in the HTML'

Step 5: Remove Incompatible features from Directives

1. Compile
2. Terminal
3. Priority
4. Replace

Note: We don’t have to modify attribute directives, since they are not upgradable to Angular 2.0 and we will end up re-writing them.

Step 6: Manual Bootstrapping

Angular 2.0 uses manual bootstrapping. To perform manual bootstrapping in Angular 1, please add this to your App.js (bootstrapping logic) and remove directive bootstrapping (ng-app).

New ES6 syntax

angular.element(document).ready( () => {
    angular.bootstrap(document.body, ['app'])
})

Old ES5 syntax

angular.element(document).ready( function () {
     angular.bootstrap(document.body, ['app'])
})

Note: Most important step, since we cannot migrate to 2.0 without it.

Level 2: Angular 2.0 Armory

Step 1: Add TypeScript to the project build

Add TypeScript and typings node modules to your dev-dependencies

     npm install typescript typings - - save-dev

Add typescript compiler and typings command to the npm scripts (package.json).

"scripts": {
    "start": "node ./server/server.js",
    "dev": "nodemon ./server/server.js -w ./server",
    "test": "karma start",
    "tsc": "tsc -p . -w --outDir build",
    "typings": "typings"
  },

Step 2: Add TypeScript Configuration

Create a tsconfig.json file in your project root. This config file will be used for adding TypeScript build path and including typings.

{
  "compilerOptions": {
    "target": "ES5",
    "module": "system",
    "sourceMap": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "removeComments": false
  },
  "exclude": [
    "node_modules",
    "typings/main.d.ts",
    "typings/main"
  ]
}

Where to store compiled source files?

1. Same directory as .ts file:
   • Advantage of using relative path
   • No configuration needed for removing build files
2. Within a separate build directory:
   • Directory looks clean, only contains .ts files
   • Need to watch scripts via build tool for development server

Step 3: Switch controllers to ES6 Classes

Here, we are re-writing the controller defined in the Step 2 - New Component.

class FirstComponentCtrl {
  $location: any;
  auth: any;
  data: string;

  constructor ($location, auth) {
    this.$location = $location;
    this.auth = auth;
  }

  someFunc () {
    this.data = 'should reflect in the view';
  }
}

Step 4: Switch services to ES6 Classes

var App = angular.module('app')

App.service('MyService', MyService)

class MyService {
  $q: any;
  auth: any;
  data: string;

  constructor ($q, auth) {
    this.$q = $q;
    this.auth = auth;
  }

  someFunc () {
    // Do some AJAX Call
    // Returns promise
  }
}

Migration Phase 2 – Upgrade to Angular 2.0

Step 5: Adding Angular 2.0

The recommendation is to wait for the stable release of Angular 2.0. After adding Angular 2.0 to the project, we will upgrade or re-write one module at a time.

This guide will be extended once the Angular 2.0 is released.

Angular 2.0 - Official Resources

• https://angular.io/docs/ts/latest/guide/style-guide.html
• https://angular.io/docs/ts/latest/guide/upgrade.html
• http://angularjs.blogspot.in/2015/08/angular-1-and-angular-2-coexistence.html
• https://docs.google.com/document/d/1xvBZoFuNq9hsgRhPPZOJC-Z48AHEbIBPlOCBTSD8m0Y/edit