migrate build to Gulp 4

- upgrade to Gulp 4
- refactor tasks to use Gulp 4 task system
- switch from map-stream to through2.obj
- switch from fs to fs-extra
- fix Gulp prettier+eslint integration
- rename tasks

.gitlab-ci.yml

@@ -24,7 +24,7 @@ bundle-stable:
   cache: *pull_cache
   script:
   - *run_yarn
-  - node_modules/.bin/gulp pack
+  - node_modules/.bin/gulp bundle
   artifacts:
     paths:
     - build/ui-bundle.zip
@@ -35,7 +35,7 @@ bundle-dev:
   cache: *pull_cache
   script:
   - *run_yarn
-  - node_modules/.bin/gulp pack
+  - node_modules/.bin/gulp bundle
   artifacts:
     expire_in: 1 day # unless marked as keep from job page
     paths:
@@ -47,7 +47,7 @@ pages:
   cache: *pull_cache
   script:
   - *run_yarn
-  - node_modules/.bin/gulp build:preview
+  - node_modules/.bin/gulp preview:build
   # FIXME figure out a way to avoid copying these files to preview site
   - rm -rf public/_/{helpers,layouts,partials}
   artifacts:

.gulp.json

@@ -1,4 +1,4 @@
 {
   "description": "Build tasks for the Antora default UI project",
-  "flags.tasksDepth": 0
+  "flags.tasksDepth": 1
 }

.nvmrc

@@ -1 +1 @@
-8
+10

gulpfile.js

@@ -1,51 +1,114 @@
 'use strict'
 
-const connect = require('gulp-connect')
+const { parallel, series, tree } = require('gulp')
+const camelcase = (name) => name.replace(/[-]./g, (m) => m.substr(1).toUpperCase())
+const exportTasks = require('./tasks/lib/export-tasks')
+const task = require('./tasks/lib/task')
+const taskFns = require('require-directory')(module, './tasks', { recurse: false, rename: camelcase })
 const path = require('path')
-const gulp = require('gulp')
-
-const build = require('./tasks/build')
-const buildPreview = require('./tasks/build-preview')
-const format = require('./tasks/format')
-const lintCss = require('./tasks/lint-css')
-const lintJs = require('./tasks/lint-js')
-const pack = require('./tasks/pack')
-const preview = require('./tasks/preview')
 
 const bundleName = 'ui'
 const buildDir = 'build'
 const previewSiteSrcDir = 'preview-site-src'
 const previewSiteDestDir = 'public'
 const srcDir = 'src'
 const destDir = path.join(previewSiteDestDir, '_')
+const { reload: livereload } = process.env.LIVERELOAD === 'true' ? require('gulp-connect') : {}
 
-const jsFiles = ['gulpfile.js', 'tasks/**/*.js', path.join(srcDir, '{helpers,js}/**/*.js')]
+const cssFileGlobs = path.join(srcDir, 'css/**/*.css')
+const jsFileGlobs = ['gulpfile.js', 'tasks/**/*.js', path.join(srcDir, '{helpers,js}/**/*.js')]
 
-gulp.task('lint:css', () => lintCss(`${srcDir}/css/**/*.css`))
-gulp.task('lint:js', () => lintJs(jsFiles))
-gulp.task('lint', ['lint:css', 'lint:js'])
+const { remove, lintCss, lintJs, format, build, pack, previewPages, previewServe } = taskFns
 
-gulp.task('format', () => format(jsFiles))
+const cleanTask = task({
+  name: 'clean',
+  desc: 'Clean files and folders generated by build',
+  then: remove(['build', 'public']),
+})
 
