Improve documentation for the parser option (#5129)
- Warn about setting parser at the top level. Refs. #4638. - Remove top level parser from examples. Instead show the most common options (I also removed printWidth, since we don't recommend changing it). Refs. #4638. - Show how to configure the flow parser for .js files. Refs. #4638. - Update valid options for the parser option, including links and "since version". - Clarify babylon vs flow.master
parent
3e05f210bb
commit
dc590e5e4b
|
@ -20,8 +20,10 @@ JSON:
|
|||
|
||||
```json
|
||||
{
|
||||
"printWidth": 100,
|
||||
"parser": "flow"
|
||||
"trailingComma": "es5",
|
||||
"tabWidth": 4,
|
||||
"semi": false,
|
||||
"singleQuote": true
|
||||
}
|
||||
```
|
||||
|
||||
|
@ -30,25 +32,31 @@ JS:
|
|||
```js
|
||||
// prettier.config.js or .prettierrc.js
|
||||
module.exports = {
|
||||
printWidth: 100,
|
||||
parser: "flow"
|
||||
trailingComma: "es5",
|
||||
tabWidth: 4,
|
||||
semi: false,
|
||||
singleQuote: true
|
||||
};
|
||||
```
|
||||
|
||||
YAML:
|
||||
|
||||
```yaml
|
||||
# .prettierrc
|
||||
printWidth: 100
|
||||
parser: flow
|
||||
# .prettierrc or .prettierrc.yaml
|
||||
trailingComma: "es5"
|
||||
tabWidth: 4
|
||||
semi: false
|
||||
singleQuote: true
|
||||
```
|
||||
|
||||
TOML:
|
||||
|
||||
```toml
|
||||
# .prettierrc.toml
|
||||
printWidth = 100
|
||||
parser = "flow"
|
||||
trailingComma = "es5"
|
||||
tabWidth = 4
|
||||
semi = false
|
||||
singleQuote = true
|
||||
```
|
||||
|
||||
## Configuration Overrides
|
||||
|
@ -83,7 +91,11 @@ overrides:
|
|||
|
||||
`files` is required for each override, and may be a string or array of strings. `excludeFiles` may be optionally provided to exclude files for a given rule, and may also be a string or array of strings.
|
||||
|
||||
To get prettier to format its own `.prettierrc` file, you can do:
|
||||
## Setting the [parser](options.md#parser) option
|
||||
|
||||
By default, Prettier automatically infers which parser to use based on the input file extension. Combined with `overrides` you can teach Prettier how to parse files it does not recognize.
|
||||
|
||||
For example, to get Prettier to format its own `.prettierrc` file, you can do:
|
||||
|
||||
```json
|
||||
{
|
||||
|
@ -96,7 +108,22 @@ To get prettier to format its own `.prettierrc` file, you can do:
|
|||
}
|
||||
```
|
||||
|
||||
For more information on how to use the CLI to locate a file, see the [CLI](cli.md) section.
|
||||
You can also switch to the `flow` parser instead of the default `babylon` for .js files:
|
||||
|
||||
```json
|
||||
{
|
||||
"overrides": [
|
||||
{
|
||||
"files": "*.js",
|
||||
"options": {
|
||||
"parser": "flow"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** _Never_ put the `parser` option at the top level of your configuration. _Only_ use it inside `overrides`. Otherwise you effectively disable Prettier's automatic file extension based parser inference. This forces Prettier to use the parser you specified for _all_ types of files – even when it doesn't make sense, such as trying to parse a CSS file as JavaScript.
|
||||
|
||||
## Configuration Schema
|
||||
|
||||
|
|
|
@ -160,17 +160,29 @@ These options cannot be used with `cursorOffset`.
|
|||
|
||||
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.
|
||||
Prettier automatically infers the parser from the input file path, so you shouldn't have to change this setting.
|
||||
|
||||
Built-in parsers:
|
||||
Both the `babylon` 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 `babylon`.
|
||||
|
||||
- [`babylon`](https://github.com/babel/babel/tree/master/packages/babylon)
|
||||
- [`flow`](https://github.com/facebook/flow/tree/master/src/parser)
|
||||
- [`typescript`](https://github.com/JamesHenry/typescript-estree) _Since v1.4.0_
|
||||
- [`postcss`](https://github.com/postcss/postcss) _Since v1.4.0_
|
||||
- [`json`](https://github.com/babel/babylon/tree/f09eb3200f57ea94d51c2a5b1facf2149fb406bf#babylonparseexpressioncode-options) _Since v1.5.0_
|
||||
- [`graphql`](https://github.com/graphql/graphql-js/tree/master/src/language) _Since v1.5.0_
|
||||
- [`markdown`](https://github.com/wooorm/remark/tree/master/packages/remark-parse) _Since v1.8.0_
|
||||
Valid options:
|
||||
|
||||
- `"babylon"` (via [@babel/parser](https://github.com/babel/babel/tree/master/packages/babel-parser))
|
||||
- `"flow"` (via [flow-parser](https://github.com/facebook/flow/tree/master/src/parser))
|
||||
- `"typescript"` (via [typescript-estree](https://github.com/JamesHenry/typescript-estree)) _Since v1.4.0_
|
||||
- `"css"` (via [postcss-scss](https://github.com/postcss/postcss-scss) and [postcss-less](https://github.com/shellscape/postcss-less), autodetects which to use) _Since v1.7.1_
|
||||
- `"scss"` (same parsers as `"css"`, prefers postcss-scss) _Since v1.7.1_
|
||||
- `"less"` (same parsers as `"css"`, prefers postcss-less) _Since v1.7.1_
|
||||
- `"json"` (via [@babel/parser parseExpression](https://babeljs.io/docs/en/next/babel-parser.html#babelparserparseexpressioncode-options)) _Since v1.5.0_
|
||||
- `"json5"` (same parser as `"json"`, but outputs as [json5](https://json5.org/)) _Since v1.13.0_
|
||||
- `"json-stringify"` (same parser as `"json"`, but outputs like `JSON.stringify`) _Since v1.13.0_
|
||||
- `"graphql"` (via [graphql/language](https://github.com/graphql/graphql-js/tree/master/src/language)) _Since v1.5.0_
|
||||
- `"markdown"` (via [remark-parse](https://github.com/wooorm/remark/tree/master/packages/remark-parse)) _Since v1.8.0_
|
||||
- `"vue"` (uses several parsers) _Since 1.10.0_
|
||||
- `"yaml"` (via [yaml](https://github.com/eemeli/yaml) and [yaml-unist-parser](https://github.com/ikatyang/yaml-unist-parser)) _Since 1.14.0_
|
||||
|
||||
<!-- TODO: Uncomment and move below "markdown" above when 1.15.0 is released.
|
||||
- `"mdx"` (same parser as `"markdown"`, with some custom overrides) _Since 1.15.0_
|
||||
-->
|
||||
|
||||
[Custom parsers](api.md#custom-parser-api) are also supported. _Since v1.5.0_
|
||||
|
||||
|
@ -184,7 +196,7 @@ Note: the default value was `"babylon"` until v1.13.0.
|
|||
|
||||
Specify the input filepath. This will be used to do parser inference.
|
||||
|
||||
For example, the following will use `postcss` parser:
|
||||
For example, the following will use the CSS parser:
|
||||
|
||||
```bash
|
||||
cat foo | prettier --stdin-filepath foo.css
|
||||
|
|
|
@ -45,7 +45,7 @@ See `:help autocmd-events` in Vim for details.
|
|||
If your project requires settings other than the default Prettier settings, you can pass arguments to do so in your `.vimrc` or [vim project](http://vim.wikia.com/wiki/Project_specific_settings), you can do so:
|
||||
|
||||
```
|
||||
autocmd FileType javascript setlocal formatprg=prettier\ --stdin\ --parser\ flow\ --single-quote\ --trailing-comma\ es5
|
||||
autocmd FileType javascript setlocal formatprg=prettier\ --stdin\ --single-quote\ --trailing-comma\ es5
|
||||
" Use formatprg when available
|
||||
let g:neoformat_try_formatprg = 1
|
||||
```
|
||||
|
|
Loading…
Reference in New Issue