Will Binns-Smith
d5e5d66407
* Add option to require @prettier or @format pragma Fixes #2397. Inspired by `eslint-plugin-prettier` and the discussion in #2397, this implements requiring a special comment pragma to be present in a file's first comment in order to be formatted. This will help large codebases gradually transition to prettier over time without tons of churn or large code reviews. I implemented this as a standard prettier "option", not just a typical `argv` flag, as it is relevant in both the cli and the api. This way it can be provided programmatically, on the command line, or standardized in a prettierrc file so like the style options, every user can use this setting consistently and only apply prettier to relevant files, no mattier their editor integration. This requires the pragma begin with `@` (in fact it's inserted if the user doesn't provide it). Currently the usage implies it must be "prettier" or "format", but it can technically be any value other than "none", which is similar to the `trailingCommas` option. cc @vjeux * Don't quote anything in runPrettier; this is usually handled by a shell * Make --require-pragma a boolean option * Use jest-docblock to find pragmas without parsing the ast * Clarify docs * includes -> indexOf * Move test out of integration
5.3 KiB
id, title
| id | title |
|---|---|
| options | Options |
Prettier ships with a handful of customizable format options, usable in both the CLI and API.
Print Width
Specify the length of line that the printer will wrap on.
We strongly recommend against using more than 80 columns.
Prettier works by cramming as much content as possible until it reaches the limit, which happens to work well for 80 columns but makes lines that are very crowded. When a bigger column count is used in styleguides, it usually means that code is allowed to go beyond 80 columns, but not to make every single line go there, like Prettier would do.
| Default | CLI Override | API Override |
|---|---|---|
80 |
--print-width <int> |
printWidth: <int> |
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> |
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> |
Quotes
Use single quotes instead of double quotes.
Notes:
- Quotes in JSX will always be double and ignore this setting.
- 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'.
| Default | CLI Override | API Override |
|---|---|---|
false |
--single-quote |
singleQuote: <bool> |
Trailing Commas
Print trailing commas wherever possible.
Valid options:
"none"- No trailing commas."es5"- Trailing commas where valid in ES5 (objects, arrays, etc.)"all"- Trailing commas wherever possible (function arguments). This requires node 8 or a transform.
| Default | CLI Override | API Override |
|---|---|---|
"none" |
--trailing-comma <none,es5,all> |
trailingComma: "<none,es5,all>" |
Bracket Spacing
Print spaces between brackets in object literals.
Valid options:
true- Example:{ foo: bar }.false- Example:{foo: bar}.
| Default | CLI Override | API Override |
|---|---|---|
true |
--no-bracket-spacing |
bracketSpacing: <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.
| Default | CLI Override | API Override |
|---|---|---|
false |
--jsx-bracket-same-line |
jsxBracketSameLine: <bool> |
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> |
Parser
Specify which parser to use.
Both the babylon and flow parsers support the same set of JavaScript features (including Flow). Prettier automatically infers the parser from the input file path, so you shouldn't have to change this setting.
Built-in parsers:
Custom parsers are also supported. Since v1.5.0
| Default | CLI Override | API Override |
|---|---|---|
babylon |
--parser <string> or --parser ./my-parser |
parser: "<string>" or parser: require("./my-parser") |
Filepath
Specify the input filepath. This will be used to do parser inference.
For example, the following will use postcss parser:
cat foo | prettier --stdin-filepath foo.css
| Default | CLI Override | API Override |
|---|---|---|
| None | --stdin-filepath <string> |
filepath: "<string>" |
Require pragma
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.
For example, 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 |
|---|---|---|
| None | --require-pragma |
requirePragma |