Configuración de ESLint para Next.js

Q: ¿Por qué Next.js usa FlatCompat en lugar de configuración plana nativa?

Los presets de ESLint de Next.js (next/core-web-vitals, next/typescript) aún usan el formato heredado extends internamente. FlatCompat vincula estas configuraciones heredadas en la configuración plana de ESLint 9. Una vez que Next.js envíe soporte nativo de configuración plana, FlatCompat ya no será necesario.

Q: ¿Cuál es la diferencia entre next/core-web-vitals y next/typescript?

next/core-web-vitals agrupa reglas de React, hooks, import y Next.js-specific con defaults estrictos. next/typescript agrega reglas de @typescript-eslint/eslint-plugin ajustadas para Next.js. La mayoría de los proyectos extienden ambos.

Q: ¿Puedo usar un archivo .eslintrc en lugar de eslint.config.mjs?

ESLint 9 prefiere la configuración plana (eslint.config.mjs). Si existen tanto .eslintrc. como eslint.config.mjs, ESLint vuelve al archivo heredado. Elimina todos los archivos .eslintrc. al migrar a configuración plana para evitar confusión.

Q: Problema Común: ¿Por qué ESLint ignora mi patrón de ignores global?

En la configuración plana, ignores solo funciona como un ignore global cuando es la única clave en su objeto de configuración. Si mezclas ignores con rules en el mismo objeto, actúa como un filtro de archivo, no como un ignore global. Siempre pon los ignores globales en un objeto separado { ignores: [...] }.

Q: ¿Cómo suprimo errores de variables no utilizadas para parámetros de función en TypeScript?

Prefija parámetros no utilizados con _ y serán ignorados.

Q: ¿Cuál es el propósito de la configuración __filename y __dirname en eslint.config.mjs?

Los módulos ES no tienen globals __filename o __dirname. fileURLToPath(import.meta.url) y dirname() los recrean. FlatCompat requiere baseDirectory para resolver rutas de configuración relativas.

Q: ¿Cómo hago type-check del archivo de configuración de ESLint?

eslint.config.mjs es JavaScript plano, no TypeScript. Puedes agregar // @ts-check al principio y usar anotaciones JSDoc para type checking básico. Alternativamente, usa eslint.config.ts con soporte experimental de configuración TypeScript en ESLint 9.

Q: ¿Puedo ejecutar ESLint directamente en lugar de a través de next lint?

Usa npx eslint . cuando necesites control total sobre qué archivos se someten a linting.

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.

Alternativa	Úsalo Cuando	No lo Uses Cuando
Biome	Quieres una única herramienta rápida para linting y formateo	Necesitas el ecosistema completo de plugins de ESLint
`oxlint`	Quieres linting extremadamente rápido escrito en Rust	Necesitas reglas personalizadas o específicas de Next.js
CLI `eslint` directamente	Necesitas control total sobre qué archivos se someten a linting	Quieres defaults conscientes de Next.js fuera de la caja

Preguntas Frecuentes

¿Por qué Next.js usa FlatCompat en lugar de configuración plana nativa?

Los presets de ESLint de Next.js (next/core-web-vitals, next/typescript) aún usan el formato heredado extends internamente.
FlatCompat vincula estas configuraciones heredadas en la configuración plana de ESLint 9.
Una vez que Next.js envíe soporte nativo de configuración plana, FlatCompat ya no será necesario.

¿Cuál es la diferencia entre next/core-web-vitals y next/typescript?

next/core-web-vitals agrupa reglas de React, hooks, import y Next.js-specific con defaults estrictos.
next/typescript agrega reglas de @typescript-eslint/eslint-plugin ajustadas para Next.js.
La mayoría de los proyectos extienden ambos.

¿Puedo usar un archivo .eslintrc en lugar de eslint.config.mjs?

ESLint 9 prefiere la configuración plana (eslint.config.mjs).
Si existen tanto .eslintrc.* como eslint.config.mjs, ESLint vuelve al archivo heredado.
Elimina todos los archivos .eslintrc.* al migrar a configuración plana para evitar confusión.

¿Cómo realizo linting de directorios fuera de los defaults de Next.js?

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

¿Qué hace el modo --strict en next lint?

Trata todas las advertencias como errores.
Cualquier regla establecida en "warn" ahora fallará la ejecución de lint.
Útil en CI donde quieres tolerancia cero para advertencias.

Problema Común: ¿Por qué ESLint ignora mi patrón de ignores global?

En la configuración plana, ignores solo funciona como un ignore global cuando es la única clave en su objeto de configuración.
Si mezclas ignores con rules en el mismo objeto, actúa como un filtro de archivo, no como un ignore global.
Siempre pon los ignores globales en un objeto separado { ignores: [...] }.

¿Cómo suprimo errores de variables no utilizadas para parámetros de función en TypeScript?

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

Prefija parámetros no utilizados con _ y serán ignorados.

¿Cuál es el propósito de la configuración __filename y __dirname en eslint.config.mjs?

Los módulos ES no tienen globals __filename o __dirname.
fileURLToPath(import.meta.url) y dirname() los recrean.
FlatCompat requiere baseDirectory para resolver rutas de configuración relativas.

