ZetCode

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.

tasks/clean.mjs
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.

tasks/styles.mjs
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.

tasks/scripts.mjs
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.

gulpfile.mjs
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.

visibility.mjs
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.

cjs-style.mjs
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.

modulejs/package.json
{ "type": "module" }

The package.json file only contains the module type. The gulpfile is next.

modulejs/gulpfile.js
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

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.