Introducción a las herramientas de calidad de código

En los proyectos front-end de Alebat convivimos con seis herramientas que se encargan de que todo el código del equipo se parezca al código de una sola persona, y de que nada roto entre en main.

Esta sección está escrita para que puedas entender la configuración sin haber usado nunca ninguna de estas herramientas. Primero explicamos qué hace cada una y por qué existe; después analizamos cómo están implementadas realmente en nuestros repositorios.

El problema que resuelven

Cuando varias personas trabajan sobre el mismo repositorio aparecen tres tipos de fricción:

Estilo: unos usan comillas dobles, otros simples; unos ponen punto y coma, otros no. El git diff se llena de cambios que no cambian nada.
Errores evitables: variables declaradas y nunca usadas, un v-for sin :key, un !important colado en un CSS.
Historial ilegible: commits llamados cambios, fix, ya va. Imposible saber qué pasó en una release.

Cada herramienta ataca una parte de ese problema:

Herramienta	¿Qué revisa?	¿Sobre qué archivos?
Prettier	El formato: sangrado, comillas, saltos de línea, ancho máximo	`.js` `.ts` `.vue` `.json` `.css` `.md`
ESLint	La lógica y los patrones de JavaScript/TypeScript/Vue	`.js` `.ts` `.vue`
Stylelint	Los estilos: CSS y el `<style>` de los `.vue`	`.vue` `.css` `.scss`
Commitlint	El mensaje del commit	— (revisa texto, no archivos)
lint-staged	Nada por sí mismo: lanza las anteriores solo sobre lo que vas a commitear	los archivos en staging
Husky	Nada por sí mismo: engancha todo lo anterior a los comandos de Git	—

Cómo encajan: el flujo de un commit

Esta es la secuencia completa que se dispara cuando alguien hace git commit en un proyecto configurado:

Escribes código y lo guardas. Si tienes las extensiones de VS Code instaladas, Prettier ya te ha formateado el archivo al guardar.
git add — marcas los archivos que quieres commitear (esto es el staging area).
git commit — aquí Git se detiene y ejecuta los hooks que Husky ha instalado:
- Hook pre-commit → lanza lint-staged, que a su vez ejecuta ESLint y Stylelint solo sobre los archivos que has añadido con git add. Si algo se puede arreglar automáticamente, se arregla; si no, el commit se aborta.
- Hook commit-msg → lanza Commitlint sobre el mensaje que has escrito. Si no cumple el formato, el commit se aborta.
El commit se crea solo si los dos pasos anteriores han pasado.

git commit
    │
    ├── hook pre-commit (Husky)
    │        └── lint-staged
    │                ├── eslint --fix   (archivos .ts .js .vue en staging)
    │                └── stylelint --fix (archivos .vue .css .scss en staging)
    │
    └── hook commit-msg (Husky)
             └── commitlint  (valida el texto del mensaje)
                     │
                     └── ¿cumple? ──► commit creado
                         ¿no?     ──► commit abortado

Dónde vive cada configuración

En un proyecto típico nuestro, la raíz del repositorio contiene un archivo por herramienta:

proyecto/
├── .husky/
│   ├── pre-commit          ← script que corre antes de crear el commit
│   └── commit-msg          ← script que valida el mensaje
├── .lintstagedrc           ← qué comando aplicar a qué extensión
├── .prettierrc             ← reglas de formato
├── .stylelintrc.json       ← reglas de CSS
├── eslint.config.js        ← reglas de JS/TS/Vue
├── commitlint.config.ts    ← reglas de mensajes de commit
└── package.json            ← scripts + dependencias + "prepare": "husky"

Configuración compartida

Las reglas de Commitlint no se escriben en cada proyecto: viven en un paquete propio, @alebat/default-alebat-config, y cada repositorio simplemente las importa. Eso garantiza que un commit válido en un proyecto lo sea también en el resto.

Prettier El formateador: qué hace y qué opciones usamos

ESLint El linter de JS/TS/Vue y su integración con Prettier

Stylelint El linter de estilos, incluido el