Migration help for gulp-typescript 3

TypeScript 2.0 has been released! Following this release, gulp-typescript 3 is now also available. This page gives an explanation of the (breaking) changes and the changes that are required to use this new version.

1. TypeScript is not bundled anymore

Previously, gulp-typescript would automatically use the latest stable release of TypeScript, but it was possible to override this version. As of gulp-typescript 3, this is even simpler. The installation of TypeScript in node_modules will automatically be picked up by gulp-typescript. A nightly version can be installed using npm install typescript@next --save-dev.

However, this does mean that all users are required to install typescript manually. The latest stable version of TypeScript can be installed using npm install typescript --save-dev.

2. Non-standard options are removed

In version 3, non-standard options were removed. This means that noExternalResolve and sortOutput are not supported any more. Users of noExternalResolve can switch to noResolve, a standard option that has almost the same behavior.

Users of sortOutput should first try whether their project compiles without sortOutput. In most cases, it will compile without problems. Otherwise, users of gulp-concat should use outFile instead and let TypeScript concatenate the JavaScript output.

3. Filters are removed

Version 2 of gulp-typescript had filters, which could filter a list of files to the list of files that were referenced from such file. Since this functionality was almost not used, this has been removed. Users of filters can soon switch to tsProject.resolve(), what I will implemented in the near future.

4. Revised API of main function

The main function has changed a bit. The signature looked like ts(options?, filter?, reporter?). Since filters were removed, the reporter argument has been moved to the second argument.

The first argument options accepted either an object with compiler options, or a 'project', created by ts.createProject. The API for the latter case has been modified. Instead of writing .pipe(ts(tsProject)), users should now use .pipe(tsProject()). When a reporter is used, this becomes .pipe(tsProject(reporter)).

5. Drop support for TypeScript 1.x

Version 3 will only support TypeScript 2.x. Users of TypeScript 1.x can still use version 2.x of gulp-typescript.

6. Default stream contains .js and .d.ts files

The stream returned by .pipe(ts(..)) will contain both JavaScript and definition files (provided that declaration is enabled). A stream with only JavaScript can still be accessed as .pipe(ts(..)).js, and the stream with only definition files as .pipe(ts(..)).dts.

7. Implicitly set the rootDir option

In the past, various issues with the handling of file paths have been reported. gulp-typescript works with relative paths, and has some complex logic to handle this. Always setting rootDir will make everything more predictable, meaning that the code of gulp-typescript can be simplified and there will be less bugs.

A consequence of this is, that you can get TypeScript errors when you have external source files (not .d.ts). The rootDir is implicitly set to the common directory of the base property of your files. Gulp sets this property automatically. When you use gulp.src(), this is usually the start of the magic inside the glob. When you use tsProject.src(), this is the common directory of all source files. In this example, I'll use gulp.src(['src/a/**/*.ts', 'src/b/**/*.ts']) to demonstrate the new behavior. Some files will have src/a as base path, some src/b. The common base path will then be src. Thus, rootDir will be set to src. These files can import or reference other files, which are then passed to the compiler. If one file would reference x.ts, TypeScript will show an error that x.ts is outside of the root directory. However, if one file would reference typings/y.d.ts, no error is reported since definition files may be located outside of the root directory.

The rationale behind this breaking change is that it makes the logic in gulp-typescript easier and only breaks cases that are already questionable. However, if you run into issues related to the implicitly set rootDir, you can set it yourself to the correct path. If it is desired that c.ts is also passed to the compiler, you should set rootDir to ./.

8. Changed paths in source maps

Handling paths in source maps correctly is difficult, since they are relative, but all are relative to a different path. The revised implementation in version 3 should be matching the specification of gulp-sourcemaps. The result of the fix is that some generated paths are now different. A setup that was previously working (with the wrong implementation of gulp-typescript), might not be working any more. There is no single solution to this. Some problems can be fixed by setting the base property explicitly in gulp.src, or by setting the rootDir option explicitly when using tsProject.src().

Issues & questions

If you found a bug in the new implementation, please report it in the issue tracker. If you have question related to the new release, you can ask them in the issue tracker too. If you have a question, not related to this release, you can ask it on Stack Overflow. You can also find me on twitter @ivogabe