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)
|
||||
+ [ESLint](#eslint)
|
||||
+ [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)
|
||||
- [`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)
|
||||
* [Options](#options)
|
||||
+ [Print Width](#print-width)
|
||||
|
@ -54,6 +47,9 @@ conforms to a consistent style. (See this [blog post](http://jlongster.com/A-Pre
|
|||
+ [Range](#range)
|
||||
+ [Parser](#parser)
|
||||
+ [Filepath](#filepath)
|
||||
* [Configuration File](#configuration-file)
|
||||
+ [Basic Configuration](#basic-configuration)
|
||||
+ [Configuration Overrides](#configuration-overrides)
|
||||
* [Editor Integration](#editor-integration)
|
||||
+ [Atom](#atom)
|
||||
+ [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)
|
||||
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.
|
||||
|
||||
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`.
|
||||
#### `--list-different`
|
||||
|
||||
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"
|
||||
```
|
||||
|
||||
#### `--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
|
||||
|
||||
If you are using ESLint, integrating Prettier to your workflow is straightforward:
|
||||
|
@ -351,8 +376,6 @@ exit 0
|
|||
|
||||
### API
|
||||
|
||||
The API has three functions: `format`, `check`, and `formatWithCursor`.
|
||||
|
||||
```js
|
||||
const prettier = require("prettier");
|
||||
```
|
||||
|
@ -383,6 +406,31 @@ prettier.formatWithCursor(" 1", { cursorOffset: 2 });
|
|||
// -> { 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
|
||||
|
||||
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>"`
|
||||
|
||||
|
||||
## 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
|
||||
|
||||
### Atom
|
||||
|
|
|
@ -8,6 +8,11 @@ const withCache = cosmiconfig("prettier");
|
|||
const noCache = cosmiconfig("prettier", { cache: false });
|
||||
|
||||
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 fileDir = filePath ? path.dirname(filePath) : undefined;
|
||||
|
||||
|
|
Loading…
Reference in New Issue