Mejores Prácticas de Linting

Puertas de calidad que mantienen las bases de código TypeScript Node consistentes, estrictas y aplicadas por CI.

Cómo Usar Esta Lista

• Adóptala al iniciar la configuración plana de ESLint en un nuevo servicio.
• Convierte las advertencias en errores una vez que la base de código esté limpia.
• Ejecuta los mismos comandos localmente que en CI; no hay reglas especiales solo para IDE.

A - Configuración de ESLint

• Usa la configuración plana de ESLint 9 (eslint.config.js). El .eslintrc heredado es una ruta obsoleta para nuevos repositorios.
• Habilita typescript-eslint recomendado o recommendedTypeChecked. Las reglas conscientes del tipo detectan errores asíncronos.
• Confirma ignores para dist/, node_modules/, coverage. La salida generada nunca debe ser linted.
• Separa las anulaciones para pruebas y scripts. Relaja no-explicit-any solo en las pruebas.
• Deshabilita las reglas estilísticas de ESLint cuando uses Prettier. eslint-config-prettier previene conflictos.

B - Formato y UX del Desarrollador

• Prettier para formato; ESLint para corrección. No debatas sobre tabulaciones en la revisión de código.
• Formato al guardar documentado para VS Code/Cursor. Misma extensión y configuración en todo el equipo.
• format:check en CI. Verificación de solo lectura en cada PR.
• lint-staged en pre-commit opcional; CI es obligatorio. --no-verify no debe eludir la calidad.
• .prettierignore excluye OpenAPI generado y dist. Evita cambios de formato sin sentido.

C - Puertas de Fusión de CI

• npm run typecheck (tsc --noEmit) en cada PR. Los tipos no son opcionales para los backends de TS.
• npm run lint -- --max-warnings 0 para una política de cero advertencias. Las advertencias se convierten rápidamente en deuda.
• Orden: install → typecheck → lint → test → build. Falla rápido en las comprobaciones más baratas.
• Fija Node 24.18.0 en CI para que coincida con los motores locales. ESLint consciente del tipo usa la misma versión de TS.
• Monorepos: turbo run lint typecheck con caché. Las tareas por paquete se mantienen en orden de gráfico.

D - Arquitectura e Higiene

• Prohíbe console.log en src/ mediante no-console. Usa un logger estructurado (Pino) en el código de la aplicación.
• Aplica límites de importación con eslint-plugin-import-x o Nx. Las aplicaciones no importan aplicaciones hermanas.
• no-extraneous-dependencies en código de producción. Las dependencias fantasma elevadas ocultan declaraciones faltantes.
• Ejecuta knip periódicamente para exportaciones y dependencias no utilizadas. Reduce la superficie de auditoría en monorepos.
• No uses @ts-ignore sin comentario y ticket. Prefiere @ts-expect-error con explicación.

E - Política y Propiedad

• Documenta cómo agregar una nueva regla de ESLint (RFC o chat de equipo). Evita guerras de reglas impulsivas en los PR.
• packages/eslint-config compartido en monorepos. Una única fuente de verdad para todos los servicios.
• Versión de ESLint bloqueada en el archivo de bloqueo raíz. npm ci asegura la paridad entre CI y local.
• Corrige el lint en el PR que introduce violaciones. No acumules deuda de lint de "corregir más tarde".
• Combina las puertas de lint con una lista de verificación de revisión de código. La automatización detecta la estructura; los humanos detectan el diseño.

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Linting - recorrido por la configuración plana
• Integración de Prettier - configuración de formato al guardar
• Typecheck en CI - puerta tsc --noEmit

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.