Configuration Next.js : ESLint + Prettier + Husky en une fois

Le cauchemar du vendredi soir

Vous vous souvenez de ce vendredi soir, quand vous alliez fermer l’ordinateur et que le lead tech vous écrit sur Slack : « Ta PR a trop de problèmes de formatage, peux-tu nettoyer avant de soumettre ? » Vous ouvrez GitHub : des diffs rouges partout — guillemets doubles ici, indentation incohérente là.

Franchement, c’est décourageant. Vous aviez pourtant lancé npm run lint avant de pousser, non ? Pire : un collègue a eu le même souci — logique impeccable, format différent du vôtre, et au merge une avalanche de conflits sans intérêt.

Ça vous est déjà arrivé ? Du bon code bloqué en review pour le style, tout le monde qui perd du temps. J’ai cherché une solution durable pour que la machine s’occupe de ces corvées.

La réponse, c’est le trio ESLint + Prettier + Husky.

Pourquoi ces trois outils ?

Au début, les trois noms m’ont semblé lourds. Après quelques semaines d’usage, difficile de revenir en arrière. Voici ce que chacun apporte.

ESLint : gardien de la qualité

Beaucoup pensent qu’ESLint ne sert qu’au format. Son rôle principal est de détecter des problèmes potentiels dans le code.

Exemple : Next.js recommande <Image> plutôt que <img> pour l’optimisation automatique. Si vous écrivez <img>, ESLint signale tout de suite :

Error: Do not use <img>. Use Image from 'next/image' instead.

Mieux vaut le savoir en dev que découvrir des images lentes en prod. Next.js 15 active ESLint par défaut ; une bonne config en tire le maximum.

Prettier : la solution formatage

ESLint = logique et qualité ; Prettier = apparence du code. Ne pas les confondre.

Avant, on se disputait en review : simples vs doubles guillemets, 2 vs 4 espaces d’indentation. Du temps perdu sur des détails. Avec Prettier, on fixe les règles une fois (ex. simples guillemets, indent 2) et tout le monde suit. Une config, des années de tranquillité.

Husky : la clé de l’automatisation

Les meilleurs outils ne servent à rien si on oublie de les lancer.

J’ai déjà poussé sans npm run lint : CI en échec, déploiement de l’équipe bloqué. Pas envie de revivre ça.

Husky lance les contrôles avant chaque commit. Au hook pre-commit, ESLint et Prettier tournent ; le commit n’aboutit que si le code est conforme.

Avec lint-staged, seuls les fichiers stagés sont vérifiés — pas tout le repo. Rapide, sans ralentir le rythme de dev.

La synergie des trois

Le flux ressemble à ceci :

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

1. ESLint définit les règles de qualité (pas de var, const ou let obligatoires, etc.)
2. Prettier uniformise le format (ex. guillemets simples partout)
3. Husky exécute tout ça avant le commit pour que personne n’oublie

Bénéfices pour l’équipe :

• Les reviews se concentrent sur la logique métier, pas le style
• Moins de conflits de merge (format homogène)
• Moins d’échecs CI (déjà vérifié en local)

Configuration complète

Passons à la pratique, étape par étape, en évitant les pièges courants.

Étape 1 : initialiser le projet Next.js

Projet existant ? Passez à l’étape 2. Sinon :

npx create-next-app@latest my-app
cd my-app

À la création, choisissez TypeScript et ESLint. Next.js 15 active ESLint par défaut — un gain de temps.

Étape 2 : installer les dépendances

pnpm add -D eslint eslint-config-next prettier eslint-config-prettier husky lint-staged

Rôle de chaque paquet :

• eslint : cœur ESLint
• eslint-config-next : config officielle Next.js (règles spécifiques)
• prettier : cœur Prettier
• eslint-config-prettier : désactive les règles ESLint qui entrent en conflit avec Prettier
• husky : gestion des Git hooks
• lint-staged : ne lint que les fichiers en staging

Attention : n’installez pas eslint-plugin-prettier. Beaucoup de tutos le recommandent, mais Prettier devient une règle ESLint et les perfs souffrent. Gardez ESLint et Prettier séparés.

Étape 3 : configurer ESLint

Zone à risque, surtout depuis Next.js 15 et ESLint 9 (nouveau format de config).

Flat Config ESLint 9 (recommandé)

À la racine, créez eslint.config.mjs :

