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
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';
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: