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:

  1. Configuration Comments - use JavaScript comments to embed configuration information directly into a file.
  2. 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:

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 supports only ECMAScript 5 syntax. You can override that setting to enable support for ECMAScript 6 as well as JSX by using parser options.

Parser options are set in your .eslintrc.* file by using the parserOptions property. The available options are:

Here's an example .eslintrc.json file:

{
    "parserOptions": {
        "ecmaVersion": 6,
        "sourceType": "module",
        "ecmaFeatures": {
            "jsx": true
        }
    },
    "rules": {
        "semi": 2
    }
}

Setting parser options helps ESLint determine what is a parsing error. All language options are false by default.

Specifying Parser

By default, ESLint uses Espree as its parser. You can optionally specify that a different parser should be used in your configuration file so long as the parser meets the following requirements:

  1. It must be an npm module installed locally.
  2. It must have an Esprima-compatible interface (it must export a parse() method).
  3. It must produce Esprima-compatible AST and token objects.

Note that even with these compatibilities, there are no guarantees that an external parser will work correctly with ESLint and ESLint will not fix bugs related to incompatibilities with other parsers.

To indicate the npm module to use as your parser, specify it using the parser option in your .eslintrc file. For example, the following specifies to use Esprima instead of Espree:

{
    "parser": "esprima",
    "rules": {
        "semi": 2
    }
}

The following parsers are compatible with ESLint:

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:

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 --env command 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:

{
    "env": {
        "browser": true,
        "node": true
    }
}

Or in a package.json file

{
    "name": "mypackage",
    "version": "0.0.1",
    "eslintConfig": {
        "env": {
            "browser": true,
            "node": true
        }
    }
}

And in YAML:

---
  env:
    browser: true
    node: true

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

{
    "plugins": ["example"],
    "env": {
        "example/custom": true
    }
}

Or in a package.json file

{
    "name": "mypackage",
    "version": "0.0.1",
    "eslintConfig": {
        "plugins": ["example"],
        "env": {
            "example/custom": true
        }
    }
}

And in YAML:

---
  plugins:
    - example
  env:
    example/custom: true

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: true
    var2: 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:

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

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

In this example, eqeqeq is turned off and curly is turned on as an error. If a rule has additional options, you can specify them using array literal syntax, such as:

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

This comment specifies the "double" option for the quotes rule.

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:

{
    "rules": {
        "eqeqeq": 0,
        "curly": 2,
        "quotes": [2, "double"]
    }
}

And in YAML:

---
  rules:
    eqeqeq: 0
    curly: 2
    quotes:
      - 2
      - "double"

To configure a rule which is defined within a plugin you have to prefix the rule ID with the plugin name and a /. For example:

{
    "plugins": [
        "plugin1"
    ],
    "rules": {
        "eqeqeq": 0,
        "curly": 2,
        "quotes": [2, "double"],
        "plugin1/rule1": 2
    }
}

And in YAML:

---
  plugins:
    - plugin1
  rules:
    eqeqeq: 0
    curly: 2
    quotes:
      - 2
      - "double"
    plugin1/rule1: 2

In these configuration files, the rule plugin1/rule1 comes from the plugin named plugin1. You can also use this format with configuration comments, such as:

/*eslint "plugin1/rule1": 2*/

Note: When specifying rules from plugins, make sure to omit eslint-plugin-. ESLint uses only the unprefixed name internally to locate rules.

To temporarily disable rule warnings in your file use the following format:

/*eslint-disable */

//Disable all rules between comments
alert('foo');

/*eslint-enable */

You can also disable or enable warnings for specific rules:

/*eslint-disable no-alert, no-console */

alert('foo');
console.log('bar');

/*eslint-enable no-alert */

To disable all rules on a specific line:

alert('foo'); // eslint-disable-line

To disable a specific rule on a specific line:

alert('foo'); // eslint-disable-line no-alert

