TypeScript Design Patterns

As Code already has TypeScript support built-in, extra configurations are actually not required. But if the version of TypeScript compiler you use to compile the source code differs from what Code has built-in, it could result in unconformity between editing and compiling.

To stay away from the undesired issues this would bring, we need to configure TypeScript SDK used by Visual Studio Code manually:

Visual Studio Code is a file- and folder-based editor, which means you can open a file or a folder and start work.

But you still need to properly configure the project to take the best advantage of Code. For TypeScript, the project file is tsconfig.json, which contains the description of source files and compiler options. Know little about tsconfig.json? Don't worry, we'll come to that later.

Here are some features of Visual Studio Code you might be interested in:

The default key binding for a build task is Ctrl + Shift + B or cmd + Shift +  B on OS X. By pressing these keys, you will get a prompt notifying you that no task runner has been configured. Click Configure Task Runner and then select a TypeScript build task template (either with or without the watch mode enabled). A tasks.json file under the .vscode folder will be created automatically with content similar to the following:

{ 
  "version": "0.1.0", 
  "command": "tsc", 
  "isShellCommand": true, 
  "args": ["-w", "-p", "."], 
  "showOutput": "silent", 
  "isWatching": true, 
  "problemMatcher": "$tsc-watch" 
} 

Now create a test.ts file with some hello-world code and run the build task again. You can either press the shortcut we mentioned before or press Ctrl/Cmd + P, type task tsc , and enter.

If you were doing things correctly, you should be seeing the output test.js by the side of test.ts.

There are some useful configurations for tasking that can't be covered. You may find more information on the website of Visual Studio Code: https://code.visualstudio.com/.

From my perspective, Visual Studio Code delivers the best TypeScript development experience in the class of code editors. But if you are not a fan of it, TypeScript is also available with official support for Sublime Text.

Package Control is de facto package manager for Sublime Text, with which we'll install the TypeScript plugin.

If you don't have Package Control installed, perform the following steps:

Now we are only one step away from IntelliSense and refactoring with Sublime Text.

With the help of Package Control, it's easy to install a plugin:

Now we have TypeScript ready for Sublime Text, cheers!

Like Visual Studio Code, unmatched TypeScript versions between the plugin and compiler could lead to problems. To fix this, you can add the field "typescript_tsdk" with a path to the TypeScript lib in the Settings - User file.

Atom is a cross-platform editor created by GitHub. It has a notable community with plenty of useful plugins, including atom-typescript. atom-typescript is the result of the hard work of Basarat Ali Syed, and it's used by my team before Visual Studio Code. It has many handy features that Visual Studio Code does not have yet, such as module path suggestion, compile on save, and so on.

Like Visual Studio Code, Atom is also an editor based on web technologies. Actually, the shell used by Visual Studio Code is exactly what's used by Atom: Electron, another popular project by GitHub, for building cross-platform desktop applications.

Atom is proud of being hackable, which means you can customize your own Atom editor pretty much as you want.

Then you may be wondering why we turned to Visual Studio Code. The main reason is that Visual Studio Code is being backed by the same company that develops TypeScript, and another reason might be the performance issue with Atom.

But anyway, Atom could be a great choice for a start.

Visual Studio is one of the best IDEs in the market. And yet it has, of course, official TypeScript support.

Since Visual Studio 2013, a community version is provided for free to individual developers, small companies, and open source projects.

If you are looking for a powerful IDE of TypeScript on Windows, Visual Studio could be a wonderful choice. Though Visual Studio has built-in TypeScript support, do make sure it's up-to-date. And, usually, you might want to install the newest TypeScript tools for Visual Studio.

WebStorm is one of the most popular IDEs for JavaScript developers, and it has had an early adoption to TypeScript as well.

A downside of using WebStorm for TypeScript is that it is always one step slower catching up to the latest version compared to other major editors. Unlike editors that directly use the language service provided by the TypeScript project, WebStorm seems to have its own infrastructure for IntelliSense and refactoring. But, in return, it makes TypeScript support in WebStorm more customizable and consistent with other features it provides.

