CSS Stylelint Rules: How To Write Your Own Rules

When working with CSS, developers usually don’t think about running a linter on the stylesheets. We usually use linters on C or C++ or JavaScript codebases but we don’t often think about whether or not it’s even possible to lint a CSS stylesheet and enforce certain coding standards and rules on it. With Stylelint, you can lint your CSS and make sure it’s in line with common standards, more powerful than that is writing your own stylelint rules.

Here’s a few reasons why you would want to write your own custom rules for a linting tool:

• You can make sure the code base is readable and consistent (a necessity for CSS!)
• You can prevent some mistakes from happening (for example, always using parens around method calls in Ruby or CoffeeScript, or making sure every method has a comment explaining what it does)
• Linters can warn you of potential issues (to take a Ruby on Rails or Django example, when you’re using the wrong method to get the count of items in the database)

Example of Stylelint rule

So I sat down and read through the CSS stylelint guide on writing plugins and rules and came up with a basic example that other developers can build upon to lint their own CSS code.

The custom stylelint rule will detect whether the “visibility” property is being used. In most codebases it isn’t used, so I thought it would be a safe enough example that anyone can run.

.stylelintrc

{
  "extends": "stylelint-config-standard",
  "rules": {
    "neverfriday/no-visibility-allowed": true
  },
  "plugins": [
    "./neverfriday-stylelint-plugin.js"
  ]
}

neverfriday-stylelint-plugin.js

var stylelint = require("stylelint");

var ruleName = "neverfriday/no-visibility-allowed";
var messages = stylelint.utils.ruleMessages(ruleName, {
  expected: function(value) {
    return "Try not to use visibility: " + value;
  }
});

module.exports = stylelint.createPlugin(ruleName, function(enabled) {
  if (!enabled) {
    return;
  }
  return function(root, result) {
    root.walkDecls(function(decl) {
      if (decl.prop === "visibility") {
        stylelint.utils.report({
          result,
          ruleName,
          message: messages.expected(decl.prop + ", " + decl.value),
          node: decl,
          word: decl.value
        });
      }
    });
  }
});

module.exports.ruleName = ruleName;
module.exports.messages = messages;

How To Create a Stylelint Plugin or Rule

The instructions for writing your own plugins and rules are in the Stylelint Developer Guide:

• Writing your own stylelint rules
• Writing your own plugins
• Testing your rules with rules testers

It didn’t take very long to write a few more rules for stylelint and the linter immediately found a lot of coding standard violations that made our CSS inconsistent. After fixing the rules, the code was cleaner and more consistent and developers could worry about higher-level concerns.

I really enjoyed using stylelint and will be using it for future projects whenever possible. Alternatively, I will be writing custom rules for whatever linters I use on projects.

Check out NeverFriday.com, where this article was first published.