Prettier : dépannage et migration

Diagnostic

npx prettier --version
npm ls prettier prettier-plugin-astro prettier-plugin-tailwindcss
npx prettier --find-config-path src/app.js        # fichier de configuration utilisé
npx prettier --file-info src/app.js               # ignoré ? analyseur déduit ?
npx prettier --log-level debug --check src/app.js 2>&1 | head -40
npx prettier src/app.js | diff src/app.js -       # voir ce qui changerait

Les trois premières commandes règlent la majorité des cas : version, configuration effective, analyseur du fichier.

Erreurs fréquentes

Message	Cause et solution
`[error] No parser could be inferred for file …`	Extension non prise en charge : installer et déclarer le plugin (`.astro`), ou indiquer `parser` dans `overrides`
`[error] src/app.js: SyntaxError: Unexpected token`	Erreur de syntaxe dans le fichier : Prettier ne formate pas du code invalide ; corriger d’abord
`[error] Invalid configuration file`	Option inconnue, valeur invalide ou JSON mal formé
`[error] Cannot find package 'prettier-plugin-…'`	Plugin non installé (`npm install -D`)
`[warn] Ignored unknown option { … }`	Option qui n’existe pas dans cette version (faute de frappe, plugin absent)
`[error] No files matching the pattern were found`	Motif sans guillemets (le shell le développe), chemin faux, fichiers ignorés
`[warn] Code style issues found in N files`	`--check` : exécuter `--write`
`Error: Cannot find module 'prettier/…'`	Plugin ancien incompatible avec Prettier 3 : le mettre à jour
`TypeError: Cannot read properties of undefined` dans un plugin	Plugin incompatible avec la version de Prettier
`[error] Unexpected "…" in …` pour du Markdown ou du MDX	Contenu mal formé : corriger, ou `<!-- prettier-ignore -->`

Le résultat n’est pas celui attendu

Symptôme	Piste
Les options sont ignorées	Mauvais fichier de configuration (`--find-config-path`), `.editorconfig` en conflit, option propre à un autre langage
Résultat différent de celui d’un collègue	Versions de Prettier ou de plugins différentes : `npm ls prettier`, installation avec `npm ci`
Résultat différent entre l’éditeur et la ligne de commande	L’éditeur n’utilise pas le Prettier du projet
Les classes Tailwind ne sont pas triées	Plugin absent ou pas en dernier, `tailwindStylesheet` manquant (Plugins)
Un fichier Markdown change de mise en forme (listes, tableaux)	Comportement normal de Prettier ; `proseWrap`, `<!-- prettier-ignore -->` pour les cas voulus
Prettier reformate sans cesse le même fichier	Un autre outil le réécrit (génération, ESLint `--fix`) : un seul responsable du format
Fins de ligne modifiées	`endOfLine` et `.gitattributes`
Le formatage casse du code (rare)	Réduire le cas, vérifier avec `prettier --debug-check`, signaler au projet

npx prettier --debug-check src/app.js         # vérifie que le résultat est stable et équivalent

Fins de ligne

Symptômes : tous les fichiers apparaissent modifiés après un clonage sous Windows, ou --check échoue seulement sur certains postes.

* text=auto eol=lf

Avec endOfLine: "lf" (par défaut en Prettier 3) et .editorconfig (end_of_line = lf). Pour corriger un dépôt existant :

npx prettier --write --end-of-line lf .
git add --renormalize .

Fichiers ignorés

npx prettier --file-info src/generated/api.js

Cause	Solution
Fichier dans `.prettierignore` ou `.gitignore`	Retirer le motif, ou formater explicitement avec `--ignore-path`
Motif trop large (`*.js`)	Préciser le dossier (`dist/`)
`node_modules/`	Ignoré par défaut

Voir Ignorer et surcharger.

Migrer vers Prettier 3

git switch -c migration-prettier-3
npm install -D --save-exact prettier@latest prettier-plugin-astro@latest prettier-plugin-tailwindcss@latest

Déclarer les plugins dans plugins.
Si les virgules finales posent problème : "trailingComma": "es5" pour retrouver l’ancien comportement (ou accepter le nouveau).
npx prettier --write . ; relire git diff --stat.
Vérifier le script de CI (--check) et les hooks.
Un commit dédié : style: reformater avec prettier 3.

Appels programmatiques (scripts) :

import { format } from 'prettier';

const resultat = await format(code, { parser: 'babel', singleQuote: true }); // asynchrone

Mises à jour sans régression

npm outdated prettier
npm install -D --save-exact prettier@latest
npx prettier --check . || npx prettier --write .
git diff --stat

Lire les notes de version (prettier.io/blog).
Mettre à jour Prettier et ses plugins ensemble.
Reformater dans un commit séparé.
Ajouter le commit de formatage à .git-blame-ignore-revs.

Obtenir de l’aide

Reproduire le problème sur un fichier minimal avec npx prettier --debug-check.
Indiquer npx prettier --version, node --version et la configuration utilisée.
Utiliser le bac à sable en ligne de Prettier (prettier.io/playground) pour comparer les versions.

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

Aucune propre à Ubuntu. Le paquet node-prettier des dépôts Ubuntu n’est pas recommandé : installer Prettier dans le projet avec npm, pour que la version soit la même pour toute l’équipe (voir Node.js : npm).

Pour aller plus loin

Prettier 3.0 : notes de version, Rationale
Retour : Installation