Implement cache busting with an assets-manifest and hashed js/css file names

[colegoldsmith]

How does this work?

I've implemented gulp-hash into the gulp build pipeline to do two things for all the js and css files.

• After gulp minifies and bundles the css and js files it appends a random hash to the file name like js/site-c322e02a.js or css/site-d4c953ff.css
• It creates an assets-manifest.json file that maps the normal file name to the new hashed versions. It looks like this

  {
  "js/site.js": "js/site-c322e02a.js",
  "js/vendor/highlight.js": "js/vendor/highlight-8d0d2281.js",
  "js/vendor/tabs.js": "js/vendor/tabs-51da7113.js",
  "js/vendor/zooming.js": "js/vendor/zooming-51d9340d.js",
  "css/site.css": "css/site-d4c953ff.css"
  } 

To make use of these gulp-hash additions I've implemented a new handlebars helper that allows the templates to read that assets-manifest.json file and insert the new hashed file name using the unhashed file name as the lookup key. For example the link for the main site.css file

<link rel="stylesheet" href="{{{uiRootPath}}}/{{{assets-manifest 'css/site.css' }}}">

// When Antora builds the html files that handlebars template turns into this

<link rel="stylesheet" href="_/css/site-9a3dd424.css">

End Result

Any time we release a new UI bundle the js/css files will get a new hash and thus a new file name. This forces all client browsers to download the new version of the file instead of using the cached version

[mlr]

UI bundle preview build failure! :x:

[02:09:39] Using gulpfile ~/work/docs-ui/docs-ui/gulpfile.js [02:09:39] Starting 'lint'... [02:09:40] /home/runner/work/docs-ui/docs-ui/gulpfile.js 3:9 error 'parallel' is assigned a value but never used no-unused-vars /home/runner/work/docs-ui/docs-ui/gulp.d/tasks/build-preview-pages.js 22:1 warning This line has a length of 127. Maximum allowed is 120 max-len ✖ 2 problems (1 error, 1 warning) [02:09:40] 'lint' errored after 1.13 s [02:09:40] ESLintError in plugin "gulp-eslint" Message: Failed with 1 error

[mlr]

Antora site build failure! :x:

[02:10:15] Using gulpfile ~/work/datastax-docs-site/datastax-docs-site/ui-bundle-preview/gulpfile.js [02:10:15] Starting 'bundle'... [02:10:15] Starting 'clean'... [02:10:15] Finished 'clean' after 12 ms [02:10:15] Starting 'lint'... [02:10:17] /home/runner/work/datastax-docs-site/datastax-docs-site/ui-bundle-preview/gulpfile.js 3:9 error 'parallel' is assigned a value but never used no-unused-vars /home/runner/work/datastax-docs-site/datastax-docs-site/ui-bundle-preview/gulp.d/tasks/build-preview-pages.js 22:1 warning This line has a length of 127. Maximum allowed is 120 max-len ✖ 2 problems (1 error, 1 warning) [02:10:17] 'lint' errored after 1.7 s [02:10:17] ESLintError in plugin "gulp-eslint" Message: Failed with 1 error [02:10:17] 'bundle' errored after 1.72 s

[mlr]

UI bundle preview build successful! :white_check_mark: Deploying preview to GitHub Pages. Deployment successful! View preview

[mlr]

UI bundle preview build successful! :white_check_mark: Deploying preview to GitHub Pages. Deployment successful! View preview