If you decide to use WebStorm as your TypeScript IDE, please make sure the version of supported TypeScript matches what you expect (usually the latest version).

A TypeScript project does not have to contain a tsconfig.json file. However, most editors rely on this file to recognize a TypeScript project with specified configurations and to provide related features.

A tsconfig.json file accepts three fields: compilerOptions, files, and exclude. For example, a simple tsconfig.json file could be like the following:

{ 
  "compilerOptions": { 
    "target": "es5", 
    "module": "commonjs", 
    "rootDir": "src", 
    "outDir": "out" 
  }, 
  "exclude": [ 
    "out", 
    "node_modules" 
  ] 
} 

Or, if you prefer to manage the source files manually, it could be like this:

{ 
  "compilerOptions": { 
    "target": "es5", 
    "module": "commonjs", 
    "rootDir": "src", 
    "outDir": "out" 
  }, 
  "files": [ 
    "src/foo.ts", 
    "src/bar.ts" 
  ] 
} 

Previously, when we used tsc, we needed to specify the source files explicitly. Now, with tsconfig.json, we can directly run tsc without arguments (or with -w/--watch if you want incremental compilation) in a folder that contains tsconfig.json.

As TypeScript is still evolving, its compiler options keep changing, with new features and updates. An invalid option may break the compilation or editor features for TypeScript. When reading these options, keep in mind that some of them might have been changed.

The following options are useful ones out of the list.

Source maps can help a lot while debugging, no matter for a debugger or for error stack traces from a log.

To have source map support, we need to enable the sourceMap compiler option in tsconfig.json. Extra configurations might be necessary to make your debugger work with source maps.

For error stack traces, we can use the help of the source-map-support package:

$ npm install source-map-support --save

To put it into effect, you can import this package with its register submodule in your entry file:

import 'source-map-support/register'; 

typings is just another Node.js package with a command-line interface like TypeScript compiler. To install typings, simply execute the following:

$ npm install typings -g

To make sure it has been installed correctly, you can now try the typings command with argument --version:

$ typings --version
1.x.x

Create a basic Node.js project with a proper tsconfig.json (module option set as commonjs), and a test.ts file:

import * as express from 'express'; 

Without the necessary declaration files, the compiler would complain with Cannot find module express. And, actually, you can't even use Node.js APIs such as process.exit() or require Node.js modules, because TypeScript itself just does not know what Node.js is.

To begin with, we'll need to install declaration files of Node.js and Express:

$ typings install env~node --global
$ typings install express

If everything goes fine, typings should've downloaded several declaration files and saved them to folder typings, including node.d.ts, express.d.ts, and so on. And I guess you've already noticed the dependency relationship existing on declaration files.

typings has several registries, and the default one is called npm (please understand this npm registry is not the npm package registry). So, if no registry is specified with <source>~ prefix or --source option, it will try to find declaration files from its npm registry. This means that typings install express is equivalent to typings install npm~express or typings install express --source npm.

While declaration files for npm packages are usually available on the npm registry, declaration files for the environment are usually available on the env. registry. As those declarations are usually global, a --global option is required for them to install correctly.

typings actually provides a --save option for saving the typing names and file sources to typings.json. However, in my opinion, this option is not practically useful.

It's great to have the most popular JavaScript libraries and frameworks typed, but these declaration files, especially declarations not frequently used, can be inaccurate, which means there's a fair chance that you will need to edit these files yourself.

It would be nice to contribute declarations, but it would also be more flexible to have typings m  managed by source control as part of the project code.

Mocha has been one of the most popular test frameworks for JavaScript, while Chaiis a good choice as an assertion library. To make life easier, you may write tests for your own implementations of contents through this book using Mocha and Chai.

To install Mocha, simply run the following command, and it will add mocha as a global command-line tool just like tsc and typings:

$ npm install mocha -g

Chai, on the other hand, is used as a module of a project, and should be installed under the project folder as a development dependency:

$ npm install chai --save-dev

Chai supports should style assertion. By invoking chai.should(), it adds the should property to the prototype of Object, which means you can then write assertions such as the following:

