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 в командной строке и полезно для запуска 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[]) помогает извлечь 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[];
  }>;
}

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

Удалено в версии 3.0.0 (заменено API плагинов)

До появления плагинов у Prettier была похожая, но более ограниченная функция, называемая пользовательскими парсерами. Она была удалена в версии 3.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"

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

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