Параметры

Prettier поставляется с несколькими параметрами форматирования.

Подробнее о подходе Prettier к параметрам см. в разделе Философия параметров.

Если вы меняете какие-либо параметры, рекомендуется сделать это с помощью файла конфигурации. Так CLI Prettier, интеграции с редакторами и другие инструменты будут знать, какие параметры вы используете.

Экспериментальный формат тернарных операторов

Попробуйте новый формат тернарных операторов Prettier до того, как он станет поведением по умолчанию.

Допустимые значения:

• true — использовать необычный формат тернарных операторов, располагая вопросительный знак после условия.
• false — сохранить поведение тернарных операторов по умолчанию; оставлять вопросительные знаки в той же строке, что и выражение после двоеточия.

Экспериментальное расположение операторов

Допустимые значения:

• "start" — при переносе бинарных выражений на новые строки выводить операторы в начале новых строк.
• "end" — поведение по умолчанию; при переносе бинарных выражений на новые строки выводить операторы в конце предыдущих строк.

Ширина строки

Задаёт длину строки, при достижении которой форматтер будет переносить текст.

Для удобства чтения рекомендуем не использовать более 80 символов:

В руководствах по стилю кода максимальная длина строки часто ограничивается 100 или 120 символами. Однако при написании кода люди не стремятся заполнять максимальное число столбцов в каждой строке. Разработчики часто используют пробелы, чтобы разбивать длинные строки и улучшать читаемость. На практике средняя длина строки обычно значительно меньше максимальной.

Параметр printWidth в Prettier работает иначе. Это не жёсткое ограничение максимальной длины строки. С его помощью можно примерно указать Prettier желаемую длину строк. Prettier будет создавать как более короткие, так и более длинные строки, но в целом постарается придерживаться заданного значения printWidth.

Помните: компьютеры неразумны. Им нужно явно указывать, что делать, тогда как люди способны самостоятельно (неявно) принимать решения, например о том, когда переносить строку.

Иными словами, не используйте printWidth так, словно это правило ESLint max-len: это разные вещи. max-len лишь указывает максимально допустимую длину строки, но не рекомендуемую длину в целом — именно её задаёт printWidth.

Настройка max_line_length в файле .editorconfig задаст ширину строки в Prettier, если она не переопределена.

(Если вы не хотите, чтобы при форматировании Markdown выполнялся перенос строк, можно отключить его с помощью параметра Перенос текста.)

Ширина табуляции

Задаёт количество пробелов на уровень отступа.

Настройка indent_size или tab_width в файле .editorconfig задаст ширину табуляции в Prettier, если она не переопределена.

Табуляция

Использовать для отступов табуляцию вместо пробелов.

Настройка indent_style в файле .editorconfig задаст использование табуляции в Prettier, если параметр не переопределён.

(Для отступов будут использоваться табуляции, но Prettier использует пробелы для выравнивания, например в тернарных операторах. Такое поведение называется SmartTabs.)

Точки с запятой

Выводить точки с запятой в конце инструкций.

Допустимые значения:

• true — добавлять точку с запятой в конце каждой инструкции.
• false — добавлять точки с запятой только в начале строк, которые могут привести к ошибкам ASI.

Кавычки

Использовать одинарные кавычки вместо двойных.

Примечания:

• На кавычки в JSX этот параметр не влияет — см. jsx-single-quote.
• Если кавычек одного типа больше, чем другого, для форматирования строки будут использоваться кавычки, встречающиеся реже. Например: "I'm double quoted" преобразуется в "I'm double quoted", а "This \"example\" is single quoted" — в 'This "example" is single quoted'.

Подробнее см. обоснование выбора строк.

Кавычки в свойствах

Задаёт, когда свойства объектов заключаются в кавычки.

Допустимые значения:

• "as-needed" — заключать в кавычки только те свойства объектов, для которых это необходимо.
• "consistent" — если хотя бы одно свойство объекта требует кавычек, заключать в кавычки все свойства.
• "preserve" — сохранять исходное использование кавычек в свойствах объектов.

Обратите внимание: Prettier никогда не удаляет кавычки у числовых имён свойств в выражениях Angular, TypeScript и Flow, поскольку в этих языках различие между строковыми и числовыми ключами имеет значение. См.: Angular, TypeScript, Flow. Prettier также не удаляет кавычки у числовых свойств Vue (см. обсуждение этой проблемы).

Кавычки в JSX

Использовать одинарные кавычки вместо двойных в JSX.

Завершающие запятые

В v3.0.0 значение по умолчанию изменено с es5 на all

