Here at Prototyp we have a great PostCSS build internally called StartGator. It has a lot of shiny components and modules, and it has proven itself over many projects and codebases, from huge .NET solutions to one-off single page websites.

Lately, we have migrated most of our code to React with Typescript, which is a welcome change of pace in frontend development. It guides you and lints errors almost as good as backend devs have used to in their environment for quite some time. There is only one part of legacy code that is a safe-space for dead code with mixed styles — our CSS build. Until now.

Enter Stylelint — “A mighty, modern CSS linter”. There are a couple of problems we need to overcome in order to make it work with both PostCSS and Visual Studio Code, and here is the step by step guide:

Setup steps

Couple of easy steps for hassle-free CSS linting:

VS Code extensions
First, install a VS Code extension called vscode-stylelint by Shinnosuke Watanabe. There are other ways of using Stylelint, but we opted for this. You can check others in the official documentation.

PostCSS integration
VS Code needs a little help in understanding PostCSS. This is optional, but otherwise you could get a lot of nasty errors from VS Code’s side. Add VS Code extension valled vscode-postcss-language and it won’t bother you anymore.

Nice defaults
At this point, you’re actually up and rolling but it doesn’t look like much. Stylelint defaults to false for all rules so you need to provide some rules to begin with. I’d recommend another npm package called stylelint-config-recommended which enables ALL possible rules for stylelint. Add this package as a per-project dependency, or globally, whatever floats your boat. After that, you should just override rules that match your writing rules.

Configuration file
Preferred way (at least for us) for extending config is using .stylelintrc configuration file in root of your project. It makes sense as it naturally sits next to .prettierrc and any others you might have. We started with this:

{
  "extends": "stylelint-config-recommended",
  "rules": {
      "max-nesting-depth": 3,
      "property-no-vendor-prefix": true,
      "max-empty-lines": 2,
      "indentation": 4,
      "function-calc-no-unspaced-operator": true,
      "string-quotes": "double",
      "no-duplicate-selectors": true,
      "color-hex-case": "upper",
      "color-named": "never",
      "selector-max-id": 0,
      "selector-combinator-space-after": "always",
      "declaration-block-trailing-semicolon": "always",
      "declaration-colon-space-before": "never",
      "declaration-colon-space-after": "always",
      "rule-empty-line-before": "always-multi-line",
      "media-feature-range-operator-space-before": "always",
      "media-feature-range-operator-space-after": "always",
      "media-feature-parentheses-space-inside": "never",
      "media-feature-colon-space-before": "never",
      "media-feature-colon-space-after": "always"
  } 
}

All possible rules are in stylelint’s documentation.

Bonus round!
If you still happen to have errors in VS Code, open Preferences > Settings, and in User Settings add postcss file association:

"files.associations”: { 
    "*.css": "postcss" 
}

That’s it. Welcome to the well behaved, linted family. Would you do anything differently? Let me know in the comments :)


Interested in working with us? Drop us a line at hello@prototyp.digital. We are always interested in new projects.