Add documentation for configuration (#2452)
* Add documentation for configuration files * Add CLI docs for configuration * Support --no-configmaster
parent
3136907a15
commit
34b0709bf0
151
README.md
151
README.md
|
@ -33,14 +33,7 @@ conforms to a consistent style. (See this [blog post](http://jlongster.com/A-Pre
|
||||||
+ [CLI](#cli)
|
+ [CLI](#cli)
|
||||||
+ [ESLint](#eslint)
|
+ [ESLint](#eslint)
|
||||||
+ [Pre-commit Hook](#pre-commit-hook)
|
+ [Pre-commit Hook](#pre-commit-hook)
|
||||||
* [Option 1. lint-staged](#option-1-lint-staged)
|
|
||||||
* [Option 2. pre-commit](#option-2-pre-commit)
|
|
||||||
* [Option 3. bash script](#option-3-bash-script)
|
|
||||||
+ [API](#api)
|
+ [API](#api)
|
||||||
- [`prettier.format`](#prettierformatsource--options)
|
|
||||||
- [`prettier.check`](#prettierchecksource--options)
|
|
||||||
- [`prettier.formatWithCursor`](#prettierformatwithcursorsource--options)
|
|
||||||
- [Custom Parser API](#custom-parser-api)
|
|
||||||
+ [Excluding code from formatting](#excluding-code-from-formatting)
|
+ [Excluding code from formatting](#excluding-code-from-formatting)
|
||||||
* [Options](#options)
|
* [Options](#options)
|
||||||
+ [Print Width](#print-width)
|
+ [Print Width](#print-width)
|
||||||
|
@ -54,6 +47,9 @@ conforms to a consistent style. (See this [blog post](http://jlongster.com/A-Pre
|
||||||
+ [Range](#range)
|
+ [Range](#range)
|
||||||
+ [Parser](#parser)
|
+ [Parser](#parser)
|
||||||
+ [Filepath](#filepath)
|
+ [Filepath](#filepath)
|
||||||
|
* [Configuration File](#configuration-file)
|
||||||
|
+ [Basic Configuration](#basic-configuration)
|
||||||
|
+ [Configuration Overrides](#configuration-overrides)
|
||||||
* [Editor Integration](#editor-integration)
|
* [Editor Integration](#editor-integration)
|
||||||
+ [Atom](#atom)
|
+ [Atom](#atom)
|
||||||
+ [Emacs](#emacs)
|
+ [Emacs](#emacs)
|
||||||
|
@ -236,11 +232,11 @@ expands the globs rather than your shell, for cross-platform usage.
|
||||||
The [glob syntax from the glob module](https://github.com/isaacs/node-glob/blob/master/README.md#glob-primer)
|
The [glob syntax from the glob module](https://github.com/isaacs/node-glob/blob/master/README.md#glob-primer)
|
||||||
is used.
|
is used.
|
||||||
|
|
||||||
|
#### `--with-node-modules`
|
||||||
|
|
||||||
Prettier CLI will ignore files located in `node_modules` directory. To opt-out from this behavior use `--with-node-modules` flag.
|
Prettier CLI will ignore files located in `node_modules` directory. To opt-out from this behavior use `--with-node-modules` flag.
|
||||||
|
|
||||||
If you're worried that Prettier will change the correctness of your code, add `--debug-check` to the command.
|
#### `--list-different`
|
||||||
This will cause Prettier to print an error message if it detects that code correctness might have changed.
|
|
||||||
Note that `--write` cannot be used with `--debug-check`.
|
|
||||||
|
|
||||||
Another useful flag is `--list-different` (or `-l`) which prints the filenames of files that are different from Prettier formatting. If there are differences the script errors out, which is useful in a CI scenario.
|
Another useful flag is `--list-different` (or `-l`) which prints the filenames of files that are different from Prettier formatting. If there are differences the script errors out, which is useful in a CI scenario.
|
||||||
|
|
||||||
|
@ -248,6 +244,35 @@ Another useful flag is `--list-different` (or `-l`) which prints the filenames o
|
||||||
prettier --single-quote --list-different "src/**/*.js"
|
prettier --single-quote --list-different "src/**/*.js"
|
||||||
```
|
```
|
||||||
|
|
||||||
|
#### `--resolve-config` and `--config`
|
||||||
|
|
||||||
|
If you are repeatedly formatting individual files with `prettier`, you will incur a small performance cost
|
||||||
|
when prettier attempts to look up a [configuration file](#configuration-file). In order to skip this, you may
|
||||||
|
ask prettier to find the config file once, and re-use it later on.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
prettier --resolve-config ./my/file.js
|
||||||
|
./my/.prettierrc
|
||||||
|
```
|
||||||
|
|
||||||
|
This will provide you with a path to the configuration file, which you can pass to `--config`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
prettier --config ./my/.prettierrc --write ./my/file.js
|
||||||
|
```
|
||||||
|
|
||||||
|
You can also use `--config` if your configuration file lives somewhere where prettier cannot find it,
|
||||||
|
such as a `config/` directory.
|
||||||
|
|
||||||
|
If you don't have a configuration file, or want to ignore it if it does exist,
|
||||||
|
you can pass `--no-config` instead.
|
||||||
|
|
||||||
|
#### `--debug-check`
|
||||||
|
|
||||||
|
If you're worried that Prettier will change the correctness of your code, add `--debug-check` to the command.
|
||||||
|
This will cause Prettier to print an error message if it detects that code correctness might have changed.
|
||||||
|
Note that `--write` cannot be used with `--debug-check`.
|
||||||
|
|
||||||
### ESLint
|
### ESLint
|
||||||
|
|
||||||
If you are using ESLint, integrating Prettier to your workflow is straightforward:
|
If you are using ESLint, integrating Prettier to your workflow is straightforward:
|
||||||
|
@ -351,8 +376,6 @@ exit 0
|
||||||
|
|
||||||
### API
|
### API
|
||||||
|
|
||||||
The API has three functions: `format`, `check`, and `formatWithCursor`.
|
|
||||||
|
|
||||||
```js
|
```js
|
||||||
const prettier = require("prettier");
|
const prettier = require("prettier");
|
||||||
```
|
```
|
||||||
|
@ -383,6 +406,31 @@ prettier.formatWithCursor(" 1", { cursorOffset: 2 });
|
||||||
// -> { formatted: '1;\n', cursorOffset: 1 }
|
// -> { formatted: '1;\n', cursorOffset: 1 }
|
||||||
```
|
```
|
||||||
|
|
||||||
|
#### `prettier.resolveConfig([filePath] [, options])`
|
||||||
|
|
||||||
|
`resolveConfig` can be used to resolve configuration for a given source file.
|
||||||
|
The function optionally accepts an input file path as an argument, which defaults to the current working directory.
|
||||||
|
A promise is returned which will resolve to:
|
||||||
|
* An options object, providing a [config file](#configuration-file) was found.
|
||||||
|
* `null`, if no file was found.
|
||||||
|
|
||||||
|
The promise will be rejected if there was an error parsing the configuration file.
|
||||||
|
|
||||||
|
If `options.withCache` is `false`, all caching will be bypassed.
|
||||||
|
|
||||||
|
```js
|
||||||
|
const text = fs.readFileSync(filePath, "utf8");
|
||||||
|
prettier.resolveConfig(filePath).then(options => {
|
||||||
|
const formatted = prettier.format(text, options);
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `prettier.clearConfigCache()`
|
||||||
|
|
||||||
|
As you repeatedly call `resolveConfig`, the file system structure will be cached for performance.
|
||||||
|
This function will clear the cache. Generally this is only needed for editor integrations that
|
||||||
|
know that the file system has changed since the last format took place.
|
||||||
|
|
||||||
#### Custom Parser API
|
#### Custom Parser API
|
||||||
|
|
||||||
If you need to make modifications to the AST (such as codemods), or you want to provide an alternate parser, you can do so by setting the `parser` option to a function. The function signature of the parser function is:
|
If you need to make modifications to the AST (such as codemods), or you want to provide an alternate parser, you can do so by setting the `parser` option to a function. The function signature of the parser function is:
|
||||||
|
@ -569,6 +617,85 @@ Default | CLI Override | API Override
|
||||||
None | `--stdin-filepath <string>` | `filepath: "<string>"`
|
None | `--stdin-filepath <string>` | `filepath: "<string>"`
|
||||||
|
|
||||||
|
|
||||||
|
## Configuration File
|
||||||
|
|
||||||
|
Prettier uses [cosmiconfig](https://github.com/davidtheclark/cosmiconfig) for configuration file support.
|
||||||
|
This means you can configure prettier via:
|
||||||
|
|
||||||
|
* A `.prettierrc` file, written in YAML or JSON.
|
||||||
|
* A `prettier.config.js` file that exports an object.
|
||||||
|
* A `"prettier"` key in your `package.json` file.
|
||||||
|
|
||||||
|
The configuration file will be resolved starting from the location of the file being formatted,
|
||||||
|
and searching up the file tree until a config file is (or isn't) found.
|
||||||
|
|
||||||
|
The options to the configuration file are the same the [API options](#options).
|
||||||
|
|
||||||
|
### Basic Configuration
|
||||||
|
|
||||||
|
JSON:
|
||||||
|
|
||||||
|
```json
|
||||||
|
// .prettierrc
|
||||||
|
{
|
||||||
|
"printWidth": 100,
|
||||||
|
"parser": "flow"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
YAML:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# .prettierrc
|
||||||
|
printWidth: 100
|
||||||
|
parser: flow
|
||||||
|
```
|
||||||
|
|
||||||
|
### Configuration Overrides
|
||||||
|
|
||||||
|
Prettier borrows eslint's [override format](http://eslint.org/docs/user-guide/configuring#example-configuration).
|
||||||
|
This allows you to apply configuration to specific files.
|
||||||
|
|
||||||
|
JSON:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"semi": false,
|
||||||
|
"overrides": [{
|
||||||
|
"files": "*.test.js",
|
||||||
|
"options": {
|
||||||
|
"semi": true
|
||||||
|
}
|
||||||
|
}]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
YAML:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
semi: false
|
||||||
|
overrides:
|
||||||
|
- files: "*.test.js"
|
||||||
|
options:
|
||||||
|
semi: true
|
||||||
|
```
|
||||||
|
|
||||||
|
`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:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"overrides": [{
|
||||||
|
"files": ".prettierrc",
|
||||||
|
"options": { "parser": "json" }
|
||||||
|
}]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
For more information on how to use the CLI to locate a file, see the [CLI](#cli) section.
|
||||||
|
|
||||||
## Editor Integration
|
## Editor Integration
|
||||||
|
|
||||||
### Atom
|
### Atom
|
||||||
|
|
|
@ -8,6 +8,11 @@ const withCache = cosmiconfig("prettier");
|
||||||
const noCache = cosmiconfig("prettier", { cache: false });
|
const noCache = cosmiconfig("prettier", { cache: false });
|
||||||
|
|
||||||
function resolveConfig(filePath, opts) {
|
function resolveConfig(filePath, opts) {
|
||||||
|
if (opts && opts.configFile === false) {
|
||||||
|
// do not look for a config file
|
||||||
|
return Promise.resolve(null);
|
||||||
|
}
|
||||||
|
|
||||||
const useCache = !(opts && opts.useCache === false);
|
const useCache = !(opts && opts.useCache === false);
|
||||||
const fileDir = filePath ? path.dirname(filePath) : undefined;
|
const fileDir = filePath ? path.dirname(filePath) : undefined;
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue