Configuring ESLint

ESLint is designed to be completely configurable, meaning you can turn off every rule and run only with basic syntax validation, or mix and match the bundled rules and your custom rules to make ESLint perfect for your project. There are two primary ways to configure ESLint:

Configuration Files - use a JavaScript, JSON or YAML file to specify configuration information for an entire directory and all of its subdirectories. This can be in the form of an .eslintrc.* file or an eslintConfig field in a package.json file, both of which ESLint will look for and read automatically, or you can specify a configuration file on the command line.

There are several pieces of information that can be configured:

Environments - which environments your script is designed to run in. Each environment brings with it a certain set of predefined global variables.

All of these options give you fine-grained control over how ESLint treats your code.

Specifying Parser Options

ESLint allows you to specify the JavaScript language options you want to support. By default, ESLint expects ECMAScript 5 syntax. You can override that setting to enable support for other ECMAScript versions as well as JSX by using parser options.

Please note that supporting JSX syntax is not the same as supporting React. React applies specific semantics to JSX syntax that ESLint doesn’t recognize. We recommend using eslint-plugin-react if you are using React and want React semantics.
By the same token, supporting ES6 syntax is not the same as supporting new ES6 globals (e.g., new types such as
Set).
For ES6 syntax, use { "parserOptions": { "ecmaVersion": 6 } }; for new ES6 global variables, use { "env":
{ "es6": true } } (this setting enables ES6 syntax automatically).
Parser options are set in your .eslintrc.* file by using the parserOptions property. The available options are:

ecmaVersion - set to 3, 5 (default), 6, 7, or 8 to specify the version of ECMAScript syntax you want to use. You can also set to 2015 (same as 6), 2016 (same as 7), or 2017 (same as 8) to use the year-based naming.

sourceType - set to "script" (default) or "module" if your code is in ECMAScript modules.

ecmaFeatures - an object indicating which additional language features you’d like to use:

experimentalObjectRestSpread - enable support for the experimental object rest/spread properties (IMPORTANT: This is an experimental feature that may change significantly in the future. It’s recommended that you do not write rules relying on this functionality unless you are willing to incur maintenance cost when it changes.)

Babel-ESLint - A wrapper around the Babel parser that makes it compatible with ESLint.

typescript-eslint-parser(Experimental) - A parser that converts TypeScript into an ESTree-compatible form so it can be used in ESLint. The goal is to allow TypeScript files to be parsed by ESLint (though not necessarily pass all ESLint rules).

Note when using a custom parser, the parserOptions configuration property is still required for ESLint to work properly with features not in ECMAScript 5 by default. Parsers are all passed parserOptions and may or may not use them to determine which features to enable.

Specifying Environments

An environment defines global variables that are predefined. The available environments are:

amd - defines require() and define() as global variables as per the amd spec.

mocha - adds all of the Mocha testing global variables.

jasmine - adds all of the Jasmine testing global variables for version 1.3 and 2.0.

jest - Jest global variables.

phantomjs - PhantomJS global variables.

protractor - Protractor global variables.

qunit - QUnit global variables.

jquery - jQuery global variables.

prototypejs - Prototype.js global variables.

shelljs - ShellJS global variables.

meteor - Meteor global variables.

mongo - MongoDB global variables.

applescript - AppleScript global variables.

nashorn - Java 8 Nashorn global variables.

serviceworker - Service Worker global variables.

atomtest - Atom test helper globals.

embertest - Ember test helper globals.

webextensions - WebExtensions globals.

greasemonkey - GreaseMonkey globals.

These environments are not mutually exclusive, so you can define more than one at a time.

Environments can be specified inside of a file, in configuration files or using the --envcommand line flag.

To specify environments using a comment inside of your JavaScript file, use the following format:

/* eslint-env node, mocha */

This enables Node.js and Mocha environments.

To specify environments in a configuration file, use the env key and specify which environments you want to enable by setting each to true. For example, the following enables the browser and Node.js environments:

If you want to use an environment from a plugin, be sure to specify the plugin name in the plugins array and then use the unprefixed plugin name, followed by a slash, followed by the environment name. For example:

Specifying Globals

The no-undef rule will warn on variables that are accessed but not defined within the same file. If you are using global variables inside of a file then it’s worthwhile to define those globals so that ESLint will not warn about their usage. You can define global variables either using comments inside of a file or in the configuration file.

To specify globals using a comment inside of your JavaScript file, use the following format:

/* global var1, var2 */

This defines two global variables, var1 and var2. If you want to optionally specify that these global variables should never be written to (only read), then you can set each with a false flag:

/* global var1:false, var2:false */

To configure global variables inside of a configuration file, use the globals key and indicate the global variables you want to use. Set each global variable name equal to true to allow the variable to be overwritten or false to disallow overwriting. For example:

