Check out our Angular Book Series.

Directories and SystemJS Config - Building Angular 2 Applications with Gulp - Part 1

I wrote an extended white paper on my Gulp process to compile Angular 2 TypeScript applications, and decided to turn some of it into a series of blog posts. The first part of this series will talk about the directory structure of the project, the initial setup, and SystemJS configuration. By the end of this series you'll have a good architecture for building Angular 2 applications with Gulp.

Directory Structure

You can find all the code for this series in our DotComIt GitHub Repository for project seeds. We structure our projects like this:

  • build: The directory where the compiled code is placed. The root will most contain the main index file.
    • com: Our compiled JavaScript code is put in a com directory, mimicking the package structure of a lot of Java package code. This may also include HTML Templates. For Angular 2 applications, I've seen this directory called 'app' in some uses
    • maps: Source Maps are placed in this directory, if they are generated.
    • js: JavaScript libraries are placed here, if any are required for the project. Some of these are copied over from node_modules, while others may be copied from the src directory.
  • node_modules: A directory that contains relevant modules installed by Node, such as Gulp, TypeScript, and the Angular libraries.
  • src: The directory where our source code goes. The root directory will contain the main index.html file, but not usually much else.
    • com: Our TypeScript code is put in a com directory, mimicking the package structure of a lot of Java package code.
    • js: JavaScript libraries are placed here, if any are required for the project. A default SystemJS Configuration is put in the source directory.

I am not going to examine a sample TypeScript application in detail as part of this series. The GitHub repository includes a simple Hello World application, which will suffice for our demonstration purposes.

Initial NodeJS Setup

Gulp runs on top of NodeJS, so you'll need that. After that, we need to create a package.json in the root directory of your project. Copy and paste this into the file:

"name": "TypeScriptAngular2Sample",
"version": "0.0.1",
"description": "TypeScript Angular 2 Sample for Article.",
"author": "Jeffry Houser",
"license": "ISC",
"dependencies": {
"@angular/common": "~2.4.0",
"@angular/compiler": "~2.4.0",
"@angular/core": "~2.4.0",
"@angular/forms": "~2.4.0",
"@angular/http": "~2.4.0",
"@angular/platform-browser": "~2.4.0",
"@angular/platform-browser-dynamic": "~2.4.0",
"@angular/router": "~3.4.0",
"angular-in-memory-web-api": "~0.2.2",
"systemjs": "0.19.40",
"core-js": "^2.4.1",
"reflect-metadata": "^0.1.8",
"rxjs": "5.0.1",
"zone.js": "^0.7.4"
"devDependencies": {
"gulp": "^3.9.1",
"typescript": "^2.1.5"
"repository": {}

This includes all the major Angular 2 libraries and dependencies in the dependency section. The devDependencies section includes Gulp and TypeScript. Install all this stuff with one command:

npm install

You'll see something like this:

This creates the node_modules directory; and installs all the modules specified in the package.json, along with any related dependencies. This is the base we use for creating our build scripts. As we need Gulp plugins we'll install them individually in future installments.

SystemJS Configuration

Angular 2 uses a module loader system named SystemJS to give the browser require() functionality like you'd use on the server side with NodeJS. We need to provide a configuration to SystemJS so that it knows how to find our custom app code, and the required Angular libraries. I put this file in the src/js/systemJSConfig directory.

Setup the file with an Immediately Invoked Function Express (IIFE):

(function (global) {

This is the JavaScript method to create a self-executing function. Inside the function, we want to configure SystemJS:


The config() method is used to configure the SystemJS library. It takes an object, which is currently empty. Add in a paths configuration:

paths: {
'js:': 'js/'

This configuration object tells the library that the js path will point to the js directory. When we write build scripts, we'll put all the relevant Angular libraries in the JS sub-directory of our final build. Next, create a map configuration:

map: {
app: 'com',
'@angular/core': 'js:@angular/core/bundles/core.umd.js',
'@angular/common': 'js:@angular/common/bundles/common.umd.js',
'@angular/compiler': 'js:@angular/compiler/bundles/compiler.umd.js',
'@angular/platform-browser': 'js:@angular/platform-browser/bundles/platform-browser.umd.js',
'@angular/platform-browser-dynamic': 'js:@angular/platform-browser-dynamic/bundles/platform-browser-dynamic.umd.js',
'@angular/http': 'js:@angular/http/bundles/http.umd.js',
'@angular/router': 'js:@angular/router/bundles/router.umd.js',
'@angular/forms': 'js:@angular/forms/bundles/forms.umd.js',
'rxjs': 'js:rxjs',
'angular-in-memory-web-api': 'js:angular-in-memory-web-api/bundles/in-memory-web-api.umd.js'

The map configuration tells the code 'when we reference 'x' in code; go look for this library. The main angular libraries are listed. Explanation of the Angular libraries are beyond the scope of this article. The important things to notice are that the js path is specified in the file location for most of the libraries. The second thing to notice is that the app map points to our com directory, where all our custom code is located.

Next, specify the packages. A package is a collection of files that have shared functionality:

packages: {
app: {
main: './dotComIt/sample/main/main.js',
defaultExtension: 'js'
rxjs: {
defaultExtension: 'js'

Two packages are specified. The first is app, which is our main application and custom code. It defines the main entry point, main.js--the name of the file that main.ts will be converted too. It also specifies the default extension of js. The second package specified is a package used by Angular, rxjs.

I wanted to cover the SystemJS configuration as part of this article because it is specific to getting Angular to work, but has nothing to do with TypeScript or creating Index files required for the application.

Setup Node and install Angular Dependencies

What's Next

Get our expanded 38-page version: Building Angular 2 Applications with Gulp.

Comments (Comment Moderation is enabled. Your comment will not appear until approved.)
All Content Copyright 2005, 2006, 2007, 2008, 2009 Jeffry Houser. May not be reused without permission
BlogCFC was created by Raymond Camden. This blog is running version