Upgrading from v6 to v7

v7.0.0 contains a number of breaking changes.

Requirements

The minimum requirements for this version have changed:

• Node.js v22
• Eleventy v3

ES modules

The plugin is now provided as an ES module with a named export, instead of using the older CommonJS format (which uses require() to import modules).

If you are already using ES modules in your project, update the following import:

- import govukEleventyPlugin from '@x-govuk/govuk-eleventy-plugin'
+ import { govukEleventyPlugin } from '@x-govuk/govuk-eleventy-plugin'

If your project is using CommonJS, you will need to import the plugin using a dynamic import(). Refer to CommonJS vs. ESM on the Eleventy website for more information.

Virtual templates

The plugin now provides its layouts using Eleventy’s virtual templates feature.

This means that default layouts can be overridden in your project by creating layouts with the same name.

Remove the path to the layouts folder in node_modules from dir.layouts in your configuration file:

  dir: {
    input: 'docs',
-   layouts: '../node_modules/@x-govuk/govuk-eleventy-plugin/layouts'
  }

GOV.UK rebrand

Sites can implement GOV.UK’s refreshed brand from 25 June 2025, using the new rebrand option.

The default value for this option is false. A subsequent minor release after 25 June 2025 will change this default to true.

Service navigation

The plugin now accepts all options for service navigation, if shown.

The name of this option has changed from navigation to serviceNavigation, with navigation.items renamed serviceNavigation.navigation:

  import { govukEleventyPlugin } from '@x-govuk/govuk-eleventy-plugin'

  export default function(eleventyConfig) {
    eleventyConfig.addPlugin(govukEleventyPlugin, {
-     navigation: {
-       items: [{
+     serviceNavigation: {
+       navigation: {
          text: 'API reference',
          href: '/api'
        }, {
          text: 'Glossary',
          href: '/glossary'
        }]
      }
    })

    // Other configuration options
    ...
  }

It is also possible to show a search field in the service navigation, using the new serviceNavigation.search option.

RSS feeds

The RSS feed layout now correctly supports limiting the number of items, in reverse chronological order:

  ---
  eleventyExcludeFromCollections: true
  layout: feed
  permalink: /posts/feed.xml
- pagination:
+ collection
-   data: collections.post
+   name: post
-   size: 20
+   limit: 20
-   reverse: true
  ---

Featured post images are now included in the generated feed.

Configuration options removed

• The deprecated header.organisationName option has been removed. Use titleSuffix to change the value shown at the end of document titles (the default is 'GOV.UK').

• The scssSettingsFile option has been removed. You can now customise GOV.UK Frontend settings by providing your own stylesheet and setting values for "pkg:govuk-frontend/dist/govuk" with @use:

// Use GOV.UK Frontend
$_font-family: system-ui, sans-serif;
@use "pkg:govuk-frontend/dist/govuk" with (
  $govuk-font-family: $_font-family,
  $govuk-brand-colour: #8822aa,
  $govuk-link-colour: #660088,
  $govuk-link-hover-colour: #440066,
  $govuk-link-visited-colour: #333366,
  $govuk-page-width: 1100px
);

// Use GOV.UK Eleventy Plugin components
@use "pkg:@x-govuk/govuk-eleventy-plugin";