Skip to main content

Estilo de código (ESLint, Prettier y convenciones)

El repositorio apolo-app-platcom-platform aplica un conjunto de reglas para mantener un código consistente y fácil de mantener en backend (NestJS), frontend (React) y librerías compartidas.

Estas reglas se implementan principalmente con:

  • ESLint → Reglas de calidad y buenas prácticas
  • Prettier → Formateo de código
  • Husky + lint-staged → Validación automática en cada commit

Linting (ESLint)​

Para ejecutar el lint de todo el workspace:

npm run lint:all

Para ejecutar el lint de un proyecto específico:

npx nx lint bff-api
npx nx lint auth-api
npx nx lint portal-web

Principios generales​

  • Código escrito en TypeScript (no usar any salvo que esté justificado).
  • Respetar patrones del framework:
    • NestJS: módulos, providers, inyección de dependencias, controllers limpios.
    • React: componentes funcionales, hooks, evitar lógica compleja en el JSX.
  • Evitar lógica de negocio en controladores / componentes:
    • Extraer a servicios, hooks, use cases o librerías en libs/.
  • Mantener funciones y métodos con responsabilidad única.

Formateo (Prettier)​

El formateo es gestionado por Prettier, configurado para aplicarse de forma consistente en:

  • Archivos .ts, .tsx`
  • Archivos .js
  • Archivos .md (Markdown), salvo que se configure lo contrario

Para formatear todo el proyecto:

npx nx format:write

Para solo verificar sin modificar:

npx nx format:check

Nota: Si existe documentación generada automáticamente (por ejemplo, Markdown generado por scripts), es recomendable excluir esos archivos concretos en la configuración de Prettier/ESLint para evitar conflictos.

Convenciones específicas​

Backend (NestJS)​

  • Usar DTOs tipados y esquemas de validación (p.ej. Zod) para requests.
  • Los controladores deben:
    • Validar y delegar en servicios.
    • No contener lógica de negocio pesada.
  • Los servicios deben ser cohesivos (un servicio por dominio lógico).
  • Manejo de errores consistente:
    • Uso de HttpException o filtros globales.
    • Mensajes orientados a diagnóstico, sin exponer información sensible.

Frontend (React + ITDS + Tailwind)​

  • Componentes enfocados en una sola responsabilidad.
  • Hooks reutilizables para lógica de datos / fetch / estados complejos.
  • Estilos:
    • Respetar el diseño y componentes de ITDS para consistencia visual.
    • Aplicar Tailwind para cosas que ITDS no logre cubrir en totalidad.
  • Estado remoto y caching:
    • Usar TanStack Query donde esté definido.
    • Evitar reimplementar caches manuales cuando ya existe un patrón.

Organización del código​

  • Reutilizar librerías compartidas en libs/ para:
    • Tipos comunes
    • Modelos de dominio
    • Utilidades de auditoría y eventos
  • Evitar duplicar lógica entre:
    • bff-api y otros microservicios
    • portal-web y `playground-library Cuando veas lógica repetida, evalúa moverla a una lib compartida.

Integración con los hooks de Git​

Antes de aceptar un commit, el proyecto ejecuta:

  • ESLint sobre archivos modificados
  • Prettier (via lint-staged) para formateo

Si el commit se bloquea:

  1. Revisa los errores en consola.
  2. Ejecuta manualmente:
npx nx lint <proyecto>
npx nx format:write
  1. Corrige y vuelve a intentar tu commit.

Mantener un estilo de código consistente facilita:

  • La revisión de PRs
  • El on-boarding de nuevos desarrolladores
  • La mantenibilidad de una plataforma regional, multi-módulo y multi-equipo como Apolo.