Stylelint для CSS и препроцессоров

В современных фронтенд-проектах, особенно построенных на Vite, CSS перестал быть простым набором стилей. Он включает архитектурные подходы (BEM, ITCSS), использование препроцессоров (Sass, Less, Stylus), CSS Modules, PostCSS-инструменты и сложные соглашения по организации кода. В таких условиях контроль качества CSS становится не менее важным, чем контроль JavaScript-кода.

Stylelint выступает стандартным инструментом статического анализа CSS и всех его диалектов. Он обеспечивает единообразие стилей, предотвращает ошибки, поддерживает командные соглашения и помогает масштабировать проект без деградации читаемости кода.

Базовые принципы работы Stylelint

Stylelint анализирует CSS-код на уровне AST (Abstract Syntax Tree), что позволяет ему:

  • выявлять синтаксические ошибки;
  • проверять соблюдение правил форматирования;
  • контролировать архитектурные соглашения;
  • анализировать специфичные конструкции препроцессоров;
  • применять кастомные правила через плагины.

Главная особенность Stylelint — расширяемость. Он не ограничивается базовым CSS и одинаково эффективно работает с:

  • Sass (SCSS/SASS)
  • Less
  • Stylus
  • PostCSS
  • CSS Modules
  • современными CSS-синтаксисами (nesting, custom properties)

Установка и интеграция в Vite-проект

Vite не включает Stylelint по умолчанию, поскольку он не влияет на runtime-сборку. Его задача — контроль качества кода на этапе разработки.

Установка базового набора:

npm install -D stylelint

Для работы с современными конфигурациями чаще подключается стандартный набор правил:

npm install -D stylelint-config-standard

Базовая конфигурация Stylelint

Конфигурация задаётся через файл .stylelintrc или stylelint.config.js.

Пример минимальной конфигурации:

{
  "extends": "stylelint-config-standard",
  "rules": {
    "indentation": 2,
    "string-quotes": "single",
    "color-hex-case": "lower"
  }
}

Ключевая структура:

  • extends — базовый набор правил;
  • rules — кастомные ограничения;
  • plugins — расширения функциональности;
  • overrides — правила для отдельных типов файлов.

Stylelint и CSS-препроцессоры

Поддержка SCSS

Для SCSS требуется дополнительная конфигурация:

npm install -D stylelint-config-standard-scss stylelint-scss

Конфигурация:

{
  "extends": ["stylelint-config-standard-scss"],
  "rules": {
    "scss/at-rule-no-unknown": true,
    "scss/dollar-variable-pattern": "^foo"
  }
}

SCSS добавляет специфичные конструкции:

  • переменные $variable
  • миксины @mixin
  • вложенность
  • функции

Stylelint через stylelint-scss распознаёт эти конструкции и анализирует их корректно.

Поддержка Less

Less требует отдельного плагина:

npm install -D stylelint-less

Пример конфигурации:

{
  "customSyntax": "postcss-less",
  "extends": ["stylelint-config-standard"]
}

Less менее стандартизирован, поэтому важно аккуратно настраивать правила, чтобы избежать ложных срабатываний.

Stylus

Stylus поддерживается через кастомный синтаксис:

npm install -D postcss-styl
{
  "customSyntax": "postcss-styl"
}

Stylus допускает более свободный синтаксис, поэтому правила Stylelint часто требуют смягчения.

Интеграция Stylelint с Vite

Vite не имеет встроенного Stylelint-плагина, но интеграция реализуется через сторонние решения или dev-server hooks.

Использование vite-plugin-stylelint

npm install -D vite-plugin-stylelint

Конфигурация Vite:

import stylelint from 'vite-plugin-stylelint';

export default {
  plugins: [
    stylelint({
      fix: true,
      include: ['src/**/*.css', 'src/**/*.scss']
    })
  ]
}

Функциональность плагина:

  • проверка файлов при запуске dev-сервера;
  • автоматическое исправление ошибок (fix);
  • фильтрация по glob-шаблонам;
  • вывод ошибок в консоль Vite.

