@alebat/default-alebat-config

@alebat/default-alebat-config es un paquete propio publicado en npm cuya única función real hoy es centralizar la configuración de Commitlint para que todos los repositorios de Alebat compartan exactamente la misma convención de mensajes de commit.

Repositorio: Alebat-Education/default-alebat-config

Ficha técnica

Concepto	Detalle
Paquete	@alebat/default-alebat-config
Versión	1.1.1
Tipo	Módulo ESM ("type": "module")
Entrada	dist/index.js (se compila con tsc)
Exporta	commitLintFront, commitLintBack
Se instala como	devDependency
Registro	npm público

npm install --save-dev @alebat/default-alebat-config
# o, en los proyectos que usan pnpm
pnpm add -D @alebat/default-alebat-config

Estructura del repositorio

• commitlint-config-front.ts configuración para proyectos front-end
• commitlint-config-back.ts configuración para proyectos back-end (Strapi)
• index.ts reexporta las dos anteriores
• package.json
• tsconfig.json
• README.md

El index.ts es de dos líneas — es simplemente el punto de entrada público del paquete:

index.ts

export { commitLintFront } from './commitlint-config-front'
export { commitLintBack } from './commitlint-config-back'

El README promete más de lo que el paquete hace hoy

El README menciona configuraciones para ESLint, Prettier, Stylelint y EditorConfig, pero están comentadas: los archivos no existen en el repositorio. A día de hoy el paquete solo aporta Commitlint. ESLint, Prettier y Stylelint se configuran hoy en cada proyecto por separado — centralizarlos aquí sigue siendo una mejora pendiente.

La configuración, campo por campo

Las dos exportaciones (commitLintFront y commitLintBack) comparten casi toda la estructura. Vamos primero por lo común.

extends

extends: ['@commitlint/config-conventional']

Parte del preset oficial de Conventional Commits, que ya trae las reglas básicas: el tipo es obligatorio, va en minúscula, la descripción no puede estar vacía, la cabecera tiene un largo máximo, etc. Todo lo que venga después en rules sobrescribe ese preset.

config-conventional hay que instalarlo aparte

El preset se resuelve desde el node_modules del proyecto consumidor, no del paquete. Por eso los proyectos necesitan también @commitlint/config-conventional y @commitlint/cli en sus devDependencies.

formatter

formatter: '@commitlint/format'

Es el formateador de la salida de error: el que produce el mensaje con colores, la flecha ⧗ input: y el nombre de la regla entre corchetes. Sin él verías un volcado de objeto en crudo.

rules comunes

Cada regla de Commitlint es un array de hasta tres posiciones: [nivel, condición, valor].

• nivel: 0 desactivada, 1 aviso, 2 error.
• condición: 'always' (se debe cumplir) o 'never' (se debe incumplir).
• valor: el parámetro de la regla, cuando aplica.

rules: {
  'subject-max-length': [2, 'always', 100],
  'subject-case': [2, 'never'],
  'scope-empty': [2, 'never'],
  'scope-case': [2, 'never'],
  'type-enum': [2, 'always', ['build', 'chore', 'ci', 'docs', 'feat', 'fix', 'perf', 'refactor', 'revert', 'style', 'test']],
}

Regla	Qué exige
subject-max-length	La descripción no puede pasar de 100 caracteres. No es que se suba un límite del preset: config-conventional no define esta regla, se añade aquí. El límite que de verdad manda es otro — ver el aviso de abajo.
subject-case	Nivel 2 con never y sin lista de casos: en la práctica no restringe ningún formato concreto de mayúsculas en la descripción. Es la forma de anular la restricción que config-conventional impone por defecto (que prohíbe, entre otros, empezar en mayúscula). Resultado: la descripción se puede escribir con la capitalización natural del español.
scope-empty	never = el ámbito nunca puede estar vacío. Esta es la desviación más visible respecto a Conventional Commits estándar, donde el ámbito es opcional. En Alebat es obligatorio: fix: algo se rechaza, fix(cart): algo se acepta.
scope-case	Igual que subject-case: anula la restricción de capitalización del ámbito. Por eso son válidos ámbitos en camelCase como coemCourses o ecomComponents.
type-enum	La lista cerrada de tipos permitidos. Ver la tabla completa en Commitlint.

El límite real de longitud no es 100, lo pone header-max-length

subject-max-length solo mide la descripción. Pero del preset heredamos también header-max-length: [2, 'always', 100], que mide la cabecera completa — tipo(ámbito): descripción. Como la cabecera siempre es más larga que la descripción, es header-max-length la que salta primero:

feat(checkout): ...
└──────┬──────┘└─┬─┘
   14 caracteres  quedan 86 para la descripción

Es decir: con feat(checkout): delante, la descripción se corta de hecho en 86 caracteres, no en 100, y el error que verás será [header-max-length], no [subject-max-length]. En la práctica subject-max-length casi nunca llega a dispararse.

Por qué scope-empty es la regla más importante del archivo

Obligar al ámbito es lo que convierte el historial en algo consultable. Con ámbito puedes preguntar “¿qué se ha tocado del checkout este mes?” (git log --grep "(checkout)"). Sin ámbito, el historial solo se puede leer de arriba abajo.

