TypeScript compiler for gulp 3
First, install gulp-tsc as a development dependency:
npm install --save-dev gulp-tscThen, 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/'))
});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:
- from
typescriptmodule installed as your project's dependency (i.e.require("typescript")on current directory) - from PATH of the running shell (using node-which)
- from Bundled
typescriptmodule
(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" or "amd")
Default: "commonjs"
--module option for tsc command.
Type: String ("ES3" or "ES5")
Default: "ES3"
--target option for tsc command.
Type: String
Default: null
--out option for tsc command.
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.
Type: Boolean
Default: false
--noResolve option for tsc command.
Type: Boolean
Default: false
--removeComments option for tsc command.
Type: Boolean
Default: false
--sourcemap option for tsc command.
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: 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 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. |
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.
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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent