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
sortOutput are not supported any more. Users of
noExternalResolve can switch to
noResolve, a standard option that has almost the same behavior.
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
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
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
The stream returned by
.pipe(ts(..)).js, and the stream with only definition files as
7. Implicitly set the
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
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
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
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
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