Skip to content

installing-with-npm.md

Latest commit

 

History

History
175 lines (120 loc) · 6.18 KB

installing-with-npm.md

File metadata and controls

175 lines (120 loc) · 6.18 KB

Installing using pnpm (or npm)

Requirements

To use Our Future Health design system toolkit in your projects you must:

  1. Have Node.js installed (version 20.19.0 or higher). We recommend using Node.js 24 LTS and pnpm as the package manager.

  2. Have a package.json file within your project. You can create a default package.json file by running pnpm init (or 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.

    pnpm add nunjucks
# or with npm:
npm install nunjucks --save

Installation

Note: As of v4.0.0, this repository is a monorepo. You must specify the package subdirectory when installing.

We don't publish to npm registry. Instead, install directly from GitHub using git with the subdirectory syntax:

{
  "dependencies": {
    "@ourfuturehealth/toolkit": "github:ourfuturehealth/design-system-toolkit#toolkit-v4.0.0:packages/toolkit"
  }
}

Then run:

pnpm install
# or with npm:
npm install

Version pinning:

  • Use specific version tags (e.g., toolkit-v4.0.0) for production
  • For development, you can use #main:packages/toolkit but ensure your lockfile pins a specific commit

Configuration

You will need to import a couple of things into your project before you can start using Our Future Health design system toolkit:

Importing styles

To build the stylesheet you will need a pipeline set up to compile Sass files to CSS. We recommend using the sass package.

Import the Our Future Health design system toolkit styles into the main Sass file in your project. Place this before your own Sass rules.

Choose a theme (recommended)

Each application should pick one theme:

  • participant
  • research

Use the matching theme entrypoint:

// Participant theme
@import 'node_modules/@ourfuturehealth/toolkit/ofh-participant';
// Research theme
@import 'node_modules/@ourfuturehealth/toolkit/ofh-research';

To add a new custom theme, follow docs/theming/adding-a-new-theme.md.

Default entrypoint (legacy-compatible)

If you import ofh, it currently resolves to the participant theme by default:

@import 'node_modules/@ourfuturehealth/toolkit/ofh';

Alternatively you can import components individually:

// Core (required)
@import 'node_modules/@ourfuturehealth/toolkit/core/all';

// Individual component (optional)
@import 'node_modules/@ourfuturehealth/toolkit/components/action-link/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 Our Future Health design system toolkit 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:

document.body.className = ((document.body.className) ? document.body.className + ' js-enabled' : 'js-enabled');

Option 1: Include compiled JavaScript

Include the compiled JavaScript in the <head> of your page using the defer attribute.

The defer attribute is used for performance benefits as the browser loads the JavaScript file as soon as possible, due to it being in the <head>, but will not run until after the page has loaded.

You can copy the file into your project or reference it from node_modules:

    <script src="path-to-assets/ofh-design-system-toolkit.min.js" defer></script>
  </head>
    <script src="node_modules/@ourfuturehealth/toolkit/dist/ofh-design-system-toolkit.min.js" defer></script>
  </head>

Option 2: Import JavaScript using modules

If you're using a bundler such as Webpack or Vite, you can import components using ES6 modules:

// Components
import Card from '@ourfuturehealth/toolkit/components/card/card';
import Checkboxes from '@ourfuturehealth/toolkit/components/checkboxes/checkboxes';
import Details from '@ourfuturehealth/toolkit/components/details/details';
import ErrorSummary from '@ourfuturehealth/toolkit/components/error-summary/error-summary';
import Header from '@ourfuturehealth/toolkit/components/header/header';
import Radios from '@ourfuturehealth/toolkit/components/radios/radios';
import SkipLink from '@ourfuturehealth/toolkit/components/skip-link/skip-link';

// Polyfills
import '@ourfuturehealth/toolkit/polyfills';

// Initialize components
document.addEventListener('DOMContentLoaded', () => {
  Card();
  Checkboxes();
  Details();
  ErrorSummary();
  Header();
  Radios();
  SkipLink();
});

Importing assets (optional)

If you want to import assets such as the Our Future Health logo, favicons and SVG icons, copy the files from node_modules/@ourfuturehealth/toolkit/assets/ or reference them directly:

<link rel="shortcut icon" href="path-to-assets/favicons/favicon.ico" type="image/x-icon" />
<link rel="apple-touch-icon" href="path-to-assets/favicons/apple-touch-icon-180x180.png" />
<link rel="mask-icon" href="path-to-assets/favicons/favicon.svg" color="#FFC62C" />
<link rel="icon" sizes="192x192" href="path-to-assets/favicons/favicon-192x192.png" />
<meta name="msapplication-TileImage" content="path-to-assets/favicons/favicon-270x270.png" />
<meta name="msapplication-TileColor" content="#FFC62C" />

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 major adaptations.