Check out our Angular Book Series.

Building HTML5 Applications with TypeScript and Gulp - Part 1

TypeScript is a newish language for application development on the web. It is a superset of JavaScript, and supports things like static typing and class based object oriented programming. Static typing, particularly, can offer improved tooling over what is currently available for simple JavaScript programming.

TypeScript can be used for any web application, or even on the server side with NodeJS. It is the recommended language for Angular 2 applications. TypeScript is compiled to regular JavaScript for deployment and testing. This white paper will explain the infrastructure we use to make this happen.

The TypeScript Application

Before we start to look at the build process, let's look at a super simple TypeScript application. We'll need some code to compile. This code borrows heavily from the official TypeScript tutorials. It will add a 'hello world' message to the body of an HTML page.

Create a directory for this setup. The final directory setup will look something like this:

This is a description of each directory:

  • TypeScriptAndGulp_Article: The root directory will contain the script files for running Gulp and config file for NodeJS.
    • build: This directory will contain the final, processed, build.
    • node_modules: This directory will contain the NodeJS package, such as Gulp and TypeScript, to needed to perform the actions.
    • src: This directory will contain the application's source files.

We will create most of these files and directories as we move through the process.

For now, I named the project directory TypeScriptAndGulp_Article. Start by creating the src directory. I always separate the source code, compiled code, build scripts, and NodeJS modules. Inside the src directory, create an index.html file:

<title>TypeScript Sample for DotComIt Article</title>
<script src="sample.min.js"></script>

This is a simple index.html file. There is one item I want to draw attention to. The script tag which imports a JavaScript file named sample.min.js. This is the file we will generate from the TypeScript code.

Next, create a file named greeter.ts. The ts extension is the standard extension for TypeScript files, similar to how 'js' is the standard extension for JavaScript files. For this sample I'll put all the files inside the root of the src directory, however in a more complex application, I may categorize the files under a descriptive directory structure.

This is the greeter.ts:

