The stack on one page#

What each piece of a GOV.UK Node service does, and which of your React and .NET skills it replaces.

On your current projects the browser does most of the work. A React app owns routing, state and forms, and calls your ASP.NET Core API for data. A GOV.UK service moves that work back to a server. The browser gets finished HTML, and every step of a form is a round trip to the server.

The Node frontend is a small web server. It renders pages from templates, keeps each user's answers in a session, and sends the finished application to a backend API. That API is often written in another language, and it may be the .NET you already write.

You do not need to know any of these tools yet. Here is what happens inside the Node frontend when a browser asks for a page; the next chapters take each part in turn.

The pieces#

Your skills carry over one layer at a time. React knowledge maps onto templates and components. .NET knowledge maps onto the server, where a GOV.UK page works much like a Razor Page with an OnGet and an OnPost.

The request loop#

Every GOV.UK question page runs the same loop: GET the page, POST the form, then show the errors or save and redirect. This loop replaces your client-side state.

Read the figure as three rules. A GET only shows a page. A POST checks the answer. If the answer is wrong, the POST renders the same page again with the errors. If it is right, the POST saves it and redirects. The redirect matters: refreshing the next page repeats a harmless GET, not the form submission. The pattern is often called Post/Redirect/Get.

State lives in the session#

In React, answers live in component state until you send them. Here the browser keeps nothing. Each answer goes into a server-side session as soon as its page is valid, and a cookie tells the server whose session it is. The next page, the check answers page and the final submission all read from that session.

function NamePage() {
  const [name, setName] = useState('');
  const [error, setError] = useState('');
  async function onSubmit(e) {
    e.preventDefault();
    if (!name) return setError('Enter your full name');
    await fetch('/api/name', { method: 'POST', body: name });
    navigate('/email');
  }
  return (
    <form onSubmit={onSubmit}>
      <input value={name} onChange={(e) => setName(e.target.value)} />
      {error && <p>{error}</p>}
      <button>Continue</button>
    </form>
  );
}

<form method="post" novalidate>
  <input type="hidden" name="_csrf" value="{{ csrfToken }}">
  {{ govukInput({
    label: { text: "What is your full name?" },
    id: "fullName",
    name: "fullName",
    value: values.fullName,
    errorMessage: fieldErrors.fullName
  }) }}
  {{ govukButton({ text: "Continue" }) }}
</form>

The template has no handlers. The check, the save and the navigation all moved into the POST route, which is the same in both frameworks apart from its wiring:

router.post('/:page', (req, res, next) => {
  const { page } = req.params;
  if (!isQuestion(page)) return next();
  const answers = req.session.answers ?? {};
  const changing = req.query.change === 'true';
  const values = pick(page, req.body);
  const errors = validate(page, values);
  if (errors.length > 0) {
    return res.render(`pages/${page}`, {
      values,
      ...errorView(errors),
      backLink: backLink(page, answers, changing),
    });
  }
  req.session.answers = { ...answers, [page]: values };
  res.redirect(
    `/${nextPage(page, req.session.answers, changing)}`,
  );
});

router.post('/:page', (req, res, next) => {
  const { page } = req.params;
  if (!isQuestion(page)) return next();
  const answers = req.session.answers ?? {};
  const changing = req.query.change === 'true';
  const values = pick(page, req.body);
  const errors = validate(page, values);
  if (errors.length > 0) {
    return res.render(`pages/${page}`, {
      values,
      ...errorView(errors),
      backLink: backLink(page, answers, changing),
    });
  }
  req.session.answers = { ...answers, [page]: values };
  res.redirect(
    `/${nextPage(page, req.session.answers, changing)}`,
  );
});

app.post<PageRequest>('/:page', async (request, reply) => {
  const { page } = request.params;
  if (!isQuestion(page)) return reply.callNotFound();
  const answers = request.session.answers ?? {};
  const changing = request.query.change === 'true';
  const values = pick(page, request.body);
  const errors = validate(page, values);
  if (errors.length > 0) {
    return reply.view(`pages/${page}`, {
      values,
      ...errorView(errors),
      backLink: backLink(page, answers, changing),
    });
  }
  request.session.answers = { ...answers, [page]: values };
  return reply.redirect(
    `/${nextPage(page, request.session.answers, changing)}`,
  );
});

app.post('/:page', async (request, reply) => {
  const { page } = request.params;
  if (!isQuestion(page)) return reply.callNotFound();
  const answers = request.session.answers ?? {};
  const changing = request.query.change === 'true';
  const values = pick(page, request.body);
  const errors = validate(page, values);
  if (errors.length > 0) {
    return reply.view(`pages/${page}`, {
      values,
      ...errorView(errors),
      backLink: backLink(page, answers, changing),
    });
  }
  request.session.answers = { ...answers, [page]: values };
  return reply.redirect(
    `/${nextPage(page, request.session.answers, changing)}`,
  );
});

CORS leaves, CSRF arrives#

Pages and forms now come from the same origin as the server, so cross-origin resource sharing (CORS) has nothing to do. But the browser sends the session cookie with every request to the service, including a form post that another site starts. That attack is cross-site request forgery (CSRF). Every form therefore carries a hidden token, which the server checks on every POST. Chapter 6 wires it up.

It works without JavaScript#

The Service Manual says every government service must follow progressive enhancement, and tells teams not to build a single-page application (Service Manual: using progressive enhancement). So every page must work with plain HTML forms. GOV.UK Frontend's JavaScript only improves components that already work, for example by moving focus to the error summary.

Express and Fastify, from zero#

Express and Fastify are the two Node web frameworks this book covers. This chapter starts from nothing: how each one turns a request into a response, then how their shapes differ.

A first app in each#

Node runs JavaScript on a server. A web framework listens for HTTP requests, matches each request's method and path to a function you wrote, and sends back what that function produces. You install a framework from npm and import it like any other module: npm install express or npm install fastify. Here is a small app in each, doing the same three things:

const app = express();

app.use((req, res, next) => {
  res.set('Cache-Control', 'no-store');
  next();
});

app.get('/', (req, res) => {
  res.send('Hello from Express');
});

app.get('/pages/:page', (req, res) => {
  res.json({
    page: req.params.page,
    change: req.query.change,
  });
});

const app = express();

app.use((req, res, next) => {
  res.set('Cache-Control', 'no-store');
  next();
});

app.get('/', (req, res) => {
  res.send('Hello from Express');
});

app.get('/pages/:page', (req, res) => {
  res.json({
    page: req.params.page,
    change: req.query.change,
  });
});

const app = Fastify();

app.addHook('onRequest', async (request, reply) => {
  reply.header('Cache-Control', 'no-store');
});

app.get('/', async () => 'Hello from Fastify');

app.get<{
  Params: { page: string };
  Querystring: { change?: string };
}>('/pages/:page', async (request) => ({
  page: request.params.page,
  change: request.query.change,
}));

const app = Fastify();

app.addHook('onRequest', async (request, reply) => {
  reply.header('Cache-Control', 'no-store');
});

app.get('/', async () => 'Hello from Fastify');

app.get('/pages/:page', async (request) => ({
  page: request.params.page,
  change: request.query.change,
}));

• The app. express() and Fastify() each create one, and everything else is added to it.
• Code that runs for every request. Express calls it middleware: a function that gets the request, the response and next, and calls next() to pass the request on. Fastify calls it a hook, such as onRequest, which runs at a named point in every request.
• A route. app.get(path, handler) in both. :page in the path arrives as req.params.page, and ?change=true as req.query.change. Fastify names the two objects request and reply, where Express names them req and res.
• The answer. An Express handler calls a method on res, such as send, json, render or redirect, and nothing is sent until it does. A Fastify handler can simply return a value: Fastify sends a string as plain text and an object as JSON.

To start an app, tell it to listen on a port. The example app keeps this in a small server file, so its tests can start the same app on any free port:

createApp().listen(port, () => {
  console.log(`Express version: http://localhost:${port}`);
});

createApp().listen(port, () => {
  console.log(`Express version: http://localhost:${port}`);
});

const app = await buildApp();
await app.listen({ port });

const app = await buildApp();
await app.listen({ port });

In the example app, npm run express or npm run fastify starts each version. Node 22 needs --experimental-strip-types to run TypeScript directly, and those scripts pass it for you.

The two shapes#

