Skip to content

Latest commit

 

History

History
602 lines (393 loc) · 30.1 KB

options.md

File metadata and controls

602 lines (393 loc) · 30.1 KB
id title
options
Options

Prettier ships with a handful of format options.

To learn more about Prettier’s stance on options – see the Option Philosophy.

If you change any options, it’s recommended to do it via a configuration file. This way the Prettier CLI, editor integrations and other tooling knows what options you use.

Print Width

Specify the line length that the printer will wrap on.

For readability we recommend against using more than 80 characters:

In code styleguides, maximum line length rules are often set to 100 or 120. However, when humans write code, they don’t strive to reach the maximum number of columns on every line. Developers often use whitespace to break up long lines for readability. In practice, the average line length often ends up well below the maximum.

Prettier’s printWidth option does not work the same way. It is not the hard upper allowed line length limit. It is a way to say to Prettier roughly how long you’d like lines to be. Prettier will make both shorter and longer lines, but generally strive to meet the specified printWidth.

Remember, computers are dumb. You need to explicitly tell them what to do, while humans can make their own (implicit) judgements, for example on when to break a line.

In other words, don’t try to use printWidth as if it was ESLint’s max-len – they’re not the same. max-len just says what the maximum allowed line length is, but not what the generally preferred length is – which is what printWidth specifies.

Default CLI Override API Override
80 --print-width <int> printWidth: <int>

(If you don’t want line wrapping when formatting Markdown, you can set the Prose Wrap option to disable it.)

Tab Width

Specify the number of spaces per indentation-level.

Default CLI Override API Override
2 --tab-width <int> tabWidth: <int>

Tabs

Indent lines with tabs instead of spaces.

Default CLI Override API Override
false --use-tabs useTabs: <bool>

(Tabs will be used for indentation but Prettier uses spaces to align things, such as in ternaries.)

Semicolons

Print semicolons at the ends of statements.

Valid options:

  • true - Add a semicolon at the end of every statement.
  • false - Only add semicolons at the beginning of lines that may introduce ASI failures.
Default CLI Override API Override
true --no-semi semi: <bool>

Indent chains

Put or disable indents at the start of chained calls.

Valid options:

  • true - Put indents at the start of chained calls.
  • false - Disable indents at the start of chained calls.
Default CLI Override API Override
true --no-indent-chains indentChains: <bool>

Quotes

Use single quotes instead of double quotes.

Notes:

  • JSX quotes ignore this option – see jsx-single-quote.
  • If the number of quotes outweighs the other quote, the quote which is less used will be used to format the string - Example: "I'm double quoted" results in "I'm double quoted" and "This \"example\" is single quoted" results in 'This "example" is single quoted'.

See the strings rationale for more information.

Default CLI Override API Override
false --single-quote singleQuote: <bool>

Quote Props

Change when properties in objects are quoted.

Valid options:

  • "as-needed" - Only add quotes around object properties where required.
  • "consistent" - If at least one property in an object requires quotes, quote all properties.
  • "preserve" - Respect the input use of quotes in object properties.
Default CLI Override API Override
"as-needed" --quote-props <as-needed|consistent|preserve> quoteProps: "<as-needed|consistent|preserve>"

Note that Prettier never unquotes numeric property names in Angular expressions, TypeScript, and Flow because the distinction between string and numeric keys is significant in these languages. See: Angular, TypeScript, Flow. Also Prettier doesn’t unquote numeric properties for Vue (see the issue about that).

If this option is set to preserve, singleQuote to false (default value), and parser to json5, double quotes are always used for strings. This effectively allows using the json5 parser for “JSON with comments and trailing commas”.

JSX Quotes

Use single quotes instead of double quotes in JSX.

Default CLI Override API Override
false --jsx-single-quote jsxSingleQuote: <bool>

Trailing Commas

Default value changed from none to es5 in v2.0.0

Print trailing commas wherever possible in multi-line comma-separated syntactic structures. (A single-line array, for example, never gets trailing commas.)

Valid options:

  • "es5" - Trailing commas where valid in ES5 (objects, arrays, etc.). No trailing commas in type parameters in TypeScript.
  • "none" - No trailing commas.
  • "all" - Trailing commas wherever possible (including function parameters and calls). To run, JavaScript code formatted this way needs an engine that supports ES2017 (Node.js 8+ or a modern browser) or downlevel compilation. This also enables trailing commas in type parameters in TypeScript (supported since TypeScript 2.7 released in January 2018).
Default CLI Override API Override
"es5" --trailing-comma <es5|none|all> trailingComma: "<es5|none|all>"

Object curly spacing

Put or disable spaces between object curly braces (similar to the corresponding eslint option).

Valid options:

  • true - Example: { foo: bar }.
  • false - Example: {foo: bar}.
