Integrate Stylelint Into Your Workflow For Better CSS

June 15, 2016 - Jake Bresnehan

Working within a team or solo can adjust the development priorities but one that should always be high on the agenda is producing the best code possible.

Working on a clean, well organised codebase is bliss. It’s enjoyable and productive. Working on an unorganised codebase is annoying to say the least. It’s often frustrating, painfully slow to change and test anything and invites laziness.

Thankfully as CSS developers we have a handy tool called Stylelint that can help us avoid the unorganised situation.

By dedicating a small amount of setup time initially we can enforce consistent conventions and reap the rewards for the duration of the project.

Getting setup

First we need to decide how we want to use Stylelint. Stylelint can be used via the command line, build tool (gulp, webpack etc), text editor (atom, sublime text etc), Node API or PostCSS.

For this example we will setup Stylelint using webpack. If you are new to webpack this post Diving Webpack should help get the ball rolling.

Ok let’s install the stylelint webpack plugin via npm like so:

npm install stylelint-webpack-plugin --save-dev

In our webpack configuration we need to “require” the plugin we just installed and add the default settings like so:

var styleLintPlugin = require('stylelint-webpack-plugin');

module.exports = {
  // ...
  plugins: [
    new styleLintPlugin({
      configFile: '.stylelintrc',
      context: 'src',
      files: '**/*.css',
      failOnError: false,
      quiet: false,
  // ...

The above options may need to be adjusted to get things running on your end. That really depends on your current setup.

  • configFile: The config file location
  • context: The root of your SCSS files
  • files: Change the glob pattern for finding your files
  • failOnError: Have Webpack’s build process die on error
  • quiet: Don’t print Stylelint output to the console

The above example doesn’t include it but if you are using a different syntax for your stylesheets you can use the following rule:

  • syntax: Use ‘scss|less|sugarss’ to lint the appropriate syntax

This is only the beginning in setting up your webpack config. A full list of options can be seen here, which will no doubt become very handy.

Next we need to create a configuration object, which is just a fancy way of saying we need to create a .stylelintrc file in the root directory of our project and add some Stylelint rules and options.

There are various other ways to setup the configuration object, but for this entry level introduction, we will just roll with the above.

To get the ball rolling, I would recommend adding a generic configuration and adjusting it to suit your needs once things are all setup.

Add this content to your .stylelintrc file.

  "rules": {
    "selector-no-id": true

The above rule will throw an error if it finds “id selectors” like so:

ID Errors

Stylelint has over 100 rules to make sure your CSS is of the highest quality. Dig into them here.

At first they might seem a little daunting but thankfully a selection of people have put together an example configuration to help – Example Config.

Time to run webpack from the command line and clean up our code.

webpack or webpack -w will do the trick.

With a little setup time we now have Stylelint keeping an eye on our code to make sure it stays organised.

Taking things to the next level

This post is just a small insight into the power of using Stylelint (or any linter for that matter) during development.

If you are working within a team or solo it’s a great habit to get into. It keeps you honest and on track to becoming a better developer.

Happy linting!

Further reading:

How Facebook use Stylelint

Join over 30,000 developers & designers who get the best news and articles delivered right to their inbox each week.