If you know the ASP.NET Core middleware pipeline, Express will feel familiar. Each app.use() adds a step, and every request walks the steps in the order you added them. Fastify registers plugins instead. A plain plugin gets its own scope, so the hooks and decorators added inside it stay inside it. A decorator is an extra method, such as reply.view. The official @fastify/* plugins are wrapped with fastify-plugin, which shares them with the whole app.

Setting up templates#

Both apps start by telling Nunjucks where templates live, then add a global that every page can use.

const env = nunjucks.configure(
  [paths.govukViews, paths.views],
  { express: app },
);
env.addGlobal('serviceName', serviceName);
app.set('view engine', 'njk');

const env = nunjucks.configure(
  [paths.govukViews, paths.views],
  { express: app },
);
env.addGlobal('serviceName', serviceName);
app.set('view engine', 'njk');

await app.register(fastifyView, {
  engine: { nunjucks },
  templates: [paths.govukViews, paths.views],
  viewExt: 'njk',
  options: {
    onConfigure: (env: nunjucks.Environment) =>
      env.addGlobal('serviceName', serviceName),
  },
});

await app.register(fastifyView, {
  engine: { nunjucks },
  templates: [paths.govukViews, paths.views],
  viewExt: 'njk',
  options: {
    onConfigure: (env) =>
      env.addGlobal('serviceName', serviceName),
  },
});

A route#

One GET route serves every question page. It refuses pages the user has not reached yet, then renders the template with the saved answer.

router.get('/:page', (req, res, next) => {
  const { page } = req.params;
  if (!isQuestion(page)) return next();
  const answers = req.session.answers ?? {};
  const pages = route(answers);
  if (!pages.includes(page)) {
    return res.redirect(`/${pages.at(-1)}`);
  }
  const changing = req.query.change === 'true';
  res.render(`pages/${page}`, {
    values: answers[page] ?? {},
    backLink: backLink(page, answers, changing),
  });
});

router.get('/:page', (req, res, next) => {
  const { page } = req.params;
  if (!isQuestion(page)) return next();
  const answers = req.session.answers ?? {};
  const pages = route(answers);
  if (!pages.includes(page)) {
    return res.redirect(`/${pages.at(-1)}`);
  }
  const changing = req.query.change === 'true';
  res.render(`pages/${page}`, {
    values: answers[page] ?? {},
    backLink: backLink(page, answers, changing),
  });
});

app.get<PageRequest>('/:page', async (request, reply) => {
  const { page } = request.params;
  if (!isQuestion(page)) return reply.callNotFound();
  const answers = request.session.answers ?? {};
  const pages = route(answers);
  if (!pages.includes(page)) {
    return reply.redirect(`/${pages.at(-1)}`);
  }
  const changing = request.query.change === 'true';
  return reply.view(`pages/${page}`, {
    values: answers[page] ?? {},
    backLink: backLink(page, answers, changing),
  });
});

app.get('/:page', async (request, reply) => {
  const { page } = request.params;
  if (!isQuestion(page)) return reply.callNotFound();
  const answers = request.session.answers ?? {};
  const pages = route(answers);
  if (!pages.includes(page)) {
    return reply.redirect(`/${pages.at(-1)}`);
  }
  const changing = request.query.change === 'true';
  return reply.view(`pages/${page}`, {
    values: answers[page] ?? {},
    backLink: backLink(page, answers, changing),
  });
});

type PageRequest = {
  Params: { page: string };
  Querystring: { change?: string };
};

The same idea, three names#

A request's life in Fastify#

Fastify names the points where you can hook in. Their order tells you where each piece of plumbing belongs.

Routes, requests and responses#

Every routing, request and response feature you will meet in Express and Fastify code, side by side, each from a tested example. The chapter ends with a plugin to read and a page to write.

Methods and routes#

A route is an HTTP method, a path and a handler. Both frameworks have a method for each HTTP method, such as get and post, and all for every method at once. Express's app.route() puts several methods on one path. Fastify's app.route() takes the whole declaration in one object. Its shorthands, such as app.get(), take the same options as their second argument.

app
  .route('/licences')
  .get((req, res) => {
    res.send('list the licences');
  })
  .post((req, res) => {
    res.status(201).send('create a licence');
  });
app.all('/ping', (req, res) => {
  res.send(`${req.method} ping`);
});

app
  .route('/licences')
  .get((req, res) => {
    res.send('list the licences');
  })
  .post((req, res) => {
    res.status(201).send('create a licence');
  });
app.all('/ping', (req, res) => {
  res.send(`${req.method} ping`);
});

app.route({
  method: 'GET',
  url: '/licences',
  handler: async () => 'list the licences',
});
app.post('/licences', async (request, reply) => {
  reply.code(201);
  return 'create a licence';
});
app.all(
  '/ping',
  async (request) => `${request.method} ping`,
);

app.route({
  method: 'GET',
  url: '/licences',
  handler: async () => 'list the licences',
});
app.post('/licences', async (request, reply) => {
  reply.code(201);
  return 'create a licence';
});
app.all(
  '/ping',
  async (request) => `${request.method} ping`,
);

Path syntax#

Both frameworks mark a path parameter with a colon. They differ on optional parts, wildcards and patterns. Express 4 differs again, as chapter 5 shows.

// a named parameter: /licences/42 gives { id: '42' }
app.get('/licences/:id', (req, res) => {
  res.json(req.params);
});
// an optional part, in braces: /search and /search/fire
app.get('/search{/:term}', (req, res) => {
  res.json(req.params);
});
// a named wildcard: /docs/a/b gives { path: ['a', 'b'] }
app.get('/docs/*path', (req, res) => {
  res.json(req.params);
});
// no regular expressions in Express 5 paths: check the value instead
app.get('/years/:year', (req, res, next) => {
  if (!/^\d{4}$/.test(req.params.year)) return next();
  res.json(req.params);
});

// a named parameter: /licences/42 gives { id: '42' }
app.get('/licences/:id', (req, res) => {
  res.json(req.params);
});
// an optional part, in braces: /search and /search/fire
app.get('/search{/:term}', (req, res) => {
  res.json(req.params);
});
// a named wildcard: /docs/a/b gives { path: ['a', 'b'] }
app.get('/docs/*path', (req, res) => {
  res.json(req.params);
});
// no regular expressions in Express 5 paths: check the value instead
app.get('/years/:year', (req, res, next) => {
  if (!/^\d{4}$/.test(req.params.year)) return next();
  res.json(req.params);
});

// a named parameter: /licences/42 gives { id: '42' }
app.get('/licences/:id', async (request) => request.params);
// only the last parameter can be optional: /search and /search/fire
app.get(
  '/search/:term?',
  async (request) => request.params,
);
// a wildcard: /docs/a/b gives { '*': 'a/b' }
app.get('/docs/*', async (request) => request.params);
// a regular expression: anything that does not match is a 404
app.get(
  '/years/:year(^\\d{4}$)',
  async (request) => request.params,
);

// a named parameter: /licences/42 gives { id: '42' }
app.get('/licences/:id', async (request) => request.params);
// only the last parameter can be optional: /search and /search/fire
app.get(
  '/search/:term?',
  async (request) => request.params,
);
// a wildcard: /docs/a/b gives { '*': 'a/b' }
app.get('/docs/*', async (request) => request.params);
// a regular expression: anything that does not match is a 404
app.get(
  '/years/:year(^\\d{4}$)',
  async (request) => request.params,
);

Several handlers on one route#

A route can run more than one function. Express takes extra handlers before the last one, and each calls next() to go on, or answers the request itself. Fastify puts them in the route's preHandler option, as hooks that run just before the handler. A hook that answers returns reply.

// a handler that runs first, and may end the request itself
const onlyOpenLicences: RequestHandler = (
  req,
  res,
  next,
) => {
  if (req.params.id === '13') {
    return res.status(403).send('licence 13 is suspended');
  }
  next();
};
app.get(
  '/licences/:id/summary',
  onlyOpenLicences,
  (req, res) => {
    res.send(`summary of licence ${req.params.id}`);
  },
);

// a handler that runs first, and may end the request itself
const onlyOpenLicences = (req, res, next) => {
  if (req.params.id === '13') {
    return res.status(403).send('licence 13 is suspended');
  }
  next();
};
app.get(
  '/licences/:id/summary',
  onlyOpenLicences,
  (req, res) => {
    res.send(`summary of licence ${req.params.id}`);
  },
);

// a preHandler runs first, and may end the request itself
const onlyOpenLicences: preHandlerAsyncHookHandler = async (
  request,
  reply,
) => {
  const { id } = request.params as { id: string };
  if (id === '13') {
    return reply.code(403).send('licence 13 is suspended');
  }
};
app.get<WithId>(
  '/licences/:id/summary',
  { preHandler: [onlyOpenLicences] },
  async (request) =>
    `summary of licence ${request.params.id}`,
);

// a preHandler runs first, and may end the request itself
const onlyOpenLicences = async (request, reply) => {
  const { id } = request.params;
  if (id === '13') {
    return reply.code(403).send('licence 13 is suspended');
  }
};
app.get(
  '/licences/:id/summary',
  { preHandler: [onlyOpenLicences] },
  async (request) =>
    `summary of licence ${request.params.id}`,
);

Grouping routes under a prefix#

Services keep each group of pages in its own file. Express puts them on a router, and mounts it at a path with app.use(). Fastify puts them in a plugin, and registers it with a prefix. Either way, the routes inside give only the end of the path.

// routes grouped in a router and mounted at a prefix;
// mergeParams lets them read :id from the prefix
const holder = Router({ mergeParams: true });
holder.get(
  '/',
  (req: Request<{ id: string }>, res: Response) => {
    res.send(`holder of licence ${req.params.id}`);
  },
);
holder.get(
  '/address',
  (req: Request<{ id: string }>, res: Response) => {
    res.send(`address for licence ${req.params.id}`);
  },
);
app.use('/licences/:id/holder', holder);

// routes grouped in a router and mounted at a prefix;
// mergeParams lets them read :id from the prefix
const holder = Router({ mergeParams: true });
holder.get('/', (req, res) => {
  res.send(`holder of licence ${req.params.id}`);
});
holder.get('/address', (req, res) => {
  res.send(`address for licence ${req.params.id}`);
});
app.use('/licences/:id/holder', holder);

// routes grouped in a plugin and registered at a prefix;
// parameters in the prefix reach every route in it
const holderRoutes: FastifyPluginAsync = async (holder) => {
  holder.get<WithId>(
    '/',
    async (request) =>
      `holder of licence ${request.params.id}`,
  );
  holder.get<WithId>(
    '/address',
    async (request) =>
      `address for licence ${request.params.id}`,
  );
};
await app.register(holderRoutes, {
  prefix: '/licences/:id/holder',
});

// routes grouped in a plugin and registered at a prefix;
// parameters in the prefix reach every route in it
const holderRoutes = async (holder) => {
  holder.get(
    '/',
    async (request) =>
      `holder of licence ${request.params.id}`,
  );
  holder.get(
    '/address',
    async (request) =>
      `address for licence ${request.params.id}`,
  );
};
await app.register(holderRoutes, {
  prefix: '/licences/:id/holder',
});

Two Express-only tools Express only#

next('route') skips the rest of a route's handlers, and tries the next route that matches. router.param() runs before any route with that parameter in its path, once per request, so it is the place to check or load a record.

// next('route') skips this route's other handlers
// and tries the next route that matches
app.get(
  '/renew/:id',
  (req, res, next) => {
    if (req.params.id === 'new') return next('route');
    next();
  },
  (req, res) => {
    res.send(`renew licence ${req.params.id}`);
  },
);
app.get('/renew/:id', (req, res) => {
  res.send('start a new application instead');
});

// next('route') skips this route's other handlers
// and tries the next route that matches
app.get(
  '/renew/:id',
  (req, res, next) => {
    if (req.params.id === 'new') return next('route');
    next();
  },
  (req, res) => {
    res.send(`renew licence ${req.params.id}`);
  },
);
app.get('/renew/:id', (req, res) => {
  res.send('start a new application instead');
});

// router.param() runs before any route with :ref in its path
const references = Router();
references.param('ref', (req, res, next, ref: string) => {
  if (!/^JL-\d{4}$/.test(ref)) {
    return res.status(404).send('no such reference');
  }
  next();
});
references.get('/reference/:ref', (req, res) => {
  res.send(`found ${req.params.ref}`);
});
app.use(references);

// router.param() runs before any route with :ref in its path
const references = Router();
references.param('ref', (req, res, next, ref) => {
  if (!/^JL-\d{4}$/.test(ref)) {
    return res.status(404).send('no such reference');
  }
  next();
});
references.get('/reference/:ref', (req, res) => {
  res.send(`found ${req.params.ref}`);
});
app.use(references);

Fastify has neither. It allows one route for each method and path, so a check like this goes in a preHandler, as above, or in a schema for the parameters.

Reading the request#

Everything a route knows about a request is on one object: req in Express, request in Fastify. Bodies and cookies are parsed first. The client's real address needs one setting when the app sits behind a load balancer or another proxy.

// a load balancer sits in front of the app: trust its X-Forwarded-*
// headers, but only when they come from its addresses
app.set('trust proxy', ['loopback', '10.0.0.0/8']);

// a load balancer sits in front of the app: trust its X-Forwarded-*
// headers, but only when they come from its addresses
app.set('trust proxy', ['loopback', '10.0.0.0/8']);

// a load balancer sits in front of the app: trust its X-Forwarded-*
// headers, but only when they come from its addresses
const app = Fastify({
  trustProxy: ['loopback', '10.0.0.0/8'],
});

// a load balancer sits in front of the app: trust its X-Forwarded-*
// headers, but only when they come from its addresses
const app = Fastify({
  trustProxy: ['loopback', '10.0.0.0/8'],
});

app.use(express.urlencoded());
app.use(express.json());
app.use(cookieParser());

app.use(express.urlencoded());
app.use(express.json());
app.use(cookieParser());

// JSON bodies need no plugin; form bodies and cookies do
await app.register(fastifyFormbody);
await app.register(fastifyCookie);

// JSON bodies need no plugin; form bodies and cookies do
await app.register(fastifyFormbody);
await app.register(fastifyCookie);

app.post('/inspect/:page', (req, res) => {
  res.json({
    params: req.params,
    query: req.query,
    body: req.body,
    host: req.get('host'),
    cookies: req.cookies,
    ip: req.ip,
    protocol: req.protocol,
    hostname: req.hostname,
    route: req.route.path,
    url: req.originalUrl,
  });
});

app.post('/inspect/:page', (req, res) => {
  res.json({
    params: req.params,
    query: req.query,
    body: req.body,
    host: req.get('host'),
    cookies: req.cookies,
    ip: req.ip,
    protocol: req.protocol,
    hostname: req.hostname,
    route: req.route.path,
    url: req.originalUrl,
  });
});

app.post<{ Params: { page: string } }>(
  '/inspect/:page',
  async (request) => ({
    params: request.params,
    query: request.query,
    body: request.body,
    host: request.host,
    cookies: request.cookies,
    ip: request.ip,
    protocol: request.protocol,
    hostname: request.hostname,
    route: request.routeOptions.url,
    url: request.url,
  }),
);

app.post('/inspect/:page', async (request) => ({
  params: request.params,
  query: request.query,
  body: request.body,
  host: request.host,
  cookies: request.cookies,
  ip: request.ip,
  protocol: request.protocol,
  hostname: request.hostname,
  route: request.routeOptions.url,
  url: request.url,
}));

The test posts a form to /inspect/name?change=true&props=clubs&props=rings, with a cookie and the proxy's headers. Both frameworks answer with the same values:

Sending the response#

An Express handler calls methods on res. A Fastify handler sets the status and headers on reply, then returns what to send. Each pair below does the same job.

app.post('/api/licences', (req, res) => {
  res
    .status(201)
    .set('Location', '/api/licences/42')
    .json({ id: '42' });
});

app.post('/api/licences', (req, res) => {
  res
    .status(201)
    .set('Location', '/api/licences/42')
    .json({ id: '42' });
});

app.post('/api/licences', async (request, reply) => {
  reply.code(201).header('Location', '/api/licences/42');
  return { id: '42' };
});

app.post('/api/licences', async (request, reply) => {
  reply.code(201).header('Location', '/api/licences/42');
  return { id: '42' };
});

app.get('/robots.txt', (req, res) => {
  res.type('text/plain').send('User-agent: *\nDisallow: /');
});

app.get('/robots.txt', (req, res) => {
  res.type('text/plain').send('User-agent: *\nDisallow: /');
});

app.get('/robots.txt', async (request, reply) => {
  reply.type('text/plain');
  return 'User-agent: *\nDisallow: /';
});

app.get('/robots.txt', async (request, reply) => {
  reply.type('text/plain');
  return 'User-agent: *\nDisallow: /';
});

app.post('/continue', (req, res) => {
  res.redirect('/next'); // 302 Found
});
app.post('/moved', (req, res) => {
  res.redirect(301, '/new-address'); // the status comes first
});

app.post('/continue', (req, res) => {
  res.redirect('/next'); // 302 Found
});
app.post('/moved', (req, res) => {
  res.redirect(301, '/new-address'); // the status comes first
});

app.post(
  '/continue',
  async (request, reply) => reply.redirect('/next'), // 302 Found
);
app.post(
  '/moved',
  async (request, reply) =>
    reply.redirect('/new-address', 301), // the status comes second
);

app.post(
  '/continue',
  async (request, reply) => reply.redirect('/next'), // 302 Found
);
app.post(
  '/moved',
  async (request, reply) =>
    reply.redirect('/new-address', 301), // the status comes second
);

// maxAge is in milliseconds; the path defaults to /
app.post('/cookies', (req, res) => {
  res.cookie('analytics', 'rejected', {
    httpOnly: true,
    sameSite: 'lax',
    maxAge: 365 * 24 * 60 * 60 * 1000,
  });
  res.redirect('/cookies');
});

// maxAge is in milliseconds; the path defaults to /
app.post('/cookies', (req, res) => {
  res.cookie('analytics', 'rejected', {
    httpOnly: true,
    sameSite: 'lax',
    maxAge: 365 * 24 * 60 * 60 * 1000,
  });
  res.redirect('/cookies');
});

// maxAge is in seconds; with no path, the browser uses the page's folder
app.post('/cookies', async (request, reply) => {
  reply.setCookie('analytics', 'rejected', {
    httpOnly: true,
    sameSite: 'lax',
    maxAge: 365 * 24 * 60 * 60,
    path: '/',
  });
  return reply.redirect('/cookies');
});

// maxAge is in seconds; with no path, the browser uses the page's folder
app.post('/cookies', async (request, reply) => {
  reply.setCookie('analytics', 'rejected', {
    httpOnly: true,
    sameSite: 'lax',
    maxAge: 365 * 24 * 60 * 60,
    path: '/',
  });
  return reply.redirect('/cookies');
});

// app.locals reaches every template; res.locals reaches
// the templates rendered for this one request
app.locals.serviceName = 'Apply for a juggling licence';
app.use((req, res, next) => {
  res.locals.phase = 'beta';
  next();
});
app.get('/about', (req, res) => {
  res.render('about', { title: 'About this service' });
});

// app.locals reaches every template; res.locals reaches
// the templates rendered for this one request
app.locals.serviceName = 'Apply for a juggling licence';
app.use((req, res, next) => {
  res.locals.phase = 'beta';
  next();
});
app.get('/about', (req, res) => {
  res.render('about', { title: 'About this service' });
});

// defaultContext reaches every template; reply.locals reaches
// the templates rendered for this one request
await app.register(fastifyView, {
  engine: { nunjucks },
  templates: join(import.meta.dirname, '..', 'views'),
  viewExt: 'njk',
  defaultContext: {
    serviceName: 'Apply for a juggling licence',
  },
});
app.addHook('onRequest', async (request, reply) => {
  reply.locals = { phase: 'beta' };
});
app.get('/about', async (request, reply) =>
  reply.view('about', { title: 'About this service' }),
);

// defaultContext reaches every template; reply.locals reaches
// the templates rendered for this one request
await app.register(fastifyView, {
  engine: { nunjucks },
  templates: join(import.meta.dirname, '..', 'views'),
  viewExt: 'njk',
  defaultContext: {
    serviceName: 'Apply for a juggling licence',
  },
});
app.addHook('onRequest', async (request, reply) => {
  reply.locals = { phase: 'beta' };
});
app.get('/about', async (request, reply) =>
  reply.view('about', { title: 'About this service' }),
);

// middleware that answers the request itself,
// and so never calls next()
app.use('/admin', (req, res, next) => {
  if (req.get('x-staff') !== 'yes') {
    return res.status(403).send('staff only');
  }
  next();
});
app.get('/admin', (req, res) => {
  res.send('admin home');
});

// middleware that answers the request itself,
// and so never calls next()
app.use('/admin', (req, res, next) => {
  if (req.get('x-staff') !== 'yes') {
    return res.status(403).send('staff only');
  }
  next();
});
app.get('/admin', (req, res) => {
  res.send('admin home');
});

// a hook that answers the request itself, so the route never runs
await app.register(
  async (admin) => {
    admin.addHook('onRequest', async (request, reply) => {
      if (request.headers['x-staff'] !== 'yes') {
        return reply.code(403).send('staff only');
      }
    });
    admin.get('/', async () => 'admin home');
  },
  { prefix: '/admin' },
);

// a hook that answers the request itself, so the route never runs
await app.register(
  async (admin) => {
    admin.addHook('onRequest', async (request, reply) => {
      if (request.headers['x-staff'] !== 'yes') {
        return reply.code(403).send('staff only');
      }
    });
    admin.get('/', async () => 'admin home');
  },
  { prefix: '/admin' },
);

Schemas Fastify only#

A Fastify route can carry a JSON Schema for its body, query string and parameters, and one for each response status. Fastify checks the request against them with Ajv before your handler runs. It then writes the reply from the response schema.

app.post(
  '/api/licences',
  {
    schema: {
      body: {
        type: 'object',
        required: ['fullName', 'props'],
        properties: {
          fullName: { type: 'string', minLength: 1 },
          props: {
            type: 'array',
            items: { enum: ['clubs', 'rings', 'knives'] },
          },
          years: {
            type: 'integer',
            minimum: 0,
            default: 0,
          },
        },
        additionalProperties: false,
      },
      response: {
        201: {
          type: 'object',
          properties: {
            id: { type: 'string' },
            fullName: { type: 'string' },
            props: {
              type: 'array',
              items: { type: 'string' },
            },
            years: { type: 'integer' },
          },
        },
      },
    },
  },
  async (request, reply) => {
    reply.code(201);
    const body = request.body as Record<string, unknown>;
    return { id: 'JL-0042', ...body, note: 'never sent' };
  },
);

app.post(
  '/api/licences',
  {
    schema: {
      body: {
        type: 'object',
        required: ['fullName', 'props'],
        properties: {
          fullName: { type: 'string', minLength: 1 },
          props: {
            type: 'array',
            items: { enum: ['clubs', 'rings', 'knives'] },
          },
          years: {
            type: 'integer',
            minimum: 0,
            default: 0,
          },
        },
        additionalProperties: false,
      },
      response: {
        201: {
          type: 'object',
          properties: {
            id: { type: 'string' },
            fullName: { type: 'string' },
            props: {
              type: 'array',
              items: { type: 'string' },
            },
            years: { type: 'integer' },
          },
        },
      },
    },
  },
  async (request, reply) => {
    reply.code(201);
    const body = request.body;
    return { id: 'JL-0042', ...body, note: 'never sent' };
  },
);

Fastify turns on three Ajv settings that change the data as it checks it:

• coerceTypes: '3' becomes 3 where the schema says integer. Every form field arrives as text, so this matters.
• useDefaults: a missing years becomes 0.
• removeAdditional: with additionalProperties: false, fields the schema does not list are removed, not refused.

The 400 is JSON, with statusCode, error, message, and code set to FST_ERR_VALIDATION. That suits an API, not a GOV.UK form. The query string works the same way, and a bad value such as ?page=abc gets "querystring/page must be integer":

// the query string is converted to the schema's types,
// and a default fills in a missing value
app.get<{ Querystring: { page: number } }>(
  '/api/licences',
  {
    schema: {
      querystring: {
        type: 'object',
        properties: {
          page: { type: 'integer', minimum: 1, default: 1 },
        },
      },
    },
  },
  async (request) => ({ page: request.query.page }),
);

// the query string is converted to the schema's types,
// and a default fills in a missing value
app.get(
  '/api/licences',
  {
    schema: {
      querystring: {
        type: 'object',
        properties: {
          page: { type: 'integer', minimum: 1, default: 1 },
        },
      },
    },
  },
  async (request) => ({ page: request.query.page }),
);

For a form, set attachValidation: true. Fastify then keeps the failure on request.validationError and runs your handler, which can show the page again with GOV.UK error messages:

// a form post: keep the validation error, and show the page
// again with GOV.UK error messages instead of a 400
const messages: Record<string, string> = {
  fullName: 'Enter your full name',
};
const fieldOf = (e: FastifySchemaValidationError) =>
  e.keyword === 'required'
    ? String(e.params.missingProperty)
    : e.instancePath.slice(1);
app.post(
  '/name',
  {
    attachValidation: true,
    schema: {
      body: {
        type: 'object',
        required: ['fullName'],
        properties: {
          fullName: { type: 'string', minLength: 1 },
        },
      },
    },
  },
  async (request, reply) => {
    if (request.validationError) {
      const errors = request.validationError.validation.map(
        (e: FastifySchemaValidationError) => ({
          field: fieldOf(e),
          text: messages[fieldOf(e)],
        }),
      );
      // a real page renders its template with these
      return errorView(errors);
    }
    return reply.redirect('/email');
  },
);

// a form post: keep the validation error, and show the page
// again with GOV.UK error messages instead of a 400
const messages = {
  fullName: 'Enter your full name',
};
const fieldOf = (e) =>
  e.keyword === 'required'
    ? String(e.params.missingProperty)
    : e.instancePath.slice(1);
app.post(
  '/name',
  {
    attachValidation: true,
    schema: {
      body: {
        type: 'object',
        required: ['fullName'],
        properties: {
          fullName: { type: 'string', minLength: 1 },
        },
      },
    },
  },
  async (request, reply) => {
    if (request.validationError) {
      const errors = request.validationError.validation.map(
        (e) => ({
          field: fieldOf(e),
          text: messages[fieldOf(e)],
        }),
      );
      // a real page renders its template with these
      return errorView(errors);
    }
    return reply.redirect('/email');
  },
);

Read it: a renewals plugin#

Here is a Fastify plugin written the way a team might write one, for renewing a licence. The service registers it with app.register(renewalRoutes, { prefix: '/renew' }). Read the code first, then the notes.

type Renewal = {
  Params: { ref: string };
  Body: { years: number };
};

const loadLicence: preHandlerAsyncHookHandler = async (
  request,
  reply,
) => {
  const { ref } = request.params as Renewal['Params'];
  const licence = await findLicence(ref);
  if (!licence) {
    reply.callNotFound();
    return reply;
  }
  reply.locals = { ...reply.locals, licence };
};

export const renewalRoutes: FastifyPluginAsync = async (
  app,
) => {
  app.get<Renewal>(
    '/:ref',
    { preHandler: loadLicence },
    async (request, reply) => reply.view('renew', {}),
  );

  app.post<Renewal>(
    '/:ref',
    {
      preHandler: loadLicence,
      attachValidation: true,
      schema: {
        body: {
          type: 'object',
          required: ['years'],
          properties: {
            years: { type: 'integer', enum: [1, 3, 5] },
          },
        },
      },
    },
    async (request, reply) => {
      if (request.validationError) {
        return reply.view('renew', {
          error: 'Select how many years to renew for',
        });
      }
      request.log.info(
        {
          ref: request.params.ref,
          years: request.body.years,
        },
        'licence renewed',
      );
      return reply.redirect(
        `/renew/${request.params.ref}/done`,
        303,
      );
    },
  );
};

const loadLicence = async (request, reply) => {
  const { ref } = request.params;
  const licence = await findLicence(ref);
  if (!licence) {
    reply.callNotFound();
    return reply;
  }
  reply.locals = { ...reply.locals, licence };
};

export const renewalRoutes = async (app) => {
  app.get(
    '/:ref',
    { preHandler: loadLicence },
    async (request, reply) => reply.view('renew', {}),
  );

  app.post(
    '/:ref',
    {
      preHandler: loadLicence,
      attachValidation: true,
      schema: {
        body: {
          type: 'object',
          required: ['years'],
          properties: {
            years: { type: 'integer', enum: [1, 3, 5] },
          },
        },
      },
    },
    async (request, reply) => {
      if (request.validationError) {
        return reply.view('renew', {
          error: 'Select how many years to renew for',
        });
      }
      request.log.info(
        {
          ref: request.params.ref,
          years: request.body.years,
        },
        'licence renewed',
      );
      return reply.redirect(
        `/renew/${request.params.ref}/done`,
        303,
      );
    },
  );
};

Write it: a date of birth page#

The task: add a page that asks for a date of birth, checks it the way the Design System says, and saves it. The finished code runs in both services. Its test tries an empty date, a missing month, 31 February, a future date and a real one.

1. The template. The date input macro draws three fields: dob-day, dob-month and dob-year. A field gets the error class only when the rule highlights it.

{% set bad = dobError.highlight if dobError else [] %}
{{ govukDateInput({
  id: "dob",
  namePrefix: "dob",
  fieldset: {
    legend: {
      text: title,
      isPageHeading: true,
      classes: "govuk-fieldset__legend--l"
    }
  },
  hint: { text: "For example, 27 3 2007" },
  errorMessage: { text: dobError.text } if dobError else false,
  items: [
    {
      name: "day",
      value: values.day,
      classes: "govuk-input--width-2" ~ (" govuk-input--error" if "day" in bad)
    },
    {
      name: "month",
      value: values.month,
      classes: "govuk-input--width-2" ~ (" govuk-input--error" if "month" in bad)
    },
    {
      name: "year",
      value: values.year,
      classes: "govuk-input--width-4" ~ (" govuk-input--error" if "year" in bad)
    }
  ]
}) }}

2. The rule. It gives one message at a time, in the Design System's order: nothing entered, a missing part, a year without four digits, a date that cannot exist, then a date in the future. JavaScript's Date quietly turns 31 February into a day in March, so the rule builds the date and checks that the day, month and year survived.

// one message at a time, most important first, with the parts to highlight
export function validateDateOfBirth(
  parts: DateParts,
  today = new Date(),
): DateError | null {
  const missing = PARTS.filter((p) => parts[p] === '');
  if (missing.length === PARTS.length) {
    return {
      text: 'Enter your date of birth',
      highlight: PARTS,
    };
  }
  if (missing.length > 0) {
    return {
      text: `Date of birth must include a ${missing.join(' and ')}`,
      highlight: missing,
    };
  }
  if (!/^\d{4}$/.test(parts.year)) {
    return {
      text: 'Year must include 4 numbers',
      highlight: ['year'],
    };
  }
  const [day, month, year] = PARTS.map((p) =>
    Number(parts[p]),
  );
  const date = new Date(Date.UTC(year, month - 1, day));
  const real =
    /^\d{1,2}$/.test(parts.day) &&
    /^\d{1,2}$/.test(parts.month) &&
    date.getUTCFullYear() === year &&
    date.getUTCMonth() === month - 1 &&
    date.getUTCDate() === day;
  if (!real) {
    return {
      text: 'Date of birth must be a real date',
      highlight: PARTS,
    };
  }
  if (date > today) {
    return {
      text: 'Date of birth must be in the past',
      highlight: PARTS,
    };
  }
  return null;
}

// one message at a time, most important first, with the parts to highlight
export function validateDateOfBirth(
  parts,
  today = new Date(),
) {
  const missing = PARTS.filter((p) => parts[p] === '');
  if (missing.length === PARTS.length) {
    return {
      text: 'Enter your date of birth',
      highlight: PARTS,
    };
  }
  if (missing.length > 0) {
    return {
      text: `Date of birth must include a ${missing.join(' and ')}`,
      highlight: missing,
    };
  }
  if (!/^\d{4}$/.test(parts.year)) {
    return {
      text: 'Year must include 4 numbers',
      highlight: ['year'],
    };
  }
  const [day, month, year] = PARTS.map((p) =>
    Number(parts[p]),
  );
  const date = new Date(Date.UTC(year, month - 1, day));
  const real =
    /^\d{1,2}$/.test(parts.day) &&
    /^\d{1,2}$/.test(parts.month) &&
    date.getUTCFullYear() === year &&
    date.getUTCMonth() === month - 1 &&
    date.getUTCDate() === day;
  if (!real) {
    return {
      text: 'Date of birth must be a real date',
      highlight: PARTS,
    };
  }
  if (date > today) {
    return {
      text: 'Date of birth must be in the past',
      highlight: PARTS,
    };
  }
  return null;
}

The error summary links to the first field to fix:

// what the template needs: the error summary links to the first highlighted part
export function dateErrorView(error: DateError) {
  return {
    ...errorView([
      {
        field: `dob-${error.highlight[0]}`,
        text: error.text,
      },
    ]),
    dobError: error,
  };
}

// what the template needs: the error summary links to the first highlighted part
export function dateErrorView(error) {
  return {
    ...errorView([
      {
        field: `dob-${error.highlight[0]}`,
        text: error.text,
      },
    ]),
    dobError: error,
  };
}

3. The routes. A GET shows the page with any saved answer. A POST checks the answer, then either shows the page again or saves it and moves on.

export function dateOfBirthRoutes() {
  const router = Router();

  router.get('/date-of-birth', (req, res) => {
    res.render('pages/date-of-birth', {
      values: req.session.dateOfBirth ?? {},
      backLink: '/name',
    });
  });

  router.post('/date-of-birth', (req, res) => {
    const values = dateParts(req.body);
    const error = validateDateOfBirth(values);
    if (error) {
      return res.render('pages/date-of-birth', {
        values,
        ...dateErrorView(error),
        backLink: '/name',
      });
    }
    req.session.dateOfBirth = values;
    res.redirect('/check-answers');
  });

  return router;
}

export function dateOfBirthRoutes() {
  const router = Router();

  router.get('/date-of-birth', (req, res) => {
    res.render('pages/date-of-birth', {
      values: req.session.dateOfBirth ?? {},
      backLink: '/name',
    });
  });

  router.post('/date-of-birth', (req, res) => {
    const values = dateParts(req.body);
    const error = validateDateOfBirth(values);
    if (error) {
      return res.render('pages/date-of-birth', {
        values,
        ...dateErrorView(error),
        backLink: '/name',
      });
    }
    req.session.dateOfBirth = values;
    res.redirect('/check-answers');
  });

  return router;
}

export const dateOfBirthRoutes: FastifyPluginAsync = async (
  app,
) => {
  app.get('/date-of-birth', async (request, reply) =>
    reply.view('pages/date-of-birth', {
      values: request.session.dateOfBirth ?? {},
      backLink: '/name',
    }),
  );

  app.post('/date-of-birth', async (request, reply) => {
    const values = dateParts(
      request.body as Record<string, unknown>,
    );
    const error = validateDateOfBirth(values);
    if (error) {
      return reply.view('pages/date-of-birth', {
        values,
        ...dateErrorView(error),
        backLink: '/name',
      });
    }
    request.session.dateOfBirth = values;
    return reply.redirect('/check-answers');
  });
};

export const dateOfBirthRoutes = async (app) => {
  app.get('/date-of-birth', async (request, reply) =>
    reply.view('pages/date-of-birth', {
      values: request.session.dateOfBirth ?? {},
      backLink: '/name',
    }),
  );

  app.post('/date-of-birth', async (request, reply) => {
    const values = dateParts(request.body);
    const error = validateDateOfBirth(values);
    if (error) {
      return reply.view('pages/date-of-birth', {
        values,
        ...dateErrorView(error),
        backLink: '/name',
      });
    }
    request.session.dateOfBirth = values;
    return reply.redirect('/check-answers');
  });
};

declare module 'express-session' {
  interface SessionData {
    dateOfBirth: DateParts;
  }
}

declare module 'fastify' {
  interface Session {
    dateOfBirth?: DateParts;
  }
}

4. Add it to the service. Express must add the router before its error pages, so the service's createApp() takes extra routers. Fastify registers one more plugin.

// the service, with the new page added before its error pages
export function createAppWithDateOfBirth() {
  return createApp([dateOfBirthRoutes()]);
}

// the service, with the new page added before its error pages
export function createAppWithDateOfBirth() {
  return createApp([dateOfBirthRoutes()]);
}

// the service, with the new page registered as one more plugin
export async function buildAppWithDateOfBirth() {
  const app = await buildApp();
  await app.register(dateOfBirthRoutes);
  return app;
}

// the service, with the new page registered as one more plugin
export async function buildAppWithDateOfBirth() {
  const app = await buildApp();
  await app.register(dateOfBirthRoutes);
  return app;
}

Structure, errors, logging and tests#

How Express and Fastify apps are laid out, how errors and logs flow, and how to test them. It ends with the Express 4 and Fastify 4 code you will meet in older services.

How an app is laid out#

Services split into the same files in both frameworks. This book's service is laid out like this:

Keeping the app apart from the server lets a test build the app without listening on a port. Configuration comes from environment variables, read once at start-up. A missing secret should stop the service starting, not fail its first request:

export function loadConfig(
  env: NodeJS.ProcessEnv = process.env,
) {
  const production = env.NODE_ENV === 'production';
  const sessionSecret =
    env.SESSION_SECRET ??
    (production
      ? undefined
      : 'development-only-secret-of-at-least-32-characters');
  // fail at start-up, not on the first request
  if (!sessionSecret || sessionSecret.length < 32) {
    throw new Error(
      'SESSION_SECRET must be set, and at least 32 characters',
    );
  }
  return {
    production,
    port: Number(env.PORT ?? 3000),
    sessionSecret,
    licensingApi:
      env.LICENSING_API_URL ?? 'http://localhost:4000',
  };
}

export function loadConfig(env = process.env) {
  const production = env.NODE_ENV === 'production';
  const sessionSecret =
    env.SESSION_SECRET ??
    (production
      ? undefined
      : 'development-only-secret-of-at-least-32-characters');
  // fail at start-up, not on the first request
  if (!sessionSecret || sessionSecret.length < 32) {
    throw new Error(
      'SESSION_SECRET must be set, and at least 32 characters',
    );
  }
  return {
    production,
    port: Number(env.PORT ?? 3000),
    sessionSecret,
    licensingApi:
      env.LICENSING_API_URL ?? 'http://localhost:4000',
  };
}

Errors#

In both frameworks, an error thrown in a handler, or a promise that rejects, goes to the error handler. An error can carry the status to answer with: Express reads err.status or err.statusCode, and Fastify reads statusCode.

// a throw and a rejected promise both reach the error handler
app.get('/sync', () => {
  throw new Error('something broke');
});
app.get('/async', async (req, res) => {
  const licence = await findLicence('JL-0042');
  res.send(licence.ref);
});
// an error can carry the status to answer with
app.post('/renew', () => {
  throw Object.assign(
    new Error('This licence has already been renewed'),
    { status: 409 },
  );
});

// a throw and a rejected promise both reach the error handler
app.get('/sync', () => {
  throw new Error('something broke');
});
app.get('/async', async (req, res) => {
  const licence = await findLicence('JL-0042');
  res.send(licence.ref);
});
// an error can carry the status to answer with
app.post('/renew', () => {
  throw Object.assign(
    new Error('This licence has already been renewed'),
    { status: 409 },
  );
});

// a throw and a rejected promise both reach the error handler
app.get('/sync', () => {
  throw new Error('something broke');
});
app.get('/async', async () => {
  const licence = await findLicence('JL-0042');
  return licence.ref;
});
// an error can carry the status to answer with
app.post('/renew', async () => {
  throw Object.assign(
    new Error('This licence has already been renewed'),
    { statusCode: 409 },
  );
});

// a throw and a rejected promise both reach the error handler
app.get('/sync', () => {
  throw new Error('something broke');
});
app.get('/async', async () => {
  const licence = await findLicence('JL-0042');
  return licence.ref;
});
// an error can carry the status to answer with
app.post('/renew', async () => {
  throw Object.assign(
    new Error('This licence has already been renewed'),
    { statusCode: 409 },
  );
});

A request that matches no route is not an error. It goes to the not-found handler: a last middleware in Express, and setNotFoundHandler in Fastify. Express's error handler is middleware with four parameters, added after everything else.

// not found: the last middleware, reached by any request
// that nothing else answered
app.use((req, res) => {
  res
    .status(404)
    .render('problem', { title: 'Page not found' });
});
// errors: four parameters, registered after everything else
const onError: ErrorRequestHandler = (
  err,
  req,
  res,
  next,
) => {
  if (res.headersSent) return next(err);
  const status = err.status ?? 500;
  res.status(status).render('problem', {
    title:
      status === 500
        ? 'Sorry, there is a problem with the service'
        : err.message,
  });
};
app.use(onError);

// not found: the last middleware, reached by any request
// that nothing else answered
app.use((req, res) => {
  res
    .status(404)
    .render('problem', { title: 'Page not found' });
});
// errors: four parameters, registered after everything else
const onError = (err, req, res, next) => {
  if (res.headersSent) return next(err);
  const status = err.status ?? 500;
  res.status(status).render('problem', {
    title:
      status === 500
        ? 'Sorry, there is a problem with the service'
        : err.message,
  });
};
app.use(onError);

// not found: a handler of its own, not the error handler
app.setNotFoundHandler((request, reply) =>
  reply
    .code(404)
    .view('problem', { title: 'Page not found' }),
);
app.setErrorHandler(
  (
    error: { statusCode?: number; message: string },
    request,
    reply,
  ) => {
    const status = error.statusCode ?? 500;
    return reply.code(status).view('problem', {
      title:
        status === 500
          ? 'Sorry, there is a problem with the service'
          : error.message,
    });
  },
);

// not found: a handler of its own, not the error handler
app.setNotFoundHandler((request, reply) =>
  reply
    .code(404)
    .view('problem', { title: 'Page not found' }),
);
app.setErrorHandler((error, request, reply) => {
  const status = error.statusCode ?? 500;
  return reply.code(status).view('problem', {
    title:
      status === 500
        ? 'Sorry, there is a problem with the service'
        : error.message,
  });
});

Fastify's error handlers are scoped. One set inside a plugin covers only that plugin's routes, which suits an API that answers errors with JSON:

// an error handler set inside a plugin covers only that plugin's routes
await app.register(
  async (api) => {
    api.setErrorHandler(async (error, request, reply) =>
      reply
        .code(502)
        .send({ error: 'The licensing API failed' }),
    );
    api.get('/licences/:ref', async () =>
      findLicence('JL-0042'),
    );
  },
  { prefix: '/api' },
);

// an error handler set inside a plugin covers only that plugin's routes
await app.register(
  async (api) => {
    api.setErrorHandler(async (error, request, reply) =>
      reply
        .code(502)
        .send({ error: 'The licensing API failed' }),
    );
    api.get('/licences/:ref', async () =>
      findLicence('JL-0042'),
    );
  },
  { prefix: '/api' },
);

Logging#

Both frameworks log through pino, which writes one JSON object per line. Fastify builds it in, but it is off until you turn it on. Express needs pino-http. Both give every request an id, and add it to every line that request logs.

// Express has no logger: pino-http adds one, and logs each
// request when it ends; keep session cookies out of the logs
app.use(
  pinoHttp({ redact: ['req.headers.cookie'] }, stream),
);

// Express has no logger: pino-http adds one, and logs each
// request when it ends; keep session cookies out of the logs
app.use(
  pinoHttp({ redact: ['req.headers.cookie'] }, stream),
);

// the logger is built in, but off until you turn it on; its
// request lines leave out headers, so cookies stay out of the logs
const app = Fastify({ logger: { level: 'info', stream } });

// the logger is built in, but off until you turn it on; its
// request lines leave out headers, so cookies stay out of the logs
const app = Fastify({ logger: { level: 'info', stream } });

app.get('/licences/:ref', (req, res) => {
  req.log.info({ ref: req.params.ref }, 'licence viewed');
  res.send('ok');
});

app.get('/licences/:ref', (req, res) => {
  req.log.info({ ref: req.params.ref }, 'licence viewed');
  res.send('ok');
});

app.get<{ Params: { ref: string } }>(
  '/licences/:ref',
  async (request) => {
    request.log.info(
      { ref: request.params.ref },
      'licence viewed',
    );
    return 'ok';
  },
);

app.get('/licences/:ref', async (request) => {
  request.log.info(
    { ref: request.params.ref },
    'licence viewed',
  );
  return 'ok';
});

Plugins and decorators Fastify only#

Everything in Fastify is a plugin, and each plugin has its own scope. What a plugin adds, such as a hook, a decorator or an error handler, reaches only the routes inside it and the plugins it registers. fastify-plugin removes the scope, so what the plugin adds is shared with the whole app. A decorator adds a property to the app, to every request or to every reply.

// a plain plugin: what it adds stays inside it
await app.register(async (child) => {
  child.decorate('shout', (text: string) =>
    text.toUpperCase(),
  );
  child.get('/inside', async () => child.shout!('inside'));
});

// a plain plugin: what it adds stays inside it
await app.register(async (child) => {
  child.decorate('shout', (text) => text.toUpperCase());
  child.get('/inside', async () => child.shout('inside'));
});

// wrapped with fastify-plugin: what it adds is shared with the app
await app.register(
  fp(async (child) => {
    child.decorate('config', {
      serviceName: 'Apply for a juggling licence',
    });
  }),
);
app.get('/service', async function () {
  return this.config.serviceName;
});

// wrapped with fastify-plugin: what it adds is shared with the app
await app.register(
  fp(async (child) => {
    child.decorate('config', {
      serviceName: 'Apply for a juggling licence',
    });
  }),
);
app.get('/service', async function () {
  return this.config.serviceName;
});

// a request decorator: declared once, then given a new value
// for each request in a hook
app.decorateRequest('user', null);
app.addHook('onRequest', async (request) => {
  const user = request.headers['x-user'];
  request.user = typeof user === 'string' ? user : null;
});
app.get(
  '/whoami',
  async (request) => request.user ?? 'nobody',
);

// a request decorator: declared once, then given a new value
// for each request in a hook
app.decorateRequest('user', null);
app.addHook('onRequest', async (request) => {
  const user = request.headers['x-user'];
  request.user = typeof user === 'string' ? user : null;
});
app.get(
  '/whoami',
  async (request) => request.user ?? 'nobody',
);

// TypeScript learns about decorators through declaration merging
declare module 'fastify' {
  interface FastifyInstance {
    config: { serviceName: string };
    shout?: (text: string) => string;
  }
  interface FastifyRequest {
    user: string | null;
  }
}

Express has no scopes. Middleware added with app.use() reaches every route added after it, and values shared with every template go on app.locals.

type Params = { ref: string };
type Body = { years?: string };
type Query = { change?: string };

// RequestHandler<Params, ResBody, ReqBody, Query>
export const renew: RequestHandler<
  Params,
  string,
  Body,
  Query
> = (req, res) => {
  const years = Number(req.body.years ?? 1);
  const changing =
    req.query.change === 'true' ? ', changing' : '';
  res.send(
    `renew ${req.params.ref} for ${years} years${changing}`,
  );
};

// RequestHandler<Params, ResBody, ReqBody, Query>
export const renew = (req, res) => {
  const years = Number(req.body.years ?? 1);
  const changing =
    req.query.change === 'true' ? ', changing' : '';
  res.send(
    `renew ${req.params.ref} for ${years} years${changing}`,
  );
};

type Renewal = {
  Params: { ref: string };
  Body: { years?: string };
  Querystring: { change?: string };
};

export const renew: RouteHandler<Renewal> = async (
  request,
) => {
  const years = Number(request.body.years ?? 1);
  const changing =
    request.query.change === 'true' ? ', changing' : '';
  return `renew ${request.params.ref} for ${years} years${changing}`;
};

export const renew = async (request) => {
  const years = Number(request.body.years ?? 1);
  const changing =
    request.query.change === 'true' ? ', changing' : '';
  return `renew ${request.params.ref} for ${years} years${changing}`;
};

Testing an app#

Both frameworks are tested by building the app and sending it requests. With Express, the test listens on port 0, which picks a free port, and calls it with fetch. Fastify's inject() sends the request straight to the app, with no port and no network.

test('express: the health check', async () => {
  const server = createAppWithHealth().listen(0, '127.0.0.1');
  await once(server, 'listening');
  const { port } = server.address() as AddressInfo;
  try {
    const res = await fetch(
      `http://127.0.0.1:${port}/health`,
    );
    assert.equal(res.status, 200);
    assert.equal(
      res.headers.get('cache-control'),
      'no-store',
    );
    assert.deepEqual(await res.json(), {
      status: 'ok',
      version: '1.2.3',
    });
  } finally {
    server.close();
  }
});

test('express: the health check', async () => {
  const server = createAppWithHealth().listen(0, '127.0.0.1');
  await once(server, 'listening');
  const { port } = server.address();
  try {
    const res = await fetch(
      `http://127.0.0.1:${port}/health`,
    );
    assert.equal(res.status, 200);
    assert.equal(
      res.headers.get('cache-control'),
      'no-store',
    );
    assert.deepEqual(await res.json(), {
      status: 'ok',
      version: '1.2.3',
    });
  } finally {
    server.close();
  }
});

test('fastify: the health check', async () => {
  const app = await buildAppWithHealth();
  try {
    const res = await app.inject({
      method: 'GET',
      url: '/health',
    });
    assert.equal(res.statusCode, 200);
    assert.equal(res.headers['cache-control'], 'no-store');
    assert.deepEqual(res.json(), {
      status: 'ok',
      version: '1.2.3',
    });
  } finally {
    await app.close();
  }
});

test('fastify: the health check', async () => {
  const app = await buildAppWithHealth();
  try {
    const res = await app.inject({
      method: 'GET',
      url: '/health',
    });
    assert.equal(res.statusCode, 200);
    assert.equal(res.headers['cache-control'], 'no-store');
    assert.deepEqual(res.json(), {
      status: 'ok',
      version: '1.2.3',
    });
  } finally {
    await app.close();
  }
});

You will also meet supertest in Express tests. It starts the app on a free port itself, and chains its checks:

test('express: the health check, with supertest', async () => {
  await request(createAppWithHealth())
    .get('/health')
    .expect(200)
    .expect('Cache-Control', 'no-store')
    .expect({ status: 'ok', version: '1.2.3' });
});

test('express: the health check, with supertest', async () => {
  await request(createAppWithHealth())
    .get('/health')
    .expect(200)
    .expect('Cache-Control', 'no-store')
    .expect({ status: 'ok', version: '1.2.3' });
});

Reading Express 4 and Fastify 4 code#

Many services you join started on the previous major versions. The code in this section runs in the example app's tests on both versions, through npm aliases: express4 and fastify4 install the old versions beside the new.

The biggest change in Express 5 is invisible. Express 4 ignores the promise an async handler returns, so a rejection never reaches the error handler:

const app = express();
app.get('/licences/:id', async (req, res) => {
  throw new Error('licensing API failed');
});
app.use((err, req, res, next) => {
  res.status(500).send('handled: ' + err.message);
});

On Express 4 the request above gets no answer at all, and Node reports an unhandled rejection. On Express 5, the error handler answers with a 500. That is why Express 4 code wraps its async handlers, as the service in "Read it" below does.

Express 5 refuses this book's Express 4 service outright: its first Express 4 path throws a TypeError as the route is added. Fastify 4 code is similar:

const app = Fastify();

// one object shared by every request: Fastify 5 refuses this
app.decorateRequest('user', { name: 'nobody' });

app.get(
  '/licences',
  {
    // a short-hand schema: Fastify 5 needs type: 'object' and properties
    schema: { querystring: { page: { type: 'integer', default: 1 } } },
  },
  async (request) => ({
    page: request.query.page,
    route: request.routerPath, // now request.routeOptions.url
    hostname: request.hostname, // had the port in Fastify 4
  }),
);

app.get('/old', async (request, reply) =>
  reply.redirect(301, '/new'), // now reply.redirect('/new', 301)
);

Read it: an Express 4 service#

This is the kind of code you will find in an older service. Read it, then the notes.

const app = express();
app.use(bodyParser.urlencoded({ extended: false }));

// Express 4 ignores a rejected promise, so async handlers are wrapped
const wrap = (handler) => (req, res, next) =>
  Promise.resolve(handler(req, res, next)).catch(next);

app.get(
  '/licences/:id',
  wrap(async (req, res) => {
    const licence = await findLicence(req.params.id);
    if (!licence) return res.sendStatus(404);
    res.send(licence.holder);
  }),
);

app.post('/licences/:id/renew', (req, res) => {
  res.redirect('back');
});

app.get('/search/:term?', (req, res) => {
  res.send(req.params.term || 'everything');
});

app.get('/old/*', (req, res) => {
  res.redirect(301, '/new/' + req.params[0]);
});

app.use((err, req, res, next) => {
  res.status(500).send('Sorry, there is a problem with the service');
});

Write it: a health check#

The task: add /health, which a load balancer calls to decide whether to send traffic to this copy of the service. It answers with the version, is never cached, and stays out of the logs.

export function healthRoutes(version: string) {
  const router = Router();
  router.get('/health', (req, res) => {
    res.set('Cache-Control', 'no-store');
    res.json({ status: 'ok', version });
  });
  return router;
}

export function healthRoutes(version) {
  const router = Router();
  router.get('/health', (req, res) => {
    res.set('Cache-Control', 'no-store');
    res.json({ status: 'ok', version });
  });
  return router;
}

export const healthRoutes: FastifyPluginAsync<{
  version: string;
}> = async (app, options) => {
  // the load balancer calls this every few seconds:
  // keep it out of the logs
  app.get(
    '/health',
    { logLevel: 'silent' },
    async (request, reply) => {
      reply.header('Cache-Control', 'no-store');
      return { status: 'ok', version: options.version };
    },
  );
};

export const healthRoutes = async (app, options) => {
  // the load balancer calls this every few seconds:
  // keep it out of the logs
  app.get(
    '/health',
    { logLevel: 'silent' },
    async (request, reply) => {
      reply.header('Cache-Control', 'no-store');
      return { status: 'ok', version: options.version };
    },
  );
};

Fastify takes the version as a plugin option, and turns the route's logging off with logLevel: 'silent'. Adding it to the service is one line in each:

export function createAppWithHealth() {
  return createApp([healthRoutes('1.2.3')]);
}

export function createAppWithHealth() {
  return createApp([healthRoutes('1.2.3')]);
}

export async function buildAppWithHealth() {
  const app = await buildApp();
  await app.register(healthRoutes, { version: '1.2.3' });
  return app;
}

export async function buildAppWithHealth() {
  const app = await buildApp();
  await app.register(healthRoutes, { version: '1.2.3' });
  return app;
}

Its tests are the pair in "Testing an app", above.

The plumbing#

Every GOV.UK service needs the same plumbing before its first page works. Here it is in order, in both frameworks, with the traps.

Sessions#

If you have kept a token in local storage, a session works the other way round. The browser holds only an id, in a cookie, and the answers stay on the server in a session store.

app.use(
  session({
    secret: sessionSecret,
    resave: false,
    saveUninitialized: false,
    cookie: {
      httpOnly: true,
      sameSite: 'lax',
      secure: process.env.NODE_ENV === 'production',
    },
  }),
);

app.use(
  session({
    secret: sessionSecret,
    resave: false,
    saveUninitialized: false,
    cookie: {
      httpOnly: true,
      sameSite: 'lax',
      secure: process.env.NODE_ENV === 'production',
    },
  }),
);

await app.register(fastifyCookie);
await app.register(fastifySession, {
  secret: sessionSecret,
  saveUninitialized: false,
  cookie: {
    httpOnly: true,
    sameSite: 'lax',
    secure: process.env.NODE_ENV === 'production',
  },
});

await app.register(fastifyCookie);
await app.register(fastifySession, {
  secret: sessionSecret,
  saveUninitialized: false,
  cookie: {
    httpOnly: true,
    sameSite: 'lax',
    secure: process.env.NODE_ENV === 'production',
  },
});

declare module 'express-session' {
  interface SessionData {
    answers: Answers;
    reference: string;
  }
}

declare module 'fastify' {
  interface Session {
    answers?: Answers;
    reference?: string;
  }
}

CSRF protection#

Each form carries the token in a hidden _csrf field, and the server checks it on every POST.

const { csrfSynchronisedProtection, generateToken } =
  csrfSync({
    // forms post the token in a hidden field, not a header
    getTokenFromRequest: (req) => req.body?._csrf,
  });
app.use(csrfSynchronisedProtection);
app.use((req, res, next) => {
  res.locals.csrfToken = generateToken(req);
  next();
});

const { csrfSynchronisedProtection, generateToken } =
  csrfSync({
    // forms post the token in a hidden field, not a header
    getTokenFromRequest: (req) => req.body?._csrf,
  });
app.use(csrfSynchronisedProtection);
app.use((req, res, next) => {
  res.locals.csrfToken = generateToken(req);
  next();
});

await app.register(fastifyCsrf, {
  sessionPlugin: '@fastify/session',
});
app.addHook('preHandler', (request, reply, done) => {
  reply.locals = {
    cspNonce: reply.cspNonce.script,
    csrfToken: reply.generateCsrf(),
  };
  done();
});
// check the token in preHandler: the form body is parsed by then
app.addHook('preHandler', (request, reply, done) => {
  if (request.method !== 'POST') return done();
  app.csrfProtection(request, reply, done);
});

await app.register(fastifyCsrf, {
  sessionPlugin: '@fastify/session',
});
app.addHook('preHandler', (request, reply, done) => {
  reply.locals = {
    cspNonce: reply.cspNonce.script,
    csrfToken: reply.generateCsrf(),
  };
  done();
});
// check the token in preHandler: the form body is parsed by then
app.addHook('preHandler', (request, reply, done) => {
  if (request.method !== 'POST') return done();
  app.csrfProtection(request, reply, done);
});

Not found and error pages#

Both apps finish with a 404 page and an error page. A rejected CSRF token arrives as a 403, so it gets its own message.

app.use((req: Request, res: Response) => {
  res.status(404).render('error', {
    title: 'Page not found',
    message:
      'If you typed the web address, check it is correct.',
  });
});
app.use(
  (
    err: { status?: number },
    req: Request,
    res: Response,
    next: NextFunction,
  ) => {
    if (err.status === 403) {
      return res.status(403).render('error', {
        title: 'Sorry, you need to start again',
        message: 'Your form expired or was sent twice.',
      });
    }
    res.status(500).render('error', {
      title: 'Sorry, there is a problem with the service',
      message: 'Try again later.',
    });
  },
);

app.use((req, res) => {
  res.status(404).render('error', {
    title: 'Page not found',
    message:
      'If you typed the web address, check it is correct.',
  });
});
app.use((err, req, res, next) => {
  if (err.status === 403) {
    return res.status(403).render('error', {
      title: 'Sorry, you need to start again',
      message: 'Your form expired or was sent twice.',
    });
  }
  res.status(500).render('error', {
    title: 'Sorry, there is a problem with the service',
    message: 'Try again later.',
  });
});

app.setNotFoundHandler((request, reply) =>
  reply.code(404).view('error', {
    title: 'Page not found',
    message:
      'If you typed the web address, check it is correct.',
  }),
);
app.setErrorHandler(
  (error: { statusCode?: number }, request, reply) => {
    if (error.statusCode === 403) {
      return reply.code(403).view('error', {
        title: 'Sorry, you need to start again',
        message: 'Your form expired or was sent twice.',
      });
    }
    return reply.code(500).view('error', {
      title: 'Sorry, there is a problem with the service',
      message: 'Try again later.',
    });
  },
);

app.setNotFoundHandler((request, reply) =>
  reply.code(404).view('error', {
    title: 'Page not found',
    message:
      'If you typed the web address, check it is correct.',
  }),
);
app.setErrorHandler((error, request, reply) => {
  if (error.statusCode === 403) {
    return reply.code(403).view('error', {
      title: 'Sorry, you need to start again',
      message: 'Your form expired or was sent twice.',
    });
  }
  return reply.code(500).view('error', {
    title: 'Sorry, there is a problem with the service',
    message: 'Try again later.',
  });
});

Nunjucks for JSX and Razor developers#

Nunjucks is the template language GOV.UK Frontend's components are written for. This chapter starts with Nunjucks on its own, then maps JSX and Razor onto it.

Nunjucks from zero#

Nunjucks is a template engine for JavaScript, from Mozilla, installed with npm install nunjucks. A template is HTML with two kinds of tag. {{ ... }} outputs a value, escaped. {% ... %} runs logic such as if, for, set, extends, block, include and macro. It runs on the server, once per request, and the browser only ever sees the HTML it produces.

Nunjucks needs no web framework. Point it at a folder of templates, then render one with some data:

const env = nunjucks.configure(
  join(import.meta.dirname, 'views'),
  { autoescape: true },
);
return env.render('hello.njk', {
  name: '<Ada>',
  props: ['clubs', 'rings'],
});

const env = nunjucks.configure(
  join(import.meta.dirname, 'views'),
  { autoescape: true },
);
return env.render('hello.njk', {
  name: '<Ada>',
  props: ['clubs', 'rings'],
});

<h1>Hello, {{ name }}</h1>
{% if props | length %}
  <ul>
    {% for prop in props %}
      <li>{{ prop | capitalize }}</li>
    {% endfor %}
  </ul>
{% endif %}

The result is a string of HTML. The heading comes out as <h1>Hello, &lt;Ada&gt;</h1>: Nunjucks escaped the < and >, so a name can never become a tag. The capitalize filter changed each prop. Nunjucks leaves a blank line where each tag was; with those removed, the list is:

<ul>
    <li>Clubs</li>
    <li>Rings</li>
</ul>

Chapter 8 covers every expression, filter, tag and scoping rule, with a rendered example of each. This chapter maps the parts you use most onto what you know.

From JSX#

function Answers({ rows, reference }) {
  return (
    <>
      {reference && <p>Your reference is {reference}</p>}
      <dl>
        {rows.map((row) => (
          <div key={row.key}>
            <dt>{row.key}</dt>
            <dd>{row.value}</dd>
          </div>
        ))}
      </dl>
    </>
  );
}

{% if reference %}
  <p>Your reference is {{ reference }}</p>
{% endif %}
<dl>
  {% for row in rows %}
    <div>
      <dt>{{ row.key }}</dt>
      <dd>{{ row.value }}</dd>
    </div>
  {% endfor %}
</dl>

Layouts and blocks#

Layouts work like Razor's _Layout.cshtml. A page names its parent with extends, and fills the parent's named blocks, where Razor would fill sections.

@* _Layout.cshtml *@
<title>@ViewData["Title"]</title>
<main>@RenderBody()</main>
@RenderSection("Scripts", required: false)

@* Name.cshtml *@
@{
  Layout = "_Layout";
  ViewData["Title"] = "What is your full name?";
}
<form method="post">...</form>

{# layout.njk #}
<title>{% block pageTitle %}{% endblock %}</title>
<main>{% block page %}{% endblock %}</main>
{% block bodyEnd %}{% endblock %}

{# pages/name.njk #}
{% extends "layout.njk" %}
{% set title = "What is your full name?" %}
{% block page %}<form method="post">...</form>{% endblock %}

JSX and Razor, translated#

Macros, text and html#

Every GOV.UK Frontend component is a macro that takes one object of options. Most text options come in pairs: text is escaped and html is not.

To pass HTML safely, build it in a {% set %} block, where {{ reference }} is still escaped:

{% set panelHtml %}
  Your reference number<br><strong>{{ reference }}</strong>
{% endset %}
{{ govukPanel({ titleText: title, html: panelHtml }) }}

Nunjucks in depth#

The whole Nunjucks template language, with a rendered example of every feature, so that you can read any template and write your own.

The environment#

Every template is rendered by an environment: a list of template folders, some settings, and any filters and globals you add. nunjucks.configure(), which the service uses, creates one and returns it. You can also create one yourself, which makes the folders and settings explicit:

const env = new nunjucks.Environment(
  new nunjucks.FileSystemLoader([
    join(views, 'service'), // searched first
    join(views, 'shared'),
  ]),
  { autoescape: true, throwOnUndefined: false },
);

const env = new nunjucks.Environment(
  new nunjucks.FileSystemLoader([
    join(views, 'service'), // searched first
    join(views, 'shared'),
  ]),
  { autoescape: true, throwOnUndefined: false },
);

An environment searches its folders in order, and uses the first template it finds with the name asked for:

Expressions#

Inside {{ }} and {% %}, Nunjucks has most of JavaScript's operators, and a few of its own. Given a reference, a fee of 20 for 3 years, and a user with no address, this template:

{{ "Licence " ~ ref }} |
{{ fee * years }} |
{{ 7 // 2 }} |
{{ "yes" if fire else "no" }} |
{{ "clubs" in props }} |
{{ name.toUpperCase() }} |
{{ r/^JL-\d{4}$/.test(ref) }} |
[{{ user.address.postcode }}]

renders Licence JL-0042 | 60 | 3 | no | true | ADA | true | [].

Filters, tests and globals#

A filter changes a value: {{ value | filter }}, or {{ value | filter(argument) }}, and filters chain from left to right. A test asks a question, as in {% if count is odd %}. A global is a function that every template can call. The tables below list every one that Nunjucks 3.2.4 has, and the example app's tests render each example and check the output shown.

if and for#

if takes elif and else. for loops over a list, over an object's keys and values, or over anything iterable such as a Map. Its else runs when there is nothing to loop over. Inside the loop, loop tells you where you are. A minus sign inside a tag's brackets removes the whitespace on that side of the tag:

{% for prop in props -%}
  {{ loop.index }} of {{ loop.length }}: {{ prop }}{{ "," if not loop.last }}
{% else -%}
  No props
{%- endfor %}
{% for name, fee in fees | dictsort -%}
  {{ name }} costs £{{ fee }}.
{% endfor %}

With two props and two fees, this renders 1 of 2: clubs, 2 of 2: rings, then clubs costs £20. and rings costs £30.. With no props, the first loop renders No props.

Variables and scope#

{% set %} gives a value a name. Its block form, {% set name %}...{% endset %}, captures what the block renders. What each part of a page can see of its variables depends on how that part was reached:

{% set total = 0 %}
{% for fee in fees %}
  {% set total = total + fee %}
  {% set lastFee = fee %}
{% endfor %}
Total: {{ total }}. Last fee: [{{ lastFee }}]

With fees of 20 and 30, this renders Total: 50. Last fee: []. The set inside the loop changed total, which existed before the loop. But lastFee began inside the loop, and ended with it.

{% set name = "Ada" %}
{% from "macros/greet.njk" import greet %}
{% from "macros/greet.njk" import greet as greetWithContext with context %}
1. {% include "partials/greeting.njk" %}
2. {{ greet() }}
3. {{ greetWithContext() }}

This renders 1. Hello, Ada, 2. Hello, and 3. Hello, Ada. The include sees name. The imported macro does not, until it is imported with context.

Macros and caller#

A macro is Nunjucks's component: a named piece of template with arguments. An argument can have a default, and a call can name its arguments, as box("Before you start", tone="warning") does. A macro called with {% call %} gets the content between the tags as caller(), the way a React component gets children:

function Box({ title, tone = 'info', children }) {
  return (
    <div className={`app-box app-box--${tone}`}>
      <h2 className="govuk-heading-m">{title}</h2>
      {children}
    </div>
  );
}

<Box title="Before you start" tone="warning">
  <p>You need your fire safety certificate number.</p>
</Box>

{% macro box(title, tone="info") %}
<div class="app-box app-box--{{ tone }}">
  <h2 class="govuk-heading-m">{{ title }}</h2>
  {% if caller %}{{ caller() }}{% endif %}
</div>
{% endmacro %}

{% from "macros/boxes.njk" import box %}
{% call box("Before you start", tone="warning") %}
  <p>You need your fire safety certificate number.</p>
{% endcall %}
{{ box("Nothing inside") }}

A macro's output is marked safe, so its HTML is not escaped when you print it. The values printed inside the macro are escaped as usual.

Inheritance and super()#

A page extends one parent, and fills the parent's blocks. {{ super() }} inside a block prints what the parent had there, so a page can add to a block instead of replacing it:

<title>{% block title %}{{ serviceName }}{% endblock %}</title>
<main>{% block content %}<p>No content yet.</p>{% endblock %}</main>

{% extends "base.njk" %}
{% block title %}Your licence – {{ super() }}{% endblock %}
{% block content %}<p>Licence {{ ref }}</p>{% endblock %}

Rendered with a reference, the page's title is "Your licence – Apply for a juggling licence". The parent comes from the shared folder, found by the search in the figure above.

Globals and filters of your own#

An environment takes new globals and filters from JavaScript. A global is a value or a function that every template can use, imported macros included. A filter is a function that gets the value before the | first, then any arguments. "Write it" below adds one.

// a global reaches every template, and every macro
env.addGlobal(
  'serviceName',
  'Apply for a juggling licence',
);

// a global reaches every template, and every macro
env.addGlobal(
  'serviceName',
  'Apply for a juggling licence',
);

Escaping, exactly#

With autoescaping on, every output is escaped unless the value is marked safe. These five lines show each case:

1. {{ comment }}
2. {{ comment | escape | nl2br | safe }}
{% set message %}<b>{{ name }}</b>{% endset %}
3. {{ message }}
4. {{ message | safe }}
5. {{ tag }}

// HTML built in JavaScript is escaped like any value,
// unless you mark it safe
export const approvedTag = new nunjucks.runtime.SafeString(
  '<strong class="govuk-tag">Approved</strong>',
);

// HTML built in JavaScript is escaped like any value,
// unless you mark it safe
export const approvedTag = new nunjucks.runtime.SafeString(
  '<strong class="govuk-tag">Approved</strong>',
);

Given a comment of <i>one</i> and a line break, and a name of <Ada>, the lines render:

1. <i>one</i>: the value is escaped.
2. &lt;i&gt;one&lt;/i&gt;<br />: escaped first, then only the line break becomes a tag.
3. <b><Ada></b>: a set block is escaped again when printed, so its own tags show, and the name is escaped twice.
4. <b>&lt;Ada&gt;</b>: the block marked safe. Its own HTML stays, and the name is escaped once.
5. <strong class="govuk-tag">Approved</strong>: HTML built in JavaScript and marked safe there.

When a template fails#

Read it: the service's layout#

Every page in the service extends this layout. You have seen parts of it. Here it is whole.

{# The layout every page extends: GOV.UK Frontend's page template plus the service's own
   pieces. Used by the Express and Fastify apps. Quoted in chapters 05, 06 and 08. #}
{% extends "govuk/template.njk" %}
{% from "govuk/components/back-link/macro.njk" import govukBackLink %}
{% from "govuk/components/error-summary/macro.njk" import govukErrorSummary %}

{% block pageTitle %}
  {{- "Error: " if errorList }}{{ title }} – {{ serviceName }} – GOV.UK
{%- endblock %}

{% block head %}
  <link rel="stylesheet" href="/govuk/govuk-frontend.min.css">
{% endblock %}

{% block beforeContent %}
  {% if backLink %}
    {{ govukBackLink({ text: "Back", href: backLink }) }}
  {% endif %}
{% endblock %}

{% block content %}
  <div class="govuk-grid-row">
    <div class="govuk-grid-column-two-thirds">
      {% if errorList %}
        {{ govukErrorSummary({
          titleText: "There is a problem",
          errorList: errorList
        }) }}
      {% endif %}
      {% block page %}{% endblock %}
    </div>
  </div>
{% endblock %}

{% block bodyEnd %}
  <script type="module" src="/govuk/govuk-frontend.min.js"></script>
  <script type="module" nonce="{{ cspNonce }}">
    import { initAll } from "/govuk/govuk-frontend.min.js"
    initAll()
  </script>
{% endblock %}

Write it: a date filter and an answer macro#

The task: a summary of answers in which an empty answer says "Not provided", and a date of birth shows in GOV.UK's style, such as 4 June 2017, with no comma.

1. The filter. Add it to the environment. It gets the value from the left of the |:

// a filter gets the value before the | first, then its arguments;
// GOV.UK style writes dates as 4 June 2017
env.addFilter('govukDate', (iso: string) => {
  const date = new Date(`${iso}T00:00:00Z`);
  if (Number.isNaN(date.getTime())) return iso;
  return new Intl.DateTimeFormat('en-GB', {
    day: 'numeric',
    month: 'long',
    year: 'numeric',
    timeZone: 'UTC',
  }).format(date);
});

// a filter gets the value before the | first, then its arguments;
// GOV.UK style writes dates as 4 June 2017
env.addFilter('govukDate', (iso) => {
  const date = new Date(`${iso}T00:00:00Z`);
  if (Number.isNaN(date.getTime())) return iso;
  return new Intl.DateTimeFormat('en-GB', {
    day: 'numeric',
    month: 'long',
    year: 'numeric',
    timeZone: 'UTC',
  }).format(date);
});

2. The macro. The minus signs inside its tags keep its output on one line:

{% macro answer(value, empty="Not provided") -%}
  {%- if value -%}
    {{ value }}
  {%- else -%}
    <span class="app-not-provided">{{ empty }}</span>
  {%- endif -%}
{%- endmacro %}

3. Use both. A filter's result can be a macro's argument:

{% from "macros/answers.njk" import answer %}
<dl class="govuk-summary-list">
  {% for row in rows %}
    <div class="govuk-summary-list__row">
      <dt class="govuk-summary-list__key">{{ row.label }}</dt>
      <dd class="govuk-summary-list__value">{{ answer(row.value) }}</dd>
    </div>
  {% endfor %}
  <div class="govuk-summary-list__row">
    <dt class="govuk-summary-list__key">Date of birth</dt>
    <dd class="govuk-summary-list__value">{{ answer(dateOfBirth | govukDate) }}</dd>
  </div>
</dl>

The test renders it with an empty email and a date of birth of 1990-05-12. The email shows "Not provided", the date shows "12 May 1990", and a name with angle brackets is escaped inside the macro.

GOV.UK Frontend#

GOV.UK Frontend gives you the page template, the components as macros, and the CSS, fonts and JavaScript behind them. This chapter wires all of it into a service, for version 6.5.0.

Where the files live#

Everything comes from GOV.UK Frontend, the govuk-frontend package. Nunjucks needs its dist folder, so a template can say govuk/template.njk. The browser needs the fonts and images at /assets, because the compiled CSS asks for them there.

export const paths = {
  // lets a template say {% extends "govuk/template.njk" %}
  govukViews: frontend,
  // the fonts and images GOV.UK Frontend's CSS asks for at /assets
  govukAssets: join(frontend, 'govuk', 'assets'),
  // govuk-frontend.min.css and govuk-frontend.min.js
  govukDist: join(frontend, 'govuk'),
  views: join(root, 'views'),
};

export const paths = {
  // lets a template say {% extends "govuk/template.njk" %}
  govukViews: frontend,
  // the fonts and images GOV.UK Frontend's CSS asks for at /assets
  govukAssets: join(frontend, 'govuk', 'assets'),
  // govuk-frontend.min.css and govuk-frontend.min.js
  govukDist: join(frontend, 'govuk'),
  views: join(root, 'views'),
};

app.use('/assets', express.static(paths.govukAssets));
app.use('/govuk', express.static(paths.govukDist));

app.use('/assets', express.static(paths.govukAssets));
app.use('/govuk', express.static(paths.govukDist));

await app.register(fastifyStatic, {
  root: paths.govukAssets,
  prefix: '/assets/',
});
await app.register(fastifyStatic, {
  root: paths.govukDist,
  prefix: '/govuk/',
  decorateReply: false,
});

await app.register(fastifyStatic, {
  root: paths.govukAssets,
  prefix: '/assets/',
});
await app.register(fastifyStatic, {
  root: paths.govukDist,
  prefix: '/govuk/',
  decorateReply: false,
});

The page template#

Your layout extends govuk/template.njk and fills its blocks. The stylesheet goes in head, and the JavaScript goes in bodyEnd:

{% block head %}
  <link rel="stylesheet" href="/govuk/govuk-frontend.min.css">
{% endblock %}

{% block bodyEnd %}
  <script type="module" src="/govuk/govuk-frontend.min.js"></script>
  <script type="module" nonce="{{ cspNonce }}">
    import { initAll } from "/govuk/govuk-frontend.min.js"
    initAll()
  </script>
{% endblock %}

The script must be a module. GOV.UK Frontend's documentation loads govuk-frontend.min.js with type="module", then calls initAll(), which starts every component on the page.

The inline script and your CSP#

The page template starts with a one-line inline script that adds the js-enabled and govuk-frontend-supported classes. A Content Security Policy (CSP) blocks inline scripts unless they carry a nonce: a random value that changes on every request. The template adds one when you pass cspNonce, and the module script above uses the same value.

app.use((req, res, next) => {
  res.locals.cspNonce = randomBytes(16).toString('hex');
  next();
});
app.use(
  helmet({
    contentSecurityPolicy: {
      directives: {
        scriptSrc: [
          "'self'",
          (req, res) =>
            `'nonce-${(res as Response).locals.cspNonce}'`,
        ],
      },
    },
  }),
);

app.use((req, res, next) => {
  res.locals.cspNonce = randomBytes(16).toString('hex');
  next();
});
app.use(
  helmet({
    contentSecurityPolicy: {
      directives: {
        scriptSrc: [
          "'self'",
          (req, res) => `'nonce-${res.locals.cspNonce}'`,
        ],
      },
    },
  }),
);

await app.register(fastifyHelmet, {
  enableCSPNonces: true,
});

await app.register(fastifyHelmet, {
  enableCSPNonces: true,
});

The Fastify version hands reply.cspNonce.script to every page through reply.locals, in the hook shown in chapter 6.

Using a component#

Import a component's macro, then call it with one object of options. Copy the call from the Nunjucks tab of the component's page on the Design System site, then change the options:

{{ govukRadios({
  name: "fire",
  idPrefix: "fire",
  fieldset: {
    legend: {
      text: title,
      classes: "govuk-fieldset__legend--l",
      isPageHeading: true
    }
  },
  hint: { text: "This includes torches, clubs and poi" },
  classes: "govuk-radios--inline",
  items: [
    { value: "yes", text: "Yes" },
    { value: "no", text: "No" }
  ],
  value: values.fire,
  errorMessage: fieldErrors.fire
}) }}

Three options do most of the work. value decides which answer shows as chosen. errorMessage shows the field's error. isPageHeading makes the label or legend the page's h1.

What every component macro shares#

Every GOV.UK Frontend macro takes one object of options, and most of them share these names. Knowing them lets you read any macro call, and write your own:

A component of your own#

When the Design System has nothing for what you need, write a component in the same shape, so that the rest of the team can read it. GOV.UK Frontend splits each component into a macro and a template. The macro includes the template, which reads params:

{% macro appLicenceCard(params) %}
  {%- include "./template.njk" -%}
{% endmacro %}

{% from "govuk/macros/attributes.njk" import govukAttributes -%}
<div class="app-licence-card {%- if params.classes %} {{ params.classes }}{% endif %}"
  {{- govukAttributes(params.attributes) }}>
  <h2 class="govuk-heading-s">
    {{ params.titleHtml | safe if params.titleHtml else params.titleText }}
  </h2>
  <p class="govuk-body">Reference: {{ params.reference }}</p>
  {% if caller %}{{ caller() }}{% endif %}
</div>

Calling it looks like calling any GOV.UK Frontend component:

{% from "components/licence-card/macro.njk" import appLicenceCard %}
{% call appLicenceCard({
  titleText: "Juggling licence",
  reference: "JL-0042",
  classes: "app-licence-card--active",
  attributes: { "data-licence": "JL-0042" }
}) %}
  <p class="govuk-body">Valid until 1 October 2026.</p>
{% endcall %}

The example app's test renders it, and checks that titleText is escaped, titleHtml is not and wins, the classes and attributes arrive, and the content between the call tags appears.

Journeys: one thing per page#

A GOV.UK form is a journey of short pages, each asking one thing, ending with check answers and a confirmation. This chapter shows the journey as data, then as code.

The Design System's question pages pattern starts from one question per page (Design System: question pages). The question is the page heading, set as the input's label or the fieldset's legend. Every question page has a Back link at the top, and its button says Continue, not Next.

The journey as data#

The example keeps the whole journey in one object: each page's fields, and a function that picks the next page from the answers so far.

export const questions: Record<QuestionPage, Question> = {
  name: { fields: ['fullName'], next: () => 'email' },
  email: { fields: ['email'], next: () => 'fire' },
  fire: {
    fields: ['fire'],
    next: (answers) =>
      answers.fire?.fire === 'yes'
        ? 'fire-certificate'
        : 'check-answers',
  },
  'fire-certificate': {
    fields: ['certificate'],
    next: () => 'check-answers',
  },
};

export const questions = {
  name: { fields: ['fullName'], next: () => 'email' },
  email: { fields: ['email'], next: () => 'fire' },
  fire: {
    fields: ['fire'],
    next: (answers) =>
      answers.fire?.fire === 'yes'
        ? 'fire-certificate'
        : 'check-answers',
  },
  'fire-certificate': {
    fields: ['certificate'],
    next: () => 'check-answers',
  },
};

From that object, route() works out which pages the user can reach. The GET route in chapter 3 uses it to stop anyone skipping ahead by typing an address.

// The pages a user can reach with their answers so far, in
// order. It stops at the first page they have not answered,
// or at check-answers once every page on the route is done.
export function route(answers: Answers): string[] {
  const pages: string[] = [];
  let page: string = firstPage;
  while (isQuestion(page)) {
    pages.push(page);
    if (!answers[page]) return pages;
    page = questions[page].next(answers);
  }
  return [...pages, page];
}

// The pages a user can reach with their answers so far, in
// order. It stops at the first page they have not answered,
// or at check-answers once every page on the route is done.
export function route(answers) {
  const pages = [];
  let page = firstPage;
  while (isQuestion(page)) {
    pages.push(page);
    if (!answers[page]) return pages;
    page = questions[page].next(answers);
  }
  return [...pages, page];
}

Check answers and confirmation#

Before the last step, show every answer on one check answers page, with a Change link for each (Design System: check answers). After a change, Continue returns the user to check answers, not through the rest of the journey. The example's nextPage() does that, unless the new answer opens a page that has not been answered yet.

router.get('/check-answers', (req, res) => {
  const answers = req.session.answers ?? {};
  const pages = route(answers);
  if (pages.at(-1) !== 'check-answers') {
    return res.redirect(`/${pages.at(-1)}`);
  }
  res.render('pages/check-answers', {
    rows: summaryRows(answers),
    backLink: backLink('check-answers', answers, false),
  });
});

router.post('/check-answers', (req, res) => {
  const answers = req.session.answers ?? {};
  if (route(answers).at(-1) !== 'check-answers') {
    return res.redirect('/');
  }
  // a real service sends the application to its API here
  req.session.answers = undefined;
  req.session.reference = newReference();
  res.redirect('/confirmation');
});

router.get('/check-answers', (req, res) => {
  const answers = req.session.answers ?? {};
  const pages = route(answers);
  if (pages.at(-1) !== 'check-answers') {
    return res.redirect(`/${pages.at(-1)}`);
  }
  res.render('pages/check-answers', {
    rows: summaryRows(answers),
    backLink: backLink('check-answers', answers, false),
  });
});

router.post('/check-answers', (req, res) => {
  const answers = req.session.answers ?? {};
  if (route(answers).at(-1) !== 'check-answers') {
    return res.redirect('/');
  }
  // a real service sends the application to its API here
  req.session.answers = undefined;
  req.session.reference = newReference();
  res.redirect('/confirmation');
});

app.get('/check-answers', async (request, reply) => {
  const answers = request.session.answers ?? {};
  const pages = route(answers);
  if (pages.at(-1) !== 'check-answers') {
    return reply.redirect(`/${pages.at(-1)}`);
  }
  return reply.view('pages/check-answers', {
    rows: summaryRows(answers),
    backLink: backLink('check-answers', answers, false),
  });
});

app.post('/check-answers', async (request, reply) => {
  const answers = request.session.answers ?? {};
  if (route(answers).at(-1) !== 'check-answers') {
    return reply.redirect('/');
  }
  // a real service sends the application to its API here
  request.session.answers = undefined;
  request.session.reference = newReference();
  return reply.redirect('/confirmation');
});

app.get('/check-answers', async (request, reply) => {
  const answers = request.session.answers ?? {};
  const pages = route(answers);
  if (pages.at(-1) !== 'check-answers') {
    return reply.redirect(`/${pages.at(-1)}`);
  }
  return reply.view('pages/check-answers', {
    rows: summaryRows(answers),
    backLink: backLink('check-answers', answers, false),
  });
});

app.post('/check-answers', async (request, reply) => {
  const answers = request.session.answers ?? {};
  if (route(answers).at(-1) !== 'check-answers') {
    return reply.redirect('/');
  }
  // a real service sends the application to its API here
  request.session.answers = undefined;
  request.session.reference = newReference();
  return reply.redirect('/confirmation');
});

The confirmation page shows the reference number and what happens next (Design System: confirmation pages). Let users come back to it; the pattern asks you to allow that whenever possible.

Validation and errors, the GOV.UK way#

GOV.UK shows an error one way: a summary at the top, a message beside the field, and "Error: " at the start of the title. This chapter builds that on the server.

The rules come from the Design System (Design System: validation):

• Always validate on the server, even if you also check in the browser.
• Validate when the user presses Continue, not when they leave a field.
• Show the page again with everything the user typed, right or wrong.
• Turn off the browser's own validation with novalidate, and do not add required to inputs.
• Start the page title with "Error: ", so screen readers announce it first.

Each summary item links to its field, and the field shows the same words (Design System: error summary). For radios, link to the first radio; for a date, link to the first field with an error. GOV.UK Frontend's JavaScript moves focus to the summary when the page loads. Together these meet WCAG 2.2 3.3.1 Error Identification and WCAG 2.2 3.3.3 Error Suggestion.

One validator for both frameworks#

The example keeps its rules in plain functions that return a field and a message. One helper turns them into what the templates need: a list for the summary, and one message per field.

// What a template needs when there are errors: a list for the
// error summary, linking to each field, and one message per
// field for the field itself.
export function errorView(errors: FieldError[]) {
  return {
    errorList: errors.map((e) => ({
      text: e.text,
      href: `#${e.field}`,
    })),
    fieldErrors: Object.fromEntries(
      errors.map((e) => [e.field, { text: e.text }]),
    ),
  };
}

// What a template needs when there are errors: a list for the
// error summary, linking to each field, and one message per
// field for the field itself.
export function errorView(errors) {
  return {
    errorList: errors.map((e) => ({
      text: e.text,
      href: `#${e.field}`,
    })),
    fieldErrors: Object.fromEntries(
      errors.map((e) => [e.field, { text: e.text }]),
    ),
  };
}

The layout adds the title prefix and the summary, so each page passes only its own field's error:

{% block pageTitle %}
  {{- "Error: " if errorList }}{{ title }} – {{ serviceName }} – GOV.UK
{%- endblock %}

{% if errorList %}
  {{ govukErrorSummary({
    titleText: "There is a problem",
    errorList: errorList
  }) }}
{% endif %}

<label asp-for="FullName">What is your full name?</label>
<span asp-validation-for="FullName"></span>
<input asp-for="FullName" />

{{ govukInput({
  label: {
    text: title,
    classes: "govuk-label--l",
    isPageHeading: true
  },
  id: "fullName",
  name: "fullName",
  value: values.fullName,
  autocomplete: "name",
  spellcheck: false,
  errorMessage: fieldErrors.fullName
}) }}

Where the rule lives#

The standards you will be assessed on#

A government service is assessed against the Service Standard, and must meet WCAG 2.2 AA. This chapter says which parts land on developers, and when.

A transactional service for central government must be assessed (Service Manual: check if you need a service assessment). Each assessment checks the service against the Service Standard's 14 points (Service Manual: agile delivery phases explains each phase).

The points that land on developers#

Read the points themselves:

• Service Standard point 5: make sure everyone can use the service
• Service Standard point 9: create a secure service which protects users' privacy
• Service Standard point 11: choose the right tools and technology
• Service Standard point 12: make new source code open
• Service Standard point 13: use and contribute to open standards, common components and patterns
• Service Standard point 14: operate a reliable service

Accessibility is a legal duty#

Public sector websites and apps must meet WCAG 2.2 at level AA, and publish an accessibility statement (Accessibility requirements for public sector websites and apps). The Design System's components and patterns do much of the work. You still own the rest: page titles (WCAG 2.2 2.4.2 Page Titled), labels (WCAG 2.2 3.3.2 Labels or Instructions), keyboard access (WCAG 2.2 2.1.1 Keyboard), and testing with assistive technology.

Cookies, and working without JavaScript#

Every service must publish a cookies page by public beta (Design System: cookies page). You do not need consent for cookies the service cannot work without, such as the session cookie. You do need consent before setting any other cookie, which means a cookie banner.

Progressive enhancement, from chapter 2, is a Service Manual rule as well: build every page to work with HTML alone, then enhance it.

On the job#

Two checklists built from every chapter's "On the job" box, and two tables for the code you will inherit.

Decode an existing repository#

1. Open package.json. express or fastify names the server, the govuk-frontend version names the components, and @dwp/govuk-casa means the journey is configured rather than written by hand.
   Chapter 01: The stack on one page
2. Pick a question page and find its two routes: a GET that renders the template, and a POST that validates, then renders again or redirects.
   Chapter 02: The request loop
3. Find where the app is created: express() or Fastify(). Read down from there. In Express, the order of app.use calls is the order a request runs. In Fastify, read each register and addHook.
   Chapter 03: Express and Fastify, from zero
4. List the routes: search for Router(, app.use( and .get( in Express, and app.register( and prefix in Fastify. Each mount path or prefix is added to the start of every route inside it.
   Chapter 04: Routes, requests and responses
5. Open the file that builds the app and read it top to bottom: the order of middleware or plugins, then the error handler. Check the Express or Fastify major version in package.json before you trust an example.
   Chapter 05: Structure, errors, logging and tests
6. Search for express-session or @fastify/session and check which store production uses. Then check that the CSRF check reads the token from the form body.
   Chapter 06: The plumbing
7. Find the folder list passed to nunjucks.configure() or to @fastify/view. Every template name, such as govuk/template.njk, is looked up in those folders, in order.
   Chapter 07: Nunjucks for JSX and Razor developers
8. When a template prints nothing where you expect a value, check the name first: Nunjucks prints nothing for anything undefined. Search the environment's set-up for addFilter and addGlobal to find the service's own filters and globals.
   Chapter 08: Nunjucks in depth
9. Check the govuk-frontend version in package.json. Version 6 code uses Sass @use; version 5 code uses @import. Then find where /assets is served.
   Chapter 09: GOV.UK Frontend
10. Find the journey's map: a next-page function or table, like questions here, or a CASA plan. It answers the question "why did Continue send me there?".
    Chapter 10: Journeys: one thing per page
11. Find where errors are built: a list for govukErrorSummary, and a message for each field's errorMessage. Check that the title starts with "Error: " when there are errors.
    Chapter 11: Validation and errors, the GOV.UK way
12. Find the service's accessibility statement, its cookies page and its last assessment report. They tell you what the team has already promised.
    Chapter 12: The standards you will be assessed on
13. In a CASA app, open the file that calls configure(). The pages hold the fields and validators, the Plan holds the routes, and the views folder holds the templates.
    Chapter 15: CASA
14. In a CASA service, start at the file that calls configure(). The pages hold the fields and validators, the plan the routes, and the hooks any custom work. Check which CASA major version package.json has before you trust a template's block names.
    Chapter 16: CASA in depth

What package.json tells you#

Start a new service#

1. Start from three packages: a server (Express or Fastify), nunjucks and govuk-frontend. The rest of this book adds the plumbing around them.
   Chapter 01: The stack on one page
2. Give every question page a GET and a POST. Save valid answers in the session, and always redirect after a successful POST.
   Chapter 02: The request loop
3. Choose one framework per service. CASA needs Express; Fastify gives you typed routes, schemas and scoped plugins.
   Chapter 03: Express and Fastify, from zero
4. Give each group of pages its own router or plugin at one prefix. Trust the proxy by its addresses, and set path: '/' on every Fastify cookie.
   Chapter 04: Routes, requests and responses
5. Build the app in a function the tests can call. Add an error handler that shows a GOV.UK page, a health check, and request logging with the cookie redacted.
   Chapter 05: Structure, errors, logging and tests
6. Add the plumbing in this order: headers, static files, form bodies, session, CSRF, then routes, then the 404 and error handlers.
   Chapter 06: The plumbing
7. Put a layout.njk that extends govuk/template.njk in your views folder, and make every page extend it.
   Chapter 07: Nunjucks for JSX and Razor developers
8. Turn on throwOnUndefined in tests, so that a misspelt variable fails. Give each repeated piece of markup a macro with arguments, and add filters in the environment's set-up.
   Chapter 08: Nunjucks in depth
9. Serve dist/govuk/assets at /assets, load the CSS and the module script, and pass cspNonce to every page.
   Chapter 09: GOV.UK Frontend
10. Write the journey down as data first: pages, fields and a next-page rule. Then guard every GET so users cannot skip ahead.
    Chapter 10: Journeys: one thing per page
11. Validate on the server when the user presses Continue, keep what they typed, link every summary item to its field, and put novalidate on every form.
    Chapter 11: Validation and errors, the GOV.UK way
12. Before public beta, publish a cookies page and an accessibility statement, and plan an accessibility audit.
    Chapter 12: The standards you will be assessed on
13. Start from configure() with a plan and pages, mount it on an Express app, and add your confirmation page as an ancillary route.
    Chapter 15: CASA
14. Give every validator a GOV.UK error message, dateObject as objects. Set session.secure from the environment, use a shared session store, and put pages outside the plan on the ancillary router.
    Chapter 16: CASA in depth

Versions you will inherit#

Chapter 5 runs Express 4 and Fastify 4 code beside the current versions, and chapter 16 does the same for CASA 9. This table lists the changes you will meet most.

Quick reference#

The book on one page to print, a quick reference for each tool, and where to look when the book stops.

Print this card

Express 5#

Fastify 5#

Nunjucks#

Every filter, test and global, each with a rendered example, is in the tables in chapter 8.

CASA 10#

Where the answer lives#

• GOV.UK Design System
• GOV.UK Frontend documentation
• Service Manual
• Express 5.x API reference
• Fastify reference

Libraries used in this book#

CASA OptionalExpress only#

CASA is DWP's framework for form journeys. You describe pages, fields and a plan, and CASA runs the request loop, sessions, CSRF protection and validation for you. It runs on Express only.

CASA from zero#

CASA is an npm package, @dwp/govuk-casa, and needs Node 22 or later. With CASA you do not write routes for question pages. You give it three things, and it builds the routes, the session, the CSRF protection and the validation from them:

• Pages. Each page names a waypoint, which is also its address, a template, and the fields it collects, each field with its validators.
• A plan. Which waypoint follows which, with a condition on any route that branches.
• Templates. Nunjucks pages that extend CASA's journey layout and use its casaGovuk* macros, which fill in each field's id and error message.

CASA keeps every answer in a journey context in the session, keyed by waypoint and then by field, so the full name lives at data.name.fullName. A route condition gets it as its second argument, and a hook reads it from req.casa.journeyContext. On a GET, CASA renders the waypoint's template with that page's saved answers as formData and any errors as formErrors.

The plan and the pages#

A route that branches carries a condition that reads the answers so far:

export function buildPlan(
  questions = ['name', 'email', 'fire'],
) {
  const plan = new Plan();
  plan.addSequence(...questions);
  plan.setRoute(
    'fire',
    'fire-certificate',
    (route: PlanRoute, context: JourneyContext) =>
      context.data.fire?.fire === 'yes',
  );
  plan.setRoute(
    'fire',
    'check-answers',
    (route: PlanRoute, context: JourneyContext) =>
      context.data.fire?.fire === 'no',
  );
  plan.setRoute('fire-certificate', 'check-answers');
  return plan;
}

export function buildPlan(
  questions = ['name', 'email', 'fire'],
) {
  const plan = new Plan();
  plan.addSequence(...questions);
  plan.setRoute(
    'fire',
    'fire-certificate',
    (route, context) => context.data.fire?.fire === 'yes',
  );
  plan.setRoute(
    'fire',
    'check-answers',
    (route, context) => context.data.fire?.fire === 'no',
  );
  plan.setRoute('fire-certificate', 'check-answers');
  return plan;
}

Each page names its template and its fields, and the validators hang off the fields. CASA then validates, shows the page again with errors, saves and redirects, with no route code at all:

{
  waypoint: 'name',
  view: 'pages/name.njk',
  fields: [
    field('fullName').validators([
      validators.required.make({
        errorMsg: 'Enter your full name',
      }),
    ]),
  ],
},

{
  waypoint: 'name',
  view: 'pages/name.njk',
  fields: [
    field('fullName').validators([
      validators.required.make({
        errorMsg: 'Enter your full name',
      }),
    ]),
  ],
},

{{ casaGovukInput({
  name: "fullName",
  value: formData.fullName,
  casaErrors: formErrors,
  label: {
    text: "What is your full name?",
    classes: "govuk-label--l",
    isPageHeading: true
  },
  autocomplete: "name",
  spellcheck: false
}) }}

Check answers and submitting#

The check answers page is a waypoint with no fields. A prerender hook builds the rows. A preredirect hook sends the application, ends the session with CASA's endSession(), and redirects to a confirmation route outside the plan.

const showAnswers: RequestHandler = (req, res, next) => {
  const context = req.casa.journeyContext;
  res.locals.rows = summaryRows(
    context.data,
    req.casa.plan.traverse(context),
    (page) => `/${page}?edit=true&editorigin=/check-answers`,
  );
  next();
};

const submit: RequestHandler = (req, res, next) => {
  // a real service sends req.casa.journeyContext.data to its API
  const reference = newReference();
  endSession(req, (err?: Error) => {
    if (err) return next(err);
    req.session.reference = reference;
    req.session.save(() => res.redirect('/confirmation'));
  });
};

const showAnswers = (req, res, next) => {
  const context = req.casa.journeyContext;
  res.locals.rows = summaryRows(
    context.data,
    req.casa.plan.traverse(context),
    (page) => `/${page}?edit=true&editorigin=/check-answers`,
  );
  next();
};

const submit = (req, res, next) => {
  // a real service sends req.casa.journeyContext.data to its API
  const reference = newReference();
  endSession(req, (err) => {
    if (err) return next(err);
    req.session.reference = reference;
    req.session.save(() => res.redirect('/confirmation'));
  });
};

const { mount, ancillaryRouter } = configure({
  views: [join(import.meta.dirname, 'views')],
  i18n: {
    dirs: [join(import.meta.dirname, 'locales')],
    locales: ['en'],
  },
  session: {
    secret: sessionSecret,
    secure: process.env.NODE_ENV === 'production',
  },
  pages: allPages,
  plan,
});

const { mount, ancillaryRouter } = configure({
  views: [join(import.meta.dirname, 'views')],
  i18n: {
    dirs: [join(import.meta.dirname, 'locales')],
    locales: ['en'],
  },
  session: {
    secret: sessionSecret,
    secure: process.env.NODE_ENV === 'production',
  },
  pages: allPages,
  plan,
});

const app = express();
mount(app, { serveFirstWaypoint: true });

const app = express();
mount(app, { serveFirstWaypoint: true });

CASA and the hand-rolled version#

Choose CASA for a long, form-filling journey on Express, where its plan, validation and edit mode save you code. Write the journey yourself when you are on Fastify, or when your pages do not fit the waypoint model.

CASA in depth OptionalExpress only#

Every part of CASA a service uses, from configure() to the journey context, hooks, macros and translations, and what CASA 9 code looks like.

configure(), in full#

This chapter's examples come from a second CASA app beside the service, "Renew a juggling licence". Its configure() call uses most of the options:

const { mount, ancillaryRouter } = configure({
  views: [join(import.meta.dirname, 'views')],
  i18n: {
    dirs: [join(import.meta.dirname, 'locales')],
    locales: ['en', 'cy'],
    fallbackLng: 'en',
  },
  session: {
    secret: sessionSecret,
    secure: process.env.NODE_ENV === 'production',
    ttl: 60 * 60,
    // in production: a store every copy of the service shares
    store: new MemoryStore(),
  },
  pages,
  plan,
  hooks: [
    {
      hook: 'journey.prerender',
      path: '/check-answers',
      middleware: answers,
    },
  ],
});

const { mount, ancillaryRouter } = configure({
  views: [join(import.meta.dirname, 'views')],
  i18n: {
    dirs: [join(import.meta.dirname, 'locales')],
    locales: ['en', 'cy'],
    fallbackLng: 'en',
  },
  session: {
    secret: sessionSecret,
    secure: process.env.NODE_ENV === 'production',
    ttl: 60 * 60,
    // in production: a store every copy of the service shares
    store: new MemoryStore(),
  },
  pages,
  plan,
  hooks: [
    {
      hook: 'journey.prerender',
      path: '/check-answers',
      middleware: answers,
    },
  ],
});

configure() returns everything it built. Each part can still change until you call mount(), which adds them to your Express app in a fixed order and seals them:

Pages and fields#

A page names its waypoint, its template and its fields. A field has a name, and can have processors, validators and conditions:

const tidy = (value: unknown) =>
  String(value ?? '')
    .trim()
    .toUpperCase();

const pages = [
  {
    waypoint: 'licence',
    view: 'pages/licence.njk',
    fields: [
      // processors run before the validators, and change what is saved
      field('licenceNumber')
        .processors([tidy])
        .validators([
          validators.required.make({
            errorMsg: 'renewal:licence.errors.required',
          }),
          validators.regex.make({
            pattern: /^JL-\d{4}$/,
            errorMsg: 'renewal:licence.errors.format',
          }),
        ]),
    ],
  },
  {
    waypoint: 'props',
    view: 'pages/props.njk',
    fields: [
      // CASA's checkboxes macro names the field props[], so the
      // answer is always a list, even with one box ticked
      field('props').validators([
        validators.required.make({
          errorMsg: 'renewal:props.errors.required',
        }),
        validators.inArray.make({
          source: ['clubs', 'rings', 'knives'],
          errorMsg: 'renewal:props.errors.required',
        }),
      ]),
    ],
  },
  {
    waypoint: 'fire',
    view: 'pages/fire.njk',
    fields: [
      field('fire').validators([
        validators.inArray.make({
          source: ['yes', 'no'],
          errorMsg: 'renewal:fire.errors.required',
        }),
      ]),
      // checked only when the answer on this page is yes
      field('certificate')
        .processors([tidy])
        .validators([
          validators.regex.make({
            pattern: /^FS-\d{6}$/,
            errorMsg: 'renewal:fire.errors.certificate',
          }),
        ])
        .if(
          ({
            journeyContext,
            waypoint,
          }: {
            journeyContext: JourneyContext;
            waypoint: string;
          }) => journeyContext.data[waypoint]?.fire === 'yes',
        ),
    ],
  },
  {
    waypoint: 'check-answers',
    view: 'pages/check-answers.njk',
    hooks: [{ hook: 'preredirect', middleware: submit }],
  },
];

const tidy = (value) =>
  String(value ?? '')
    .trim()
    .toUpperCase();

const pages = [
  {
    waypoint: 'licence',
    view: 'pages/licence.njk',
    fields: [
      // processors run before the validators, and change what is saved
      field('licenceNumber')
        .processors([tidy])
        .validators([
          validators.required.make({
            errorMsg: 'renewal:licence.errors.required',
          }),
          validators.regex.make({
            pattern: /^JL-\d{4}$/,
            errorMsg: 'renewal:licence.errors.format',
          }),
        ]),
    ],
  },
  {
    waypoint: 'props',
    view: 'pages/props.njk',
    fields: [
      // CASA's checkboxes macro names the field props[], so the
      // answer is always a list, even with one box ticked
      field('props').validators([
        validators.required.make({
          errorMsg: 'renewal:props.errors.required',
        }),
        validators.inArray.make({
          source: ['clubs', 'rings', 'knives'],
          errorMsg: 'renewal:props.errors.required',
        }),
      ]),
    ],
  },
  {
    waypoint: 'fire',
    view: 'pages/fire.njk',
    fields: [
      field('fire').validators([
        validators.inArray.make({
          source: ['yes', 'no'],
          errorMsg: 'renewal:fire.errors.required',
        }),
      ]),
      // checked only when the answer on this page is yes
      field('certificate')
        .processors([tidy])
        .validators([
          validators.regex.make({
            pattern: /^FS-\d{6}$/,
            errorMsg: 'renewal:fire.errors.certificate',
          }),
        ])
        .if(
          ({ journeyContext, waypoint }) =>
            journeyContext.data[waypoint]?.fire === 'yes',
        ),
    ],
  },
  {
    waypoint: 'check-answers',
    view: 'pages/check-answers.njk',
    hooks: [{ hook: 'preredirect', middleware: submit }],
  },
];

• Processors change the value before it is checked and saved. tidy turns " jl-0042 " into JL-0042.
• Conditions, added with .if(), decide whether the field's validators run. The certificate is checked only when the answer on the same page is "yes".
• Optional fields: field(name, { optional: true }) skips the validators when the field is empty.
• Nested names: field('address[postcode]') saves an object, one level deep only.

CASA saves only the fields a page lists: anything else in the form body is dropped.

Validators#

Each built-in validator is made with make(), which takes its options and an errorMsg. The message can be a string, a translation key, an object with summary and inline text, or a function that returns one of those.

The plan in depth#

addSequence() joins waypoints with routes that go both ways, so the Back link works. setRoute(from, to, condition) adds one pair of routes, and setNextRoute() and setPrevRoute() add one direction only:

const plan = new Plan({ arbiter: 'auto' });
plan.addSequence('licence', 'props', 'fire', 'check-answers');
// a waypoint the user may skip, with ?skipto=
plan.addSkippables('props');

const plan = new Plan({ arbiter: 'auto' });
plan.addSequence('licence', 'props', 'fire', 'check-answers');
// a waypoint the user may skip, with ?skipto=
plan.addSkippables('props');

• Conditions run only after the page they leave has passed validation, unless the plan is made with validateBeforeRouteCondition: false.
• Skippable waypoints can be passed with ?skipto=, as the props page's "I will not use props" link does. Skipping a page replaces its answers.
• Exit nodes, written url:///path/, send the user to another CASA app mounted in the same service.
• plan.traverse(context) lists the waypoints the user's answers lead through. The service's check answers page uses it to list the rows.
• arbiter: 'auto' lets CASA choose a Back link when old answers make two routes look valid.

The journey context#

The journey context is the user's answers and their validation state, kept in the session. Everything in CASA reads from it:

Hooks, in order#

A hook is Express middleware that CASA runs at a named point. A global hook is named with the router's scope, as journey.prerender, and can be limited to one path. A page hook leaves out the scope, and runs after the global hooks. On a GET:

On a POST, CASA runs the steps in chapter 15's figure. The example app's test records every hook and proves this order:

Templates and macros#

A waypoint's template extends casa/layouts/journey.njk, and fills two blocks. casaPageTitle gets "Error: " added when there are errors. journey_form sits inside a form with the CSRF token and the continue button. Other pages extend casa/layouts/main.njk. CASA gives every template these values:

CASA's macros wrap GOV.UK Frontend's, and take the same options, plus casaErrors and, for some, casaValue. They fill in the id, the name and the error message the way CASA expects:

A conditionally revealed field is a second macro, captured in a {% set %} block and passed as the radio item's html:

{% set certificateHtml %}
  {{ casaGovukInput({
    name: "certificate",
    value: formData.certificate,
    casaErrors: formErrors,
    label: { text: t("renewal:fire.certificate") },
    classes: "govuk-input--width-10"
  }) }}
{% endset %}
{{ casaGovukRadios({
  name: "fire",
  value: formData.fire,
  casaErrors: formErrors,
  fieldset: {
    legend: {
      text: t("renewal:fire.title"),
      classes: "govuk-fieldset__legend--l",
      isPageHeading: true
    }
  },
  items: [
    { value: "yes", text: "Yes", conditional: { html: certificateHtml } },
    { value: "no", text: "No" }
  ]
}) }}

Translations#

Each translation folder has a folder for each language, such as en and cy. Each file in it is a namespace, so renewal.json holds the keys that t("renewal:licence.title") finds. req.t() does the same in code. Adding ?lang=cy to any address switches the language, and CASA keeps the choice in the session. With fallbackLng: 'en', a key with no Welsh text shows the English.