Добавлять завершающие запятые везде, где это возможно, в синтаксических конструкциях с разделением запятыми, занимающих несколько строк. (Например, в однострочном массиве завершающая запятая никогда не ставится.)

Допустимые значения:

• "all" — завершающие запятые везде, где это возможно (в том числе в параметрах и вызовах функций). Для запуска кода JavaScript в таком формате требуется движок с поддержкой ES2017 (Node.js 8+ или современный браузер) либо транспиляция в более раннюю версию. Также добавляются завершающие запятые в параметрах типов TypeScript (поддерживается начиная с TypeScript 2.7, выпущенного в январе 2018 года).
• "es5" — завершающие запятые там, где они допустимы в ES5 (объекты, массивы и т. д.). Завершающие запятые в параметрах типов TypeScript и Flow.
• "none" — без завершающих запятых.

Пробелы внутри фигурных скобок

Добавлять пробелы внутри фигурных скобок в литералах объектов.

Допустимые значения:

• true — пример: { foo: bar }.
• false — пример: {foo: bar}.

Перенос объектов

Доступно начиная с v3.5.0

Задаёт, как Prettier переносит литералы объектов, которые могут уместиться в одной строке или занимать несколько строк.

По умолчанию Prettier форматирует объекты в несколько строк, если перед первым свойством есть перевод строки. Авторы могут использовать эту эвристику для контекстного повышения читаемости, хотя у неё есть и недостатки. См. раздел Многострочные объекты.

Допустимые значения:

• "preserve" — сохранять многострочный формат, если между открывающей фигурной скобкой и первым свойством есть перевод строки.
• "collapse" — при возможности размещать в одной строке.

Скобка в той же строке

Размещать > многострочного элемента HTML (HTML, JSX, Vue, Angular) в конце последней строки, а не отдельно в следующей строке (не применяется к самозакрывающимся элементам).

Допустимые значения:

• true — пример:

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

• false — пример:

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

[Устарело] Скобки JSX

Этот параметр устарел в v2.4.0; используйте вместо него --bracket-same-line.

Размещать > многострочного элемента JSX в конце последней строки, а не отдельно в следующей строке (не применяется к самозакрывающимся элементам).

Допустимые значения:

• true — пример:

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

• false — пример:

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

Круглые скобки в стрелочных функциях

Впервые доступно в v1.9.0; в v2.0.0 значение по умолчанию изменено с avoid на always

Заключать единственный параметр стрелочной функции в круглые скобки.

Допустимые значения:

• "always" — всегда добавлять скобки. Пример: (x) => x
• "avoid" — опускать скобки, когда это возможно. Пример: x => x

На первый взгляд отказ от круглых скобок может показаться лучшим выбором, поскольку он уменьшает визуальный шум. Однако после того, как Prettier удаляет скобки, становится сложнее добавлять аннотации типов, дополнительные аргументы или значения по умолчанию, а также вносить другие изменения. Последовательное использование скобок упрощает редактирование реальных кодовых баз и обеспечивает более удобную работу разработчиков, поэтому для этого параметра выбрано такое значение по умолчанию.

Диапазон

Форматировать только часть файла.

Эти два параметра позволяют форматировать код, начиная и заканчивая указанным смещением символа (включительно и исключительно соответственно). Диапазон будет расширен:

• назад — до начала первой строки, содержащей выбранную инструкцию;
• вперёд — до конца выбранной инструкции.

Парсер

Задаёт используемый парсер.

Prettier автоматически определяет парсер по пути к входному файлу, поэтому менять эту настройку обычно не требуется.

Парсеры babel и flow поддерживают один и тот же набор возможностей JavaScript (включая аннотации типов Flow). В некоторых пограничных случаях они могут различаться, поэтому, если вы столкнётесь с одним из них, можно попробовать flow вместо babel. Почти то же самое относится к typescript и babel-ts. babel-ts может поддерживать возможности JavaScript (предложения), которые ещё не поддерживаются TypeScript, но он менее терпим к некорректному коду и проверен меньше, чем парсер typescript.

Допустимые значения:

