Options

Traduction Bêta Non Officielle

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

Prettier est livré avec un ensemble d'options de formatage.

Pour comprendre la philosophie de Prettier concernant les options – consultez la Philosophie des options.

Si vous modifiez des options, il est recommandé de le faire via un fichier de configuration. Ainsi le CLI Prettier, les intégrations éditeurs et les autres outils connaîtront vos options.

Ternaires expérimentaux

Testez le nouveau formatage des ternaires avant qu'il ne devienne le comportement par défaut.

Options valides :

• true - Utilise des ternaires curieux, avec le point d'interrogation après la condition.

• false - Conserve le comportement par défaut des ternaires ; garde les points d'interrogation sur la même ligne que la conséquence.

Default	CLI Override	API Override
false	--experimental-ternaries	experimentalTernaries: <bool>

Position expérimentale des opérateurs

Options valides :

• "start" - Lorsque les expressions binaires s'étendent sur plusieurs lignes, place les opérateurs en début de nouvelles lignes.

• "end" - Comportement par défaut ; place les opérateurs en fin de lignes précédentes lors du retour à la ligne des expressions binaires.

Default	CLI Override	API Override
"end"	--experimental-operator-position <start|end>	experimentalOperatorPosition: "<start|end>"

Largeur d'impression

Définit la longueur de ligne à laquelle le formateur effectuera un retour à la ligne.

avertissement

Pour la lisibilité, nous déconseillons d'utiliser plus de 80 caractères :

Dans les guides de style, la longueur maximale des lignes est souvent fixée à 100 ou 120 caractères. Cependant, lorsqu'ils écrivent du code, les développeurs ne cherchent pas systématiquement à atteindre cette limite. Ils utilisent souvent des espaces pour diviser les longues lignes et améliorer la lisibilité. En pratique, la longueur moyenne des lignes reste généralement bien inférieure au maximum.

L'option printWidth de Prettier ne fonctionne pas de cette manière. Ce n'est pas une limite stricte de longueur de ligne, mais une indication de la longueur approximative souhaitée. Prettier produira des lignes plus courtes et plus longues, mais s'efforcera globalement de respecter la printWidth spécifiée.

N'oubliez pas : les ordinateurs sont littéraux. Vous devez leur indiquer explicitement quoi faire, alors que les humains peuvent prendre des décisions implicites, comme l'endroit où couper une ligne.

En d'autres termes, n'utilisez pas printWidth comme s'il s'agissait de la règle max-len d'ESLint – elles sont différentes. max-len définit uniquement la longueur maximale autorisée, sans indiquer la longueur préférentielle – ce que fait précisément printWidth.

Default	CLI Override	API Override
80	--print-width <int>	printWidth: <int>

Définir max_line_length dans un fichier .editorconfig configurera la printWidth de Prettier, sauf substitution.

