ESLint Flat Config avec Claude Code pour un vrai projet

Ne laissez pas Claude Code deviner toute la configuration

ESLint est un outil d’analyse statique pour JavaScript et TypeScript. L’analyse statique consiste à lire le code avant son exécution pour détecter des promesses oubliées, des erreurs React Hooks, des problèmes d’accessibilité, des imports incohérents et des pratiques qui rendent les revues plus fragiles.

Depuis ESLint v9, Flat Config est devenu le format de configuration standard. En juin 2026, la documentation officielle continue de présenter les fichiers eslint.config.js et eslint.config.mjs comme point central. Le risque est de demander simplement à Claude Code “configure ESLint”. Il peut alors mélanger d’anciens réflexes .eslintrc, oublier le lint avec types, ou activer des règles coûteuses pour CI sans bénéfice clair.

La méthode fiable consiste à donner un contrat précis à Claude Code : stack utilisée, dossiers générés, commandes qui doivent passer, et règles que l’on accepte de relâcher seulement dans les tests. Ce guide reprend le workflow que Masa applique sur une interface d’administration React, un site Astro de contenu et une petite librairie TypeScript.

Gardez les sources officielles à portée de main : ESLint Configuration Files, typescript-eslint typed linting, eslint-plugin-astro User Guide et Claude Code CLI reference.

Installez d’abord les dépendances et scripts

Avant de laisser Claude Code modifier le dépôt, installez les paquets adaptés. Le socle couvre ESLint, TypeScript, React, Hooks, accessibilité et tri des imports. Ajoutez les paquets Astro uniquement si le projet contient des fichiers .astro.

npm i -D eslint @eslint/js typescript typescript-eslint globals
npm i -D eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-jsx-a11y
npm i -D eslint-plugin-simple-import-sort

# À ajouter seulement pour Astro
npm i -D eslint-plugin-astro astro-eslint-parser

Dans package.json, séparez la correction locale de la vérification CI. lint:fix sert à nettoyer en local. lint et typecheck sont les commandes de référence. --max-warnings=0 transforme les avertissements en échec ; sur un ancien dépôt, activez-le après un premier passage de nettoyage.

{
  "scripts": {
    "lint": "eslint . --max-warnings=0",
    "lint:fix": "eslint . --fix",
    "lint:debug": "eslint --print-config src/App.tsx > .eslint-debug.json",
    "typecheck": "tsc --noEmit",
    "ci:verify": "npm run lint && npm run typecheck"
  }
}

Claude Code ne doit pas s’arrêter après avoir écrit le fichier. Il doit exécuter la même chaîne de vérification que l’équipe utilisera ensuite.

package.json scripts
  -> eslint.config.mjs
  -> npm run lint:fix
  -> npm run lint
  -> npm run typecheck
  -> CI gate
  -> revue du diff restant avec Claude Code

Flat Config pour TypeScript et React

Pour une application React + TypeScript, ce eslint.config.mjs est un point de départ solide. projectService: true active le lint avec informations de types. C’est puissant, mais plus coûteux ; les dossiers générés et sorties de build doivent donc être ignorés dès le début.

import js from "@eslint/js";
import globals from "globals";
import react from "eslint-plugin-react";
import reactHooks from "eslint-plugin-react-hooks";
import jsxA11y from "eslint-plugin-jsx-a11y";
import simpleImportSort from "eslint-plugin-simple-import-sort";
import tseslint from "typescript-eslint";

export default tseslint.config(
  {
    ignores: [
      "node_modules/",
      "dist/",
      "build/",
      "coverage/",
      ".next/",
      ".astro/",
      "public/",
      "*.min.js"
    ]
  },
  js.configs.recommended,
  ...tseslint.configs.strictTypeChecked,
  ...tseslint.configs.stylisticTypeChecked,
  {
    files: ["**/*.{js,mjs,cjs,ts,tsx}"],
    languageOptions: {
      ecmaVersion: "latest",
      sourceType: "module",
      globals: {
        ...globals.browser,
        ...globals.node,
        ...globals.es2024
      },
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname
      }
    }
  },
  {
    files: ["**/*.{jsx,tsx}"],
    ...react.configs.flat.recommended,
    settings: {
      react: { version: "detect" }
    },
    rules: {
      ...react.configs.flat.recommended.rules,
      "react/react-in-jsx-scope": "off",
      "react/prop-types": "off"
    }
  },
  {
    files: ["**/*.{jsx,tsx}"],
    plugins: {
      "react-hooks": reactHooks,
      "jsx-a11y": jsxA11y
    },
    rules: {
      ...reactHooks.configs.recommended.rules,
      ...jsxA11y.configs.recommended.rules
    }
  },
  {
    plugins: {
      "simple-import-sort": simpleImportSort
    },
    rules: {
      "simple-import-sort/imports": "error",
      "simple-import-sort/exports": "error",
      "@typescript-eslint/consistent-type-imports": [
        "error",
        { prefer: "type-imports", fixStyle: "separate-type-imports" }
      ],
      "@typescript-eslint/no-floating-promises": "error",
      "@typescript-eslint/no-misused-promises": [
        "error",
        { checksVoidReturn: { attributes: false } }
      ],
      "@typescript-eslint/no-unused-vars": [
        "error",
        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" }
      ],
      "no-console": ["warn", { allow: ["warn", "error"] }]
    }
  },
  {
    files: ["**/*.{js,mjs,cjs}"],
    extends: [tseslint.configs.disableTypeChecked]
  },
  {
    files: ["**/*.{test,spec}.{ts,tsx}", "**/__tests__/**/*.{ts,tsx}"],
    rules: {
      "@typescript-eslint/no-explicit-any": "off",
      "@typescript-eslint/no-unsafe-assignment": "off",
      "@typescript-eslint/no-unsafe-member-access": "off"
    }
  }
);

