ZetCode

Gulp 5

last modified November 15, 2026

In this article we look at what changed in Gulp 5 compared to Gulp 4. The task API is almost identical, so most gulpfiles keep working. A few details changed under the hood, and one of them, the way files are read, can silently corrupt images. We test each change and finish with a migration checklist.

Gulp 5

Gulp is a streaming task runner for Node.js. Gulp 5 was released in March 2024, more than five years after Gulp 4. The functions that gulpfiles use every day, src, dest, series, parallel, and watch, have the same names and the same signatures. See the Gulp getting started tutorial for an introduction.

The changes are in the dependencies. Gulp 5 reads and writes files with vinyl-fs 4, which is built on streamx, a stream library that replaces the Node.js streams used by vinyl-fs 3. The command line tool is now gulp-cli 3.

Versions

We create a project and install Gulp. The --version option prints the version of the command line interface and of the local Gulp package. The npm ls command shows that vinyl-fs 4 and its helpers, such as glob-stream, depend on streamx.

The package.json of Gulp 5.0.1 declares support for Node.js 10.13 and later, but plugins can require a newer version: the current del package, for instance, is distributed as an ES module only.

$ mkdir gulp-five
$ cd gulp-five
$ npm init -y
$ npm i -D gulp
$ npx gulp --version
CLI version: 3.1.0
Local version: 5.0.1
$ npm ls streamx vinyl-fs glob-stream
gulp-five@1.0.0 ~/Documents/prog/js/gulp-five
└─┬ gulp@5.0.1
  └─┬ vinyl-fs@4.0.2
    ├─┬ fs-mkdirp-stream@2.0.1
    │ └── streamx@2.28.1 deduped
    ├─┬ glob-stream@8.0.4
    │ └── streamx@2.28.1 deduped
    ├─┬ stream-composer@1.0.2
    │ └── streamx@2.28.1 deduped
    ├── streamx@2.28.1
    ├─┬ to-through@3.0.0
    │ └── streamx@2.28.1 deduped
    ├─┬ vinyl-sourcemap@2.0.0
    │ └── streamx@2.28.1 deduped
    └─┬ vinyl@3.0.1
      └─┬ teex@1.0.1
        └── streamx@2.28.1 deduped

Binary files and encoding

The most dangerous change concerns the encoding option of src. Gulp 5 decodes the content of every file as UTF-8 text by default, and encodes it again when the file is written. For text files in UTF-8 this is invisible, but a binary file, such as an image, does not survive the round trip: bytes that are not valid UTF-8 are replaced with the Unicode replacement character.

The example copies a PNG image, a UTF-8 text file, and a text file in Latin-1 encoding into two directories. The first task uses the defaults, the second task sets encoding to false, which makes Gulp read the raw bytes.

gulpfile.mjs
import { src, dest } from 'gulp';

export function copy() {

    return src('src/*.{png,txt}')
        .pipe(dest('dist'));
}

export function copyBinary() {

    return src('src/*.{png,txt}', { encoding: false })
        .pipe(dest('dist-ok'));
}

The two tasks are identical except for the options of src.

return src('src/*.{png,txt}', { encoding: false })
    .pipe(dest('dist-ok'));

With encoding: false the file contents are passed through untouched. Nothing is reported when the default is used: both tasks finish successfully. Only the checksums tell the difference. The copy made with the default encoding has a different checksum for the PNG image and for the Latin-1 file, while the UTF-8 file is identical in both copies. The hex dump shows that the byte e9 of the Latin-1 letter é was replaced with the three bytes ef bf bd of the replacement character.

