Husky y lint-staged (Ganchos de pre-commit)

Ejecuta ESLint y Prettier automáticamente en los archivos staged antes de cada commit para detectar problemas temprano.

Receta

Tarjeta de referencia rápida - lista para copiar y pegar.

# Instala husky y lint-staged
npm install --save-dev husky lint-staged
 
# Inicializa husky
npx husky init
 
# El comando init crea .husky/pre-commit
# Edítalo para ejecutar lint-staged
echo "npx lint-staged" > .husky/pre-commit

Cuándo usarlo: Cualquier proyecto en equipo donde quieras garantizar que el código cometido pase los controles de linting y formateo.

Ejemplo de Trabajo

# .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"
    ]
  }
}

Lo que demuestra esto:

• Husky se engancha al evento pre-commit de Git
• lint-staged ejecuta ESLint y Prettier solo en archivos que son staged (git add)
• Los archivos TypeScript obtienen linting y formateo; otros archivos solo obtienen formateo
• El script prepare asegura que husky se instale automáticamente después de npm install

Análisis Profundo

Cómo Funciona

• Husky utiliza ganchos de Git (.husky/pre-commit) para ejecutar comandos antes de cada commit
• lint-staged recopila archivos de git diff --staged y los pasa a los comandos configurados
• Los comandos se ejecutan en secuencia por patrón glob - si ESLint falla, Prettier no se ejecuta y el commit se bloquea
• Los archivos reparados se revisten automáticamente para que el commit incluya las correcciones
• El script prepare se ejecuta después de npm install, asegurando que los ganchos estén configurados para cada desarrollador

Variaciones

Con Biome en lugar de ESLint + Prettier:

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

Con revisión de tipos (más lento pero exhaustivo):

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

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

Nota: tsc --noEmit revisa el proyecto completo, no solo los archivos staged, porque TypeScript necesita el contexto completo del proyecto.

Linting de mensajes de commit con 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"] };

Omitiendo ganchos (escotilla de escape):

# Cuando realmente necesitas eludir (depuración, commits WIP)
git commit --no-verify -m "WIP: trabajo en progreso"

Notas de TypeScript

// lint-staged pasa rutas de archivo a ESLint, que funciona con
// archivos TypeScript sin problemas siempre que @typescript-eslint
// esté configurado.
 
// Nota: ESLint --fix puede corregir automáticamente algunos problemas de TypeScript:
// - Eliminar importaciones no utilizadas
// - Agregar la palabra clave `type` a importaciones solo de tipos
// - Corregir violaciones de consistent-type-imports

Gotchas

Cosas que te van a morder. Cada gotcha incluye qué sale mal, por qué sucede y la solución.

• Los ganchos no se ejecutan después de clonar - Los ganchos de Git no se cometieron al repo; viven en .git/hooks/. Los nuevos desarrolladores deben ejecutar npm install (que dispara prepare). Solución: Asegúrate de que "prepare": "husky" esté en tus scripts de package.json.

• Advertencias de ESLint en archivos ignorados - Cuando lint-staged pasa rutas de archivo a ESLint, los archivos que coinciden con tus ignorados de ESLint disparan advertencias. Solución: Agrega la flag --no-warn-ignored al comando de ESLint en la configuración de lint-staged.

• Problemas de staging parcial - Si revistes solo parte de un archivo (git add -p), lint-staged opera en el archivo completo, que puede incluir cambios no staged. Solución: Ten conocimiento de esta limitación. Para casos críticos, reviste el archivo completo.

• Ganchos de pre-commit lentos - Ejecutar revisión de tipos (tsc) en cada commit puede tomar 10 o más segundos en proyectos grandes. Solución: Ejecuta tsc solo en CI. Mantén los ganchos de pre-commit rápidos limitándolos a ESLint y Prettier en archivos staged.

• CI no ejecuta ganchos - Los ganchos de Git son solo locales. Los entornos de CI no ejecutan ganchos de pre-commit. Solución: Siempre ejecuta linting y controles de formateo en CI como red de seguridad. Ver Linting en CI/CD.

Alternativas

Otras formas de resolver el mismo problema - y cuándo cada una es la mejor opción.

FAQs

git commit --no-verify -m "WIP: trabajo en progreso"

# .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

Relacionado

• Configuración de ESLint para Next.js - Configuración de ESLint para el paso de lint
• Configuración de Prettier - Configuración de Prettier para el paso de formateo
• Integración de ESLint + Prettier - asegurar que no haya conflictos entre los dos
• Linting en CI/CD - Red de seguridad de CI para ganchos
• EditorConfig y Configuración de VS Code - Consistencia a nivel de editor