Note: Comments that disable warnings for a portion of a file tell ESLint not to report rule violations for the disabled code. ESLint parses the entire file, 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.

Configuration File Formats

ESLint supports configuration files in several formats:

If there are multiple configuration files in the same directory, ESLint will only use one. The priority order is:

  1. .eslintrc.js
  2. .eslintrc.yaml
  3. .eslintrc.yml
  4. .eslintrc.json
  5. .eslintrc
  6. package.json

Configuration Cascading and Hierarchy

When using .eslintrc.* and package.json files for configuration, you can take advantage of configuration cascading. For instance, suppose you have the following structure:

your-project
├── .eslintrc
├── lib
│ └── source.js
└─┬ tests
  ├── .eslintrc
  └── test.js

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.

your-project
├── package.json
├── lib
│ └── source.js
└─┬ tests
  ├── .eslintrc
  └── test.js

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 main project directory. In this case, while linting main.js, the configurations within lib/will be used, but the .eslintrc file in projectA/ will not.

home
└── user
    ├── .eslintrc <- Always skipped if other configs present
    └── projectA
        ├── .eslintrc  <- Not used
        └── lib
            ├── .eslintrc  <- { "root": true }
            └── main.js

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

  1. Inline configuration
    1. /*eslint-disable*/ and /*eslint-enable*/
    2. /*global*/
    3. /*eslint*/
    4. /*eslint-env*/
  2. Command line options:
    1. --global
    2. --rule
    3. --env
    4. -c, --config
  3. Project-level configuration:
    1. .eslintrc.* or package.json file in same directory as linted file
    2. 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.
    3. In the absence of any configuration from (1) thru (3), fall back to a personal default configuration in ~/.eslintrc.

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.

Configurations can be extended by using:

  1. YAML file
  2. JSON file
  3. JS file
  4. Shareable configuration package

The extended configuration provides base rules, which can be overridden by the configuration that references it. For example:

{
    "extends": "./node_modules/coding-standard/.eslintrc",

    "rules": {
        // Override any settings from the "parent" configuration
        "eqeqeq": 1
    }
}

Configurations may also be provided as an array, with additional files overriding any properties provided in the previous file. For example:

{
    "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",
    ],

    "rules": {
        // Override any settings from the "parent" configuration
        "eqeqeq": 1
    }
}

The extended configurations can also contain their own extends, resulting in recursive merging of the referenced configurations.

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:

{
    "extends": "eslint-config-myrules",

    "rules": {
        // Override any settings from the "parent" configuration
        "eqeqeq": 1
    }
}

In this example, the eslint-config-myrules package will be loaded as an object and used as the parent of this configuration.

Note: You can omit eslint-config- and ESLint will automatically insert it for you, similar to how plugins work. See Shareable Configs for more information.

ESLint also supports extending configuration from plugins that provide configs:

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

    "rules": {
        // Override any settings from the "parent" configuration
        "eqeqeq": 1
    }
}

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:

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

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.

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:

In addition to any patterns in a .eslintignore file, ESLint always ignores files in /node_modules/** and /bower_components/**.

For example, placing the following .eslintignore file in the current working directory will ignore all of node_modules, bower_components, any files with the extensions .ts.js or .coffee.js extension that might have been transpiled, and anything in the build/ directory except build/index.js:

# /node_modules and /bower_components ignored by default

# Ignore files compiled from TypeScript and CoffeeScript
**/*.{ts,coffee}.js

# Ignore built files except build/index.js
build/
!build/index.js

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 are more strict than in .gitignore. See all supported patterns in minimatch docs

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:

foo.js

And then you run:

eslint foo.js

You'll see this warning:

foo.js
  0:0  warning  File ignored because of your .eslintignore file. Use --no-ignore to override.

✖ 1 problem (0 errors, 1 warning)

This message occurs because ESLint is unsure if you wanted to actually lint the file or not. As the message indicates, you can use --no-ignore to omit using the ignore rules.