ESLint

Next.js proporciona una experiencia integrada con ESLint lista para usar. Agrega next lint como un script en package.json:

{
  "scripts": {
    "lint": "next lint"
  }
}

Luego ejecuta npm run lint o yarn lint:

yarn lint

Si aún no tienes ESLint configurado en tu aplicación, se te guiará a través del proceso de instalación y configuración.

yarn lint

Verás un mensaje como este:

? ¿Cómo te gustaría configurar ESLint?

❯ Estricto (recomendado)
Base
Cancelar

Puedes seleccionar una de las siguientes tres opciones:

• Estricto: Incluye la configuración base de ESLint de Next.js junto con un conjunto de reglas más estrictas para Core Web Vitals. Esta es la configuración recomendada para desarrolladores que configuran ESLint por primera vez.

  {
    "extends": "next/core-web-vitals"
  }

• Base: Incluye solo la configuración base de ESLint de Next.js.

  {
    "extends": "next"
  }

• Cancelar: No incluye ninguna configuración de ESLint. Selecciona esta opción solo si planeas configurar tu propia configuración personalizada de ESLint.

Si seleccionas cualquiera de las dos opciones de configuración, Next.js instalará automáticamente eslint y eslint-config-next como dependencias en tu aplicación y creará un archivo .eslintrc.json en la raíz de tu proyecto con la configuración seleccionada.

Ahora puedes ejecutar next lint cada vez que quieras ejecutar ESLint para detectar errores. Una vez configurado ESLint, también se ejecutará automáticamente durante cada compilación (next build). Los errores harán que falle la compilación, mientras que las advertencias no.

Si no deseas que ESLint se ejecute durante next build, consulta la documentación para Ignorar ESLint.

Recomendamos usar una integración adecuada para ver advertencias y errores directamente en tu editor de código durante el desarrollo.

Configuración de ESLint

La configuración predeterminada (eslint-config-next) incluye todo lo necesario para una experiencia óptima de linting con Next.js. Si aún no tienes ESLint configurado en tu aplicación, recomendamos usar next lint para configurar ESLint junto con esta configuración.

Si deseas usar eslint-config-next junto con otras configuraciones de ESLint, consulta la sección Configuraciones Adicionales para aprender cómo hacerlo sin causar conflictos.

Los conjuntos de reglas recomendados de los siguientes plugins de ESLint se incluyen en eslint-config-next:

• eslint-plugin-react
• eslint-plugin-react-hooks
• eslint-plugin-next

Esto tendrá prioridad sobre la configuración de next.config.js.

Plugin de ESLint

Next.js proporciona un plugin de ESLint, eslint-plugin-next, ya incluido en la configuración base que permite detectar problemas comunes en una aplicación Next.js. El conjunto completo de reglas es el siguiente:

Habilitado en la configuración recomendada

Si ya tienes ESLint configurado en tu aplicación, recomendamos extender directamente desde este plugin en lugar de incluir eslint-config-next a menos que se cumplan algunas condiciones. Consulta Conjunto de Reglas Recomendadas del Plugin para más información.

Configuración Personalizada

rootDir

Si estás usando eslint-plugin-next en un proyecto donde Next.js no está instalado en tu directorio raíz (como un monorepo), puedes indicarle a eslint-plugin-next dónde encontrar tu aplicación Next.js usando la propiedad settings en tu .eslintrc:

{
  "extends": "next",
  "settings": {
    "next": {
      "rootDir": "packages/my-app/"
    }
  }
}

rootDir puede ser una ruta (relativa o absoluta), un glob (ej. "packages/*/") o un array de rutas y/o globs.

Linting de Directorios y Archivos Personalizados

Por defecto, Next.js ejecutará ESLint para todos los archivos en los directorios pages/, app/, components/, lib/ y src/. Sin embargo, puedes especificar qué directorios usar con la opción dirs en la configuración eslint de next.config.js para compilaciones de producción:

module.exports = {
  eslint: {
    dirs: ['pages', 'utils'], // Solo ejecuta ESLint en los directorios 'pages' y 'utils' durante compilaciones de producción (next build)
  },
}

De manera similar, se pueden usar los flags --dir y --file con next lint para hacer linting de directorios y archivos específicos:

next lint --dir pages --dir utils --file bar.js

Caché

Para mejorar el rendimiento, la información de los archivos procesados por ESLint se almacena en caché por defecto. Esto se guarda en .next/cache o en tu directorio de compilación definido. Si incluyes reglas de ESLint que dependen de más que el contenido de un solo archivo fuente y necesitas deshabilitar la caché, usa el flag --no-cache con next lint.

