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.

Référence

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

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

Cette configuration prendra le pas sur celle de next.config.js.

Règles

L'ensemble complet des règles est le suivant :

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

Exemples

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 les répertoires à l'aide de 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

Spécification d'un répertoire racine dans un monorepo

Si vous utilisez eslint-plugin-next dans un projet où Next.js n'est pas installé dans votre répertoire 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 :

import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname est disponible à partir de Node.js v20.11.0
  baseDirectory: import.meta.dirname,
})

const eslintConfig = [
  ...compat.config({
    extends: ['next'],
    settings: {
      next: {
        rootDir: 'packages/my-app/',
      },
    },
  }),
]

export default eslintConfig

rootDir peut être un chemin (relatif ou absolu), un glob (c'est-à-dire "packages/*/") ou un tableau de chemins et/ou globs.

Désactivation du cache

Pour améliorer les performances, les informations des fichiers traités par ESLint sont mises en cache par défaut. Ceci 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 modifier directement en utilisant la propriété rules dans votre .eslintrc :

import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname est disponible à partir de Node.js v20.11.0
  baseDirectory: import.meta.dirname,
})

const eslintConfig = [
  ...compat.config({
    extends: ['next'],
    rules: {
      'react/no-unescaped-entities': 'off',
      '@next/next/no-page-custom-font': 'off',
    },
  }),
]

export default eslintConfig

Avec 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.

import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname est disponible à partir de Node.js v20.11.0
  baseDirectory: import.meta.dirname,
})

const eslintConfig = [
  ...compat.config({
    extends: ['next/core-web-vitals'],
  }),
]

export default eslintConfig

next/core-web-vitals met à jour eslint-plugin-next pour signaler comme erreurs un certain nombre de 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.

Avec TypeScript

En plus des règles ESLint de Next.js, create-next-app --typescript ajoutera également des règles de lint spécifiques à TypeScript avec next/typescript à votre configuration :

import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname est disponible à partir de Node.js v20.11.0
  baseDirectory: import.meta.dirname,
})

const eslintConfig = [
  ...compat.config({
    extends: ['next/core-web-vitals', 'next/typescript'],
  }),
]

export default eslintConfig

Ces règles sont basées sur plugin:@typescript-eslint/recommended. Voir typescript-eslint > Configs pour plus de détails.

Avec 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.

Premièrement, 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

Ensuite, ajoutez prettier à votre configuration ESLint existante :

import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname est disponible à partir de Node.js v20.11.0
  baseDirectory: import.meta.dirname,
})

const eslintConfig = [
  ...compat.config({
    extends: ['next', 'prettier'],
  }),
]

export default eslintConfig

Exécution du lint sur les fichiers mis en stage

Si vous souhaitez utiliser next lint avec lint-staged pour exécuter le linter sur les fichiers git mis en stage, 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],
}

Désactivation du lint pendant les builds de production

Si vous ne souhaitez pas qu'ESLint s'exécute pendant next build, vous pouvez définir l'option eslint.ignoreDuringBuilds dans next.config.js sur true :

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  eslint: {
    // Attention : Cela permet aux builds de production de se terminer avec succès même si
    // votre projet contient des erreurs ESLint.
    ignoreDuringBuilds: true,
  },
}

export default nextConfig

Migration d'une configuration existante

Si vous avez déjà configuré ESLint dans votre application, nous recommandons d'étendre directement ce plugin plutôt que d'inclure eslint-config-next, sauf si certaines conditions sont remplies.

Ensemble de règles recommandé du plugin

Si les conditions suivantes sont vraies :

• Vous avez un ou plusieurs des plugins suivants déjà installés (soit séparément, soit via une configuration différente comme airbnb ou react-app) :
  • react
  • react-hooks
  • jsx-a11y
  • import
• Vous avez défini des parserOptions spécifiques qui diffèrent de la configuration de Babel dans Next.js (ce n'est pas recommandé sauf si vous avez personnalisé votre configuration Babel)
• Vous avez installé eslint-plugin-import 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 ont été configurées dans eslint-config-next, soit d'étendre directement 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 qui peuvent 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 :

import js from '@eslint/js'
import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname est disponible à partir de Node.js v20.11.0
  baseDirectory: import.meta.dirname,
  recommendedConfig: js.configs.recommended,
})

const eslintConfig = [
  ...compat.config({
    extends: ['eslint:recommended', 'next'],
  }),
]

export default eslintConfig

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. Sinon, 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.