Merge pull request #69 from ministryofjustice/template-changes-20240828

chore: Template changes 20240828

.circleci/config.yml

@@ -53,7 +53,6 @@ jobs:
             - node_modules
             - build
             - dist
-            - assets/stylesheets
 
   unit_test:
     executor:
@@ -195,11 +194,6 @@ workflows:
               only:
                 - main
     jobs:
-      - hmpps/npm_outdated:
-          slack_channel: << pipeline.parameters.alerts-slack-channel >>
-          node_tag: << pipeline.parameters.node-version >>
-          context:
-            - hmpps-common-vars
       - hmpps/npm_security_audit:
           slack_channel: << pipeline.parameters.alerts-slack-channel >>
           node_tag: << pipeline.parameters.node-version >>

.eslintrc.json

@@ -57,12 +57,6 @@
           }
         ]
       }
-    },
-    {
-      "files": ["esbuild/**/*"],
-      "rules": {
-        "no-console": "off"
-      }
     }
   ],
 

.gitignore

@@ -117,8 +117,6 @@ dist
 .pnp.*
 
 
-
-assets/stylesheets/*.css
 .idea
 .vscode
 dist/

.husky/pre-commit

@@ -1,4 +1 @@
-#!/bin/sh
-. "$(dirname "$0")/_/husky.sh"
-
 NODE_ENV=dev && node_modules/.bin/lint-staged && npm run typecheck && npm test

CHANGELOG.md

@@ -1,6 +1,47 @@
 # Change log
 
-**May 22nd 2024** – Remove prometheus metrics middleware and metrics app. We had discussed that very few teams actually go on to set up a dashboard to surface the information and tend to use application insights instead for the information.  In addition it had also caused a memory leak and production issues (manifesting in increased 502 error rates) in at least two applications that had inherited from the template so it seems wise to remove this tooling by default.
+**July 13th 2024** - ESBuild and asset caching improvements
+
+We have recently introduced several enhancements to the ESBuild process to improve stability, logging, and basic type annotations. These are part of
+
+PR: [#388](https://github.com/ministryofjustice/hmpps-template-typescript/pull/388) and PR: [#378](https://github.com/ministryofjustice/hmpps-template-typescript/pull/378)
+
+Additionally, we have integrated a new and improved process for handling asset cache-busting. Previously, we appended a query string representing the build number or Git commit hash to our assets for cache-busting. With the recent introduction of ESBuild, we have implemented a more common asset-revving solution, using the hash of the asset in the asset's output filename, like `/assets/js/app.UG7VY7MS.js`.
+
+In brief, this implementation creates a `manifest.json` file during the asset build process, which maps the original asset name to it's new rev'd name. We then use the assetMap filter, introduced as part of this PR, to match the original asset names to their hashed versions, like so 
+
+`<script type="module" src="{{ '/assets/js/app.js' | assetMap }}"></script>`
+
+To see the full conversation see the #typescript slack channel
+
+PR: [#377](https://github.com/ministryofjustice/hmpps-template-typescript/pull/377)
+
+---
+
+**July 11th 2024** – Remove Typescript outdated checks
+
+We originally added these checks to the template project to try to nudge people into performing major version updates rather than solely focusing on security patches. 
+This has led to a lot of confusion and queries from teams asking why we're enforcing these draconian checks.
+Previously we added some guidance suggesting developers remove it but this was not generally read.
+
+Rather than add to the complexity of the rewrite script we've decided to remove these checks entirely. 
+
+PR: [#388](https://github.com/ministryofjustice/hmpps-template-typescript/pull/388)
+
+---
+
+**June 19th 2024** – Add ESBuild!
+
+This is a bit of a WiP but rapidly speeds up the time to redeploy on changes. It does that by running typescript compiler in a side channel.
+It's worth adopting now but there are subsequent commits and changes that will continue to be integrated to improve this.
+
+To see the full conversation see the #typescript slack channel
+
+PR: [#375](https://github.com/ministryofjustice/hmpps-template-typescript/pull/375)
+
+---
+
+**May 22nd 2024** – Remove prometheus metrics middleware and metrics app. We had discussed that very few teams actually go on to set up a dashboard to surface the information and tend to use application insights instead for the information. In addition it had also caused a memory leak and production issues (manifesting in increased 502 error rates) in at least two applications that had inherited from the template so it seems wise to remove this tooling by default.
 
 PR: [#365](https://github.com/ministryofjustice/hmpps-template-typescript/pull/365)
 
@@ -20,52 +61,52 @@ PR: [#321](https://github.com/ministryofjustice/hmpps-template-typescript/pull/3
 
 **February 15th 2024** – Move over to use Debian 12 based image (bookworm)
 
-PR: [#316](https://github.com/ministryofjustice/hmpps-alerts-ui/pull/316)
+PR: [#316](https://github.com/ministryofjustice/hmpps-template-typescript/pull/316)
 
 ---
 
 **January 9th 2024** – Move over to Gov UK Frontend 5.0 and MoJ Frontend 2.0
 
 Note, this removed support for IE8,9,10 etc.
 
-PR: [#297](https://github.com/ministryofjustice/hmpps-alerts-ui/pull/297)
+PR: [#297](https://github.com/ministryofjustice/hmpps-template-typescript/pull/297)
 
 ---
 
 **November 29th 2023** – Remove getUserRoles as an api call and add as decoded from the token #274
 
-This is to encourage services not to make additional calls to retrieve a user's role information. 
-Usually roles are cached with the session meaning that the user has to log out and in again to bring in changes to roles - as user details are also cached this will not change this behaviour. 
+This is to encourage services not to make additional calls to retrieve a user's role information.
+Usually roles are cached with the session meaning that the user has to log out and in again to bring in changes to roles - as user details are also cached this will not change this behaviour.
 
-PR: [#274](https://github.com/ministryofjustice/hmpps-alerts-ui/pull/274)
+PR: [#274](https://github.com/ministryofjustice/hmpps-template-typescript/pull/274)
 
 ---
 
 **November 29th 2023** – Use in-memory token store when developing locally
 
-PR: [#273](https://github.com/ministryofjustice/hmpps-alerts-ui/pull/273)
+PR: [#273](https://github.com/ministryofjustice/hmpps-template-typescript/pull/273)
 
 ---
 
 **November 6th 2023** – Add HMPPS Manage Users API to health checks
 
-PR: [#255](https://github.com/ministryofjustice/hmpps-alerts-ui/pull/255)
+PR: [#255](https://github.com/ministryofjustice/hmpps-template-typescript/pull/255)
 
 ---
 
 **October 27th 2023** – Update to 4.0.0 of `jwt-decode` module
 
 This had breaking changes and required an update to the import statement
 
-PR: [#252](https://github.com/ministryofjustice/hmpps-alerts-ui/pull/252)
+PR: [#252](https://github.com/ministryofjustice/hmpps-template-typescript/pull/252)
 
 ---
 
 **October 27th 2023** – Update application to use node.js version 20 and npm version 10
 
 Application updated to node 20.8 along with one minor node module tweaks
 
-PR: [#249](https://github.com/ministryofjustice/hmpps-alerts-ui/pull/249)
+PR: [#249](https://github.com/ministryofjustice/hmpps-template-typescript/pull/249)
 
 ---
 
@@ -74,7 +115,7 @@ PR: [#249](https://github.com/ministryofjustice/hmpps-alerts-ui/pull/249)
 `/api/user/me` -> `/users/me` <br>
 `/api/user/me/roles` -> `/users/me/roles`
 
-PR: [#247](https://github.com/ministryofjustice/hmpps-alerts-ui/pull/247)
+PR: [#247](https://github.com/ministryofjustice/hmpps-template-typescript/pull/247)
 
 ---
 
@@ -86,14 +127,14 @@ and generic response types.
 The user object built by `setUpCurrentUser` middleware is exposed in `res.locals` of request handlers
 preventing the need for type assertions.
 
-PR: [#238](https://github.com/ministryofjustice/hmpps-alerts-ui/pull/238)
+PR: [#238](https://github.com/ministryofjustice/hmpps-template-typescript/pull/238)
 
 ---
 
 **September 28th 2023** - Add in environment name to the header
 
 For dev and pre-prod we now display the environment name in the header to let people know that the service isn't
-production.  This brings the template into line with the new micro frontend components header.
+production. This brings the template into line with the new micro frontend components header.
 
 ---
 
@@ -103,55 +144,55 @@ As part of the work on the [service catalogue](https://hmpps-developer-portal.hm
 
 For more details ask on the `#hmpps-service-catalogue channel`.
 
-PR: [here](https://github.com/ministryofjustice/hmpps-alerts-ui/pull/231)
+PR: [here](https://github.com/ministryofjustice/hmpps-template-typescript/pull/231)
 
 ---
 
-**August 3rd 2023** - Add /info endpoint and expose product ids  
+**August 3rd 2023** - Add /info endpoint and expose product ids
 
 As part of the work on the [service catalogue](https://hmpps-developer-portal.hmpps.service.justice.gov.uk/products) we are giving all applications their own product id.
-This change adds a new info endpoint to expose this id in a consistent place. 
+This change adds a new info endpoint to expose this id in a consistent place.
 
 For more details ask on the `#hmpps-service-catalogue channel`.
 
-PR: [here](https://github.com/ministryofjustice/hmpps-alerts-ui/pull/212)
+PR: [here](https://github.com/ministryofjustice/hmpps-template-typescript/pull/212)
 
 ---
 
 **June 9th 2023** - Do not retry POST requests by default
 
 It's not safe to retry idempotent calls as this introduces the risk of creating multiple resources. This fix changes the default to not carry out any retries but allows switching on retrying if desired.
 
-PR: [here](https://github.com/ministryofjustice/hmpps-alerts-ui/pull/197) 
+PR: [here](https://github.com/ministryofjustice/hmpps-template-typescript/pull/197)
 
 ---
 
 **April 13th 2023** - Caching fix
 
 Asset caching was only set to 20 seconds. This fix changes the default to 1 hour which has a profound effect on the number of requests the application serves.
 
-PR: [here](https://github.com/ministryofjustice/hmpps-alerts-ui/pull/178) 
+PR: [here](https://github.com/ministryofjustice/hmpps-template-typescript/pull/178)
 
 ---
 
 **April 4th 2023** - Remove unnecessary build step
 
 There was an additional unnecessary build step as part of start:dev npm task. This more than doubled the start time on the initial run.
 
-PR: [here](https://github.com/ministryofjustice/hmpps-alerts-ui/pull/172) 
+PR: [here](https://github.com/ministryofjustice/hmpps-template-typescript/pull/172)
 
 ---
 
 **March 20th 2023** - CSP fix for redirects during POST on session timeout
 
 Updates the Content Security Policy to fix issues when users would be stuck on pages after submitting a form after their session times out. (Lots more detail in the PR)
 
-PR: [here](https://github.com/ministryofjustice/hmpps-alerts-ui/pull/170) 
+PR: [here](https://github.com/ministryofjustice/hmpps-template-typescript/pull/170)
 
 ---
 
 **February 3rd 2023** - Revert multi build docker image
 
-Multibuild docker images ended up taking a very long time after the upgrade to node 18 (1hr+). Some work needs to be done to move to support multi host builds in our circle orb, in the meantime we’ve removed this and are just building images solely for deployment. 
- 
-PR: [here](https://github.com/ministryofjustice/hmpps-alerts-ui/pull/149)
+Multibuild docker images ended up taking a very long time after the upgrade to node 18 (1hr+). Some work needs to be done to move to support multi host builds in our circle orb, in the meantime we’ve removed this and are just building images solely for deployment.
+
+PR: [here](https://github.com/ministryofjustice/hmpps-template-typescript/pull/149)

Dockerfile

@@ -1,5 +1,5 @@
 # Stage: base image
-FROM node:20.15-bookworm-slim as base
+FROM node:20.16-bookworm-slim as base
 
 ARG BUILD_NUMBER
 ARG GIT_REF

esbuild/app.config.js

@@ -3,24 +3,34 @@ const { typecheckPlugin } = require('@jgoz/esbuild-plugin-typecheck')
 const esbuild = require('esbuild')
 const glob = require('glob')
 
+/**
+ * Build typescript application into CommonJS
+ * @type {BuildStep}
+ */
+const buildApp = buildConfig => {
+  return esbuild.build({
+    entryPoints: glob.sync(buildConfig.app.entryPoints),
+    outdir: buildConfig.app.outDir,
+    bundle: false,
+    sourcemap: true,
+    platform: 'node',
+    format: 'cjs',
+    plugins: [
+      typecheckPlugin(),
+      copy({
+        resolveFrom: 'cwd',
+        assets: buildConfig.app.copy,
+      }),
+    ],
+  })
+}
+
+/**
+ * @param {BuildConfig} buildConfig
+ * @returns {Promise}
+ */
 module.exports = buildConfig => {
-  console.log('\u{1b}[1m\u{2728}  Building app....\u{1b}[0m')
+  process.stderr.write('\u{1b}[1m\u{2728} Building app...\u{1b}[0m\n')
 
-  esbuild
-    .build({
-      entryPoints: glob.sync(buildConfig.app.entryPoints),
-      outdir: buildConfig.app.outDir,
-      bundle: false,
-      sourcemap: true,
-      platform: 'node',
-      format: 'cjs',
-      plugins: [
-        typecheckPlugin(),
-        copy({
-          resolveFrom: 'cwd',
-          assets: buildConfig.app.copy,
-        }),
-      ],
-    })
-    .catch(() => process.exit(1))
+  return buildApp(buildConfig)
 }

