A typescript compiler for gulp with incremental compilation support.
A gulp plugin that compiles TypeScript files.
- Incremental compilation (so faster builds)
- Error reporting
- Different output streams for .js, .d.ts files.
- Support for sourcemaps using gulp-sourcemaps
- Compile once, and filter different targets
- Not just a wrapper around the
tsccommand, but a plugin that uses the TypeScript API.
npm install gulp-typescript
var ts = require'gulp-typescript';var tsResult = pipetsoptions;tsResultdtspipetsResultjspipe
var ts = require'gulp-typescript';var merge = require'merge2';gulptask'scripts'var tsResult = gulpsrc'lib/*.ts'pipetsdeclarationFiles: truenoExternalResolve: true;return mergetsResultdtspipegulpdest'release/definitions'tsResultjspipegulpdest'release/js';;
Instead of calling
ts(options), you can create a project first, and then call
ts(project). An example:
var ts = require'gulp-typescript';var merge = require'merge2';var tsProject = tscreateProjectdeclarationFiles: truenoExternalResolve: true;gulptask'scripts'var tsResult = gulpsrc'lib/*.ts'pipetstsProject;return merge // Merge the two output streams, so this task is finished when the IO of both operations are done.tsResultdtspipegulpdest'release/definitions'tsResultjspipegulpdest'release/js';;gulptask'watch' 'scripts'gulpwatch'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.
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)
noEmitOnError(boolean) - Do not emit outputs if any type checking errors were reported.
target(string) - Specify ECMAScript target version: 'ES3' (default), 'ES5' or 'ES6'.
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).
typescript(object) - Use a different version / fork of TypeScript (see below). You probably won't need this option, unless you know what you're doing!
You can use a custom version of TypeScript. Add the version you want (1.4+) to your package.json file as a devDependency. You can also use the master from GitHub to get the latest features. You can use this in your
package.json to get the master from GitHub:
"devDependencies":"gulp-typescript": "*""typescript": "Microsoft/TypeScript"
It's also possible to use a fork of TypeScript. Add an extra option to the options object like this:
There are two ways to filter files:
gulptask'scripts'var tsResult = gulpsrc'lib/*.ts'pipetstsProject filterSettings;;
gulptask'scripts'var tsResult = gulpsrc'lib/*.ts'pipetstsProject;tsResultpipetsfilterfilterSettings ;;
The first example doesn't add files (that don't pass the filter) to the compiler, the second one does add them to the compiler, but removes them later from the stream. You can put as much pipes between compilation and filtering as you want, as long as the filename doesn't change.
At the moment there is only one filter available:
referencedFrom(string) Only files that are referenced (using
/// <reference path="..." />) by the files in this array pass this filter.
By default, gulp-typescript 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-typescript 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: faster compilation.
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, unless you are using the
tsc command has the ability to concatenate using the
--out parameter. There are two approaches to do that in
You can use the
out option. This is fine for small projects, but for big projects it's not always sufficient.
The other option is to use
tsc command sorts the files using the
gulp-typescript does this when you enable the
sortOutput option. You can use the
referencedFrom filter to only include files that are referenced from certain files.
Source maps have changed a bit in version 0.2.0. Here's an example gulpfile:
var ts = require'gulp-typescript';var concat = require'gulp-concat';var sourcemaps = require'gulp-sourcemaps';gulptask'scripts'var tsResult = gulpsrc'lib/*.ts'pipesourcemapsinit // This means sourcemaps will be generatedpipetssortOutput: true// ...;return tsResultjspipeconcat'output.js' // You can use other plugins that also support gulp-sourcemapspipesourcemapswrite // Now the sourcemaps are added to the .js filepipegulpdest'release/js';;
For more information, see gulp-sourcemaps.
You can specify a custom reporter as the 3rd argument of the main function:
tsoptionsOrProject filters reporter;
You can set options, project or filter to
if you don't want to set them. Available reporters are:
- nullReporter (
ts.reporter.nullReporter()) - Don't report errors
- defaultReporter (
ts.reporter.defaultReporter()) - Report basic errors to the console
- fullReporter (
ts.reporter.fullReporter(showFullFilename?: boolean)) - Show full error messages, with source.
If you want to build a custom reporter, you take a look at
lib/reporter.ts, in that file is an interface which a reporter should implement.
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
The plugin uses itself to compile. There are 2 build directories,
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
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