ts-gulp-tasks v1.0.2
:: Usage :: API :: Installation :: Running Gulp Tasks
Write Gulp Tasks with Typescript
Utilize custom
Decorators
to convert classes and their static
methods to
Gulp
tasks, optionally define dependency tasks, work with existing gulp
plugin(s)
and enjoy Typescript
's strongly typed benefits.
Usage
import { Gulp, Task, SetGulpOptions } from "ts-gulp-tasks";
import * as gulp from "gulp";
import * as tsc from "gulp-typescript";
import * as maps from "gulp-sourcemaps";
import * as lint from "gulp-tslint";
const del = require("del");
SetGulpOptions({
"allowSpacesInTaskNames": false,
"outputGulpSetup": true
});
@Gulp(gulp)
class GulpFile {
@Task("build")
static default(done: Function): void {
done();
}
@Task("clean", "tslint-src")
static build(): NodeJS.ReadableStream {
let ts = tsc.createProject("tsconfig.json");
return ts.src()
.pipe(maps.init())
.pipe(tsc(ts)).js
.pipe(maps.write())
.pipe(gulp.dest("release"));
}
@Task()
static clean(done: Function): void {
del.sync([ "release\\**\\*" ]);
done();
}
@Task()
static "tslint-src"(): NodeJS.ReadableStream {
return gulp.src([ "src\\**\\*.ts" ])
.pipe(lint({
configuration: "tslint.json"
}))
.pipe(lint.report());
}
}
API
@Gulp class and @Task method Decorators are used to setup gulp tasks.
@Gulp([instance])
The @Gulp
class decorator indicates that a class
contains Gulp
task(s).
instance
is a required parameter expecting an instance of gulp
, to which
tasks are registered.
Organizing Gulp Tasks
Tasks can be organized across multiple classes and across multiple external files.
Use the
import
statement to include externally defined task registrations in yourgulpfile.ts
import "./gulp-tasks/linting-tasks";
* see this project's
gulpfile.ts
for an advanced example
@Task([...dependentTasks])
The @Task
decorator registers a class' static
method as a Gulp
task.
dependentTasks
is an optional list of dependent task names.- The
@Task
decorator captures and uses the method name as the task's name. - Use quote marks around the method name to include none standard symbols, such as hyphens.
- Task methods should either call the provided
done
callbackFunction
, return an eventstream
or return aPromise
.
as defined by
Gulp
functionality, all dependent tasks execute asynchronouslyusing
@Task
on astatic
method of class not decorated with@Gulp
will fail to register the method as aGulp
task.
SetGulpOptions([options])
Use the SetGulpOptions
method to set ts-gulp-tasks
options.
options
is an object
literal, that defines the following options
allowSpacesInTaskNames
, defaults to false, if set to true allows spaces in task namesoutputGulpSetup
, defaults to false, if set to true output's all tasks, including dependent tasks, tostdout
.
outputGulpSetup: true
example output ...GulpFile defines 3 task(s) clean: run nothing else first build: run clean first clean-test: run nothing else first test: run [ clean-test, build ] first
* use
SetGulpOptions
before the first@Gulp
class definition or an import which contains external definitions.
Installation
Use the following npm
command line, in the root folder of your project, to
install the ts-gulp-tasks
package locally and save it as a dev dependency
in your project's packages.json
.
<your-app-root> $ npm i -D ts-gulp-tasks
Running Gulp Tasks
Use Gulp's support for LiftOff
and Interpret, which uses a local
installation of ts-node, to
interpret and run Typescript
code in Node
.
You need to do two things to get this working:
- first, install
ts-node
locally, it's recommended to save it as a dev dependency - second, ensure the
experimentalDecorators
tsconfig setting is set totrue
voilà ... gulp will work as expected.
<your-app-root> $ gulp build
Installing ts-node
Use the following npm
command line, in the root folder of your project, to
install the ts-node
package locally and save it as a dev dependency
in your project's packages.json
.
<your-app-root> $ npm i -D ts-node
if your project's
tsconfig.json
needs to be different from yourgulpfile.ts
configuration, which is highly probable (this project required it),ts-node
can be set to use a different configuration file with theTS_NODE_PROJECT
environment variable set to agulpfile.ts
specific configurations file. see this project's "build" | "test"npm
scripts for an example.
WebStorm
The very latest version of WebStorm,
(2016.2.2 as of this writing), has a Gulp
task runner that automatically recognizes
and supports gulpfile.ts
, if you have ts-node
locally installed.
The only caveat being is you to set
TS_NODE_PROJECT
environment option to point to your customtsconfig.json
, using the Gulp Settings dialog, if it differs from your project's configuration file, which it most likely will.