Having an existing Angular 1 application doesn't mean that we can't begin enjoying everything Angular 2 has to offer. That's because Angular 2 comes with built-in tools for migrating Angular 1 projects over to the Angular 2 platform.

Some applications will be easier to upgrade than others, and there are ways in which we can make it easier for ourselves. It is possible to prepare and align Angular 1 applications with Angular 2 even before beginning the upgrade process. These preparation steps are all about making the code more decoupled, more maintainable, and up to speed with modern development tools. That means the preparation work will not only make the eventual upgrade easier, but will also generally improve our Angular 1 applications.

One of the keys to a successful upgrade is to do it incrementally, by running the two frameworks side by side in the same application, and porting Angular 1 components to Angular 2 one by one. This makes it possible to upgrade even large and complex applications without disrupting other business, because the work can be done collaboratively and spread over a period of time. The upgrade module in Angular 2 has been designed to make incremental upgrading seamless.

Preparation
Upgrading with The Upgrade Adapter
PhoneCat Upgrade Tutorial
Appendix: Upgrading PhoneCat Tests

Preparation

There are many ways to structure Angular 1 applications. When we begin to upgrade these applications to Angular 2, some will turn out to be much more easy to work with than others. There are a few key techniques and patterns that we can apply to future proof our apps even before we begin the migration.

Follow the Angular Style Guide

The Angular 1 Style Guide collects patterns and practices that have been proven to result in cleaner and more maintainable Angular 1 applications. It contains a wealth of information about how to write and organize Angular code - and equally importantly - how not to write and organize Angular code.

Angular 2 is a reimagined version of the best parts of Angular 1. In that sense, its goals are the same as the Angular Style Guide's: To preserve the good parts of Angular 1, and to avoid the bad parts. There's a lot more to Angular 2 than just that of course, but this does mean that following the style guide helps make your Angular 1 app more closely aligned with Angular 2.

There are a few rules in particular that will make it much easier to do an incremental upgrade using the Angular 2 upgrade module:

The Rule of 1 states that there should be one component per file. This not only makes components easy to navigate and find, but will also allow us to migrate them between languages and frameworks one at a time. In this example application, each controller, component, service, and filter is in its own source file.
The Folders-by-Feature Structure and Modularity rules define similar principles on a higher level of abstraction: Different parts of the application should reside in different directories and Angular modules.

When an application is laid out feature per feature in this way, it can also be migrated one feature at a time. For applications that don't already look like this, applying the rules in the Angular style guide is a highly recommended preparation step. And this is not just for the sake of the upgrade - it is just solid advice in general!

Using a Module Loader

When we break application code down into one component per file, we often end up with a project structure with a large number of relatively small files. This is a much neater way to organize things than a small number of large files, but it doesn't work that well if you have to load all those files to the HTML page with <script> tags. Especially when you also have to maintain those tags in the correct order. That's why it's a good idea to start using a module loader.

Using a module loader such as SystemJS, Webpack, or Browserify allows us to use the built-in module systems of the TypeScript or ES2015 languages in our apps. We can use the import and export features that explicitly specify what code can and will be shared between different parts of the application. For ES5 applications we can use CommonJS style require and module.exports features. In both cases, the module loader will then take care of loading all the code the application needs in the correct order.

When we then take our applications into production, module loaders also make it easier to package them all up into production bundles with batteries included.

Migrating to TypeScript

If part of our Angular 2 upgrade plan is to also take TypeScript into use, it makes sense to bring in the TypeScript compiler even before the upgrade itself begins. This means there's one less thing to learn and think about during the actual upgrade. It also means we can start using TypeScript features in our Angular 1 code.

Since TypeScript is a superset of ECMAScript 2015, which in turn is a superset of ECMAScript 5, "switching" to TypeScript doesn't necessarily require anything more than installing the TypeScript compiler and switching renaming files from *.js to *.ts. But just doing that is not hugely useful or exciting, of course. Additional steps like the following can give us much more bang for the buck:

For applications that use a module loader, TypeScript imports and exports (which are really ECMAScript 2015 imports and exports) can be used to organize code into modules.
Type annotations can be gradually added to existing functions and variables to pin down their types and get benefits like build-time error checking, great autocompletion support and inline documentation.
JavaScript features new to ES2015, like arrow functions, lets and consts, default function parameters, and destructuring assignments can also be gradually added to make the code more expressive.
Services and controllers can be turned into classes. That way they'll be a step closer to becoming Angular 2 service and component classes, which will make our life easier once we do the upgrade.

Using Component Directives

In Angular 2, components are the main primitive from which user interfaces are built. We define the different parts of our UIs as components, and then compose the UI by using components in our templates.

You can also do this in Angular 1, using component directives. These are directives that define their own templates, controllers, and input/output bindings - the same things that Angular 2 components define. Applications built with component directives are much easier to migrate to Angular 2 than applications built with lower-level features like ng-controller, ng-include, and scope inheritance.

To be Angular 2 compatible, an Angular 1 component directive should configure these attributes:

restrict: 'E'. Components are usually used as elements.
scope: {} - an isolate scope. In Angular 2, components are always isolated from their surroundings, and we should do this in Angular 1 too.
bindToController: {}. Component inputs and outputs should be bound to the controller instead of using the $scope.
controller and controllerAs. Components have their own controllers.
template or templateUrl. Components have their own templates.

Component directives may also use the following attributes:

transclude: true, if the component needs to transclude content from elsewhere.
require, if the component needs to communicate with some parent component's controller.

Component directives may not use the following attributes:

compile. This will not be supported in Angular 2.
replace: true. Angular 2 never replaces a component element with the component template. This attribute is also deprecated in Angular 1.
priority and terminal. While Angular 1 components may use these, they are not used in Angular 2 and it is better not to write code that relies on them.

An Angular 1 component directive that is fully aligned with the Angular 2 architecture may look something like this:

export function heroDetailDirective() {
  return {
    restrict: 'E',
    scope: {},
    bindToController: {
      hero: '=',
      deleted: '&'
    },
    template: `
      <h2>{{ctrl.hero.name}} details!</h2>
      <div><label>id: </label>{{ctrl.hero.id}}</div>
      <button ng-click="ctrl.onDelete()">Delete</button>
    `,
    controller: function() {
      this.onDelete = () => {
        this.deleted({hero: this.hero});
      };
    },
    controllerAs: 'ctrl'
  };
}

Angular 1.5 introduces the component API that makes it easier to define directives like these. It is a good idea to use this API for component directives for several reasons:

It requires less boilerplate code.
It enforces the use of component best practices like controllerAs.
It has good default values for directive attributes like scope and restrict.

The component directive example from above looks like this when expressed using the component API:

export const heroDetail = {
  bindings: {
    hero: '<',
    deleted: '&'
  },
  template: `
    <h2>{{$ctrl.hero.name}} details!</h2>
    <div><label>id: </label>{{$ctrl.hero.id}}</div>
    <button ng-click="$ctrl.onDelete()">Delete</button>
  `,
  controller: function() {
    this.onDelete = () => {
      this.deleted(this.hero);
    };
  }
};

Controller lifecycle hook methods $onInit(), $onDestroy(), and $onChanges() are another convenient feature that Angular 1.5 introduces. They all have nearly exact equivalents in Angular 2, so organizing component lifecycle logic around them will ease the eventual Angular 2 upgrade process.

Upgrading with The Upgrade Adapter

The upgrade module in Angular 2 is a very useful tool for upgrading anything but the smallest of applications. With it we can mix and match Angular 1 and 2 components in the same application and have them interoperate seamlessly. That means we don't have to do the upgrade work all at once, since there's a natural coexistence between the two frameworks during the transition period.

How The Upgrade Adapter Works

The primary tool provided by the upgrade module is called the UpgradeAdapter. This is a service that can bootstrap and manage hybrid applications that support both Angular 2 and Angular 1 code.

When we use UpgradeAdapter, what we're really doing is running both versions of Angular at the same time. All Angular 2 code is running in the Angular 2 framework, and Angular 1 code in the Angular 1 framework. Both of these are the actual, fully featured versions of the frameworks. There is no emulation going on, so we can expect to have all the features and natural behavior of both frameworks.

What happens on top of this is that components and services managed by one framework can interoperate with those from the other framework. This happens in three main areas: Dependency injection, the DOM, and change detection.

Dependency Injection

Dependency injection is front and center in both Angular 1 and Angular 2, but there are some key differences between the two frameworks in how it actually works.

Angular 1	Angular 2
Dependency injection tokens are always strings	Tokens can have different types. They are often classes. They may also be strings.
There is exactly one injector. Even in multi-module applications, everything is poured into one big namespace.	There is a tree hierarchy of injectors, with a root injector and an additional injector for each component.

Even accounting for these differences we can still have dependency injection interoperability. The UpgradeAdapter resolves the differences and makes everything work seamlessly:

We can make Angular 1 services available for injection to Angular 2 code by upgrading them. The same singleton instance of each service is shared between the frameworks. In Angular 2 these services will always be in the root injector and available to all components. They will always have string tokens - the same tokens that they have in Angular 1.
We can also make Angular 2 services available for injection to Angular 1 code by downgrading them. Only services from the Angular 2 root injector can be downgraded. Again, the same singleton instances are shared between the frameworks. When we register a downgrade, we explicitly specify a string token that we want to use in Angular 1.

The two injectors in a hybrid application

Components and the DOM

What we'll find in the DOM of a hybrid application are components and directives from both Angular 1 and Angular 2. These components communicate with each other by using the input and output bindings of their respective frameworks, which the UpgradeAdapter bridges together. They may also communicate through shared injected dependencies, as described above.

There are two key things to understand about what happens in the DOM of a hybrid application:

Every element in the DOM is owned by exactly one of the two frameworks. The other framework ignores it. If an element is owned by Angular 1, Angular 2 treats it as if it didn't exist, and vice versa.
The root of the application is always an Angular 1 template.

So a hybrid application begins life as an Angular 1 application, and it is Angular 1 that processes its root template. Angular 2 then steps into the picture when an Angular 2 component is used somewhere in the application templates. That component's view will then be managed by Angular 2, and it may use any number of Angular 2 components and directives.

Beyond that, we may interleave the two frameworks as much as we need to. We always cross the boundary between the two frameworks by one of two ways:

By using a component from the other framework: An Angular 1 template using an Angular 2 component, or an Angular 2 template using an Angular 1 component.
By transcluding or projecting content from the other framework. The UpgradeAdapter bridges the related concepts of Angular 1 transclusion and Angular 2 content projection together.

DOM element ownership in a hybrid application

Whenever we use a component that belongs to the other framework, a switch between framework boundaries occurs. However, that switch only happens to the children of the component element. Consider a situation where we use an Angular 2 component from Angular 1 like this:

<ng2-component></ng2-component>

