Skip to content

installing-with-npm.md

Latest commit

 

History

History
140 lines (92 loc) · 5.85 KB

installing-with-npm.md

File metadata and controls

140 lines (92 loc) · 5.85 KB

Installing using npm

Requirements

To use NHS.UK frontend in your projects with npm you must:

  1. Have Node.js installed. We recommend using the long-term support (LTS) version of Nodejs, which also includes npm.

  2. Have a package.json file within your project. You can create a default package.json file by running npm init -y from the root of your project.

  3. Have a pipeline set up to compile Sass files to CSS.

  4. (Optional) If you want to use our Nunjucks macros, you will need to install Nunjucks. Nunjucks macros allows you to define reusable chunks of content. It is similar to a function in a programming language.

    npm install nunjucks --save

Install dependencies

Install the NHS.UK frontend package into your project:

npm install nhsuk-frontend --save

When the installation finishes, the nhsuk-frontend package and other dependencies will be in your node_modules folder.

Configuration

You will need to import a couple of things into your project before you can start using NHS.UK frontend:

Importing styles

To build the stylesheet you will need a pipeline set up to compile Sass files to CSS. We recommend using Gulp and gulp-sass however you can use any tools that you are familiar with.

You must add the root of your application to Sass load paths, by either:

  • calling the Sass compiler from the command line with the --load-path . flag
  • using the JavaScript API with loadPaths: ['.'] in the options object

Then load the NHS.UK frontend styles by adding the following to your Sass file. You should place the below code before your own Sass rules (or Sass @forward).

@forward "node_modules/nhsuk-frontend/src/nhsuk";

Alternatively you can use NHS.UK frontend styles with a custom configuration:

@forward "node_modules/nhsuk-frontend/src/nhsuk" with (
  $nhsuk-include-font-face: false
);

Or to use only the minimum components necessary:

// Core (required)
@forward "node_modules/nhsuk-frontend/src/nhsuk/core";

// Individual component (optional)
@forward "node_modules/nhsuk-frontend/src/nhsuk/components/action-link";

Importing JavaScript

Some of our components require JavaScript to function properly, others need JavaScript to improve the usability and accessibility.

You should include NHS.UK frontend JavaScript in your project to ensure that all users can use it successfully.

Add the following JavaScript to the top of the <body> section of your page template:

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

Option 1: Include compiled JavaScript

Copy the /node_modules/nhsuk-frontend/dist/nhsuk/nhsuk-frontend.min.js script file into your application.

Include the script in the <head> of your page using the type="module" attribute.

The type="module" attribute stops Internet Explorer 11 and other older browsers running the JavaScript, which relies on features older browsers might not support and could cause errors. The script will be loaded as soon as possible, due to it being in the <head>, but will not run until after the page has loaded.

    <script type="module" src="/javascripts/nhsuk-frontend.min.js"></script>
  </head>

Option 2: Import JavaScript using a bundler

We encourage the use of ECMAScript (ES) modules, but you should check your bundler does not unnecessarily downgrade modern JavaScript for unsupported browsers.

If you decide to import using a bundler like Rollup or webpack, import and run the initAll function to initialise NHS.UK frontend:

import { initAll } from 'nhsuk-frontend'
initAll()

Initialise individual components

Rather than using initAll, you can initialise individual components used by your service. For example:

import { initRadios } from 'nhsuk-frontend/src/nhsuk/components/radios/radios.mjs';
import { initSkipLink } from 'nhsuk-frontend/src/nhsuk/components/skip-link/skip-link.mjs';

// Initialise components
document.addEventListener('DOMContentLoaded', () => {
  initRadios();
  initSkipLink();
});

Importing assets (optional)

If you want to import assets such as the NHS logo, favicons and SVG icons, copy the files into your project folders from the node_modules/nhsuk-frontend/dist/nhsuk/assets/ directory.

<link rel="shortcut icon" href="/assets/favicon.ico" type="image/x-icon">
<link rel="apple-touch-icon" href="/assets/apple-touch-icon-180x180.png">
<link rel="mask-icon" href="/assets/favicon.svg" color="#005eb8">
<link rel="icon" sizes="192x192" href="/assets/favicon-192x192.png">
<meta name="msapplication-TileImage" content="/assets/mediumtile-144x144.png">
<meta name="msapplication-TileColor" content="#005eb8">
<meta name="msapplication-square70x70logo" content="/assets/smalltile-70x70.png">
<meta name="msapplication-square150x150logo" content="/assets/mediumtile-150x150.png">
<meta name="msapplication-wide310x150logo" content="/assets/widetile-310x150.png">
<meta name="msapplication-square310x310logo" content="/assets/largetile-310x310.png">

Thanks to the Government Digital Service (GDS)

This documentation has been taken from Installing GOV.UK Frontend with node package manager (NPM) with a few minor adaptations.