Skip to content

Commit

Permalink
Docs: Describe values under Extending Configuration Files (refs #6240)
Browse files Browse the repository at this point in the history
  • Loading branch information
@pedrottimark
pedrottimark committed Jun 8, 2016
1 parent 1cc4356 commit b9b5d2d
Showing 1 changed file with 90 additions and 42 deletions.
132 changes: 90 additions & 42 deletions docs/user-guide/configuring.md
View file
Expand Up @@ -550,85 +550,133 @@ The complete configuration hierarchy, from highest precedence to lowest preceden

## Extending Configuration Files

If you want to extend a specific configuration file, you can use the `extends` property and specify the path to the file. The path can be either relative or absolute.
A configuration file can extend the set of enabled rules from base configurations.

Configurations can be extended by using:
The `extends` property value is either:

1. YAML file
1. JSON file
1. JS file
1. Shareable configuration package
* a string that specifies a configuration
* an array of strings: each additional configuration extends the preceding configurations

The extended configuration provides base rules, which can be overridden by the configuration that references it. For example:
ESLint extends configurations recursively so a base configuration can also have an `extends` property.

```js
{
"extends": "./node_modules/coding-standard/.eslintrc",
The `rules` property can do any of the following to extend (or override) the set of rules:

* enable additional rules
* specify different options for rules from base configurations
* disable rules from base configurations

### Using the recommended rules

An `extends` property value `"eslint:recommended"` enables a subset of core rules that report common problems, which have a check mark (recommended) on the [rules page](http://eslint.org/docs/rules/). The recommended subset can change only at major versions of ESLint.

The `eslint --init` command can create a configuration so you can extend the recommended rules.

Example of an extended configuration in JavaScript file format:

```js
module.exports = {
"extends": "eslint:recommended",
"rules": {
// Override any settings from the "parent" configuration
"eqeqeq": 1
// enable additional rules
"indent": ["error", 4],
"linebreak-style": ["error", "unix"],
"quotes": ["error", "double"],
"semi": ["error", "always"],

// specify different options for rules from base configurations
"no-cond-assign": ["error", "always"],

// disable rules from base configurations
"no-console": "off",
}
}
```

Configurations may also be provided as an array, with additional files overriding any properties provided in the previous file. For example:
### Using a shareable configuration package

```js
A [sharable configuration](../developer-guide/shareable-configs) is an npm package that exports a configuration object. Make sure the package has been installed to a directory where ESLint can require it.

The `extends` property value can omit the `eslint-config-` prefix of the package name.

The `eslint --init` command can create a configuration so you can extend a popular style guide (for example, `eslint-config-standard`).

Example of an extended configuration in YAML file format:

```yaml
extends: standard
rules:
comma-dangle:
- error
- always
no-empty: warn
```

### Using the configuration from a plugin

A [plugin](../developer-guide/working-with-plugins) is an npm package that usually exports rules. Some plugins also export one or more named [configurations](../developer-guide/working-with-plugins#configs-in-plugins). Make sure the package has been installed to a directory where ESLint can require it.

The `plugins` [property value](#configuring-plugins) can omit the `eslint-plugin-` prefix of the package name.

The `extends` property value can consist of:

* `plugin:`
* the package name (from which you can omit the prefix, for example, `react`)
* `/`
* the configuration name (for example, `recommended`)

Example of an extended configuration in JSON file format:

```json
{
"plugins": [
"react"
],
"extends": [
"./node_modules/coding-standard/eslintDefaults.js",
// Override eslintDefaults.js
"./node_modules/coding-standard/.eslintrc-es6",
// Override .eslintrc-es6
"./node_modules/coding-standard/.eslintrc-jsx",
"eslint:recommended",
"plugin:react/recommended"
],

"rules": {
// Override any settings from the "parent" configuration
"eqeqeq": "warn"
"no-set-state": "off"
}
}
```

The extended configurations can also contain their own `extends`, resulting in recursive merging of the referenced configurations.
### Using a configuration file

You can also extend configurations using shareable configuration packages. To do so, be sure to install the configuration package you want from npm and then use the package name, such as:
The `extends` property value can be an absolute or relative path to another [configuration file](#using-configuration-files).

```js
{
"extends": "eslint-config-myrules",
ESLint resolves a relative path to a "child" configuration file relative to the "parent" configuration file **unless** the "parent" file is in your home directory or a directory that isn't an ancestor to the directory in which ESLint is installed (either locally or globally). In those cases, ESLint resolves the relative path to the "child" file relative to the linted **project** directory (typically the current working directory).

Example of an extended configuration in JSON file format:

```json
{
"extends": [
"./node_modules/coding-standard/eslintDefaults.js",
"./node_modules/coding-standard/.eslintrc-es6",
"./node_modules/coding-standard/.eslintrc-jsx"
],
"rules": {
// Override any settings from the "parent" configuration
"eqeqeq": "warn"
}
}
```

In this example, the `eslint-config-myrules` package will be loaded as an object and used as the parent of this configuration.
### Using all core rules

**Note:** You can omit `eslint-config-` and ESLint will automatically insert it for you, similar to how plugins work. See [Shareable Configs](../developer-guide/shareable-configs) for more information.
The `extends` property value can be `"eslint:all"` to enable all core rules in the currently installed version of ESLint. The set of rules can change at any minor or major version of ESLint.

ESLint also supports extending configuration from plugins that provide configs:
Example of an extended configuration in JavaScript file format:

```js
{
"extends": "plugin:eslint-plugin-myplugin/myConfig",

module.exports = {
"extends": "eslint:all",
"rules": {
// Override any settings from the "parent" configuration
"eqeqeq": "warn"

}
}
```

In this example, the `eslint-plugin-myplugin` package contains configuration named `default`.

**Important:** When you are extending from the configuration bundled with plugins, you need to start with `plugin:` prefix as well as specify configuration name after the slash. You may optionally omit the `eslint-plugin-` prefix.

**Note:** For configuration files in your home directory, or in any path that isn't an ancestor to the location of ESLint (either globally or locally), `extends` is resolved from the path of the project using ESLint (typically the current working directory) rather than relative to the file itself.

## Comments in Configuration Files

Both the JSON and YAML configuration file formats support comments (`package.json` files should not include them). You can use JavaScript-style comments or YAML-style comments in either type of file and ESLint will safely ignore them. This allows your configuration files to be more human-friendly. For example:
Expand Down

0 comments on commit b9b5d2d

Please sign in to comment.