gulp-tsc

TypeScript compiler for gulp 3

Usage

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/'))
});

Supported TSC versions

All versions starting from 0.9.1, up to 2.1.0.

API

typescript(options)

options.tscPath

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.

options.tscSearch

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.

options.emitError

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.

options.module

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

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

--module option for tsc command.

options.target

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

--target option for tsc command.

options.out

Type: String Default: null

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

options.outDir

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.

options.mapRoot

Type: String Default: null

--mapRoot option for tsc command.

options.sourceRoot

Type: String Default: null

--sourceRoot option for tsc command.

options.allowbool

Type: Boolean Default: false

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

options.allowimportmodule

Type: Boolean Default: false

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

options.declaration

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.

options.noEmitOnError

Type: Boolean Default: false

--noImplicitAny option for tsc command.

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

options.noImplicitAny

Type: Boolean Default: false

--noImplicitAny option for tsc command.

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

options.noResolve

Type: Boolean Default: false

--noResolve option for tsc command.

options.preserveConstEnums

Type: Boolean Default: false

--preserveConstEnums option for tsc command.

Do not erase const enum declarations in generated code.

options.removeComments

Type: Boolean Default: false

--removeComments option for tsc command.

Do not emit comments to output.

options.project

Type: String Default: null

--project option for tsc command.

Compile the project in the given directory.

options.moduleResolution

Type: String Default: null

--moduleResolution option for tsc command.

Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6).

options.allowJs

Type: Boolean Default: false

--allowJs option for tsc command. (at least version 1.8)

options.allowUnreachableCode

Type: Boolean Default: false

--allowUnusedLabels option for tsc command. (at least version 1.8)

Allows unreachable code.

options.allowUnusedLabels

Type: Boolean Default: false

--allowUnusedLabels option for tsc command. (at least version 1.8)

Allows specify unused labels in the source code.

options.baseUrl

Type: String

--baseUrl option for tsc command. (at least version 1.8)

Base directory to resolve non-absolute module names.

options.noImplicitReturns

Type: Boolean Default: false

--noImplicitReturns option for tsc command. (at least version 1.8)

Disallow implicit returns from the functions.

options.noFallthroughCasesInSwitch

Type: Boolean Default: false

--noFallthroughCasesInSwitch option for tsc command. (at least version 1.8)

Disallow fallthrough cases in switch statement.

options.allowSyntheticDefaultImports

Type: Boolean Default: false

--allowSyntheticDefaultImports option for tsc command. (at least version 1.8)

Indicates that the module loader performs some kind of synthetic default import member creation not indicated in the imported .ts or .d.ts.

options.jsx

Type: String Default: null

--jsx option for tsc command.

Enable React support. (Starting from TSC version 1.6)

options.reactNamespace

Type: Boolean Default: false

--reactNamespace option for tsc command. (at least version 1.6)

Allow specify namespace name for JSX factory.

options.sourceMap

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.

options.suppressImplicitAnyIndexErrors

Type: Boolean Default: false

--suppressImplicitAnyIndexErrors option for tsc command. (Starting from TSC version 1.5)

Suppress noImplicitAny errors for indexing objects lacking index signatures.

options.reactNamespace

Type: Boolean Default: false

--reactNamespace option for tsc command. (at least version 1.8)

Disallow fallthrough cases in switch statement.

options.tmpDir

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.

options.noLib

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)

options.keepTree

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.

options.pathFilter

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 value | Effect | | ------------------- | ------ | | true, undefined | Use the file as-is. | | false | Skip the file. (not piped into output gulp stream) | | String | Replace the file's path with the returned string. | | vinyl.File | Use the returned vinyl.File instead. |

options.safe

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.

options.emitDecoratorMetadata

Type: Boolean Default: false

--emitDecoratorMetadata option for tsc command.

Emit decorator metadata.

options.experimentalDecorators

Type: Boolean Default: false

--experimentalDecorators option for tsc command.

Enable experimental Decorator support. (Starting from TSC version 1.5)

options.additionalTscParameters

Type: Array of string Default: []

This option is used to pass any parameter to tsc command. Especially it can be used to pass parameters not yet suported by gulp-tsc. You have to pass each parameter separately.

Example:

gulp.task('compile', function(){
  gulp.src(['src/**/*.tsx'])
    .pipe(typescript({
      additionalTscParameters: ['--jsx', 'react']
    }))
    .pipe(gulp.dest('build/'))
});

Error handling

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/'));
});

Path modification

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/'))
});

Temporary directory and file by gulp-tsc

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.