Cómo configurar Husky con Conventional Commits, Prettier y ESLint (Husky v9)

Husky te deja ejecutar Git hooks de forma sencilla: comandos que corren automáticamente antes de un commit o al escribir su mensaje. Con eso puedes impedir que entre al repositorio código sin formatear, con errores de lint o con mensajes de commit desordenados.

En esta nota configuramos, en este orden:

1. Prettier, para formatear el código.
2. ESLint, para encontrar errores.
3. Husky, para correr los dos antes de cada commit.
4. commitlint, para obligar a usar Conventional Commits.

Esta guía usa Husky v9. Si ves tutoriales con npx husky-init o npx husky add, son de versiones anteriores: esos comandos ya no funcionan.

1. Prettier #

Instálalo:

npm install --save-dev --save-exact prettier

Crea el archivo de configuración .prettierrc en la raíz del proyecto. Esta es la que uso yo:

{
  "printWidth": 80,
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "all",
  "endOfLine": "auto"
}

Para formatear todo el proyecto o solo revisar sin cambiar archivos:

npx prettier --write .
npx prettier --check .

Prettier ignora lo que está en .gitignore. Si necesitas ignorar algo más, créalo en un archivo .prettierignore.

2. ESLint #

ESLint trae un asistente que crea la configuración por ti:

npm init @eslint/config@latest

Responde las preguntas (JavaScript o TypeScript, React o no, etc.) y te crea un archivo eslint.config.mjs. Para revisar el proyecto:

npx eslint .

Para que ESLint y Prettier no se peleen por el formato, instala eslint-config-prettier:

npm install --save-dev eslint-config-prettier

Y agrégalo al final de tu eslint.config.mjs:

import eslintConfigPrettier from 'eslint-config-prettier';

export default [
  // ...tu configuración actual
  eslintConfigPrettier,
];

Por último, agrega dos scripts en tu package.json:

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

3. Husky #

Necesitas un repositorio de Git ya inicializado (git init). Instala Husky y ejecuta su comando de inicio:

npm install --save-dev husky
npx husky init

husky init hace dos cosas:

• Crea la carpeta .husky/ con un hook pre-commit.
• Agrega el script "prepare": "husky" a tu package.json, para que los hooks se instalen solos cuando alguien haga npm install.

Ahora edita .husky/pre-commit para que corra tu script de lint. El archivo debe quedar solo con esta línea:

npm run lint

Desde ahora, si el código no pasa Prettier o ESLint, el commit se cancela.

Si tu proyecto es grande, revisar todo en cada commit puede ser lento. Con lint-staged puedes revisar solo los archivos que vas a commitear.

4. commitlint y Conventional Commits #

Instala commitlint con la configuración de Conventional Commits:

npm install --save-dev @commitlint/cli @commitlint/config-conventional

Crea el archivo commitlint.config.mjs en la raíz:

export default { extends: ['@commitlint/config-conventional'] };

Y crea el hook que revisa el mensaje de cada commit, en .husky/commit-msg:

npx --no -- commitlint --edit $1

Pruébalo #

Intenta un commit con un mensaje cualquiera:

git commit -m "cambios"

commitlint lo rechaza porque no sigue el formato. En cambio, esto sí pasa:

git commit -m "feat: agrega formulario de contacto"

Los tipos más usados son feat (funcionalidad nueva), fix (corrección), docs, refactor, test y chore.

Resumen #

Si además quieres dejar limpio el historial antes de un pull request, mira cómo hacer squash en Git.