gulp-tsc

TypeScript compiler for gulp.js

gulp-tsc

TypeScript compiler for gulp 3

First, install gulp-tsc as a development dependency:

npm install --save-dev gulp-tsc

Then, add it to your gulpfile.js:

var typescript = require('gulp-tsc');
 
gulp.task('compile', function(){
  gulp.src(['src/**/*.ts'])
    .pipe(typescript())
    .pipe(gulp.dest('dest/'))
});

All versions starting from 0.9.1, up to 1.5.0.

Type: String Default: null

The path to tsc command for compile.

If not set, this plugin searches for tsc command in the order as described below:

  1. from typescript module installed as your project's dependency (i.e. require("typescript") on current directory)
  2. from PATH of the running shell (using node-which)
  3. from Bundled typescript module

(This search list can be modified by options.tscSearch)

So, if you want to use other version of tsc command, you can add any version of typescript module to your project's dependecy.

However, this plugin could fail to run the future tsc because of incompatible changes of arguments.

Type: Array of String Default: ['cwd', 'shell', 'bundle']

This option changes how this plugin searches for tsc command on your system.

See options.tscPath for details.

Type: Boolean Default: true

If set to true, this plugin emits error event on compilation failure, which causes gulp to abort running task.

See Error handling for details.

Type: String ("commonjs", "amd", "system" or "umd") Default: null (if options.target is "ES6"), or "commonjs" (otherwise)

The "system" and "umd" module options available only when using TypeScript 1.5

--module option for tsc command.

Type: String ("ES3", "ES5", or "ES6") Default: "ES3"

--target option for tsc command.

Type: String Default: null

--out option for tsc command, which will be the name of the output file. example: out: 'app.js'

Type: String Default: null

A path to the directory where output files are finally going to.

This option does not affect the actual output directory for tsc command.

See Path modification for usage of this option.

Type: String Default: null

--mapRoot option for tsc command.

Type: String Default: null

--sourceRoot option for tsc command.

Type: Boolean Default: false

--allowbool option for tsc command. (version 0.9.1.1)

Type: Boolean Default: false

--allowimportmodule option for tsc command. (version 0.9.1.1)

Type: Boolean Default: false

--declaration option for tsc command.

Generated .d.ts file is also piped into the stream.

Notice: If your output files are NOT going to {working directory}/something/ (to a directory beneath the working directory), you have to tell your output path to gulp-tsc by outDir option for correct reference paths. See Path modification for details.

Type: Boolean Default: false

--noImplicitAny option for tsc command.

Do not emit outputs if any type checking errors were reported.

Type: Boolean Default: false

--noImplicitAny option for tsc command.

Warn on expressions and declarations with an implied 'any' type.

Type: Boolean Default: false

--noResolve option for tsc command.

Type: Boolean Default: false

--preserveConstEnums option for tsc command.

Do not erase const enum declarations in generated code.

Type: Boolean Default: false

--removeComments option for tsc command.

Do not emit comments to output.

Type: Boolean Default: false

--sourcemap option for tsc command. Alternatively you could use sourcemap parameter for backward compatibilty, that parameter would be removed in some future releases.

Generated .js.map file is also piped into the stream.

Notice: If your output files are NOT going to {working directory}/something/ (to a directory beneath the working directory), you have to tell your output path to gulp-tsc by outDir option or sourceRoot option. See Path modification for details.

Type: Boolean Default: false

--suppressImplicitAnyIndexErrors option for tsc command. (version 1.5 only)

Suppress noImplicitAny errors for indexing objects lacking index signatures.

Type: String Default: '' (current working directory)

A path relative to current working directory, where a temporary build folder will be put in.

Notice: If you use this option with sourcemaps, consider to specify outDir or sourceRoot. See options.sourceMap for details.

If you are watching some files in current working directory with gulp.watch(), the creation of temporary build folder will trigger a folder change event.

If this is unexpected, you can put temp folders in a non-watched directory with this option.

Example:

gulp.task('tsc', function() {
  return gulp.src(src.ts)
        .pipe(tsc({tmpDir:'.tmp'}))
        .pipe(gulp.dest('.tmp/js'));
});

This will put a temporary folder in '.tmp'.

See Temporary directory and file by gulp-tsc for details.

Type: Boolean Default: false

--noLib option for tsc command.

Set noLib to true will dramatically reduce compile time, because 'tsc' will ignore builtin declarations like 'lib.d.ts'.

