Configuration Tips to build Hybrid Angular 1 and Angular 2 project in real world

4 min readMar 7, 2016

I think many people like me would like to upgrade Angular 2, but encounter configuration issue. In fact, that is the main problem in Angular 1 migrate to Angular 2. Because if you don’t have a good configuration, you could not start your code, much less learn TypeScript or ES6 in Angular 2.

Angular 2 official site provided 5 min quick start to introduce how to configure Angular 2 project. It is magical, awesome quick start. But I think there are some tips for building up hybrid Angular web app successfully in real world. Here I would like to share my build up experience, maybe it could be useful for somebody.

Start from Angular 1 project

My original Angular 1 project structure like this:

src/
----- app/
---------- admin-management/
---------- dashboard/
---------- api-usage/
           ...
---------- app.js
---------- config-init.js
---------- config-route.js
....
node_modules/
gulpfile.js
package.json
index.html

Install Angular 2 dependency libraries

There are three configuration json files need to be modified:

package.json — for npm, already in project, need to be modfied
tsconfig.json — for typescript compile configuration, need to be added in project
typings.json — for typescript compile configuration, need to be added in project

package.json

{
  "name": "angular2-quickstart",
  "version": "1.0.0",
  "scripts": {
    "start": "concurrently \"npm run tsc:w\" \"npm run lite\" ",    
    "tsc": "tsc",
    "tsc:w": "tsc -w",
    "lite": "lite-server",
    "typings": "typings",
    "postinstall": "typings install" 
  },
  "license": "ISC",
  "dependencies": {
    "angular2": "2.0.0-beta.7",
    "systemjs": "0.19.22",
    "es6-promise": "^3.0.2",
    "es6-shim": "^0.33.3",
    "reflect-metadata": "0.1.2",
    "rxjs": "5.0.0-beta.2",
    "zone.js": "0.5.15"
  },
  "devDependencies": {
    "concurrently": "^2.0.0",
    "lite-server": "^2.1.0",
    "typescript": "^1.8.2",
    "typings":"^0.6.8"
  }
}

Tips: when you run npm run start , it will execute npm run tsc:w and npm run lite at the same time. In other words, it will compile typescript to javascript (npm run tsc) and run lite server(npm run lite).

tsconfig.json

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

Tips: After npm install, there will be generated typings folder, that why typings/main in exclude here. In compilerOptions, target means language typescript want to compile .

typings.json

{
  "ambientDependencies": {
    "es6-shim": "github:DefinitelyTyped/DefinitelyTyped/es6-shim/es6-shim.d.ts#6697d6f7dadbf5773cb40ecda35a76027e0783b2"
  }
}

Tips: After npm install, there will be generated typings folder. typings.json shows which TypeScript type definition files needed in project.

Add JavaScript dependencies to Index.html

There are three parts to be added in index.html: ( boot.js will be compiled from boot.ts, we will talk later ).

Add angular 2 dependency libraries
Add upgrade.js. it has UpgradeAdapter, we will import it into boot.js and that is the key for hybrid Angular 1 and 2 app.
Add SystemJS inline script. It will load boot.js that make a bootstrap entry point using ngUpgrade.

My original Index.html:

Add dependency libraries and upgrade.js

Because npm already installed relevant dependencies, we can link them from node_modules path, look at lines 22–31:

Add System.js Script

Add SystemJS script to index.html bottom. SystemJS is the module loader — Universal dynamic module loader which could load ES6 modules, AMD, CommonJS and global scripts in the browser and NodeJS. In lines 46–57 we are configuring SystemJS to load boot.js.

Tips: Notice line 12, we don’t need ng-app any more, we will use bootstrap script (boot.ts) to make a bootstrap entry point in Angular 2.
Tips: Notice line 48, there are src key under packages property. because boot.js path is src/app, the key under packages should 「match」 the source folder. In other words, if our boot.js is under src/main, it should be like:

System.config({
                packages: {
                    main:{
                        format: 'register',
                        defaultExtension: 'js'
                    }
                }
            });System.import('src/main/boot')
                .then(null, console.error.bind(console));

First Angular 2 Component

Good news, We finished all Angular 2 configurations. We can begin writing our first Angular 2 Component. Create ng2 folder under src/app, then add new typescript file call ng2.component.ts :

now our project is like:

src/
----- app/
---------- admin-management/
---------- dashboard/
---------- api-usage/
---------- ng2/
--------------- ng2.component.ts
           ...
---------- app.js
---------- config-init.js
---------- config-route.js
....
node_modules/
gulpfile.js
package.json
index.html

Bootstrap Angular Hybrid App from UpgradeAdapter

Finally we could write the most important bootstrap script — boot.ts. Create boot.ts typescript file under src/app. Magic bootstrap Hybrid Angular here:

Tips: Remember upgrade.js? Here we imported UpgradAdapter module from it, then we used adapter instance of UpgradeAdapter to bootstrap hybrid Angular project. We also imported our first Angular 2 component — ng2.component.js we created before, used downgradeNg2Component to make Angular 2 Component build on Angular 1 Directive.
Tips: The awesome part is you do not need to modify angular.module(‘AdminApp’, [ … ]) or declare app variable here, you can directly use app.directive, because you already declare app variable in the original app.js.

now our project is like:

src/
----- app/
---------- admin-management/
---------- dashboard/
---------- api-usage/
---------- ng2/
--------------- ng2.component.ts
           ...
---------- app.js
---------- boot.ts
---------- config-init.js
---------- config-route.js
....
node_modules/
gulpfile.js
package.json
index.html

Run Awesome Hybrid Angular Project !

You can’t believe it, Only one command line under the project folder:

npm run start

Finished! Amazing!

Tips: When you run npm run start, actually it will execute npm run tsc:w and npm run lite at the same time. npm run tsc:w — typescript compiler will compile the typescript files under src/app to EcmaScript 5. npm run lite — it will start up lite server.
Tips: After npm run tsc, it will generate boot.js and ng2.component.js. The two file will be loaded in our project with SystemJS we configured before.

the Compiled project will be:

src/
----- app/
---------- admin-management/
---------- dashboard/
---------- api-usage/
---------- ng2/
--------------- ng2.component.ts
--------------- ng2.component.js
           ...
---------- app.js
---------- boot.ts
---------- boot.js
---------- config-init.js
---------- config-route.js
....
node_modules/
gulpfile.js
package.json
index.html

Fin

Everything is clear now, Enjoy the Awesome Hybrid Angular Web App :)