The DOM element <ng2-component> will remain to be an Angular 1 managed element, because it's defined in an Angular 1 template. That also means you can apply additional Angular 1 directives to it, but not Angular 2 directives. It is only in the template of the Ng2Component component where Angular 2 steps in. This same rule also applies when you use Angular 1 component directives from Angular 2.

Change Detection

Change detection in Angular 1 is all about scope.$apply(). After every event that occurs, scope.$apply() gets called. This is done either automatically by the framework, or in some cases manually by our own code. It is the point in time when change detection occurs and data bindings get updated.

In Angular 2 things are different. While change detection still occurs after every event, no one needs to call scope.$apply() for that to happen. This is because all Angular 2 code runs inside something called the Angular zone. Angular always knows when the code finishes, so it also knows when it should kick off change detection. The code itself doesn't have to call scope.$apply() or anything like it.

In the case of hybrid applications, the UpgradeAdapter bridges the Angular 1 and Angular 2 approaches. Here's what happens:

Everything that happens in the application runs inside the Angular 2 zone. This is true whether the event originated in Angular 1 or Angular 2 code. The zone triggers Angular 2 change detection after every event.
The UpgradeAdapter will invoke the Angular 1 $rootScope.$apply() after every turn of the Angular zone. This also triggers Angular 1 change detection after every event.

Change detection in a hybrid application

What this means in practice is that we do not need to call $apply() in our code, regardless of whether it is in Angular 1 on Angular 2. The UpgradeAdapter does it for us. We can still call $apply() so there is no need to remove such calls from existing code. Those calls just don't have any effect in a hybrid application.

When we downgrade an Angular 2 component and then use it from Angular 1, the component's inputs will be watched using Angular 1 change detection. When those inputs change, the corresponding properties in the component are set. We can also hook into the changes by implementing the OnChanges interface in the component, just like we could if it hadn't been downgraded.

Correspondingly, when we upgrade an Angular 1 component and use it from Angular 2, all the bindings defined for the component directive's scope (or bindToController) will be hooked into Angular 2 change detection. They will be treated as regular Angular 2 inputs and set onto the scope (or controller) when they change.

Using the Upgrade Adapter with Angular 2 NgModules

Both Angular 1 and Angular 2 have their own concept of modules to help organize an application into cohesive blocks of funcionality.

Their details are quite different in architecture and implementation. In Angular 1, you add Angular assets to the angular.module property. In Angular 2, you create one or more classes adorned with an NgModule decorator that describes Angular assets in metadata. The differences blossom from there.

In a hybrid application we run both versions of Angular at the same time. That means that we need at least one module each from both Angular 1 and Angular 2. We will give the Angular 2 module to the UpgradeAdapter while we use the Angular 1 module for bootstrapping. Let's see how.

Learn more about Angular 2 modules at the NgModule guide.

Bootstrapping Hybrid Angular 1+2 Applications

The first step to upgrading an application using the UpgradeAdapter is always to bootstrap it as a hybrid that supports both Angular 1 and Angular 2.

Pure Angular 1 applications can be bootstrapped in two ways: By using an ng-app directive somewhere on the HTML page, or by calling angular.bootstrap from JavaScript. In Angular 2, only the second method is possible - there is no ng-app in Angular 2. This is also the case for hybrid applications. Therefore, it is a good preliminary step to switch Angular 1 applications to use the JavaScript bootstrap method even before switching them to hybrid mode.

Say we have an ng-app driven bootstrap such as this one:

<!DOCTYPE HTML>
<html>
  <head>
    <script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.5.3/angular.js"></script>
    <script src="app/1-ng-app/app.module.js"></script>
  </head>

  <body ng-app="heroApp" ng-strict-di>
    <div id="message" ng-controller="MainCtrl as mainCtrl">
      {{ mainCtrl.message }}
    </div>
  </body>
</html>

We can remove the ng-app and ng-strict-di directives from the HTML and instead switch to calling angular.bootstrap from JavaScript, which will result in the same thing:

angular.bootstrap(document.body, ['heroApp'], {strictDi: true});

Now introduce Angular 2 to the project. Inspired by instructions in the QuickStart, you can selectively copy in material from the QuickStart github repository.

Next, create an app.module.ts file and add the following NgModule class:

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

@NgModule({
  imports: [ BrowserModule ]
})
export class AppModule {}

This bare minimum NgModule imports BrowserModule, the module every Angular browser-based app must have.

Import and instantiate the UpgradeAdapter with the new AppModule and call its bootstrap method. That method takes the exact same arguments as angular.bootstrap:

import { UpgradeAdapter } from '@angular/upgrade';

/* . . . */

const upgradeAdapter = new UpgradeAdapter(AppModule);

upgradeAdapter.bootstrap(document.body, ['heroApp'], {strictDi: true});

Congratulations! You're running a hybrid Angular 1+2 application! The existing Angular 1 code works as before and you're ready to run Angular 2 code.

Note that, unlike angular.bootstrap, the upgradeAdapter.bootstrap runs asynchronously. The application is not launched immediately. Some time must pass after the bootstrap call returns.

As we begin to migrate components to Angular 2, we'll be using the UpgradeAdapter for more than just bootstrapping. It'll be important to use the same instance of the adapter across the whole application, because it stores internal information about what's going on in the application. It'll be useful to have a module for a shared UpgradeAdapter instance in the project:

upgrade_adapter.tsimport { UpgradeAdapter } from '@angular/upgrade';
export const upgradeAdapter = new UpgradeAdapter(AppModule);

This shared instance can then be pulled in to all the modules that need it:

import { upgradeAdapter } from './upgrade_adapter';

/* . . . */

upgradeAdapter.bootstrap(document.body, ['heroApp'], {strictDi: true});

Using Angular 2 Components from Angular 1 Code

Using an Angular 2 component from Angular 1 code

Once we're running a hybrid app, we can start the gradual process of upgrading code. One of the more common patterns for doing that is to use an Angular 2 component in an Angular 1 context. This could be a completely new component or one that was previously Angular 1 but has been rewritten for Angular 2.

Say we have a simple Angular 2 component that shows information about a hero:

hero-detail.component.tsimport { Component } from '@angular/core';

@Component({
  selector: 'hero-detail',
  template: `
    <h2>Windstorm details!</h2>
    <div><label>id: </label>1</div>
  `
})
export class HeroDetailComponent {

}

If we want to use this component from Angular 1, we need to downgrade it using the upgrade adapter. What we get when we do that is an Angular 1 directive, which we can then register into our Angular 1 module:

import { HeroDetailComponent } from './hero-detail.component';

/* . . . */

angular.module('heroApp', [])
  .directive('heroDetail', upgradeAdapter.downgradeNg2Component(HeroDetailComponent));

Because HeroDetailComponent is an Angular 2 component, we must also add it to the declarations in the AppModule.

import { HeroDetailComponent } from './hero-detail.component';

@NgModule({
  imports: [ BrowserModule ],
  declarations: [ HeroDetailComponent ]
})
export class AppModule {}

All Angular 2 components, directives and pipes must be declared in an NgModule.

The net resulit is an Angular 1 directive called heroDetail, that we can use like any other directive in our Angular 1 templates.

<hero-detail></hero-detail>

Note that this Angular 1 is an element directive (restrict: 'E') called heroDetail. An Angular 1 element directive is matched based on its name. The selector metadata of the downgraded Angular 2 component is ignored.

Most components are not quite this simple, of course. Many of them have inputs and outputs that connect them to the outside world. An Angular 2 hero detail component with inputs and outputs might look like this:

hero-detail.component.tsimport { Component, EventEmitter, Input, Output } from '@angular/core';
import { Hero } from '../hero';

@Component({
  selector: 'hero-detail',
  template: `
    <h2>{{hero.name}} details!</h2>
    <div><label>id: </label>{{hero.id}}</div>
    <button (click)="onDelete()">Delete</button>
  `
})
export class HeroDetailComponent {
  @Input() hero: Hero;
  @Output() deleted = new EventEmitter<Hero>();
  onDelete() {
    this.deleted.emit(this.hero);
  }
}

These inputs and outputs can be supplied from the Angular 1 template, and the UpgradeAdapter takes care of bridging them over:

<div ng-controller="MainController as mainCtrl">
  <hero-detail [hero]="mainCtrl.hero"
               (deleted)="mainCtrl.onDelete($event)">
  </hero-detail>
</div>

Note that even though we are in an Angular 1 template, we're using Angular 2 attribute syntax to bind the inputs and outputs. This is a requirement for downgraded components. The expressions themselves are still regular Angular 1 expressions.

Use kebab-case for downgraded component attributes

There's one notable exception to the rule of using Angular 2 attribute syntax for downgraded components. It has to do with input or output names that consist of multiple words. In Angular 2 we would bind these attributes using camelCase:

[myHero]="hero"

But when using them from Angular 1 templates, we need to use kebab-case:

[my-hero]="hero"

The $event variable can be used in outputs to gain access to the object that was emitted. In this case it will be the Hero object, because that is what was passed to this.deleted.emit().

Since this is an Angular 1 template, we can still use other Angular 1 directives on the element, even though it has Angular 2 binding attributes on it. For example, we can easily make multiple copies of the component using ng-repeat:

<div ng-controller="MainController as mainCtrl">
  <hero-detail [hero]="hero"
               (deleted)="mainCtrl.onDelete($event)"
               ng-repeat="hero in mainCtrl.heroes">
  </hero-detail>
</div>

Using Angular 1 Component Directives from Angular 2 Code

Using an Angular 1 component from Angular 2 code

So, we can write an Angular 2 component and then use it from Angular 1 code. This is very useful when we start our migration from lower-level components and work our way up. But in some cases it is more convenient to do things in the opposite order: To start with higher-level components and work our way down. This too can be done using the UpgradeAdapter. We can upgrade Angular 1 component directives and then use them from Angular 2.

Not all kinds of Angular 1 directives can be upgraded. The directive really has to be a component directive, with the characteristics described in the preparation guide above. Our safest bet for ensuring compatibility is using the component API introduced in Angular 1.5.

A simple example of an upgradable component is one that just has a template and a controller:

hero-detail.component.tsexport const heroDetail = {
  template: `
    <h2>Windstorm details!</h2>
    <div><label>id: </label>1</div>
  `,
  controller: function() {
  }
};

We can upgrade this component to Angular 2 using the UpgradeAdapter's upgradeNg1Component method. It takes the name of an Angular 1 component directive and returns an Angular 2 component class. Declare it in an NgModule as with other Angular 2 components:

app.module.tsconst HeroDetail = upgradeAdapter.upgradeNg1Component('heroDetail');

@NgModule({
  imports: [ BrowserModule ],
  declarations: [ ContainerComponent, HeroDetail ]
})
export class AppModule {}

Upgraded components always have an element selector, which is based on the original name of the original Angular 1 component directive.

An upgraded component may also have inputs and outputs, as defined by the scope/controller bindings of the original Angular 1 component directive. When we use the component from an Angular 2 template, we provide the inputs and outputs using Angular 2 template syntax, with the following rules:

	Binding definition	Template syntax
