ESLint

¿Qué es ESLint?

ESLint es un linter pluggable para JavaScript y TypeScript. Analiza tu código convirtiéndolo en un árbol de sintaxis, ejecuta un conjunto de reglas sobre él y reporta los problemas encontrados. Las reglas varían desde la detección de errores reales —variables no utilizadas, falta de await, comparaciones inseguras— hasta convenciones que tu equipo desee implementar.

El valor es acumulativo. Cada regla detecta una clase de error una sola vez, en todas partes y para siempre, en lugar de depender de que los revisores lo noten. Muchas reglas también se corrigen solas, por lo que eslint --fix limpia una cantidad sorprendente de código automáticamente. ESLint es una de las herramientas con mayor impacto en un proyecto de JavaScript.

Flat config

ESLint utiliza flat config: un archivo que exporta un array de objetos de configuración. Este formato reemplaza el antiguo formato .eslintrc mediante importaciones explícitas y una composición predecible.

// eslint.config.js
import js from "@eslint/js";
import tseslint from "typescript-eslint";

export default tseslint.config(
  { ignores: ["dist", "coverage", "**/*.generated.*"] },
  js.configs.recommended,
  ...tseslint.configs.recommended,
  {
    files: ["**/*.ts", "**/*.tsx"],
    rules: {
      "@typescript-eslint/no-floating-promises": "error",
    },
  },
);

Cada objeto puede especificar a qué archivos se aplica, qué plugins registra y qué reglas establece. Los objetos posteriores sobrescriben a los anteriores, por lo que el array se lee de arriba hacia abajo, como una cascada.

Reglas y severidad

Cada regla tiene una severidad: "off", "warn" o "error".

// rules.js
export default [
  {
    rules: {
      eqeqeq: "error",              // require ===
      "no-unused-vars": "warn",
      "no-console": ["warn", { allow: ["warn", "error"] }],
    },
  },
];

Algunas reglas aceptan opciones, como ocurre con no-console aquí. error hace que el CI falle; warn reporta el problema sin fallar. Usa warn para reglas que estés implementando gradualmente y error para cualquier cosa que deba bloquear un merge.

Plugins y presets

Los plugins añaden reglas para ecosistemas específicos, y los presets empaquetan un conjunto seleccionado de ellas.

// react.js
import react from "eslint-plugin-react";
import reactHooks from "eslint-plugin-react-hooks";

export default [
  react.configs.flat.recommended,
  reactHooks.configs["recommended-latest"],
];

Los plugins más comunes cubren React, Vue, TypeScript, imports, librerías de testing y accesibilidad. Empezar con eslint:recommended más un preset de framework te aporta el 90% del valor con casi ninguna configuración. Añade reglas individuales solo cuando tengas un motivo justificado.

Linting consciente de los tipos

typescript-eslint puede utilizar el comprobador de tipos de TypeScript para reglas que el análisis sintáctico simple no puede gestionar.

// type-aware.js
export default tseslint.config({
  languageOptions: {
    parserOptions: {
      projectService: true,
      tsconfigRootDir: import.meta.dirname,
    },
  },
  rules: {
    "@typescript-eslint/no-floating-promises": "error",
    "@typescript-eslint/no-misused-promises": "error",
  },
});

Reglas como no-floating-promises detectan errores que son realmente difíciles de notar al leer el código: una promesa que nunca se espera con await. El linting consciente de los tipos es más lento porque ejecuta el comprobador de tipos, por lo que muchos proyectos lo habilitan para el código fuente y lo omiten en las pruebas y los archivos de configuración.

Corrección y desactivación

Muchas reglas se pueden corregir automáticamente, así que ejecuta el corrector antes de leer la salida.

npx eslint . --fix

Cuando realmente necesites incumplir una regla, desactívala de forma puntual y explica el motivo.

// targeted.js
// eslint-disable-next-line no-console -- intentional debug log
console.log("payment flow", payload);

El uso de /* eslint-disable */ general al principio de un archivo desactiva todo, incluyendo las reglas que habrían detectado errores reales. Es preferible usar una desactivación de una sola línea con una justificación, y ajustar la configuración si una regla entra en conflicto con tus estándares.

Editores y CI

Instala la extensión de ESLint en tu editor y activa la opción de corregir al guardar (fix-on-save). Así recibirás feedback mientras escribes y se aplicarán correcciones seguras de inmediato, convirtiendo el linting en parte del flujo de edición en lugar de una tarea tediosa. En CI, ejecuta ESLint como un paso independiente para que los fallos sean claros y rápidos, y cachea los resultados siempre que sea posible.

Dónde encaja ESLint

ESLint se encarga de la calidad del código; Prettier se encarga del formato. La configuración estándar consiste en dejar que Prettier gestione el estilo y desactivar las reglas de ESLint que entren en conflicto, a menudo mediante una configuración compartida. Juntos, permiten que los revisores discutan el diseño en lugar de los espacios y los puntos y coma.

Mejores prácticas

• Comienza desde eslint:recommended y un preset de framework, y luego añade reglas de forma deliberada.
• Utiliza flat config con imports explícitos y una lista de ignores clara.
• Deja que Prettier se encargue del formateo y desactiva las reglas de ESLint que entren en conflicto.
• Ejecuta --fix antes de clasificar los problemas restantes.
• Activa las reglas type-aware para los archivos fuente.
• Desactiva las reglas de forma puntual, incluyendo un comentario que explique el motivo.
• Ejecuta el linting en el editor, en un pre-commit hook y en CI.

Errores comunes

• Hacer linting de dist, código generado y dependencias.
• Desactivar reglas de forma generalizada en lugar de solucionar la causa raíz.
• Activar todas las reglas a la vez y saturarse con el ruido.
• Duplicar reglas de formato que Prettier ya gestiona.
• Ejecutar linting basado en tipos (type-aware linting) en todo el repositorio, ralentizando el proceso.
• Tratar las advertencias como inofensivas hasta que se acumulan.

Próximos pasos

ESLint es la puerta de enlace de calidad para tu base de código. Combínalo con Prettier para el formateo, profundiza en los tipos con TypeScript e intégralo en el build de Vite y en tu pipeline de CI. Después, activa una regla nueva y corrige cada instancia; es un pequeño hábito con una gran recompensa.