ts-gulp-tasks v1.0.2

Master: Develop:

:: 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 your gulpfile.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 callback Function, return an event stream or return a Promise.

as defined by Gulp functionality, all dependent tasks execute asynchronously

using @Task on a static method of class not decorated with @Gulp will fail to register the method as a Gulp 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 names
• outputGulpSetup, defaults to false, if set to true output's all tasks, including dependent tasks, to stdout.

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 to true

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 your gulpfile.ts configuration, which is highly probable (this project required it), ts-node can be set to use a different configuration file with the TS_NODE_PROJECT environment variable set to a gulpfile.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 custom tsconfig.json, using the Gulp Settings dialog, if it differs from your project's configuration file, which it most likely will.