// eslint.config.mjs
import { FlatCompat } from '@eslint/eslintrc';
import nextPlugin from '@next/eslint-plugin-next';

const compat = new FlatCompat();

export default [
  ...compat.extends('next/core-web-vitals'),
  {
    plugins: {
      '@next/next': nextPlugin,
    },
    rules: {
      '@next/next/no-img-element': 'error',
      'react/no-unescaped-entities': 'off',
      // Ajoutez vos règles ici
    },
  },
  {
    ignores: ['.next/', 'node_modules/', 'out/'],
  },
];

Points clés :

• ESLint 9 n’utilise plus .eslintrc.json mais le flat config (eslint.config.mjs)
• Erreur « The Next.js plugin was not detected » après upgrade Next.js 15 ? Souvent un mauvais format de config
• Next.js 16 supprimera next lint — autant migrer tôt

Plan B (compatibilité)

Pour rester sur le format ESLint 8 :

ESLINT_USE_FLAT_CONFIG=false

Puis .eslintrc.json :

{
  "extends": ["next/core-web-vitals", "prettier"],
  "rules": {
    "@next/next/no-img-element": "error"
  }
}

Mieux vaut migrer vers flat config : c’est la direction du projet.

Étape 4 : configurer Prettier

Créez .prettierrc.json à la racine :

{
  "semi": true,
  "singleQuote": true,
  "trailingComma": "es5",
  "tabWidth": 2,
  "printWidth": 80,
  "arrowParens": "avoid"
}

Choix personnels, ajustables en équipe :

• singleQuote: true : guillemets simples, plus léger visuellement
• printWidth: 80 : pratique avec plusieurs fenêtres d’éditeur
• trailingComma: 'es5' : virgule finale dans objets/tableaux — diffs Git plus propres

.prettierignore pour exclure certains chemins :

.next
out
node_modules
public
*.lock

Intégration VSCode (recommandé)

.vscode/settings.json pour formater à l’enregistrement :

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

Ctrl + S et Prettier formate — très agréable au quotidien.

Étape 5 : Husky + lint-staged

Le cœur de la config pour la collaboration.

Initialiser Husky

pnpm dlx husky init

Crée .husky/ et ajoute dans package.json :

{
  "scripts": {
    "prepare": "husky install"
  }
}

prepare installe les hooks après pnpm install : les nouveaux membres n’ont rien de plus à faire.

Hook pre-commit

Éditez .husky/pre-commit :

pnpm lint-staged

À chaque git commit, Husky lance pnpm lint-staged d’abord.

lint-staged

.lintstagedrc.mjs à la racine :

Alibaba Cloud - Choix n°1 des développeurs, 15 % de réduction exclusive sur Lighthouse

Obtenir -15 % →Pub

export default {
  '*.{js,jsx,ts,tsx}': [
    'eslint --fix',
    'prettier --write',
  ],
  '*.{json,md,css}': [
    'prettier --write',
  ],
};

• Fichiers JS/TS : eslint --fix puis prettier --write
• JSON, MD, CSS : Prettier seulement

Optimisation perfs :

1. Fichiers stagés uniquement — lint-staged filtre ce qui est dans git add
2. Pas de lint global — ne lancez pas pnpm lint en pre-commit (trop lent)
3. Pas de tests lourds — format + qualité de base en local, tests complets en CI
4. Urgence : git commit --no-verify si besoin (correctif prod, etc.)

Dépannage courant

Husky inactif sous Windows

Utilisez Git Bash, pas CMD/PowerShell. Vérifiez les droits sur .husky/pre-commit :

chmod +x .husky/pre-commit

Hook trop lent

Si le pre-commit dépasse 10 s, vérifiez qu’il n’y a pas de scan projet entier. Quelques fichiers stagés : 2–3 s en général.

Vérifier la configuration

Étapes de test

1. Modifiez un fichier avec des erreurs de format (guillemets, points-virgules, etc.)
2. git add .
3. git commit -m "test"
4. Observez la sortie terminal

Signes de succès

✔ Preparing lint-staged...
✔ Running tasks for staged files...
✔ Applying modifications from tasks...
✔ Cleaning up temporary files...

Le fichier modifié est souvent corrigé automatiquement — c’est l’intérêt de l’automatisation.

En cas d’échec

• .husky/pre-commit existe et contient la bonne commande ?
• .lintstagedrc.mjs est bien à la racine ?
• Test manuel : pnpm lint-staged et lisez les erreurs

Configuration avancée