Cette configuration vise les erreurs qui ont un impact réel. no-floating-promises repère les await oubliés. no-misused-promises réduit les handlers JSX async dangereux. consistent-type-imports clarifie les imports qui ne servent qu’au typage. Les tests peuvent être assouplis, mais le code de production doit rester strict.

Astro doit être traité comme une surface séparée

Un fichier Astro combine template, TypeScript frontmatter, appels de composants et scripts client. Si vous appliquez une configuration React classique à .astro, ESLint peut échouer au parsing avant de trouver des problèmes utiles.

Pour un site Astro de contenu, commencez par les configurations recommandées du plugin, puis ajoutez une petite surcharge .astro. La règle astro/no-set-html-directive est utile sur les blogs et documentations, car l’injection HTML peut être difficile à repérer en revue éditoriale.

import js from "@eslint/js";
import astro from "eslint-plugin-astro";
import globals from "globals";
import tseslint from "typescript-eslint";

export default tseslint.config(
  {
    ignores: ["dist/", ".astro/", "node_modules/", "public/"]
  },
  js.configs.recommended,
  ...astro.configs["flat/recommended"],
  ...astro.configs["jsx-a11y-recommended"],
  ...tseslint.configs.recommendedTypeChecked,
  {
    files: ["**/*.{ts,tsx}"],
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.node
      },
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname
      }
    }
  },
  {
    files: ["**/*.astro"],
    languageOptions: {
      parserOptions: {
        parser: tseslint.parser,
        extraFileExtensions: [".astro"],
        projectService: true,
        tsconfigRootDir: import.meta.dirname
      }
    },
    rules: {
      "astro/no-set-html-directive": "error",
      "astro/no-unused-define-vars-in-style": "error"
    }
  }
);

N’utilisez pas ESLint comme formateur universel. Confiez le formatage à Prettier et gardez ESLint pour les risques de code, l’accessibilité, les erreurs typées et les règles de projet. La suite logique est le guide Prettier avec Claude Code.

Trois cas d’usage concrets

Premier cas : une interface SaaS d’administration. Invitations, facturation et permissions dépendent de code asynchrone. Ici, @typescript-eslint/no-floating-promises doit être en error, car un await oublié peut provoquer un incident réel.

Deuxième cas : un blog technique Astro. Les vérifications les plus utiles sont le parsing .astro, l’accessibilité, les styles inutilisés et le HTML dangereux. Comme le site génère beaucoup de pages, ignorer dist/, .astro/ et les sorties de build est indispensable.

Troisième cas : une librairie TypeScript. L’API publique doit être plus stricte que les tests. Gardez les règles fortes pour les imports de types, variables inutilisées et exports, puis assouplissez seulement les fixtures de test.

Projet	Règles à renforcer	Zones à assouplir
Admin React	Promesses, Hooks, a11y	Mocks Storybook
Blog Astro	.astro, HTML dangereux, CSS inutilisé	Contenu généré
Librairie TypeScript	Imports de types, variables, exports	Fixtures de test

Pour ajouter une vérification avant commit, combinez cela avec Husky + lint-staged. Dans un grand dépôt, gardez le pre-commit rapide et laissez le lint typé à CI.

Ajoutez une porte CI

Un succès local ne suffit pas. CI doit exécuter les mêmes commandes avec les mêmes règles. Pour GitHub Actions, ce workflow minimal couvre la plupart des projets.

name: code-quality

on:
  pull_request:
  push:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck

