Husky & lint-staged (Hooks de Pré-commit)

Execute ESLint e Prettier automaticamente em arquivos versionados antes de cada commit para capturar problemas precocemente.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Instale husky e lint-staged
npm install --save-dev husky lint-staged
 
# Inicialize o husky
npx husky init
 
# O comando init cria .husky/pre-commit
# Edite-o para executar lint-staged
echo "npx lint-staged" > .husky/pre-commit

Quando usar isso: Qualquer projeto de equipe onde você queira garantir que o código commitado passe nas verificações de linting e formatação.

Exemplo de Trabalho

# .husky/pre-commit
npx lint-staged

// package.json
{
  "scripts": {
    "lint": "next lint",
    "format": "prettier --write .",
    "prepare": "husky"
  },
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix --no-warn-ignored",
      "prettier --write"
    ],
    "*.{css,json,md}": [
      "prettier --write"
    ]
  }
}

O que isso demonstra:

• Husky se integra ao evento pre-commit do Git
• lint-staged executa ESLint e Prettier apenas em arquivos que estão versionados (git add)
• Arquivos TypeScript são lintados e formatados; outros arquivos são apenas formatados
• O script prepare garante que o husky seja instalado automaticamente após npm install

Mergulho Profundo

Como Funciona

• Husky usa hooks do Git (.husky/pre-commit) para executar comandos antes de cada commit
• lint-staged coleta arquivos de git diff --staged e os passa para os comandos configurados
• Comandos são executados em sequência por padrão de glob - se o ESLint falhar, o Prettier não é executado e o commit é bloqueado
• Arquivos corrigidos são automaticamente re-versionados para que o commit inclua as correções
• O script prepare é executado após npm install, garantindo que os hooks sejam configurados para cada desenvolvedor

Variações

Com Biome em vez de ESLint + Prettier:

{
  "lint-staged": {
    "*.{ts,tsx,js,jsx,json,css}": [
      "biome check --write --no-errors-on-unmatched"
    ]
  }
}

Com verificação de tipos (mais lento, mas completo):

{
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix --no-warn-ignored",
      "prettier --write"
    ]
  }
}

# .husky/pre-commit
npx lint-staged
npx tsc --noEmit

Nota: tsc --noEmit verifica todo o projeto, não apenas os arquivos versionados, pois o TypeScript precisa do contexto completo do projeto.

Linting de mensagens de commit com commitlint:

npm install --save-dev @commitlint/cli @commitlint/config-conventional
echo "npx commitlint --edit \$1" > .husky/commit-msg

// commitlint.config.js
export default { extends: ["@commitlint/config-conventional"] };

Ignorando hooks (válvula de escape):

# Quando você realmente precisar ignorar (depuração, commits WIP)
git commit --no-verify -m "WIP: work in progress"

Notas de TypeScript

// lint-staged passa caminhos de arquivo para o ESLint, que funciona
// com arquivos TypeScript perfeitamente, desde que @typescript-eslint
// esteja configurado.
 
// Nota: ESLint --fix pode corrigir automaticamente alguns problemas de TypeScript:
// - Remover imports não utilizados
// - Adicionar a palavra-chave `type` a imports apenas de tipo
// - Corrigir violações de consistent-type-imports

Armadilhas

Coisas que vão te morder. Cada armadilha inclui o que dá errado, por que acontece e a correção.

• Hooks não executando após clonar - Hooks do Git não são commitados no repositório; eles vivem em .git/hooks/. Novos desenvolvedores precisam executar npm install (que aciona prepare). Correção: Certifique-se de que "prepare": "husky" esteja em seus scripts do package.json.

• Avisos do ESLint em arquivos ignorados - Quando lint-staged passa caminhos de arquivo para o ESLint, arquivos que correspondem aos seus ignores do ESLint geram avisos. Correção: Adicione o flag --no-warn-ignored ao comando ESLint na configuração do lint-staged.

• Problemas de staging parcial - Se você versionar apenas parte de um arquivo (git add -p), lint-staged opera no arquivo completo, que pode incluir alterações não versionadas. Correção: Esteja ciente dessa limitação. Para casos críticos, comite o arquivo completo.

• Hooks de pré-commit lentos - Executar a verificação de tipos (tsc) em cada commit pode levar 10 segundos ou mais em projetos grandes. Correção: Execute tsc apenas em CI. Mantenha os hooks de pré-commit rápidos limitando-os a ESLint e Prettier em arquivos versionados.

• CI não executa hooks - Hooks do Git são apenas locais. Ambientes de CI não executam hooks de pré-commit. Correção: Sempre execute verificações de lint e formatação em CI como uma rede de segurança. Veja Linting em CI/CD.

Alternativas

Outras maneiras de resolver o mesmo problema - e quando cada uma é a melhor escolha.

FAQs

git commit --no-verify -m "WIP: work in progress"

# .husky/pre-commit
npx lint-staged
npx tsc --noEmit

{
  "lint-staged": {
    "*.{ts,tsx,js,jsx,json,css}": [
      "biome check --write --no-errors-on-unmatched"
    ]
  }
}

npm install --save-dev @commitlint/cli @commitlint/config-conventional
echo "npx commitlint --edit \$1" > .husky/commit-msg

Relacionados

• Configuração do ESLint para Next.js - Configuração do ESLint para a etapa de lint
• Configuração do Prettier - Configuração do Prettier para a etapa de formatação
• Integração ESLint + Prettier - Garanta que não haja conflitos entre os dois
• Linting em CI/CD - Rede de segurança de CI para hooks
• Configurações do EditorConfig & VS Code - Consistência em nível de editor