Default CLI Override API Override
true --no-object-curly-spacing objectCurlySpacing: <bool>

JSX Brackets

Put the > of a multi-line JSX element at the end of the last line instead of being alone on the next line (does not apply to self closing elements).

Valid options:

  • true - Example:
<button
  className="prettier-class"
  id="prettier-id"
  onClick={this.handleClick}>
  Click Here
</button>
  • false - Example:
<button
  className="prettier-class"
  id="prettier-id"
  onClick={this.handleClick}
>
  Click Here
</button>
Default CLI Override API Override
false --jsx-bracket-same-line jsxBracketSameLine: <bool>

Arrow Function Parentheses

First available in v1.9.0, default value changed from avoid to always in v2.0.0

Include parentheses around a sole arrow function parameter.

Valid options:

  • "always" - Always include parens. Example: (x) => x
  • "avoid" - Omit parens when possible. Example: x => x
Default CLI Override API Override
"always" --arrow-parens <always|avoid> arrowParens: "<always|avoid>"

At first glance, avoiding parentheses may look like a better choice because of less visual noise. However, when Prettier removes parentheses, it becomes harder to add type annotations, extra arguments or default values as well as making other changes. Consistent use of parentheses provides a better developer experience when editing real codebases, which justifies the default value for the option.

Range

Format only a segment of a file.

These two options can be used to format code starting and ending at a given character offset (inclusive and exclusive, respectively). The range will extend:

  • Backwards to the start of the first line containing the selected statement.
  • Forwards to the end of the selected statement.

These options cannot be used with cursorOffset.

Default CLI Override API Override
0 --range-start <int> rangeStart: <int>
Infinity --range-end <int> rangeEnd: <int>

Align object properties

Align colons in multiline object literals (not applied with any of the JSON parsers).

Default CLI Override API Override
false --align-object-properties alignObjectProperties: <bool>

break long method chains

Break method chains with more than 3 method calls, like Prettier 1.x.

Default CLI Override API Override
false --break-long-method-chains breakLongMethodChains: <bool>

Space before function parentheses

Put a space before function parenthesis in all declarations (similar to the corresponding eslint option). (Default is to put a space before function parenthesis for untyped anonymous functions only.)

Default CLI Override API Override
false --space-before-function-paren spaceBeforeFunctionParen: <bool>

Generator star spacing

Put spaces around the star (*) in generator functions (before and after - similar to the corresponding eslint option). (Default is after only.)

Default CLI Override API Override
false --generator-star-spacing generatorStarSpacing: <bool>

Yield star spacing

Put spaces around the star (*) in yield* expressions (before and after - similar to the corresponding eslint option). (Default is after only.)

Default CLI Override API Override
false --yield-star-spacing yieldStarSpacing: <bool>

break before else

Always add a line break before else.

Default CLI Override API Override
false --break-before-else breakBeforeElse: <bool>

Formatting of import statements

Formatting of import statements, may be oneline to avoid conflict with VSCode "Organize Imports" feature.

Valid options:

  • "auto" - automatic formatting, like Prettier
  • "oneline" - keep import statements on one line
Default CLI Override API Override
"auto" --import-formatting <auto|oneline> importFormatting: "<auto|oneline>"

HTML void element tags

Format void HTML elements as void tags.

Default CLI Override API Override
false --html-void-tags htmlVoidTags: <bool>

Array bracket spacing

Put spaces between array brackets (similar to the corresponding eslint option). Status: experimental, with limited testing.

Default CLI Override API Override
false --array-bracket-spacing arrayBracketSpacing: <bool>

CSS paren spacing

Put spaces between parens in CSS, WordPress style. Status: experimental, with limited testing.

Default CLI Override API Override
false --css-paren-spacing cssParenSpacing: <bool>

Computed property spacing

Put spaces between computed property brackets (similar to the corresponding eslint option). Status: experimental, with limited testing.

Default CLI Override API Override
false --computed-property-spacing computedPropertySpacing: <bool>

Offset ternary expressions

Indent and align ternary expression branches more consistently with "Standard JS" (similar to the corresponding eslint option).

Default CLI Override API Override
false --offset-ternary-expressions offsetTernaryExpressions: <bool>

Space after unary operator symbols

Put spaces after unary operator symbols, except in the middle of !! (similar to the corresponding eslint option). Status: experimental, with limited testing.

Default CLI Override API Override
false --space-unary-ops spaceUnaryOps: <bool>

Spaces in parens

Print spaces in between parens, WordPress style (similar to the corresponding eslint option). Not recommended in combination with the default arrowParens: "always" option. Status: experimental, with limited testing.

Default CLI Override API Override
false --space-in-parens spaceInParens: <bool>

Template curly spacing