-gulp.task('build', function () {
-  return build(srcDir, destDir, this.seq.slice(0).some((name) => ~name.indexOf('preview')))
+const lintCssTask = task({
+  name: 'lint:css',
+  desc: 'Lint the CSS source files using stylelint (standard config)',
+  then: lintCss(cssFileGlobs),
 })
 
-gulp.task('build:preview', ['build'], () =>
-  buildPreview(srcDir, destDir, previewSiteSrcDir, previewSiteDestDir, connect.reload)
-)
+const lintJsTask = task({
+  name: 'lint:js',
+  desc: 'Lint the JavaScript source files using eslint (JavaScript Standard Style)',
+  then: lintJs(jsFileGlobs),
+})
+
+const lintTask = task({
+  name: 'lint',
+  desc: 'Lint the CSS and JavaScript source files',
+  then: parallel(lintCssTask, lintJsTask),
+})
+
+const formatTask = task({
+  name: 'format',
+  desc: 'Format the JavaScript source files using prettify (JavaScript Standard Style)',
+  then: format(jsFileGlobs),
+})
+
+const buildTask = task({
+  name: 'build',
+  desc: 'Build and stage the UI assets for bundling',
+  then: build(srcDir, destDir, tree().nodes.some((name) => ~name.indexOf('preview'))),
+})
+
+const bundleBuildTask = task({
+  name: 'bundle:build',
+  desc: 'Lint the source files and build and stage the UI assets for bundling',
+  then: series(cleanTask, lintTask, buildTask),
+})
 
-gulp.task('preview', ['build:preview'], () =>
-  preview(previewSiteDestDir, {
+const bundlePackTask = task({
+  name: 'bundle:pack',
+  desc: 'Create a bundle of the staged UI assets for publishing',
+  then: pack(destDir, buildDir, bundleName),
+})
+
+const bundleTask = task({
+  name: 'bundle',
+  desc: 'Clean, lint, build, and bundle the UI for publishing',
+  then: series(bundleBuildTask, bundlePackTask),
+})
+
+const previewPagesTask = task({
+  name: 'preview:pages',
+  desc: 'Generate pages for the preview by applying the specified layout template',
+  then: previewPages(srcDir, destDir, previewSiteSrcDir, previewSiteDestDir, livereload),
+})
+
+const previewBuildTask = task({
+  name: 'preview:build',
+  desc: 'Process and stage the UI assets and generate pages for the preview',
+  then: parallel(buildTask, previewPagesTask),
+})
+
+const previewServeTask = task({
+  name: 'preview:serve',
+  desc: 'Launch server to preview UI',
+  then: previewServe(previewSiteDestDir, {
     port: 5252,
-    livereload: process.env.LIVERELOAD === 'true',
-    watch: {
-      src: [srcDir, previewSiteSrcDir],
-      onChange: () => gulp.start('build:preview'),
-    },
-  })
-)
+    livereload,
+    watch: { src: [srcDir, previewSiteSrcDir], onChange: previewBuildTask },
+  }),
+})
 
-gulp.task('pack', ['build', 'lint'], () => pack(destDir, buildDir, bundleName))
+const previewTask = task({
+  name: 'preview',
+  desc: 'Generate a preview site and launch a server to view it',
+  then: series(previewBuildTask, previewServeTask),
+})
 
-gulp.task('default', ['build'])
+module.exports = exportTasks(
+  task({ name: 'default', desc: `(${bundleTask.displayName})`, then: series(bundleTask) }),
+  cleanTask,
+  lintTask,
+  formatTask,
+  buildTask,
+  bundleTask,
+  previewTask,
+  previewBuildTask
+)

package.json

@@ -21,28 +21,30 @@
     "eslint-plugin-node": "^8.0.0",
     "eslint-plugin-promise": "^4.0.1",
     "eslint-plugin-standard": "^4.0.0",
-    "gulp": "^3.9.1",
+    "fs-extra": "^7.0.1",
+    "gulp": "^4.0.0",
     "gulp-concat": "^2.6.1",
     "gulp-connect": "^5.2.0",
     "gulp-eslint": "^5.0.0",
-    "gulp-imagemin": "^4.1.0",
+    "gulp-imagemin": "^5.0.3",
     "gulp-postcss": "^8.0.0",
     "gulp-stylelint": "^8.0.0",
     "gulp-uglify": "^3.0.0",
     "gulp-vinyl-zip": "^2.1.0",
     "handlebars": "^4.0.10",
     "highlight.js": "^9.12.0",
     "js-yaml": "^3.10.0",
-    "map-stream": "^0.0.7",
     "merge-stream": "^1.0.1",
     "postcss-calc": "^7.0.1",
     "postcss-custom-properties": "^8.0.9",
     "postcss-import": "^12.0.1",
     "postcss-url": "^8.0.0",
     "prettier-eslint": "^8.2.0",
+    "require-directory": "^2.1.1",
     "require-from-string": "^2.0.1",
     "stylelint": "^9.9.0",
     "stylelint-config-standard": "^18.2.0",
+    "through2": "^3.0.0",
     "typeface-roboto": "^0.0.54",
     "typeface-roboto-mono": "^0.0.54",
     "vinyl-buffer": "^1.0.0",

tasks/build.js

@@ -5,11 +5,10 @@ const browserify = require('browserify')
 const buffer = require('vinyl-buffer')
 const concat = require('gulp-concat')
 const cssnano = require('cssnano')
-const fs = require('fs')
+const fs = require('fs-extra')
 const imagemin = require('gulp-imagemin')
-const map = require('map-stream')
 const merge = require('merge-stream')
-const mkdirp = require('mkdirp')
+const { obj: map } = require('through2')
 const path = require('path')
 const postcss = require('gulp-postcss')
 const postcssCalc = require('postcss-calc')
@@ -19,7 +18,7 @@ const postcssVar = require('postcss-custom-properties')
 const uglify = require('gulp-uglify')
 const vfs = require('vinyl-fs')
 
-module.exports = (src, dest, preview) => {
+module.exports = (src, dest, preview) => () => {
   const opts = { base: src, cwd: src }
   const postcssPlugins = [
     postcssImport(),
@@ -31,13 +30,7 @@ module.exports = (src, dest, preview) => {
           const abspath = path.resolve('node_modules', relpath)
           const basename = path.basename(abspath)
           const destpath = path.join(dest, 'font', basename)
-          if (!fs.existsSync(destpath)) {
-            const dirname = path.dirname(destpath)
-            if (!fs.existsSync(dirname)) {
-              mkdirp.sync(dirname)
-            }
-            fs.copyFileSync(abspath, destpath)
-          }
+          if (!fs.pathExists(destpath)) fs.copy(abspath, destpath)
           return path.join('..', 'font', basename)
         },
       },
@@ -48,34 +41,27 @@ module.exports = (src, dest, preview) => {
     preview ? () => {} : cssnano({ preset: 'default' }),
   ]
 
-  return merge([
+  return merge(
     vfs
       .src('js/+([0-9])-*.js', opts)
       .pipe(uglify())
       .pipe(concat('js/site.js')),
-
     vfs
       .src('js/vendor/*.js', Object.assign({ read: false }, opts))
       .pipe(
         // see https://gulpjs.org/recipes/browserify-multiple-destination.html
-        map((file, next) => {
+        map((file, enc, next) => {
           file.contents = browserify(file.relative, { basedir: src, detectGlobals: false }).bundle()
           next(null, file)
         })
       )
       .pipe(buffer())
       .pipe(uglify()),
-
     vfs.src('css/site.css', opts).pipe(postcss(postcssPlugins)),
-
     vfs.src('font/*.woff*(2)', opts),
-
     vfs.src('img/**/*.{jpg,ico,png,svg}', opts).pipe(imagemin()),
-
     vfs.src('helpers/*.js', opts),
-
     vfs.src('layouts/*.hbs', opts),
-
-    vfs.src('partials/*.hbs', opts),
-  ]).pipe(vfs.dest(dest))
+    vfs.src('partials/*.hbs', opts)
+  ).pipe(vfs.dest(dest))
 }

tasks/format.js

@@ -1,9 +1,9 @@
 'use strict'
 
-const vfs = require('vinyl-fs')
 const prettier = require('./lib/gulp-prettier-eslint')
+const vfs = require('vinyl-fs')
 
-module.exports = (files) =>
+module.exports = (files) => () =>
   vfs
     .src(files)
     .pipe(prettier())