TypeScript 3.0 Quick Start Guide

Grunt is a JavaScript task runner. It can be installed using NPM, which is used to list all its plugins:

npm install -g grunt-cli

In the case of a new project, make sure that package.json exists in the root of your TypeScript project. You can generate a simple one by using npm init.

Once it is done, you can install Grunt into your project:

npm install grunt --save-dev

Once Grunt is available on your machine and specified in your project, you need to get a TypeScript plugin. Grunt has two plugins named grunt -TypeScript and grunt-TS. The former has not been maintained for a few years and lacks the latest TypeScript compiler configuration. I strongly suggest using the latter:

npm install grunt-ts --save-dev

The last package should be installed as a dev dependency for Grunt to compile TypeScript and to install it locally. Grunt will search for the package locally. Omitting TypeScript as a local dependency will result in the following error when executing Grunt.

Installing TypeScript locally as a dev dependency is easy:

npm install typescript --save-dev

Prior to grunt-ts version 6, TypeScript and Grunt were installed during the installation of grunt-ts. This is not the case anymore, so they must be added manually.

The next step is to configure Grunt to use a TypeScript plugin. If you are not using Grunt, you need to create a Gruntfile.js at the root of your project. Otherwise, you can edit your existing one. The plugin allows you to specify many TypeScript options in the Gruntfile.js, but a good practice is to limit TypeScript options directly in the file and to leverage the TypeScript configuration file. By configuring TypeScript outside Grunt, this gives you the possibility of compiling your code without Grunt, or migrating to another build tool without having to duplicate or change TypeScript preferences.

A minimalist Grunt configuration with the sole purpose of compiling TypeScript into JavaScript may look like the following:

module.exports = function(grunt) {
 grunt.initConfig({
   ts: {
    default : {
     tsconfig: './tsconfig.json'
    }
   }
 });
 grunt.loadNpmTasks("grunt-ts");
 grunt.registerTask("default", ["ts"]);
};

The Grunt configuration creates a default task that executes a custom ts task that links to the tsconfig.json file, which is the default TypeScript configuration file.

The tsconfig.json file can look like the following one, which takes every TypeScript file with the extension .ts and will compile them outputting the result in the build folder:

{
 "compilerOptions": {
   "rootDir": "src",
   "outDir": "build",
 }
}

When using grunt and grunt-ts, you must ensure that that the JSON is valid with no-trailing commas in the tsconfig.json file. Otherwise, you may get the following error:

tsconfig error: "Error parsing \"./tsconfig.json\".  It may not be valid JSON in UTF-8."

To test the configuration, create a simple index.ts file in an src folder at the root of the project. You can type console.log('test'). After, run grunt in a command line at the root of your project as well. This will create a build folder with an index.js file containing the same line of code. It will also create the js.map file that will let you debug in your browser directly in TypeScript's code.

If, for some reason, you do not want to rely on tsconfig.json, it's possible to specify the source and destination directly into Gruntfile.js file:

module.exports = function (grunt) {
 grunt.initConfig({
  ts: {
   default: {
    src: ["src/**/*.ts"],
     outDir: "build",
     options: {
     rootDir: "src"
    }
   }
  }
 });
 grunt.loadNpmTasks("grunt-ts");
 grunt.registerTask("default", ["ts"]);
};

In the end, grunt-ts wraps the TypeScript command line. It provides options such as the fast compilation, which compile, only what has changed since the last compilation. It is also an interesting option if you are already using Grunt in your project and want to start using TypeScript without modifying your build process.

Gulp is an automation toolkit that has a TypeScript plugin as well. There are two plugins available in NPM, which are gulp-tsb and gulp-typescript. The latter is the most popular and more maintained. You can fetch gulp and the plugin by using the following command:

npm install -g gulp
npm install --save-dev gulp-typescript

If you do not have a Gulp configuration file, you will need to create one at the root of your gulpfile.js project.

The configuration without an explicit option will rely on the default configuration. It means that configuring Gulp can be as simple as piping the source into the TypeScript plugin and then piping the result into the destination folder where the build files, that is the JavaScript file, will be placed for consumption. Once the following code is placed in gulpfile.js, you can execute it by using gulp in the command line. This will execute the default task once, automatically:

var gulp = require("gulp");
var ts = require("gulp-typescript");

gulp.task("default", function () {
 var tsResult = gulp.src("src/**/*.ts")
 .pipe(ts());
 return tsResult.js.pipe(gulp.dest("build"));
});

