Parched

NOTE: This is hella experimental. Please give any feedback you might have.

Parched is a tiny layer built on top of Gulp that lets people write and share plugins and tasks with minimal configuration from the end user.

It aims for convention over configuration.
It is heavily inspired by Brunch.

See parched-example-app, or parched-tasks-webapp even. The following will be based on them.

A list of ready-made plugins can be found on npm.

Getting Started

npm install --save gulp parched

Then update your Gulpfile.js.

var gulp = require('gulp');
var Parched = require('parched');

Parched.setup({
  gulp: gulp,
  
  plugins: {
    'parched-jshint': {
      reporter: 'some-other-reporter'
    }
  },
  
  parchedWillBuild: function (done) {
    console.log('Before');
    done();
  },
  
  parchedDidBuild: function (done) {
    console.log('After');
    done();
  }
});

Any dependencies in package.json starting with /^parched-.+/ will be loaded, and, if they export a function they will be passed a Parched API object.

This is parched-jshint:

var jshint = require('gulp-jshint');
var stylish = require('jshint-stylish');

// All plugins and tasks loaded by Parched are passed an object containing
// the API.
module.exports = function (Parched) {
  Parched.createPlugin({
    // This property is required and must be unique.
    // The upside is all plugins are more easily configured
    // and sorted in `appConfig`.
    displayName: 'parched-jshint',
    
    // This can be an array.
    src: '*.js',
    
    // Returns an empty object by default.
    getDefaultOptions: function () {
      return {
        reporter: stylish
      };
    },
    
    // This will be called in the task we create later.
    lint: function () {
      // Basically, plugins return something that will work in a regular
      // Gulp pipeline. Return one item or an array, Parched don't mind.
      var pipeline = [
        jshint(this.options),
        jshint.reporter(this.options.reporter)
      ];
      
      // There is a concept of `production`.
      if (this.isProduction()) {
        pipeline.push(jshint.reporter('fail'));
      }
      
      return pipeline;
    }
  });
};

Okay, sure, but how do you call these methods? First, let's define a task:

Parched.createTask({
  taskName: 'build-app-scripts',
  
  // This can be an array.
  src: 'app/scripts/**/*',
  
  // Parched makes heavy use of `run-sequence`, in this example `lint` and
  // `transform` will be run in parallel. Drop the nested array and they will
  // be run in sequence.
  sequence: [
    ['lint', 'transform']
  ]
});

Now in your terminal run gulp build-app-scripts. Voila!

You might expect the output of lint to be passed to transform, but Parched opts for parallelization. To do more with the methods in the sequence, you can simply add before and after callbacks in createTask.

Parched.createTask({
  // ...
  
  // This prepended to each stream in the sequence.
  beforeEach: function (stream, streamContext) {
    // `streamContext` contains context ... about the stream.
    console.log(streamContext);
    return stream
      .pipe(cached(streamContext.taskNameUnique));
  }
  
  // This is appended to each stream in the sequence.
  afterEach: function (stream, streamContext) {
    return stream
      .pipe(remember(streamContext.taskNameUnique));
  }
  
  // This is appended to the `transform` stream.
  afterTransform: function (stream) {
    return stream
      .pipe(gulp.dest('public'));
  }
});

Parched.setup(appConfig)

The main entrypoint into Parched.

Property | Description ---------|------------ stream beforeEach(stream, streamContext) | Will be run before every method of every sequence of every task stream afterEach(stream, streamContext) | Will be run after every method of every sequence of every task string[]? plugins.order.before | Specify which plugins should be run first string[]? plugins.order.after | Specify which plugins should be run last object? plugins[plugin.displayName] | Will be merged with plugin.getDefaultOptions() to create plugin.options void parchedWillBuild(done) | Put any logic you want to run before any builds here. void parchedDidBuild(done) | Put any logic you want to run after any builds here.

Public API

Parched.createPlugin(pluginPrototype)