¿Cómo hago type-check del archivo de configuración de ESLint?

eslint.config.mjs es JavaScript plano, no TypeScript.
Puedes agregar // @ts-check al principio y usar anotaciones JSDoc para type checking básico.
Alternativamente, usa eslint.config.ts con soporte experimental de configuración TypeScript en ESLint 9.

Problema Común: ¿Por qué la primera ejecución de npx next lint me solicita elegir una configuración?

Next.js muestra un asistente de configuración en la primera ejecución si no existe un archivo de configuración de ESLint.
Para evitar esto, crea eslint.config.mjs antes de ejecutar npx next lint.
Elige "Strict" en el asistente para obtener los defaults de next/core-web-vitals.

¿Puedo ejecutar ESLint directamente en lugar de a través de next lint?

# 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

Usa npx eslint . cuando necesites control total sobre qué archivos se someten a linting.

¿Cómo agrego soporte de alias de ruta de TypeScript a ESLint?

El preset next/typescript configura el parser de TypeScript automáticamente.
Los aliases de ruta como @/* definidos en tsconfig.json se resuelven mediante el parser.
No se necesita configuración extra de ESLint para aliases de ruta en un proyecto de Next.js.

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

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.

Alternativa	Úsalo Cuando	No lo Uses Cuando
Biome	Quieres una única herramienta rápida para linting y formateo	Necesitas el ecosistema completo de plugins de ESLint
`oxlint`	Quieres linting extremadamente rápido escrito en Rust	Necesitas reglas personalizadas o específicas de Next.js
CLI `eslint` directamente	Necesitas control total sobre qué archivos se someten a linting	Quieres defaults conscientes de Next.js fuera de la caja

Preguntas Frecuentes

¿Por qué Next.js usa FlatCompat en lugar de configuración plana nativa?

Los presets de ESLint de Next.js (next/core-web-vitals, next/typescript) aún usan el formato heredado extends internamente.
FlatCompat vincula estas configuraciones heredadas en la configuración plana de ESLint 9.
Una vez que Next.js envíe soporte nativo de configuración plana, FlatCompat ya no será necesario.

¿Cuál es la diferencia entre next/core-web-vitals y next/typescript?

next/core-web-vitals agrupa reglas de React, hooks, import y Next.js-specific con defaults estrictos.
next/typescript agrega reglas de @typescript-eslint/eslint-plugin ajustadas para Next.js.
La mayoría de los proyectos extienden ambos.

¿Puedo usar un archivo .eslintrc en lugar de eslint.config.mjs?

ESLint 9 prefiere la configuración plana (eslint.config.mjs).
Si existen tanto .eslintrc.* como eslint.config.mjs, ESLint vuelve al archivo heredado.
Elimina todos los archivos .eslintrc.* al migrar a configuración plana para evitar confusión.

¿Cómo realizo linting de directorios fuera de los defaults de Next.js?

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

¿Qué hace el modo --strict en next lint?

Trata todas las advertencias como errores.
Cualquier regla establecida en "warn" ahora fallará la ejecución de lint.
Útil en CI donde quieres tolerancia cero para advertencias.

Problema Común: ¿Por qué ESLint ignora mi patrón de ignores global?

En la configuración plana, ignores solo funciona como un ignore global cuando es la única clave en su objeto de configuración.
Si mezclas ignores con rules en el mismo objeto, actúa como un filtro de archivo, no como un ignore global.
Siempre pon los ignores globales en un objeto separado { ignores: [...] }.

¿Cómo suprimo errores de variables no utilizadas para parámetros de función en TypeScript?

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

Prefija parámetros no utilizados con _ y serán ignorados.

¿Cuál es el propósito de la configuración __filename y __dirname en eslint.config.mjs?

Los módulos ES no tienen globals __filename o __dirname.
fileURLToPath(import.meta.url) y dirname() los recrean.
FlatCompat requiere baseDirectory para resolver rutas de configuración relativas.

¿Cómo hago type-check del archivo de configuración de ESLint?

eslint.config.mjs es JavaScript plano, no TypeScript.
Puedes agregar // @ts-check al principio y usar anotaciones JSDoc para type checking básico.
Alternativamente, usa eslint.config.ts con soporte experimental de configuración TypeScript en ESLint 9.

Problema Común: ¿Por qué la primera ejecución de npx next lint me solicita elegir una configuración?

Next.js muestra un asistente de configuración en la primera ejecución si no existe un archivo de configuración de ESLint.
Para evitar esto, crea eslint.config.mjs antes de ejecutar npx next lint.
Elige "Strict" en el asistente para obtener los defaults de next/core-web-vitals.

¿Puedo ejecutar ESLint directamente en lugar de a través de next lint?

# 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

Usa npx eslint . cuando necesites control total sobre qué archivos se someten a linting.

¿Cómo agrego soporte de alias de ruta de TypeScript a ESLint?

El preset next/typescript configura el parser de TypeScript automáticamente.
Los aliases de ruta como @/* definidos en tsconfig.json se resuelven mediante el parser.
No se necesita configuración extra de ESLint para aliases de ruta en un proyecto de Next.js.

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

Configuración de ESLint para Next.js

Buscar en la documentación

Configuración de ESLint para Next.js