ESLint

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

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

Luego ejecuta npm run lint o yarn lint:

yarn lint

Si 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. Solo selecciona esta opción 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 que incluirá 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 quieres 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 que necesitas para tener una experiencia óptima de linting lista para usar en Next.js. Si 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 utilizan dentro de 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 el Conjunto de Reglas Recomendadas del Plugin para obtener más información.

Configuraciones Personalizadas

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 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, las banderas --dir y --file se pueden usar 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 la bandera --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 error varias reglas que son advertencias por defecto 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.

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 de la bandera --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],
}

Migrar Configuración Existente

Conjunto de Reglas Recomendadas del 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 dentro de 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 eliminar estas configuraciones si prefieres cómo se han configurado estas propiedades dentro de eslint-config-next o extender directamente desde el plugin de ESLint de Next.js:

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

El plugin se puede instalar 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 en múltiples configuraciones.

Configuraciones adicionales

Si ya utiliza una configuración separada de ESLint y desea incluir eslint-config-next, asegúrese de que se extienda al final, después de otras configuraciones. Por ejemplo:

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

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

Si incluye otras configuraciones compartibles, deberá asegurarse de que estas propiedades no se sobrescriban ni modifiquen. De lo contrario, recomendamos eliminar cualquier configuración que comparta comportamiento con la configuración next o extender directamente desde el plugin ESLint de Next.js como se mencionó anteriormente.