Gulp plugin to group vinyl files by properties on the vinyl file using group-array.

array, group, group-array, gulp, gulp-plugin, gulpplugin, plugin, vinyl, vinyl-group
npm install gulp-group-array@0.1.2


gulp-group-array NPM version NPM downloads Build Status

Gulp plugin to group vinyl files by properties on the vinyl file using group-array.


Install with npm:

$ npm install --save gulp-group-array


var groupArray = require('gulp-group-array');



Group vinyl files by specified properties on the vinyl files. This uses group-array to do the grouping after all the vinyl files have come through the stream. See the group-array documentation for more advanced features.


  • args... {Mixed}: All of the arguments will be passed through to group-array except for the last argument if it's an object.
  • options {Object}: Optional object to specify options. If this is passed, then it won't be passed to group-array.
  • options.groupFn {Function}: Function that will be called with the group object. This is the results from calling group-array.
  • options.flush {Boolean}: When set to false, the source files will not be pushed through the stream. (Defaults to true)
  • options.groupFile {Boolean}: When set to true, a new vinyl-group will be created with a .group property containing the group object created by group-array.
  • returns {Stream}: Returns a stream to pipe vinyl source files through.


gulp.task('group', function() {
  return gulp.src(['path/to/src/files/*.js'])
    .pipe(groupArray('dirname', {
      groupFn: function(group) { console.log(group); }


Use the groupFn to capture the group to use the group in another place:

var cache = {};
gulp.task('group', function() {
  return gulp.src(['path/to/src/files/*.js'])
    .pipe(groupArray('dirname', {
      groupFn: function(group) { = group;

gulp.task('default', ['group'], function(cb) {
  // do something with the group

Use groupFile to get the group in another plugin before the other files come through. This example will use gulp-gray-matter to parse yaml front matter from handlebars templates, build a context for each file using the group and the, then render the handlebars templates to html using the context.

This example requires having some handlebars templates with yaml front-matter. Create a few files with the following template:

tags: ['foo', 'bar']
{{#each groups.tags as |items tag|}}
  {{#each items as |item|}}

Use the following javascript in a gulpfile.js to render the files:

var gulp = require('gulp');
var extname = require('gulp-extname');
var extend = require('extend-shallow');
var Handlebars = require('handlebars');
var matter = require('gulp-gray-matter');
var through = require('through2');

var groupArray = require('gulp-group-array');

gulp.task('render', function() {
  var cache = {groups: {}};

  // load handlebars files that have yaml front matter
  return gulp.src(['templates/*.hbs'])

    // use gulp-gray-matter to parse yaml front matter and put it on `.data` object

    // look for `data.tags` from the front matter to group by and push the results into the stream
    .pipe(groupArray('data.tags', { groupFile: true }))

    // custom plugin that captures the tags group and renders the other handlebars files.
    .pipe(through.obj(function(file, enc, cb) {
      // the first file through should be the groupFile
      if ( {
        cache.groups.tags =;
        return cb();

      // use extend-shallow to create a data context from the file front matter and the cache
      var context = extend({}, cache,;

      // render the handlebars using the context
      var content = Handlebars.compile(file.contents.toString())(context);
      file.contents = new Buffer(content);
      cb(null, file);

Run the following command to render the files:

$ gulp render


Related projects


Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Building docs

(This document was generated by verb-generate-readme (a verb generator), please don't edit the readme directly. Any changes to the readme must be made in

To generate the readme and API documentation with verb:

$ npm install -g verb verb-generate-readme && verb

Running tests

Install dev dependencies:

$ npm install -d && npm test


Brian Woodward


Copyright © 2016, Brian Woodward. Released under the MIT license.

This file was generated by verb, v0.9.0, on July 29, 2016.