ESLint

Next.js offre une expérience intégrée ESLint prête à l'emploi. Ajoutez next lint comme script dans package.json :

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

Puis exécutez npm run lint ou yarn lint :

yarn lint

Si ESLint n'est pas déjà configuré dans votre application, vous serez guidé à travers le processus d'installation et de configuration.

yarn lint

Vous verrez une invite comme celle-ci :

? Comment souhaitez-vous configurer ESLint ?

❯ Strict (recommandé)
Base
Annuler

L'une des trois options suivantes peut être sélectionnée :

• Strict : Inclut la configuration de base ESLint de Next.js ainsi qu'un ensemble de règles plus strictes pour les Core Web Vitals. C'est la configuration recommandée pour les développeurs configurant ESLint pour la première fois.

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

• Base : Inclut uniquement la configuration de base ESLint de Next.js.

  {
    "extends": "next"
  }

• Annuler : N'inclut aucune configuration ESLint. Ne choisissez cette option que si vous prévoyez de configurer votre propre configuration ESLint personnalisée.

Si l'une des deux options de configuration est sélectionnée, Next.js installera automatiquement eslint et eslint-config-next comme dépendances dans votre application et créera un fichier .eslintrc.json à la racine de votre projet avec la configuration sélectionnée.

Vous pouvez maintenant exécuter next lint chaque fois que vous souhaitez lancer ESLint pour détecter les erreurs. Une fois ESLint configuré, il s'exécutera également automatiquement lors de chaque build (next build). Les erreurs feront échouer le build, tandis que les avertissements ne le feront pas.

Si vous ne souhaitez pas qu'ESLint s'exécute pendant next build, consultez la documentation pour Ignorer ESLint.

Nous recommandons d'utiliser une intégration appropriée pour voir les avertissements et erreurs directement dans votre éditeur de code pendant le développement.

Configuration ESLint

La configuration par défaut (eslint-config-next) inclut tout ce dont vous avez besoin pour une expérience de linting optimale prête à l'emploi avec Next.js. Si ESLint n'est pas déjà configuré dans votre application, nous recommandons d'utiliser next lint pour configurer ESLint avec cette configuration.

Si vous souhaitez utiliser eslint-config-next avec d'autres configurations ESLint, consultez la section Configurations supplémentaires pour apprendre comment le faire sans causer de conflits.

Les ensembles de règles recommandés des plugins ESLint suivants sont tous utilisés dans eslint-config-next :

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

Cela prendra la priorité sur la configuration de next.config.js.

Plugin ESLint

Next.js fournit un plugin ESLint, eslint-plugin-next, déjà inclus dans la configuration de base, qui permet de détecter les problèmes courants dans une application Next.js. L'ensemble complet des règles est le suivant :

Activé dans la configuration recommandée

Si ESLint est déjà configuré dans votre application, nous recommandons d'étendre directement ce plugin plutôt que d'inclure eslint-config-next, sauf si certaines conditions sont remplies. Consultez la section Ensemble de règles recommandé du plugin pour en savoir plus.

Paramètres personnalisés

rootDir

Si vous utilisez eslint-plugin-next dans un projet où Next.js n'est pas installé à la racine (comme un monorepo), vous pouvez indiquer à eslint-plugin-next où trouver votre application Next.js en utilisant la propriété settings dans votre .eslintrc :

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

rootDir peut être un chemin (relatif ou absolu), un glob (par exemple "packages/*/") ou un tableau de chemins et/ou globs.

Linting des répertoires et fichiers personnalisés

Par défaut, Next.js exécutera ESLint pour tous les fichiers des répertoires pages/, app/, components/, lib/ et src/. Cependant, vous pouvez spécifier quels répertoires utiliser avec l'option dirs dans la configuration eslint de next.config.js pour les builds de production :

module.exports = {
  eslint: {
    dirs: ['pages', 'utils'], // Exécute ESLint uniquement sur les répertoires 'pages' et 'utils' pendant les builds de production (next build)
  },
}

