ZetCode

Gulp series and parallel

last modified November 15, 2026

In this article we compose Gulp tasks with series and parallel. We run tasks one after another and at the same time, nest the two functions, learn how a task tells Gulp that it has finished, and see what happens when a task fails.

Composing tasks

A Gulp task is a function. The functions series and parallel take any number of tasks and return a new task. series runs its tasks one at a time, in the given order; the next task starts when the previous one has finished. parallel starts all its tasks at once and finishes when the last one finishes. Because the result is again a task, the two functions can be nested to any depth. See the Gulp getting started tutorial for the basics.

Series and parallel

To see the order of execution without any file processing, the example defines three fake tasks that print a message, wait for a while, and print another message. The task helper creates them; the displayName property gives each function the name that Gulp shows in its log.

gulpfile.mjs
import { series, parallel } from 'gulp';
import { setTimeout as sleep } from 'node:timers/promises';

function task(name, ms) {

    const fn = async () => {
        console.log(`  ${name} started`);
        await sleep(ms);
        console.log(`  ${name} done`);
    };

    fn.displayName = name;
    return fn;
}

const a = task('a', 300);
const b = task('b', 100);
const c = task('c', 200);

export const inSeries = series(a, b, c);
export const inParallel = parallel(a, b, c);
export const mixed = series(a, parallel(b, c));

The helper is only scaffolding; the interesting part of the file are the three exported tasks.

export const inSeries = series(a, b, c);
export const inParallel = parallel(a, b, c);
export const mixed = series(a, parallel(b, c));

The task a takes 300 ms, b 100 ms, and c 200 ms. The three exported tasks combine them in different ways: all in series, all in parallel, and a first followed by b and c in parallel. The helper uses an async function, so Gulp knows a task is finished when the returned promise is resolved.

In the series the tasks run strictly one after another and the total time is the sum of the three durations, about 600 ms.

$ npx gulp inSeries
[12:45:02] Using gulpfile ~/Documents/prog/js/gulp-compose/gulpfile.mjs
[12:45:02] Starting 'inSeries'...
[12:45:02] Starting 'a'...
  a started
  a done
[12:45:03] Finished 'a' after 302 ms
[12:45:03] Starting 'b'...
  b started
  b done
[12:45:03] Finished 'b' after 102 ms
[12:45:03] Starting 'c'...
  c started
  c done
[12:45:03] Finished 'c' after 202 ms
[12:45:03] Finished 'inSeries' after 609 ms

Parallel tasks

In the parallel version all three tasks start at the same moment, and they finish in the order of their durations: b, c, then a. The total time is the duration of the slowest task, about 300 ms.

$ npx gulp inParallel
[12:45:03] Using gulpfile ~/Documents/prog/js/gulp-compose/gulpfile.mjs
[12:45:03] Starting 'inParallel'...
[12:45:03] Starting 'a'...
[12:45:03] Starting 'b'...
[12:45:03] Starting 'c'...
  a started
  b started
  c started
  b done
[12:45:03] Finished 'b' after 102 ms
  c done
[12:45:03] Finished 'c' after 202 ms
  a done
[12:45:03] Finished 'a' after 301 ms
[12:45:03] Finished 'inParallel' after 302 ms

Nesting series and parallel

The third task waits for a to finish and then starts b and c together; it takes about 500 ms, which is 300 ms plus the 200 ms of the slower of the two. This is the typical structure of a build: a clean step first, then independent steps such as styles, scripts, and images in parallel, and possibly a final step that needs all of their results.

$ npx gulp mixed
[12:45:04] Using gulpfile ~/Documents/prog/js/gulp-compose/gulpfile.mjs
[12:45:04] Starting 'mixed'...
[12:45:04] Starting 'a'...
  a started
  a done
[12:45:04] Finished 'a' after 302 ms
[12:45:04] Starting 'b'...
[12:45:04] Starting 'c'...
  b started
  c started
  b done
[12:45:04] Finished 'b' after 103 ms
  c done
[12:45:04] Finished 'c' after 202 ms
[12:45:04] Finished 'mixed' after 509 ms

Signalling completion

Gulp must know when a task is finished, otherwise series could not start the next one. A task signals completion in one of several ways: it can call the callback that Gulp passes as the first argument, return a promise, be an async function, return a stream, or return a child process.

completion.mjs
import { src, dest, series } from 'gulp';
import { exec } from 'node:child_process';
import { setTimeout as sleep } from 'node:timers/promises';

export function callback(done) {

    setTimeout(() => {
        console.log('callback finished');
        done();
    }, 100);
}

export function promise() {

    return new Promise(resolve => {
        setTimeout(() => {
            console.log('promise resolved');
            resolve();
        }, 100);
    });
}

export async function asyncFn() {

    await sleep(100);
    console.log('async function finished');
}

export function stream() {

    return src('input.txt').pipe(dest('out'));
}

export function childProcess() {

    return exec('sleep 0.3');
}

export function forgotten(done) {

    console.log('never calls done');
}

