Health Education England - Frontend prototype

This codebase contains the assets, components, templates ant tooling used to compile the frontend for Health Education England's (HEE) different websites / channels.

The compiled prototype is hosted on GitHub Pages, and can be viewed here: https://health-education-england.github.io/hee-prototypes/

It is based off the NHS UK prototype kit, making use of existing components and styles where possible. You can find more information on the NHS UK design system and it's components here.

Table of contents

1. Prerequisites
2. Getting started
3. Contributing your work
4. Tooling
5. Makefile commands
6. Codebase structure
7. App
   1. Assets
   2. Views
8. Tasks
9. Tests
10. CI / CD pipeline
11. Hosting

Prerequisites

In order to install and configure the prototype on your local machine, there are a few prerequisite tools to install:

• Git
• GNU Make utility (Install build-essential on Linux, 'Developer tools' or 'Xcode' on Mac or via homebrew, or GnuWin32 for Windows)
• Docker
• Docker compose (ships with Docker Desktop)

All other build and testing tools are run within their respective docker containers, so don't need to be installed locally.

Getting started

To get the prototype up and running you first need to run:

make install

This will pull down the nodejs docker image, and start up the docker container, and finally it will install all the dependencies defined in package.json and package-lock.json

Once complete you can run either:

make serve

This will build the prototype and serve it on a local webserver - http://localhost:3000

or

make watch

(This watches all *.scss *.js *.njk and *.html files, and rebuilds and reloads the browser when a change is detected)

Contributing your work

Before starting on your first piece of work, please see CONTRIBUTING.md for guidelines and best practices regarding HEE branching strategies etc.

Tooling

The HEE prototype uses the following tech / tooling to compile and serve the prototype:

• SASS
• JS ES6
• Nunjucks
• NHS UK front end library
• Gulp
• Babel
• Webpack
• BackstopJS (visual regression testing)
• Playwright (end to end javascript testing)
• GitHub Actions (CI / CD pipeline)
• GitHub Pages

Makefile commands

We make use of a Makefile for a better developer experience when working with the docker containers within the HEE prototype.

All commands can be run using make [command-name]

Below is a complete list of all the commands and their purposes:

install - Installs all node dependencies via npm

build - Compiles the prototype components, assets and templates into the public directory

build-prod - Same as above, except adds a basePath for Github pages to all links (used for pipeline debugging purposes)

serve - Runs the build command and starts up a local webserver serving the prototype at http://localhost:3000

watch - Runs the serve command and recompiles the codebase, reloads the browser when there is a change in any source code

npm-audit - Runs the npm audit report displaying packages which need secruity updates. Helpful to use alongside GitHub Dependabot reports.

open-shell - Opens a terminal prompt allowing you to run commands directly within the nodejs container. Useful when installing, removing, upgrading packages or general build debugging.

run-tests - Runs BackstopJS and Playwright tests. See more details in the testing README within the tests directory.

Codebase structure

Below is a high level summary of the codebase structure:

App

.
├── app
│   ├── assets
│   └── views

Assets

/app/assets/hee

HEE components containing all SASS, JS and Nunjucks assets, organised into the HEE design system definitions:

• Content
• Furniture
• Scaffolding

/app/assets/prototype

Contains all styling and JS logic related to the serving of the actual prototype itself. In other words assets which are not used in any HEE channels, but are used to display the prototype navigation, component / template previews etc.

Views

/app/views

Contains all the Nunjucks templates which are eventually compiled into flat HTML files within the public folder, used to render the HEE prototype in browser.

Tasks

Contains all the Gulp task runners, pertaining to specific parts of the build process:

• Assets - compiling stylesheets, javascript and copying other assets
• Serve - serves prototype via gulp-connect webserver
• Templates - logic for compiling component nunjucks macros and templates into flat HTML files)

├── tasks
│   ├── assets.js
│   ├── serve.js
│   └── templates.js

Tests

As mentioned in the Tooling section there are two types of tests run against all HEE components and templates:

• BackstopJS for visual regression testing
• Playwright for end to end javascript testing

For a deeper dive on how to write and run your own tests, please see the README within the tests directory:

├── tests
│   ├── backstop
│   └── playwright
│   └── README.md

CI / CD pipeline

We make use of Github Actions for our CI/CD pipeline. The prototype is compiled, tested and published using GitHub Action workflows.

For a full outline on the CI/CD build, please see the README within the .github directory.

Hosting

The compiled prototype is hosted using GitHub Pages and can be viewed here: https://health-education-england.github.io/hee-prototypes/

GH Pages have been configured to serve the prototype from the gh-pages branch, but the publishing of updates is handled in the CI / CD pipeline process above, and should not be updated manually.