Sass Lint Or: How I Learned to Love the Lint

If you’re like me, you’ve been writing Sass for a while, but how good at it are you really? Not everyone needs to code the same, but chances are you picked up some bad habits along the way.

Every developer writes in a slightly different way—tabs or spaces, single line comments or multi, space before a curly bracket or not—how we style is a bit of who we are and bad habits are both easy to pick and very tough to break.

However, like great novelists, we should strive to at least use the same grammar constructions, spell things in the same way (we’ll leave the British out of this one), and have a consistent layout to our manuscript so that not only can it be easily read by someone else, but they can read it as fast as possible and get the most out of it.

This is where Sass linting comes in. Not only can you enforce consistency, but you can also check for human error, prevent lazy coding, and enforce a consistent way of doing things for everyone who may ever work on the project in the future.

This post is about using linting with Gulp. If you’re not using Gulp, there are other ways to lint and tutorials on how to get started.

Firstly, you’ll want to install the following tools:  gulp-postcss, postcss-scss, postcss-reporter and stylelint. Here is a handy npm command to do that:  
npm install gulp-postcss stylelint postcss-scss postcss-reporter --save-dev

You can also define these as devDependencies in a package.json so they will be installed when running just plain old ‘npm install’ at the start of a project. You’d define them with the name of the package in quotes, then a colon, then the version or minimum version of the project in quotes:
"devDependencies": {
  "gulp-postcss": "^7.0.0",
  "styelintr": "^08.1.1",
}

Once you have the npm packages installed you need to set up either a gulp.js file to run it, or wire the tasks into your existing gulp.js or gulp-config.js.  Either way, there are some things we need to require:
var postcss = require('gulp-postcss');
var reporter = require('postcss-reporter');
var syntax_scss = require('postcss-scss');
var stylelint = require('stylelint');

If you are creating a new gulp file for linting, then you must also first require Gulp:
var gulp = require(gulp);

Next we need to tell Gulp what to lint and how to lint it. I’m defining my style rules in a .stylelinrc file in the root of my Drupal theme, but you can define them in a .stylelintrc.json or .yml file or even right in your gulp file itself. There really isn’t a right or wrong way so go with whatever language you are familiar with or what seems easiest to you. Depending on how you decide to bring the rules in, you’ll set up your gulp function differently.

To run linting directly from your gulp.js file:
gulp.task("scss-lint", function() {
  // Stylelint config rules
  var stylelintConfig = {
    "rules": {
      "color-no-invalid-hex": true,
      "function-url-quotes": "double",
      "rule-trailing-semicolon": "always",
    }
  }

  //reporting and messaging treatment
  var processors = [
    stylelint(stylelintConfig),
    reporter({
      clearMessages: true,
      throwError: true
    })
  ];

  //tell gulp where to check (i.e. path to your sass root file)
  return gulp.src('src/**/*.scss')
  .pipe(postcss(processors, {syntax: syntax_scss}));
});

If you are using a separate file for your rule configuration, you'll want to change the gulp function a bit. The stylelint({/*options*/)}, config below is the placeholder for your .stylelintrc file. If using a json or yml file, you'll have to specify that in place of /*options*/, otherwise gulp will automatically look for and find .stylelintrc if it's in your root folder.
gulp.task('lint:css', function() {
  //path to sass files
  return gulp.src('src/**/*.scss')
    //reporting and options
    .pipe(postcss(
      [
        stylelint({/*options*/}),
        reporter({ clearMessages: true })
      ],
      //syntax to follow when linting
      {
        syntax: scss
      }
    ));
});

NOTE: All rule configuration examples in this post use styntax for .stylelintrc. If you are configuring your rules in a json or yml file or directly in gulp you will need to adjust accordingly.

Now that we are familiar with the vocab, let’s look at how a rule is built. There are lot more constructs and rule options but this will get you started and will get you familiar with some of the vocabulary. You can find much more information in the Stylelint User Guide.

