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
 ))
 

tasks/asset-version.js → tasks/asset-version.mjs

@@ -1,14 +1,14 @@
-const { rename, writeFile } = require('fs/promises')
-const { basename, join } = require('path')
-const { EOL } = require('os')
+import { readFile, rename, writeFile } from 'fs/promises'
+import { basename, join } from 'path'
+import { EOL } from 'os'
 
-const configPaths = require('../config/paths.js')
-const { destination, isDist } = require('./task-arguments.js')
+import configPaths from '../config/paths.js'
+import { destination, isDist } from './task-arguments.mjs'
 
 // Update assets' version numbers
 // Uses the version number from `package/package.json` and writes it to various places
-async function updateDistAssetsVersion () {
-  const pkg = require(join(configPaths.package, 'package.json'))
+export async function updateDistAssetsVersion () {
+  const pkg = JSON.parse(await readFile(join(configPaths.package, 'package.json'), 'utf8'))
 
   if (!isDist) {
     throw new Error('Asset versions can only be applied to ./dist')
@@ -38,7 +38,3 @@ async function updateDistAssetsVersion () {
 }
 
 updateDistAssetsVersion.displayName = 'update-dist-assets-version'
-
-module.exports = {
-  updateDistAssetsVersion
-}

tasks/clean.js → tasks/clean.mjs

@@ -1,11 +1,12 @@
-const { basename, join } = require('path')
-const del = require('del')
-const slash = require('slash')
+import { basename, join } from 'path'
+import del from 'del'
+import slash from 'slash'
+
+import { destination } from './task-arguments.mjs'
 
-const { destination } = require('./task-arguments.js')
 const cleanPath = slash(destination)
 
-function paths () {
+export function paths (cleanPath) {
   const param = [slash(join(cleanPath, '**/*'))]
 
   // Preserve package files
@@ -21,13 +22,8 @@ function paths () {
   return param
 }
 
-function clean () {
-  return del(paths())
+export function clean () {
+  return del(paths(cleanPath))
 }
 
 clean.displayName = `clean:${basename(cleanPath)}`
-
-module.exports = {
-  paths,
-  clean
-}

tasks/clean.unit.test.js → tasks/clean.unit.test.mjs

@@ -1,8 +1,6 @@
-describe('Clean task', () => {
-  beforeEach(() => {
-    jest.resetModules()
-  })
+import { paths } from './clean.mjs'
 
+describe('Clean task', () => {
   it.each(
     [
       {
@@ -28,9 +26,7 @@ describe('Clean task', () => {
         paths: ['custom/location/here/**/*']
       }
     ]
-  )('cleans destination "$destination"', async ({ destination: mockDestination, paths }) => {
-    jest.mock('./task-arguments.js', () => ({ destination: mockDestination }))
-    const clean = await import('./clean.js')
-    expect(clean.paths()).toEqual(paths)
+  )('cleans destination "$destination"', async ({ destination, paths: pathsExpected }) => {
+    expect(paths(destination)).toEqual(pathsExpected)
   })
 })

tasks/gulp/__tests__/after-build-dist.test.js → tasks/gulp/__tests__/after-build-dist.test.mjs

@@ -1,8 +1,8 @@
-const { readFile } = require('fs/promises')
-const { join } = require('path')
+import { readFile } from 'fs/promises'
+import { join } from 'path'
 
-const configPaths = require('../../../config/paths.js')
-const { getListing } = require('../../../lib/file-helper')
+import configPaths from '../../../config/paths.js'
+import { getListing } from '../../../lib/file-helper.js'
 
 describe('dist/', () => {
   const pkg = require(join(configPaths.package, 'package.json'))

tasks/gulp/__tests__/after-build-package.test.js → tasks/gulp/__tests__/after-build-package.test.mjs

@@ -1,11 +1,11 @@
-const { readFile } = require('fs/promises')
-const { join } = require('path')
+import { readFile } from 'fs/promises'
+import { join } from 'path'
 
-const configPaths = require('../../../config/paths.js')
-const { filterPath, getDirectories, getListing, mapPathTo } = require('../../../lib/file-helper')
-const { componentNameToJavaScriptClassName, componentNameToJavaScriptModuleName } = require('../../../lib/helper-functions')
+import configPaths from '../../../config/paths.js'
+import { filterPath, getDirectories, getListing, mapPathTo } from '../../../lib/file-helper.js'
+import { componentNameToJavaScriptClassName, componentNameToJavaScriptModuleName } from '../../../lib/helper-functions.js'
 
-const { renderSass } = require('../../../lib/jest-helpers')
+import { renderSass } from '../../../lib/jest-helpers.js'
 
 describe('package/', () => {
   let listingSource