Линт проектов: собираем ESLint, Prettier и Stylelint в один пакет

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

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

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

• выравнивает отступы;
  
• убирает лишние пустые строки;
  
• расставляет переносы строк.

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

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

eslint/
  core/ – содержит best-practices для js
  reactBase/ – содержит best-practices для react
  base.mjs – базовые настройки + объединение всех конфигов из core + typescript (потому что typescript это де-факто база)
  react.mjs – base.mjs + объединение всех конфигов из reactBase
  typescript.mjs – правила для typescript, подключение tsconfig.json
  webpack.mjs – подключение webpack.config.ts

• Правило import/order.
  Раньше часто сталкивался с тем, что некоторым разработчикам все равно, что у них там в импортах. Как IDE автоматически добавила импорт, так они и оставили – вперемешку импорты библиотек, относительные импорты, алиасы.
  Прекрасно понимаю, что вручную их корректировать это безумие, но единый порядок способствует лучшей нафигации по коду, а следовательно ускорению разработки (еще и глазу приятнее). Поэтому данное правило позволяет всем оставаться довольными без применения усилий, так как автоматически сортирует и группирует импорты. Можно сделать максимально гибко, но базовых настроек уже будет хватать.
  
• Использование eslint-config-flat-gitignore.
  Этот конфиг помогает ESLint обходить ненужные для индексации и проверки файлы и директории. За основу берет .gitignore файл проекта. Соответственно, если все настроено корректно, линтер не будет ходить в build, dist, node_modules и прочие папки.

• Устанавливаем зависимости

  pnpm i -D @company/lint eslint
  

  Этих зависимостей достаточно, чтобы все заработало. Это возможно благодаря тому, что все плагины и дополнительные зависимости инкапсулированы внутри @company/lint и будут корректно зарезолвлены без конфликтов.
  
• Добавляем файл конфига

  // eslint.config.js
  import eslintReactConfig from '@company/lint/eslint/react';
  export default eslintReactConfig;
  

• Добавляем скрипт

  // package.json
  "scripts": {
    "lint:eslint": "eslint . --fix",
  }
  

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

• eslint-config-prettier отключал стилистические правила ESLint, которые конфликтовали с Prettier;
  
• eslint-plugin-prettier позволял запускать Prettier как правило ESLint.

• Устанавливаем зависимости

  pnpm i -D @company/lint prettier
  

• Добавляем файл конфига

  // .prettierrc
  "@company/lint/prettier"
  

• Добавляем скрипт

  // package.json
  "scripts": {
    "lint:prettier": "prettier . -w --log-level error --ignore-unknown",
  }
  

  Флаг --ignore-unknown позволяет пропускать файлы, которые Prettier не умеет форматировать.
  
• Добавляем файл для игнора

  // .prettierignore
  pnpm-lock.yaml
  

  Если используется pnpm, рекомендуется добавить pnpm-lock.yaml в список игнорируемых файлов. В противном случае Prettier может пытаться форматировать его при каждом запуске. В остальном, Prettier по умолчанию смотрит в .gitignore, находящийся в папке запуска, и не сканирует файлы и папки, которые там перечислены.

• Устанавливаем зависимости

  pnpm i -D @company/lint stylelint
  

• Добавляем файл конфига

  // stylelint.config.js
  module.exports = {
    extends: ['@company/lint/stylelint'],
  };
  

• Добавляем скрипт

  // package.json
  "scripts": {
    "lint:style": "stylelint \"{src,packages/*/src}/**/*.css\" --fix",
  }
  

• Устанавливаем зависимости

  pnpm i -D madge
  

• Добавляем файл конфига

  // .madgerc
  {
    "detectiveOptions": {
      "ts": {
        "skipTypeImports": true
      },
      "tsx": {
        "skipTypeImports": true
      }
    },
    "fileExtensions": ["ts", "tsx"],
    "tsConfig": "./tsconfig.json"
  }
  

  По желанию можно удалить из конфига игнорирование импортов типов, если вы хотите, чтобы для них тоже не было рекурсии, но в рамках типов обычно это допускается, если мы делаем их через import type.
  
• Добавляем скрипт

  // package.json
  "scripts": {
    "lint:madge": "madge --circular src packages/*/src",
  }
  

• Устанавливаем зависимости

  pnpm i -D typescript
  

• Добавляем файл конфига tsconfig.json с настройками для вашего проекта
  
• Добавляем скрипт

  // package.json
  "scripts": {
    "lint:ts": "tsc --noEmit",
  }
  

• Меняем файлы
  
• Делаем git add.
  
• Перед git commit запускается lint-staged.
  
• Он прогоняет линтеры/форматтеры только по staged-файлам.
  
• Если всё ок – коммит проходит.

• Устанавливаем зависимости

  pnpm i -D lint-staged
  

• Добавляем конфиг

  // package.json
  "lint-staged": {
    "*.{css,ts,tsx}": ["stylelint --fix"],
    "*.{js,jsx,ts,tsx,mjs,cjs}": ["eslint --fix --quiet"],
    "*": ["prettier -w --log-level error --ignore-unknown"]
  }
  

  Команды для разных масок запускаются параллельно. Если файл подходит под несколько масок – для него выполнятся все подходящие команды.

• Устанавливаем зависимости

  pnpm i -D husky
  

• Добавляем файл конфига

  // .husky/pre-commit
  pnpm lint:madge
  pnpm lint-staged
  pnpm lint:ts
  

  Важные моменты:
  • запуск lint:madge добавляем сюда, а не в lint-staged, потому что в lint-staged идет работа с каждым файлом отдельно, а здесь один раз сделает прогон и все, экономит время.
    
  • запуск lint:ts добавляем сюда, а не в lint-staged, потому что в противном случае рискуем закоммитить код, который содержит ошибки. Например, если мы обновили только зависимости в package.json, lint-staged проверит только сам packages.json и lock файл, но не обнаружит typescript ошибок, которые могли возникнуть из за обновления этих зависимостей.
• Добавляем скрипт

  // package.json
  "scripts": {
    "prepare": "husky",
  }
  

  Этот скрипт сработает автоматически, в момент установки зависимостей (pnpm i), и настроит husky для работы в проекте.

{
  "scripts": {
    "prepare": "husky",
    "lint:ts": "tsc --noEmit",
    "lint:eslint": "eslint . --fix",
    "lint:madge": "madge --circular src packages/*/src",
    "lint:prettier": "prettier . -w --log-level error --ignore-unknown",
    "lint:style": "stylelint \"{src,packages/*/src}/**/*.css\" --fix",
    "lint": "yarn lint:madge && yarn lint:style && yarn lint:eslint && yarn lint:ts && yarn lint:prettier"
  },
  "lint-staged": {
    "*.{css,ts,tsx}": ["stylelint --fix"],
    "*.{js,jsx,ts,tsx,mjs,cjs}": ["eslint --fix --quiet"],
    "*": ["prettier -w --log-level error --ignore-unknown"]
  },
  "devDependencies": {
    "@company/lint": "^1.0.0",
    "eslint": "^9.39.4",
    "husky": "^9.1.7",
    "lint-staged": "^13.0.3",
    "madge": "^8.0.0",
    "prettier": "^3.8.1",
    "stylelint": "^17.4.0",
    "typescript": "^5.9.3",
  }
}

• cтало меньше бойлерплейтного кода в проектах;
  
• правила линтинга инкапсулировались в одном месте;
  
• удобно обновлять их в одном месте и постепенно применять в каждом проекте обновлением одной зависимости.