{"globals":{"var1":true,"var2":false}}

And in YAML:

---globals:var1:truevar2:false

These examples allow var1 to be overwritten in your code, but disallow it for var2.

Configuring Plugins

ESLint supports the use of third-party plugins. Before using the plugin you have to install it using npm.

To configure plugins inside of a configuration file, use the plugins key, which contains a list of plugin names. The eslint-plugin- prefix can be omitted from the plugin name.

{"plugins":["plugin1","eslint-plugin-plugin2"]}

And in YAML:

---plugins:-plugin1-eslint-plugin-plugin2

Note: A globally-installed instance of ESLint can only use globally-installed ESLint plugins. A locally-installed ESLint can make use of both locally- and globally- installed ESLint plugins.

Configuring Rules

ESLint comes with a large number of rules. You can modify which rules your project uses either using configuration comments or configuration files. To change a rule setting, you must set the rule ID equal to one of these values:

"off" or 0 - turn the rule off

"warn" or 1 - turn the rule on as a warning (doesn’t affect exit code)

"error" or 2 - turn the rule on as an error (exit code is 1 when triggered)

To configure rules inside of a file using configuration comments, use a comment in the following format:

/* eslint eqeqeq: "off", curly: "error" */

In this example, eqeqeq is turned off and curly is turned on as an error. You can also use the numeric equivalent for the rule severity:

/* eslint eqeqeq: 0, curly: 2 */

This example is the same as the last example, only it uses the numeric codes instead of the string values. The eqeqeq rule is off and the curly rule is set to be an error.

If a rule has additional options, you can specify them using array literal syntax, such as:

/* eslint quotes: ["error", "double"], curly: 2 */

This comment specifies the “double” option for the quotes rule. The first item in the array is always the rule severity (number or string).

To configure rules inside of a configuration file, use the rules key along with an error level and any options you want to use. For example:

All of the above methods also work for plugin rules. For example, to disable eslint-plugin-example’s rule-name rule, combine the plugin’s name (example) and the rule’s name (rule-name) into example/rule-name:

foo();// eslint-disable-line example/rule-name

Note: Comments that disable warnings for a portion of a file tell ESLint not to report rule violations for the disabled code. ESLint still parses the entire file, however, so disabled code still needs to be syntactically valid JavaScript.

Adding Shared Settings

ESLint supports adding shared settings into configuration file. You can add settings object to ESLint configuration file and it will be supplied to every rule that will be executed. This may be useful if you are adding custom rules and want them to have access to the same information and be easily configurable.

In JSON:

{"settings":{"sharedData":"Hello"}}

And in YAML:

---settings:sharedData:"Hello"

Using Configuration Files

There are two ways to use configuration files. The first is to save the file wherever you would like and pass its location to the CLI using the -c option, such as:

eslint -c myconfig.json myfiletotest.js

The second way to use configuration files is via .eslintrc.* and package.json files. ESLint will automatically look for them in the directory of the file to be linted, and in successive parent directories all the way up to the root directory of the filesystem. This option is useful when you want different configurations for different parts of a project or when you want others to be able to use ESLint directly without needing to remember to pass in the configuration file.

In each case, the settings in the configuration file override default settings.

The configuration cascade works by using the closest .eslintrc file to the file being linted as the highest priority, then any configuration files in the parent directory, and so on. When you run ESLint on this project, all files in lib/ will use the .eslintrc file at the root of the project as their configuration. When ESLint traverses into the tests/ directory, it will then use your-project/tests/.eslintrc in addition to your-project/.eslintrc. So your-project/tests/test.js is linted based on the combination of the two .eslintrc files in its directory hierarchy, with the closest one taking priority. In this way, you can have project-level ESLint settings and also have directory-specific overrides.

In the same way, if there is a package.json file in the root directory with an eslintConfig field, the configuration it describes will apply to all subdirectories beneath it, but the configuration described by the .eslintrc file in the tests directory will override it where there are conflicting specifications.

If there is an .eslintrc and a package.json file found in the same directory, .eslintrc will take a priority and package.json file will not be used.

Note: If you have a personal configuration file in your home directory (~/.eslintrc), it will only be used if no other configuration files are found. Since a personal configuration would apply to everything inside of a user’s directory, including third-party code, this could cause problems when running ESLint.

By default, ESLint will look for configuration files in all parent folders up to the root directory. This can be useful if you want all of your projects to follow a certain convention, but can sometimes lead to unexpected results. To limit ESLint to a specific project, place "root": true inside the eslintConfig field of the package.json file or in the .eslintrc.* file at your project’s root level. ESLint will stop looking in parent folders once it finds a configuration with "root": true.

{"root":true}

And in YAML:

---root:true

For example, consider projectA which has "root": true set in the .eslintrc file in the lib/ directory. In this case, while linting main.js, the configurations within lib/ will be used, but the .eslintrc file in projectA/ will not.

