Using VSCode with gulp-typescript


Since TypeScript 1.5 is just released, it's a good moment to take a look at how we can integrate the new Visual Studio Code with gulp-typescript. Both support TypeScript 1.5 out of the box, and have support for a universal configuration file called tsconfig.json.

About TypeScript 1.5

TypeScript 1.5 introduces a lot of new features, like ES6 compatibility (ES6 modules, destructuring, for of loop). Also decorators and the SystemJS module system were added. Besides these features, also a new configuration file was introduced: tsconfig.json

tsconfig.json

The tsconfig.json file is a standard way to write down your project settings. With this configuration file you don't have to configure your project multiple times for different applications, like editors and build systems.

Let's take a look at a simple tsconfig file:

{
}

That looks simple, doesn't it? It will load all TypeScript files from the containing directory and compile these files with the standard compiler options. You can specify different compiler options like this:

{
    "compilerOptions": {
        "target": "ES5",
        "module": "commonjs"
    }
}

You can specify the files that should be compiled in three ways:

  1. Include all files.
  2. Include all files from the files property.

In TypeScript 1.6 you can also use the excludes property. It will include all files, except the directories or files in the excludes property. This is not supported in TypeScript 1.5, but you can already use it in gulp-typescript.

We've already used the first in the first example. When using the second option, you have a property in your configuration file called files, which will look like this:

{
    "files": ["file-1.ts", "file-2.ts"]
}

Configuring gulp

A basic gulpfile with this configuration file will look like this:

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

var tsProject = typescript.createProject('tsconfig.json');

gulp.task('scripts', function() {  
    return tsProject.src()
        .pipe(typescript(tsProject))
        .pipe(gulp.dest('release'));
});
gulp.task('default', ['scripts']);  

If you also want to generate definition files, you should add "declaration": true to your tsconfig file, and change your gulpfile to:

var merge = require('merge2');  
// ...
gulp.task('scripts', function() {  
    var tsResult = tsProject.src()
        .pipe(typescript(tsProject));
    return merge([
        tsResult.js.pipe(gulp.dest('release')),
        tsResult.dts.pipe(gulp.dest('release'))
    ]);
});

By running gulp our TypeScript sources will now be compiled using the tsconfig.json file.

Configuring Visual Studio Code

VSCode will use the tsconfig file by default, there's nothing we need to do to use it. We can also use gulp from VSCode without configuration, but we can make that experience better by configuring it. We'll first take a look at how it looks without configuration.

Press Ctrl Shift P or Cmd Shift P (Mac) to open the Command Palette in VSCode. Here you can run a lot of commands, like "View: Change to Dark Theme" and "Files: New File". When you begin typing "Task" you'll see that the list is filtered. You need to look for "Tasks: Run Task". Select the item using the arrow keys and press enter. Now you'll see all tasks that you've defined in the gulpfile, in our example default and scripts. You can run them the same way as choosing the command in the previous step.

We'll now configure VSCode so we can press Ctrl B or Cmd B to compile our project and see compile errors in the code editor. Open the Command Palette and execute "Tasks: Configure Task Runner". VSCode creates a new file with a basic configuration. You can see the property command contains gulp, which means VSCode will run gulp to compile the project. tasks is an empty array, we'll need to change that. First we add a build task to this section:

{
    "tasks": [
        {
            "taskName": "scripts",
            "isBuildCommand": true,
            "args": [],
            "problemMatcher": ["$tsc"]
        }
    ]
}

The taskName property contains the name of the task, scripts in this example. isBuildCommand means that this command should be called when your project should be build (for example pressing Ctrl B or Cmd B). We don't want to add any arguments (thus args is an empty array). problemMatcher describes how VSCode will parse the output of gulp. Because gulp-typescript shows errors the same way as tsc does, we can use the built-in problem matcher that can parse the output of tsc. That will mean that when you build your project, you'll see the errors from gulp-typescript in VSCode.

Note: you'll already see errors when you just edit files in VSCode, but when you build your project you'll see only the errors from the build process. After editing a file you'll get the errors from VSCode again. In most cases these errors will be the same as both VSCode and gulp-typescript use the settings from tsconfig.json.

You can also specify a test command by setting isTestCommand instead of isBuildCommand.

Summary

We've configured a project using a tsconfig.json file. That file can be used by both VSCode as gulp-typescript. Afterwards we've integrated VSCode with our gulp tasks so we can easily build our project using gulp.

You can read more about Visual Studio Code on their website.