Update README.md: fixed typo, added links (#1115)
parent
d9a4efcc35
commit
cefec125f7
78
README.md
78
README.md
|
@ -6,28 +6,28 @@
|
||||||
|
|
||||||
Prettier is an opinionated JavaScript formatter inspired by
|
Prettier is an opinionated JavaScript formatter inspired by
|
||||||
[refmt](https://facebook.github.io/reason/tools.html) with advanced
|
[refmt](https://facebook.github.io/reason/tools.html) with advanced
|
||||||
support for language features from ES2017, JSX, and Flow. It removes
|
support for language features from [ES2017](https://github.com/tc39/proposals/blob/master/finished-proposals.md), [JSX](https://facebook.github.io/jsx/), and [Flow](https://flow.org/). It removes
|
||||||
all original styling and ensures that all outputted JavaScript
|
all original styling and ensures that all outputted JavaScript
|
||||||
conforms to a consistent style. (See this [blog post](http://jlongster.com/A-Prettier-Formatter))
|
conforms to a consistent style. (See this [blog post](http://jlongster.com/A-Prettier-Formatter))
|
||||||
|
|
||||||
*Warning*: This is a beta, and the format may change over time. If you
|
*Warning*: This is a **beta**, and the format may change over time. If you
|
||||||
aren't OK with the format changing, wait for a more stable version.
|
aren't OK with the format changing, wait for a more stable version.
|
||||||
|
|
||||||
This goes way beyond [eslint](http://eslint.org/) and other projects
|
This goes way beyond [ESLint](http://eslint.org/) and other projects
|
||||||
[built on it](https://github.com/feross/standard). Unlike eslint,
|
[built on it](https://github.com/feross/standard). Unlike ESLint,
|
||||||
there aren't a million configuration options and rules. But more
|
there aren't a million configuration options and rules. But more
|
||||||
importantly: **everything is fixable**. This works because prettier
|
importantly: **everything is fixable**. This works because Prettier
|
||||||
never "checks" anything; it takes JavaScript as input and outputs the
|
never "checks" anything; it takes JavaScript as input and delivers the
|
||||||
formatted JavaScript as output.
|
formatted JavaScript as output.
|
||||||
|
|
||||||
In technical terms: prettier parses your JavaScript into an AST and
|
In technical terms: Prettier parses your JavaScript into an AST (Abstract Syntax Tree) and
|
||||||
pretty-prints the AST, completely ignoring any of the original
|
pretty-prints the AST, completely ignoring any of the original
|
||||||
formatting. Say hello to completely consistent syntax!
|
formatting. Say hello to completely consistent syntax!
|
||||||
|
|
||||||
There's an extremely important piece missing from existing styling
|
There's an extremely important piece missing from existing styling
|
||||||
tools: **the maximum line length**. Sure, you can tell eslint to warn
|
tools: **the maximum line length**. Sure, you can tell ESLint to warn
|
||||||
you when you have a line that's too long, but that's an after-thought
|
you when you have a line that's too long, but that's an after-thought
|
||||||
(eslint *never* knows how to fix it). The maximum line length is a
|
(ESLint *never* knows how to fix it). The maximum line length is a
|
||||||
critical piece the formatter needs for laying out and wrapping code.
|
critical piece the formatter needs for laying out and wrapping code.
|
||||||
|
|
||||||
For example, take the following code:
|
For example, take the following code:
|
||||||
|
@ -107,7 +107,7 @@ npm install [-g] prettier
|
||||||
|
|
||||||
### CLI
|
### CLI
|
||||||
|
|
||||||
Run prettier through the CLI with this script. Run it without any
|
Run Prettier through the CLI with this script. Run it without any
|
||||||
arguments to see the options.
|
arguments to see the options.
|
||||||
|
|
||||||
To format a file in-place, use `--write`. While this is in beta you
|
To format a file in-place, use `--write`. While this is in beta you
|
||||||
|
@ -123,7 +123,7 @@ In practice, this may look something like:
|
||||||
prettier --single-quote --trailing-comma es5 --write "{app,__{tests,mocks}__}/**/*.js"
|
prettier --single-quote --trailing-comma es5 --write "{app,__{tests,mocks}__}/**/*.js"
|
||||||
```
|
```
|
||||||
|
|
||||||
(Don't forget the quotes around the globs! The quotes make sure that prettier
|
(Don't forget the quotes around the globs! The quotes make sure that Prettier
|
||||||
expands the globs rather than your shell, for cross-platform usage.)
|
expands the globs rather than your shell, for cross-platform usage.)
|
||||||
|
|
||||||
In the future we will have better support for formatting whole projects.
|
In the future we will have better support for formatting whole projects.
|
||||||
|
@ -212,7 +212,7 @@ prettier.format(source, {
|
||||||
});
|
});
|
||||||
```
|
```
|
||||||
|
|
||||||
`check` checks to see if the file has been formatted with prettier given the those options and returns a Boolean.
|
`check` checks to see if the file has been formatted with Prettier given those options and returns a Boolean.
|
||||||
This is similar to the `--list-different` parameter in the CLI and is useful for running Prettier in CI scenarios.
|
This is similar to the `--list-different` parameter in the CLI and is useful for running Prettier in CI scenarios.
|
||||||
|
|
||||||
### Excluding code from formatting
|
### Excluding code from formatting
|
||||||
|
@ -253,18 +253,17 @@ matrix(
|
||||||
|
|
||||||
### Atom
|
### Atom
|
||||||
|
|
||||||
Atom users can simply install the `prettier-atom` package and use
|
Atom users can simply install the [prettier-atom](https://github.com/prettier/prettier-atom) package and use
|
||||||
ctrl+alt+f to format a file (or format on save if turned on).
|
`Ctrl+Alt+F` to format a file (or format on save if enabled).
|
||||||
|
|
||||||
### Emacs
|
### Emacs
|
||||||
|
|
||||||
Emacs users should see [this
|
Emacs users should see [this directory](https://github.com/prettier/prettier/tree/master/editors/emacs)
|
||||||
folder](https://github.com/jlongster/prettier/tree/master/editors/emacs)
|
|
||||||
for on-demand formatting.
|
for on-demand formatting.
|
||||||
|
|
||||||
### Vim
|
### Vim
|
||||||
|
|
||||||
For Vim users there are two main approaches, one that leans on [sbdchd](https://github.com/sbdchd)/[neoformat](https://github.com/sbdchd/neoformat), which has the advantage of leaving the cursor in the same position despite changes, or a vanilla approach which can only approximate the cursor location, but might be good enough for your needs.
|
For Vim users, there are two main approaches: one that leans on [sbdchd](https://github.com/sbdchd)/[neoformat](https://github.com/sbdchd/neoformat), which has the advantage of leaving the cursor in the same position despite changes, or a vanilla approach which can only approximate the cursor location, but might be good enough for your needs.
|
||||||
|
|
||||||
#### Vanilla approach
|
#### Vanilla approach
|
||||||
|
|
||||||
|
@ -284,7 +283,7 @@ autocmd FileType javascript.jsx,javascript setlocal formatprg=prettier\ --stdin
|
||||||
|
|
||||||
This makes Prettier power the [`gq` command](http://vimdoc.sourceforge.net/htmldoc/change.html#gq)
|
This makes Prettier power the [`gq` command](http://vimdoc.sourceforge.net/htmldoc/change.html#gq)
|
||||||
for automatic formatting without any plugins. You can also add the following to your
|
for automatic formatting without any plugins. You can also add the following to your
|
||||||
`.vimrc` to run prettier when `.js` files are saved:
|
`.vimrc` to run Prettier when `.js` files are saved:
|
||||||
|
|
||||||
```vim
|
```vim
|
||||||
autocmd BufWritePre *.js :normal gggqG
|
autocmd BufWritePre *.js :normal gggqG
|
||||||
|
@ -312,9 +311,9 @@ Then make Neoformat run on save:
|
||||||
autocmd BufWritePre *.js Neoformat
|
autocmd BufWritePre *.js Neoformat
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Customizing prettier in Vim
|
#### Customizing Prettier in Vim
|
||||||
|
|
||||||
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:
|
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:
|
||||||
|
|
||||||
```vim
|
```vim
|
||||||
autocmd FileType javascript set formatprg=prettier\ --stdin\ --parser\ flow\ --single-quote\ --trailing-comma\ es5
|
autocmd FileType javascript set formatprg=prettier\ --stdin\ --parser\ flow\ --single-quote\ --trailing-comma\ es5
|
||||||
|
@ -329,15 +328,15 @@ let g:neoformat_try_formatprg = 1
|
||||||
|
|
||||||
### Visual Studio Code
|
### Visual Studio Code
|
||||||
|
|
||||||
Can be installed using the extension sidebar. Search for `Prettier - JavaScript formatter`
|
Can be installed using the extension sidebar. Search for `Prettier - JavaScript formatter`.
|
||||||
|
|
||||||
Can also be installed using `ext install prettier-vscode`
|
Can also be installed using `ext install prettier-vscode`.
|
||||||
|
|
||||||
[Check repository for configuration and shortcuts](https://github.com/esbenp/prettier-vscode)
|
[Check its repository for configuration and shortcuts](https://github.com/esbenp/prettier-vscode)
|
||||||
|
|
||||||
### Visual Studio
|
### Visual Studio
|
||||||
|
|
||||||
Install the [JavaScript Prettier extension](https://github.com/madskristensen/JavaScriptPrettier)
|
Install the [JavaScript Prettier extension](https://github.com/madskristensen/JavaScriptPrettier).
|
||||||
|
|
||||||
### Sublime Text
|
### Sublime Text
|
||||||
|
|
||||||
|
@ -346,8 +345,8 @@ the [JsPrettier](https://packagecontrol.io/packages/JsPrettier) plug-in.
|
||||||
|
|
||||||
### JetBrains
|
### JetBrains
|
||||||
|
|
||||||
JetBrains users can configure `prettier` as an **External Tool** see [this
|
JetBrains users can configure `prettier` as an **External Tool**.
|
||||||
blog post](https://blog.jetbrains.com/webstorm/2016/08/using-external-tools/) or [this
|
See [this blog post](https://blog.jetbrains.com/webstorm/2016/08/using-external-tools/) or [this
|
||||||
directory](https://github.com/jlongster/prettier/tree/master/editors/jetbrains) with examples.
|
directory](https://github.com/jlongster/prettier/tree/master/editors/jetbrains) with examples.
|
||||||
|
|
||||||
More editors are coming soon.
|
More editors are coming soon.
|
||||||
|
@ -356,9 +355,9 @@ More editors are coming soon.
|
||||||
|
|
||||||
Prettier attempts to support all JavaScript language features,
|
Prettier attempts to support all JavaScript language features,
|
||||||
including non-standardized ones. By default it uses the
|
including non-standardized ones. By default it uses the
|
||||||
[babylon](https://github.com/babel/babylon) parser with all language
|
[Babylon](https://github.com/babel/babylon) parser with all language
|
||||||
features enabled, but you can also use
|
features enabled, but you can also use the
|
||||||
[flow](https://github.com/facebook/flow) parser with the
|
[Flow](https://github.com/facebook/flow) parser with the
|
||||||
`parser` API or `--parser` CLI option.
|
`parser` API or `--parser` CLI option.
|
||||||
|
|
||||||
All of JSX and Flow syntax is supported. In fact, the test suite in
|
All of JSX and Flow syntax is supported. In fact, the test suite in
|
||||||
|
@ -366,8 +365,8 @@ All of JSX and Flow syntax is supported. In fact, the test suite in
|
||||||
|
|
||||||
## Related Projects
|
## Related Projects
|
||||||
|
|
||||||
- [`eslint-plugin-prettier`](https://github.com/not-an-aardvark/eslint-plugin-prettier) plugs prettier into your ESLint workflow
|
- [`eslint-plugin-prettier`](https://github.com/not-an-aardvark/eslint-plugin-prettier) plugs Prettier into your ESLint workflow
|
||||||
- [`eslint-config-prettier`](https://github.com/prettier/eslint-config-prettier) turns off all ESLint rules that are unnecessary or might conflict with prettier
|
- [`eslint-config-prettier`](https://github.com/prettier/eslint-config-prettier) turns off all ESLint rules that are unnecessary or might conflict with Prettier
|
||||||
- [`prettier-eslint`](https://github.com/prettier/prettier-eslint)
|
- [`prettier-eslint`](https://github.com/prettier/prettier-eslint)
|
||||||
passes `prettier` output to `eslint --fix`
|
passes `prettier` output to `eslint --fix`
|
||||||
- [`prettier-standard`](https://github.com/sheerun/prettier-standard)
|
- [`prettier-standard`](https://github.com/sheerun/prettier-standard)
|
||||||
|
@ -376,7 +375,7 @@ uses `prettier` and `prettier-eslint` to format code with standard rules
|
||||||
passes `prettier` output to `standard --fix`
|
passes `prettier` output to `standard --fix`
|
||||||
- [`prettier-with-tabs`](https://github.com/arijs/prettier-with-tabs)
|
- [`prettier-with-tabs`](https://github.com/arijs/prettier-with-tabs)
|
||||||
allows you to configure prettier to use `tabs`
|
allows you to configure prettier to use `tabs`
|
||||||
- [`neutrino-preset-prettier`](https://github.com/SpencerCDixon/neutrino-preset-prettier) allows you to use prettier as a neutrino preset
|
- [`neutrino-preset-prettier`](https://github.com/SpencerCDixon/neutrino-preset-prettier) allows you to use Prettier as a Neutrino preset
|
||||||
|
|
||||||
|
|
||||||
## Technical Details
|
## Technical Details
|
||||||
|
@ -412,24 +411,25 @@ Show the world you're using *Prettier* → [![styled with prettier](https://img.
|
||||||
[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
|
[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
We will work on better docs over time, but in the mean time, here are
|
We will work on better docs over time, but in the mean time, here are
|
||||||
a few notes if you are interested in contributing:
|
a few notes if you are interested in contributing:
|
||||||
|
|
||||||
* You should be able to get up and running with just `yarn`
|
* You should be able to get up and running with just `yarn`.
|
||||||
* This uses jest snapshots for tests. The entire Flow test suite is
|
* This uses [Jest](https://facebook.github.io/jest/) snapshots for tests. The entire Flow test suite is
|
||||||
included here and you can make changes and run `jest -u` and then
|
included here. You can make changes and run `jest -u`, and then
|
||||||
`git diff` to see the styles that changed. Always update the
|
`git diff` to see the styles that changed. Always update the
|
||||||
snapshots if opening a PR.
|
snapshots if opening a PR.
|
||||||
* If you can, look at [commands.md](commands.md) and check out
|
* If you can, look at [commands.md](commands.md) and check out
|
||||||
[Wadler's
|
[Wadler's paper](http://homepages.inf.ed.ac.uk/wadler/papers/prettier/prettier.pdf)
|
||||||
paper](http://homepages.inf.ed.ac.uk/wadler/papers/prettier/prettier.pdf)
|
|
||||||
to understand how this works. I will try to write a better explanation soon.
|
to understand how this works. I will try to write a better explanation soon.
|
||||||
* I haven't set up any automated tests yet, but for now as long as you
|
* I haven't set up any automated tests yet, but for now as long as you
|
||||||
run `jest -u` to update the snapshots and I see them in the PR, that's fine.
|
run `jest -u` to update the snapshots and I see them in the PR, that's fine.
|
||||||
* You can run `AST_COMPARE=1 jest` for a more robust test run. That
|
* You can run `AST_COMPARE=1 jest` for a more robust test run. That
|
||||||
formats each file, re-parses it, and compares the new AST with the
|
formats each file, re-parses it, and compares the new AST with the
|
||||||
original one and makes sure they are semantically equivalent.
|
original one and makes sure they are semantically equivalent.
|
||||||
* Each test folder has a `jsfmt.spec.js` that runs the tests. Normally you can just put `run_spec(__dirname);` there but if you want to pass specific options you can add the options object as the 2nd parameter like: `run_spec(__dirname, { parser: 'babylon' });`
|
* Each test folder has a `jsfmt.spec.js` that runs the tests.
|
||||||
|
Normally you can just put `run_spec(__dirname);` there but if you want to pass
|
||||||
|
specific options, you can add the options object as the 2nd parameter like:
|
||||||
|
`run_spec(__dirname, { parser: 'babylon' });`
|
||||||
|
|
Loading…
Reference in New Issue