Attribute binding	`myAttribute: '@myAttribute'`	`<my-component myAttribute="value">`
Expression binding	`myOutput: '&myOutput'`	`<my-component (myOutput)="action()">`
One-way binding	`myValue: '<myValue'`	`<my-component [myValue]="anExpression">`
Two-way binding	`myValue: '=myValue'`	As a two-way binding: `<my-component [(myValue)]="anExpression">`. Since most Angular 1 two-way bindings actually only need a one-way binding in practice, `<my-component [myValue]="anExpression">` is often enough.

As an example, say we have a hero detail Angular 1 component directive with one input and one output:

hero-detail.component.tsexport const heroDetail = {
  bindings: {
    hero: '<',
    deleted: '&'
  },
  template: `
    <h2>{{$ctrl.hero.name}} details!</h2>
    <div><label>id: </label>{{$ctrl.hero.id}}</div>
    <button ng-click="$ctrl.onDelete()">Delete</button>
  `,
  controller: function() {
    this.onDelete = () => {
      this.deleted(this.hero);
    };
  }
};

We can upgrade this component to Angular 2, and then provide the input and output using Angular 2 template syntax:

container.component.tsimport { Component } from '@angular/core';
import { Hero } from '../hero';

@Component({
  selector: 'my-container',
  template: `
    <h1>Tour of Heroes</h1>
    <hero-detail [hero]="hero"
                 (deleted)="heroDeleted($event)">
    </hero-detail>
  `
})
export class ContainerComponent {
  hero = new Hero(1, 'Windstorm');
  heroDeleted(hero: Hero) {
    hero.name = 'Ex-' + hero.name;
  }
}

Projecting Angular 1 Content into Angular 2 Components

When we are using a downgraded Angular 2 component from an Angular 1 template, the need may arise to transclude some content into it. This is also possible. While there is no such thing as transclusion in Angular 2, there is a very similar concept called content projection. The UpgradeAdapter is able to make these two features interoperate.

Angular 2 components that support content projection make use of an <ng-content> tag within them. Here's an example of such a component:

hero-detail.component.tsimport { Component, Input } from '@angular/core';
import { Hero } from '../hero';

@Component({
  selector: 'hero-detail',
  template: `
    <h2>{{hero.name}}</h2>
    <div>
      <ng-content></ng-content>
    </div>
  `
})
export class HeroDetailComponent {
  @Input() hero: Hero;
}

When using the component from Angular 1, we can supply contents for it. Just like they would be transcluded in Angular 1, they get projected to the location of the <ng-content> tag in Angular 2:

<div ng-controller="MainController as mainCtrl">
  <hero-detail [hero]="mainCtrl.hero">
    <!-- Everything here will get projected -->
    <p>{{mainCtrl.hero.description}}</p>
  </hero-detail>
</div>

When Angular 1 content gets projected inside an Angular 2 component, it still remains in "Angular 1 land" and is managed by the Angular 1 framework.

Transcluding Angular 2 Content into Angular 1 Component Directives

Projecting Angular 2 content into Angular 1

Just like we can project Angular 1 content into Angular 2 components, we can transclude Angular 2 content into Angular 1 components, whenever we are using upgraded versions from them.

When an Angular 1 component directive supports transclusion, it may use the ng-transclude directive in its template to mark the transclusion point:

hero-detail.component.tsexport const heroDetailComponent = {
  bindings: {
    hero: '='
  },
  template: `
    <h2>{{$ctrl.hero.name}}</h2>
    <div>
      <ng-transclude></ng-transclude>
    </div>
  `
};

The directive also needs to have the transclude: true option enabled. It is on by default for component directives defined with the 1.5 component API.

If we upgrade this component and use it from Angular 2, we can populate the component tag with contents that will then get transcluded:

container.component.tsimport { Component } from '@angular/core';
import { Hero } from '../hero';

@Component({
  selector: 'my-container',
  template: `
    <hero-detail [hero]="hero">
      <!-- Everything here will get transcluded -->
      <p>{{hero.description}}</p>
    </hero-detail>
  `
})
export class ContainerComponent {
  hero = new Hero(1, 'Windstorm', 'Specific powers of controlling winds');
}

Making Angular 1 Dependencies Injectable to Angular 2

When running a hybrid app, we may bump into situations where we need to have some Angular 1 dependencies to be injected to Angular 2 code. This may be because we have some business logic still in Angular 1 services, or because we need some of Angular 1's built-in services like $location or $timeout.

In these situations, it is possible to upgrade an Angular 1 provider to Angular 2. This makes it possible to then inject it somewhere in Angular 2 code. For example, we might have a service called HeroesService in Angular 1:

heroes.service.tsimport { Hero } from '../hero';

export class HeroesService {
  get() {
    return [
      new Hero(1, 'Windstorm'),
      new Hero(2, 'Spiderman')
    ];
  }
}

We can upgrade the service using the UpgradeAdapter's upgradeNg1Provider method by giving it the name of the service. This adds the service into Angular 2's root injector.

app.module.tsangular.module('heroApp', [])
  .service('heroes', HeroesService)
  .directive('heroDetail',
    upgradeAdapter.downgradeNg2Component(HeroDetailComponent));

upgradeAdapter.upgradeNg1Provider('heroes');

We can then inject it in Angular 2 using a string token that matches its original name in Angular 1:

hero-detail.component.tsimport { Component, Inject } from '@angular/core';
import { HeroesService } from './heroes.service';
import { Hero } from '../hero';

@Component({
  selector: 'hero-detail',
  template: `
    <h2>{{hero.id}}: {{hero.name}}</h2>
  `
})
export class HeroDetailComponent {
  hero: Hero;
  constructor(@Inject('heroes') heroes: HeroesService) {
    this.hero = heroes.get()[0];
  }
}

In this example we upgraded a service class, which has the added benefit that we can use a TypeScript type annotation when we inject it. While it doesn't affect how the dependency is handled, it enables the benefits of static type checking. This is not required though, and any Angular 1 service, factory, or provider can be upgraded.

Making Angular 2 Dependencies Injectable to Angular 1

In addition to upgrading Angular 1 dependencies, we can also downgrade Angular 2 dependencies, so that we can use them from Angular 1. This can be useful when we start migrating services to Angular 2 or creating new services in Angular 2 while we still have components written in Angular 1.

For example, we might have an Angular 2 service called Heroes:

heroes.tsimport { Injectable } from '@angular/core';
import { Hero } from '../hero';

@Injectable()
export class Heroes {
  get() {
    return [
      new Hero(1, 'Windstorm'),
      new Hero(2, 'Spiderman')
    ];
  }
}

Again, as with Angular 2 components, register the provider with the NgModule by adding it to the module's providers list.

app.module.tsimport { Heroes } from './heroes';

@NgModule({
  imports: [ BrowserModule ],
  providers: [ Heroes ]
})
export class AppModule {}

Now wrap the Angular 2 Heroes in an Angular 1 factory function using upgradeAdapter.downgradeNg2Provider(). and plug the factory into an Angular 1 module. The name of the Angular 1 dependency is up to you:

app.module.tsangular.module('heroApp', [])
  .factory('heroes', upgradeAdapter.downgradeNg2Provider(Heroes))
  .component('heroDetail', heroDetailComponent);

After this, the service is injectable anywhere in our Angular 1 code:

hero-detail.component.tsexport const heroDetailComponent = {
  template: `
    <h2>{{$ctrl.hero.id}}: {{$ctrl.hero.name}}</h2>
  `,
  controller: ['heroes', function(heroes: Heroes) {
    this.hero = heroes.get()[0];
  }]
};

PhoneCat Upgrade Tutorial

In this section and we will look at a complete example of preparing and upgrading an application using the upgrade module. The app we're going to work on is Angular PhoneCat from the original Angular 1 tutorial, which is where many of us began our Angular adventures. Now we'll see how to bring that application to the brave new world of Angular 2.

During the process we'll learn how to apply the steps outlined in the preparation guide in practice: We'll align the application with Angular 2 and also take TypeScript into use.

To follow along with the tutorial, clone the angular-phonecat repository and apply the steps as we go.

In terms of project structure, this is where our work begins:

angular-phonecat

bower.json

karma.conf.js

package.json

app

core

checkmark

checkmark.filter.js

checkmark.filter.spec.js

phone

phone.module.js

phone.service.js

phone.service.spec.js

core.module.js

phone-detail

phone-detail.component.js

phone-detail.component.spec.js

phone-detail.module.js

phone-detail.template.html

phone-list

phone-list.component.js

phone-list.component.spec.js

phone-list.module.js

phone-list.template.html

img

...

phones

...

app.animations.js

app.config.js

app.css

app.module.js

index.html

e2e-tests

protractor-conf.js

scenarios.js

This is actually a pretty good starting point. The code uses the Angular 1.5 component API and the organization follows the Angular 1 Style Guide, which is an important preparation step before a successful upgrade.

Each component, service, and filter is in its own source file, as per the Rule of 1.
The core, phone-detail, and phone-list modules are each in their own subdirectory. Those subdirectories contain the JavaScript code as well as the HTML templates that go with each particular feature. This is in line with the Folders-by-Feature Structure and Modularity rules.
Unit tests are located side-by-side with application code where they are easily found, as described in the rules for Organizing Tests.

Switching to TypeScript

Since we're going to be writing our Angular 2 code in TypeScript, it makes sense to bring in the TypeScript compiler even before we begin upgrading.

We will also start to gradually phase out the Bower package manager in favor of NPM. We'll install all new dependencies using NPM, and will eventually be able to remove Bower from the project.

Let's begin by installing TypeScript to the project. While we're at it, let's also install the Typings type definition manager. It will allow us to install type definitions for libraries that don't come with prepackaged types.

npm i typescript typings --save-dev

Let's also add run scripts for the tsc TypeScript compiler and the typings tool to package.json:

package.json{
  "scripts": {
    "tsc": "tsc",
    "tsc:w": "tsc -w"
  }
}

We can now use Typings to install type definitions for the existing libraries that we're using: Angular 1 and the Jasmine unit test framework.

npm run typings install dt~jquery dt~angular dt~angular-route \ dt~angular-resource dt~angular-mocks dt~angular-animate \ dt~jasmine -- --save --global

This will add these typings into a typings.json configuration file as well as download them into the typings directory.

We should also configure the TypeScript compiler so that it can understand our project. We'll add a tsconfig.json file to the project directory, just like we do in the Quickstart. It instructs the TypeScript compiler how to interpret our source files.

tsconfig.json{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "moduleResolution": "node",
    "sourceMap": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "removeComments": false,
    "noImplicitAny": false,
    "suppressImplicitAnyIndexErrors": true
  }
}

We are telling the TypeScript compiler to turn our TypeScript files to ES5 code bundled into CommonJS modules.

