2017-01-16 18:08:06 +03:00
# Prettier
2016-12-23 21:38:10 +03:00
2017-01-11 20:01:02 +03:00
[![Gitter ](https://badges.gitter.im/gitterHQ/gitter.svg )](https://gitter.im/jlongster/prettier)
2017-01-16 18:08:06 +03:00
[![Build Status ](https://travis-ci.org/jlongster/prettier.svg?branch=master )](https://travis-ci.org/jlongster/prettier)
[![NPM version ](https://img.shields.io/npm/v/prettier.svg )](https://www.npmjs.com/package/prettier)
2017-01-11 20:01:02 +03:00
2017-01-10 09:02:39 +03:00
Prettier is an opinionated JavaScript formatter inspired by
2017-01-10 17:06:50 +03:00
[refmt ](https://facebook.github.io/reason/tools.html ) with advanced
support for language features from ES2017, JSX, and Flow. It removes
all original styling and ensures that all outputted JavaScript
2017-01-10 18:33:54 +03:00
conforms to a consistent style. (See this [blog post ](http://jlongster.com/A-Prettier-Formatter ))
2016-12-23 21:38:10 +03:00
2017-01-10 20:09:06 +03:00
*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.
2016-12-23 21:38:10 +03:00
2017-01-10 08:45:11 +03:00
This goes way beyond [eslint ](http://eslint.org/ ) and other projects
[built on it ](https://github.com/feross/standard ). Unlike eslint,
there aren't a million configuration options and rules. But more
importantly: **everything is fixable** . This works because prettier
never "checks" anything; it takes JavaScript as input and outputs the
formatted JavaScript as output.
2016-12-23 21:38:10 +03:00
2017-01-10 08:45:11 +03:00
In technical terms: prettier parses your JavaScript into an AST and
pretty-prints the AST, completely ignoring any of the original
formatting. Say hello to completely consistent syntax!
2016-12-23 21:38:10 +03:00
2017-01-10 08:45:11 +03:00
There's an extremely important piece missing from existing styling
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
(eslint *never* knows how to fix it). The maximum line length is a
critical piece the formatter needs for laying out and wrapping code.
2016-12-23 21:38:10 +03:00
2017-01-10 08:45:11 +03:00
For example, take the following code:
2016-12-23 21:38:10 +03:00
```js
2017-01-28 05:49:23 +03:00
foo(arg1, arg2, arg3, arg4);
2016-12-23 21:38:10 +03:00
```
2017-01-10 08:45:11 +03:00
That looks like the right way to format it. However, we've all run
into this situation:
2016-12-23 21:38:10 +03:00
```js
2017-01-10 08:45:11 +03:00
foo(reallyLongArg(), omgSoManyParameters(), IShouldRefactorThis(), isThereSeriouslyAnotherOne());
2016-12-23 21:40:43 +03:00
```
2016-12-23 21:38:10 +03:00
2017-01-10 08:45:11 +03:00
Suddenly our previous format for calling function breaks down because
this is too long. What you would probably do is this instead:
2016-12-23 21:38:10 +03:00
2017-01-11 03:26:35 +03:00
```js
2017-01-10 08:45:11 +03:00
foo(
reallyLongArg(),
omgSoManyParameters(),
IShouldRefactorThis(),
isThereSeriouslyAnotherOne()
);
```
2016-12-23 21:38:10 +03:00
2017-01-10 08:45:11 +03:00
This clearly shows that the maximum line length has a direct impact on
the style of code we desire. The fact that current style tools ignore
this means they can't really help with the situations that are
actually the most troublesome. Individuals on teams will all format
these differently according to their own rules and we lose the
consistency we sought after.
2016-12-23 21:38:10 +03:00
2017-01-10 08:45:11 +03:00
Even if we disregard line widths, it's too easy to sneak in various
styles of code in all other linters. The most strict linter I know
happily lets all these styles happen:
2016-12-23 21:38:10 +03:00
```js
2017-01-10 08:45:11 +03:00
foo({ num: 3 },
1, 2)
2016-12-23 21:38:10 +03:00
2017-01-10 08:45:11 +03:00
foo(
{ num: 3 },
1, 2)
2016-12-23 21:38:10 +03:00
2017-01-10 08:45:11 +03:00
foo(
{ num: 3 },
1,
2
)
```
2016-12-23 21:38:10 +03:00
2017-01-10 08:45:11 +03:00
Prettier bans all custom styling by parsing it away and re-printing
the parsed AST with its own rules that take the maximum line width
into account, wrapping code when necessary.
2016-12-23 21:38:10 +03:00
2017-01-10 08:52:52 +03:00
## Usage
Install:
```
2017-01-11 19:30:46 +03:00
yarn add prettier
```
You can install it globally if you like:
```
yarn global add prettier
2017-01-10 08:52:52 +03:00
```
2017-01-11 19:31:42 +03:00
*We're defaulting to `yarn` but you can use `npm` if you like:*
2017-01-11 19:30:46 +03:00
```
npm install [-g] prettier
```
2017-01-10 08:52:52 +03:00
### CLI
Run prettier through the CLI with this script. Run it without any
arguments to see the options.
2017-01-10 17:06:50 +03:00
To format a file in-place, use `--write` . While this is in beta you
2017-01-11 19:02:30 +03:00
should probably commit your code before doing that.
2017-01-10 17:06:50 +03:00
2017-01-10 08:52:52 +03:00
```js
2017-01-11 19:02:30 +03:00
prettier [opts] [filename ...]
2017-01-10 08:52:52 +03:00
```
2017-01-23 18:37:57 +03:00
For easier cross-platform usage, prettier has built-in glob support:
2017-01-11 19:02:30 +03:00
```bash
2017-01-23 18:37:57 +03:00
prettier --write 'src/**/*.js' 'bin/*.js'
2017-01-11 19:02:30 +03:00
```
In the future we will have better support for formatting whole projects.
2017-01-10 08:52:52 +03:00
### API
The API is a single function exported as `format` . The options
argument is optional, and all of the defaults are shown below:
```js
const prettier = require("prettier");
prettier.format(source, {
// Fit code within this line limit
printWidth: 80,
// Number of spaces it should use per tab
2017-01-11 13:31:59 +03:00
tabWidth: 2,
2017-01-10 08:52:52 +03:00
// If true, will use single instead of double quotes
singleQuote: false,
// Controls the printing of trailing commas wherever possible
trailingComma: false,
2017-01-31 17:54:31 +03:00
// Controls the printing of spaces inside object literals
2017-01-20 01:35:12 +03:00
bracketSpacing: true,
// Which parser to use. Valid options are 'flow' and 'babylon'
parser: 'babylon'
2017-01-10 08:52:52 +03:00
});
```
2017-01-10 09:00:02 +03:00
### Atom
Atom users can simply install the `prettier-atom` package and use
ctrl+alt+f to format a file (or format on save if turned on).
### Emacs
Emacs users should see [this
folder](https://github.com/jlongster/prettier/tree/master/editors/emacs)
for on-demand formatting.
2017-01-11 18:57:16 +03:00
### Vim
Vim users can add the following to their `.vimrc` :
```
autocmd FileType javascript set formatprg=prettier\ --stdin
```
This makes Prettier power the [`gq` command ](http://vimdoc.sourceforge.net/htmldoc/change.html#gq )
2017-01-23 18:27:52 +03:00
for automatic formatting without any plugins. You can also add the following to your
`.vimrc` to run prettier when `.js` files are saved:
```
autocmd BufWritePre *.js :normal gggqG
```
2017-01-11 18:57:16 +03:00
2017-01-11 20:09:15 +03:00
### Visual Studio Code
Can be installed using the extension sidebar. Search for `Prettier - JavaScript formatter`
Can also be installed using `ext install prettier-vscode`
[Check repository for configuration and shortcuts ](https://github.com/esbenp/prettier-vscode )
2017-01-15 07:21:58 +03:00
### Sublime Text
2017-01-19 18:17:23 +03:00
Sublime Text support is available through Package Control and
the [JsPrettier ](https://packagecontrol.io/packages/JsPrettier ) plug-in.
2017-01-15 07:21:58 +03:00
2017-01-30 18:06:35 +03:00
### JetBrains
JetBrains users can configure `prettier` as an **External Tool** 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.
2017-01-10 09:00:02 +03:00
More editors are coming soon.
2017-01-10 08:52:52 +03:00
2017-01-10 17:06:50 +03:00
## Language Support
Prettier attempts to support all JavaScript language features,
including non-standardized ones. By default it uses the
[babylon ](https://github.com/babel/babylon ) parser with all language
features enabled, but you can also use
[flow ](https://github.com/facebook/flow ) parser with the
2017-01-20 01:35:12 +03:00
`parser` API or `--parser` CLI option.
2017-01-10 17:06:50 +03:00
All of JSX and Flow syntax is supported. In fact, the test suite in
`tests` *is* the entire Flow test suite and they all pass.
2017-01-26 00:33:38 +03:00
## Related Projects
2017-01-27 02:06:49 +03:00
- [`eslint-plugin-prettier` ](https://github.com/not-an-aardvark/eslint-plugin-prettier ) plugs `prettier` into your `eslint` workflow
2017-01-30 18:22:49 +03:00
- [`eslint-config-prettier` ](https://github.com/lydell/eslint-config-prettier ) turns all `eslint` rules that are unnecessary or might conflict with prettier off
2017-01-26 00:33:38 +03:00
- [`prettier-eslint` ](https://github.com/kentcdodds/prettier-eslint )
passes `prettier` output to `eslint --fix`
- [`prettier-standard-formatter` ](https://github.com/dtinth/prettier-standard-formatter )
passes `prettier` output to `standard --fix`
- [`prettier-with-tabs` ](https://github.com/arijs/prettier-with-tabs )
allows you to configure prettier to use `tabs`
2017-01-10 08:45:11 +03:00
## Technical Details
2016-12-23 21:38:10 +03:00
2017-01-10 08:45:11 +03:00
This printer is a fork of
2017-01-11 23:48:07 +03:00
[recast ](https://github.com/benjamn/recast )'s printer with its
2017-01-10 08:45:11 +03:00
algorithm replaced by the one described by Wadler in "[A prettier
printer](http://homepages.inf.ed.ac.uk/wadler/papers/prettier/prettier.pdf)".
There still may be leftover code from recast that needs to be cleaned
up.
2016-12-23 21:38:10 +03:00
2017-01-10 08:45:11 +03:00
The basic idea is that the printer takes an AST and returns an
intermediate representation of the output, and the printer uses that
to generate a string. The advantage is that the printer can "measure"
the IR and see if the output is going to fit on a line, and break if
not.
2016-11-29 20:26:03 +03:00
2017-01-10 08:45:11 +03:00
This means that most of the logic of printing an AST involves
generating an abstract representation of the output involving certain
commands. For example, `concat(["(", line, arg, line ")"])` would
represent a concatentation of opening parens, an argument, and closing
parens. But if that doesn't fit on one line, the printer can break
where `line` is specified.
2016-12-23 21:38:10 +03:00
2017-01-10 08:45:11 +03:00
More (rough) details can be found in [commands.md ](commands.md ).
Better docs will come soon.
2016-12-23 21:38:10 +03:00
2017-01-10 08:45:11 +03:00
## Contributing
2016-11-29 20:26:03 +03:00
2017-01-10 09:00:02 +03:00
We will work on better docs over time, but in the mean time, here are
a few notes if you are interested in contributing:
2017-01-11 19:30:46 +03:00
* You should be able to get up and running with just `yarn`
2017-01-10 09:00:02 +03:00
* This uses jest snapshots for tests. The entire Flow test suite is
included here and you can make changes and run `jest -u` and then
`git diff` to see the styles that changed. Always update the
snapshots if opening a PR.
* If you can, look at [commands.md ](commands.md ) and check out
[Wadler's
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.
* 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.
* 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
2017-01-11 03:26:35 +03:00
original one and makes sure they are semantically equivalent.
2017-01-25 20:30:48 +03:00
* 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' });`