The complete configuration hierarchy, from highest precedence to lowest precedence, is as follows:

Inline configuration

/*eslint-disable*/ and /*eslint-enable*/

/*global*/

/*eslint*/

/*eslint-env*/

Command line options:

--global

--rule

--env

-c, --config

Project-level configuration:

.eslintrc.* or package.json file in same directory as linted file

Continue searching for .eslintrc and package.json files in ancestor directories (parent has highest precedence, then grandparent, etc.), up to and including the root directory or until a config with "root": true is found.

In the absence of any configuration from (1) thru (3), fall back to a personal default configuration in ~/.eslintrc.

Extending Configuration Files

A configuration file can extend the set of enabled rules from base configurations.

The extends property value is either:

a string that specifies a configuration

an array of strings: each additional configuration extends the preceding configurations

ESLint extends configurations recursively so a base configuration can also have an extends property.

The rules property can do any of the following to extend (or override) the set of rules:

enable additional rules

change an inherited rule’s severity without changing its options:

Base config: "eqeqeq": ["error", "allow-null"]

Derived config: "eqeqeq": "warn"

Resulting actual config: "eqeqeq": ["warn", "allow-null"]

override options for rules from base configurations:

Base config: "quotes": ["error", "single", "avoid-escape"]

Derived config: "quotes": ["error", "single"]

Resulting actual config: "quotes": ["error", "single"]

Using "eslint:recommended"

An extends property value "eslint:recommended" enables a subset of core rules that report common problems, which have a check mark on the rules page. The recommended subset can change only at major versions of ESLint.

If your configuration extends the recommended rules: after you upgrade to a newer major version of ESLint, review the reported problems before you use the --fix option on the command line, so you know if a new fixable recommended rule will make changes to the code.

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

Using a configuration file

The extends property value can be an absolute or relative path to a base configuration file.

ESLint resolves a relative path to a base configuration file relative to the configuration file that uses it unless that 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 base file relative to the linted project directory (typically the current working directory).

Using "eslint:all"

The extends property value can be "eslint:all" to enable all core rules in the currently installed version of ESLint. The set of core rules can change at any minor or major version of ESLint.

Important: This configuration is not recommended for production use because it changes with every minor and major version of ESLint. Use at your own risk.

If you configure ESLint to automatically enable new rules when you upgrade, ESLint can report new problems when there are no changes to source code, therefore any newer minor version of ESLint can behave as if it has breaking changes.

You might enable all core rules as a shortcut to explore rules and options while you decide on the configuration for a project, especially if you rarely override options or disable rules. The default options for rules are not endorsements by ESLint (for example, the default option for the quotes rule does not mean double quotes are better than single quotes).

If your configuration extends all core rules: after you upgrade to a newer major or minor version of ESLint, review the reported problems before you use the --fix option on the command line, so you know if a new fixable rule will make changes to the code.

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:

{"env":{"browser":true},"rules":{// Override our default settings just for this directory"eqeqeq":"warn","strict":"off"}}

Specifying File extensions to Lint

Currently the sole method for telling ESLint which file extensions to lint is by specifying a comma separated list of extensions using the --ext command line option. Note this flag only takes effect in conjunction with directories, and will be ignored if used with filenames or glob patterns.

Ignoring Files and Directories

You can tell ESLint to ignore specific files and directories by creating an .eslintignore file in your project’s root directory. The .eslintignore file is a plain text file where each line is a glob pattern indicating which paths should be omitted from linting. For example, the following will omit all JavaScript files:

**/*.js

When ESLint is run, it looks in the current working directory to find an .eslintignore file before determining which files to lint. If this file is found, then those preferences are applied when traversing directories. Only one .eslintignore file can be used at a time, so .eslintignore files other than the one in the current working directory will not be used.

Globs are matched using node-ignore, so a number of features are available:

Lines beginning with # are treated as comments and do not affect ignore patterns.

Paths are relative to .eslintignore location or the current working directory. This also influences paths passed via --ignore-pattern.

Using an Alternate File

If you’d prefer to use a different file than the .eslintignore in the current working directory, you can specify it on the command line using the --ignore-path option. For example, you can use .jshintignore file because it has the same format:

eslint --ignore-path .jshintignore file.js

You can also use your .gitignore file:

eslint --ignore-path .gitignore file.js

Any file that follows the standard ignore file format can be used. Keep in mind that specifying --ignore-path means that any existing .eslintignore file will not be used. Note that globbing rules in .eslintignore follow those of .gitignore.

Ignored File Warnings

When you pass directories to ESLint, files and directories are silently ignored. If you pass a specific file to ESLint, then you will see a warning indicating that the file was skipped. For example, suppose you have an .eslintignore file that looks like this: