Moving from Sass-Lint to Stylelint

Why make the transition?

So frequently in the past, sass-lint was used as a linting staple, so why make the change from a tried and true linter to stylelint? Well for one, Sass-Lint is no longer being maintained, but also Stylint has a wider realm of support and contributions. stylelint has a wide variety of configs and plugins to extend, which allows you to match and go beyond the rules that are present in Sass-Lint. Not only that it also parses the syntaxes SCSS, Sass, Less, and SugarSS , while also extracting style from in-line HTML styles, markdown and CSS-in-JS objects/ template literals. So it's great to use with a variety of frontend frameworks.

What are the steps?

First, you'll want to install stylelint and any of the plug-ins and configs you plan on using. The plugins and configurations available to you are great in numbers, so you won't be left wanting. Links can be found within the stylelint repository on GitHub under a sub-directory called awesome-stylelint. For the transition, we use stylelint-config-recommended, stylelint-config-sass-guidelines, stylelint-config-standard, and stylelint-scss.

There are additional formaters within the list of plugins, but stylelint comes with inherent formatting functionality.

To Install stylelint and any plug-ins/additional configs:

npm i stylelint stylelint-config-recommended stylelint-config-sass-guidelines stylelint-config-standard stylelint-scss --save-dev

Setting up the rules

Once stylint is installed, you can start putting together your rc file. You would create it with the name of .stylelintrc.yml. The rc file is where you'll extend and apply your plugins and configuration modules you've installed, but also where you will define and manipulate the rules that are provided in those plugins and configurations. I like to compare my .sass-lint.yml to find comparable rules.

This is an example of a .stylelintrc.yml file :

defaultSeverity: warning
extends:
    - stylelint-config-standard
    - stylelint-config-recommended
    - stylelint-config-sass-guidelines
plugins:
    - stylelint-scss
rules:
# Line Spacing
rule-empty-line-before:
    - always-multi-line
    - ignore:
        - after-comment
        - first-nested
        - inside-block

# Disallows
selector-max-id: 2
comment-no-empty: true
declaration-block-no-duplicate-properties: true
block-no-empty:
    - true
    - ignore:
        - comments
no-descending-specificity:
    - true
    - ignore:
        - selectors-within-list
no-extra-semicolons: true
color-no-invalid-hex: true
number-no-trailing-zeros: true
length-zero-no-unit: true
scss/at-extend-no-missing-placeholder: null
selector-no-qualifying-type:
    - true
    - ignore:
        - attribute
        - class
        - id
property-no-unknown:
    - true
    - ignoreProperties:
        - 'box-orient'

# Nesting
max-nesting-depth:
    - 5
    - ignore: ['blockless-at-rules', 'pseudo-classes']  

# Name Formats
selector-class-pattern: ^[A-Z].*$
scss/at-mixin-pattern: ^[A-Z].*$  

# Style Guide
indentation: 4
color-named: 'never'
declaration-block-trailing-semicolon: always
unit-case: lower
color-hex-case: lower
number-leading-zero: always
unit-no-unknown:
    - true
    - ignoreUnits:
        - /^[-+][\d$(]/
font-family-no-duplicate-names: true
string-quotes: single
selector-max-compound-selectors: 6

# Inner Spacing
function-calc-no-unspaced-operator: true
declaration-block-semicolon-newline-after: always
block-opening-brace-space-before: always
block-opening-brace-newline-after: always
block-closing-brace-newline-after: always
declaration-bang-space-after: never
declaration-colon-space-after: always

# Final Items
scss/at-import-partial-extension-blacklist: [/css/]

These files are super flexible and not set in stone, they are made to be updated per a project's needs.

Adding the scripts

Stylelint uses npx to run inherently, so when you write your scripts in your package.json you need to add the npx in for it to work properly. Below are the base scripts for running the linter and formatting based on your rules.

"scripts": {
    ...
    "stylelint": "stylelint '**/*.scss'",
    "stylelint-fix": "stylelint '**/*.scss' --fix",
    ...
}

Ok the rules are set up you have your scripts, so running the scripts to make sure they work is key. Now, running the stylelint-fix will not fix everything magically. Likely, you will still need to go through and make some changes before your transition is complete.

At this point, you can add your npm run stylelint and npm run stylelint-fix to your lint and format script replacing whatever you had there for sass-lint.

Time to remove Sass-lint

Since we replaced the sass-lint scripts in the lint and format scripts we can uninstall sass-lint.

npm unistall sass-lint sass-lint-auto-fix

Now you can delete your sass-lint.yml file, after that is done I like to do a fresh install by running:
rm -rf node_modules/ package-lock.json
then
npm i

Get to fixing

From here you are free to run your lint and formats. Your new rule definitions will likely introduce new warnings for you. So you can run the formatter to see how far that gets you, but inevitably you will need to fix some

Resources

Stylelint
Sass Lint