Configuración de ESLint para Next.js

Configura ESLint con el formato de configuración plana para un proyecto Next.js utilizando presets integrados.

Receta

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

# Instala ESLint (incluido con create-next-app)
npm install --save-dev eslint eslint-config-next
 
# Ejecuta linting a través de la CLI de Next.js
npx next lint
 
# Lint y auto-fix
npx next lint --fix
 
# Lint de directorios específicos
npx next lint --dir src --dir app

Cuándo usarlo: Cada proyecto de Next.js debe tener ESLint configurado desde el primer día.

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: {
      // Personaliza las reglas aquí
      "@typescript-eslint/no-unused-vars": [
        "error",
        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
      ],
      "react/no-unescaped-entities": "off",
    },
  },
  {
    ignores: [
      "node_modules/",
      ".next/",
      "out/",
      "public/",
      "coverage/",
    ],
  },
];
 
export default eslintConfig;

Lo que esto demuestra:

• Formato de configuración plana de ESLint 9 usando eslint.config.mjs
• Usando FlatCompat para vincular configuraciones de Next.js (que aún usan el formato heredado) en configuración plana
• Extendiendo next/core-web-vitals (incluye reglas de React, hooks e import) y next/typescript
• Personalizar una regla e ignorar directorios

Profundización

Cómo Funciona

• Next.js incluye su propia integración de ESLint a través de npx next lint
• El preset next/core-web-vitals agrupa eslint-plugin-react, eslint-plugin-react-hooks, eslint-plugin-next y eslint-plugin-import con defaults estrictos
• El preset next/typescript agrega reglas de @typescript-eslint/eslint-plugin ajustadas para Next.js
• ESLint 9 usa configuración plana (eslint.config.mjs) en lugar del formato .eslintrc heredado
• FlatCompat es un puente que te permite usar configuraciones de estilo extends heredado dentro de la configuración plana — necesario porque los presets de Next.js aún no han migrado completamente

Variaciones

ESLint Independiente (sin next lint):

# Ejecuta ESLint directamente
npx eslint . --fix
 
# O a través de script en package.json

{
  "scripts": {
    "lint": "next lint",
    "lint:fix": "next lint --fix",
    "lint:strict": "next lint --strict"
  }
}

Modo estricto (trata advertencias como errores):

npx next lint --strict

Ignorar archivos:

// En eslint.config.mjs — bloque ignores
{
  ignores: [
    "**/*.config.js",
    "**/*.config.mjs",
    "migrations/",
    "generated/",
  ],
}

Notas de TypeScript

# El preset next/typescript maneja estos automáticamente:
# - @typescript-eslint/parser está configurado
# - Las reglas conscientes de TypeScript están habilitadas
# - Los archivos .ts y .tsx se incluyen por defecto

Problemas Comunes

Cosas que te harán tropezar. Cada problema incluye qué sale mal, por qué sucede y la solución.

• Configuración plana no detectada — Si ESLint ignora tu eslint.config.mjs, es posible que tengas un archivo .eslintrc.* antiguo. ESLint 9 prefiere la configuración plana pero vuelve a la heredada si ambas existen. Solución: Elimina todos los archivos .eslintrc.* cuando uses configuración plana.

• La primera ejecución solicita configuración — Ejecutar npx next lint por primera vez muestra un asistente de configuración. Solución: Elige "Strict" para next/core-web-vitals o crea el archivo de configuración manualmente de antemano.

• Los ignores deben ser un objeto separado — En la configuración plana, el array ignores solo funciona como un ignore global cuando es la única clave en su objeto de configuración. Mezclar ignores con rules en el mismo objeto lo convierte en un filtro, no en un ignore global. Solución: Siempre pon los ignores globales en su propio objeto { ignores: [...] }.

• Rendimiento en proyectos grandes — npx next lint solo realiza linting en app/, pages/, components/, lib/ y src/ por defecto. Los directorios personalizados necesitan --dir. Solución: Agrega flags --dir o configura eslint.dirs en next.config.js.

Alternativas

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

Preguntas Frecuentes

# Next.js solo realiza linting en app/, pages/, components/, lib/, src/ por defecto
npx next lint --dir src --dir utils --dir services

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

# ESLint directo (omite los defaults de directorio de Next.js)
npx eslint . --fix
 
# next lint (respeta los defaults de directorio de Next.js)
npx next lint --fix

Relacionado

• Reglas ESLint Esenciales — configura reglas individuales
• Plugins de ESLint — agrega plugins para React, TypeScript, accesibilidad
• Integración ESLint + Prettier — evita conflictos de formateo
• Linting en CI/CD — ejecuta ESLint en GitHub Actions