Mastering Gulp 4’s Series and Parallel API: Build Workflows Made Predictable

Why order matters in a build pipeline

In a typical front‑end project you often have to clean a distribution folder, compile Sass, transpile JavaScript, run tests, and finally bundle everything for production. If one step runs before its prerequisite, you’ll end up with stale files or missing dependencies. In Gulp 3 the implicit dependency system was fragile – tasks would simply run in the order they were defined, and there was no way to guarantee that a file a later task expected had actually been written.

Gulp 4’s explicit composition helpers

Gulp 4 replaces that implicit model with two clear helpers: gulp.series() and gulp.parallel(). They accept either named tasks (strings) or inline async functions, and they return a new task that Gulp can execute. The API is intentionally simple: series guarantees sequential execution, parallel runs tasks concurrently.

Series – the safe path

Use series when the output of one task is a required input for the next. For example, you must clean the dist folder before you build anything into it. The following snippet shows a minimal example:

const { series, src, dest, deleteAsync } = require('gulp');

function clean() {
  return deleteAsync('dist');
}

function buildJs() {
  return src('src/**/*.js')
    .pipe(/* transpile, bundle, etc */)
    .pipe(dest('dist/js'));
}

exports.default = series(clean, buildJs);

When you run gulp, Gulp will first finish clean, then start buildJs. If clean never finishes (for example, it forgets to return the promise from deleteAsync), the whole pipeline stalls.

Parallel – speed up independent work

When tasks don’t share state, you can run them at the same time to cut build time. A common pattern is linting and unit‑testing in parallel, then bundling after both complete:

const { parallel, series, src, dest } = require('gulp');

function lintJs() {
  return src('src/**/*.js')
    .pipe(/* eslint */);
}

function lintCss() {
  return src('src/**/*.css')
    .pipe(/* stylelint */);
}

function bundle() {
  return src('dist/**/*')
    .pipe(/* webpack */)
    .pipe(dest('build'));
}

exports.build = series(
  parallel(lintJs, lintCss),
  bundle
);

On a quad‑core machine you’ll notice the linting steps finish roughly a third of the time compared to running them sequentially.

Practical decision‑making: when to mix series and parallel

In real projects you often need a mix. For example, you might want to lint everything, then run a test suite that depends on the linted files, and finally build the bundle:

exports.default = series(
  parallel(lintJs, lintCss),
  testSuite,
  bundle
);

Here the testSuite will only start after both lint tasks finish. However, if testSuite accidentally writes to a file that lintJs reads, you’ll get a race condition. The rule of thumb: keep side‑effects isolated; only run tasks in parallel if they are truly independent.

Common pitfalls and how to avoid them

• Missing return value. Gulp 4 determines task completion by a returned stream, promise, or callback. Forgetting to return a promise will cause the task to finish immediately, potentially leaving files in an inconsistent state.
• Unregistered tasks. If you pass an async function directly to series or parallel, Gulp does not expose it as a named task. That’s fine for internal composition but you’ll lose the ability to run it standalone via gulp <task>.
• Over‑parallelizing. Running too many tasks in parallel can exhaust file descriptors or memory. Use gulp.parallel(..., { concurrency: 4 }) to limit the number of simultaneous workers.

Verifying your pipeline works as intended

1. Run gulp --tasks to list all exported tasks and confirm the composite ones are present.
2. Insert console.log statements in each task to see the order in the terminal. For example:

   function demo() {
     console.log('first');
     return Promise.resolve();
   }
   exports.test = series(demo, () => console.log('second'));
   

3. Measure the total time with time gulp build before and after adding parallel. A significant drop indicates concurrent execution.

Takeaway

Gulp 4’s series and parallel give you explicit control over build order and concurrency. Use series for steps that depend on each other, parallel for independent work, and keep an eye on side‑effects to avoid race conditions. With a well‑structured gulpfile you’ll get predictable builds, faster feedback, and a clearer maintenance path.