We can now launch the TypeScript compiler from the command line. It will watch our .ts source files and compile them to JavaScript on the fly. Those compiled .js files are then loaded into the browser by SystemJS. This is a process we'll want to have continuously running in the background as we go along.

npm run tsc:w

The next thing we'll do is convert our JavaScript files to TypeScript. Since TypeScript is a superset of ECMAScript 2015, which in turn is a superset of ECMAScript 5, we can simply switch the file extensions from .js to .ts and everything will work just like it did before. As the TypeScript compiler runs, it emits the corresponding .js file for every .ts file and the compiled JavaScript is what actually gets executed. If you start the project HTTP server with npm start, you should see the fully functional application in your browser.

Now that we have TypeScript though, we can start benefiting from some of its features. There's a lot of value the language can provide to Angular 1 applications.

For one thing, TypeScript is a superset of ES2015. Any app that has previously been written in ES5 - like the PhoneCat example has - can with TypeScript start incorporating all of the JavaScript features that are new to ES2015. These include things like lets and consts, arrow functions, default function parameters, and destructuring assignments.

Another thing we can do is start adding type safety to our code. This has actually partially already happened because of the Angular 1 typings we installed. TypeScript are checking that we are calling Angular 1 APIs correctly when we do things like register components to Angular modules.

But we can also start adding type annotations for our own code to get even more out of TypeScript's type system. For instance, we can annotate the checkmark filter so that it explicitly expects booleans as arguments. This makes it clearer what the filter is supposed to do.

app/core/checkmark/checkmark.filter.ts
angular.
  module('core').
  filter('checkmark', function() {
    return function(input: boolean) {
      return input ? '\u2713' : '\u2718';
    };
  });

In the Phone service we can explicitly annotate the $resource service dependency as an angular.resource.IResourceService - a type defined by the Angular 1 typings.

app/core/phone/phone.service.tsangular.
  module('core.phone').
  factory('Phone', ['$resource',
    function($resource: angular.resource.IResourceService) {
      return $resource('phones/:phoneId.json', {}, {
        query: {
          method: 'GET',
          params: {phoneId: 'phones'},
          isArray: true
        }
      });
    }
  ]);

We can apply the same trick to the application's route configuration file in app.config.ts, where we are using the location and route services. By annotating them accordingly TypeScript can verify we're calling their APIs with the correct kinds of arguments.

app/app.config.tsangular.
  module('phonecatApp').
  config(['$locationProvider', '$routeProvider',
    function config($locationProvider: angular.ILocationProvider,
                    $routeProvider: angular.route.IRouteProvider) {
      $locationProvider.hashPrefix('!');

      $routeProvider.
        when('/phones', {
          template: '<phone-list></phone-list>'
        }).
        when('/phones/:phoneId', {
          template: '<phone-detail></phone-detail>'
        }).
        otherwise('/phones');
    }
  ]);

The Angular 1.x type definitions we installed with Typings are not officially maintained by the Angular team, but are quite comprehensive. It is possible to make an Angular 1.x application fully type-annotated with the help of these definitions.

If this is something we wanted to do, it would be a good idea to enable the noImplicitAny configuration option in tsconfig.json. This would cause the TypeScript compiler to display a warning when there's any code that does not yet have type annotations. We could use it as a guide to inform us about how close we are to having a fully annotated project.

Another TypeScript feature we can make use of is classes. In particular, we can turn our component controllers into classes. That way they'll be a step closer to becoming Angular 2 component classes, which will make our life easier once we do the upgrade.

Angular 1 expects controllers to be constructor functions. That's exactly what ES2015/TypeScript classes are under the hood, so that means we can just plug in a class as a component controller and Angular 1 will happily use it.

Here's what our new class for the phone list component controller looks like:

app/phone-list/phone-list.component.tsclass PhoneListController {
  phones: any[];
  orderProp: string;
  query: string;

  static $inject = ['Phone'];
  constructor(Phone: any) {
    this.phones = Phone.query();
    this.orderProp = 'age';
  }

}

angular.
  module('phoneList').
  component('phoneList', {
    templateUrl: 'phone-list/phone-list.template.html',
    controller: PhoneListController
  });

What was previously done in the controller function is now done in the class constructor function. The dependency injection annotations are attached to the class using a static property $inject. At runtime this becomes the PhoneListController.$inject property.

The class additionally declares three members: The array of phones, the name of the current sort key, and the search query. These are all things we have already been attaching to the controller but that weren't explicitly declared anywhere. The last one of these isn't actually used in the TypeScript code since it's only referred to in the template, but for the sake of clarity we want to define all the members our controller will have.

In the Phone detail controller we'll have two members: One for the phone that the user is looking at and another for the URL of the currently displayed image:

app/phone-detail/phone-detail.component.tsclass PhoneDetailController {
  phone: any;
  mainImageUrl: string;

  static $inject = ['$routeParams', 'Phone'];
  constructor($routeParams: angular.route.IRouteParamsService, Phone: any) {
    let phoneId = $routeParams['phoneId'];
    this.phone = Phone.get({phoneId}, (phone: any) => {
      this.setImage(phone.images[0]);
    });
  }

  setImage(imageUrl: string) {
    this.mainImageUrl = imageUrl;
  }
}

angular.
  module('phoneDetail').
  component('phoneDetail', {
    templateUrl: 'phone-detail/phone-detail.template.html',
    controller: PhoneDetailController
  });

This makes our controller code look a lot more like Angular 2 already. We're all set to actually introduce Angular 2 into the project.

If we had any Angular 1 services in the project, those would also be a good candidate for converting to classes, since like controllers, they're also constructor functions. But we only have the Phone factory in this project, and that's a bit special since it's an ngResource factory. So we won't be doing anything to it in the preparation stage. We'll instead turn it directly into an Angular 2 service.

Installing Angular 2

Having completed our preparation work, let's get going with the Angular 2 upgrade of PhoneCat. We'll do this incrementally with the help of the upgrade module that comes with Angular 2. By the time we're done, we'll be able to remove Angular 1 from the project completely, but the key is to do this piece by piece without breaking the application.

The project also contains some animations, which we are not yet upgrading in this version of the guide. This will change in a later release.

Let's install Angular 2 into the project, along with the SystemJS module loader. Take a look into the Quickstart guide and get the following configurations from there:

Add Angular 2 and the other new dependencies to package.json
Add the new typings into typings.json
The SystemJS configuration file systemjs.config.js to the project root directory.

Once these are done, run:

npm install npm run typings install

We can soon load Angular 2 dependencies into the application via index.html, but first we need to do some directory path adjustments. This is because we're going to need to load files from node_modules and the project root, whereas so far in this project everything has been loaded from the /app directory.

Move the app/index.html file to the project root directory. Then change the development server root path in package.json to also point to the project root instead of app:

package.json (start script){
  "scripts": {
    "start": "http-server -a localhost -p 8000 -c-1 ./"
  }
}

Now we're able to serve everything from the project root to the web browser. But we do not want to have to change all the image and data paths used in the application code to match our development setup. For that reason, we'll add a <base> tag to index.html, which will cause relative URLs to be resolved back to the /app directory:

index.html<base href="/app/">

Now we can load Angular 2 via SystemJS. We'll add the Angular 2 polyfills and the SystemJS config to the end of the <head> section, and then we'll use System.import to load the actual application:

index.html<script src="/node_modules/core-js/client/shim.min.js"></script>
<script src="/node_modules/zone.js/dist/zone.js"></script>
<script src="/node_modules/reflect-metadata/Reflect.js"></script>
<script src="/node_modules/systemjs/dist/system.src.js"></script>
<script src="/systemjs.config.js"></script>
<script>
  System.import('/app');
</script>

In the systemjs.config.js file we got from the Quickstart we also need to make a couple of adjustments because of our project structure. We want to point the browser to the project root when loading things through SystemJS, instead of using the <base> URL:

