The perfect gulp setup

This project aims to create a modular and configurable gulp setup. Get project automation up and running with minimum involvement.

npm install gulp-cli -g
npm install gulp gulp-load-plugins gulp-setup --save-dev

Sample gulpfile.js

Setting up gulp using gulp-setup is simpler than ever.

const packages = require('gulp-setup/package.json');
const gulp = require('gulp');
const $ = require('gulp-load-plugins')({ config: packages });
const setup = require('gulp-setup')($, gulp);

Default Tasks

By default, gulp-setup comes bundled with a variety of pre-made tasks.

gulp
gulp build
gulp clean
gulp watch
gulp lint
gulp html
gulp html-lint
gulp css
gulp css-lint
gulp sass
gulp sass-lint
gulp stylus
gulp stylus-lint
gulp javascript
gulp javascript-lint
gulp coffeescript
gulp coffeescript-lint
gulp typescript
gulp typescript-lint
gulp fonts
gulp images
gulp browser-sync

gulp

The default task will run a sequence of build, browser-sync, and watch, as you would usually do in gulp.

gulp build

By default, the build task will execute the clean task, after which it runs all the other tasks that provide a pattern parameter.

gulp clean

This task will remove the existing build and dist folders.

gulp watch

The watch task will watch for changes and rebuild any task that provides a pattern parameter. In addition to this, gulp-setup creates a partials graph, which will rebuild any file that depends on the one that got changed.

gulp lint

This task will run any task that ends with -lint.

gulp html

Copies .html files to the build folder, then minifies them and outputs them in dist.

gulp css

Autoprefixes .css files and outputs them to the build folder, then minifies them and outputs them in dist.

gulp sass

Compiles and autoprefixes .sass and .scss files and outputs them to the build folder, then minifies them and outputs them in dist.

This task makes use of the partials graph, meaning that any changes on a partial will trigger a rebuild on the parent files.

gulp stylus

Compiles and autoprefixes .styl files and outputs them to the build folder, then minifies them and outputs them in dist. Stylus instance also provides rucksack-css functionality.

This task makes use of the partials graph, meaning that any changes on a partial will trigger a rebuild on the parent files.

gulp javascript

Compiles ES6 .js files and outputs them to the build folder, then minifies them and outputs them in dist. The javascript task can use either webpack or browserify to process and bundle the files, specified using the options.bundler parameter (as seen in the configuration example below).

This task makes use of the partials graph, meaning that any changes on a partial will trigger a rebuild on the parent files.

gulp coffeescript

Compiles .coffee files and outputs them to the build folder, then minifies them and outputs them in dist. Just like in the javascript task, you can use either webpack or browserify to bundle the files.

This task makes use of the partials graph, meaning that any changes on a partial will trigger a rebuild on the parent files.

gulp typescript

Compiles .ts files and outputs them to the build folder, then minifies them and outputs them in dist. Just like in the javascript task, you can use either webpack or browserify to bundle the files.

This task makes use of the partials graph, meaning that any changes on a partial will trigger a rebuild on the parent files.

gulp images

Optimizes .svg, .jpg, .png, and .gif files and outputs them to the build and dist folders.

gulp fonts

Copies .eot, .svg, .ttf, .woff, and .woff2 files to the build and dist folders.

Configuration

Here's a sample configuration for gulp-setup that sets the options for the existing default javascript task, and creates a new gulp task called javascript-ext by extending the base javascript one. You can override any of the default task parameters when extending a task.

The tasks object key defines the name of the gulp task.

const packages = require('gulp-setup/package.json');
const gulp = require('gulp');
const $ = require('gulp-load-plugins')({ config: packages });
const setup = require('gulp-setup')($, gulp, {
  paths: {
    src: 'path/to/src',
    build: 'path/to/build',
    dist: 'path/to/dist'
  },
  cache: true,
  debug: true,
  tasks: {
    'javascript': {
      options: {
        bundler: 'webpack'
      }
    },
    'javascript-ext': {
      extends: 'javascript',
      paths: {
        src: 'path/to/custom-src'
      }
    }
  }
});

Writing a task

The tasks present in gulp-setup are made out of two components: process and base. All other parameters, such as pattern, are made available in these components.

const setup = require('gulp-setup')($, gulp, {
  tasks: {
    'mytask': {
      base: './bases/base',
      process: './tasks/mytask',
      pattern: '**/*.css',
      paths: {
        src: 'path/to/custom-src',
        build: 'path/to/custom-build',
        dist: 'path/to/custom-dist'
      }
    }
  }
});

Base tasks

The base task serves as a template for other tasks. It makes four pipeline hooks available: init, build, dist and end for integrating a process into it. If the base task is missing, then the process is considered as a standalone task and won't use a template.

// bases/base.js

module.exports = ($, gulp, config, task) => () =>
  gulp.src($.path.join(config.task.src || config.paths.src, task.pattern))
    .pipe(task.process.init())     // Initialization hook
    .pipe($.debug())
    .pipe(task.process.build())    // Building hook
    .pipe(gulp.dest(config.task.build || config.paths.build))
    .pipe(task.process.dist())     // Distribution hook
    .pipe(gulp.dest(config.task.dist || config.paths.dist))
    .pipe(task.process.end());     // Ending hook

The gulp-setup package provides you with the following premade bases: gulp-setup/bases/base, gulp-setup/bases/compile and gulp-setup/bases/lint. You can use these bases for your custom process tasks.

Process tasks

The process task is the main processing that the task is concerned with. Process tasks normally use a template, a base task that they integrate with by providing init, build, dist or end hooks. Alternatively, you can write the process as a standalone gulp task.

Template

// tasks/mytask.js

module.exports = ($, gulp, config, task) => ({
  build: $.lazypipe()
    .pipe($.autoprefixer),
  dist: $.lazypipe()
    .pipe($.cssmin)
});

Standalone

// tasks/myclean.js

module.exports = ($, gulp, config, task) => {
  return () => gulp.src([config.paths.build, config.paths.dist])
    .pipe($.clean());
}

Contributions, bugs and feature requests

Have a bug or a feature request? Please first read the issue guidelines and search for existing and closed issues. If your problem or idea is not addressed yet, please open a new issue.