Updating to version 8

Version 8 of the NHS prototype kit contains some significant changes which will make it much easier for you to update your prototype in future.

However, to upgrade to version 8 from version 7 or below involves some manual steps.

Follow this guide:

1. Check which version of Node.js you are using.

Version 8 requires you to be using either Node 22 or Node 24.

You can check which version you are currently using by running this command in your terminal:

node --version

2. Edit the package.json file

In the dependencies section, update the contents to:

"dependencies": {
  "nhsuk-frontend": "^10.2.2",
  "nhsuk-prototype-kit": "8.0.0-beta.6"
}

In the devDependencies section, update the contents to:

"devDependencies": {
}

Update the scripts section of your package.json file to:

"scripts": {
  "start": "node --watch app.js"
}

3. Delete these folders and files

Delete these folders:

• lib
• tests/lib
• docs (if present)
• middleware (if present)
• .github/ISSUE_TEMPLATE

Delete these files:

• gulpfile.js
• app/assets/javascript/auto-store-data.js (if present)
• .babelrc
• .browserslistrc
• .prettierignore
• .prettierrc.js
• .github/workflows/pull-request.yml
• .github/PULL_REQUEST_TEMPLATE.md
• .gitpod.yml
• CONTRIBUTING.md

4. Edit your locals.js file

Update the file to this:

module.exports = function(req, res, next) {

  // You can set any additional local variables here.
  // These will be made available to any views
  //
  // For example:
  //
  // req.locals.organisationName = 'NHS'

  next()
}

If you had previously edited the file to set any local variables, copy the relevant lines back in to the file, above the next() line.

You no longer need to set the serviceName variable as this is done automatically.

5. Edit your devcontainer.json file

If you have a file named .devcontainer/devcontainer.json, update the postAttachCommand line to this:

  "postAttachCommand": {
    "server": "npm start"
  },

This will make sure that your prototype still works within GitHub Codespaces.

6. Edit your app.js file

Replace the entire contents of it with this:

const { join } = require('node:path')

const NHSPrototypeKit = require('nhsuk-prototype-kit')

// Local dependencies
const config = require('./app/config')
const sessionDataDefaults = require('./app/data/session-data-defaults')
const filters = require('./app/filters')
const locals = require('./app/locals')
const routes = require('./app/routes')

const SERVICE_NAME = config.serviceName

// Set configuration variables
const port = parseInt(process.env.PORT, 10) || 2000

const viewsPath = join(__dirname, 'app/views/')

const prototype = NHSPrototypeKit.init({
  serviceName: SERVICE_NAME,
  routes: routes,
  locals: locals,
  sessionDataDefaults: sessionDataDefaults,
  viewsPath: viewsPath,
  buildOptions: {
    entryPoints: ['app/assets/sass/main.scss']
  }
})

for (const [name, filter] of Object.entries(filters())) {
  prototype.nunjucks.addFilter(name, filter)
}

prototype.start(port)

const viewsPath = [
  join(__dirname, 'app/views/'),
  join(__dirname, 'node_modules/nhsapp-frontend/dist')
]

7. Run npm install in your terminal

The install may take up to a minute.

While installing it may WARN about some items – this is okay. As long as there are no ERRORs you can continue.

You should see a message like this:

added 1251 packages, and audited 1252 packages in 7s

180 packages are looking for funding
run `npm fund` for details

found 0 vulnerabilities

8. Edit your layout file

You should have a layout file named app/layout.html.

In that file, update the lines which references block head to this:

{% block head %}
  <!-- Add your custom CSS or Sass in /app/assets/sass/main.scss -->
  <link href="/main.css" rel="stylesheet">
{% endblock %}

Update the section which references block bodyEnd to this:

{% block bodyEnd %}
  <script type="module" src="/application.js"></script>
  {{ super() }}
{% endblock %}

If you have added any custom frontend JavaScript to your prototype, you will need to add references to it here too.

9. Start your local server

In your terminal, enter: npm start

After the kit has started, you should see a message telling you that the kit is running:

> node app.js

[Browsersync] Access URLs:
 -----------------------------------
    Local: http://localhost:2001
 External: http://192.168.1.247:2001
 -----------------------------------
[Browsersync] Watching files...

Help and support

If you have any problems:

• ask a developer on your team (if you have one)
• email the service manual team at england.service-manual.nhs.net
• get in touch on the NHS digital service manual #prototype-kit Slack channel