Как линтить CSS с помощью Stylelint

May 4, 2026 · 4 min read

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

В этом руководстве рассмотрено всё, что нужно для настройки линтинга CSS со Stylelint в вашем проекте уже сегодня.

Ключевые выводы

Stylelint обнаруживает ошибки в CSS и обеспечивает соблюдение соглашений с помощью статического анализа, имея более 100 встроенных правил.
Он отвечает за качество кода, а не за форматирование, поэтому естественно сочетается с Prettier, а не конкурирует с ним.
Самый быстрый способ настройки — npm create stylelint@latest, который создаёт конфиг и устанавливает stylelint-config-standard.
Правила можно включать, отключать или понижать до предупреждений — это полезно при внедрении Stylelint в существующие кодовые базы.
Подключите его к npm-скрипту и CI-пайплайну, чтобы линтинг действительно запускался.

Что такое Stylelint и почему он должен быть в вашем рабочем процессе?

Stylelint — это CSS-линтер с более чем 100 встроенными правилами, которому доверяют команды Google и GitHub. Он статически анализирует ваши CSS-файлы и сообщает о проблемах — некорректном синтаксисе, неизвестных свойствах, дублирующихся селекторах и нарушениях соглашений — без выполнения кода.

Важное уточнение: Stylelint занимается качеством кода, а не форматированием. Он не будет конфликтовать с Prettier из-за пробелов или точек с запятой. Эти два инструмента дополняют друг друга. Prettier форматирует, а Stylelint обеспечивает корректность и согласованность. Используйте оба.

Установка Stylelint: два способа начать

Stylelint требует современной версии Node.js (Node 20.19.0 или новее в последних релизах), поэтому убедитесь, что ваше окружение обновлено.

Вариант 1: Автоматизированная настройка (рекомендуется)

Самый быстрый способ запустить линтинг CSS со Stylelint — команда create:

npm create stylelint@latest

Она создаёт файл конфигурации и автоматически устанавливает stylelint-config-standard. Также работает с pnpm, Yarn и Bun:

pnpm create stylelint
bun create stylelint

Вариант 2: Ручная настройка Stylelint

Если вы предпочитаете полный контроль, установите зависимости самостоятельно:

npm add -D stylelint stylelint-config-standard

Затем создайте файл stylelint.config.mjs в корне проекта:

/** @type {import('stylelint').Config} */
export default {
  extends: ["stylelint-config-standard"]
};

Расширение .mjs использует ESM — современный формат модулей. Stylelint поддерживает конфигурацию ESM, и это рекомендуемый подход в современных проектах.

Запуск Stylelint для ваших CSS-файлов

После установки запустите Stylelint для всех CSS-файлов:

npx stylelint "**/*.css"

При обнаружении нарушений вы увидите вывод вроде такого:

src/main.css
  12:3  ✖  Unexpected duplicate selector ".btn"   no-duplicate-selectors
  24:5  ✖  Unknown property "colour"              property-no-unknown

Чтобы автоматически исправить то, что поддаётся исправлению, добавьте флаг --fix:

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

Не каждое правило поддерживает автоисправление, но многие — да. Флаг --fix применяет безопасные исправления, где это возможно, но он не решит абсолютно все проблемы.

Настройка правил линтинга CSS в Stylelint

stylelint-config-standard — это надёжная основа. Вы можете расширить её и переопределить конкретные правила в своём конфиге:

/** @type {import('stylelint').Config} */
export default {
  extends: ["stylelint-config-standard"],
  rules: {
    "color-no-invalid-hex": true,
    "unit-no-unknown": true,
    "selector-id-pattern": null  // disable a rule
  }
};

Правила принимают true для включения, null для отключения или массив для настройки уровня важности:

"color-no-invalid-hex": [true, { severity: "warning" }]

Это полезно при внедрении Stylelint в существующую кодовую базу — предупреждения позволяют выявлять проблемы без немедленной блокировки сборок.

Добавление скрипта линтинга в package.json

Подключите Stylelint к вашему рабочему процессу через npm-скрипт:

{
  "scripts": {
    "lint:css": "stylelint \"**/*.css\""
  }
}

Запускайте его командой npm run lint:css. Отсюда вы можете интегрировать его в CI-пайплайн или pre-commit хуки с помощью lint-staged и Husky.

Лучшие практики линтинга CSS

Начинайте с stylelint-config-standard — он отражает актуальные лучшие практики CSS и активно поддерживается.
Используйте предупреждения вместо ошибок при внедрении Stylelint в legacy-код.
Игнорируйте сгенерированные файлы, добавив файл .stylelintignore (аналог .gitignore).
Сочетайте с Prettier — не пытайтесь использовать Stylelint для форматирования.
Запускайте в CI — линтинг только на локальных машинах часто пропускается.

Заключение

Настройка Stylelint занимает около пяти минут и сразу же окупается обнаруженными ошибками и согласованным кодом. Установите его, расширьте stylelint-config-standard, добавьте скрипт и запустите. Это вся настройка. Всё остальное — кастомные правила, поддержка SCSS, интеграция с IDE — строится на этом фундаменте.

Часто задаваемые вопросы

Да. Stylelint поддерживает SCSS, Less и другие CSS-подобные синтаксисы через кастомные синтаксисы, такие как `postcss-scss` или `postcss-less`. Поддержка CSS-in-JS зависит от конкретной библиотеки и требует соответствующего пакета кастомного синтаксиса, настроенного через опцию `customSyntax`.

Да, они решают разные задачи. Prettier форматирует ваш код, обрабатывая пробелы, переносы строк и стиль кавычек. Stylelint выявляет проблемы качества кода, такие как некорректные свойства, дублирующиеся селекторы и нарушения соглашений. Современный Stylelint удалил свои стилистические правила именно для того, чтобы избежать пересечения с Prettier, так что эти два инструмента работают вместе без конфликтов.

Используйте lint-staged совместно с Husky. Настройте lint-staged в package.json для запуска stylelint --fix на staged CSS-файлах, затем добавьте Husky pre-commit хук, который вызывает lint-staged. Это линтит только файлы, которые собираются закоммитить, сохраняя скорость хука даже в больших репозиториях и предотвращая попадание проблемного CSS в основную ветку.

Да. У VS Code есть официальное расширение Stylelint, которое подсвечивает проблемы по мере набора текста и может исправлять их при сохранении. WebStorm и другие IDE от JetBrains имеют встроенную поддержку Stylelint. Другие редакторы могут иметь интеграции, поддерживаемые сообществом. Интеграция с редактором значительно сокращает цикл обратной связи по сравнению с ручным запуском CLI.

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.