Линтеры и форматтеры в команде: настройка без споров

Если локально код проходит проверку, а в CI падает из-за кавычек или отступов, проблема обычно не в разработчиках, а в разрозненных настройках. Для JavaScript-проекта на ESLint 9 и Prettier 3 полезно разделить ответственность: ESLint ищет ошибки и нарушения правил, Prettier приводит формат к общему виду. Тогда команда не спорит о пробелах в каждом pull request, а проверяет один и тот же результат.

Сначала договоритесь, кто за что отвечает

Линтер анализирует код по правилам: например, сообщает о необъявленной переменной или неиспользуемом импорте. Форматтер автоматически выбирает расположение скобок, переносы строк и кавычки. Эти инструменты могут пересекаться: часть правил ESLint тоже касается форматирования. Если оба инструмента пытаются задавать один и тот же стиль, проверка начинает противоречить самой себе.

Для команды на JavaScript разумная базовая схема такая:

• ESLint отвечает за потенциальные ошибки и согласованные правила кода.
• Prettier отвечает за форматирование файлов.
• Редактор запускает локальные проверки по тем же конфигурациям, что и CI.
• CI проверяет, что изменения уже приведены к нужному виду, но не переписывает их молча.

Настройка ниже рассчитана на ESLint 9.x с flat config и Prettier 3.x. Она показывает базовый JavaScript без TypeScript, React и специфических правил фреймворков: их конфигурации подключают отдельно, не меняя принцип разделения.

Настройте один источник правды

Установите ESLint, Prettier, рекомендованный набор правил ESLint и конфигурацию, которая отключает конфликтующие правила форматирования. В примере команды используются пакеты npm:

npm install --save-dev eslint@^9 @eslint/js@^9 prettier@^3 eslint-config-prettier

Создайте eslint.config.js в корне проекта:

import js from "@eslint/js";
import prettier from "eslint-config-prettier";

export default [
  {
    ignores: ["dist/**", "coverage/**", "node_modules/**"],
  },
  js.configs.recommended,
  {
    files: ["**/*.js"],
    languageOptions: {
      ecmaVersion: "latest",
      sourceType: "module",
    },
    rules: {
      "no-console": "warn",
    },
  },
  prettier,
];

Последним элементом стоит конфигурация eslint-config-prettier: она выключает известные правила ESLint, которые конфликтуют с форматированием Prettier. Не ставьте её выше набора правил, иначе следующий конфиг может включить конфликтующие проверки обратно. no-console здесь — пример командного решения, а не обязательная норма: для CLI-приложения команда может выбрать другое поведение.

Создайте .prettierrc.json и явно зафиксируйте стиль. Это пример исходных договорённостей, а не универсально правильный вкус:

{
  "singleQuote": true,
  "semi": true,
  "printWidth": 100
}

Без файла Prettier всё равно использует значения по умолчанию, но команда не видит договорённость и может случайно изменить поведение обновлением или локальными настройками редактора. Файл конфигурации нужно хранить в репозитории.

Сравните варианты до того, как выбрать

Для обычного JavaScript-проекта отдельная пара ESLint и Prettier чаще всего даёт хороший баланс. Отдельный ESLint-конфиг для форматирования имеет смысл, если команда осознанно хочет проверять именно такие правила линтером и готова разбирать пересечения.

Правило стиля полезно не потому, что оно строгое, а потому, что команда может применять его одинаково и автоматически.

Подключите проверки, которые можно повторить

Добавьте в package.json команды для проверки и исправления:

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "format": "prettier . --write",
    "format:check": "prettier . --check"
  }
}

--fix и --write меняют файлы. В CI используйте проверочные команды, чтобы сборка не переписывала рабочую копию, а сообщала об ошибке. В настройках CI запустите, например, npm run lint и npm run format:check. Не запускайте одну и ту же проверку двумя конкурирующими конфигурациями.

Перед первым включением в CI проверьте проект локально. Если форматтер меняет сотни уже существующих файлов, выделите первичное форматирование в отдельный коммит: иначе ревью функциональных изменений станет шумным. Затем договоритесь, что новые изменения должны проходить проверки, а не менять конфигурацию ради одного спорного фрагмента.

Когда какой подход выбирать

• Выберите ESLint плюс Prettier, если нужна отдельная проверка ошибок и автоматическая унификация внешнего вида.
• Оставьте форматирование ESLint, если команда уже использует такие правила и готова поддерживать их набор вместо Prettier.
• Не ограничивайтесь Prettier, если проекту нужна статическая проверка кода: одинаковые кавычки не обнаружат обращение к необъявленной переменной.

В редакторе включите использование конфигурации проекта, а не личные настройки пользователя. Названия параметров отличаются между редакторами и расширениями, поэтому закрепите конкретное расширение и настройку в документации команды. Чтобы не зависеть от автоматических действий редактора, оставьте проверки в npm-скриптах и CI.

Что ломается чаще всего

ESLint и Prettier спорят об одном правиле

Линтер требует один стиль, а форматтер после запуска создаёт другой. Установите eslint-config-prettier и убедитесь, что он подключён после остальных конфигураций ESLint. Если конфликт остаётся, проверьте, какое именно правило сообщает ESLint, и откуда оно пришло.

Локальная проверка проходит, CI — нет

Сравните версии Node.js и установленные зависимости. Зафиксируйте зависимости в lock-файле и используйте установку из него в CI. Также убедитесь, что разработчик запускает команды из корня нужного пакета: в монорепозитории конфигурации и сценарии могут различаться по директориям.

Форматтер изменяет чужие файлы

Проверьте, что команды запускаются только по отслеживаемым исходникам и не включают результаты сборки. Список исключений в конфигурации ESLint не заменяет исключения Prettier: если форматтер обрабатывает лишние каталоги, настройте для него отдельный файл исключений .prettierignore.

Команда отключает правила точечно и без объяснений

Запретите бесконтекстные изменения конфигурации в ходе обычного исправления и обсуждайте спорные правила отдельно. Настройка, которую постоянно обходят, не упрощает ревью — она лишь создаёт второй, неформальный стандарт.

Flat config — формат конфигурации ESLint, используемый в ESLint 9 по умолчанию. В нём настройки задают массивом объектов в eslint.config.js, а не набором прежних конфигурационных файлов.

Что делать дальше

Сначала примените настройки к небольшому пакету или одному каталогу, затем запустите обе проверки локально и в CI. После первого чистого прохода закрепите версии в lock-файле и добавьте короткую инструкцию для команды: какие команды запускать перед pull request и как обновлять конфигурацию. Следите не за количеством правил, а за числом повторяющихся замечаний в ревью и ложных срабатываний — именно они показывают, помогает ли настройка работе.