• "babel" (через @babel/parser) До v1.16.0 назывался "babylon"
• "babel-flow" (то же, что "babel", но с явным включением разбора Flow во избежание неоднозначностей) Впервые доступно в v1.16.0
• "babel-ts" (аналогично "typescript", но использует Babel и его плагин TypeScript) Впервые доступно в v2.0.0
• "flow" (через flow-parser)
• "typescript" (через @typescript-eslint/typescript-estree) Впервые доступно в v1.4.0
• "espree" (через espree) Впервые доступно в v2.2.0
• "meriyah" (через meriyah) Впервые доступно в v2.2.0
• "acorn" (через acorn) Впервые доступно в v2.6.0
• "css" (через postcss) Впервые доступно в v1.7.1
• "scss" (через postcss-scss) Впервые доступно в v1.7.1
• "less" (через postcss-less) Впервые доступно в v1.7.1
• "json" (через @babel/parser parseExpression) Впервые доступно в v1.5.0
• "json5" (тот же парсер, что и "json", но с выводом в формате json5) Впервые доступно в v1.13.0
• "jsonc" (тот же парсер, что и "json", но с выводом в формате «JSON с комментариями») Впервые доступно в v3.2.0
• "json-stringify" (тот же парсер, что и "json", но с выводом в формате JSON.stringify) Впервые доступно в v1.13.0
• "graphql" (через graphql/language) Впервые доступно в v1.5.0
• "markdown" (через remark-parse) Впервые доступно в v1.8.0
• "mdx" (через remark-parse и @mdx-js/mdx) Впервые доступно в v1.15.0
• "html" (через angular-html-parser) Впервые доступно в 1.15.0
• "vue" (тот же парсер, что и "html", но также форматирует синтаксис, специфичный для Vue) Впервые доступно в 1.10.0
• "angular" (тот же парсер, что и "html", но также форматирует синтаксис, специфичный для Angular, с помощью angular-estree-parser) Впервые доступно в 1.15.0
• "lwc" (тот же парсер, что и "html", но также форматирует синтаксис, специфичный для LWC, для не заключённых в кавычки атрибутов шаблонов) Впервые доступно в 1.17.0
• "mjml" (тот же парсер, что и "html", но также форматирует синтаксис, специфичный для MJML) Впервые доступно в 3.6.0
• "yaml" (через yaml и yaml-unist-parser) Впервые доступно в 1.14.0

Примечание: до v1.13.0 значением по умолчанию было "babylon".

Примечание: API пользовательских парсеров удалён в v3.0.0. Вместо него используйте плагины (инструкция по миграции).

Путь к файлу

Задаёт имя файла, по которому определяется используемый парсер.

Например, в следующем случае будет использоваться парсер CSS:

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

Этот параметр полезен только в CLI и API. Использовать его в файле конфигурации не имеет смысла.

Требовать прагму

Впервые доступно в v1.7.0

Prettier может форматировать только файлы, содержащие в начале специальный комментарий, называемый прагмой. Это очень удобно при постепенном переходе на Prettier в больших, неформатированных кодовых базах.

Файл, первым комментарием которого является следующая запись, будет отформатирован при указании --require-pragma:

/**
 * @prettier
 */

или

/**
 * @format
 */

Добавлять прагму

Впервые доступно в v1.8.0

Prettier может добавлять в начало файлов специальный маркер @format, указывающий, что файл отформатирован с помощью Prettier. Этот параметр удобно использовать вместе с параметром --require-pragma. Если в начале файла уже есть блок документации, этот параметр добавит в него перевод строки и маркер @format.

Обратите внимание: «вместе» не означает «одновременно». При одновременном использовании этих параметров приоритет имеет --require-pragma, поэтому --insert-pragma игнорируется. Идея заключается в том, что при постепенном внедрении Prettier в большую кодовую базу разработчики, участвующие в переходе, используют --insert-pragma, а остальные члены команды и автоматизированные инструменты используют --require-pragma, чтобы обрабатывать только уже переведённые файлы. Функция вдохновлена стратегией внедрения Facebook.

Проверять прагму игнорирования

Впервые доступно в v3.6.0

Prettier позволяет отдельным файлам отказаться от форматирования, если в начале файла присутствует специальный комментарий, называемый прагмой.

Проверка этих маркеров требует небольших дополнительных затрат при форматировании, поэтому по умолчанию она отключена.

Файл, первым комментарием которого является следующая запись, не будет отформатирован при указании --check-ignore-pragma:

/**
 * @noprettier
 */

или

/**
 * @noformat
 */

Перенос текста

Впервые доступно в v1.8.2

По умолчанию Prettier не меняет переносы в тексте Markdown, поскольку некоторые сервисы используют рендерер, чувствительный к переводам строк, например комментарии GitHub и BitBucket. Чтобы Prettier переносил текст в соответствии с шириной строки, измените этот параметр на "always". Если вы хотите, чтобы Prettier размещал каждый блок текста в одной строке, полагаясь на автоматический перенос в редакторе или средстве просмотра, можно использовать "never".