It is possible to have a task in Gulp to build incrementally a TypeScript file that changes instead of building all of them. This can be useful on a big project to reduce the time between the edition and the access to the result. This is similar to the fast compilation of Grunt. To have an ongoing compilation, you must create a new Gulp task. In this example, we will change Gulp to rely on tsconfig.json file, which will allow us to separate the TypeScript compiler option from the Gulp configuration:

var gulp = require('gulp');
var ts = require('gulp-typescript');
var tsProject = ts.createProject('tsconfig.json');

gulp.task('scripts', function() {
 return gulp.src('src/**/*.ts')
 .pipe(tsProject())
 .pipe(gulp.dest('build'));
});
gulp.task('watch', ['scripts'], function() {
 gulp.watch('src/**/*.ts', ['scripts']);
});

To run the watch task, you need to execute Gulp followed by the name of the task: gulp watch. Unlike Grunt, Gulp will not produce the map file. It requires an additional Gulp plugin. Because the sourceMap is crucial to have an efficient debugging environment, it is keen to download the gulp-sourcemap package and change the previous configuration to the following. But first, let's download the gulp-sourcemaps package:

npm install --save-dev gulp-sourcemaps

And then create a new task:

var sourcemaps = require('gulp-sourcemaps');
gulp.task('scriptswithsourcemap', function () {
 return gulp.src('src/**/*.ts')
 .pipe(sourcemaps.init())
 .pipe(tsProject())
 .pipe(sourcemaps.write('.', { includeContent: false, sourceRoot: '.'}))
 .pipe(gulp.dest('build'));
});

The configuration will create the source map in a file with the same name as the JavaScript file generated but with a different extension. The extension will be .jsmap. If you want to have the mapping directly in the JavaScript file, you can remove the two arguments passed in the write function. I suggest having a single script task that produces the source map in a file to separate the mapping from the code generated, and to always have the source map created. It's a small tax on the compilation and a huge gain in debugging.

Webpack is one of the most commonly used ways to automate workflow when working with JavaScript and web development. Its main purpose is to bundle, but it can do many sequential steps, such as compiling TypeScript. Similarly to Grunt and Gulp, webpack has two loaders (similar to a plugin) for TypeScript. One is called ts-loader and the second awesome-typescript-loader. While with Grunt and Gulp, it was a clear which one users prefer, this is not the case with Webpack. Both loaders are similar in terms of popularity. It is also not difficult to change between the two if needed. Originally, awesome-typescript-loader was faster than ts-loader but with the evolution of TypeScript, the difference is often minimal. Also, there is sometimes an issue with an advanced feature in one or the other, and so it is practical to be able to switch depending on how your project. I'll present ts-loader, which is a little more popular, still actively maintained, and has a little more usage than the awesome-typescript-loader.

In the case, you are not yet using webpack, we need to install it:

npm install --save-dev webpack
npm install --save-dev webpack-cli

Once webpack is installed, you can install the TypeScript loader:

npm install --save-dev ts-loader

Once all the tools are installed, you can configure webpack to bundle the JavaScript produced by the webpack loader. However, webpack.config.js is needed at the root of your project. Like any Webpack configuration, the entry property must be defined. Make sure you are referring to the TypeScript file. The output is also specified in the output property. Webpack requires mentioning the extension to be analyzed. In TypeScript case it is .ts, but if you are working with React you might want to also add .tsx under resolve:extensions. Finally, the ts-loader is specified under module:rules. Once again, the extension of TypeScript is required and the name of the loader:

module.exports = {
 mode: "development",
 devtool: "source-map",
 entry: "./src/index.ts",
 output: {
  path: __dirname + "/build",
  filename: "bundle.js"
 },
 resolve: {
  extensions: [".ts"]
 },
 module: {
  rules: [
  { test: /\.ts$/, loader: "ts-loader" }
  ]
 }
};

You can run the webpack command line (cli) by accessing the binary file, which will read the webpack.config.jsfile:

node node-modules/webpack-cli/bin/cli.js

If you want to avoid referencing node_modules, you can install webpack-cli in your global space, using npm install -g webpack-cli.

Here are a few little details about webpack. There is an additional module that divides the production of the bundle and compilation, compared to just validating TypeScript. These modules might be interesting when your project starts to grow and you want to have a faster compilation pace. Feel free to check fork-ts-checker-webpack-plugin and thread-loader. Before diving into other libraries, ts-loader has a way to incrementally build and to use the TypeScript watch API to avoid building everything all the time. This will increase your performance on every compilation. To allow the watch, change the rule of ts-loader to the following:

rules: [
 {
 test: /\.ts$/,
 use: [
  {
   loader: 'ts-loader',
   options: {
    transpileOnly: true,
    experimentalWatchApi: true,
   },
  },
 ],
 }
]