El resto de campos

ignores: [(commit: string) => commit === ''],
defaultIgnores: true,
helpUrl: 'https://github.com/conventional-changelog/commitlint/#what-is-commitlint',
prompt: {
  messages: {},
  questions: { type: { description: 'please input type:' } },
},

Campo	Función
ignores	Lista de funciones que, si devuelven true, hacen que Commitlint no valide ese mensaje. Aquí solo se ignora el mensaje vacío (que Git ya aborta por su cuenta).
defaultIgnores	true mantiene las exclusiones que Commitlint trae de fábrica: los mensajes que Git genera automáticamente. Es lo que permite que Merge pull request #135 from … o Revert … no sean rechazados, aunque no cumplan la convención.
helpUrl	La URL que se imprime al fallar.
prompt	Textos para @commitlint/prompt-cli, la utilidad interactiva que va preguntando tipo, ámbito y descripción. Está configurada pero no la usamos en el flujo habitual.

La diferencia entre front y back

Es una sola: commitLintBack añade una regla scope-enum, es decir, restringe también los ámbitos a una lista cerrada.

commitLintFront

No hay scope-enum. El ámbito es obligatorio pero libre: se puede usar cualquier palabra.

✅ feat(checkout): añadido el pago con Stripe Link
✅ fix(cursosCoem): corregido el filtro de categorías
✅ docs(ecomComponents): documentada la instalación

Por qué: los fronts son proyectos de dominio muy variado (verticales, tiendas, campus, Inspiria). Una lista cerrada de ámbitos se quedaría obsoleta en cada feature nueva y obligaría a publicar una versión del paquete para poder commitear.

commitLintBack

Añade una lista cerrada de 19 ámbitos, que se corresponden con la estructura de carpetas de un proyecto Strapi:

'scope-enum': [
  2, 'always',
  [
    'api', 'components', 'config', 'constants', 'controllers',
    'dependencies', 'documentation', 'extensions', 'lifecycles',
    'middlewares', 'plugins', 'readme', 'routes', 'schemas',
    'services', 'styles', 'testing', 'types', 'utils',
  ],
],

✅ feat(controllers): añadido el endpoint de suscripciones
✅ fix(lifecycles): corregido el afterCreate del pedido
❌ feat(suscripciones): ...   → 'suscripciones' no está en la lista

Por qué: todos nuestros back-ends son Strapi y comparten la misma estructura. Ahí sí tiene sentido cerrar la lista: el ámbito indica en qué capa has trabajado, lo cual es información útil y estable.

Cómo se implementa en un proyecto

1. Instalar las dependencias. Hacen falta tres paquetes en devDependencies:

   pnpm add -D @alebat/default-alebat-config @commitlint/cli @commitlint/config-conventional

   Y husky, si el proyecto no lo tiene ya.

2. Crear el commitlint.config.ts en la raíz del proyecto, con la exportación que corresponda:

   commitlint.config.ts (proyecto front)

   import { commitLintFront } from '@alebat/default-alebat-config'
   
   export default commitLintFront

   commitlint.config.ts (proyecto back / Strapi)

   import { commitLintBack } from '@alebat/default-alebat-config'
   
   export default commitLintBack

3. Excluir el archivo del linter. Como el commitlint.config.ts normalmente no entra en el tsconfig.json, hay que añadirlo a los ignores de eslint.config.js para que el parser de TypeScript no falle al analizarlo.

4. Crear el hook de Husky que lo ejecuta:

   .husky/commit-msg

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

5. Comprobar que funciona, intentando un commit deliberadamente inválido:

   git commit --allow-empty -m "prueba"
   # ✖ subject may not be empty [subject-empty]
   # ✖ type may not be empty [type-empty]

Modificar la configuración compartida

Como el paquete es compartido, cualquier cambio afecta a todos los repositorios que lo consuman en su próxima actualización. El flujo es:

1. Abrir una rama en default-alebat-config y editar commitlint-config-front.ts o commitlint-config-back.ts.

2. Compilar con npm run build (ejecuta tsc y genera dist/, que es lo que se publica).

3. Subir la versión en el package.json siguiendo semver. Añadir un tipo o un ámbito es una minor; quitarlos o hacer una regla más estricta es un cambio que romperá commits que antes eran válidos.

4. Abrir Pull Request y publicar en npm una vez aprobado.

5. En cada proyecto consumidor, actualizar la dependencia cuando se quiera adoptar el cambio.

Un proyecto puede sobrescribir puntualmente

Si un repositorio necesita una desviación, no hace falta cambiar el paquete: se puede extender la configuración importada. Úsalo con cuidado, porque cada excepción resta valor a tener una convención común.

commitlint.config.ts

import { commitLintFront } from '@alebat/default-alebat-config'

export default {
  ...commitLintFront,
  rules: {
    ...commitLintFront.rules,
    'subject-max-length': [2, 'always', 140],
    'header-max-length': [2, 'always', 140],
  },
}

Fíjate en que hay que subir las dos: tocar solo subject-max-length no serviría de nada, porque el header-max-length: 100 heredado del preset seguiría rechazando la cabecera.