lint-staged: линтинг staged файлов

lint-staged — инструмент для запуска линтеров и форматтеров только на файлах, добавленных в git staging area, а не на всём проекте.

Зачем нужно

Запуск ESLint или Prettier на всём проекте в pre-commit хуке занимает секунды или минуты. lint-staged фильтрует только staged файлы — те, что в git add. Это делает проверку мгновенной и релевантной: исправляем только то, что коммитим.

Где используется

  • Pre-commit хук в связке с Husky
  • Форматирование кода перед каждым коммитом (Prettier)
  • Линтинг изменений перед коммитом (ESLint)
  • TypeScript проверка типов только для изменённых файлов

Установка

npm install --save-dev lint-staged

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

// package.json
{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md,yaml,yml}": "prettier --write",
    "*.css": "prettier --write"
  }
}

// lint-staged.config.js — расширенная конфигурация
export default {
  '*.{ts,tsx}': [
    // Автофикс ESLint
    'eslint --fix',
    // Форматирование Prettier
    'prettier --write',
    // TypeScript проверка типов (только для ts файлов)
    // Не передаём файлы — tsc проверяет весь проект
     => 'tsc --noEmit',
  ],
  '*.{js,jsx}': ['eslint --fix', 'prettier --write'],
  '*.{json,md,css,scss}': 'prettier --write',
  // Bash/shell скрипты
  '*.sh': 'shellcheck',
};

Интеграция с Husky

# .husky/pre-commit
#!/usr/bin/env sh
. "$(dirname "$0")/_/husky.sh"

npx lint-staged

Как работает

git add src/components/Button.tsx src/utils/api.ts

# При git commit срабатывает pre-commit хук:
# 1. lint-staged получает список staged файлов:
#    [Button.tsx, api.ts]
# 2. Применяет правила для *.tsx и *.ts:
#    → eslint --fix Button.tsx api.ts
#    → prettier --write Button.tsx api.ts
# 3. Если файлы были изменены форматтером — re-stag автоматически
# 4. Если eslint завершился с ошибкой — коммит прерывается

Опции командной строки

# Запуск вручную (без коммита) на staged файлах
npx lint-staged

# Запуск на конкретных файлах (для тестирования)
npx lint-staged --diff="HEAD"

# Подробный вывод
npx lint-staged --verbose

# Не изменять файлы (только проверка)
npx lint-staged --no-stash

Частые ошибки

  • ESLint с --fix и Prettier запускают оба — разные правила форматирования конфликтуют. Решение: eslint-config-prettier
  • => 'tsc --noEmit' передаёт все файлы в tsc — не нужно, TypeScript сам найдёт зависимости
  • Нет --fix у ESLint — lint-staged не исправит ошибки, только найдёт их
  • Запуск тяжёлых тестов в lint-staged — должны быть только линтер и форматтер

Связанные темы

Ресурсы