search

reaganthomas / gulp-simple-task-loader

MIT License
4 stars 3 forks source link

readme

Gulp Simple Task Loader

NPM

npm version Coverage Status Build Status Dependency Status Codacy Badge

Pull Requests Status Issues Status

Easily modularize gulp tasks and minify your gulpfile. Works well with gulp-load-plugins.

Installation

$ npm install gulp-simple-task-loader --save-dev

Test

To test this package clone it and run the following commands:

$ npm install
$ npm test

Usage

var taskLoader = require('gulp-simple-task-loader');
taskLoader(options);

This will load and register tasks for all files defined in your taskDirectory.

If your tasks aren't registering (they are, but to the wrong gulp package) you can optionally specify a gulp to register the tasks to.

var gulp = require('gulp');
var taskLoader = require('gulp-simple-task-loader');
taskLoader(options, gulp);

Options

You can pass in an options object as shown below. The values shown below are the defaults.

taskLoader({
  taskDirectory: 'gulp-tasks', // the directory your tasks are stored in (relative and absolute paths accepted)
  plugins: {},                 // the plugins to expose to your tasks
  filenameDelimiter: '',       // a character or string of characters to replace in task filenames
  tasknameDelimiter: '',       // a character or string of characters to insert in place of removed filenameDelimiter
  config: {},                  // an object to store configuration for use in tasks
  configFile: ''               // the relative path to your task configuration file from your task directory
});

Task Directory

Only put gulp tasks in your taskDirectory. All .js files in this directory, unless the configFile option is being used, will be attempted to be read as gulp tasks. Nested directories are supported as of v1.0.29.

Delimiters

The purpose of the delimiters is to allow flexibility in task naming. A common convention for task names is to delimit using the : character, however :'s are not generally used or allowed in file names. A common usage of the delimiters is as follows:

taskLoader({
  filenameDelimiter: '-',
  tasknameDelimiter: ':'
});

These options would convert a filename such as move-all.js to a task with the name move:all.

Plugins

Using gulp-load-plugins

You can use gulp-load-plugins to easily lazy-load your gulp plugins. Use gulp-load-plugins in conjunction with gulp-simple-task-loader to minimize your gulpfile.

'use strict';

var taskLoader = require('gulp-simple-task-loader');
var plugins = require('gulp-load-plugins')();

taskLoader({ plugins: plugins });

Passing in plugins manually

If not using gulp-load-plugins you must specify which plugins you want made available to your tasks.

(gulpfile.js)
'use strict';

var taskLoader = require('gulp-simple-task-loader');
var plugins = {
  bump: require('gulp-bump'),
  mocha: require('gulp-mocha')
};

taskLoader({ plugins: plugins });

Config File

You have the option of passing in the location of a configuration file from within your task directory. Please note that the configuration file takes precedence over the config option that you may also pass in, meaning that any key in config is overwritten if the same key exists in the config file.

(gulpfile.js)
'use strict';

var taskLoader = require('gulp-simple-task-loader');
var config = { env: 'production' };

taskLoader({ config: config, configFile: 'config.js' });
(config.js)
'use strict';

module.exports = {
  // insert configuration options here
};

Structuring a task

All tasks should be functions that receive the parameters gulp, config, and plugins.

There are 2 ways to structure a task -- returning a function that executes the task, or returning an object that contains dependencies, parameters, and the function that executes the task.

Basic tasks

This is a typical function as you are used to with gulp.

'use strict';

module.exports = function(gulp, config, plugins) {
  return function([callback]) {}; // the task functionality -- callback optional
};

Tasks with dependencies and/or parameters

All 3 object keys (deps, params, and fn) are optional. This allows you to create a task that strictly calls other tasks, a task that is parameterized, or a task that just acts like a normal task.

If there are no dependencies or parameters for the task you can use the above "Basic task" format for creating a basic task.

The values shown below are the defaults.

'use strict';

module.exports = function(gulp, config, plugins) {
  return {
    deps: [],                   // an array of task names to execute before this task
    params: [],                 // an array of parameters to send to `fn`
    fn: function([callback]) {} // the task functionality -- callback optional
  };
};

Please note that if you use the params key your fn must be of the following form:

params: [ 'a', 'b' ],
fn: function(param, cb) {} // where param is an item from the params array,
                           // and cb is a callback to be called at the end of your function

Complete examples

Using gulp-load-plugins

(gulpfile.js)

'use strict';

var taskLoader = require('gulp-simple-task-loader');
var plugins = require('gulp-load-plugins');

taskLoader({
  filenameDelimiter: '-',
  tasknameDelimiter: ':',
  plugins: plugins
});
(tasks/lint-all.js)

'use strict';

module.exports = function(gulp, config, plugins) {
  return {
    deps: [ 'lint:client', 'lint:server' ]
  };
};
(tasks/lint-client.js)

'use strict';

module.exports = function(gulp, config, plugins) {
  return function() {
    return gulp.src('./client/**/*.js')
      .pipe(plugins.jshint);
  };
};
(tasks/lint-server.js)

'use strict';

module.exports = function(gulp, config, plugins) {
  return function() {
    return gulp.src('./server/**/*.js')
      .pipe(plugins.jshint);
  };
};

Parameterize tasks

(gulpfile.js)

'use strict';

var taskLoader = require('gulp-simple-task-loader');
var plugins = require('gulp-load-plugins');

taskLoader({
  filenameDelimiter: '-',
  tasknameDelimiter: ':',
  plugins: plugins
});
(tasks/parameterized.js)

'use strict';

module.exports = function(gulp, config, plugins) {
  return {
    params: [ '1', '2' ],
    fn: function(param, cb) {
      console.log(param);
      cb();  // note that the callback must be called in order for the task
             // to finish iterating through your params array
    }
  };
};

The task in parameterized.js would produce the following output:

1
2

Changelog

Documented below are any significant changes to the package.