export const all = series(callback, promise, asyncFn, stream, childProcess);

The gulpfile defines one task for each way. The callback task calls done; promise returns a promise that is resolved after a timeout; asyncFn is an async function that awaits a timer; stream returns the stream made of src and dest, so the task is finished when all files are written; and childProcess returns the child process started with exec, so the task is finished when the process exits. The all task runs them in series.

The childProcess task runs sleep 0.3, and the log shows that Gulp waited for 300 ms until the process ended.

$ npx gulp --gulpfile completion.mjs all
[12:45:05] Using gulpfile ~/Documents/prog/js/gulp-compose/completion.mjs
[12:45:05] Starting 'all'...
[12:45:05] Starting 'callback'...
callback finished
[12:45:05] Finished 'callback' after 102 ms
[12:45:05] Starting 'promise'...
promise resolved
[12:45:05] Finished 'promise' after 103 ms
[12:45:05] Starting 'asyncFn'...
async function finished
[12:45:05] Finished 'asyncFn' after 102 ms
[12:45:05] Starting 'stream'...
[12:45:05] Finished 'stream' after 20 ms
[12:45:05] Starting 'childProcess'...
[12:45:05] Finished 'childProcess' after 308 ms
[12:45:05] Finished 'all' after 639 ms

Forgetting to signal completion

The forgotten task of the same gulpfile accepts the done callback but never calls it. Gulp cannot know that the task is finished. When the Node.js process has nothing more to do and exits, Gulp reports the tasks that never completed and sets a failure exit status.

$ npx gulp --gulpfile completion.mjs forgotten
[12:45:06] Using gulpfile ~/Documents/prog/js/gulp-compose/completion.mjs
[12:45:06] Starting 'forgotten'...
never calls done
[12:45:06] The following tasks did not complete: forgotten
Did you forget to signal async completion?
$ echo $?
1

Errors in series

A task fails when its callback receives an error, when its promise is rejected, or when an async function throws. In the next gulpfile the broken task passes an error to done.

errors.mjs
import { series, parallel } from 'gulp';
import { setTimeout as sleep } from 'node:timers/promises';

async function ok() {

    await sleep(100);
    console.log('ok finished');
}

async function slow() {

    await sleep(500);
    console.log('slow finished');
}

function broken(done) {

    done(new Error('something went wrong'));
}

function never() {

    console.log('never runs');
    return Promise.resolve();
}

export const stopsAtError = series(ok, broken, never);
export const parallelError = parallel(slow, broken);

In stopsAtError the first task succeeds, the second fails, and the third one is never started: series stops at the first error. Gulp prints the error with its stack trace and marks the composed task as errored too. The exit status of the process is 1, which makes a failing build visible to shell scripts and to CI servers.

$ npx gulp --gulpfile errors.mjs stopsAtError
[12:45:06] Using gulpfile ~/Documents/prog/js/gulp-compose/errors.mjs
[12:45:06] Starting 'stopsAtError'...
[12:45:06] Starting 'ok'...
ok finished
[12:45:06] Finished 'ok' after 102 ms
[12:45:06] Starting 'broken'...
[12:45:06] 'broken' errored after 1.3 ms
[12:45:06] Error: something went wrong
    at broken (file://~/Documents/prog/js/gulp-compose/errors.mjs:18:10)
    at bound (node:domain:433:15)
    at runBound (node:domain:444:12)
    at asyncRunner (~/Documents/prog/js/gulp-compose/node_modules/async-done/index.js:52:18)
    at process.processTicksAndRejections (node:internal/process/task_queues:85:11)
[12:45:06] 'stopsAtError' errored after 107 ms
$ echo $?
1

Errors in parallel

In parallelError the slow task is already running when broken fails. Gulp reports the error immediately and the process exits with status 1 without waiting for slow, which never prints its finishing message. Tasks that run in parallel and have side effects, such as writing files, can therefore be interrupted in the middle of their work when a sibling fails.

$ npx gulp --gulpfile errors.mjs parallelError
[12:45:06] Using gulpfile ~/Documents/prog/js/gulp-compose/errors.mjs
[12:45:06] Starting 'parallelError'...
[12:45:06] Starting 'slow'...
[12:45:06] Starting 'broken'...
[12:45:06] 'broken' errored after 720 μs
[12:45:06] Error: something went wrong
    at broken (file://~/Documents/prog/js/gulp-compose/errors.mjs:18:10)
    at bound (node:domain:433:15)
    at runBound (node:domain:444:12)
    at asyncRunner (~/Documents/prog/js/gulp-compose/node_modules/async-done/index.js:52:18)
    at process.processTicksAndRejections (node:internal/process/task_queues:85:11)
[12:45:06] 'parallelError' errored after 2.48 ms
$ echo $?
1

Source

Gulp series API, Gulp parallel API, Gulp async completion

In this article we have composed Gulp tasks with series and parallel, nested them, learned the ways a task signals completion, and seen how errors stop a build. See also the Gulp watch and Gulp error handling tutorials.

Author

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Gulp tutorials.