Skip to main content
Last updated: 13 Aug 2024

Configure linting

This explains how to configure linting for a GOV.UK application. It is written with the expectation that you are configuring a conventional GOV.UK Rails application although the approaches can be applied to non-Rails applications by minor adjustments to the steps.

Linting Ruby

We use rubocop-govuk to lint Ruby projects.

This is installed by adding gem "rubocop" to your Gemfile and then creating a .rubocop.yml file in the root of your project:

inherit_gem:
  rubocop-govuk:
    - config/default.yml
    - config/rails.yml
    - config/rake.yml
    - config/rspec.yml

inherit_mode:
  merge:
    - Exclude

# **************************************************************
# TRY NOT TO ADD OVERRIDES IN THIS FILE
#
# This repo is configured to follow the RuboCop GOV.UK styleguide.
# Any rules you override here will cause this repo to diverge from
# the way we write code in all other GOV.UK repos.
#
# See https://github.com/trade-tariff/rubocop-govuk/blob/main/CONTRIBUTING.md
# **************************************************************

After running bundle install you can test the linting by running bundle exec rubocop.

Linting JavaScript and SCSS

We follow the GDS Way guidance on linting Javascript and CSS.

To configure this for a Rails application you will need to install standardx and stylelint-config-gds. To do this you will first need to install Yarn and then you should create a package.json file in your project root. You can use the following template:

{
  "name": "My application",
  "description": "A brief description of the application's purpose",
  "private": true,
  "author": "Government Digital Service",
  "license": "MIT",
  "scripts": {
    "lint": "yarn run lint:js && yarn run lint:scss",
    "lint:js": "standard 'app/assets/javascripts/**/*.js' 'spec/javascripts/**/*.js'",
    "lint:scss": "stylelint app/assets/stylesheets/"
  },
  "standardx": {
    "env": {
      "browser": true
    }
  },
  "eslintConfig": {
    "rules": {
      "no-var": 0
    }
  },
  "stylelint": {
    "extends": "stylelint-config-gds/scss"
  }
}

The dependencies can then be installed:

yarn add --dev standard stylelint stylelint-config-gds

You can now test the linting by running yarn run lint.

To finish up you should add node_modules and yarn-error.log to your .gitignore file.

Configuring Rails

To configure this linting in Rails you should create a rake task for this in lib/tasks/lint.rake:

desc "Run all linters"
task lint: :environment do
  sh "bundle exec rubocop"
  sh "yarn run lint" # lint JS and SCSS
end

You should then configure the default rake task for the application to include linting. For example to run linting and RSpec as the default task add the following code to your Rakefile:

# Undo any existing default tasks added by depenencies so we can redefine the task
Rake::Task[:default].clear if Rake::Task.task_defined?(:default)
task default: %i[lint spec]

You can confirm this works by running bundle exec rake and seeing your linting run followed by specs.