How to Lint CSS Using Stylelint

Linters have been around for a good while; but if you’re new to CSS this might be the first you’ve heard about them. A CSS linter will keep your stylesheets in check and make you a better coder!

What Are the Benefits of CSS Linters?

As front end developers we hope that the code we write will be shipped to production and enjoyed by the users of our product. We spend a huge amount of time ensuring that we write code that is free of bugs and errors. But how many of these errors can we figure out without actually running the code? This is where tests come in, though there are certainly things that tests will not pick up, or might not be tested for at all.

For example, as a JavaScript developer, will you prioritize and write tests to handle cases of missing semi-colons? Or rather for performance issues that arise from making use of a universal selector?


The use of CSS linters makes it possible to capture the kinds of CSS issues you might not be aware of. This is especially helpful for beginners, whose skills are in the early phases. Beyond that, the benefits of using linters go well beyond performance to areas like security issues, static analysis, and so on.

Why Use Stylelint as Your Linter?

Stylelint is, in the developers’ own words:

“A mighty, modern linter that helps you avoid errors and enforce conventions in your styles.”

Here are some features that Stylelint gives you;

  • It supports the latest CSS syntax and understands CSS-like syntax such as SCSS and Less.
  • It automatically fixes some styles of errors.
  • It has over 170 built-in rules to catch errors and enforce stylistic conventions.
  • It is opinionated, giving you the ability to enable only the rules you want to use and configure them to suit your preferences.
  • It supports sharable config which can be handy when working in a team.

You can find more of the features here.

How to Use Stylelint

There are different ways to use Stylelint, such as installing a plugin for your favorite code editor, or a plugin for Post CSS, but we’re going to use the Command Line.

Start linting by installing the NPM package on your machine. Open up your terminal and type the following command:

The above command installs Stylelint globally. If you prefer to have it project-based, you can do so with the command below:

Then you can have this in the package.json file which is added to your project.

Running the Linter Command

Note: before you actually run the linter you’ll need to set up the configuration, which we’ll cover in a moment. Without configuration an error will be thrown.

There are different combinations when running the command to lint your stylesheet. Let’s start from the one above.

This command will search for styles in your application and attempt to lint them. If you want to run Stylelint scoped to a particular directory, you have to make use of:

This works if you already have Stylelint installed globally on your machine. If you do not, you can add that to the script section of your package.json file. The command will lint all .css files contained in the styles directory.

There is also a command for cases where you want to lint the styles that are contained in HTML files.

This will handle styles that are written in the <style> blocks in all HTML files in the home.

Stylelint Configuration

Stylelint uses a configuration to figure out how you want to lint your styles. As an unopinionated tool, it has no styles turned on by default, even though there are default configurations that can be used. 

Rules that you wish to use will be contained in the configuration. You will run into errors if you try to lint without having a configuration. Stylelint will be clueless about what to do without the configuration, it expects a configuration file. 

There are different methods that can be followed when setting up configuration:

  1. A stylelint property in your package.json file.
  2. A .stylelintrc file. This file can either be in JSON or YAML format.
  3. A stylelint.config.js file that exports a JavaScript object.

These are the places Stylelint will look when searching for the configuration to use. The configuration expected by Stylelint is an object which should have the following keys; rules, extends, plugins, processors, ignoreFiles.

Here is a sample of how a configuration file might look:

Here we are specifying the configuration we want to extend: the standard configuration.

Then we add a few rules we want to make use of. When getting started with Stylelint, you might want to begin by using an existing configuration file. Extending already existing configurations is a relatively easy way to start out, then you can override the styles by adding them to the rules object with your own configuration value.


In addition to the rules being turned off by default, there are no default values for any of the rules–you’ll have to configure the rules you want to use. To configure a rule, you have to make use of the rule’s name (which is the key) and the rule configuration (which is the value). Here is an example of how that looks:

In the above snippet, I am turning on the indentation rule. I do that by adding the key and value pair, which is the rule’s name and configuration, to the rules object.

According to the documentation, there are three ways of setting up a rule configuration:

  1. A single value, like the example we have above.
  2. An array with 2 values–the first will be the primary option, while the second is the secondary option
  3. A null value–this turns off the rule.

The rules are broken into different categories like rules for errors, stylistic issues, and limiting language features.

Check the documentation to properly go through the possible rules. Here are a few we can cover:

Prevent Invalid Hex Values

Styelint makes it possible to prevent invalid hex values using the color-no-invalid-hex rule.

That will make a style like this invalid:

This rule will help save you and your team from mistakenly using an invalid hex value for your color, or background-color, or other cases where you’ll need to make use of a hex color.

Add a New Line After a Semi-Colon

There is also a rule to add a newline after a semi-colon in a declaration block.

This rule has three possible values:

  • always: this requires that a new line is always added after a semi-colon.
  • always-multi-line: this requires a new line when the rule spans across multiple lines.
  • never-multi-line: with this value there must never be a whitespace after the semi-colon in multi-line rules.

You can check out the documentation for more on this rule.

Stylelint Plugins

Plugins make it possible to use rules are that not defined in Stylelint by default. You, or members of the community, can build plugins that adopt Stylelint’s methodologies. These plugins can then be used in addition to Stylelint. There are already tons of plugins that are available for you to try your hands on.

stylelint-color-format is a plugin that converts hex color to RGB or HSL format. To use it you need to first install the package.

Next, you add it into the plugin array in your configuration.

With that, you can then add to the rules object to signify the rule’s name and the value you want to use.


There’s lots to learn about Stylelint, and you should now have a good grasp of what is it and how it works. Going forward, you can begin to adopt it into your workflow, and consider using other linters (such as ESLint) for keeping your JavaScript and other code you write in check!

Useful Links

Leave a comment

Your email address will not be published.