GOV.UK Frontend Webpack Demo

This repo demonstrates how to use Webpack to bundle, compile and minify JavaScript, SCSS, images, and fonts, while optimising the output for performance. It uses various loaders and plugins to process files and generate the final build:

• CSS Minimizer Webpack Plugin: Uses CSSNANO to minimise the CSS output, reducing file size and improving page load times.
• PostCSS Preset Env: Uses Autoprefixer to add vendor prefixes and ensure compatibility with older browsers.
• PurgeCSS: Analyses your content and your CSS files. Then it matches the selectors used in your files with the one in your content files. It removes unused selectors from your CSS, resulting in smaller CSS files.
• Babel Preset Env: Transpiles ES6+ JavaScript for cross-browser compatibility while allowing the use of modern JavaScript features.
• Copy Webpack Plugin: Automates copying images and fonts from GOV.UK Frontend to the output directory.
• Webpack Dev Server: Serves files from the output directory with live reloading for development workflows.

Prerequisites

• A supported LTS version of Node.js
• Node Version Manager (optional)
• Docker (optional)

Get started

You can run on your local host, or in a Docker container:

On your host

1. Install Node, preferably using nvm. The version is set in the .nvmrc file and is typically the latest LTS release codename.

   nvm install

2. Install the Node package dependencies from npm:

   npm install

Using Docker

1. Build the image

   docker build -t govuk-webpack:latest .

2. Run the container

   docker run -p 8000:8000 govuk-webpack:latest

How to

Use GOV.UK Design System components

The main.scss file at /src/scss is highly selective about which components are imported above the required base, core, objects, utilities and overrides. Components account for around 70% of the output CSS, so should only be included if they are used in the service, in order to keep distributon file sizes small.

By default, the following components are imported:

• Cookie banner
• Footer
• Header
• Service navigation
• Skip link

Simply uncomment any other components in main.scss that you need to use.

The same approach applies to JS; the main.mjs file at /src/js only imports JS for the components being used:

• Service navigation
• Skip link

Note: The JS for the Header component is not needed when using the newer Service navigation component alongside it.

For comparison (using GOV.UK Frontend v5.10.0):

Asset	Size (KB)
Precompiled CSS	128
Selective CSS	24 (-81%)
Precompiled JS	49
Selective JS	5 (-90%)

Format source code

Use Prettier, an opinionated code formatter, for consistency.

To check formatting (without changing):

npm run format:check

To reformat files:

npm run format:fix

Lint source code

Use ESLint to statically analyse your code to quickly find problems.

To check for issues:

npm run lint:check

To attempt to automatically fix issues:

npm run lint:fix

Build assets

Use Webpack loaders and plugins to output CSS, JS, fonts and images to ./dist:

npm run build

Watch changes

Rebuild distribution assets automatically when source is changed:

npm run watch

Run dev server

Start a simple web server with live reloading:

npm start

Go to http://localhost:8000

Upgrade dependencies

Use npm-check-updates to upgrade Node package dependencies (such as govuk-frontend):

npm run upgrade:latest

If you want to be more cautious you can apply only minor or patch level upgrades:

npm run upgrade:minor

npm run upgrade:patch