Angular2 TypeScript Gulp and ExpressJS

Let’s get started. You’ll need NodeJS for this project. Make sure you have npm installed as well.

You’ll need some global tools too. You might need to run these as sudo or “Run As Administrator” if you’re using windows.

1	npm install --global typescript gulp tsd

• typescript is our global typescript compiler
• gulp is a build tool that’s crazy popular now and will help us create beautiful expressive build commands
• tsd is a package manager for downloading TypeScript definition files. We’ll primarily use this for expressjs

Base Project Setup

Create a new directory and install some dependencies.

1 2 3

mkdir sample cd sample npm init -y #creates a default npm project

Now in your package.json file copy the following dependencies in:

1 2 3 4 5 6 7 8 9 10 11

"dependencies": {     "angular2": "2.0.0-beta.1",     "es6-promise": "3.0.2",     "es6-shim": "0.33.3",     "express": "4.13.3",     "gulp-concat": "2.6.0",     "reflect-metadata": "0.1.2",     "rxjs": "5.0.0-beta.0",     "systemjs": "0.19.16",     "zone.js": "0.5.10"   }

And also these:

1 2 3 4 5 6 7 8

"devDependencies": {     "del": "2.2.0",     "gulp": "3.9.0",     "gulp-concat": "2.6.0",     "gulp-sourcemaps": "1.6.0",     "gulp-typescript": "2.10.0",     "run-sequence": "1.1.5"   }

Let’s get all the packages that that we need by running:

1	npm install

We’ll have 2 different folders inside out project one for front-end stuff and one for backend stuff. In addition let’s create a file called “gulpfile.js“. This will be our build file.

1 2 3

mkdir client mkdir server touch gulpfile.js

Our directory will look something like this:

1 2 3 4 5

sample/      /node_modules      /client      /server      gulpfile.js

Server Setup

Inside the server folder we’re going to create a tsconfig.json file. This tells our typescript compiler some information about how to compile our .ts extension files. You can read more about tsconfig.json files here.

Let’s create the tsconfig.json in “/server” with the following contents.

1 2 3 4 5 6 7 8 9 10 11

{   "compilerOptions": {     "target": "ES5",     "module": "commonjs",     "sourceMap": true,     "emitDecoratorMetadata": true,     "experimentalDecorators": true,     "removeComments": false,     "noImplicitAny": false   } }

In our server directory. We’ll need to start a typescript definition file.

1 2	cd server tsd init -y

Now we’ll install express’s typescript definition with:

1 2	cd server tsd install express -s

Your server folder should look something like this:

1 2 3 4 5 6 7 8

sample/     /node_modules     /client     /server           /tsd.json           /typings           tsconfig.json           tsd.json

The typings folder should have all the definition files that express needs.

Now let’s create our server.ts file. This a basic ExpressJS server in TypeScript.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

import express = require('express'); import path = require('path'); var port: number = process.env.PORT || 3000; var app = express();   app.use('/app', express.static(path.resolve(__dirname, 'app'))); app.use('/libs', express.static(path.resolve(__dirname, 'libs')));   var renderIndex = (req: express.Request, res: express.Response) => {     res.sendFile(path.resolve(__dirname, 'index.html')); }   app.get('/*', renderIndex);   var server = app.listen(port, function() {     var host = server.address().address;     var port = server.address().port;     console.log('This express app is listening on port:' + port); });

• This server will run on port 3000 unless given an environment variable about the port. This is great if you’re deploying to Heroku or Azure websites
• All routes render the “index.html” file that we will put in the client folder.
• I’ve used path.resolve here for all you windows developers.
• I’ve exposed a folder called “/app” and “/libs” as static public directories. “/app” will house all of our built Angular2 code. “/libs” will house all of the dependencies that we should include before our app starts. These folders don’t exist yet but don’t worry since we will take care of them when we get to building the project.

That’s all it takes to setup the back-end server. You can extend whatever you’d like with your standard Express app like API end-points.

Moving on to the Front-End

In the “/client” folder, create an “index.html” file and put the following contents in it:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34

<html>     <head>     <title>newfamily-example</title>     <base href="/"/>       <!-- 1. Load libraries -->     <script src="libs/angular2/bundles/angular2-polyfills.js"></script>     <script src="libs/systemjs/dist/system.src.js"></script>     <script src="libs/rxjs/bundles/Rx.js"></script>     <script src="libs/angular2/bundles/angular2.dev.js"></script>     <script src="libs/angular2/bundles/router.dev.js"></script>       <!-- 2. Configure SystemJS -->     <script>       System.config({         packages: {                   app: {             format: 'register',             defaultExtension: 'js'           }         }       });       System.import('app/bootstrap')             .then(null, console.error.bind(console));     </script>     </head>   <!-- 3. Display the application -->   <body>     <my-app>Loading...</my-app>   </body>   </html>

