Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    gulp-tscpublic

    gulp-tsc NPM version Build Status Dependency Status

    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.

    install

    npm i gulp-tsc

    Downloadsweekly downloads

    2,170

    version

    1.3.2

    license

    MIT

    repository

    githubgithub

    last publish

    collaborators

    • avatar
    • avatar