next lint --no-cache

Deshabilitar Reglas

Si deseas modificar o deshabilitar cualquier regla proporcionada por los plugins soportados (react, react-hooks, next), puedes cambiarlas directamente usando la propiedad rules en tu .eslintrc:

{
  "extends": "next",
  "rules": {
    "react/no-unescaped-entities": "off",
    "@next/next/no-page-custom-font": "off"
  }
}

Core Web Vitals

El conjunto de reglas next/core-web-vitals se habilita cuando next lint se ejecuta por primera vez y se selecciona la opción estricto.

{
  "extends": "next/core-web-vitals"
}

next/core-web-vitals actualiza eslint-plugin-next para marcar como errores varias reglas que normalmente son advertencias si afectan Core Web Vitals.

El punto de entrada next/core-web-vitals se incluye automáticamente para nuevas aplicaciones creadas con Create Next App.

TypeScript

Además de las reglas de ESLint de Next.js, create-next-app --typescript también agregará reglas específicas de TypeScript con next/typescript a tu configuración:

{
  "extends": ["next/core-web-vitals", "next/typescript"]
}

Estas reglas se basan en plugin:@typescript-eslint/recommended. Consulta typescript-eslint > Configs para más detalles.

Uso con Otras Herramientas

Prettier

ESLint también incluye reglas de formato de código, que pueden entrar en conflicto con tu configuración existente de Prettier. Recomendamos incluir eslint-config-prettier en tu configuración de ESLint para que ESLint y Prettier trabajen juntos.

Primero, instala la dependencia:

npm install --save-dev eslint-config-prettier

yarn add --dev eslint-config-prettier

pnpm add --save-dev eslint-config-prettier

bun add --dev eslint-config-prettier

Luego, agrega prettier a tu configuración existente de ESLint:

{
  "extends": ["next", "prettier"]
}

lint-staged

Si deseas usar next lint con lint-staged para ejecutar el linter en archivos git en staging, debes agregar lo siguiente al archivo .lintstagedrc.js en la raíz de tu proyecto para especificar el uso del flag --file.

const path = require('path')

const buildEslintCommand = (filenames) =>
  `next lint --fix --file ${filenames
    .map((f) => path.relative(process.cwd(), f))
    .join(' --file ')}`

module.exports = {
  '*.{js,jsx,ts,tsx}': [buildEslintCommand],
}

Migración de Configuración Existente

Conjunto de reglas recomendadas para el plugin

Si ya tienes ESLint configurado en tu aplicación y alguna de las siguientes condiciones es verdadera:

• Tienes uno o más de los siguientes plugins ya instalados (ya sea por separado o a través de una configuración diferente como airbnb o react-app):
  • react
  • react-hooks
  • jsx-a11y
  • import
• Has definido parserOptions específicos que son diferentes a cómo está configurado Babel en Next.js (esto no se recomienda a menos que hayas personalizado tu configuración de Babel)
• Tienes eslint-plugin-import instalado con resolvers de Node.js y/o TypeScript definidos para manejar imports

Entonces recomendamos que elimines estas configuraciones si prefieres cómo están definidas estas propiedades dentro de eslint-config-next o que extiendas directamente del plugin ESLint de Next.js:

module.exports = {
  extends: [
    //...
    'plugin:@next/next/recommended',
  ],
}

El plugin puede instalarse normalmente en tu proyecto sin necesidad de ejecutar next lint:

npm install --save-dev @next/eslint-plugin-next

yarn add --dev @next/eslint-plugin-next

pnpm add --save-dev @next/eslint-plugin-next

bun add --dev @next/eslint-plugin-next

Esto elimina el riesgo de colisiones o errores que pueden ocurrir al importar el mismo plugin o parser a través de múltiples configuraciones.

Configuraciones adicionales

Si ya usas una configuración separada de ESLint y deseas incluir eslint-config-next, asegúrate de extenderla después de otras configuraciones. Por ejemplo:

{
  "extends": ["eslint:recommended", "next"]
}

La configuración next ya maneja los valores por defecto para las propiedades parser, plugins y settings. No es necesario volver a declarar manualmente ninguna de estas propiedades a menos que necesites una configuración diferente para tu caso de uso.

Si incluyes otras configuraciones compartibles, deberás asegurarte de que estas propiedades no sean sobrescritas o modificadas. De lo contrario, recomendamos eliminar cualquier configuración que comparta comportamiento con la configuración next o extender directamente del plugin ESLint de Next.js como se mencionó anteriormente.