Stylelint Setup for CSS Linting

Setting Up Stylelint for CSS Linting

Stylelint analyzes CSS, SCSS, Less, CSS-in-JS and catches real problems: nonexistent properties, incorrect units, duplicate selectors, property order violations. Unlike Prettier which only formats, Stylelint finds logical errors.

Installation

npm install --save-dev stylelint stylelint-config-standard

For SCSS:

npm install --save-dev stylelint-config-standard-scss

For CSS Modules (prevents nonexistent composition):

npm install --save-dev stylelint-config-css-modules

.stylelintrc.json

Basic config for CSS/SCSS project:

{
  "extends": [
    "stylelint-config-standard",
    "stylelint-config-standard-scss"
  ],
  "plugins": [
    "stylelint-order"
  ],
  "rules": {
    "color-named": "never",
    "color-no-invalid-hex": true,
    "unit-no-unknown": true,
    "property-no-unknown": true,
    "declaration-block-no-duplicate-properties": true,
    "no-duplicate-selectors": true,
    "selector-class-pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
    "order/properties-order": [
      "content",
      "position", "top", "right", "bottom", "left", "z-index",
      "display", "flex", "flex-direction", "flex-wrap", "align-items", "justify-content",
      "grid", "grid-template",
      "width", "min-width", "max-width",
      "height", "min-height", "max-height",
      "margin", "margin-top", "margin-right", "margin-bottom", "margin-left",
      "padding", "padding-top", "padding-right", "padding-bottom", "padding-left",
      "border", "border-radius",
      "background", "background-color",
      "color",
      "font", "font-size", "font-weight", "line-height",
      "transition", "animation",
      "cursor", "pointer-events", "opacity", "overflow", "visibility"
    ]
  }
}

Property order — stylelint-order — is a debatable topic. Can be simplified to grouping without strict order within groups.

For Tailwind CSS

When using Tailwind directives @apply, @tailwind cause errors by default:

npm install --save-dev stylelint-config-tailwindcss

{
  "extends": [
    "stylelint-config-standard",
    "stylelint-config-tailwindcss"
  ]
}

Or manually:

{
  "rules": {
    "at-rule-no-unknown": [true, {
      "ignoreAtRules": ["tailwind", "apply", "variants", "responsive", "screen", "layer"]
    }]
  }
}

CSS-in-JS (styled-components, emotion)

npm install --save-dev @stylelint/postcss-css-in-js postcss-syntax

{
  "overrides": [
    {
      "files": ["**/*.{js,jsx,ts,tsx}"],
      "customSyntax": "@stylelint/postcss-css-in-js",
      "rules": {
        "color-named": "never",
        "property-no-unknown": true
      }
    }
  ]
}

scripts in package.json

{
  "scripts": {
    "lint:css": "stylelint \"src/**/*.{css,scss}\"",
    "lint:css:fix": "stylelint \"src/**/*.{css,scss}\" --fix"
  }
}

Ignoring Files

.stylelintignore:

node_modules/
dist/
build/
*.min.css
vendor/

Or via config:

{
  "ignoreFiles": ["dist/**", "node_modules/**", "**/*.min.css"]
}

VS Code Integration

Extension stylelint.vscode-stylelint. In .vscode/settings.json:

{
  "stylelint.validate": ["css", "scss", "less"],
  "css.validate": false,
  "scss.validate": false,
  "editor.codeActionsOnSave": {
    "source.fixAll.stylelint": "explicit"
  }
}

"css.validate": false disables VS Code's built-in CSS linter — otherwise there will be duplicate errors.

Timeline

Setting up Stylelint for CSS/SCSS project: 1–2 hours. Adding property ordering and debugging rules for specific styleguide: another 1–2 hours.