The file is the basic entry HTML file for our angular app. As you notice, we’ve included the scripts in the “libs” folder. This is the same folder that we’ve made public in the server setup section. We’ll include some important scripts that we’ll need to get Angular2 working like Angular-Polyfills, SystemJS, Router etc…

The second part is that we have setup “SystemJS”. To keep this tutorial small and easy to digest, I’ll avoid a large overview of what it does. SystemJS allows us to load module-based scripts in the browser.  We configure SystemJS to note that our Angular2 app (which is placed the “app” folder”) is a package that has a default extension. Then when the package is loaded, we tell SystemJS to start our Angular2 application in the “import” method.  SystemJS is a large topic for another day, so if you’d like to know more then please visit: https://github.com/systemjs/systemjs

When developing an Angular2 App in TypeScript, you should include it’s own specifictsconfig.json seperate from your server tsconfig.json.

In the client folder you should create another tsconfig.json file with the following contents:

1 2 3 4 5 6 7 8 9 10 11 12

{   "compilerOptions": {     "target": "ES5",     "module": "system",     "moduleResolution": "node",     "sourceMap": true,     "emitDecoratorMetadata": true,     "experimentalDecorators": true,     "removeComments": false,     "noImplicitAny": false   } }

Finally some Angular2 code

Our Angular2 code will all be in client/app folder. Let’s create the bootstrap.ts file that SystemJS will call to get our Angular2 app up and running.

1 2 3 4 5 6 7 8 9 10 11

import {bootstrap}    from 'angular2/platform/browser' import {provide}    from 'angular2/core' import {CORE_DIRECTIVES} from 'angular2/common' import {ROUTER_BINDINGS, ROUTER_PROVIDERS, LocationStrategy, PathLocationStrategy} from 'angular2/router'   import {AppComponent} from './components/app/AppComponent' bootstrap(AppComponent, [     ROUTER_PROVIDERS,     CORE_DIRECTIVES,     provide(LocationStrategy, {useClass: PathLocationStrategy}) ]);

So there are a lot of things happening here:

We are importing some key functions and classes into our bootstrap.ts file. These are all inputs for angular2’s bootstrap function.

In our gulpfile.js which is in the root of the project let’s add some build code.

First let’s include our packages.

1 2 3

var path = require('path'); var gulp = require('gulp'); var ts = require('gulp-typescript');

Next let’s create a task called buildServer.

1 2 3 4 5 6 7

gulp.task('buildServer', function () { var tsProject = ts.createProject(path.resolve('./server/tsconfig.json')); return gulp.src(path.resolve('./server/**/*.ts')) .pipe(ts(tsProject)) .js .pipe(gulp.dest(path.resolve('./server'))) });

This task takes our tsconfig.json and assumes that the server folder is a TypeScript project. Then it tells it to build all the files in that folder using that tsconfig.json and then dump the built js files into the same folder. Server files don’t need concatenation so it’s totally okay not to concatenate them.

You can run this task by navigating to the root directory and running

1	gulp buildServer

Then you should see some files in the buildServer directory:

1 2 3 4 5 6

sample /        /server              /server.ts               server.js               server.js.map               .. other files...

Front-End setup

Now that we’re done with the backbone of the project, we need to start on the client.

Go to the client folder and create an index.html and a tsconfig.json

1 2 3

cd sample/client touch index.html touch tsconfig.json

The tsconfig.json is exactly the same as before:

1 2 3 4 5 6 7 8 9 10 11

{   "compilerOptions": {     "target": "ES5",     "module": "commonjs",     "sourceMap": true,     "emitDecoratorMetadata": true,     "experimentalDecorators": true,     "removeComments": false,     "noImplicitAny": false   } }

Now in the index.html

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33