Put spaces between template curly brackets (similar to the corresponding eslint option). Status: experimental, with limited testing.

Default CLI Override API Override
false --template-curly-spacing templateCurlySpacing: <bool>

Type angle bracket spacing

Put spaces between type angle brackets. Status: experimental, with limited testing.

Default CLI Override API Override
false --type-angle-bracket-spacing typeAngleBracketSpacing: <bool>

Type bracket spacing

Put spaces between type brackets. Status: experimental, with limited testing.

Default CLI Override API Override
false --type-bracket-spacing typeBracketSpacing: <bool>

export curly spacing

Put or disable spaces between export curly braces.

Default CLI Override API Override
true --no-export-curly-spacing exportCurlySpacing: <bool>

import curly spacing

Put or disable spaces between import curly braces.

Default CLI Override API Override
true --no-import-curly-spacing importCurlySpacing: <bool>

GraphQL curly spacing

Put or disable spaces between curly braces for GraphQL.

Default CLI Override API Override
true --no-graphql-curly-spacing graphqlCurlySpacing: <bool>

YAML curly spacing

Put or disable spaces between brackets / curly braces for YAML.

Default CLI Override API Override
true --no-yaml-bracket-spacing yamlBracketSpacing: <bool>

Type curly spacing

Put or disable spaces between type curly braces.

Default CLI Override API Override
true --no-type-curly-spacing typeCurlySpacing: <bool>

Parser

Specify which parser to use.

Prettier automatically infers the parser from the input file path, so you shouldn’t have to change this setting.

Both the babel and flow parsers support the same set of JavaScript features (including Flow type annotations). They might differ in some edge cases, so if you run into one of those you can try flow instead of babel. Almost the same applies to typescript and babel-ts. babel-ts might support JavaScript features (proposals) not yet supported by TypeScript, but it’s less permissive when it comes to invalid code and less battle-tested than the typescript parser.

