Previously, we introduced you to linting, and showed you how to integrate JSHint into your workflow. In this tutorial, we want to assist CSS developers produce the best code possible by looking at how they can bring order to their stylesheets and integrate stylelint in their workflow. Below, you will find a detailed explanation about the benefits, installation, configuration, and usage of stylelint.

What is stylelint?

Stylelint is a tool that reports bad code in your CSS files. It helps to enforce the consistent code and prevents you from making errors in your stylesheets. It is highly configurable. Therefore, you can track almost everything from unknown units to important declarations in keyframe rules. Last but not least, you can customize and extend everything by writing and publishing your own rules as plugins.

Installation

The simplest way to run stylelint is through its CLI. This gives you the stylelint CLI command which performs the CSS linting. You can install it globally and use it from everywhere in the file system by running the following command:

 

Note: Stylelint is an npm package, so Node.js is a prerequisite.

Configuration

First of all, you should create JSON file in the root directory of your project, named .stylelintrc where you will store your stylelint configuration object.

You have two options to create your configuration object:

• by either design your own
• or extend a shared config (supported by stylelint).

There are also two strategies to craft your configuration:

• start with an empty object and progress by adding rules one by one as you need them
• you can copy/paste the example configuration which holds all possible rules and turn on each one’s options

To extend a shared config, developers recommend using either stylelint-config-standard or stylelint-config- recommended

The configuration object

Let’s take a look at some of the properties in the configuration object:

1. Rules

There are more than a hundred pre-defined rules, reporting warnings in case of violations. The rules property

is an object whose keys are rule names and whose values are rule configurations. Here is how a sample configuration might look like:

Each rule configuration fits in one of the following formats:

a single value (the primary option) – will turn a rule on

an array with two values ([primary option, secondary options]) – provides further customization null – turns the rule off

2. Extends

If you decide to use an existing config and then change some of the rules, you have to add extends property in your configuration object. Its value can be an npm module name, an absolute path or a path relative to the invoking configuration file.

In the following example, we extend stylelint-config-standard and then change “indentation” to tab, add a new rule “block-no-empty” that disallows empty blocks and turn off the “max-empty-lines” rule:

 

You can extend more than one existing configuration:

 

Note: Each item in the array takes precedence over all the previous items.

3. Plugins

To use a plugin, you have to add a “plugins” property with a npm module name value, an absolute path, or a path relative to the invoking configuration file.

Once the plugin is declared, within your “rules” object, you’ll need to add options for the rule.

A plugin can also provide a set of rules, just add the rules you want to invoke. For example:

 

The complete list of plugins, including their documentation can be found here. If you want to write your own

plugin get familiar with stylelint’s conventions for writing plugins.

Other properties of the configuration object are processors, ignoreFiles, and defaultSeverity; you can learn more about them from the Stylelint Configuration.

Usage

Stylelint will look for your .stylelintrc recursively till the root of your file system. Make sure you include the quotation marks around file globs so that you can use the advantages of node-glob regardless of your shell. Now you can start linting with the following commands:

• linting all .css files in styles current directory:

• linting all .css files in foo current directory and any of its subdirectories:

• linting all .css files in the whole directory:

Example output:

Additional resources:

Stylelint: The Style Sheet Linter We’ve Always Wanted

Lint your CSS with stylelint How to lint SCSS with stylelint The stylelint CLI

Stylelint Configuration

If you have any questions about how to integrate stylelint in your workflow, write a comment below or start a discussion in our Forum.