A final detail about webpack is its dependency on tsconfig.json for all TypeScript related configurations. Grunt and Gulp allow you to override configurations inside their tool configuration, which is not the case with webpack. When bundling, webpack produces bundle.js.map, but only if the dev tool specifies a configuration. However, you must set the tsconfig.json "sourceMap" to true to have a mapping that works with TypeScript.

Almost all web projects use NPM. NPM is the mechanism we used to fetch TypeScript. This one creates package.json at the root of your project and can be used to launch TypeScript directly. This is possible because TypeScript has a CLI called tsc (TypeScript compiler).

NPM configuration has a section named scripts where you can add any command you want. You can create a build one that invokes tsc. Without any parameters, tsc uses tsconfig.json at the root of your project. In the following snippet, the "build" script is defined. To run the command, the use of the run command of NPM is needed, that is, npm run build:

"scripts": {
"build": "node_modules/typescript/bin/tsc"
},

With a TypeScript configuration file that specifies the source map, the rootDir, and outDir the result will be the same as Gulp and Grunt (different from webpack since it won't be bundled):

{
 "compilerOptions": {
 "rootDir": "src",
 "outDir": "build",
 "sourceMap": true
 }
}

This is often not the preferred configuration because of how simplistic and limited it is. However, it's possible to have several commands executed one after the other, using the double ampersand (&&) to create a chain of commands. This option is fast, doesn't require any dependency on NPM libraries, and is often enough to get started at a basic level.

The advantage of the NPM and CLI approach is that TypeScript can be executed easily. Hence, if you have a custom build system you can easily plug TypeScript by invoking the CLI.

Considering all the tooling available to compile TypeScript to JavaScript, one pillar concept remains the same: you must know which configuration to use. Insofar that you are not responsible for configuring the compiler, you could skip this section – configuring TypeScript is something you do rarely and when it works as desired it can stay unaltered for a very long time. However, to have an understanding of the capability of TypeScript, you need to know some of the core options. In this section, we will see the main settings that you can enable and customize for your project.

rootDir:src
outDir:build

{
 "compilerOptions": {
 "baseUrl": ".", // This must be specified if "paths" is.
 "paths": {
 "jquery": ["node_modules/jquery/dist/jquery"] // This mapping is relative to "baseUrl"
 }
 }
}

Import * from "jquery"

const text = "Text for test1";
console.log(text);
//# sourceMappingURL=index.js.map

{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"]......

"include": [
 "src/**/*"
 ],
 "exclude": [
 "node_modules",
 "dont/compile/*.mock.ts"
 ]

{
 "compilerOptions": {
 "rootDir": "src",
 "outDir": "build",
 "target": "es6",
 "sourceMap": true,
 "outFile": "build/mySingleFile.js"
 }
}

{
 "compilerOptions": {
 "typeRoots" : ["./typings", “./node_modules”]
 }
}

{
 "compilerOptions": {
 "declaration" : true
 }
}

{
 "compilerOptions": {
 "declaration" : true,
 "declarationDir": "definitionfiles/here"
 }
}

error TS5053: Option 'declarationDir' cannot be specified with option 'outFile'.

tsc
tsc -p tsconfig.json
tsc -p tsconfig.test.json

{
 "extends": "./tsconfig.json",
 "compilerOptions": {
 "outDir": "buildtest",
 "sourceMap": false,
 "declaration": false
 }
}

tsc -p tsconfig.test.json

"None", "CommonJS", "AMD", "System", "UMD", "ES6", "ES2015" or "ESNext".

import x from "./sameFolder";
import y from "../parent/folder";
import z from "../../../deeper/";

import a from "module123";

"ES3", "ES5", "ES6"/"ES2015", "ES2016", "ES2017" or "ESNext"

interface A {
 name: string;
}

interface B extends A {
 firstName: string;
}

declare let f1: (x: A) => void;
declare let f2: (x: B) => void;

f1 = f2; // DOESNT COMPILE
f2 = f1;

Error message :  Type 'A' is not assignable to type 'B'. Property 'firstName' is missing in type 'A'.

class A {
 public field1: number;
}

class A {
 public field1: number = 1;
}

class A {
 public field1: number;
 constructor(p:number){
   This.field1 = p;
 }
}

In this chapter, we put in place different configurations allowing you to start coding with TypeScript in a straightforward way. After setting up your working environment to your liking, we briefly mentioned the most important compiler options to get you started on the right path. TypeScript is a flexible compiler, and you should be rapidly up-to-speed developing because of how the settings can be selected.

In the next chapter, we will look at programming with TypeScript by introducing how ECMAScript primitive type can be strongly typed.