commitlint (messages de commit)

Les messages comptent aussi. commitlint impose un format commun (ex. Conventional Commits).

pnpm add -D @commitlint/cli @commitlint/config-conventional

commitlint.config.mjs :

export default {
  extends: ['@commitlint/config-conventional'],
};

Hook commit-msg :

echo "pnpm commitlint --edit \$1" > .husky/commit-msg

Un message du type fix bug au lieu de fix: bug sera rejeté.

Vérification de types TypeScript

Dans .lintstagedrc.mjs :

export default {
  '*.{ts,tsx}': [
    () => 'tsc --noEmit', // vérification des types
    'eslint --fix',
    'prettier --write',
  ],
  '*.{js,jsx}': [
    'eslint --fix',
    'prettier --write',
  ],
  '*.{json,md,css}': [
    'prettier --write',
  ],
};

Note : tsc --noEmit analyse tout le projet — lent sur les gros repos. Je laisse souvent le typage à la CI et garde le pre-commit léger.

Monorepo

Avec pnpm workspace ou Turborepo :

• Husky et lint-staged à la racine
• .lintstagedrc.mjs par package si besoin
• Éviter que la config d’un package affecte les autres

Voir la doc officielle de lint-staged.

FAQ et solutions

Q1 : conflit entre ESLint et Prettier ?

Symptôme : ESLint signale le format, Prettier le remet comme avant.

Solution : installez eslint-config-prettier et étendez prettier en dernier :

export default [
  ...compat.extends('next/core-web-vitals'),
  ...compat.extends('prettier'), // en dernier
];

eslint-config-prettier coupe les règles de format ESLint ; Prettier formate, ESLint juge la qualité.

Q2 : « plugin not detected » après Next.js 15 ?

Symptôme :

Error: The Next.js plugin was not detected in your ESLint configuration.

Solution : vérifiez le flat config et l’import de @next/eslint-plugin-next :

import nextPlugin from '@next/eslint-plugin-next';

export default [
  {
    plugins: {
      '@next/next': nextPlugin,
    },
  },
];

Sinon temporairement : ESLINT_USE_FLAT_CONFIG=false.

KiloClaw - OpenClaw managé pour l’entreprise : orchestration d’agents IA et routage intelligent

Commencer →Pub

Q3 : pre-commit trop lent ?

Symptôme : plus de 10 s à chaque commit.

Solutions :

1. Confirmer que lint-staged ne cible que le staging
2. Retirer les tests du pre-commit
3. Sur gros projets : ESLint seulement sur .ts/.tsx, Prettier sur le reste

Q4 : un collègue n’a pas les hooks Husky ?

Symptôme : après clone, pas de pre-commit.

Solution : script prepare dans package.json :

{
  "scripts": {
    "prepare": "husky install"
  }
}

Demandez un pnpm install — les hooks s’installent seuls.

Q5 : Husky sous Windows

Symptôme : le hook ne s’exécute pas.

Solutions :

1. Git Bash, pas CMD
2. chmod +x .husky/pre-commit
3. Réinit si besoin :

rm -rf .husky
pnpm dlx husky init

Synthèse et bonnes pratiques

Une demi-heure de setup pour des mois de sérénité en équipe.

Bénéfices

• Qualité : ESLint attrape les problèmes tôt
• Collaboration : format unique, moins de débats et de conflits
• Automatisation : Husky garantit le respect des règles à chaque commit

Recommandations

1. Progressif : règles strictes plus tard ; commencez par les défauts
2. Consensus : choix Prettier (guillemets, etc.) validés en équipe
3. Perfs : pre-commit minimal ; tests lourds en CI
4. Veille : Next.js 16 retirera next lint — anticipez la migration ESLint

Prochaines étapes

Si ce n’est pas encore en place, suivez ce guide maintenant — une demi-heure suffit.

Partagez la config avec l’équipe pour aligner les environnements.

Ajustez ensuite Prettier et ESLint selon vos besoins. Les outils vous servent, pas l’inverse.

Retour d’expérience

La migration flat config ESLint 9 m’a pris du temps, mais je ne reviendrais pas en arrière.

Plus de stress format ni de lint oublié : le pre-commit fait le travail.

Les reviews portent sur l’architecture et la logique, plus sur « simple ou double guillemet ». Ce gain vaut largement le temps de configuration.

Des questions en cours de config ? Laissez un commentaire — j’essaierai d’aider.

Bonne configuration !