Prettier is an opinionated JavaScript formatter. This document gives a rationale behind those opinions.
Prettier exists for one purpose: to enforce consistency across your entire project. Not only do we output code with consistent whitespace, prettier will lay out code according to a wrapping algorithm based on a maximum line width. That means that long expressions will be broken up across lines, removing the need for manual layout from the programmer which inevitably leads to inconsistency.
The first requirement of prettier is to output valid JavaScript and code that has the exact same behavior as before formatting. Please report any JavaScript code where prettier fails to follow these correctness rules — that's a bug which needs to be fixed!
This is the core of prettier. The formatting rules are going to be explained in a later section.
...TBD...
Prettier enforces double quotes by default, but has a setting for enforcing single quotes instead. There are two exceptions:
- The number of escaped quotes are minimized. For example, if you have a string with a single quote inside, it will be enclosed in double quotes regardless of the quote setting:
"that's a double quote", not'that\'s a double quote'. - JSX always uses double quotes. JSX takes its roots from HTML, where the dominant use of quotes for attributes is double quotes. Browser developer tools also follow this convention by always displaying HTML with double quotes, even if the source code uses single quotes.
Prettier maintains the way your string is escaped. For example, "🙂" won't be formatted into "\uD83D\uDE42" and vice versa.
Prettier outputs the minimum number of parentheses required to ensure that the behavior of the formatted code stays unchanged. This may lead to code that feels ambiguous. If that's the case, you are encouraged to extract the ambiguous parts into variables.
It turns out that empty lines are very hard to automatically generate. The approach that prettier takes is to preserve empty lines the way they were in the original source code. The only constraint is that prettier disallows several empty lines in a row. They are collapsed to a single one.
It is tempting to collapse an object to a single line if it fits, but there are times when it is better for sibling/cousin keys to stay vertically aligned—see object lists, nested configs, stylesheets, and keyed methods. To avoid unfavorable collapsing, prettier simply formats any object as multi-line if it appears as such in the original source code. This is the same strategy used by elm-format for multi-line records.
Here are a few examples of things that are out of scope for prettier:
- Turning single/double quotes into template literals or vice versa.
- Adding/removing
{}andreturnwhere they are optional. - Turning
?:intoif then else.
... TBD ...