De même, les flags --dir et --file peuvent être utilisés avec next lint pour linter des répertoires et fichiers spécifiques :

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

Cache

Pour améliorer les performances, les informations des fichiers traités par ESLint sont mises en cache par défaut. Ce cache est stocké dans .next/cache ou dans votre répertoire de build défini. Si vous incluez des règles ESLint qui dépendent de plus que le contenu d'un seul fichier source et que vous devez désactiver le cache, utilisez le flag --no-cache avec next lint.

next lint --no-cache

Désactivation des règles

Si vous souhaitez modifier ou désactiver certaines règles fournies par les plugins pris en charge (react, react-hooks, next), vous pouvez les changer directement en utilisant la propriété rules dans votre .eslintrc :

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

Core Web Vitals

L'ensemble de règles next/core-web-vitals est activé lorsque next lint est exécuté pour la première fois et que l'option strict est sélectionnée.

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

next/core-web-vitals met à jour eslint-plugin-next pour signaler comme erreurs plusieurs règles qui sont des avertissements par défaut si elles affectent les Core Web Vitals.

Le point d'entrée next/core-web-vitals est automatiquement inclus pour les nouvelles applications créées avec Create Next App.

Utilisation avec d'autres outils

Prettier

ESLint inclut également des règles de formatage de code, qui peuvent entrer en conflit avec votre configuration existante de Prettier. Nous recommandons d'inclure eslint-config-prettier dans votre configuration ESLint pour faire fonctionner ESLint et Prettier ensemble.

D'abord, installez la dépendance :

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

Puis, ajoutez prettier à votre configuration ESLint existante :

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

lint-staged

Si vous souhaitez utiliser next lint avec lint-staged pour exécuter le linter sur les fichiers git stagés, vous devrez ajouter ce qui suit au fichier .lintstagedrc.js à la racine de votre projet afin de spécifier l'utilisation du 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],
}

Migration d'une configuration existante

Ensemble de règles recommandé du plugin

Si ESLint est déjà configuré dans votre application et qu'une des conditions suivantes est vraie :

• Vous avez un ou plusieurs des plugins suivants déjà installés (soit séparément, soit via une autre configuration comme airbnb ou react-app) :
  • react
  • react-hooks
  • jsx-a11y
  • import
• Vous avez défini des parserOptions spécifiques différents de la configuration Babel dans Next.js (ce n'est pas recommandé sauf si vous avez personnalisé votre configuration Babel)
• Vous avez eslint-plugin-import installé avec des résolveurs Node.js et/ou TypeScript définis pour gérer les imports

Alors nous recommandons soit de supprimer ces paramètres si vous préférez la façon dont ces propriétés sont configurées dans eslint-config-next, soit d'étendre directement depuis le plugin ESLint de Next.js :

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

Le plugin peut être installé normalement dans votre projet sans avoir besoin d'exécuter 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

Cela élimine le risque de collisions ou d'erreurs pouvant survenir en raison de l'importation du même plugin ou parseur à travers plusieurs configurations.

Configurations supplémentaires

Si vous utilisez déjà une configuration ESLint séparée et souhaitez inclure eslint-config-next, assurez-vous qu'elle est étendue en dernier après les autres configurations. Par exemple :

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

La configuration next gère déjà la définition des valeurs par défaut pour les propriétés parser, plugins et settings. Il n'est pas nécessaire de redéclarer manuellement ces propriétés, sauf si vous avez besoin d'une configuration différente pour votre cas d'utilisation.

Si vous incluez d'autres configurations partageables, vous devrez vous assurer que ces propriétés ne sont pas écrasées ou modifiées. Dans le cas contraire, nous recommandons de supprimer les configurations qui partagent un comportement avec la configuration next ou d'étendre directement depuis le plugin ESLint de Next.js comme mentionné ci-dessus.