Допустимые значения:

• "always" — переносить текст, если он превышает ширину строки.
• "never" — разворачивать каждый блок текста в одну строку.
• "preserve" — ничего не делать, оставлять текст без изменений. Впервые доступно в v1.9.0

Чувствительность HTML к пробелам

Впервые доступно в v1.15.0. Для Handlebars — начиная с 2.3.0

Задаёт общую чувствительность к пробелам для HTML, Vue, Angular и Handlebars. Подробнее см. в разделе Форматирование с учётом пробелов.

Допустимые значения:

• "css" — учитывать значение свойства CSS display по умолчанию. Для Handlebars обрабатывается так же, как strict.
• "strict" — пробелы (или их отсутствие) вокруг всех тегов считаются значимыми.
• "ignore" — пробелы (или их отсутствие) вокруг всех тегов считаются незначимыми.

Отступы в тегах script и style файлов Vue

Впервые доступно в v1.19.0

Определяет, нужно ли добавлять отступ к коду внутри тегов <script> и <style> в файлах Vue.

Допустимые значения:

• false — не добавлять отступы в тегах script и style файлов Vue.
• true — добавлять отступы в тегах script и style файлов Vue.

Конец строки

Впервые доступно в v1.15.0; в v2.0.0 значение по умолчанию изменено с auto на lf

По историческим причинам в текстовых файлах существуют два распространённых варианта окончания строк: \n (или LF для перевода строки) и \r\n (или CRLF для возврата каретки + перевода строки). Первый распространён в Linux и macOS, второй — в Windows. Некоторые пояснения причин этого явления можно найти в Википедии.

Когда над проектом совместно работают пользователи разных операционных систем, в общем репозитории git легко могут появиться файлы со смешанными окончаниями строк. Пользователи Windows также могут случайно изменить окончания строк в ранее сохранённом файле с LF на CRLF. Это приводит к большому git diff, из-за чего становится сложнее просматривать историю изменений файла построчно (git blame).

Если вы хотите убедиться, что в файлах репозитория git, обрабатываемых Prettier, используются только окончания строк в стиле Linux:

1. Убедитесь, что для параметра endOfLine в Prettier задано значение lf (с v2.0.0 это значение используется по умолчанию).
2. Настройте перехватчик pre-commit, который будет запускать Prettier.
3. Настройте запуск Prettier в конвейере CI с помощью флага --check. Если вы используете Travis CI, установите для параметра autocrlf значение input в .travis.yml.
4. Добавьте * text=auto eol=lf в файл .gitattributes репозитория. Возможно, пользователям Windows потребуется заново клонировать репозиторий после этого изменения, чтобы убедиться, что git не преобразовал LF в CRLF при получении файлов.

Все современные текстовые редакторы во всех операционных системах правильно отображают окончания строк при использовании \n (LF). Однако старые версии Блокнота Windows будут визуально сливать такие строки в одну, поскольку они могут обрабатывать только \r\n (CRLF).

Допустимые значения:

• "lf" – Только перевод строки (\n), распространённый в Linux и macOS, а также в репозиториях git
• "crlf" - Символы возврата каретки и перевода строки (\r\n), распространённые в Windows
• "cr" - Только символ возврата каретки (\r), используется очень редко
• "auto" - Сохранять существующие окончания строк (смешанные значения в одном файле нормализуются с учётом значения, использованного после первой строки)

Задание end_of_line в файле .editorconfig настроит используемый Prettier символ окончания строки, если это значение не переопределено.

Форматирование встроенного языка

Впервые доступно в версии 2.1.0

Управляет форматированием Prettier фрагментов кода в кавычках, встроенных в файл.

Если Prettier обнаруживает случаи, когда в строку другого файла, например в шаблонный литерал с тегом html в JavaScript или в блок кода Markdown, помещён код, который он умеет форматировать, по умолчанию он попытается отформатировать этот код.

Иногда такое поведение нежелательно, особенно если вы не собирались использовать строку как код. Этот параметр позволяет переключаться между поведением по умолчанию (auto) и полным отключением этой функции (off).

Допустимые значения:

• "auto" – Форматировать встроенный код, если Prettier может автоматически его определить.
• "off" - Никогда не форматировать встроенный код автоматически.

Один атрибут на строку

Впервые доступно в версии 2.6.0

Размещать каждый атрибут HTML, Vue и JSX на отдельной строке.

Допустимые значения:

• false - Не размещать каждый атрибут на отдельной строке.
• true - Размещать каждый атрибут на отдельной строке.