Aller au contenu principal

API

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 →

Si vous souhaitez exécuter Prettier programmatiquement, consultez cette page.

import * as prettier from "prettier";

Nos API publiques sont toutes asynchrones. Si vous devez utiliser une version synchrone pour une raison particulière, vous pouvez essayer @prettier/sync.

prettier.format(source, options)​

format sert à formater du texte avec Prettier. options.parser doit être défini selon le langage que vous formatez (voir la liste des analyseurs disponibles). Alternativement, options.filepath peut être spécifié pour que Prettier déduise l'analyseur à partir de l'extension du fichier. D'autres options peuvent être fournies pour remplacer les valeurs par défaut.

await prettier.format("foo ( );", { semi: false, parser: "babel" });
// -> 'foo()\n'

prettier.check(source [, options])​

check vérifie si le fichier a été formaté avec Prettier selon les options fournies et renvoie une Promise<boolean>. Cela correspond aux paramètres --check ou --list-different de la CLI et est utile pour exécuter Prettier dans des scénarios d'intégration continue (CI).

prettier.formatWithCursor(source [, options])​

formatWithCursor formate le code et traduit la position du curseur du code non formaté vers le code formaté. Utile pour les intégrations d'éditeur, afin d'éviter que le curseur ne bouge lors du formatage du code.

L'option cursorOffset doit être fournie pour spécifier la position du curseur.

await prettier.formatWithCursor(" 1", { cursorOffset: 2, parser: "babel" });
// -> { formatted: '1;\n', cursorOffset: 1 }

prettier.resolveConfig(fileUrlOrPath [, options])​

resolveConfig permet de résoudre la configuration pour un fichier source donné, en passant son chemin ou URL comme premier argument. La recherche de configuration démarre au répertoire du fichier et remonte l'arborescence. Vous pouvez aussi passer directement le chemin du fichier de configuration via options.config si vous ne souhaitez pas le chercher. Une promesse est renvoyée qui se résout en :

La promesse est rejetée en cas d'erreur d'analyse du fichier de configuration.

Si options.useCache est false, tout mécanisme de cache sera contourné.

const text = await fs.readFile(filePath, "utf8");
const options = await prettier.resolveConfig(filePath);
const formatted = await prettier.format(text, {
  ...options,
  filepath: filePath,
});

Si options.editorconfig est true et qu'un fichier .editorconfig est présent dans votre projet, Prettier l'analysera et convertira ses propriétés en configuration Prettier correspondante. Cette configuration sera écrasée par .prettierrc, etc. Actuellement, les propriétés EditorConfig suivantes sont prises en charge :

  • end_of_line

  • indent_style

  • indent_size/tab_width

  • max_line_length

prettier.resolveConfigFile([fileUrlOrPath])​

resolveConfigFile permet de trouver le chemin du fichier de configuration Prettier qui sera utilisé lors de la résolution de la config (c'est-à-dire lors de l'appel à resolveConfig). Une promesse est renvoyée qui se résout en :

  • Le chemin du fichier de configuration

  • null si aucun fichier n'est trouvé

La promesse est rejetée en cas d'erreur d'analyse du fichier de configuration.

La recherche démarre à process.cwd(), ou au répertoire de fileUrlOrPath si fourni.

const configFile = await prettier.resolveConfigFile(filePath);
// you got the path of the configuration file

prettier.clearConfigCache()​

Lorsque Prettier charge les fichiers de configuration et les plugins, la structure du système de fichiers est mise en cache pour des raisons de performance. Cette fonction efface le cache. Généralement, cela n'est nécessaire que pour les intégrations d'éditeur qui détectent des changements du système de fichiers depuis le dernier formatage.

prettier.getFileInfo(fileUrlOrPath [, options])​

getFileInfo peut être utilisé par les extensions d'éditeur pour déterminer si un fichier spécifique nécessite un formatage. Cette méthode renvoie une promesse qui se résout en un objet avec les propriétés suivantes :

{
  ignored: boolean;
  inferredParser: string | null;
}

La promesse sera rejetée si le type de fileUrlOrPath n'est pas string ou URL.

Le paramétrage de options.ignorePath (string | URL | (string | URL)[]) et options.withNodeModules (boolean) influence la valeur de ignored (false par défaut).

Si le fileUrlOrPath donné est ignoré, inferredParser est toujours null.

Fournir les chemins de plugins dans options.plugins ((string | URL | Plugin)[]) aide à extraire inferredParser pour les fichiers non pris en charge par le cœur de Prettier.

Lorsque options.resolveConfig (boolean, par défaut true) est défini sur false, Prettier ne recherchera pas de fichier de configuration. Utile si cette fonction sert uniquement à vérifier l'ignorance d'un fichier.

prettier.getSupportInfo()​

Renvoie une promesse qui se résout en un objet représentant les options, analyseurs, langages et types de fichiers pris en charge par Prettier.

Les informations de support se présentent ainsi :

{
  languages: Array<{
    name: string;
    parsers: string[];
    group?: string;
    tmScope?: string;
    aceMode?: string;
    codemirrorMode?: string;
    codemirrorMimeType?: string;
    aliases?: string[];
    extensions?: string[];
    filenames?: string[];
    linguistLanguageId?: number;
    vscodeLanguageIds?: string[];
    isSupported?(options: { filepath: string }): boolean;
  }>;
}
remarque

Prettier ne peut garantir que filepath existe sur le disque.
Lorsqu'elle est utilisée via des API (ex : prettier.format()), Prettier ne peut pas non plus garantir qu'il s'agit d'un chemin valide.

API Custom Parser (supprimée)​

Supprimée dans la v3.0.0 (remplacée par l'API Plugin)

Avant l'apparition des plugins, Prettier proposait une fonctionnalité similaire mais plus limitée appelée custom parsers. Elle a été supprimée dans la v3.0.0 car ses capacités étaient un sous-ensemble de l'API Plugin. Si vous l'utilisiez, consultez l'exemple ci-dessous pour migrer.

❌ API Custom Parser (supprimée) :

import { format } from "prettier";

format("lodash ( )", {
  parser(text, { babel }) {
    const ast = babel(text);
    ast.program.body[0].expression.callee.name = "_";
    return ast;
  },
});
// -> "_();\n"

✔️ API Plugin :

import { format } from "prettier";
import * as prettierPluginBabel from "prettier/plugins/babel";

const myCustomPlugin = {
  parsers: {
    "my-custom-parser": {
      async parse(text) {
        const ast = await prettierPluginBabel.parsers.babel.parse(text);
        ast.program.body[0].expression.callee.name = "_";
        return ast;
      },
      astFormat: "estree",
    },
  },
};

await format("lodash ( )", {
  parser: "my-custom-parser",
  plugins: [myCustomPlugin],
});
// -> "_();\n"
remarque

L'approche générale de codemods n'est pas recommandée. Prettier utilise les données de position des nœuds AST pour préserver les lignes vides et attacher les commentaires. Si l'AST est modifié après le parsing, ces données perdent leur synchronisation, entraînant des résultats imprévisibles. Privilégiez jscodeshift pour les codemods.

Dans le cadre de l'API Custom Parser supprimée, il était possible de passer un chemin vers un module exportant une fonction parse via l'option --parser. Utilisez plutôt l'option CLI --plugin ou l'option API plugins pour charger les plugins.