Gulp Common Utils

Provides a set of methods to support common gulp operations. Includes an autoloader that allows you to inject common code for your tasks. See usage for more details. This library has no external dependencies besides gulp itself.

Usage

If you're using this library in conjuction with an ES6 compiler (i.e. Babel with require hooks), simply require the package root. ES6 is preferred since the injected object works really well with destructuring. However, if you're still on ES5 this package also exposes a transpiled version so you don't miss out. There's also an example gulpfile which can be run using npm run sample.

require('gulp-common-utils'); // es6
require('gulp-common-utils/es5'); // es5

Autoloading tasks is painless, just pass a configuration object to .load():

const path = require('path');
 
require('gulp-common-utils').load({
  path   : path.resolve(__dirname, 'build/tasks'), // tasks dir
  inject : {} // this object gets passed to every task file
});

If you want the autoloader to recursively search your tasks directory, you can flag this via the "deep" property in your load config. For more details on the configuration options, see configuration.

require('gulp-common-utils').load({
  deep : true
});

Defining Your Tasks

Task files should export a function, and all gulp tasks should reside within that function definition. By default the injected object will expose a "gulp" and "common" property, "common" being a reference to this library.

// build/tasks/default.js
module.exports = function (inject) {
 
  // use destructuring to easily reference properties from the injected utilities.
  const { gulp, common } = inject;
 
  gulp.task('default', function () {
    // do something...
  });
};

Custom Injections

If you'd like to inject more than just the default gulp and common definitions into your tasks, simply provide them via the "inject" property on the configuration object when calling load().

const path = require('path');
 
require('gulp-common-utils').load({
  path : path.resolve(__dirname, 'build/tasks'),
  inject : {
    path : path
  }
});
 
// build/tasks/default.js
module.exports = function (inject) {
 
  // path is now a property on inject
  const { gulp, path } = inject;
 
  // task definition(s)
};

Configuration

The load task accepts a single configuration object with the following properties:

Path (String)

Default: "~/build/tasks"

Absolute path that points to the root of the directory containing your task definitions.

[Optional] Inject (Object)

Default:

{
  gulp : require('gulp'),
  common : require('gulp-common-utils')
}

Object that will be passed to each task file's export function. Includes "gulp" and "common" properties by default.

[Optional] Deep (Boolean)

Default: false

Specify whether or not to perform a deep search of the root directory.

Example

See ~/example for a sample gulpfile. You can also use npm run sample to run it from this project's root.

Contributing

Please make sure to run "npm run build" to create the transpiled es5.js file. You must have babel installed globally for this to work.

npm install -g babel

TODO

• Improve error handling/reporting
• Tests (Mocha)