Merging Two Gulp Streams

When you use gulp as your task runner, as is common in JavaScript development these days, your gulpfile.js contains a series of tasks. Some of those tasks might depend on each other, so you have to make sure they run in the right order. After all, you don't want to clean a directory right after you've written files to it.

Within a gulp task, you usually read some files using gulp.src, pass them through various transformations using the pipe function, and finally write them back to disk by piping to gulp.dest:

var gulp = require("gulp");
var concat = require("gulp-concat");
var uglify = require("gulp-uglify");

gulp.task("scripts", function () {
  return gulp
    .src(["src/**/*.js"])
    .pipe(concat("bundle.min.js"))
    .pipe(uglify())
    .pipe(gulp.dest("dist/"));
});

Note that there's a return statement that returns the created stream. Without it, the task system wouldn't be able to detect when asynchronous operations finish and thus couldn't await the result of the task. Plus, the task runner would incorrectly display very short task execution times.

So, to make sure asynchronous operations are handled correctly, you should always return the created stream. But what if there are multiple streams in a single task? Which one do you return? Somehow, these streams have to be combined into a single stream that can be handed back to gulp's task system.

Of course, there's an NPM package that does precisely that: merge-stream creates a stream that emits events from multiple other streams. Here's how it's used:

var merge = require("merge-stream");

gulp.task("copy-vendor-files", function () {
  var vendorStyles = gulp
    .src("src/styles/vendor/*.css")
    .pipe(gulp.dest("dist/styles/vendor"));

  var vendorScripts = gulp
    .src("src/scripts/vendor/*.js")
    .pipe(gulp.dest("dist/scripts/vendor"));

  return merge(vendorStyles, vendorScripts);
});

Two separate streams read vendor library files and copy them to different folders in the dist directory. The copy-vendor-files task isn't finished until both individual streams are, so the two are merged into a single stream that is returned to gulp's task system. That's it!