Reglas ESLint esenciales

Configura las reglas ESLint más impactantes para React, hooks, TypeScript, importaciones y accesibilidad.

Receta

Tarjeta de referencia rápida — lista para copiar y pegar.

// Niveles de severidad
"off"   // 0 — desactiva la regla
"warn"  // 1 — advertencia amarilla, no falla CI
"error" // 2 — error rojo, falla CI y bloquea compilaciones
 
// Patrón común: anular una regla
{
  rules: {
    "rule-name": "error",
    "rule-name": ["error", { option: "value" }],
  },
}

Cuándo usarlo: Cuando los preajustes predeterminados son demasiado flexibles o estrictos y necesitas afinar reglas específicas.

Ejemplo funcional

// eslint.config.mjs
import { FlatCompat } from "@eslint/eslintrc";
import { dirname } from "path";
import { fileURLToPath } from "url";
 
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
 
const compat = new FlatCompat({ baseDirectory: __dirname });
 
const eslintConfig = [
  ...compat.extends("next/core-web-vitals", "next/typescript"),
  {
    rules: {
      // --- Reglas React ---
      "react/jsx-no-target-blank": "error",
      "react/no-unescaped-entities": "off",
      "react/self-closing-comp": "warn",
      "react/jsx-curly-brace-presence": [
        "warn",
        { props: "never", children: "never" },
      ],
 
      // --- Reglas hooks ---
      "react-hooks/rules-of-hooks": "error",
      "react-hooks/exhaustive-deps": "warn",
 
      // --- Reglas TypeScript ---
      "@typescript-eslint/no-unused-vars": [
        "error",
        {
          argsIgnorePattern: "^_",
          varsIgnorePattern: "^_",
          caughtErrorsIgnorePattern: "^_",
        },
      ],
      "@typescript-eslint/no-explicit-any": "warn",
      "@typescript-eslint/consistent-type-imports": [
        "error",
        { prefer: "type-imports" },
      ],
 
      // --- Reglas de importación ---
      "import/order": [
        "warn",
        {
          groups: [
            "builtin",
            "external",
            "internal",
            ["parent", "sibling"],
            "index",
            "type",
          ],
          "newlines-between": "always",
          alphabetize: { order: "asc", caseInsensitive: true },
        },
      ],
      "import/no-duplicates": "error",
 
      // --- Reglas de accesibilidad ---
      "jsx-a11y/alt-text": "error",
      "jsx-a11y/anchor-is-valid": "warn",
    },
  },
];
 
export default eslintConfig;

Lo que esto demuestra:

• Reglas organizadas por categoría: React, hooks, TypeScript, importaciones, accesibilidad
• Combinación de severidades error (debe corregirse) y warn (debería corregirse)
• Ignorancia basada en patrones de variables sin usar con prefijo _
• Ordenamiento de importaciones con separación de grupos y alfabetización

Inmersión profunda

Cómo funciona

• Cada regla tiene un nivel de severidad: "off", "warn" o "error"
• Las reglas pueden aceptar opciones como el segundo elemento de un array: ["error", { option: true }]
• El preajuste next/core-web-vitals ya habilita muchas reglas — las anulas en tu propia configuración
• Las reglas de plugins tienen prefijo del nombre del plugin (p. ej., react/, @typescript-eslint/)

Variaciones

Reglas React que vale la pena conocer:

Reglas hooks:

Reglas TypeScript que vale la pena habilitar:

Notas de TypeScript

// consistent-type-imports fuerza esto:
import type { User } from "@/types"; // importación solo-tipo
import { fetchUser } from "@/lib/api"; // importación de valor
 
// En lugar de mezclarlos:
import { User, fetchUser } from "@/lib/api"; // ❌ error de lint

Trampas

Cosas que te morderán. Cada trampa incluye qué sale mal, por qué sucede y la solución.

• Falsos positivos de exhaustive-deps — Esta regla a veces marca referencias estables como dispatch o refs. Solución: Usa // eslint-disable-next-line react-hooks/exhaustive-deps solo cuando estés seguro de que la dependencia es estable. Nunca la desactives globalmente.

• Conflictos de no-unused-vars con TypeScript — La regla base de ESLint no-unused-vars y @typescript-eslint/no-unused-vars pueden entrar en conflicto. Solución: Desactiva la regla base y usa solo la versión de TypeScript: "no-unused-vars": "off".

• import/order sin auto-corrección — La regla reporta violaciones pero --fix solo funciona para reordenar, no para agregar saltos de línea entre grupos retroactivamente. Solución: Ejecuta eslint --fix y agrega manualmente saltos de línea en el primer paso.

• La severidad importa para CI — Usar "warn" significa que CI pasa incluso con violaciones. Si quieres forzar una regla, usa "error". Solución: Reserva "warn" para reglas hacia las que te estás migrando, usa "error" para reglas forzadas.

Alternativas

Otras formas de resolver el mismo problema — y cuándo es mejor cada una.

Preguntas frecuentes

"no-unused-vars": "off",
"@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],

// Forzado (correcto):
import type { User } from "@/types";
import { fetchUser } from "@/lib/api";
 
// Rechazado (error de lint):
import { User, fetchUser } from "@/lib/api";

// Solo severidad:
"rule-name": "error"
 
// Severidad con opciones:
"rule-name": ["error", { option: "value" }]

const eslintConfig = [
  ...compat.extends("next/core-web-vitals"),
  { rules: { "react/no-unescaped-entities": "off" } },
];

Relacionado

• Configuración de ESLint para Next.js — configuración inicial de ESLint
• Plugins de ESLint — instala y configura plugins
• Modo estricto de TypeScript — complementa ESLint con opciones estrictas del compilador
• Integración ESLint + Prettier — evita conflictos de formateo