Si un dépôt existant produit des centaines d’erreurs, ne lancez pas eslint --fix sur tout le code en une fois. Regroupez d’abord les erreurs par règle, puis demandez à Claude Code de corriger de petits lots.

npm run lint
npm run lint:fix
npm run lint
npm run typecheck
npm run lint:debug

lint:debug affiche la configuration résolue pour un fichier. Utilisez-le si une règle React touche par erreur un fichier .astro, ou si une exception de test fuit dans le code de production.

Prompts pour Claude Code

Modèle 1 : nouvelle installation.

Ajoute ESLint Flat Config à ce dépôt.
La stack est TypeScript + React. Lis d'abord package.json, tsconfig et toute configuration lint existante.
Crée eslint.config.mjs et continue jusqu'à ce que npm run lint et npm run typecheck passent.
Évite les autofixes qui peuvent changer le comportement. Si l'un est nécessaire, explique pourquoi avant.

Modèle 2 : correction d’erreurs.

Je vais coller la sortie de npm run lint.
Regroupe les erreurs par règle, corrige d'abord les catégories à faible risque et garde un diff petit.
N'utilise eslint-disable qu'en dernier recours. Si tu l'utilises, ajoute une raison sur une ligne.
Après modification, lance npm run lint et npm run typecheck.

Modèle 3 : support Astro.

Revois la configuration ESLint de ce site Astro.
Sépare les règles pour .astro, .ts et .tsx. Utilise la configuration Flat recommandée de eslint-plugin-astro.
Passe astro/no-set-html-directive en error et confirme que les règles React ne s'appliquent pas par erreur à tout le fichier .astro.

Modèle 4 : échec CI.

Le job lint de GitHub Actions échoue.
Compare les versions locales et CI de Node, npm, ESLint et des plugins.
Crée une commande de reproduction, puis sépare la correction en changement de config, mise à jour de dépendance ou changement de code.
Applique le plus petit diff sûr.

Claude Code répond mieux quand la demande contient les fichiers à lire, les commandes à lancer et les limites à respecter. “Corrige lint” est trop vague. “Ne relâche pas les règles de production et prouve la correction avec ces commandes” est beaucoup plus sûr.

Pièges fréquents

Premier piège : copier une vieille chaîne extends de .eslintrc dans Flat Config. La forme est différente. Si une configuration partagée n’est pas encore compatible, cherchez une couche de compatibilité, mais privilégiez les exemples Flat officiels.

Deuxième piège : activer le lint typé sur tous les fichiers visibles. projectService: true est puissant, mais les bundles, sorties générées et builds ralentissent CI. Définissez les ignores avant de discuter des règles.

Troisième piège : accepter un énorme diff d’autofix. Tri des imports, imports de types, variables inutilisées et formatage peuvent masquer des changements de comportement. Masa sépare souvent le premier déploiement par promesses, imports et règles de framework.

Quatrième piège : garder des warnings pour toujours. Un avertissement qui ne bloque jamais devient du bruit. Utilisez error pour une règle d’équipe, warn pour une phase d’apprentissage temporaire, et retirez les règles à faible signal.

Cinquième piège : ne pas expliquer l’intention à Claude Code. Dites-lui si l’accessibilité est critique, si les fixtures de test peuvent utiliser any, ou si l’API publique doit être stricte. Ces contraintes donnent une meilleure configuration qu’une recommandation générique.

Résumé

ESLint Flat Config rend la portée des règles plus lisible, car la configuration du projet vit au même endroit. Claude Code est utile non parce qu’il génère ce fichier une fois, mais parce qu’il peut lire le code existant, lancer les vérifications et ajuster sans affaiblir les standards importants.

Commencez par la bonne base React/TypeScript ou Astro. Ajoutez npm run lint et npm run typecheck à CI. Utilisez ensuite des prompts explicites, et relisez manuellement tout eslint-disable ou gros diff de --fix.

Pour compléter le workflow, associez ce guide à Prettier et Husky + lint-staged. Si vous voulez des prompts de revue réutilisables et des checklists de déploiement, la page produits ClaudeCodeLab regroupe guides et consultation.

Résultat testé en pratique

Masa a essayé cette configuration sur une petite interface React et un starter de blog Astro. Le premier passage a surtout révélé du bruit d’ordre d’import et plusieurs promesses non gérées. Un seul diff eslint --fix était difficile à relire, donc séparer promesses, imports et règles de sécurité Astro a mieux fonctionné. Le workflow le plus reproductible a été de fixer npm run lint et npm run typecheck dans CI, puis de coller les logs d’échec à Claude Code pour obtenir de petites corrections prouvées par commande.