systemjs.config.jsSystem.config({
  paths: {
    // paths serve as alias
    'npm:': '/node_modules/'
  },
  map: {
    app: '/app',
    /* . . . */
  },

Creating the AppModule

Now create the root NgModule class called AppModule. There is already a file named app.module.ts that holds the Angular 1 module. Rename it to app.module.ng1.ts and update the corresponding script name in the index.html as well. The file contents remain:

app.module.ng1.ts'use strict';

// Define the `phonecatApp` Angular 1 module
angular.module('phonecatApp', [
  'ngAnimate',
  'ngRoute',
  'core',
  'phoneDetail',
  'phoneList',
]);

Now create a new app.module.ts with the minimum NgModule class:

app.module.tsimport { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

@NgModule({
  imports: [
    BrowserModule,
  ],
})
export class AppModule {}

Bootstrapping a hybrid 1+2 PhoneCat

What we'll do next is bootstrap the application as a hybrid application that supports both Angular 1 and Angular 2 components. Once we've done that we can start converting the individual pieces to Angular 2.

To bootstrap a hybrid application, we first need to initialize an UpgradeAdapter, which provides the glue that joins the two versions of the framework together. Let's import the UpgradeAdapter class into a new file app/main.ts. This file has been configured as the application entrypoint in systemjs.config.js, so it is already being loaded by the browser.

app/main.tsimport { UpgradeAdapter } from '@angular/upgrade';

import { AppModule } from './app.module';

We can then make an adapter by instantiating the class:

let upgradeAdapter = new UpgradeAdapter(AppModule);

Our application is currently bootstrapped using the Angular 1 ng-app directive attached to the <html> element of the host page. This will no longer work with Angular 2. We should switch to a JavaScript-driven bootstrap instead. So, remove the ng-app attribute from index.html, and instead add this to main.ts:

upgradeAdapter.bootstrap(document.documentElement, ['phonecatApp']);

The arguments used here are the root element of the application (which is the same element we had ng-app on earlier), and the Angular 1.x modules that we want to load. Since we're bootstrapping the app through an UpgradeAdapter, we're actually now running the app as a hybrid Angular 1+2 app.

This means we are now running both Angular 1 and 2 at the same time. That's pretty exciting! We're not running any actual Angular 2 components yet though, so let's do that next.

Upgrading the Phone service

The first piece we'll port over to Angular 2 is the Phone service, which resides in app/core/phone/phone.service.ts and makes it possible for components to load phone information from the server. Right now it's implemented with ngResource and we're using it for two things:

For loading the list of all phones into the phone list component
For loading the details of a single phone into the phone detail component.

We can replace this implementation with an Angular 2 service class, while keeping our controllers in Angular 1 land.

In the new version, we import the Angular 2 HTTP module and call its Http service instead of ngResource.

Re-open the app.module.ts file, import and add HttpModule to the imports array of the AppModule:

app.module.tsimport { HttpModule } from '@angular/http';

@NgModule({
  imports: [
    BrowserModule,
    HttpModule,
  ],
})
export class AppModule {}

Now we're ready to upgrade the Phone service itself. We replace the ngResource-based service in phone.service.ts with a TypeScript class decorated as @Injectable:

app/core/phone/phone.service.ts (skeleton)@Injectable()
export class Phone {
/* . . . */
}

The @Injectable decorator will attach some dependency injection metadata to the class, letting Angular 2 know about its dependencies. As described by our Dependency Injection Guide, this is a marker decorator we need to use for classes that have no other Angular 2 decorators but still need to have their dependencies injected.

In its constructor the class expects to get the Http service. It will be injected to it and it is stored as a private field. The service is then used in the two instance methods, one of which loads the list of all phones, and the other the details of a particular phone:

@Injectable()
export class Phone {
  constructor(private http: Http) { }
  query(): Observable<PhoneData[]> {
    return this.http.get(`phones/phones.json`)
      .map((res: Response) => res.json());
  }
  get(id: string): Observable<PhoneData> {
    return this.http.get(`phones/${id}.json`)
      .map((res: Response) => res.json());
  }
}

The methods now return Observables of type PhoneData and PhoneData[]. This is a type we don't have yet, so let's add a simple interface for it:

app/core/phone/phone.service.ts (interface)export interface PhoneData {
  name: string;
  snippet: string;
  images: string[];
}

Here's the full, final code for the service:

app/core/phone/phone.service.tsimport { Injectable } from '@angular/core';
import { Http, Response } from '@angular/http';
import { Observable } from 'rxjs/Rx';

import 'rxjs/add/operator/map';

export interface PhoneData {
  name: string;
  snippet: string;
  images: string[];
}

@Injectable()
export class Phone {
  constructor(private http: Http) { }
  query(): Observable<PhoneData[]> {
    return this.http.get(`phones/phones.json`)
      .map((res: Response) => res.json());
  }
  get(id: string): Observable<PhoneData> {
    return this.http.get(`phones/${id}.json`)
      .map((res: Response) => res.json());
  }
}

Notice that we're importing the map operator of the RxJS Observable separately. We need to do this for all RxJS operators that we want to use, since Angular 2 does not load all of them by default.

The new Phone service has the same features as the original, ngResource-based service. Because it's an Angular 2 service, we register it with the NgModule providers:

app.module.tsimport { Phone } from './core/phone/phone.service';

@NgModule({
  imports: [
    BrowserModule,
    HttpModule,
  ],
  providers: [ Phone ]
})
export class AppModule {}

UpgradeAdapter has a downgradeNg2Provider method for the purpose of making Angular 2 services available to Angular 1 code. Use it to plug in the Phone service:

app/main.ts (excerpt)import { Phone } from './core/phone/phone.service';

/* . . . */

angular.module('core.phone')
  .factory('phone', upgradeAdapter.downgradeNg2Provider(Phone));

Now that we are loading phone.service.ts through an import that is resolved by SystemJS, we should remove the <script> tag for the service from index.html. This is something we'll do to all our components as we upgrade them. Simultaneously with the Angular 1 to 2 upgrade we're also migrating our code from scripts to modules.

At this point we can switch our two components to use the new service instead of the old one. We $inject it as the downgraded phone factory, but it's really an instance of the Phone class and we can annotate its type accordingly:

app/phone-list/phone-list.component.tsimport { Phone, PhoneData } from '../core/phone/phone.service';

class PhoneListController {
  phones: PhoneData[];
  orderProp: string;

  static $inject = ['phone'];
  constructor(phone: Phone) {
    phone.query().subscribe(phones => {
      this.phones = phones;
    });
    this.orderProp = 'age';
  }

}

angular.
  module('phoneList').
  component('phoneList', {
    templateUrl: 'app/phone-list/phone-list.template.html',
    controller: PhoneListController
  });

app/phone-detail/phone-detail.component.tsimport { Phone, PhoneData } from '../core/phone/phone.service';

class PhoneDetailController {
  phone: PhoneData;
  mainImageUrl: string;

  static $inject = ['$routeParams', 'phone'];
  constructor($routeParams: angular.route.IRouteParamsService, phone: Phone) {
    let phoneId = $routeParams['phoneId'];
    phone.get(phoneId).subscribe(data => {
      this.phone = data;
      this.setImage(data.images[0]);
    });
  }

  setImage(imageUrl: string) {
    this.mainImageUrl = imageUrl;
  }
}

angular.
  module('phoneDetail').
  component('phoneDetail', {
    templateUrl: 'phone-detail/phone-detail.template.html',
    controller: PhoneDetailController
  });

What we have here are two Angular 1 components using an Angular 2 service! The components don't need to be aware of this, though the fact that the service returns Observables and not Promises is a bit of a giveaway. In any case, what we've achieved is a migration of a service to Angular 2 without having to yet migrate the components that use it.

We could also use the toPromise method of Observable to turn those Observables into Promises in the service. This can in many cases further reduce the amount of changes needed in the component controllers.

Upgrading Components

Next, let's upgrade our Angular 1 components to Angular 2 components. We'll do it one at a time, while still keeping the application in hybrid mode. As we make these conversions, we'll also be defining our first Angular 2 pipes.

Let's look at the phone list component first. Right now it contains a TypeScript controller class and a component definition object. We can morph this into an Angular 2 component by just renaming the controller class and turning the Angular 1 component definition object into an Angular 2 @Component decorator. We can then also remove the static $inject property from the class:

app/phone-list/phone-list.component.tsimport { Component } from '@angular/core';
import { Phone, PhoneData } from '../core/phone/phone.service';

@Component({
  moduleId: module.id,
  selector: 'phone-list',
  templateUrl: 'phone-list.template.html'
})
export class PhoneListComponent {
  phones: PhoneData[];
  query: string;
  orderProp: string;

  constructor(phone: Phone) {
    phone.query().subscribe(phones => {
      this.phones = phones;
    });
    this.orderProp = 'age';
  }
}

The selector attribute is a CSS selector that defines where on the page the component should go. In Angular 1 we do matching based on component names, but in Angular 2 we have these explicit selectors. This one will match elements with the name phone-list, just like the Angular 1 version did.

We now also need to convert the template of this component into Angular 2 syntax. The search controls replace the Angular 1 $ctrl expressions with Angular 2's two-way [(ngModel)] binding syntax:

app/phone-list/phone-list.template.html (search controls)<p>
  Search:
  <input [(ngModel)]="query" />
</p>

<p>
  Sort by:
  <select [(ngModel)]="orderProp">
    <option value="name">Alphabetical</option>
    <option value="age">Newest</option>
  </select>
</p>

Replace the list's ng-repeat with an *ngFor as described in the Template Syntax page. Replace the image tag's ng-src with a binding to the native src property.

app/phone-list/phone-list.template.html (phones)<ul class="phones">
  <li *ngFor="let phone of getPhones()"
      class="thumbnail phone-list-item">
    <a href="/#!/phones/{{phone.id}}" class="thumb">
      <img [src]="phone.imageUrl" [alt]="phone.name" />
    </a>
    <a href="/#!/phones/{{phone.id}}" class="name">{{phone.name}}</a>
    <p>{{phone.snippet}}</p>
  </li>
</ul>

No Angular 2 filter or orderBy filters

The built-in Angular 1 filter and orderBy filters do not exist in Angular 2, so we need to do the filtering and sorting ourselves.

We replaced the filter and orderBy filters with bindings to the getPhones() controller method, which implements the filtering and ordering logic inside the component itself.

app/phone-list/phone-list.component.tsgetPhones(): PhoneData[] {
  return this.sortPhones(this.filterPhones(this.phones));
}

private filterPhones(phones: PhoneData[]) {
  if (phones && this.query) {
    return phones.filter(phone => {
      let name = phone.name.toLowerCase();
      let snippet = phone.snippet.toLowerCase();
      return name.indexOf(this.query) >= 0 || snippet.indexOf(this.query) >= 0;
    });
  }
  return phones;
}

private sortPhones(phones: PhoneData[]) {
  if (phones && this.orderProp) {
    return phones
      .slice(0) // Make a copy
      .sort((a, b) => {
        if (a[this.orderProp] < b[this.orderProp]) {
          return -1;
        } else if ([b[this.orderProp] < a[this.orderProp]]) {
          return 1;
        } else {
          return 0;
        }
      });
  }
  return phones;
}

The new PhoneListComponent uses the Angular 2 ngModel directive, located in the FormsModule. Add the FormsModule to NgModule imports and declare the new PhoneListComponent :

app.module.tsimport { FormsModule } from '@angular/forms';
import { PhoneListComponent } from './phone-list/phone-list.component';

@NgModule({
  imports: [
    BrowserModule,
    HttpModule,
    FormsModule,
  ],
  declarations: [
    PhoneListComponent,
  ],
  providers: [ Phone ]
})
export class AppModule {}

In the entrypoint file main.ts we'll plug this component into the Angular 1 module.

Instead of registering a component, we register a phoneList directive, a downgraded version of the Angular 2 component. The UpgradeAdapter creates the bridge between the two:

app/main.ts (excerpt)import { PhoneListComponent } from './phone-list/phone-list.component';

/* . . . */

angular.module('phoneList')
  .directive(
    'phoneList',
    upgradeAdapter.downgradeNg2Component(PhoneListComponent) as angular.IDirectiveFactory
  );

The as angular.IDirectiveFactory cast tells the TypeScript compiler that the return value of the downgrade method is a directive factory.

Remove the <script> tag for the phone list component from index.html.

Now set the remaining phone-detail.component.ts as follows:

app/phone-detail/phone-detail.component.tsimport { Component, Inject } from '@angular/core';

import { Phone, PhoneData } from '../core/phone/phone.service';
@Component({
  moduleId: module.id,
  selector: 'phone-detail',
  templateUrl: 'phone-detail.template.html',
})
export class PhoneDetailComponent {
  phone: PhoneData;
  mainImageUrl: string;

  constructor(@Inject('$routeParams')
                $routeParams: angular.route.IRouteParamsService,
              phone: Phone) {
    phone.get($routeParams['phoneId']).subscribe(phone => {
      this.phone = phone;
      this.setImage(phone.images[0]);
    });
  }

  setImage(imageUrl: string) {
    this.mainImageUrl = imageUrl;
  }
}

This is similar to the phone list component. The new wrinkle is the @Inject decorator that identifies the $routeParams dependency.

The Angular 1 injector has an Angular 1 router dependency called $routeParams. which was injected into PhoneDetails when it was still an Angular 1 controller. We intend to inject it into the new PhoneDetailsComponent.

Unfortunately, Angular 1 dependencies are not automatically available to Angular 2 components. We must use the UpgradeAdapter to make the $routeParams an Angular 2 provider. Do that in main.ts:

app/main.ts ($routeParms)upgradeAdapter.upgradeNg1Provider('$routeParams');

Do not register an upgraded Angular 1 provider in the NgModule.

Convert the phone detail component template into Angular 2 syntax as follows:

app/phone-detail/phone-detail.template.html<div *ngIf="phone">
  <div class="phone-images">
    <img [src]="img" class="phone"
        [ngClass]="{selected: img === mainImageUrl}"
        *ngFor="let img of phone.images" />
  </div>

  <h1>{{phone.name}}</h1>

  <p>{{phone.description}}</p>

  <ul class="phone-thumbs">
    <li *ngFor="let img of phone.images">
      <img [src]="img" (click)="setImage(img)" />
    </li>
  </ul>

  <ul class="specs">
    <li>
      <span>Availability and Networks</span>
      <dl>
        <dt>Availability</dt>
        <dd *ngFor="let availability of phone.availability">{{availability}}</dd>
      </dl>
    </li>
    <li>
      <span>Battery</span>
      <dl>
        <dt>Type</dt>
        <dd>{{phone.battery?.type}}</dd>
        <dt>Talk Time</dt>
        <dd>{{phone.battery?.talkTime}}</dd>
        <dt>Standby time (max)</dt>
        <dd>{{phone.battery?.standbyTime}}</dd>
      </dl>
    </li>
    <li>
      <span>Storage and Memory</span>
      <dl>
        <dt>RAM</dt>
        <dd>{{phone.storage?.ram}}</dd>
        <dt>Internal Storage</dt>
        <dd>{{phone.storage?.flash}}</dd>
      </dl>
    </li>
    <li>
      <span>Connectivity</span>
      <dl>
        <dt>Network Support</dt>
        <dd>{{phone.connectivity?.cell}}</dd>
        <dt>WiFi</dt>
        <dd>{{phone.connectivity?.wifi}}</dd>
        <dt>Bluetooth</dt>
        <dd>{{phone.connectivity?.bluetooth}}</dd>
        <dt>Infrared</dt>
        <dd>{{phone.connectivity?.infrared | checkmark}}</dd>
        <dt>GPS</dt>
        <dd>{{phone.connectivity?.gps | checkmark}}</dd>
      </dl>
    </li>
    <li>
      <span>Android</span>
      <dl>
        <dt>OS Version</dt>
        <dd>{{phone.android?.os}}</dd>
        <dt>UI</dt>
        <dd>{{phone.android?.ui}}</dd>
      </dl>
    </li>
    <li>
      <span>Size and Weight</span>
      <dl>
        <dt>Dimensions</dt>
        <dd *ngFor="let dim of phone.sizeAndWeight?.dimensions">{{dim}}</dd>
        <dt>Weight</dt>
        <dd>{{phone.sizeAndWeight?.weight}}</dd>
      </dl>
    </li>
    <li>
      <span>Display</span>
      <dl>
        <dt>Screen size</dt>
        <dd>{{phone.display?.screenSize}}</dd>
        <dt>Screen resolution</dt>
        <dd>{{phone.display?.screenResolution}}</dd>
        <dt>Touch screen</dt>
        <dd>{{phone.display?.touchScreen | checkmark}}</dd>
      </dl>
    </li>
    <li>
      <span>Hardware</span>
      <dl>
        <dt>CPU</dt>
        <dd>{{phone.hardware?.cpu}}</dd>
        <dt>USB</dt>
        <dd>{{phone.hardware?.usb}}</dd>
        <dt>Audio / headphone jack</dt>
        <dd>{{phone.hardware?.audioJack}}</dd>
        <dt>FM Radio</dt>
        <dd>{{phone.hardware?.fmRadio | checkmark}}</dd>
        <dt>Accelerometer</dt>
        <dd>{{phone.hardware?.accelerometer | checkmark}}</dd>
      </dl>
    </li>
    <li>
      <span>Camera</span>
      <dl>
        <dt>Primary</dt>
        <dd>{{phone.camera?.primary}}</dd>
        <dt>Features</dt>
        <dd>{{phone.camera?.features?.join(', ')}}</dd>
      </dl>
    </li>
    <li>
      <span>Additional Features</span>
      <dd>{{phone.additionalFeatures}}</dd>
    </li>
  </ul>
</div>

There are several notable changes here:

We've removed the $ctrl. prefix from all expressions.
Just like we did in the phone list, we've replaced ng-src with property bindings for the standard src property.
We're using the property binding syntax around ng-class. Though Angular 2 does have a very similar ngClass as Angular 1 does, its value is not magically evaluated as an expression. In Angular 2 we always specify in the template when an attribute's value is a property expression, as opposed to a literal string.
We've replaced ng-repeats with *ngFors.
We've replaced ng-click with an event binding for the standard click.
We've wrapped the whole template in an ngIf that causes it only to be rendered when there is a phone present. We need this because when the component first loads, we don't have phone yet and the expressions will refer to a non-existing value. Unlike in Angular 1, Angular 2 expressions do not fail silently when we try to refer to properties on undefined objects. We need to be explicit about cases where this is expected.

Add this component to the NgModule declarations:

app.module.tsimport { PhoneDetailComponent } from './phone-detail/phone-detail.component';

@NgModule({
  imports: [
    BrowserModule,
    HttpModule,
    FormsModule,
  ],
  declarations: [
    PhoneListComponent,
    PhoneDetailComponent,
  ],
  providers: [ Phone ]
})
export class AppModule {}

In main.ts we'll now register a phoneDetail directive instead of a component. The directive is a downgraded version of the PhoneDetail Angular 2 component.

app/main.ts (excerpt)import { PhoneDetailComponent } from './phone-detail/phone-detail.component';

/* . . . */

angular.module('phoneDetail')
  .directive(
    'phoneDetail',
    upgradeAdapter.downgradeNg2Component(PhoneDetailComponent) as angular.IDirectiveFactory
  );

We should now also remove the phone detail component <script> tag from index.html.

Add the CheckmarkPipe

The Angular 1 directive had a checkmark filter. Turn that into an Angular 2 pipe.

There is no upgrade adapter method to convert filters into pipes. You won't miss it. It's easy to turn the filter function into an equivalent Pipe class. The implementation is the same as before, repackaged in the transform method. Rename the file to checkmark.pipe.ts to conform with Angular 2 conventions:

app/core/checkmark/checkmark.pipe.tsimport { Pipe, PipeTransform } from '@angular/core';

@Pipe({name: 'checkmark'})
export class CheckmarkPipe implements PipeTransform {
  transform(input: boolean) {
    return input ? '\u2713' : '\u2718';
  }
}

Now import and declare the newly created pipe and remove the filter <script> tag from index.html:

app.module.tsimport { CheckmarkPipe } from './core/checkmark/checkmark.pipe';

@NgModule({
  imports: [
    BrowserModule,
    HttpModule,
    FormsModule,
  ],
  declarations: [
    PhoneListComponent,
    PhoneDetailComponent,
    CheckmarkPipe
  ],
  providers: [ Phone ]
})
export class AppModule {}

Switching To The Angular 2 Router And Bootstrap

At this point we've replaced all Angular 1 application components with their Angular 2 counterparts.

The application is still bootstrapped as a hybrid app. There's no need for that anymore. It's time to remove the last remnants of Angular 1 in two final steps:

Switch to the Angular 2 router.
Bootstrap as a pure Angular 2 app.

Switch to the Angular 2 router

Angular 2 has an all-new router.

Like all routers, it needs a place in the UI to display routed views. The Angular 2 that's the <router-outlet> and it belongs in a root component at the top of the applications component tree.

We don't yet have such a root component, because the app is still managed as an Angular 1 app. Create a new app.component.ts file with the following AppComponent class:

app/app.component.tsimport { Component } from '@angular/core';

@Component({
  selector: 'phonecat-app',
  template: '<router-outlet></router-outlet>'
})
export class AppComponent {
}

It has a simple template that only includes the <router-outlet>. This component just renders the contents of the active route and nothing else.

The selector tells Angular 2 to plug this root component into the <phonecat-app> element on the host web page when the application launches.

Add this <phonecat-app> element to the index.html. It replaces the old Angular 1 ng-view directive:

index.html (body)  <body>
    <phonecat-app></phonecat-app>
  </body>
</html>

Create the Routing Module

A router needs configuration whether it's the Angular 1 or Angular 2 or any other router.

The details of Angular 2 router configuration are best left to the Routing documentation which recommends that you create a NgModule dedicated to router configuration (called a Routing Module):

app/app-routing.module.tsimport { NgModule } from '@angular/core';
import { Routes, RouterModule } from '@angular/router';
import { APP_BASE_HREF, HashLocationStrategy, LocationStrategy } from '@angular/common';

import { PhoneDetailComponent } from './phone-detail/phone-detail.component';
import { PhoneListComponent }   from './phone-list/phone-list.component';

const routes: Routes = [
  { path: '', redirectTo: 'phones', pathMatch: 'full' },
  { path: 'phones',          component: PhoneListComponent },
  { path: 'phones/:phoneId', component: PhoneDetailComponent }
];

@NgModule({
  imports: [ RouterModule.forRoot(routes) ],
  exports: [ RouterModule ],
  providers: [
    { provide: APP_BASE_HREF, useValue: '!' },
    { provide: LocationStrategy, useClass: HashLocationStrategy },
  ]
})
export class AppRoutingModule {}

This module defines a routes object with two routes to the two phone components and a default route for the empty path. It passes the routes to the RouterModule.forRoot method which does the rest.

A couple of extra providers enable routing with "hash" URLs such as #!/phones instead of the default "push state" strategy.

Now update the AppModule to import this AppRoutingModule and also the declare the root AppComponent:

app/app.module.tsimport { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { FormsModule } from '@angular/forms';
import { HttpModule } from '@angular/http';

import { AppRoutingModule } from './app-routing.module';
import { AppComponent }     from './app.component';
import { CheckmarkPipe }    from './core/checkmark/checkmark.pipe';
import { Phone }            from './core/phone/phone.service';
import { PhoneDetailComponent } from './phone-detail/phone-detail.component';
import { PhoneListComponent }   from './phone-list/phone-list.component';

@NgModule({
  imports: [
    BrowserModule,
    FormsModule,
    HttpModule,
    AppRoutingModule
  ],
  declarations: [
    AppComponent,
    PhoneListComponent,
    CheckmarkPipe,
    PhoneDetailComponent
  ],
  providers: [
    Phone,
  ],
  bootstrap: [ AppComponent ]
})
export class AppModule {}

The Angular 2 router passes route parameters differently. Correct the PhoneDetail component constructor to expect an injected ActivatedRoute object. Extract the phoneId from the ActivatedRoute.snapshot.params and fetch the phone data as before:

app/phone-detail/phone-detail.component.tsimport { Component }      from '@angular/core';
import { ActivatedRoute } from '@angular/router';

import { Phone, PhoneData } from '../core/phone/phone.service';

@Component({
  moduleId: module.id,
  selector: 'phone-detail',
  templateUrl: 'phone-detail.template.html'
})
export class PhoneDetailComponent {
  phone: PhoneData;
  mainImageUrl: string;

  constructor(activatedRoute: ActivatedRoute, phone: Phone) {
    phone.get(activatedRoute.snapshot.params['phoneId'])
      .subscribe((p: PhoneData) => {
        this.phone = p;
        this.setImage(p.images[0]);
      });
  }

  setImage(imageUrl: string) {
    this.mainImageUrl = imageUrl;
  }
}

Generate links for each phone

We no longer have to hardcode the links to phone details in the phone list. We can generate them data binding each phone's id to the routerLink directive and let that directive construct the appropriate URL to the PhoneDetailComponent:

app/phone-list/phone-list.template.html (list with links)<ul class="phones">
  <li *ngFor="let phone of getPhones()"
      class="thumbnail phone-list-item">
    <a [routerLink]="['/phones', phone.id]" class="thumb">
      <img [src]="phone.imageUrl" [alt]="phone.name" />
    </a>
    <a [routerLink]="['/phones', phone.id]" class="name">{{phone.name}}</a>
    <p>{{phone.snippet}}</p>
  </li>
</ul>

See the Routing page for details.

Bootstrap as an Angular 2 app

You may have noticed one extra bootstrap metadata property added to the AppModule

app/app.module.ts (bootstrap)bootstrap: [ AppComponent ]

That tells Angular 2 that it should bootstrap the app with the root AppComponent and insert it's view into the host web page.

Now switch the bootstrap method of the application from the UpgradeAdapter to the Angular 2 way. Because this is a browser application, compiled with the Just-in-Time (JiT) compiler, use the platformBrowserDynamic function to bootstrap the AppModule:

main.tsimport { platformBrowserDynamic } from '@angular/platform-browser-dynamic';

import { AppModule } from './app.module';

platformBrowserDynamic().bootstrapModule(AppModule);

You are now running a pure Angular 2 application!

Say Goodbye to Angular 1

It is time to take off the training wheels and let our application begin its new life as a pure, shiny Angular 2 app. The remaining tasks all have to do with removing code - which of course is every programmer's favorite task!

If you haven't already, remove all references to the UpgradeAdapter from main.ts. Also remove the Angular 1 bootstrap code.

When you're done, this is what main.ts should look like:

app/main.tsimport { platformBrowserDynamic } from '@angular/platform-browser-dynamic';

import { AppModule } from './app.module';

platformBrowserDynamic().bootstrapModule(AppModule);

You may also completely remove the following files. They are Angular 1 module configuration files and not needed in Angular 2:

app/app.module.ts
app/app.config.ts
app/core/core.module.ts
app/core/phone/phone.module.ts
app/phone-detail/phone-detail.module.ts
app/phone-list/phone-list.module.ts

The external typings for Angular 1 may be uninstalled as well. The only ones we still need are for Jasmine and Angular 2 polyfills.

npm run typings uninstall jquery -- --save --global npm run typings uninstall angular -- --save --global npm run typings uninstall angular-route -- --save --global npm run typings uninstall angular-resource -- --save --global npm run typings uninstall angular-mocks -- --save --global npm run typings uninstall angular-animate -- --save --global

Finally, from index.html, remove all references to Angular 1 scripts, the Angular 2 upgrade module, and jQuery. When we're done, this is what it should look like:

index.html<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <base href="/app/">
    <title>Google Phone Gallery</title>
    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css" />
    <link rel="stylesheet" href="app.css" />

    <script src="/node_modules/core-js/client/shim.min.js"></script>
    <script src="/node_modules/zone.js/dist/zone.js"></script>
    <script src="/node_modules/reflect-metadata/Reflect.js"></script>
    <script src="/node_modules/systemjs/dist/system.src.js"></script>
    <script src="/systemjs.config.js"></script>
    <script>
      System.import('/app');
    </script>
  </head>
  <body>
    <phonecat-app></phonecat-app>
  </body>
</html>

That is the last we'll see of Angular 1! It has served us well but now it's time to say goodbye.

Appendix: Upgrading PhoneCat Tests

Tests can not only be retained through an upgrade process, but they can also be used as a valuable safety measure when ensuring that the application does not break during the upgrade. E2E tests are especially useful for this purpose.

E2E Tests

The PhoneCat project has both E2E Protractor tests and some Karma unit tests in it. Of these two, E2E tests can be dealt with much more easily: By definition, E2E tests access our application from the outside by interacting with the various UI elements the app puts on the screen. E2E tests aren't really that concerned with the internal structure of the application components. That also means that although we modify our project quite a bit during the upgrade, the E2E test suite should keep passing with just minor modifications. This is because we don't change how the application behaves from the user's point of view.

During TypeScript conversion, there is nothing we have to do to keep E2E tests working. It is only when we start to upgrade components and their template to Angular 2 that we need to make some changes. This is because the E2E tests have matchers that are specific to Angular 1. For PhoneCat we need to make the following changes in order to make things work with Angular 2:

Previous code	New code	Notes
`by.repeater('phone in $ctrl.phones').column('phone.name')`	`by.css('.phones .name')`	The repeater matcher relies on Angular 1 `ng-repeat`
`by.repeater('phone in $ctrl.phones')`	`by.css('.phones li')`	The repeater matcher relies on Angular 1 `ng-repeat`
`by.model('$ctrl.query')`	`by.css('input')`	The model matcher relies on Angular 1 `ng-model`
`by.model('$ctrl.orderProp')`	`by.css('select')`	The model matcher relies on Angular 1 `ng-model`
`by.binding('$ctrl.phone.name')`	`by.css('h1')`	The binding matcher relies on Angular 1 data binding

When the bootstrap method is switched from that of UpgradeAdapter to pure Angular 2, Angular 1 ceases to exist on the page completely. At this point we need to tell Protractor that it should not be looking for an Angular 1 app anymore, but instead it should find Angular 2 apps from the page. The following change is then needed in protractor-conf.js:

useAllAngular2AppRoots: true,

Also, there are a couple of Protractor API calls in the PhoneCat test code that are using the Angular 1 $location service under the hood. As that service is no longer there after the upgrade, we need to replace those calls with ones that use WebDriver's generic URL APIs instead. The first of these is the redirection spec:

e2e-tests/scenarios.tsit('should redirect `index.html` to `index.html#!/phones', function() {
  browser.get('index.html');
  browser.waitForAngular();
  browser.getCurrentUrl().then(function(url: string) {
    expect(url.endsWith('/phones')).toBe(true);
  });
});

And the second is the phone links spec:

e2e-tests/scenarios.tsit('should render phone specific links', function() {
  let query = element(by.css('input'));
  // https://github.com/angular/protractor/issues/2019
  let str = 'nexus';
  for (let i = 0; i < str.length; i++) {
    query.sendKeys(str.charAt(i));
  }
  element.all(by.css('.phones li a')).first().click();
  browser.getCurrentUrl().then(function(url: string) {
    expect(url.endsWith('/phones/nexus-s')).toBe(true);
  });
});

Unit Tests

For unit tests, on the other hand, more conversion work is needed. Effectively they need to be upgraded along with the production code.

During TypeScript conversion no changes are strictly necessary. But it may be a good idea to convert the unit test code into TypeScript as well, as the same benefits we from TypeScript in production code also applies to tests.

For instance, in the phone detail component spec we can use not only ES2015 features like arrow functions and block-scoped variables, but also type definitions for some of the Angular 1 services we're consuming:

app/phone-detail/phone-detail.component.spec.tsdescribe('phoneDetail', () => {

  // Load the module that contains the `phoneDetail` component before each test
  beforeEach(angular.mock.module('phoneDetail'));

  // Test the controller
  describe('PhoneDetailController', () => {
    let $httpBackend: angular.IHttpBackendService;
    let ctrl: any;
    let xyzPhoneData = {
      name: 'phone xyz',
      images: ['image/url1.png', 'image/url2.png']
    };

    beforeEach(inject(($componentController: any,
                       _$httpBackend_: angular.IHttpBackendService,
                       $routeParams: angular.route.IRouteParamsService) => {
      $httpBackend = _$httpBackend_;
      $httpBackend.expectGET('phones/xyz.json').respond(xyzPhoneData);

      $routeParams['phoneId'] = 'xyz';

      ctrl = $componentController('phoneDetail');
    }));

    it('should fetch the phone details', () => {
      jasmine.addCustomEqualityTester(angular.equals);

      expect(ctrl.phone).toEqual({});

      $httpBackend.flush();
      expect(ctrl.phone).toEqual(xyzPhoneData);
    });

  });

});

Once we start the upgrade process and bring in SystemJS, configuration changes are needed for Karma. We need to let SystemJS load all the new Angular 2 code, which can be done with the following kind of shim file:

karma-test-shim.js// /*global jasmine, __karma__, window*/
Error.stackTraceLimit = 0; // "No stacktrace"" is usually best for app testing.

// Uncomment to get full stacktrace output. Sometimes helpful, usually not.
// Error.stackTraceLimit = Infinity; //

jasmine.DEFAULT_TIMEOUT_INTERVAL = 1000;

var builtPath = '/base/app/';

__karma__.loaded = function () { };

function isJsFile(path) {
  return path.slice(-3) == '.js';
}

function isSpecFile(path) {
  return /\.spec\.(.*\.)?js$/.test(path);
}

function isBuiltFile(path) {
  return isJsFile(path) && (path.substr(0, builtPath.length) == builtPath);
}

var allSpecFiles = Object.keys(window.__karma__.files)
  .filter(isSpecFile)
  .filter(isBuiltFile);

System.config({
  baseURL: '/base',
  // Extend usual application package list with test folder
  packages: { 'testing': { main: 'index.js', defaultExtension: 'js' } },

  // Assume npm: is set in `paths` in systemjs.config
  // Map the angular testing umd bundles
  map: {
    '@angular/core/testing': 'npm:@angular/core/bundles/core-testing.umd.js',
    '@angular/common/testing': 'npm:@angular/common/bundles/common-testing.umd.js',
    '@angular/compiler/testing': 'npm:@angular/compiler/bundles/compiler-testing.umd.js',
    '@angular/platform-browser/testing': 'npm:@angular/platform-browser/bundles/platform-browser-testing.umd.js',
    '@angular/platform-browser-dynamic/testing': 'npm:@angular/platform-browser-dynamic/bundles/platform-browser-dynamic-testing.umd.js',
    '@angular/http/testing': 'npm:@angular/http/bundles/http-testing.umd.js',
    '@angular/router/testing': 'npm:@angular/router/bundles/router-testing.umd.js',
    '@angular/forms/testing': 'npm:@angular/forms/bundles/forms-testing.umd.js',
  },
});

System.import('systemjs.config.js')
  .then(importSystemJsExtras)
  .then(initTestBed)
  .then(initTesting);

/** Optional SystemJS configuration extras. Keep going w/o it */
function importSystemJsExtras(){
  return System.import('systemjs.config.extras.js')
  .catch(function(reason) {
    console.log(
      'Warning: System.import could not load the optional "systemjs.config.extras.js". Did you omit it by accident? Continuing without it.'
    );
    console.log(reason);
  });
}

function initTestBed(){
  return Promise.all([
    System.import('@angular/core/testing'),
    System.import('@angular/platform-browser-dynamic/testing')
  ])

  .then(function (providers) {
    var coreTesting    = providers[0];
    var browserTesting = providers[1];

    coreTesting.TestBed.initTestEnvironment(
      browserTesting.BrowserDynamicTestingModule,
      browserTesting.platformBrowserDynamicTesting());
  })
}

// Import all spec files and start karma
function initTesting () {
  return Promise.all(
    allSpecFiles.map(function (moduleName) {
      return System.import(moduleName);
    })
  )
  .then(__karma__.start, __karma__.error);
}

The shim first loads the SystemJS configuration, then Angular 2's test support libraries, and then the application's spec files themselves.

Karma configuration should then be changed so that it uses the application root dir as the base directory, instead of app.

karma.conf.jsbasePath: './',

Once this is done, we can load SystemJS and other dependencies, and also switch the configuration for loading application files so that they are not included to the page by Karma. We'll let the shim and SystemJS load them.

karma.conf.js// System.js for module loading
'node_modules/systemjs/dist/system.src.js',

// Polyfills
'node_modules/core-js/client/shim.js',
'node_modules/reflect-metadata/Reflect.js',

// zone.js
'node_modules/zone.js/dist/zone.js',
'node_modules/zone.js/dist/long-stack-trace-zone.js',
'node_modules/zone.js/dist/proxy.js',
'node_modules/zone.js/dist/sync-test.js',
'node_modules/zone.js/dist/jasmine-patch.js',
'node_modules/zone.js/dist/async-test.js',
'node_modules/zone.js/dist/fake-async-test.js',

// RxJs.
{ pattern: 'node_modules/rxjs/**/*.js', included: false, watched: false },
{ pattern: 'node_modules/rxjs/**/*.js.map', included: false, watched: false },

// Angular 2 itself and the testing library
{pattern: 'node_modules/@angular/**/*.js', included: false, watched: false},
{pattern: 'node_modules/@angular/**/*.js.map', included: false, watched: false},

{pattern: 'systemjs.config.js', included: false, watched: false},
'karma-test-shim.js',

{pattern: 'app/**/*.module.js', included: false, watched: true},
{pattern: 'app/*!(.module|.spec).js', included: false, watched: true},
{pattern: 'app/!(bower_components)/**/*!(.module|.spec).js', included: false, watched: true},
{pattern: 'app/**/*.spec.js', included: false, watched: true},

{pattern: '**/*.html', included: false, watched: true},

Since the HTML templates of Angular 2 components will be loaded as well, we need to help Karma out a bit so that it can route them to the right paths:

karma.conf.js// proxied base paths for loading assets
proxies: {
  // required for component assets fetched by Angular's compiler
  "/phone-detail": '/base/app/phone-detail',
  "/phone-list": '/base/app/phone-list'
},

The unit test files themselves also need to be switched to Angular 2 when their production counterparts are switched. The specs for the checkmark pipe are probably the most straightforward, as the pipe has no dependencies:

app/core/checkmark/checkmark.pipe.spec.tsimport { CheckmarkPipe } from './checkmark.pipe';

describe('CheckmarkPipe', function() {

  it('should convert boolean values to unicode checkmark or cross', function () {
    const checkmarkPipe = new CheckmarkPipe();
    expect(checkmarkPipe.transform(true)).toBe('\u2713');
    expect(checkmarkPipe.transform(false)).toBe('\u2718');
  });
});

The unit test for the phone service is a bit more involved. We need to switch from the mocked-out Angular 1 $httpBackend to a mocked-out Angular 2 Http backend.

app/core/phone/phone.service.spec.tsimport { inject, TestBed } from '@angular/core/testing';
import {
  Http,
  BaseRequestOptions,
  ResponseOptions,
  Response
} from '@angular/http';
import { MockBackend, MockConnection } from '@angular/http/testing';
import { Phone, PhoneData } from './phone.service';

describe('Phone', function() {
  let phone: Phone;
  let phonesData: PhoneData[] = [
    {name: 'Phone X', snippet: '', images: []},
    {name: 'Phone Y', snippet: '', images: []},
    {name: 'Phone Z', snippet: '', images: []}
  ];
  let mockBackend: MockBackend;

  beforeEach(() => {
    TestBed.configureTestingModule({
      providers: [
        Phone,
        MockBackend,
        BaseRequestOptions,
        { provide: Http,
          useFactory: (backend: MockBackend, options: BaseRequestOptions) => new Http(backend, options),
          deps: [MockBackend, BaseRequestOptions]
        }
      ]
    });
  });

  beforeEach(inject([MockBackend, Phone], (_mockBackend_: MockBackend, _phone_: Phone) => {
    mockBackend = _mockBackend_;
    phone = _phone_;
  }));

  it('should fetch the phones data from `/phones/phones.json`', (done: () => void) => {
    mockBackend.connections.subscribe((conn: MockConnection) => {
      conn.mockRespond(new Response(new ResponseOptions({body: JSON.stringify(phonesData)})));
    });
    phone.query().subscribe(result => {
      expect(result).toEqual(phonesData);
      done();
    });
  });

});

For the component specs we can mock out the Phone service itself, and have it provide canned phone data. We use Angular's component unit testing APIs for both components.

app/phone-detail/phone-detail.component.spec.tsimport { ActivatedRoute } from '@angular/router';

import { Observable } from 'rxjs/Rx';

import { async, TestBed } from '@angular/core/testing';

import { PhoneDetailComponent } from './phone-detail.component';
import { Phone, PhoneData } from '../core/phone/phone.service';
import { CheckmarkPipe } from '../core/checkmark/checkmark.pipe';

function xyzPhoneData(): PhoneData {
  return {
    name: 'phone xyz',
    snippet: '',
    images: ['image/url1.png', 'image/url2.png']
  };
}

class MockPhone {
  get(id: string): Observable<PhoneData> {
    return Observable.of(xyzPhoneData());
  }
}


class ActivatedRouteMock {
  constructor(public snapshot: any) {}
}


describe('PhoneDetailComponent', () => {


  beforeEach(async(() => {
    TestBed.configureTestingModule({
      declarations: [ CheckmarkPipe, PhoneDetailComponent ],
      providers: [
        { provide: Phone, useClass: MockPhone },
        { provide: ActivatedRoute, useValue: new ActivatedRouteMock({ params: { 'phoneId': 1 } }) }
      ]
    })
    .compileComponents();
  }));

  it('should fetch phone detail', () => {
    const fixture = TestBed.createComponent(PhoneDetailComponent);
    fixture.detectChanges();
    let compiled = fixture.debugElement.nativeElement;
    expect(compiled.querySelector('h1').textContent).toContain(xyzPhoneData().name);
  });

});

app/phone-list/phone-list.component.spec.tsimport { NO_ERRORS_SCHEMA } from '@angular/core';
import { ActivatedRoute } from '@angular/router';
import { Observable } from 'rxjs/Rx';
import { async, ComponentFixture, TestBed } from '@angular/core/testing';
import { SpyLocation } from '@angular/common/testing';

import { PhoneListComponent } from './phone-list.component';
import { Phone, PhoneData } from '../core/phone/phone.service';

class ActivatedRouteMock {
  constructor(public snapshot: any) {}
}

class MockPhone {
  query(): Observable<PhoneData[]> {
    return Observable.of([
      {name: 'Nexus S', snippet: '', images: []},
      {name: 'Motorola DROID', snippet: '', images: []}
    ]);
  }
}

let fixture: ComponentFixture<PhoneListComponent>;

describe('PhoneList', () => {

  beforeEach(async(() => {
    TestBed.configureTestingModule({
      declarations: [ PhoneListComponent ],
      providers: [
        { provide: ActivatedRoute, useValue: new ActivatedRouteMock({ params: { 'phoneId': 1 } }) },
        { provide: Location, useClass: SpyLocation },
        { provide: Phone, useClass: MockPhone },
      ],
      schemas: [ NO_ERRORS_SCHEMA ]
    })
    .compileComponents();
  }));

  beforeEach(() => {
    fixture = TestBed.createComponent(PhoneListComponent);
  });

  it('should create "phones" model with 2 phones fetched from xhr', () => {
    fixture.detectChanges();
    let compiled = fixture.debugElement.nativeElement;
    expect(compiled.querySelectorAll('.phone-list-item').length).toBe(2);
    expect(
      compiled.querySelector('.phone-list-item:nth-child(1)').textContent
    ).toContain('Motorola DROID');
    expect(
      compiled.querySelector('.phone-list-item:nth-child(2)').textContent
    ).toContain('Nexus S');
  });

  xit('should set the default value of orderProp model', () => {
    fixture.detectChanges();
    let compiled = fixture.debugElement.nativeElement;
    expect(
      compiled.querySelector('select option:last-child').selected
    ).toBe(true);
  });

});

Finally, we need to revisit both of the component tests when we switch to the Angular 2 router. For the details component we need to provide a mock of Angular 2 ActivatedRoute object instead of using the Angular 1 $routeParams.

app/phone-detail/phone-detail.component.spec.tsimport { ActivatedRoute } from '@angular/router';

/* . . . */

class ActivatedRouteMock {
  constructor(public snapshot: any) {}
}

/* . . . */

  beforeEach(async(() => {
    TestBed.configureTestingModule({
      declarations: [ CheckmarkPipe, PhoneDetailComponent ],
      providers: [
        { provide: Phone, useClass: MockPhone },
        { provide: ActivatedRoute, useValue: new ActivatedRouteMock({ params: { 'phoneId': 1 } }) }
      ]
    })
    .compileComponents();
  }));

And for the phone list component we need to set up a few things for the router itself so that the route link directive will work.

app/phone-list/phone-list.component.spec.tsimport { NO_ERRORS_SCHEMA } from '@angular/core';
import { ActivatedRoute } from '@angular/router';
import { Observable } from 'rxjs/Rx';
import { async, ComponentFixture, TestBed } from '@angular/core/testing';
import { SpyLocation } from '@angular/common/testing';

import { PhoneListComponent } from './phone-list.component';
import { Phone, PhoneData } from '../core/phone/phone.service';

/* . . . */

  beforeEach(async(() => {
    TestBed.configureTestingModule({
      declarations: [ PhoneListComponent ],
      providers: [
        { provide: ActivatedRoute, useValue: new ActivatedRouteMock({ params: { 'phoneId': 1 } }) },
        { provide: Location, useClass: SpyLocation },
        { provide: Phone, useClass: MockPhone },
      ],
      schemas: [ NO_ERRORS_SCHEMA ]
    })
    .compileComponents();
  }));

  beforeEach(() => {
    fixture = TestBed.createComponent(PhoneListComponent);
  });

Sep	OCT	Nov
	18
2015	2016	2017