Skip to main content
Warning This document has not been updated for a while now. It may be out of date.
Last updated: 12 May 2023

govuk_publishing_components: Generate a new component

You can create a new component in the application (when you don't intend to use it in other places), the gem, or Static (deprecated).

Option 1: create a component in the application

The gem includes a component generator to stub the minimal files required for a component. The following command will create a component in the application it is run in - it will not create a component if run within the gem.

rails generate govuk_publishing_components:component [component_name]

component_name should use underscores and not hyphens. Read our component conventions for further details.

This will create a template, scss file and yml documentation file for a new component. It will not create a test file as this cannot be reliably done automatically across applications, but a test file will be necessary.

Option 2: create a component in the gem

New components in the gem should be tested with users. Mark all new components as (experimental) (after the component name in the documentation file) until you collect enough feedback to be confident it can be used across applications.

Currently components in the gem must be manually created. File naming conventions should follow those in the component conventions, but a slightly different directory structure is required to avoid conflicts with components in applications.

  • Stylesheets go in app/assets/stylesheets/govuk_publishing_components/components
  • Print styles should be included in the main stylesheet
  • Scripts go in app/assets/javascripts/govuk_publishing_components/components
  • Templates go in app/views/govuk_publishing_components/components
  • Documentation goes in app/views/govuk_publishing_components/components/docs
  • Test files go in spec/components
  • Script test files go in spec/javascripts/components

In addition, components in the gem can have helper files. Helper files go in lib/govuk_publishing_components/components and need to be required in lib/govuk_publishing_components.rb. Helper files should be structured as a class.

Option 3: create a component in Static (don't)

This is deprecated, don't add any more components to Static.