API · Prettier

Prettierをプログラムで実行したい場合は、このページをご覧ください。

import * as prettier from "prettier";

公開APIはすべて非同期です。何らかの理由で同期バージョンを使用する必要がある場合は、@prettier/syncを試すことができます。

`prettier.format(source, options)`

formatは、Prettierを使用してテキストをフォーマットするために使用されます。フォーマットする言語に応じて、options.parserを設定する必要があります（利用可能なパーサーのリストを参照）。または、Prettierがファイル拡張子からパーサーを推測できるように、options.filepathを指定することもできます。その他のオプションを指定して、デフォルトをオーバーライドできます。

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

`prettier.check(source [, options])`

checkは、指定されたオプションでファイルがPrettierでフォーマットされているかどうかを確認し、Promise<boolean>を返します。これは、CLIの--checkまたは--list-differentパラメーターに似ており、CIシナリオでPrettierを実行するのに役立ちます。

`prettier.formatWithCursor(source [, options])`

formatWithCursorは、コードのフォーマットと、フォーマットされていないコードからフォーマットされたコードへのカーソル位置の変換の両方を行います。これは、コードがフォーマットされたときにカーソルが移動しないように、エディタ統合に役立ちます。

カーソルの位置を指定するために、cursorOffsetオプションを指定する必要があります。

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

`prettier.resolveConfig(fileUrlOrPath [, options])`

resolveConfigは、指定されたソースファイルの構成を解決するために使用できます。最初の引数としてパスまたはURLを渡します。設定の検索は、ファイルの場所のディレクトリから開始され、ディレクトリを上に検索し続けます。または、検索したくない場合は、設定ファイルのパスをoptions.configとして直接渡すことができます。返されるPromiseは、次のいずれかに解決されます。

設定ファイルが見つかった場合は、オプションオブジェクト。
ファイルが見つからない場合は、null。

設定ファイルの解析中にエラーが発生した場合、Promiseは拒否されます。

options.useCacheがfalseの場合、すべてのキャッシュがバイパスされます。

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

options.editorconfigがtrueで、プロジェクトに.editorconfigファイルがある場合、Prettierはそれを解析し、そのプロパティを対応するPrettier設定に変換します。この設定は、.prettierrcなどによってオーバーライドされます。現在、次のEditorConfigプロパティがサポートされています。

end_of_line
indent_style
indent_size/tab_width
max_line_length

`prettier.resolveConfigFile([fileUrlOrPath])`

resolveConfigFileは、設定を解決するときに使用されるPrettier設定ファイルのパスを見つけるために使用できます（つまり、resolveConfigを呼び出すとき）。返されるPromiseは、次のいずれかに解決されます。

設定ファイルのパス。
ファイルが見つからない場合は、null。

設定ファイルの解析中にエラーが発生した場合、Promiseは拒否されます。

検索はprocess.cwd()から、またはfileUrlOrPathが提供されている場合はそのディレクトリから開始されます。

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

`prettier.clearConfigCache()`

Prettierが設定ファイルとプラグインをロードすると、パフォーマンスのためにファイルシステム構造がキャッシュされます。この関数はキャッシュをクリアします。一般に、これは、最後のフォーマット以降にファイルシステムが変更されたことを認識しているエディタ統合にのみ必要です。

`prettier.getFileInfo(fileUrlOrPath [, options])`

getFileInfoは、エディタ拡張機能が特定のファイルをフォーマットする必要があるかどうかを判断するために使用できます。このメソッドは、次のプロパティを持つオブジェクトに解決されるPromiseを返します。

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

fileUrlOrPathのタイプがstringまたはURLでない場合、Promiseは拒否されます。

options.ignorePath（string | URL | (string | URL)[]）とoptions.withNodeModules（boolean）を設定すると、ignored（デフォルトはfalse）の値に影響します。

指定されたfileUrlOrPathが無視される場合、inferredParserは常にnullです。

options.plugins（string[]）にプラグインパスを指定すると、PrettierコアでサポートされていないファイルのinferredParserを抽出するのに役立ちます。

options.resolveConfig（boolean、デフォルトはtrue）をfalseに設定すると、Prettierは設定ファイルを検索しません。この関数がファイルが無視されるかどうかを確認するためだけに使用される場合、これは役立ちます。

`prettier.getSupportInfo()`

Prettierがサポートするオプション、パーサー、言語、およびファイルタイプを表すオブジェクトに解決されるPromiseを返します。

サポート情報は次のようになります。

{
  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[];
  }>;
}

カスタムパーサーAPI（削除済み）

v3.0.0で削除されました（プラグインAPIに置き換えられました）

プラグインが登場する前は、Prettierにはカスタムパーサーと呼ばれる同様ですが、より限定的な機能がありました。その機能はプラグインAPIのサブセットであったため、v3.0.0で削除されました。使用していた場合は、以下の例で移行方法を確認してください。

❌ カスタムパーサーAPI（削除済み）

import { format } from "prettier";

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

✔️ プラグインAPI

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"

注：全体的に、この方法でコードモッドを実行することはお勧めしません。Prettierは、空白行の保持やコメントの添付など、多くのことにASTノードの位置データを使用します。解析後にASTが変更されると、位置データの同期がずれて、予期しない結果が生じる可能性があります。コードモッドが必要な場合は、jscodeshiftの使用を検討してください。

削除されたカスタムパーサーAPIの一部として、以前は--parserオプションを介してparse関数をエクスポートするモジュールへのパスを渡すことができました。プラグインをロードするには、代わりに--plugin CLIオプションまたはplugins APIオプションを使用してください。