(Si vous ne voulez pas de retours à la ligne lors du formatage Markdown, utilisez l'option Prose Wrap.)

Largeur de tabulation

Définit le nombre d'espaces par niveau d'indentation.

Default	CLI Override	API Override
2	--tab-width <int>	tabWidth: <int>

Définir indent_size ou tab_width dans un fichier .editorconfig configurera la largeur de tabulation de Prettier, sauf substitution.

Tabulations

Indente les lignes avec des tabulations au lieu d'espaces.

Default	CLI Override	API Override
false	--use-tabs	useTabs: <bool>

Définir indent_style dans un fichier .editorconfig configurera l'usage des tabulations par Prettier, sauf substitution.

(Les tabulations sont utilisées pour l'indentation, mais Prettier utilise des espaces pour l'alignement (par exemple dans les ternaires). Ce comportement s'appelle SmartTabs.)

Points-virgules

Imprime les points-virgules en fin d'instructions.

Options valides :

• true - Ajoute un point-virgule à la fin de chaque instruction.

• false - N'ajouter des points-virgules qu'au début des lignes pouvant provoquer des échecs ASI.

Default	CLI Override	API Override
true	--no-semi	semi: <bool>

Guillemets

Utiliser des guillemets simples au lieu de guillemets doubles.

Notes :

• Les guillemets JSX ignorent cette option – voir jsx-single-quote.

• Si un type de guillemet est majoritairement utilisé dans la chaîne, le guillemet le moins présent sera choisi pour le formatage - Exemple : "I'm double quoted" devient "I'm double quoted" et "This \"example\" is single quoted" devient 'This "example" is single quoted'.

Voir la logique concernant les chaînes pour plus d'informations.

Default	CLI Override	API Override
false	--single-quote	singleQuote: <bool>

Guillemets des propriétés

Détermine quand les propriétés des objets doivent être entourées de guillemets.

Options valides :

• "as-needed" - Ajouter des guillemets uniquement autour des propriétés d'objet qui en nécessitent.

• "consistent" - Si au moins une propriété d'un objet nécessite des guillemets, toutes les propriétés en reçoivent.

• "preserve" - Respecter l'utilisation originale des guillemets dans les propriétés d'objet.

Default	CLI Override	API Override
"as-needed"	--quote-props <as-needed|consistent|preserve>	quoteProps: "<as-needed|consistent|preserve>"

Notez que Prettier ne supprime jamais les guillemets des noms de propriétés numériques dans les expressions Angular, TypeScript et Flow car la distinction entre clés chaînes et numériques est significative dans ces langages. Voir : Angular, TypeScript, Flow. Prettier ne supprime pas non plus les guillemets des propriétés numériques pour Vue (voir le problème correspondant).

Guillemets JSX

Utiliser des guillemets simples au lieu de guillemets doubles en JSX.

Default	CLI Override	API Override
false	--jsx-single-quote	jsxSingleQuote: <bool>

Virgules finales

Valeur par défaut passée de es5 à all dans la v3.0.0

Ajouter des virgules finales partout où possible dans les structures syntaxiques multilignes séparées par des virgules. (Un tableau monoligne, par exemple, n'aura jamais de virgules finales.)

Options valides :

• "all" - Virgules finales partout où possible (y compris les paramètres et appels de fonction). Pour exécuter du JavaScript formaté ainsi, un moteur supportant ES2017 (Node.js 8+ ou navigateur moderne) ou une transpilation est requis. Active également les virgules finales dans les paramètres de type TypeScript (supporté depuis TypeScript 2.7 sorti en janvier 2018).

• "es5" - Virgules finales là où valides en ES5 (objets, tableaux, etc.). Virgules finales dans les paramètres de type TypeScript et Flow.

• "none" - Aucune virgule finale.

Default	CLI Override	API Override
"all"	--trailing-comma <all|es5|none>	trailingComma: "<all|es5|none>"

Espacement des crochets

Imprimer des espaces entre les crochets dans les littéraux d'objet.

Options valides :

• true - Exemple : { foo: bar }.

• false - Exemple : {foo: bar}.

Default	CLI Override	API Override
true	--no-bracket-spacing	bracketSpacing: <bool>

Encapsulation des objets

Disponible depuis la v3.5.0

Configure la façon dont Prettier formate les objets littéraux selon qu'ils pourraient tenir sur une ligne ou nécessiter plusieurs lignes.

Par défaut, Prettier formate les objets sur plusieurs lignes s'il y a un saut de ligne avant la première propriété. Les développeurs peuvent utiliser cette heuristique pour améliorer la lisibilité contextuellement, bien que cela présente certains inconvénients. Voir Objets multi-lignes.

Options valides :

• "preserve" - Conserve le format multi-ligne s'il y a un saut de ligne entre l'accolade ouvrante et la première propriété.

• "collapse" - Tient sur une seule ligne quand c'est possible.

Default	CLI Override	API Override
"preserve"	--object-wrap <preserve|collapse>	objectWrap: "<preserve|collapse>"

Ligne d'accolade

Place le > d'un élément HTML multi-ligne (HTML, JSX, Vue, Angular) à la fin de la dernière ligne plutôt que seul sur la ligne suivante (ne s'applique pas aux éléments auto-fermants).

Options valides :

• true - Exemple :

<button
  className="prettier-class"
  id="prettier-id"
  onClick={this.handleClick}>
  Click Here
</button>

• false - Exemple :

<button
  className="prettier-class"
  id="prettier-id"
  onClick={this.handleClick}
>
  Click Here
</button>

Default	CLI Override	API Override
false	--bracket-same-line	bracketSameLine: <bool>

[Obsolète] Accolades JSX

danger

Cette option est obsolète depuis la v2.4.0, utilisez plutôt --bracket-same-line.

Place le > d'un élément JSX multi-ligne à la fin de la dernière ligne plutôt que seul sur la ligne suivante (ne s'applique pas aux éléments auto-fermants).

Options valides :

• true - Exemple :

<button
  className="prettier-class"
  id="prettier-id"
  onClick={this.handleClick}>
  Click Here
</button>

• false - Exemple :

<button
  className="prettier-class"
  id="prettier-id"
  onClick={this.handleClick}
>
  Click Here
</button>

Default	CLI Override	API Override
false	--jsx-bracket-same-line	jsxBracketSameLine: <bool>

Parenthèses des fonctions fléchées

Disponible depuis la v1.9.0, valeur par défaut changée de avoid à always en v2.0.0

Inclut les parenthèses autour du paramètre unique d'une fonction fléchée.

Options valides :

• "always" - Toujours inclure les parenthèses. Exemple : (x) => x

• "avoid" - Omettre les parenthèses quand possible. Exemple : x => x

Default	CLI Override	API Override
"always"	--arrow-parens <always|avoid>	arrowParens: "<always|avoid>"

À première vue, omettre les parenthèses peut sembler préférable pour réduire le bruit visuel. Cependant, quand Prettier supprime les parenthèses, cela complique l'ajout d'annotations de type, d'arguments supplémentaires ou de valeurs par défaut, ainsi que d'autres modifications. L'utilisation systématique des parenthèses offre une meilleure expérience aux développeurs lors de la modification de bases de code réelles, ce qui justifie la valeur par défaut de cette option.

Intervalle

Formate uniquement un segment d'un fichier.

Ces deux options permettent de formater le code à partir d'un décalage de caractère de début (inclusif) et de fin (exclusif). L'intervalle s'étendra :

• Vers l'arrière jusqu'au début de la première ligne contenant l'instruction sélectionnée.

• Vers l'avant jusqu'à la fin de l'instruction sélectionnée.

Default	CLI Override	API Override
0	--range-start <int>	rangeStart: <int>
Infinity	--range-end <int>	rangeEnd: <int>

Parseur

Spécifie le parseur à utiliser.

Prettier déduit automatiquement le parseur à partir du chemin du fichier source, vous ne devriez donc pas avoir à modifier ce paramètre.

Les parseurs babel et flow prennent en charge le même ensemble de fonctionnalités JavaScript (y compris les annotations de type Flow). Ils peuvent différer dans certains cas limites, donc si vous rencontrez un problème, essayez flow au lieu de babel. Le même principe s'applique à typescript et babel-ts. babel-ts peut supporter des fonctionnalités JavaScript (propositions) non encore prises en charge par TypeScript, mais il est moins permissif pour le code invalide et moins éprouvé que le parseur typescript.

Options valides :

• "babel" (via @babel/parser) Nommé "babylon" jusqu'à la version v1.16.0

• "babel-flow" (identique à "babel" mais active explicitement l'analyse Flow pour éviter les ambiguïtés) Disponible pour la première fois dans la version v1.16.0

• "babel-ts" (similaire à "typescript" mais utilise Babel et son plugin TypeScript) Disponible pour la première fois dans la version v2.0.0

• "flow" (via flow-parser)

• "typescript" (via @typescript-eslint/typescript-estree) Disponible pour la première fois dans la version v1.4.0

• "espree" (via espree) Disponible pour la première fois dans la version v2.2.0

• "meriyah" (via meriyah) Disponible pour la première fois dans la version v2.2.0

• "acorn" (via acorn) Disponible pour la première fois dans la version v2.6.0

• "css" (via postcss) Disponible pour la première fois dans la version v1.7.1

• "scss" (via postcss-scss) Disponible pour la première fois dans la version v1.7.1

• "less" (via postcss-less) Disponible pour la première fois dans la version v1.7.1

• "json" (via @babel/parser parseExpression) Disponible pour la première fois dans la version v1.5.0

• "json5" (même analyseur que "json", mais produit du json5) Disponible pour la première fois dans la version v1.13.0

• "jsonc" (même analyseur que "json", mais produit du "JSON avec commentaires") Disponible pour la première fois dans la version v3.2.0

• "json-stringify" (parse comme JSON.parse() mais moins strictement, les espaces blancs ressemblent à JSON.stringify()) Disponible depuis la v1.13.0

• "graphql" (via graphql/language) Disponible pour la première fois dans la version v1.5.0

• "markdown" (via remark-parse) Disponible pour la première fois dans la version v1.8.0

• "mdx" (via remark-parse et @mdx-js/mdx) Disponible pour la première fois dans la version v1.15.0

• "html" (via angular-html-parser) Disponible pour la première fois dans la version 1.15.0

• "vue" (même analyseur que "html", mais formate également la syntaxe spécifique à Vue) Disponible pour la première fois dans la version 1.10.0

• "angular" (même analyseur que "html", mais formate également la syntaxe spécifique à Angular via angular-estree-parser) Disponible pour la première fois dans la version 1.15.0

• "lwc" (même analyseur que "html", mais formate également la syntaxe spécifique à LWC pour les attributs de template non quotés) Disponible pour la première fois dans la version 1.17.0

• "mjml" (même parseur que "html", mais formate également la syntaxe spécifique à MJML) Disponible à partir de la version 3.6.0

• "yaml" (via yaml et yaml-unist-parser) Disponible à partir de la version 1.14.0

Default	CLI Override	API Override
None	--parser <string>	parser: "<string>"

Note : la valeur par défaut était "babylon" jusqu'à la version 1.13.0.

Note : l'API de parseur personnalisé a été supprimée dans la version 3.0.0. Utilisez plutôt des plugins (comment migrer).

Chemin du fichier

Spécifiez le nom du fichier à utiliser pour déterminer quel parseur utiliser.

Par exemple, ce qui suit utilisera le parseur CSS :

cat foo | prettier --stdin-filepath foo.css

Cette option n'est utile que dans la CLI et l'API. Elle n'a pas de sens dans un fichier de configuration.

Default	CLI Override	API Override
None	--stdin-filepath <string>	filepath: "<string>"

Exiger un pragma

Disponible à partir de la version 1.7.0

Prettier peut se limiter à formater uniquement les fichiers contenant un commentaire spécial, appelé pragma, en haut du fichier. Ceci est très utile lors de la transition progressive de grandes bases de code non formatées vers Prettier.

Un fichier avec le commentaire suivant en première position sera formaté lorsque --require-pragma est spécifié :

/**
 * @prettier
 */

ou

/**
 * @format
 */

Default	CLI Override	API Override
false	--require-pragma	requirePragma: <bool>

Insérer un pragma

Disponible à partir de la version 1.8.0

Prettier peut insérer un marqueur spécial @format en haut des fichiers indiquant que le fichier a été formaté avec Prettier. Cela fonctionne bien en combinaison avec l'option --require-pragma. S'il existe déjà un bloc de documentation en haut du fichier, cette option ajoutera une nouvelle ligne avec le marqueur @format.

Notez que "en combinaison" ne signifie pas "simultanément". Lorsque les deux options sont utilisées ensemble, --require-pragma a la priorité et --insert-pragma est ignoré. L'idée est que lors d'une adoption progressive de Prettier dans une grande base de code, les développeurs participant à la transition utilisent --insert-pragma tandis que --require-pragma est utilisé par le reste de l'équipe et les outils automatisés pour ne traiter que les fichiers déjà convertis. Cette fonctionnalité s'inspire de la [stratégie d'adoption] de Facebook.

Default	CLI Override	API Override
false	--insert-pragma	insertPragma: <bool>

Vérifier le pragma d'ignoré

Disponible à partir de la version 3.6.0

Prettier peut permettre à des fichiers individuels d'ignorer le formatage s'ils contiennent un commentaire spécial, appelé pragma, en haut du fichier.

La vérification de ces marqueurs entraîne un léger coût supplémentaire pendant le formatage, c'est pourquoi elle n'est pas activée par défaut.

Un fichier avec le commentaire suivant en première position ne sera pas formaté lorsque --check-ignore-pragma est spécifié :

/**
 * @noprettier
 */

ou

/**
 * @noformat
 */

Default	CLI Override	API Override
false	--check-ignore-pragma	checkIgnorePragma: <bool>

Enveloppe de la prose

Disponible à partir de la version 1.8.2

Par défaut, Prettier ne modifie pas les retours à la ligne dans le texte Markdown car certains services utilisent un rendu sensible aux sauts de ligne (par exemple les commentaires GitHub et BitBucket). Pour que Prettier renvoie la prose à la ligne selon la largeur d'impression, définissez cette option sur "always". Si vous souhaitez que Prettier force tous les blocs de prose à rester sur une seule ligne et s'appuie sur le retour à la ligne souple de l'éditeur/visionneuse, utilisez "never".

Options valides :

• "always" - Renvoyer la prose à la ligne si elle dépasse la largeur d'impression.

• "never" - Forcer chaque bloc de prose sur une seule ligne.

• "preserve" - Ne rien modifier, conserver le texte tel quel. Disponible depuis la v1.9.0

Default	CLI Override	API Override
"preserve"	--prose-wrap <always|never|preserve>	proseWrap: "<always|never|preserve>"

Sensibilité aux espaces en HTML

Disponible depuis la v1.15.0. Disponible pour Handlebars depuis la v2.3.0

Définit la sensibilité globale aux espaces pour le HTML, Vue, Angular et Handlebars. Voir le formatage sensible aux espaces pour plus d'informations.

Options valides :

• "css" - Respecte la valeur par défaut de la propriété CSS display. Traité comme strict pour Handlebars.

• "strict" - Les espaces (ou leur absence) autour de toutes les balises sont considérés comme significatifs.

• "ignore" - Les espaces (ou leur absence) autour de toutes les balises sont considérés comme non significatifs.

Default	CLI Override	API Override
"css"	--html-whitespace-sensitivity <css|strict|ignore>	htmlWhitespaceSensitivity: "<css|strict|ignore>"

Indentation des balises script et style dans les fichiers Vue

Disponible depuis la v1.19.0

Détermine s'il faut indenter le code à l'intérieur des balises <script> et <style> dans les fichiers Vue.

Options valides :

• false - N'indente pas les balises script et style dans les fichiers Vue.

• true - Indente les balises script et style dans les fichiers Vue.

Default	CLI Override	API Override
false	--vue-indent-script-and-style	vueIndentScriptAndStyle: <bool>

Fin de ligne

Disponible depuis la v1.15.0, valeur par défaut changée de auto à lf dans la v2.0.0

Pour des raisons historiques, il existe deux types courants de fins de ligne dans les fichiers texte : \n (ou LF pour Line Feed) et \r\n (ou CRLF pour Carriage Return + Line Feed). Le premier est courant sous Linux et macOS, tandis que le second prévaut sous Windows. Des détails expliquant cette différence sont disponibles sur Wikipédia.

Lorsque des personnes collaborent sur un projet depuis différents systèmes d'exploitation, il devient facile d'obtenir des fins de ligne mélangées dans un dépôt git partagé. Il est également possible que des utilisateurs Windows modifient accidentellement les fins de ligne d'un fichier déjà validé de LF à CRLF. Cela génère un git diff important et rend l'historique ligne par ligne d'un fichier (git blame) plus difficile à explorer.

Pour garantir que votre dépôt git ne contienne que des fins de ligne de style Linux dans les fichiers gérés par Prettier :

1. Vérifiez que l'option endOfLine de Prettier est définie sur lf (valeur par défaut depuis la v2.0.0)

2. Configurez un hook pre-commit qui exécutera Prettier

3. Configurez Prettier pour qu'il s'exécute dans votre pipeline CI avec l'option --check. Si vous utilisez Travis CI, définissez l'option autocrlf sur input dans .travis.yml.

4. Ajoutez * text=auto eol=lf au fichier .gitattributes du dépôt. Les utilisateurs Windows devront peut-être recloner votre dépôt après ce changement pour s'assurer que git n'ait pas converti LF en CRLF lors du checkout.

Tous les éditeurs de texte modernes sur tous les systèmes d'exploitation peuvent afficher correctement les fins de ligne quand \n (LF) est utilisé. Cependant, les anciennes versions de Notepad sous Windows afficheront ces lignes comme une seule car elles ne gèrent que \r\n (CRLF).

Options valides :

• "lf" – Line Feed uniquement (\n), courant sous Linux et macOS ainsi que dans les dépôts git

• "crlf" - Carriage Return + Line Feed (\r\n), couramment utilisé sous Windows

• "cr" - Carriage Return uniquement (\r), très rarement utilisé

• "auto" - Conserver les fins de ligne existantes (les valeurs mixtes dans un fichier sont normalisées en fonction de l'usage après la première ligne)

Default	CLI Override	API Override
"lf"	--end-of-line <lf|crlf|cr|auto>	endOfLine: "<lf|crlf|cr|auto>"

La configuration de end_of_line dans un fichier .editorconfig définira l'utilisation des fins de ligne par Prettier, sauf remplacement.

Formatage des langages embarqués

Disponible à partir de la v2.1.0

Contrôle si Prettier formate le code cité intégré dans le fichier.

Lorsque Prettier identifie des cas où vous semblez avoir placé du code formatable dans une chaîne (comme dans un template balisé JavaScript avec une balise html ou dans des blocs de code Markdown), il tentera par défaut de formater ce code.

Ce comportement est parfois indésirable, notamment si vous ne souhaitiez pas que la chaîne soit interprétée comme du code. Cette option permet de basculer entre le comportement par défaut (auto) et la désactivation complète (off).

Options valides :

• "auto" – Formate le code embarqué si Prettier peut l'identifier automatiquement.

• "off" - Ne formate jamais automatiquement le code embarqué.

Default	CLI Override	API Override
"auto"	--embedded-language-formatting=<off|auto>	embeddedLanguageFormatting: "<off|auto>"

Un attribut par ligne

Disponible à partir de la v2.6.0

Impose un seul attribut par ligne en HTML, Vue et JSX.

Options valides :

• false - N'impose pas un seul attribut par ligne.

• true - Impose un seul attribut par ligne.

Default	CLI Override	API Override
false	--single-attribute-per-line	singleAttributePerLine: <bool>