<html>   <head>     <title>Sample App</title>     <base href="/" />     <script src="/node_modules/systemjs/dist/system.src.js"></script>     <script src="/node_modules/angular2/bundles/angular2.dev.js"></script>     <script src="/node_modules/angular2/bundles/router.dev.js"></script>     <script src="/node_modules/angular2/bundles/http.dev.js"></script>       <script>         System.config({             baseUrl: "/",             packages: {                 'client/app': {                     defaultExtension: 'js',                 },                 'rxjs': {                     defaultExtension: 'js'                 }             },             map: {                 "rxjs": "/node_modules/rxjs",         });         System.import('client/app/app.js');     </script> </head>   <body>     <my-app>Loading...</my-app> </body>   </html>

There’s a lot of information going on here.

First we need to give Angular2 a good base href to grab on to. This is important for routing. I set the base to the current root of the URL with:

1	<base href="/">

We exposed our node_modules folder publically and proceed to tell the browser to pull the angular framework into the head. We’ll need SystemJS as well:

1 2 3 4

<script src="/node_modules/systemjs/dist/system.src.js"></script> <script src="/node_modules/angular2/bundles/angular2.dev.js"></script> <script src="/node_modules/angular2/bundles/router.dev.js"></script> <script src="/node_modules/angular2/bundles/http.dev.js"></script>

SystemJS is a tool to help us modularize JavaScript code. The Angular team looks like they heavily prefer using SystemJS, so let’s start early while we can. Angular2 heavily uses RxJS v5 and you’ll more than likely import it into your files. I’ve taken the liberty to show you how SystemJS can map a specific import to a module.

1 2 3 4 5 6 7 8 9 10 11 12 13 14

System.config({             baseUrl: "/",             packages: {                 'client/app': {                     defaultExtension: 'js',                 },                 'rxjs': {                     defaultExtension: 'js'                 }             },             map: {                 "rxjs": "/node_modules/rxjs",         }); System.import('client/app/app.js');

Finally, we’ll need to import our app.js file. (We’ll create this soon) At this point you can test to see if the server is working by calling the server code we just built.

1	node server/server.js

You can now open your browser to “http://localhost:3000” and you should see a “loading” text.

Angular2 code

Inside the client folder, create another folder called “app”. This will house all of our Angular2 application code.

Inside app, create an app.ts file:

1 2 3 4 5 6 7 8 9 10 11 12 13 14

import {Component, bootstrap} from 'angular2/angular2' import {RouteConfig, RouterLink, RouterOutlet, LocationStrategy, PathLocationStrategy, ROUTER_PROVIDERS, ROUTER_DIRECTIVES} from 'angular2/router'   @Component({ selector: 'my-app', template: `<router-outlet></router-outlet>`, directives: [ROUTER_DIRECTIVES, RouterOutlet] }) export class App { } bootstrap(App, [     ROUTER_PROVIDERS,     bind(LocationStrategy).toClass(PathLocationStrategy) ]);

The first part we import our modules and the objects and classes that we want. Notice that TypeScript supports ES6 module loading. We import Component, which allows us to annotate our classes with angular2 information. It gives the Angular2 runtime a lot of information about which directives to use, which selector to attach to and the inner-html inside the component.

Next we have to tell the Component about the application class. We make it available to other modules by dictating it with the “export” identifier.

Next, we call the angular2 bootstrap method which tells Angular2 to initialize our app with some dependencies.

The bootstrap method also allows us to specify how we want Angular2 to handle routing. I prefer routes not to have the “#” navigation system and opt in for HTML5 routing.

In our server code, we told express that we want to route all uncaught routes to our index.html file. Recall:

1 2 3 4

var renderIndex = (req: express.Request, res: express.Response) => {     res.sendFile(path.resolve(__dirname, 'index.html')); } app.get('/*', renderIndex);

Thus, this will tell our Angular2 runtime to handle all the routing.

Creating our components.

We’ll create 2 stub components. They’ll have minimal information but they’ll get the point across. The two components will be home and about.

In our app folder. Create a folder called “components”. And inside that create 2 directories “home” and “about”. Then create 2 files for each component: HomeComponent.ts and AboutComponent.ts

The files should be here.

1 2 3 4 5 6 7

sample/       /client/              /app/                  app.ts                  /components/                             home/HomeComponent.ts                             about/AboutComponent.ts

In HomeComponent.ts

We’ll create a basic component:

1 2 3 4 5 6 7 8 9 10 11 12 13

import {Component} from 'angular2/angular2'   @Component({ template: '<h1>{{titleName}}</h1>', selector: 'home' }) export class HomeComponent{         titleName: string constructor(){             this.titleName = "Hello from Home" } }

As you can see we’re demonstrating some simple mechanisms of Angular2 by passing some code data to our HTML by manipulating the property “titleName”.

In LoginComponent.ts, we’ll do pretty much the same thing:

1 2 3 4 5 6 7 8 9 10 11 12 13

import {Component} from 'angular2/angular2'   @Component({ template: '<h1>{{titleName}}</h1>', selector: 'home' }) export class LoginComponent{         titleName: string         constructor(){             this.titleName = "Hello from Login" } }

Now let’s hook the two Components up by routing

Back in the app.ts file let’s configure the routes:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

import {Component} from 'angular2/angular2' import {RouterOutlet, RouteConfig, ROUTER_DIRECTIVES, PathLocationStrategy, LocationStrategy} from 'angular2/router'     import {LoginComponent} from './components/LoginComponent' import {HomeComponent} from './components/HomeComponent'     @Component({ selector: 'my-app', template: `<router-outlet></router-outlet>`, directives: [ROUTER_DIRECTIVES, RouterOutlet] }) @RouteConfig([ {path: '/', component: HomeComponent, as: 'Home'}, {path: '/login', component: LoginComponent, as: 'Login'} ]) export class App { } bootstrap(App, [     ROUTER_PROVIDERS,     bind(LocationStrategy).toClass(PathLocationStrategy) ]);

This should give us our proper routing!