So if you are not using 'lib.d.ts' or prefer speed, set this to true. (In my case noLib:true only takes 25% time compared to noLib:false)

Type: Boolean Default: true

If set to false, gulp-tsc skips creating a temporary file in your source directory which is used for keeping source directory structure in output.

See Temporary directory and file by gulp-tsc for details.

Type: Object, Function Default: null

This option is used for modifying paths of compiled files.

You can pass a Hash-like object which is a mapping of output paths in relative form.

Example:

gulp.task('compile', function(){
  gulp.src(['src/**/*.ts'])
    .pipe(typescript({
      pathFilter: { 'aaa/bbb': 'xxx/yyy' }
    }))
    .pipe(gulp.dest('build/'))
});

The example above will compile src/aaa/bbb/ccc.ts into build/xxx/yyy/ccc.js.

You can also pass a function which takes a relative path of compiled files as an argument and returns a modified path.

Example:

gulp.task('compile', function(){
  gulp.src(['src/**/*.ts'])
    .pipe(typescript({
      pathFilter: function (path) { return path.replace(/^aaa\/bbb/, 'xxx/yyy') }
    }))
    .pipe(gulp.dest('build/'))
});

A path filter function will receive following two arguments:

  • String: A relative path to a compiled file.
  • vinyl.File: A vinyl.File object of a compiled file.

A path filter function can return Boolean, String, vinyl.File or undefined.

Returned valueEffect
true, undefinedUse the file as-is.
falseSkip the file. (not piped into output gulp stream)
StringReplace the file's path with the returned string.
vinyl.FileUse the returned vinyl.File instead.

Type: Boolean Default: false

By default, gulp-tsc ignores warnings from tsc command and emits compiled js files to the gulp stream anyway.

If set this option to true, gulp-tsc never emits compiled files when tsc command returned warnings or errors.

Type: Boolean Default: false

--emitDecoratorMetadata option for tsc command.

Emit decorator metadata.

Type: Boolean Default: false

--experimentalDecorators option for tsc command.

Enable experimental Decorator support.

If gulp-tsc fails to compile files, it emits error event with gutil.PluginError as the manner of gulp plugins.

This causes gulp to stop running on TypeScript compile errors, which is sometimes a problem like using with gulp.watch().

If you want to suppress the error, just pass { emitError: false } to gulp-tsc like below.

var typescript = require('gulp-tsc');
 
gulp.task('default', function () {
    gulp.watch('src/**/*.ts', ['compile'])
});
 
gulp.task('compile', function () {
    return gulp.src('src/**/*.ts')
        .pipe(typescript({ emitError: false }))
        .pipe(gulp.dest('dest/'));
});

gulp-tsc does some modification to output files to correct relative paths in sourcemap files (.js.map) and declaration files (.d.ts).

However, gulp-tsc doesn't know where your output files are going to be stored finally since it is specified by gulp.dest and gulp-tsc cannot access to it. So gulp-tsc assumes that your output files go into {working directory}/something/ by default.

If your output files are not going there, you have to tell your output path to gulp-tsc by outDir option.

If you have a gulp task like this:

gulp.task('compile', function(){
  gulp.src(['src/**/*.ts'])
    .pipe(typescript({ sourceMap: true, declaration: true }))
    .pipe(gulp.dest('foo/bar/'))
});

Output files are going under {working directory}/foo/bar/, but sourcemap files and declaration files will contain a relative path to source files from {working directory}/foo/ which is not correct.

To fix the relative path, just specify outDir same as your gulp.dest path.

gulp.task('compile', function(){
  gulp.src(['src/**/*.ts'])
    .pipe(typescript({ sourceMap: true, declaration: true, outDir: 'foo/bar/' }))
    .pipe(gulp.dest('foo/bar/'))
});

Since gulp-tsc uses tsc command internally for compiling TypeScript files, compiled JavaScript files require to be written on the file system temporarily.

For those compiled files, gulp-tsc creates a temporary directory named gulp-tsc-tmp-* in the current working directory. You can change the location of the temporary directory by options.tmpDir.

In addition, gulp-tsc also creates a temporary file named .gulp-tsc-tmp-*.ts in your source root directory while compiling. The source root is determined by your gulp.src(). (e.g. For gulp.src("src/**/*.ts"), the source root is src/)

This is required for keeping your source directory structure in output since tsc command omits the common part of your output paths.

If you do not need to keep the structure, you can skip creating the temporary file by setting options.keepTree to false.