$ npx gulp copy
[12:44:58] Using gulpfile ~/Documents/prog/js/gulp-five/gulpfile.mjs
[12:44:58] Starting 'copy'...
[12:44:58] Finished 'copy' after 13 ms
$ npx gulp copyBinary
[12:44:58] Using gulpfile ~/Documents/prog/js/gulp-five/gulpfile.mjs
[12:44:58] Starting 'copyBinary'...
[12:44:58] Finished 'copyBinary' after 13 ms
$ md5sum src/*.{png,txt} dist/* dist-ok/*
fd4b795489b2ea455d481365c7f8d949  src/logo.png
70941b2a2a6a84556c97b2a3220ef4be  src/latin1.txt
6e99834b7c3e3fd53529a5489725d7e8  src/utf8.txt
68d268dab6a93236da26ea6e5d6ca2ba  dist/latin1.txt
576c8d01744c981218776334f452d0de  dist/logo.png
6e99834b7c3e3fd53529a5489725d7e8  dist/utf8.txt
70941b2a2a6a84556c97b2a3220ef4be  dist-ok/latin1.txt
fd4b795489b2ea455d481365c7f8d949  dist-ok/logo.png
6e99834b7c3e3fd53529a5489725d7e8  dist-ok/utf8.txt
$ xxd dist/latin1.txt
00000000: 6361 66ef bfbd 0a                        caf....

Streams and errors

Because the streams come from streamx, plugins behave a little differently than under Gulp 4. The most visible difference concerns errors. The pipe method does not forward an error from one stream to the next, so when a plugin in the middle of a chain fails, Gulp may report success, or report that the task never completed. The Gulp error handling tutorial shows how to make such failures visible with pipeline from the Node.js stream/promises module. The Gulp Terser tutorial shows a real case with gulp-terser.

Plugins built on the Node.js Transform class still work, because pipe accepts any stream. Plugins that are no longer maintained may depend on old libraries; run npm audit after the upgrade and replace such plugins, as we did with gulp-minify, which is superseded by gulp-terser.

CommonJS gulpfiles still work

A gulpfile written for Gulp 4 does not have to be rewritten. This one uses require, the string-based gulp.task function, and gulp.series.

legacy/gulpfile.js
const gulp = require('gulp');
const terser = require('gulp-terser');

gulp.task('scripts', function () {

    return gulp.src('src/*.js')
        .pipe(terser())
        .pipe(gulp.dest('dist'));
});

gulp.task('default', gulp.series('scripts'));

Gulp 5 runs the file unchanged. We point the command line to the file with --gulpfile and keep the working directory with --cwd. The task registry of Gulp 4, with gulp.task, is still available, although the recommended way of defining tasks is to export functions.

$ npx gulp --gulpfile legacy/gulpfile.js --cwd .
[12:44:59] Using gulpfile ~/Documents/prog/js/gulp-five/legacy/gulpfile.js
[12:44:59] Starting 'default'...
[12:44:59] Starting 'scripts'...
[12:44:59] Finished 'scripts' after 28 ms
[12:44:59] Finished 'default' after 30 ms
$ cat dist/hello.js
const greet=e=>`Hello ${e}`;console.log(greet("Gulp"));

The same gulpfile as an ES module

The modern version of the same gulpfile is an ES module. The tasks are exported functions and the default export is the default task.

modern/gulpfile.mjs
import { src, dest, series } from 'gulp';
import terser from 'gulp-terser';

export function scripts() {

    return src('src/*.js')
        .pipe(terser())
        .pipe(dest('dist'));
}

export default series(scripts);

The .mjs extension tells Node.js to treat the file as an ES module, so import and export work. The ESM gulpfile tutorial covers this in detail. The result is the same minified file as before.

$ npx gulp --gulpfile modern/gulpfile.mjs --cwd .
[12:44:59] Using gulpfile ~/Documents/prog/js/gulp-five/modern/gulpfile.mjs
[12:44:59] Starting 'default'...
[12:44:59] Starting 'scripts'...
[12:44:59] Finished 'scripts' after 31 ms
[12:44:59] Finished 'default' after 33 ms
$ cat dist/hello.js
const greet=e=>`Hello ${e}`;console.log(greet("Gulp"));

Migrating a gulpfile

Moving a project from Gulp 4 to Gulp 5 takes a few steps.

Most gulpfiles need nothing more than the second step.

Source

Gulp 5.0.0 release notes, Gulp src API, vinyl-fs on GitHub, streamx on GitHub

In this article we have looked at the differences between Gulp 4 and Gulp 5: the new stream library, UTF-8 decoding of file contents and the encoding option, CommonJS and ES module gulpfiles, and the steps of a migration. See also the ESM gulpfile and Gulp src and dest 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.