Husky : hooks et lint-staged

Lancer l’analyse et le formatage sur tout le projet à chaque commit est trop lent. lint-staged n’exécute les commandes que sur les fichiers indexés (git add), puis réintègre les corrections au commit.

Installer

npm install -D lint-staged

.husky/pre-commit :

npx lint-staged

Configurer dans package.json

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx,astro}": ["eslint --fix", "prettier --write"],
    "*.{json,md,css,yaml,yml}": "prettier --write"
  }
}

Chaque motif est associé à une ou plusieurs commandes, exécutées dans l’ordre sur les fichiers correspondants (leurs chemins sont ajoutés en fin de commande). Les fichiers modifiés par --fix et --write sont automatiquement réindexés.

Élément	Rôle
Motif (*.{js,ts})	Fichiers concernés (glob)
Liste de commandes	Exécutées l’une après l’autre ; une erreur interrompt le commit
eslint --fix	Corrige ce qui peut l’être automatiquement (ESLint)
prettier --write	Formate (Prettier)

Mettre eslint avant prettier : les corrections d’ESLint sont ensuite formatées.

Fichier de configuration séparé

Pour une configuration plus longue : lint-staged.config.js (ou .lintstagedrc.json) :

export default {
  '*.{js,jsx,ts,tsx,astro}': [
    'eslint --max-warnings 0 --fix',
    'prettier --write',
  ],
  '*.{json,md,css,yaml,yml}': 'prettier --write',
  '*.css': 'stylelint --fix',
};

Commandes qui ne prennent pas de fichiers

Par défaut, lint-staged ajoute la liste des fichiers à la commande. Pour une commande qui doit s’exécuter sans fichiers (vérification de types sur tout le projet) :

export default {
  '*.{ts,tsx}': () => 'tsc --noEmit', // fonction : aucun fichier ajouté
  '*.{js,ts}': ['eslint --fix', 'prettier --write'],
};

tsc analyse tout le projet (impossible sur quelques fichiers seulement) : le réserver à pre-push ou à l’intégration continue si c’est trop lent.

Lancer des tests sur les fichiers modifiés

export default {
  '*.{js,ts,tsx}': ['vitest related --run', 'eslint --fix'],
};

vitest related --run n’exécute que les tests concernés par les fichiers modifiés (voir Vitest : configuration et intégration continue). Pour de longs tests, préférer le hook pre-push (Pre-push et tests).

Fichiers partiellement indexés

Quand on indexe seulement une partie des modifications d’un fichier (git add -p), lint-staged met de côté les modifications non indexées avant de lancer les commandes, puis les restaure. Si une commande échoue, les modifications sont restaurées. Si lint-staged signale un conflit à la restauration, retrouver les modifications dans la réserve de Git (git stash list).

Options utiles

npx lint-staged --diff="origin/main...HEAD"      # fichiers modifiés par rapport à une branche
npx lint-staged --no-stash                       # ne pas utiliser la réserve
npx lint-staged --verbose                        # détail des commandes
npx lint-staged --concurrent false               # une commande à la fois

--diff est utile dans un pre-push ou en intégration continue pour contrôler tous les fichiers de la branche.

Que mettre dans le pre-commit ?

À inclure	À éviter
Formatage des fichiers modifiés	Suite de tests complète
Analyse des fichiers modifiés	Compilation du projet
Détection de secrets (voir Hooks Git natifs)	Appels réseau
Vérification rapide (YAML, JSON)	Tout ce qui dépasse quelques secondes

Un hook trop lent est contourné par habitude (--no-verify) : il perd alors toute utilité.

Exemple complet

package.json :

{
  "scripts": {
    "prepare": "husky",
    "lint": "eslint .",
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "test": "vitest run"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx,astro}": [
      "eslint --max-warnings 0 --fix",
      "prettier --write"
    ],
    "*.{json,md,css,yaml,yml}": "prettier --write"
  }
}

.husky/pre-commit :

npx lint-staged

Dépannage

Symptôme	Piste
No staged files match any configured task	Aucun fichier indexé ne correspond aux motifs : normal
lint-staged failed due to a git error	Dépôt dans un état particulier (fusion en cours) : terminer ou annuler
Les corrections ne sont pas dans le commit	Commande qui modifie sans écrire (--fix/--write manquant) ou fichiers hors des motifs
eslint: command not found	Dépendances non installées, ou outil à appeler par npx
Le hook dure trop longtemps	Réduire les commandes, déplacer les tests dans pre-push
Fichiers ignorés quand même traités	Ajouter un .prettierignore / ignores d’ESLint
Modifications non indexées « perdues »	Chercher dans git stash list

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

Aucune.

Pour aller plus loin

• lint-staged
• Suite : Messages de commit avec commitlint

Dans la même rubrique

• Installation
• Hooks et lint-staged
• Messages de commit avec commitlint
• Pre-push et tests
• Intégration continue et équipes
• Alternative : hooks Git natifs
• Dépannage