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-10 08:45:11 +03:00
|
|
|
foo(arg1, arg2, arg3);
|
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-11 19:02:30 +03:00
|
|
|
For example, you could format your source using bash filename expansion:
|
|
|
|
```bash
|
|
|
|
prettier --write src/**/*.js bin/*.js
|
|
|
|
```
|
|
|
|
|
|
|
|
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
|
|
|
|
|
|
|
// Use the flow parser instead of babylon
|
|
|
|
useFlowParser: false,
|
|
|
|
|
|
|
|
// If true, will use single instead of double quotes
|
|
|
|
singleQuote: false,
|
|
|
|
|
|
|
|
// Controls the printing of trailing commas wherever possible
|
|
|
|
trailingComma: false,
|
|
|
|
|
|
|
|
// Controls the printing of spaces inside array and objects
|
|
|
|
bracketSpacing: true
|
|
|
|
});
|
|
|
|
```
|
|
|
|
|
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)
|
|
|
|
for automatic formatting without any plugins.
|
|
|
|
|
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
|
|
|
|
|
|
|
|
Please see [this issue](https://github.com/jlongster/prettier/issues/17) for those interested in working on Sublime Text integration.
|
|
|
|
|
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
|
|
|
|
`useFlowParser` API or `--flow-parser` CLI option.
|
|
|
|
|
|
|
|
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-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.
|