From b9b5d2d35c4f0b2daab13bf2860ea1156b82cf89 Mon Sep 17 00:00:00 2001 From: Mark Pedrotti Date: Tue, 7 Jun 2016 16:25:41 -0400 Subject: [PATCH] Docs: Describe values under Extending Configuration Files (refs #6240) --- docs/user-guide/configuring.md | 132 ++++++++++++++++++++++----------- 1 file changed, 90 insertions(+), 42 deletions(-) diff --git a/docs/user-guide/configuring.md b/docs/user-guide/configuring.md index f22600ef8df..46074377631 100644 --- a/docs/user-guide/configuring.md +++ b/docs/user-guide/configuring.md @@ -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: