stylelint-plugin-prefer-utility

A Stylelint plugin to let you know when you might be better off using a utility class rather than creating a new one.

The plugin provides a prefer-utility/prefer-utility rule that compares the number of declarations in each ruleset with a configurable threshold. It warns you if that number is equal or below that threshold, so that you can avoid introducing a new rule for a so few properties.

You'll probably want to avoid certain rules, too. Like your utility classes for example... they're already utility classes. For this, the rule can be configured to ignore some rulesets through String/RegExp matching on the selector or a custom Function.

As CSS projects file organisation and naming schemes vary greatly from one to another, the plugin does only the warning bit. If you chose to listen to the warning, it's up to you to:

• write the utility class, however best suits your project,
• clean up the class that triggered the warning to keep things tidy ;)

That said, there might be room for some help in the warning message. If you'd find this handy, please join the discussion on this issue

Getting started

The package is available on NPM and can be installed via:

npm install stylelint-plugin-prefer-utility

It provides a shareable config you can extend to quickly add the rule to you current .stylelintrc. With this configuration, it will:

• warn when there's 1 declaration (as utility classes generally have only one declaration),
• ignore any selector that's not a single class or id.

{
  "extends": [
    "stylelint-plugin-prefer-utility/config"
  ]
}

You can then override the options for the prefer-utility/prefer-utility rule as best suits your needs:

{
  "extends": [
    "stylelint-plugin-prefer-utility/config"
  ],
  "rules": [
    "prefer-utility/prefer-utility": [
      // If you prefer only creating new classes
      // for more than 2 declarations
      2, {
        // If your utility classes are prefixed with `u-`
        ignoreRules: /^.u-/
      }]
  ]
}

If you need it for creating your own ignoreRules, you can reuse the helper function used by the shareable config for testing if a selector is a single class or ID with:

 targetsSingleClassOrId = require('stylelint-plugin-prefer-utility/lib/targetsSingleClassOrId')

or

 import targetsSingleClassOrId from 'stylelint-plugin-prefer-utility/lib/targetsSingleClassOrId'