This gist is modified from a gist by Alexandre Zanni, which can be found at: https://gist.github.com/noraj/007a943dc781dc8dd3198a29205bae04
del v7.0.0 moved to pure ESM (no dual support), which forced me to move my gulpfile to ESM to be able to continue to use del.
The author sindresorhus maintains a lot of npm packages and does not want to provides an upgrade guide for each package so he provided a generic guide. But this guide is a bit vague because it's generic and not helping for gulp, hence this guide.
- Rename
gulpfile.jstogulpfile.mjs
The first step is easy, since v2.3.0 (#214) gulp-cli supports ESM. So we can just rename gulpfile.js to gulpfile.mjs.
This avoid having to add "type": "module" to package.json which makes no sense if you are not providing a package but rather just use gulp to automate deployment tasks for example.
- Change gulp import
Gulp doesn't support all module.exports as named exports yet (#2634) but CJS modules can always be imported via the default export:
-const { series, parallel, src, dest, task } = require('gulp');
+import gulp from 'gulp';
+const { series, parallel, src, dest, task } = gulp;- Change gulp plugins import
Most gulp plugin can be changed easily, eg.
-const pug = require('gulp-pug');
+import pug from 'gulp-pug';
-const replace = require('gulp-replace');
+import replace from 'gulp-replace';- Change gulp-sass
Edit: The original gulp-sass code from the original gist that this gist is based on is not required if you use gulp-dart-sass. Use the standard modified ES Module import statement if using gulp-dart-sass.
import {default as sass} from 'gulp-dart-sass';
The following is from the original gist and is not required if using gulp-dart-sass
gulp-sass is a tricky one but hopefuly the project README explains how to do it.
-const sass = require('gulp-sass')(require('sass'));
+import dartSass from 'sass';
+import gulpSass from 'gulp-sass';
+const sass = gulpSass(dartSass);- Change del
I could have done import { deleteAsync as del } from 'del'; to keep this named del but it's advised to keep descriptive names to avoid namespace conflicts so I moved it to deleteAsync as recommended and renamed all call to del to deleteAsync in gulpfile.mjs.
-const del = require('del');
+import { deleteAsync } from 'del';- Use
node:URL scheme
It's recommanded to use node: URL scheme to import Node.js builtin modules so they are referenced by valid absolute URL strings.
-const { exec } = require('child_process');
+import { exec } from 'node:child_process';
- Change Task Exports
-exports.default = series(parallel(sassTask, jsTask), watchTask);
+const defaultTask = series(parallel(sassTask, jsTask), watchTask);
+export default defaultTask;
-exports.build = series(setBuildState, cleanTask, parallel(sassBuildTask, jsBuildTask, jQueryTask), parallel(imagesTask, mediaTask, fontsTask), htmlTask, cacheBustTask);
+const buildTask = series(setBuildState, cleanTask, parallel(sassBuildTask, jsBuildTask, jQueryTask), parallel(imagesTask, mediaTask, fontsTask), htmlTask, cacheBustTask);
+export { buildTask as build};Example of migration for my project:
- Main migration: https://gitlab.com/rawsec/rawsec-cybersecurity-list/-/commit/1d0f6b48792f7ced811e16d245a20724b34ac0d3
node:URL scheme: https://gitlab.com/rawsec/rawsec-cybersecurity-list/-/commit/89e758c91474c426f9281c48ff1218d822f6ca48- descriptive import names: https://gitlab.com/rawsec/rawsec-cybersecurity-list/-/commit/ca4ae66bb104a780388024edfbf43af1fa941210
- ESM = ES Modules = ECMAScript Modules
- CSJ = CommonJS
| System | Extension |
|---|---|
| ESM | .mjs |
| CJS | .cjs |
| Default module system | .js |
More about ESM in: