ESLint : migration et dépannage

Pourquoi migrer

ESLint 9 utilise par défaut le format flat config (eslint.config.js). L’ancien format (.eslintrc.*) n’est plus pris en charge par défaut ; il reste disponible un temps via ESLINT_USE_FLAT_CONFIG=false, mais il est abandonné.

Changements notables d’ESLint 9

• Configuration par défaut : eslint.config.js (et non .eslintrc.*).
• .eslintignore n’est plus lu : utiliser ignores dans la configuration.
• Les commentaires /* eslint-env */ ne sont plus pris en compte : déclarer les globales dans languageOptions.globals.
• Plusieurs règles de formatage sont dépréciées (déplacées vers @stylistic/eslint-plugin).
• Node.js récent obligatoire (versions LTS actuelles).
• Certains plugins demandent une version compatible avec ESLint 9.

Procédure

git switch -c migration-eslint-9
npm install -D eslint@latest @eslint/js globals
npx @eslint/migrate-config .eslintrc.json          # génère eslint.config.mjs

1. Lancer l’outil de migration : il convertit .eslintrc.* en eslint.config.mjs.
2. Relire et simplifier le fichier produit (il utilise parfois FlatCompat pour les configurations non converties).
3. Migrer ou remplacer les plugins par des versions compatibles ESLint 9.
4. Supprimer .eslintrc.* et .eslintignore.
5. npx eslint . : comparer les résultats avec l’ancienne version.
6. Mettre à jour les scripts et la CI.

Équivalences .eslintrc → configuration à plat

Ancien (.eslintrc)	Nouveau (eslint.config.js)
extends: ['eslint:recommended']	js.configs.recommended (import js from '@eslint/js')
extends: ['plugin:react/recommended']	...react.configs.flat.recommended ou FlatCompat
env: { browser: true, node: true }	languageOptions: { globals: { ...globals.browser, ...globals.node } }
parser: '@typescript-eslint/parser'	languageOptions: { parser } (ou tseslint.config)
parserOptions	languageOptions.parserOptions et ecmaVersion/sourceType
plugins: ['react']	plugins: { react } (objet, import explicite)
overrides: [{ files, rules }]	Blocs { files, rules } dans le tableau
ignorePatterns / .eslintignore	{ ignores: [...] }
settings	settings
root: true	Inutile (recherche du fichier la plus proche)
// eslint-env node	languageOptions.globals

Exemple avant/après :

{
  "root": true,
  "env": { "browser": true, "es2022": true },
  "extends": ["eslint:recommended"],
  "parserOptions": { "sourceType": "module" },
  "rules": { "eqeqeq": "error" },
  "ignorePatterns": ["dist/"]
}

import js from '@eslint/js';
import globals from 'globals';

export default [
  { ignores: ['dist/'] },
  js.configs.recommended,
  {
    languageOptions: {
      ecmaVersion: 2022,
      sourceType: 'module',
      globals: globals.browser,
    },
    rules: { eqeqeq: 'error' },
  },
];

Utiliser une configuration au format ancien

Pour une configuration partagée non encore convertie :

import { FlatCompat } from '@eslint/eslintrc';
import { dirname } from 'node:path';
import { fileURLToPath } from 'node:url';

const compat = new FlatCompat({
  baseDirectory: dirname(fileURLToPath(import.meta.url)),
});

export default [
  ...compat.extends('ancienne-config-partagee'),
  ...compat.plugins('ancien-plugin'),
];

C’est une solution de transition : préférer les versions à plat de ces configurations quand elles existent.

Les règles de formatage

Les règles de style (indent, quotes, semi…) ne sont plus recommandées dans ESLint. Deux voies :

Voie	Principe
Prettier + eslint-config-prettier	Prettier formate, ESLint analyse (recommandé : voir Prettier et éditeur)
@stylistic/eslint-plugin	Les mêmes règles de formatage, dans ESLint

Erreurs fréquentes

Message	Cause et solution
Could not find config file	eslint.config.js absent (ou nom incorrect : .mjs / .cjs acceptés)
ESLintRC … is no longer supported / .eslintrc ignoré	Migrer vers eslint.config.js
A config object is using the "extends" key, which is not supported in flat config	Utiliser ...compat.extends(...) ou les jeux à plat des plugins
Key "plugins": Expected an object	plugins doit être un objet { nom: plugin }, pas un tableau
Definition for rule '…' not found	Plugin non déclaré, mauvais préfixe
Cannot read config file … ERR_REQUIRE_ESM	eslint.config.js avec import sans "type": "module" : renommer en .mjs
TypeError: Cannot read properties of undefined (reading 'configs')	Plugin importé de façon incorrecte (export par défaut ou nommé) : lire sa documentation
Error: Failed to load plugin '…'	Plugin non installé, ou incompatible avec ESLint 9
'x' is not defined (no-undef)	Globales absentes : languageOptions.globals
Parsing error: Unexpected token	Syntaxe non prise en charge : analyseur TypeScript, plugin Astro
File ignored because of a matching ignore pattern	Fichier couvert par ignores ; pour forcer : --no-ignore
Oops! Something went wrong! ESLint: …	Erreur interne : regarder la ligne suivante, vérifier plugin et version
Avertissement eslint-env	Remplacer par languageOptions.globals
Avertissement de version de TypeScript	Mettre à jour typescript-eslint

Diagnostiquer

npx eslint --version
npm ls eslint                                  # une seule version
npx eslint --print-config src/app.js           # configuration effective
npx eslint --debug src/app.js 2>&1 | head -60  # détail de la résolution
npx eslint . --no-cache                        # éliminer un cache obsolète

Quand une règle ne se comporte pas comme prévu : vérifier d’abord quel bloc s’applique au fichier (--print-config), puis l’ordre des blocs (le dernier l’emporte).

Mises à jour courantes

npm outdated eslint @eslint/js typescript-eslint
npm install -D eslint@latest @eslint/js@latest typescript-eslint@latest
npx eslint . --max-warnings 0

1. Lire les notes de version (eslint.org/blog).
2. Mettre à jour ESLint et ses plugins ensemble.
3. Corriger les règles renommées ou retirées.
4. Relancer l’analyse complète et les tests.

Ubuntu 24.04 et 26.04 : différences à connaître

Aucune propre à Ubuntu. Vérifier que la version de Node.js installée satisfait ESLint 9 (voir Node.js : installation).

Pour aller plus loin

• Guide de migration vers la configuration à plat, Migration vers ESLint 9
• Retour : Installation

Dans la même rubrique

• Installation
• Configuration
• TypeScript
• React, Astro et Next.js
• Prettier et éditeur
• Intégration continue et performance
• Migration et dépannage