Valid options:

  • "babel" (via @babel/parser) Named "babylon" until v1.16.0
  • "babel-flow" (same as "babel" but enables Flow parsing explicitly to avoid ambiguity) First available in v1.16.0
  • "babel-ts" (similar to "typescript" but uses Babel and its TypeScript plugin) First available in v2.0.0
  • "flow" (via flow-parser)
  • "typescript" (via @typescript-eslint/typescript-estree) First available in v1.4.0
  • "espree" (via espree) First available in v2.2.0
  • "meriyah" (via meriyah) First available in v2.2.0
  • "css" (via postcss) First available in v1.7.1
  • "scss" (via postcss-scss) First available in v1.7.1
  • "less" (via postcss-less First available in v1.7.1
  • "json" (via @babel/parser parseExpression) First available in v1.5.0
  • "json5" (same parser as "json", but outputs as json5) First available in v1.13.0
  • "json-stringify" (same parser as "json", but outputs like JSON.stringify) First available in v1.13.0
  • "graphql" (via graphql/language) First available in v1.5.0
  • "markdown" (via remark-parse) First available in v1.8.0
  • "mdx" (via remark-parse and @mdx-js/mdx) First available in v1.15.0
  • "html" (via angular-html-parser) First available in 1.15.0
  • "vue" (same parser as "html", but also formats vue-specific syntax) First available in 1.10.0
  • "angular" (same parser as "html", but also formats angular-specific syntax via angular-estree-parser) First available in 1.15.0
  • "lwc" (same parser as "html", but also formats LWC-specific syntax for unquoted template attributes) First available in 1.17.0
  • "yaml" (via yaml and yaml-unist-parser) First available in 1.14.0

Custom parsers are also supported. First available in v1.5.0

Default CLI Override API Override
None --parser <string>
--parser ./my-parser
parser: "<string>"
parser: require("./my-parser")

Note: the default value was "babylon" until v1.13.0.

File Path

Specify the file name to use to infer which parser to use.

For example, the following will use the CSS parser:

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

This option is only useful in the CLI and API. It doesn’t make sense to use it in a configuration file.

Default CLI Override API Override
None --stdin-filepath <string> filepath: "<string>"

Require Pragma

First available in v1.7.0

Prettier can restrict itself to only format files that contain a special comment, called a pragma, at the top of the file. This is very useful when gradually transitioning large, unformatted codebases to Prettier.

A file with the following as its first comment will be formatted when --require-pragma is supplied:

/**
 * @prettier
 */

or

/**
 * @format
 */
Default CLI Override API Override
false --require-pragma requirePragma: <bool>

Insert Pragma

First available in v1.8.0

Prettier can insert a special @format marker at the top of files specifying that the file has been formatted with Prettier. This works well when used in tandem with the --require-pragma option. If there is already a docblock at the top of the file then this option will add a newline to it with the @format marker.

Note that “in tandem” doesn’t mean “at the same time”. When the two options are used simultaneously, --require-pragma has priority, so --insert-pragma is ignored. The idea is that during an incremental adoption of Prettier in a big codebase, the developers participating in the transition process use --insert-pragma whereas --require-pragma is used by the rest of the team and automated tooling to process only files already transitioned. The feature has been inspired by Facebook’s adoption strategy.

Default CLI Override API Override
false --insert-pragma insertPragma: <bool>

Prose Wrap

First available in v1.8.2

By default, Prettier will wrap markdown text as-is since some services use a linebreak-sensitive renderer, e.g. GitHub comment and BitBucket. In some cases you may want to rely on editor/viewer soft wrapping instead, so this option allows you to opt out with "never".

Valid options:

  • "always" - Wrap prose if it exceeds the print width.
  • "never" - Do not wrap prose.
  • "preserve" - Wrap prose as-is. First available in v1.9.0
Default CLI Override API Override
"preserve" --prose-wrap <always|never|preserve> proseWrap: "<always|never|preserve>"

HTML Whitespace Sensitivity

First available in v1.15.0. First available for Handlebars in 2.3.0

Specify the global whitespace sensitivity for HTML, Vue, Angular, and Handlebars. See whitespace-sensitive formatting for more info.

Valid options:

  • "css" - Respect the default value of CSS display property. For Handlebars treated same as strict.
  • "strict" - Whitespace (or the lack of it) around all tags is considered significant.
  • "ignore" - Whitespace (or the lack of it) around all tags is considered insignificant.
Default CLI Override API Override
"css" --html-whitespace-sensitivity <css|strict|ignore> htmlWhitespaceSensitivity: "<css|strict|ignore>"

Vue files script and style tags indentation

First available in v1.19.0

Whether or not to indent the code inside <script> and <style> tags in Vue files. Some people (like the creator of Vue) don’t indent to save an indentation level, but this might break code folding in your editor.

Valid options:

  • "false" - Do not indent script and style tags in Vue files.
  • "true" - Indent script and style tags in Vue files.
Default CLI Override API Override
false --vue-indent-script-and-style vueIndentScriptAndStyle: <bool>

End of Line

First available in v1.15.0, default value changed from auto to lf in v2.0.0

For historical reasons, there exist two common flavors of line endings in text files. That is \n (or LF for Line Feed) and \r\n (or CRLF for Carriage Return + Line Feed). The former is common on Linux and macOS, while the latter is prevalent on Windows. Some details explaining why it is so can be found on Wikipedia.

When people collaborate on a project from different operating systems, it becomes easy to end up with mixed line endings in a shared git repository. It is also possible for Windows users to accidentally change line endings in a previously committed file from LF to CRLF. Doing so produces a large git diff and thus makes the line-by-line history for a file (git blame) harder to explore.

If you want to make sure that your entire git repository only contains Linux-style line endings in files covered by Prettier:

  1. Ensure Prettier’s endOfLine option is set to lf (this is a default value since v2.0.0)
  2. Configure a pre-commit hook that will run Prettier
  3. Configure Prettier to run in your CI pipeline using --check flag. If you use Travis CI, set the autocrlf option to input in .travis.yml.
  4. Add * text=auto eol=lf to the repo’s .gitattributes file. You may need to ask Windows users to re-clone your repo after this change to ensure git has not converted LF to CRLF on checkout.

All modern text editors in all operating systems are able to correctly display line endings when \n (LF) is used. However, old versions of Notepad for Windows will visually squash such lines into one as they can only deal with \r\n (CRLF).

Valid options:

  • "lf" – Line Feed only (\n), common on Linux and macOS as well as inside git repos
  • "crlf" - Carriage Return + Line Feed characters (\r\n), common on Windows
  • "cr" - Carriage Return character only (\r), used very rarely
  • "auto" - Maintain existing line endings (mixed values within one file are normalised by looking at what’s used after the first line)
Default CLI Override API Override
"lf" --end-of-line <lf|crlf|cr|auto> endOfLine: "<lf|crlf|cr|auto>"

Embedded Language Formatting

First available in v2.1.0

Control whether Prettier formats quoted code embedded in the file.

When Prettier identifies cases where it looks like you've placed some code it knows how to format within a string in another file, like in a tagged template in JavaScript with a tag named html or in code blocks in Markdown, it will by default try to format that code.

Sometimes this behavior is undesirable, particularly in cases where you might not have intended the string to be interpreted as code. This option allows you to switch between the default behavior (auto) and disabling this feature entirely (off).

Valid options:

  • "auto" – Format embedded code if Prettier can automatically identify it.
  • "off" - Never automatically format embedded code.
Default CLI Override API Override
"auto" --embedded-language-formatting=off embeddedLanguageFormatting: "off"