Updating the kit

The way that you update the kit has recently changed.

If you are using version 8 of the kit or above, you can now update the kit by changing the version number in your package.json file and then running npm install.

If your version of the kit is version 7 or below, follow this upgrade 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.3.1",
  "nhsuk-prototype-kit": "^8.0.1"
}

In the devDependencies section, update the contents to:

"devDependencies": {
}

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

"scripts": {
  "start": "node ."
}

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 config.js file

The useAutoStoreData and useCookieSessionStore settings in the config.js are no longer needed and can be removed.

You should change the port: 2000 option to port: 3000 to continue using http://localhost:3000 in the browser.

(We’ve fixed a previous bug that added 1000 to this number.)

For example, the file could now look like this:

// Use this file to change prototype configuration.
module.exports = {
  // Service name
  serviceName: 'Service name goes here',

  // Port to run the prototype on locally
  port: 3000
}

If you added any other configuration options of your own, you should keep those if still needed.

5. 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 have 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.

6. 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.

7. Edit your app.js file

Replace the entire contents of it with this:

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 viewsPath = [
  'app/views/'
]

const entryPoints = [
  'app/assets/sass/main.scss',
  'app/assets/javascript/*.js'
]

async function init() {
  const prototype = await NHSPrototypeKit.init({
    serviceName: config.serviceName,
    buildOptions: {
      entryPoints
    },
    viewsPath,
    routes,
    locals,
    filters,
    sessionDataDefaults
  })

  prototype.start(config.port)
}

init()

const viewsPath = [
  'app/views/',
  'node_modules/nhsapp-frontend/dist/'
]

8. 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

9. Edit your layout file

You should have a layout file named app/views/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="/assets/sass/main.css" rel="stylesheet">
{% endblock %}

Update the section which references block bodyEnd to this:

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

If you have previously edited app/views/includes/scripts.html to add custom scripts, you must move them to block bodyEnd like this:

{% block bodyEnd %}
  {{ super() }}
  <script type="module" src="/assets/javascript/main.js"></script>

  <!-- Add any custom scripts -->
  <script type="module" src="/assets/javascript/custom-file-1.js"></script>
  <script type="module" src="/assets/javascript/custom-file-2.js"></script>
  <script type="module" src="/assets/javascript/custom-file-3.js"></script>
  {% block pageScripts %}{% endblock %}
{% endblock %}

You can now delete the file app/views/includes/scripts.html.

10. 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 .

[Browsersync] Access URLs:
 -----------------------------------
    Local: http://localhost:3000
 External: http://192.168.1.247:3000
 -----------------------------------
[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