gulp-type
v0.3.0gulp-type
A gulp plugin that compiles TypeScript files.
Features
- Incremental compilation (so faster builds)
- Error reporting
- Different output streams for .js, .d.ts files.
- Support for sourcemaps using gulp-sourcemaps
- Not just a wrapper around the
tsc
command, but a plugin that uses the TypeScript API.
How to install
npm install gulp-type
Easy usage
var ts = require('gulp-type');
[...]
var t sResult = [...].pipe(ts(options));
tsResult.dts.pipe(...)
tsResult.js.pipe(...)
Example gulpfile:
var ts = require('gulp-type');
gulp.task('scripts', function() {
var tsResult = gulp.src('lib/*.ts')
.pipe(ts({
declarationFiles: true,
noExternalResolve: true
}));
tsResult.dts.pipe(gulp.dest('release/definitions'));
return tsResult.js.pipe(gulp.dest('release/js'));
});
Incremental compilation
Instead of calling ts(options)
, you can create a project first, and then call ts(project)
. An example:
var ts = require('gulp-type');
var tsProject = ts.createProject({
declarationFiles: true,
noExternalResolve: true
});
gulp.task('scripts', function() {
var tsResult = gulp.src('lib/*.ts')
.pipe(ts(tsProject));
tsResult.dts.pipe(gulp.dest('release/definitions'));
return tsResult.js.pipe(gulp.dest('release/js'));
});
gulp.task('watch', ['scripts'], function() {
gulp.watch('lib/*.ts', ['scripts']);
});
When you run gulp watch
, the source will be compiled as usual. Then, when you make a change and save the file, your TypeScript files will be compiled in about half the time.
Make sure you create the project outside of a task! Otherwise it won't work.
Options
removeComments
(boolean) - Do not emit comments to output.noImplicitAny
(boolean) - Warn on expressions and declarations with an implied 'any' type.noLib
(boolean) - Don't include the default lib (with definitions for - Array, Date etc)target
(string) - Specify ECMAScript target version: 'ES3' (default), or 'ES5'.module
(string) - Specify module code generation: 'commonjs' or 'amd'sourceRoot
(string) - Specifies the location where debugger should locate TypeScript files instead of source locations.declarationFiles
(boolean) - Generates corresponding .d.ts files.noExternalResolve
(boolean) - Do not resolve files that are not in the input. Explanation below.sortOutput
(boolean) - Sort output files. Usefull if you want to concatenate files (see below).
Resolving files
By default, gulp-type will try to resolve the files you require and reference. These files are parsed, but not emitted (so you will not see them in the output stream).
If you set the option noExternalResolve
to true, gulp-type will not resolve all the requires and references. It assumes that all the necessary files are in the input stream. For example, if you have your .ts
files in the lib
folder, and the .d.ts
files in the definitions
folder, you must use gulp.src(['lib/**.ts', 'definitions/**.ts'])
instead of gulp.src(['lib/**.ts'])
in your gulpfile if you use the option noExternalResolve
.
Advantage of noExternalResolve
: faster compilation.
Disadvantage of noExternalResolve
: won't work when you forgot some input files.
Advice: turn it on, and make sure you list all the input files.
Files that are resolved when noExternalResolve
is off, won't be pushed to the output stream.
Concatenate files
The tsc
command has the ability to concatenate using the --out
parameter. gulp-type
doesn't have that, because you should use the gulp-concat
plugin for that, or - if you want sourcemaps - gulp-concat-sourcemaps
.
The tsc
command sorts the files using the <reference>
tags. gulp-type
does this when you enable the sortOutput
option.
Source maps
Source maps have changed a bit in version 0.2.0. Here's an example gulpfile:
var ts = require('gulp-type');
var concat = require('gulp-concat-sourcemap');
var sourcemaps = require('gulp-sourcemaps');
gulp.task('scripts', function() {
var tsResult = gulp.src('lib/*.ts')
.pipe(sourcemaps.init()) // This means sourcemaps will be generated
.pipe(ts({
sortOutput: true,
// ...
}));
return tsResult.js
.pipe(concat('output.js')) // You can use other plugins that also support gulp-sourcemaps
.pipe(sourcemaps.write()) // Now the sourcemaps are added to the .js file
.pipe(gulp.dest('release/js'));
});
For more information, see gulp-sourcemaps.
How to build
First you have to install gulp using npm install gulp -g
, if you haven't done already. Then you must install the npm dependencies, using npm install
.
The plugin uses itself to compile. There are 2 build directories, release
and release-2
. release
must always contain a working build. release-2
contains the last build. When you run gulp compile
, the build will be saved in the release-2
directory. gulp test
will compile the source to release-2
, and then it will run some tests. If these tests give no errors, you can run gulp release
. The contents from release-2
will be copied to release
.