'foo'.should.not.equal('bar'); 
'typescript'.should.have.length(10); 

require('chai').should(); 
 
describe('some feature', () => {  
  it('should pass', () => { 
    'foo'.should.not.equal('bar'); 
  }); 
 
  it('should error', () => { 
    (() => { 
      throw new Error(); 
    }).should.throw(); 
  }); 
}); 

src/tsconfig.json 
test/tsconfig.json 

out/app/ 
out/test/ 

src/ 
test/ 
tsconfig.json 

out/src/ 
out/test/ 

src/ 
src/test/ 
tsconfig.json 

out/ 
out/test/ 

--require ./test/mocha.js 
out/test/ 

require('chai').should(); 

$ typings install env~mocha --global

Coverage could be important for measuring the quality of tests. However, it might take much effort to reach a number close to 100%, which could be a burden for developers. To balance efforts on tests and code that bring direct value to the product, there would go another debate.

Install Istanbul via npm just as with the other tools:

$ npm install istanbul -g

The subcommand for Istanbul to generate code coverage information is istanbul cover. It should be followed by a JavaScript file, but we need to make it work with Mocha, which is a command-line tool. Luckily, the entry of the Mocha command is, of course, a JavaScript file.

To make them work together, we'll need to install a local (instead of global) version of Mocha for the project:

$ npm install mocha --save-dev

After installation, we'll get the file _mocha under node_modules/mocha/bin, which is the JavaScript entry we were looking for. So now we can make Istanbul work:

$ istanbul cover node_modules/mocha/bin/_mocha

Then you should've got a folder named coverage, and within it the coverage report.

Reviewing the coverage report is important; it can help you decide whether you need to add tests for specific features and code branches.

A TypeScript application that runs in browsers can be quite different from a Node.js one. But if you know what the project should look like after the build, you should already have clues on how to configure that project.

To avoid introducing too many concepts and technologies not directly related, I will keep things as simple as possible:

This means we'll go with separated output files that need to be put into an HTML file with a script tag manually. Here's the tsconfig.json we'll be playing with; notice that we no longer have the module option, set:

{ 
  "compilerOptions": { 
    "target": "es5", 
    "rootDir": "src", 
    "outDir": "out" 
  }, 
  "exclude": [ 
    "out", 
    "node_modules" 
  ] 
} 

Then let's create package.json and install packages mocha and chai with their declarations:

$ npm init
$ npm install mocha chai --save-dev
$ typings install env~mocha --global
$ typings install chai

And to begin with, let's fill this project with some source code and tests.

Create src/index.ts with the following code:

function getLength(str: string): number { 
  return str.length; 
} 

And create src/test/test.ts with some tests:

describe('get length', () => {  
  it('"abc" should have length 3', () => { 
    getLength('abc').should.equal(3); 
  }); 
 
  it('"" should have length 0', () => { 
    getLength('').should.equal(0); 
  }); 
}); 

Again, in order to make the should style assertion work, we'll need to call chai.should() before tests start. To do so, create file test/mocha.js just like we did in the Node.js project, though the code line slightly differs, as we no longer use modules:

chai.should(); 

Now compile these files with tsc, and we've got our project ready.

Karma itself runs on Node.js, and is available as an npm package just like other Node.js tools we've been using. To install Karma, simply execute the npm install command in the project directory:

$ npm install karma --save-dev

And, in our case, we are going to have Karma working with Mocha, Chai, and the browser Chrome, so we'll need to install related plugins:

$ npm install karma-mocha karma-chai karma-chrome-launcher --save-dev

Before we configure Karma, it is recommended to have karma-cli installed globally so that we can execute the karma command from the console directly:

$ npm install karma-cli -g

The configurations are to tell Karma about the testing frameworks and browsers you are going to use, as well as other related information such as source files and tests to run.

To create a Karma configuration file, execute karma init and answer its questions:

Now you should see a karma.conf.js file under the project directory; open it with your editor and add 'chai' to the list of option frameworks.

Almost there! Execute the command karma start and, if everything goes fine, you should have specified browsers opened with the testing results being logged in the console in seconds.