Merge pull request #2982 from alphagov/gulp-esm

Migrate Gulp and Node.js build tasks to ESM

config/paths.js

@@ -7,6 +7,7 @@ const rootPath = dirname(__dirname)
  * Config root paths
  */
 const configPaths = {
+  root: rootPath,
   src: join(rootPath, 'src'),
   config: join(rootPath, 'config'),
   node_modules: join(rootPath, 'node_modules'),

docs/contributing/tasks.md

@@ -11,7 +11,7 @@ npm scripts are defined in `package.json`. These trigger a number of Gulp tasks.
 **`npm start` will trigger `gulp dev` that will:**
 - clean the `./public` folder
 - compile JavaScript and Sass, including documentation (`gulp compile`)
-- compile again when `.scss` and `.mjs` files change (`gulp watch`)
+- compile again when `.scss` and `.mjs` files change
 - runs `npm run serve`
 
 **`npm test` will do the following:**
@@ -37,14 +37,14 @@ npm scripts are defined in `package.json`. These trigger a number of Gulp tasks.
 - copy Nunjucks component template/macro files, including JSON configs
 - copy GOV.UK Prototype Kit config files
 - copy JavaScript ESM source files
-- compile JavaScript ESM to CommonJS (`gulp js:compile`)
+- compile JavaScript ESM to CommonJS
 - runs `npm run test:build:package` (which will test the output is correct)
 
 **`npm run build:dist` will do the following:**
 - output files into `./dist`, or another location via the `--destination` flag
 - clean the `./dist` folder
 - compile JavaScript and Sass, including documentation (`gulp compile`)
-- copy fonts and images (`gulp copy:assets`)
+- copy fonts and images
 - append version number from `package/package.json` to compiled JavaScript and CSS files
 - runs `npm run test:build:dist` (which will test the output is correct)
 
@@ -58,24 +58,18 @@ Gulp tasks are defined in `gulpfile.js` and .`/tasks/gulp/` folder.
 This task will:
 - list out all available tasks
 
-**`gulp watch`**
-
-This task will:
-- run `gulp styles` when `.scss` files change
-- run `gulp scripts` when `.mjs` files change
-
 **`gulp styles`**
 
 This task will:
 - check Sass code quality via Stylelint (`npm run lint:scss`)
-- compile Sass to CSS (`gulp scss:compile`) into `./public`, or another location via the `--destination` flag
+- compile Sass to CSS into `./public`, or another location via the `--destination` flag
 - compile Sass documentation into `./sassdoc`
 
 **`gulp scripts`**
 
 This task will:
 - check JavaScript code quality via ESLint (`npm run lint:js`) (using JavaScript Standard Style)
-- compile JavaScript ESM to CommonJS (`gulp js:compile`) into `./public`, or another location via the `--destination` flag
+- compile JavaScript ESM to CommonJS into `./public`, or another location via the `--destination` flag
 - compile JavaScript documentation into `./jsdoc`
 
 **`gulp compile`**

gulpfile.js → gulpfile.mjs

@@ -1,20 +1,16 @@
-const { join } = require('path')
-const gulp = require('gulp')
-const taskListing = require('gulp-task-listing')
-const configPaths = require('./config/paths.js')
-const { destination } = require('./tasks/task-arguments.js')
-const slash = require('slash')
+import gulp from 'gulp'
+import taskListing from 'gulp-task-listing'
 
 // Gulp sub-tasks
-require('./tasks/gulp/compile-assets.js')
-require('./tasks/gulp/copy-to-destination.js')
-require('./tasks/gulp/watch.js')
+import { compileJavaScripts, compileStylesheets } from './tasks/gulp/compile-assets.mjs'
+import { copyAssets, copyFiles } from './tasks/gulp/copy-to-destination.mjs'
+import { watch } from './tasks/gulp/watch.mjs'
 
 // Node tasks
-const { updateDistAssetsVersion } = require('./tasks/asset-version.js')
-const { updatePrototypeKitConfig } = require('./tasks/prototype-kit-config.js')
-const { clean } = require('./tasks/clean.js')
-const { npmScriptTask } = require('./tasks/run.js')
+import { updateDistAssetsVersion } from './tasks/asset-version.mjs'
+import { updatePrototypeKitConfig } from './tasks/prototype-kit-config.mjs'
+import { clean } from './tasks/clean.mjs'
+import { npmScriptTask } from './tasks/run.mjs'
 
 /**
  * Umbrella scripts tasks (for watch)
@@ -23,7 +19,7 @@ const { npmScriptTask } = require('./tasks/run.js')
 gulp.task('scripts', gulp.series(
   npmScriptTask('lint:js', ['--silent']),
   npmScriptTask('build:jsdoc', ['--silent']),
-  'js:compile'
+  compileJavaScripts
 ))
 
 /**
@@ -33,25 +29,16 @@ gulp.task('scripts', gulp.series(
 gulp.task('styles', gulp.series(
   npmScriptTask('lint:scss', ['--silent']),
   npmScriptTask('build:sassdoc', ['--silent']),
-  'scss:compile'
+  compileStylesheets
 ))
 
-/**
- * Copy assets task
- * Copies assets to taskArguments.destination (dist)
- */
-gulp.task('copy:assets', () => {
-  return gulp.src(slash(join(configPaths.assets, '**/*')))
-    .pipe(gulp.dest(slash(join(destination, 'assets'))))
-})
-
 /**
  * Compile task for local & heroku
  * Runs JavaScript and Sass compilation, including documentation
  */
 gulp.task('compile', gulp.series(
-  'js:compile',
-  'scss:compile',
+  compileJavaScripts,
+  compileStylesheets,
   npmScriptTask('build:jsdoc', ['--silent']),
   npmScriptTask('build:sassdoc', ['--silent'])
 ))
@@ -63,7 +50,7 @@ gulp.task('compile', gulp.series(
 gulp.task('dev', gulp.series(
   clean,
   'compile',
-  'watch',
+  watch,
   npmScriptTask('serve', ['--silent', '--workspace', 'app'])
 ))
 
@@ -73,8 +60,8 @@ gulp.task('dev', gulp.series(
  */
 gulp.task('build:package', gulp.series(
   clean,
-  'copy:files',
-  'js:compile',
+  copyFiles,
+  compileJavaScripts,
   updatePrototypeKitConfig
 ))
 
@@ -85,7 +72,7 @@ gulp.task('build:package', gulp.series(
 gulp.task('build:dist', gulp.series(
   clean,
   'compile',
-  'copy:assets',
+  copyAssets,
   updateDistAssetsVersion
 ))
 

package.json

@@ -70,7 +70,7 @@
     "rollup": "0.56.5",
     "sassdoc": "^2.7.4",
     "slash": "^3.0.0",
-    "yargs": "^17.6.2"
+    "yargs-parser": "^21.1.1"
   },
   "devDependencies": {
     "@percy/cli": "^1.14.0",