Using With Node

Note: These instructions describe setting up the alpha version of govuk_frontend and can/will change

Quick start

1. Add govuk_frontend_alpha as a dependency

npm install govuk_frontend_alpha --save

❗️Alpha Note: govuk_frontend_alpha isn’t available on the NPM registry. You’ll need to install it manually (see below).

Add this line to your dependencies in package.json:

  "govuk_frontend_alpha": ""

Install the govuk_frontend_alpha package:

npm install

2. Extend the GOV.UK Frontend layout by updating your application layout, to look like this:

{% extends "govuk_template.njk" %}

You can find the GOV.UK Frontend layout in


3. Start your application, you should see the familiar GOV.UK brand.

Setting up GOV.UK Frontend


  • Add govuk_frontend_alpha as a dependency

Follow the quick start instructions above.

Using the GOV.UK Frontend layout

Create a layout file in your application’s views directory:


In your views/layout.njk file:

{% extends "govuk_template.njk" %}

You may need to configure your application’s views to find the GOV.UK Frontend template.

// Set the location of the component and template files
var appViews = [
  path.join(__dirname, 'views'),
  path.join(__dirname, '/node_modules/govuk_frontend_alpha/templates/'),
  path.join(__dirname, '/node_modules/govuk_frontend_alpha/components/')

// Tell nunjucks we are using express to serve the templates within
// the views defined in appViews
nunjucks.configure(appViews, { express: app })

Customising the GOV.UK Frontend layout

GOV.UK Frontend has template blocks that you can use to override bits of the layout.

Setting page content

Add a content block to your page:

{% block content %}
  Hello world!
{% endblock %}

Update the page_title block:

{% block page_title %}
  My page title
{% endblock %}

Styling the layout

By default the GOV.UK Frontend layout will load its own stylesheet, separate from your application.

Having multiple stylesheets

The quickest way to add your own styling is to add a new stylesheet to the head block.

{% block head %}
  <link href="{{ asset_path }}stylesheets/application.css" media="screen" rel="stylesheet" />
{% endblock %}

If you want to use any of the GOV.UK Frontend SCSS mixins or variables you’ll need to import them in to your application SCSS.

For example, to use the $govuk-blue variable you’ll need to do this:

// GOV.UK Frontend colour variables
@import '../../node_modules/govuk_frontend_alpha/assets/scss/settings/colours';

Having a single stylesheet

To use a single stylesheet, you will need to override the default stylesheet block.

To set a stylesheet block, in your application’s layout file:

{% block stylesheet %}
  <link href="{{ asset_path }}stylesheets/application.css" media="screen" rel="stylesheet" />
{% endblock %}

❗️The stylesheet block replaces the default stylesheet.

Until you import the govuk_frontend_alpha scss files in your application stylesheet, your application styling will be broken.

  • To import all of the scss files, add this line to your application.scss file:
@import '../../node_modules/govuk_frontend_alpha/assets/scss/govuk-frontend';
  • To import some of the scss files, choose files to add to your application.scss file from:

Configuring includePaths (optional)

If you’d prefer to configure includePaths to include the path to the govuk_frontend_alpha package, instead use:

@import 'govuk-frontend';

If you haven’t defined includePaths, you may well see an error:

Parent style sheet: /assets/scss/application.scss
        on line 4 of assets/scss/application.scss
>> @import 'govuk-frontend';

Fix this by configuring includePaths for gulp-sass, in your gulpfile.js:

  includePaths: ['node_modules/govuk_frontend_alpha/assets/scss/']

Using GOV.UK Frontend components

You can find all the GOV.UK Frontend components here.

An example component

Here is an example of a button component:

{{ govuk.button(text="Save and continue") }}

This will render a Button component with the text ‘Save and continue’