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.
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.
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.
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
List all Gulp tutorials.