export function sayHello(name: string) {
return `Hello from ${name}`;

This file exports a function named sayHello(). The export is not something you'll commonly see in browser JavaScript, but is used when creating NodeJS Modules. It, basically, says that "This is an API I Want people to use to access code in this file." The sayHello() method has a single parameter, name. The type of the name is specified, something that doesn't happen in JavaScript but adding it allows for type checking at the compiler level. The body of the method returns a string, referencing the name variable inside the string. The syntax is very similar to JavaScript, so learning TypeScript should not be a big hurdle for you to climb.

Now create a file named main.ts. This is the entry point to our application. Back in my school days we'd call the routine that ran the app a main routine, so this is a similar approach. The first thing the main.ts does is import the greeter file:

import { sayHello } from "./greeter";

This makes all the code from the greeter.ts file available to use in the main.ts file. Now, create a showHello() method:

function showHello(name: string) {
document.body.innerHTML = sayHello(name);

This method looks a lot like a JavaScript method definition, the only difference is that the name variable is given a type of string. The code accesses the innerHTML of the web pages body tags and outputs the results of the sayHello method, which will just be a string that says hello from the given name.

Finally, call the showHello() method:


That completes the super simple TypeScript application. I could write a lot about TypeScript, however I wanted this article to focus on the build process of turning TypeScript into a JavaScript web application. As such, I'll leave the JavaScript there. When you finally compile the application, it should look something like this in the browser:

A Basic Compile Script

To compile TypeScript into JavaScript we are going to use NodeJS and a bunch of plugins.

Install and Setup NodeJS

The first step is to install NodeJS if you haven't already. The formal instructions will give you more detailed instructions if you haven't already done so. Then create a generic package.json configuration file. You can run this script:

npm init

And follow the instructions to create a simple package.json. You'll see something like this:

My final package.json is listed below:

"name": "typescriptandgulp",
"version": "1.0.0",
"description": "A sample project to compile TypeScript with Gulp",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
"author": "Jeffry Houser",
"license": "ISC",
"repository": {}

Install Node Modules

Now we want to install some NodeJS plugins. First, we want to make sure Gulp is available. Gulp is the script runner we'll use to execute tasks to run our application. Run this command:

npm install --save-dev gulp

You'll see a screen similar to this:

You can ignore the warnings. Your project directory will now have a node_modules directory.

Next, install the TypeScript plugin:

npm install --save-dev typescript

The NodeJS TypeScript plugin will not be used directly in the gulp script, but is a required dependency:

Next, install browserify. Browserify will combine all the JavaScript files into a single file. We also want tsify installed, a plugin that will allow browserify to compile TypeScript into JavaScript. First, install browserify:

npm install --save-dev browserify

You'll see results like this:

Then install tsify:

npm install --save-dev tsify

Your screen should look like this:

A Gulp stream object is named vinyl and is a virtual file format. To manipulate the output from Browserify with a Gulp script , we'll need to convert Browserify's object to the vinyl format. Thankfully there is a plugin for that, vinyl-source-stream module:

npm install --save-dev vinyl-source-stream

See the console results:

It is a lot of setup, but we should have all the required plugins we need to get started now.

Create the Gulp Task

In the root directory of the project, create a file named gulpfile.js. It is the default Gulp configuration file.

First, load the gulp module:

var gulp = require("gulp");

From there, you can create a gulp task for compiling TypeScript:

gulp.task("buildTS", function () {

This is a blank task that does nothing. It calls the task() method on the gulp object. The task() method has two argument: the name of the task and a function to perform the task. You can execute this task by typing this into your console:

gulp buildTS

You should see something like this:

The task does nothing yet, though. Let's make it do something. Import the rest of the libraries:

var browserify = require("browserify");
var source = require('vinyl-source-stream');
var tsify = require("tsify");

Make sure these libraries are imported outside of the Gulp task. After the library import, still outside the Gulp task, let's define a few variables. The first is something I call appEntry:

var appEntries = ['src/main.ts']

It is an array that contains the main TypeScript file. Browserify will analyze main.ts to find all other files it uses and will do recursively. This is a bit different than the process I used in an AngularJS JavaScript application; where I'd process all files ending with the js extension.

Next, create a variable for the processed file name, and one for the final path:

var javaScriptDestinationFile = 'sample.min.js';
var destinationPath = 'build';

The destination file is the final output after the TypeScript files are merged and compiled into a single one. We referenced this file name in the index.html document. The second variable specifies the final destination of the file. I could define these as part of the Gulp task, but prefer to define them as global variables so they are easily accessible across multiple tasks, and I can tweak how everything works just by changing the config values. Now go back inside the buildTS task and call the browserify() method:

return browserify({
compilerOptions: {
module: "commonjs",
target: "es5",
entries: appEntries

This calls the browserify() method and passes in an argument. The argument object specifies the configuration for this browserify process. Let's go through them:

  • compilerOptions: This is another object that specifies how the TypeScript compiler will work.
    • module: Specifies how modules are loaded in UI code, in this case we are using the commonjs convention.
    • target: Specifies the ECMAScript version you want to output to; in this case I am specifying EcmaScript 5, however other versions are supported.
  • entries: Specifies an array of entry points to your application.

This is a very simple config, and it can be a lot more complicated if you need it to be. Next, tell Browserify to compile the TypeScript code:


Each successive command is daisy chained on the other with the dot syntax. This uses the Browserify plugin() method to call the tsify package to compile the TypeScript code into JavaScript.

Next, call bundle() to merge all code into a single unit:


This one is simple. Then, specify the name of the new file:


This uses the vinyl-source-stream module to turn the javaScriptDestinationFile name into something that can be accessed via Gulp. The pipe() method means that we are getting ready to output information, instead of processing input. Finally, specify the destination of the new file:


This uses the pipe() operator too; and the value is Gulp's dest() function. This, basically, tells the script to put all our files in the build directory.

You can run the gulp script:

Look at the directory structure after our first run:

All the node modules we installed are in the node_modules directory. The source we looked at earlier is in the src directory. The JavaScript file built from the TypeScript files is in the build directory. The gulpfile.js and package.json are in the root application directory. I like this structure because it cleanly separates concerns.

Things are not yet runnable in a browser, because the Index.html was not moved from the src directory to the build directory. For the sake of this article, you can move it manually. Runt he code in the browser, and you should see this:

This isn't an interesting app, but it does prove that Gulp is successfully compiling TypeScript and copying the HTML files from the source directory into the build directory.

What's Next?

The next article in this blog series will focus on how to write a Gulp Script that will watch for any changes to your TypeScript files, and re-compile them as you change code.

If you want a more in depth tutorial, sign up to get our full 30 page white paper on building TypeScript applications with Gulp.

Yes, I want to get your white paper on building TypeScript applications

Related Blog Entries

Comments (Comment Moderation is enabled. Your comment will not appear until approved.)
Duke Vukadinovic's Gravatar As amazing as TypeScript is, there’s one big disadvantage: It needs to be transpiled. In other words, the code you write isn’t the code that runs. You write some code, it gets converted into JavaScript, and that generated JavaScript runs in the browser. This introduces some friction, especially while debugging.
# Posted By Duke Vukadinovic | 5/30/17 8:48 AM
Jeffry Houser's Gravatar Hi Duke,

Thanks for reading! Have you ever used a tool such as UglifyJS to minimize your JavaScript code? Perhaps you noticed it rewrites certain things, and the code you wrote is not the same as what is running in the browser.

Aside from that, minimizers and other 'build tools' have become a common 'best practice' approach.

Source maps can be used if you need to view the original source for debugging purposes.

In other news, compiled languages have been in use for much longer and do similar conversion, and often optimization, of the code you write into something different that runs on the machine.

I don't think your fears are a valid concern.
# Posted By Jeffry Houser | 6/18/17 10:00 PM
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