Настройка Stylelint для линтинга CSS

Настройка Stylelint для линтинга CSS

Stylelint анализирует CSS, SCSS, Less, CSS-in-JS и ловит реальные проблемы: несуществующие свойства, неправильные единицы измерения, дублирующиеся селекторы, нарушения порядка свойств. В отличие от Prettier который только форматирует, Stylelint находит логические ошибки.

Установка

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

Для SCSS:

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

Для CSS Modules (запрещает несуществующие composition):

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

.stylelintrc.json

Базовый конфиг для CSS/SCSS проекта:

{
  "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"
    ]
  }
}

Порядок свойств — stylelint-order — спорная тема. Можно упростить до группировки без строгого порядка внутри группы.

Для Tailwind CSS

При использовании Tailwind директивы @apply, @tailwind вызывают ошибки по умолчанию:

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

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

Или вручную:

{
  "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 в package.json

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

Игнорирование файлов

.stylelintignore:

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

Или через конфиг:

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

Интеграция с VS Code

Расширение stylelint.vscode-stylelint. В .vscode/settings.json:

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

"css.validate": false отключает встроенный CSS-линтер VS Code — иначе будут дублирующиеся ошибки.

Сроки

Настройка Stylelint для CSS/SCSS проекта: 1–2 часа. Добавление упорядочивания свойств и отладка правил под конкретный стайлгайд: ещё 1–2 часа.