Skip to main content

Install with Node.js package manager (npm)

Requirements

  1. Install Node.js.

    GOV.UK Frontend requires Node.js version 12.17.0 or later to support ECMAScript (ES) modules. Where possible, we recommend you install the latest Long Term Support (LTS) version.

  2. cd to the root of your project and check if you have a package.json file. If you do not have the file, create it by running:

    npm init

  3. Install Dart Sass - version 1.0.0 or higher.

    If you’re using Dart Sass 1.33.0 or greater, you might see deprecation warnings when compiling your Sass. If required, you can silence deprecation warnings caused by dependencies.

    Do not use either LibSass or Ruby Sass for new projects as they are deprecated in GOV.UK Frontend.

    Although GOV.UK Frontend currently supports LibSass (version 3.3.0 and above) and Ruby Sass (version 3.4.0 and above), we will remove support in future. If you’re using either of these Sass compilers, you should migrate to Dart Sass as soon as you reasonably can.

You can also install Nunjucks v3.0.0 or later if you want to use GOV.UK Frontend’s Nunjucks macros.

Install GOV.UK Frontend

Run:

npm install govuk-frontend --save

When the installation finishes, the govuk-frontend package will be in your node_modules folder.

Get the CSS, Assets and JavaScript working

Add the HTML for a component to your application. We recommend the accordion component as this makes it easier to spot if JavaScript is not working.

Go to the example accordion component on the GOV.UK Design System website, then copy the HTML.

Paste the HTML into a page or template in your application.

Get the CSS working

  1. Copy the /node_modules/govuk-frontend/dist/govuk/govuk-frontend.min.css file into your application.

  2. Add your CSS file to your page layout if you need to. For example:

    <head>
  <!-- // ... -->
  <link rel="stylesheet" href="<YOUR-STYLESHEETS-FOLDER>/govuk-frontend.min.css">
  <!-- // ... -->
</head>

  3. Run your application and check that the accordion displays correctly.

The accordion will use a generic font until you get the font and images working, and will not be interactive until you get the JavaScript working.

There are also different ways you can import GOV.UK Frontend’s CSS, including into your project’s main Sass file:

@import "node_modules/govuk-frontend/dist/govuk/index";

You do not need /index at the end of your import if you’re using Dart Sass, LibSass 3.6.0 or higher, or Ruby Sass 3.6.0 or higher.

Get the font and images working

Your component will not use the right font or images until you’ve added GOV.UK Frontend’s assets to your application.

  1. Copy the following 3 items:
  • /node_modules/govuk-frontend/dist/govuk/assets/images folder to <YOUR-APP>/assets/images
  • /node_modules/govuk-frontend/dist/govuk/assets/fonts folder to <YOUR-APP>/assets/fonts
  • /node_modules/govuk-frontend/dist/govuk/assets/manifest.json file to <YOUR-APP>/assets
  1. Run your application, then use the Fonts tab in Firefox Page Inspector to check the accordion is using the GDS Transport font.

In your live application, we recommend using an automated task or your build pipeline instead of copying the files manually.

Get the JavaScript working

  1. Add the following to the top of the <body class="govuk-template__body"> section of your page template:

    <script>document.body.className += ' js-enabled' + ('noModule' in HTMLScriptElement.prototype ? ' govuk-frontend-supported' : '');</script>

  2. Copy the /node_modules/govuk-frontend/dist/govuk/govuk-frontend.min.js file into your application.

  3. Import the file before the closing </body> tag of your page template, then run the initAll function to initialise all the components. For example:

    <body class="govuk-template__body">
  <!-- // ... -->
  <script type="module" src="<YOUR-JAVASCRIPTS-FOLDER>/govuk-frontend.min.js"></script>
  <script type="module">
    import { initAll } from '<YOUR-JAVASCRIPTS-FOLDER>/govuk-frontend.min.js'
    initAll()
  </script>
</body>

  4. Run your application and check it works the same way as the Design System accordion example, by selecting the buttons and checking the accordion shows and hides sections.

In your live application, we recommend:

Make sure you import all the components used throughout your application or some components will not work correctly for disabled users who use assistive technologies.

Once your testing is complete you can use the full code for page layouts and other components from the Design System website.