API

Если вы хотите использовать Prettier программно, ознакомьтесь с этой страницей.

import * as prettier from "prettier";

Все наши общедоступные API асинхронны. Если вам по какой-либо причине нужна синхронная версия, попробуйте @prettier/sync.

`prettier.format(source, options)`

format используется для форматирования текста с помощью Prettier. Значение options.parser должно соответствовать форматируемому языку (см. список доступных парсеров). Также можно указать options.filepath, чтобы Prettier определил парсер по расширению файла. Для переопределения значений по умолчанию можно указать другие параметры.

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

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

check проверяет, отформатирован ли файл с помощью Prettier с указанными параметрами, и возвращает Promise<boolean>. Это аналог параметра --check или --list-different в CLI и полезно для запуска Prettier в сценариях CI.

`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. Возвращается промис, который будет разрешен одним из следующих значений:

Объект параметров, если найден файл конфигурации.
null, если файл не найден.

Промис будет отклонен, если при разборе файла конфигурации возникнет ошибка.

Если options.useCache имеет значение false, кэширование будет отключено.

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

Если 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). Возвращается промис, который будет разрешен одним из следующих значений:

Путь к файлу конфигурации.
null, если файл не найден.

Промис будет отклонен, если при разборе файла конфигурации возникнет ошибка.

Поиск начинается в 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 может использоваться расширениями редакторов, чтобы определить, нужно ли форматировать конкретный файл. Этот метод возвращает промис, который разрешается объектом со следующими свойствами:

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

Промис будет отклонен, если тип fileUrlOrPath не равен string или URL.

Значения options.ignorePath (string | URL | (string | URL)[]) и options.withNodeModules (boolean) влияют на значение ignored (по умолчанию false).

Если указанный fileUrlOrPath игнорируется, значение inferredParser всегда равно null.

Указание путей к плагинам в options.plugins ((string | URL | Plugin)[]) помогает извлечь inferredParser для файлов, не поддерживаемых ядром Prettier.

Если установить options.resolveConfig (boolean, значение по умолчанию — true) в false, Prettier не будет искать файл конфигурации. Это может быть полезно, если эта функция используется только для проверки того, игнорируется ли файл.

`prettier.getSupportInfo()`

Возвращает промис, который разрешается объектом с информацией о параметрах, парсерах, языках и типах файлов, поддерживаемых Prettier.

Информация о поддержке выглядит так:

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

примечание

Prettier не может проверить, существует ли filepath на диске.
При использовании через API (например, prettier.format()) Prettier также не может проверить, является ли этот путь допустимым.

Пользовательский API парсера (удален)

Удален в v3.0.0 (заменен API плагинов)

До появления плагинов в Prettier была похожая, но более ограниченная возможность, называвшаяся пользовательскими парсерами. Она была удалена в v3.0.0, поскольку ее функциональность входила в набор возможностей API плагинов. Если вы использовали ее, ознакомьтесь с примером ниже, чтобы узнать, как выполнить миграцию.

❌ Пользовательский 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"

примечание

В целом такой способ создания codemod не рекомендуется. Prettier использует данные о расположении узлов AST для многих задач, например для сохранения пустых строк и привязки комментариев. Если изменить AST после разбора, данные о расположении часто перестают соответствовать действительности, что может привести к непредсказуемым результатам. Если вам нужны codemod, рассмотрите возможность использования jscodeshift.

В рамках удаленного API пользовательских парсеров ранее можно было передать путь к модулю, экспортирующему функцию parse, с помощью параметра --parser. Вместо этого используйте параметр CLI --plugin или параметр API plugins, чтобы загрузить плагины.