• Rule Names—Rule names are always lowercase and separated by hyphens: “number-leading-zero” 
  The first word in the rule defines the element that the rule is going to check (unless the rule applies to the whole stylesheet). “number-leading-zero” is going to check all numbers whereas “indentation” would check the whole stylesheet. The next part of the rule name (if there is one) is what the rule is checking. Hence, “number-leading-zero” is checking all numbers for a leading zero (unless there is no decimal or there is a whole number already before the decimal).
• Allowing and Disallowing—Most rules are written simply to allow or disallow something. “number-leading-zero”: "always" is going to check all numbers for leading zeros and throw a flag anytime one is not found so line-height: .5; would throw a flag, but line-height: 0.5; would pass. Commonly used checks for allowances are "always" and "never". However, some rules are only made to disallow things. “block-no-empty” would make sure that blocks are not empty. The converse (make sure all blocks are empty) would make no sense.
• Max, Min, and Whitespace—Rule names can include variables like max, min, before, after and inside when checking amounts and spacing in and around elements so a rule like “comment-empty-line-before”: “always” would flag any comment that is not preceded by an empty line. Further whitespace rules can be strung together in the name like “function-comma-space-after”: “never” would never allow a space after a comma in a css function like translate(50%,50%).
• Rules like to work together—You can use multiple rules on a single element to enforce strict linting. You can force a space after a colon but not before with combination of rules like:
  “declaration-colon-space-after”: “always”,
  “declaration-color-space-before”: ”never”
• Exceptions—Sometimes you don’t want a rule to apply. If you wanted an empty line before At Rules nested inside a block in all cases except when they are the first thing nested you would write a rule like this:
  “at-rule-empty-line-before”: [“always”, {
    “except”: [“first-nested”]
  }]
• Custom violation messages—You can define custom messages for your rules that will override any standard error or warning messages. The following code would enforce lowercase hex numbers, but rather than just spitting out the name of the rule, it would tell you why its flagging the hex code.
  "color-hex-case": ["lower", {
    "message": "Lowercase letters are easier to distinguish from numbers"
  }],

Up to now we've been talking about rules and configuration and forcing best practice behavior. However, this is not boot camp. No one is going to make you do push ups if you don't toe the line.  You are the one who decides which rules to follow and how much Stylelint chastises you when you break them.

Depending on your workflow and how severe you want to be, you can tell Stylelint to either throw a warning or an error when it finds something against the rules. Errors could be handy to use in your gulp config to prevent compiling if a rule is broken but depending on how many rules you have and how strict you are with your standards, this could cause a lot of stoppage time. However, in the case of something like an invalid hex code or missing semi-colon, having a stoppage might be better than ignoring or not seeing a warning and pushing code that may break the theming.

I like the using the warning severity level because I don’t want to always worry about how I’m writing things when testing a new bit of theming or just spitballing something in Sass. As long as I see the warnings, I can go back and clean things up when I’m ready to ship the code but still experiment quickly rather than being forced to follow a lot of grammar rules. Its also just plain friendlier to see yellow warning signs rather than red errors in my terminal windows.

Severity can be changed in your configuration and can be entered either before you define your rules and bring in libraries:
"defaultSeverity": "warning",
“extends”: “stylelint-config-standard”,
“rules”{
  “indentation”: “tab”,
  “function-comma-space-after”: “never”,
  “number-leading-zero”: “null”,
}

Or on a rule by rule basis:
"color-hex-case": ["lower", { "severity": "warning" }]

As with the exceptions noted above, every rule is sometimes meant to be broken. If you want a consistent breaking of the rule then you should definitely use the exception method, but every once in a while there comes along that special unicorn that just needs a little extra attention. In that case you can enable and disable your linting in chunks as needed right in your stylesheets.
/* stylelint-disable */
.my-little-pony {}
/* stylelint-enable */

You can also ignore entire files (for instance files that are being generated by an SVG icon to Sass mixin gulp function).  Depending on your configuration, you can either create a .stylelintrcignore file in your theme root folder, you can specify files to ignore in gulp, or you can specify files to ignore right at the top your .stylelintrc file:
"ignoreFiles": [
  "components/_patterns/01-atoms/04-images/icons/_icon_sprite.scss"
],