esbuild/assets.config.js

@@ -1,12 +1,18 @@
+const path = require('node:path')
+
 const { copy } = require('esbuild-plugin-copy')
 const { sassPlugin } = require('esbuild-sass-plugin')
 const { clean } = require('esbuild-plugin-clean')
+const manifestPlugin = require('esbuild-plugin-manifest')
 const esbuild = require('esbuild')
-const path = require('path')
 const { glob } = require('glob')
 
-const buildAdditionalAssets = buildConfig =>
-  esbuild.build({
+/**
+ * Copy additional assets into distribution
+ * @type {BuildStep}
+ */
+const buildAdditionalAssets = buildConfig => {
+  return esbuild.build({
     outdir: buildConfig.assets.outDir,
     plugins: [
       copy({
@@ -15,12 +21,17 @@ const buildAdditionalAssets = buildConfig =>
       }),
     ],
   })
+}
 
+/**
+ * Build scss and javascript assets
+ * @type {BuildStep}
+ */
 const buildAssets = buildConfig => {
   return esbuild.build({
     entryPoints: buildConfig.assets.entryPoints,
     outdir: buildConfig.assets.outDir,
-    entryNames: '[ext]/app',
+    entryNames: '[ext]/app.[hash]',
     minify: buildConfig.isProduction,
     sourcemap: !buildConfig.isProduction,
     platform: 'browser',
@@ -31,6 +42,10 @@ const buildAssets = buildConfig => {
       clean({
         patterns: glob.sync(buildConfig.assets.clear),
       }),
+      manifestPlugin({
+        generate: entries =>
+          Object.fromEntries(Object.entries(entries).map(paths => paths.map(p => p.replace(/^dist\//, '/')))),
+      }),
       sassPlugin({
         quietDeps: true,
         loadPaths: [process.cwd(), path.join(process.cwd(), 'node_modules')],
@@ -39,11 +54,12 @@ const buildAssets = buildConfig => {
   })
 }
 
+/**
+ * @param {BuildConfig} buildConfig
+ * @returns {Promise}
+ */
 module.exports = buildConfig => {
-  console.log('\u{1b}[1m\u{2728}  Building assets....\u{1b}[0m')
+  process.stderr.write('\u{1b}[1m\u{2728} Building assets...\u{1b}[0m\n')
 
-  Promise.all([buildAssets(buildConfig), buildAdditionalAssets(buildConfig)]).catch(e => {
-    console.log(e)
-    process.exit(1)
-  })
+  return Promise.all([buildAssets(buildConfig), buildAdditionalAssets(buildConfig)])
 }