build(dev workflow improvements) (#602)

* build(eleventy): change 11ty config to allow reloading of components in development

By default the nunjucks environment loads components from the ./package directory.  This means
changes to a component won't be loaded in development.  This PR updates the nunjucks environment to
load from the ./src directoy when the ENV var is det to dev

* build(husky): update husky config to prevent double prompt

When aliasing git commit to git cz alongside the pre-commit-hook would cause the interactive prompt
to run twice.  This Pr updates the pre-commit-hook to only run if a commit message has not already
been provided

* build(eleventy): amend 11ty config to allow reloading components from src directory

Documentation examples by default load components from the built /package directory.  This PR adds
the ability to pass an ENV='dev' flag to the eleventy command to enable loading of components direct
from the /src directory. This also adds a gulp watcher to rebuild the package css and js files
during development.

This needs further work! We have three file watchers running in parallel to build/rebuild the
docs site in development. (11ty, webpack, and gulp) It would be good if we could use just one!

* build(remove webpack): remove webpack and use 11ty and gulp only

We were using 3 build tools in combination: 11ty, webpack, and gulp.  This was overly complex, a bit
unnecessary, and was slow.  Webpack was only really being used to copy files - which can very easily
eb done by gulp. This PR removes the webpack dependency and pipeline in favour of gulp. the pipeline
is now setup such that any changes in dev for a component will trigger a rebuild of the assets and
the 11ty docs making working on a component much faster as changes to both nunjucks templates and
js/scss files trigger a reload in the browser.

* build(gulp): improve dev workflow pipeline with gulp

Move more config from 11ty to gulp in order to work better.  11ty now handles anything nunjucks related, and gulp handles anything asset related.  11ty is then set to watch the files output from the gulp build pipeline in order to trigger a reload.

.eleventy.js

@@ -9,14 +9,28 @@ const nunjucks = require("nunjucks");
 const path = require("path");
 const { execSync } = require("child_process");
 const releasePackage = require('./package/package.json');
+const sass = require("sass");
+const esbuild = require('esbuild');
 
 module.exports = function (eleventyConfig) {
-  const nunjucksEnv = nunjucks.configure([
+  /*
+   * If the node env is 'dev' then we include the src dir allowing components
+   * under development to be watched and loaded
+   */
+  const templatePaths = process.env.ENV === 'dev' ? [
     ".",
+    "src",
     "docs/_includes/",
     "node_modules/govuk-frontend/dist/",
     "node_modules/@ministryofjustice/frontend/",
-  ]);
+  ] : [
+    ".",
+    "docs/_includes/",
+    "node_modules/govuk-frontend/dist/",
+    "node_modules/@ministryofjustice/frontend/",
+  ];
+
+  const nunjucksEnv = nunjucks.configure(templatePaths);
 
   Object.entries({
     ...eleventyConfig.nunjucksFilters,
@@ -147,4 +161,29 @@ module.exports = function (eleventyConfig) {
   eleventyConfig.addFilter("getScriptPath", function (inputPath) {
     return inputPath.split("/").slice(1, -1).join("/") + "/script.js";
   });
+
+  // Rebuild when a change is made to a component template file
+  eleventyConfig.addWatchTarget("src/moj/components/**/*.njk");
+
+  // Copy the docs images to the public assets dir
+  eleventyConfig.addPassthroughCopy( { "docs/assets/images/": "assets/images/"});
+  eleventyConfig.setServerPassthroughCopyBehavior('copy')
+
+  // Give gulp a little time..
+  eleventyConfig.setWatchThrottleWaitTime(100);
+
+  eleventyConfig.setServerOptions({
+    liveReload: true,
+    domDiff: false,
+    port: 8080,
+    // Reload once assets have been rebuilt by gulp
+    watch: [
+      'public/assets/stylesheets/application.css',
+      'public/assets/javascript/all.js'
+    ],
+    // Show local network IP addresses for device testing
+    showAllHosts: true,
+    // Show the dev server version number on the command line
+    showVersion: true,
+  });
 };

.husky/prepare-commit-msg

@@ -1,4 +1,7 @@
 #!/usr/bin/env sh
 . "$(dirname -- "$0")/_/husky.sh"
 
-exec < /dev/tty && npx cz --hook || true
+# Only run commitizen if no commit message was already provided.
+if [ -z "${2-}" ]; then
+    exec < /dev/tty && npx cz --hook || true
+fi

assets/all.js → docs/assets/javascript/all.js

@@ -1,9 +1,9 @@
 import { initAll as initGOVUKFrontend } from "govuk-frontend/dist/govuk/all.mjs";
-import MOJFrontend from "../package/moj/all.js";
+import MOJFrontend from "../../../package/moj/all.js";
 
-import Cookies from "./javascript/cookies";
-import Copy from "./javascript/copy";
-import Tabs from "./javascript/tabs";
+import Cookies from "./cookies";
+import Copy from "./copy";
+import Tabs from "./tabs";
 
 initGOVUKFrontend();
 MOJFrontend.initAll();

gulp/build-copy-files.js

@@ -3,9 +3,10 @@ const gulp = require('gulp');
 gulp.task('build:copy-files', () => {
   return gulp.src([
       'src/**/*',
+      '!src/moj/all.js', // this will get built
       'README.md',
       '!**/.DS_Store',
       '!src/README.md'
     ])
     .pipe(gulp.dest('package/'));
-});
+});

gulp/docs.js

@@ -0,0 +1,63 @@
+const gulp = require("gulp");
+const sass = require("gulp-sass")(require("sass"));
+const {createGulpEsbuild} = require("gulp-esbuild")
+const esbuild = createGulpEsbuild({
+	incremental: false, // enables the esbuild"s incremental build
+	piping: true,      // enables piping
+})
+
+// Copy all the govuk-frontend assets across
+gulp.task(
+  "docs:copy-dependencies", () => {
+    return gulp.src([
+      "node_modules/govuk-frontend/dist/govuk/assets/**/*",
+      "src/moj/assets/**/*"
+    ])
+    .pipe(gulp.dest("public/assets"))
+  }
+);
+
+// Copy package vendor files across
+gulp.task(
+  "docs:copy-vendor", () => {
+    return gulp.src([
+      "src/moj/vendor/**/*.js"
+    ])
+    .pipe(gulp.dest("public/assets/javascript"))
+  }
+);
+
+// Ordering is important here! - Docs > Package > GovUK frontend
+gulp.task(
+  "docs:copy-files", gulp.series(
+    "docs:copy-dependencies",
+    "docs:copy-vendor",
+  )
+);
+
+// Compile the docs site stylesheet
+gulp.task(
+  "docs:styles", () => {
+    return gulp
+      .src("docs/assets/stylesheets/application.scss")
+      .pipe(sass())
+      .pipe(gulp.dest("public/assets/stylesheets"));
+  }
+);
+
+// Bundle the docs site javascript
+gulp.task(
+  "docs:scripts", () => {
+    return gulp
+      .src("docs/assets/javascript/all.js")
+      .pipe(esbuild({
+          outfile: "all.js",
+          target: "es6",
+          bundle: true,
+      }))
+      .pipe(gulp.dest("public/assets/javascript"))
+  }
+);
+
+
+

gulpfile.js

@@ -3,9 +3,9 @@ const requireDir = require("require-dir");
 
 requireDir("./gulp");
 
+// Copy ./src directory and build scripts into ./package
 gulp.task(
-  "build:package",
-  gulp.series(
+  "build:package", gulp.series(
     "build:clean",
     "build:copy-files",
     "build:javascript",
@@ -14,13 +14,58 @@ gulp.task(
   )
 );
 
+// Build the dist bundle of the package
 gulp.task(
-  "build:dist",
-  gulp.series(
+  "build:dist", gulp.series(
     "dist:clean",
     "dist:javascript",
     "dist:css",
     "dist:assets",
-    "dist:zip"
+    "dist:zip",
   )
 );
+
+// Initial build of the docs site to ./public
+gulp.task(
+  "build:docs", gulp.series(
+    "docs:copy-files",
+    "build:package",
+    gulp.parallel("docs:styles", "docs:scripts"),
+  )
+);
+
+// Watch the docs site sass and all component sass files and recompile
+gulp.task(
+  "watch:styles",  () => {
+    gulp.watch(
+      ["docs/assets/**.*.scss", "src/moj/components/**/*.scss"],
+      gulp.series(["docs:styles"]),
+    )
+  }
+);
+
+// Watch all the component js files and build the package
+gulp.task(
+  "watch:package-js", () => {
+    gulp.watch(
+      ["src/moj/components/**/*.js"],
+      gulp.series("build:javascript")
+    )
+  }
+);
+
+// Watch the docs js files and the bundled package js and rebuild
+gulp.task(
+  "watch:docs-js", () => {
+    gulp.watch(
+      ["docs/assets/**/*.js", "package/moj/all.js"],
+      gulp.series(["docs:scripts"]),
+    )
+  }
+);
+
+// Watch all the files in dev
+gulp.task(
+  "watch:dev",
+  gulp.parallel("watch:styles", "watch:package-js", "watch:docs-js"),
+);