Add error pages (#84)

Add a template and error middleware which will display nicer error
messages when there’s an error in your template:

<img width="965" height="611" alt="Screenshot 2025-11-22 at 23 44 18"
src="https://github.com/user-attachments/assets/8f4a22e4-07a0-4631-a6af-674746de88fd"
/>

Borrowing heavily from
[nhsuk-prototype-rig](https://github.com/x-govuk/nhsuk-prototype-rig)
(thanks @paulrobertlloyd!).

Author: frankieroberto

CHANGELOG.md

@@ -27,6 +27,7 @@ If you are upgrading a prototype which used a previous version of the kit, see [
 ### :new: **New features**
 
 - A more helpful 404 error page if you visit a path which doesn’t match a route or a template.
+- A more helpful error page if you have an error in your template
 
 ## 7.1.0 - 20 October 2025
 

eslint.config.mjs

@@ -132,7 +132,14 @@ export default defineConfig([
     },
     rules: {
       '@typescript-eslint/no-require-imports': 'off',
-      '@typescript-eslint/unbound-method': 'off'
+      '@typescript-eslint/unbound-method': 'off',
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_'
+        }
+      ]
     }
   },
   {

lib/express-middleware/index.js

@@ -9,6 +9,7 @@ const authenticate = require('./authentication')
 const autoRouting = require('./auto-routing')
 const autoStoreData = require('./auto-store-data')
 const productionHeaders = require('./production-headers')
+const renderErrorPage = require('./render-error-page')
 const renderPageNotFound = require('./render-page-not-found')
 const resetSessionData = require('./reset-session-data')
 const setCurrentPageInLocals = require('./set-current-page-in-locals')
@@ -116,7 +117,7 @@ function all(options) {
     app.use(autoRouting.matchRoutes)
 
     // Page not found - this must come last
-    app.use(renderPageNotFound)
+    app.use(renderPageNotFound, renderErrorPage)
 
     next()
   }
@@ -129,6 +130,7 @@ module.exports = {
   authenticate,
   productionHeaders,
   renderPageNotFound,
+  renderErrorPage,
   resetSessionData,
   setCurrentPageInLocals,
   setSessionDataDefaults

lib/express-middleware/render-error-page.js

@@ -0,0 +1,10 @@
+const renderErrorPage = function (error, req, res, _next) {
+  error.status = error.status || 500
+
+  console.error(error.stack)
+
+  res.status(error.status)
+  res.render('500.html', { error })
+}
+
+module.exports = renderErrorPage

lib/views/500.html

@@ -0,0 +1,27 @@
+{% extends "layout.html" %}
+
+{% set pageName = "Sorry, there is a problem with the prototype" %}
+
+{% set stackHtml -%}
+<pre class="nhsuk-u-margin-0" tabindex="0"><code class="nhsuk-u-font-size-14">{{ error.stack }}</code></pre>
+{%- endset %}
+
+{% block content %}
+  <div class="nhsuk-grid-row">
+    <div class="nhsuk-grid-column-two-thirds">
+
+      <h1 class="nhsuk-heading-xl">{{ pageName }}</h1>
+
+      <h2 class="nhsuk-heading-m">{{ error.name }}</h2>
+
+      <p class="nhsuk-caption-m">{{ error.message | nl2br | nl2br | safe }}</p>
+      {{ details({
+        summaryText: "Stack trace",
+        html: stackHtml
+      }) }}
+
+      <pre class="nhsuk-u-margin-top-8">Status code: {{ error.status }}</pre>
+    </div>
+  </div>
+{% endblock %}
+

testapp/views/containing-error.html

@@ -0,0 +1,10 @@
+{% extends "layout.html" %}
+
+{% block content %}
+  <div class="nhsuk-grid-row">
+    <div class="nhsuk-grid-column-two-thirds">
+      {% if %}
+    </div>
+  </div>
+{% endblock %}
+

testapp/views/index.html

@@ -50,6 +50,7 @@ <h1>{{ serviceName }}</h1>
       </form>
 
       <p><a href="/custom-route">Custom route</a>.</p>
+      <p><a href="/containing-error">Template with a syntax error</a>.</p>
     </div>
   </div>
 {% endblock %}

tests/express-middleware/500.html

@@ -0,0 +1 @@
+Server error

tests/express-middleware/render-error-page.test.js

@@ -0,0 +1,58 @@
+const assert = require('node:assert')
+const http = require('node:http')
+const { join } = require('node:path')
+const { describe, it, beforeEach, afterEach } = require('node:test')
+
+const express = require('express')
+const nunjucks = require('nunjucks')
+const request = require('supertest')
+
+const originalError = console.error
+let errorCalls = []
+
+const renderErrorPage = require('../../lib/express-middleware/render-error-page')
+
+const app = express()
+app.set('view engine', 'html')
+nunjucks.configure([join(__dirname, '.')], {
+  express: app,
+  noCache: true
+})
+
+app.use(function (_req, _res, _next) {
+  throw Error('Template error')
+})
+
+app.use(renderErrorPage)
+
+const server = http.createServer(app)
+
+describe('renderErrorPage', () => {
+  beforeEach(() => {
+    errorCalls = []
+    console.error = (...args) => {
+      errorCalls.push(args)
+      originalError(...args) // Still logs to console
+    }
+  })
+
+  afterEach(() => {
+    console.error = originalError
+  })
+
+  it('sets the 500 status code', async () => {
+    const response = await request(server).get('/error')
+    assert.strictEqual(response.status, 500)
+  })
+
+  it('renders the 500.html template', async () => {
+    const response = await request(server).get('/error')
+    assert.strictEqual(response.text, 'Server error\n')
+  })
+
+  it('calls console.error() with the error', async () => {
+    await request(server).get('/error')
+    assert.strictEqual(errorCalls.length, 1)
+    assert.ok(errorCalls[0][0].startsWith('Error: Template error'))
+  })
+})