Property | Description ---------|------------ string displayName | The unique name of the plugin string[] src | Which files to act on bool? shouldProcessAssets() | Does this plugin process "assets"? object? getDefaultOptions() | The plugin's default options bool isProduction() | NODE_ENV === 'production' stream processManyFiles(src / null, context, process(files, done)) | Returns a through stream, passing all matched files to the process callback. If no src was passed, the plugin's src will be used. stream noop | gutil.noop

Parched.createTask(taskOptions)

Passes each item in the sequence to createPluginMethodTask and a creates a gulp task that returns a runSequence based on [].concat(deps).concat(sequence)

Property | Description ---------|------------ string taskName | The name of the task string? helpText | Help text to be displayed with gulp --help string[] sequence | The sequence of methods to be called in this task string[]? deps | Any dependencies of this task. Note these are passed through run-sequence, so nested arrays means run in parallel.

Parched.addPluginMethodsToStream(streamContext)

Pipe a stream through all plugins and their methods.

For instance this is used in the webapp tasks in afterTransform of the final scripts and styles builds to to run minify

Property | Description ---------|------------ string[] methodNames | Flat list of plugin method names stream stream | The stream to be modified bool? shouldProcessAssets | To asset or not bool? shouldProcessUnderscores | Process files / folders that start with an underscore

Parched.createPluginMethodTask(options)

Creates a Gulp task of many gulp.src streams that are modified in before and after callbacks.

Property | Description ---------|------------ string taskName (string) | The name of the task string src | Which files to act on (can also be an array) void? modifyContext(taskOptions) | Modify the taskOptions / streamContext bool? shouldProcessAssets | Are these files "assets"? stream? beforeEach(stream, streamContext) | Will be run before each method in the sequence stream? afterEach(stream, streamContext) | Will be run after each method in the sequence stream? beforeMethod(stream, streamContext) | Will be run before the targeted method in the sequence stream? afterMethod(stream, streamContext) | Will be run after the targeted method in the sequence

Parched has a concept of assets. If a task shouldProcessAssets, any plugins that don't will be skipped, and vice versa.

A note on before/after callbacks: The targeted callbacks are called before and after beforeEach / afterEach, ie given we are calling the lint method from parched-jshint:

var streamContext = {
  pluginInstance: __pluginInstance,
  methodName: 'lint',
  taskName: 'build-app-scripts',
  taskNameProxy: 'build-app-scripts--lint',
  taskNameUnique: 'build-app-scripts--lint--parched-jshint'
};

beforeLint(stream, streamContext);
beforeEach(stream, streamContext);
beforeEachFromConfig(stream, streamContext);
__pluginInstance[methodName](streamContext);
afterEachFromConfig(stream, streamContext);
afterEach(stream, streamContext);
afterLint(stream, streamContext);

Parched.sortBeforeAfter(options)

Sort an array based on before and after properties.

Property | Description ---------|------------ object[] collection | The array to act on string[]? before | What should be first string[]? after | What should be last string? getItem(item) | Any logic to identify the item

Parched.gulpSort(options)

Sort a stream of gulp files with sortBeforeAfter

Property | Description ---------|------------ string[]? before | What should be first string[]? after | What should be last

Parched.processManyFiles(src, streamContext, process(files, done))

Returns a through stream that will call process with any files matching src. When used in a watch scenario, it will run when files are updated, not only when their contents change.

When used in createPlugin, omitting src with give you an array of all files matching plugin.src. This allows things like parched-webfont have configurable options.svgPath while still watching all .svg assets for changes.

Property | Description ---------|------------ object taskNameUnique | Something unique so the cache can keep track of things.

Parched.addDependencyToClean(taskName)

Adds gulp task taskName to the parched-clean task.

Parched.addDependencyToBuild(taskName)

Adds gulp task taskName to the parched-build task.

Parched.addDependencyToWatch(taskName)

Adds gulp task taskName to the parched-watch task.

Parched.vendor

The foundation.

Exported Name | Package --------------|-------- gulp | This is actually a function that returns the gulp reference defined in appConfig gulpif | gulp-if gutil | gulp-util through2 | through2 combine | stream-combiner merge | merge-stream runSequence | run-sequence xtend | node.extend anymatch | anymatch lazypipe | lazypipe multistream | multistream