ESM gulpfile
last modified November 15, 2026
In this article we write gulpfiles as ES modules. We use
import and export, turn exported functions into
tasks, split a large gulpfile into several modules, and look at the errors
that appear when CommonJS and ES module syntax are mixed.
Gulp and ES modules
A gulpfile is the JavaScript file that defines the tasks. Older
gulpfiles are CommonJS modules: they load Gulp with require and
publish tasks with exports. Modern Node.js code uses ES modules,
and a growing number of Gulp plugins and helpers, such as del,
are distributed only in that format. A CommonJS gulpfile cannot
require them, so an ES module gulpfile is the better choice for
new projects.
Gulp supports both formats. It loads the gulpfile with Node.js, so the usual
Node.js rules apply: the file name and the type field of the
nearest package.json decide. A file named
gulpfile.mjs is always an ES module, and gulpfile.js
is an ES module only when package.json contains
"type": "module". In this article we use the
.mjs extension because it works without any extra
configuration. See also Gulp 5.
Installing the project
The example project minifies one JavaScript file and one CSS file. We
install Gulp, gulp-terser, gulp-clean-css, and
del, which removes the build directory. The task modules go into
the tasks directory.
$ mkdir gulp-esm $ cd gulp-esm $ npm init -y $ npm i -D gulp gulp-terser gulp-clean-css del $ mkdir -p src/js src/css tasks
Task modules
Each task lives in its own module and is exported by name. The
clean task deletes the output directory.
import { deleteAsync } from 'del';
export function clean() {
return deleteAsync(['dist']);
}
The deleteAsync function of the del package returns
a promise, and Gulp waits for it to settle.
import { src, dest } from 'gulp';
import cleanCSS from 'gulp-clean-css';
export function styles() {
return src('src/css/*.css')
.pipe(cleanCSS())
.pipe(dest('dist/css'));
}
The styles task minifies all CSS files with
gulp-clean-css.
import { src, dest } from 'gulp';
import terser from 'gulp-terser';
export function scripts() {
return src('src/js/*.js')
.pipe(terser())
.pipe(dest('dist/js'));
}
The scripts task minifies the JavaScript files with
gulp-terser. The modules import src and
dest from gulp themselves, so they do not depend on
the gulpfile.
The gulpfile
The gulpfile imports the task modules, re-exports the individual tasks,
and combines them into a build task.
import { series, parallel } from 'gulp';
import { clean } from './tasks/clean.mjs';
import { styles } from './tasks/styles.mjs';
import { scripts } from './tasks/scripts.mjs';
export { clean, styles, scripts };
export const build = series(clean, parallel(styles, scripts));
export default build;
Only series and parallel come from Gulp itself; the individual tasks come from the modules.
export { clean, styles, scripts };
export const build = series(clean, parallel(styles, scripts));
export default build;
Every exported function or composed task becomes a public task, available
from the command line. The export { ... } line republishes the
imported functions without redefining them. build removes the old
output first and then builds styles and scripts in parallel. The default export
is the task that runs when no task name is given.
Running npx gulp executes the default task. The order of
styles and scripts may differ from run to run,
because they run in parallel.
$ npx gulp [12:44:59] Using gulpfile ~/Documents/prog/js/gulp-esm/gulpfile.mjs [12:44:59] Starting 'default'... [12:44:59] Starting 'clean'... [12:44:59] Finished 'clean' after 15 ms [12:44:59] Starting 'styles'... [12:44:59] Starting 'scripts'... [12:44:59] Finished 'styles' after 64 ms [12:44:59] Finished 'scripts' after 66 ms [12:44:59] Finished 'default' after 83 ms $ find dist -type f | sort dist/css/site.css dist/js/app.js
Listing the tasks
The --tasks option prints the tasks of the gulpfile as a tree,
and --tasks-simple prints only their names. The tree also shows
how composed tasks are built from series and parallel parts. Note that
default and build have the same structure, because
they are the same function.
$ npx gulp --tasks Tasks for ~/Documents/prog/js/gulp-esm/gulpfile.mjs ├─┬ build │ └─┬ <series> │ ├── clean │ └─┬ <parallel> │ ├── styles │ └── scripts ├── clean ├─┬ default │ └─┬ <series> │ ├── clean │ └─┬ <parallel> │ ├── styles │ └── scripts ├── scripts └── styles $ npx gulp --tasks-simple build clean default scripts styles
Public and private tasks
In an ES module gulpfile only the exported functions are public. A function
that is not exported can still be used inside series or
parallel, but it cannot be run from the command line and is not
listed by --tasks. This is how private helper tasks are defined.
A function can also carry a description property, which the task
listing shows.
import { series } from 'gulp';
function prepare(done) {
console.log('preparing');
done();
}
export function build(done) {
console.log('building');
done();
}
build.description = 'Builds the project';
export default series(prepare, build);
Here prepare is private, build is public and has a
description, and the default task runs both. Asking for the private task by
name fails with the message that the task is not defined.
$ npx gulp --gulpfile visibility.mjs --tasks
Tasks for ~/Documents/prog/js/gulp-esm/visibility.mjs
├── build Builds the project
└─┬ default
└─┬ <series>
├── prepare
└── build
$ npx gulp --gulpfile visibility.mjs
[12:45:01] Using gulpfile ~/Documents/prog/js/gulp-esm/visibility.mjs
[12:45:01] Starting 'default'...
[12:45:01] Starting 'prepare'...
preparing
[12:45:01] Finished 'prepare' after 532 μs
[12:45:01] Starting 'build'...
building
[12:45:01] Finished 'build' after 416 μs
[12:45:01] Finished 'default' after 2.42 ms
$ npx gulp --gulpfile visibility.mjs prepare
[12:45:01] Using gulpfile ~/Documents/prog/js/gulp-esm/visibility.mjs
[12:45:01] Task never defined: prepare
To list available tasks, try running: gulp --tasks
Mixing require and import
The most common mistake when upgrading an old gulpfile is to keep
require in a file that is an ES module. In an ES module there is
no require function; the same applies to
module.exports and __dirname.
const gulp = require('gulp');
export function hello(done) {
console.log('hello');
done();
}
The gulpfile above has the right extension but the old syntax. Node.js
refuses to load it, and Gulp prints the error. The fix is to replace
require with import. The ES module replacements for
__dirname and __filename are
import.meta.dirname and import.meta.filename.
$ npx gulp --gulpfile cjs-style.mjs hello 2>&1 | head -3
ReferenceError: require is not defined in ES module scope, you can use import instead
at file://~/Documents/prog/js/gulp-esm/cjs-style.mjs:1:14
at ModuleJobSync.runSync (node:internal/modules/esm/module_job:458:37)
Using gulpfile.js as an ES module
If we prefer the traditional gulpfile.js name, we add
"type": "module" to package.json. The setting applies
to every .js file in the project, so it must suit all of them. The
example keeps the experiment in a subdirectory with its own
package.json. It also shows that the default export of
gulp gives access to the whole API, which is an alternative to
named imports.
{ "type": "module" }
The package.json file only contains the module type. The gulpfile is next.
import gulp from 'gulp';
export function where(done) {
console.log(import.meta.dirname);
console.log(typeof gulp.series);
done();
}
The --cwd option makes the subdirectory the working directory,
and Gulp reports the change. The task prints the directory of the gulpfile
with import.meta.dirname and shows that
gulp.series is a function.
$ npx gulp --gulpfile modulejs/gulpfile.js --cwd modulejs where [12:45:02] Working directory changed to ~/Documents/prog/js/gulp-esm/modulejs [12:45:02] Using gulpfile ~/Documents/prog/js/gulp-esm/modulejs/gulpfile.js [12:45:02] Starting 'where'... ~/Documents/prog/js/gulp-esm/modulejs function [12:45:02] Finished 'where' after 1.13 ms
Source
Gulp JavaScript and Gulpfiles, Node.js ECMAScript modules, Gulp series API
In this article we have written Gulp 5 gulpfiles as ES modules: exported
functions became tasks, a gulpfile was split into task modules, and private
tasks, descriptions, and the typical require error were covered.
See also the Gulp series and parallel and
Gulp 5 tutorials.
Author
List all Gulp tutorials.