Связка Stylelint и PostCSS

Vite использует PostCSS внутри pipeline обработки CSS. Stylelint может использовать PostCSS-синтаксис для анализа современных возможностей CSS:

  • nesting rules;
  • custom media queries;
  • CSS variables;
  • logical properties.

Пример:

npm install -D postcss postcss-syntax
{
  "customSyntax": "postcss-scss"
}

Это позволяет Stylelint понимать CSS, который ещё не стал полностью стандартным.

Архитектурные правила CSS

Stylelint особенно полезен для поддержания архитектуры CSS-кода.

Пример правил для архитектуры

{
  "rules": {
    "selector-class-pattern": "^[a-z][a-z0-9\\-]*$",
    "max-nesting-depth": 3,
    "no-descending-specificity": true
  }
}

Эти правила предотвращают:

  • хаотичные имена классов;
  • чрезмерную вложенность;
  • конфликты специфичности.

Работа с CSS Modules

CSS Modules широко используются в Vite-проектах. Stylelint можно настроить для их поддержки.

{
  "rules": {
    "selector-class-pattern": null
  }
}

Причина отключения — генерируемые хеш-классы не соответствуют стандартным паттернам.

Дополнительно можно использовать overrides:

{
  "overrides": [
    {
      "files": ["**/*.module.scss"],
      "rules": {
        "selector-class-pattern": null
      }
    }
  ]
}

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

Stylelint поддерживает исключения через .stylelintignore:

dist
node_modules
coverage

Также можно использовать конфигурацию:

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

Автоисправление ошибок

Stylelint может автоматически исправлять часть нарушений:

npx stylelint "src/**/*.css" --fix

Типичные исправления:

  • пробелы и отступы;
  • кавычки;
  • порядок свойств;
  • форматирование цветов.

Однако архитектурные нарушения (например, глубина вложенности) требуют ручного исправления.

Интеграция с ESLint в Vite-проектах

В современных Vite-проектах Stylelint почти всегда используется совместно с ESLint.

Разделение обязанностей:

  • ESLint — JavaScript/TypeScript;
  • Stylelint — CSS/SCSS/Less.

Обе системы объединяются через npm-скрипты:

{
  "scripts": {
    "lint:js": "eslint .",
    "lint:css": "stylelint \"src/**/*.{css,scss}\""
  }
}

Плагины Stylelint

Экосистема плагинов расширяет возможности анализа:

  • stylelint-order — контроль порядка CSS-свойств;
  • stylelint-scss — поддержка SCSS;
  • stylelint-declaration-block-no-ignored-properties — поиск бессмысленных деклараций;
  • stylelint-config-recommended — базовые правила.

Пример порядка свойств:

{
  "plugins": ["stylelint-order"],
  "rules": {
    "order/properties-alphabetical-order": true
  }
}

Производительность Stylelint в больших проектах

В крупных Vite-проектах важно учитывать производительность линтера:

  • ограничение scope через include;
  • исключение build-артефактов;
  • использование кеширования;
  • запуск только на изменённых файлах.

Оптимизация конфигурации может существенно сократить время проверки в dev-режиме.

Типичные ошибки при использовании Stylelint

На практике встречаются повторяющиеся проблемы:

  • конфликт правил между конфигурациями;
  • чрезмерно строгие правила, замедляющие разработку;
  • отсутствие поддержки препроцессора;
  • дублирование ESLint и Stylelint правил;
  • игнорирование архитектурных нарушений ради автофиксов.

Роль Stylelint в масштабируемых Vite-архитектурах

При росте проекта CSS становится одной из наиболее уязвимых частей системы. Без линтинга он быстро превращается в набор несвязанных правил, сложных для поддержки.

Stylelint обеспечивает:

  • единообразие кода;
  • контроль архитектуры стилей;
  • снижение технического долга;
  • предсказуемость поведения UI;
  • интеграцию стандартов команды в автоматическую проверку.

В Vite-проектах он становится не дополнительным инструментом, а обязательной частью инфраструктуры качества кода.

Оглавление