Configuration Files

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 as follows:

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

Using Configuration Files

There are two ways to use configuration files.

The first 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 (/), the home directory of the current user (~/), or when root: true is specified. See Cascading and Hierarchy below for more details on this. Configuration files can be 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.

The second way to use configuration files is to save the file wherever you would like and pass its location to the CLI using the --config option, such as:

eslint -c myconfig.json myfiletotest.js

If you are using one configuration file and want ESLint to ignore any .eslintrc.* files, make sure to use --no-eslintrc along with the -c flag.

Here's an example JSON configuration file that uses the typescript-eslint parser to support TypeScript syntax:

{
    "root": true,
    "extends": [
        "eslint:recommended",
        "plugin:@typescript-eslint/recommended"
    ],
    "parser": "@typescript-eslint/parser",
    "parserOptions": { "project": ["./tsconfig.json"] },
    "plugins": [
        "@typescript-eslint"
    ],
    "rules": {
        "@typescript-eslint/strict-boolean-expressions": [
            2,
            {
                "allowString" : false,
                "allowNumber" : false
            }
        ]
    },
    "ignorePatterns": ["src/**/*.test.ts", "src/frontend/generated/*"]
}

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 for JSON files and YAML-style comments for YAML files. ESLint safely ignores comments in configuration files. This allows your configuration files to be more human-friendly.

For JavaScript-style comments:

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

For YAML-style comments:

env:
    browser: true
rules:
    # Override default settings
    eqeqeq: warn
    strict: off

Adding Shared Settings

ESLint supports adding shared settings into configuration files. Plugins use settings to specify information that should be shared across all of its rules. You can add settings object to ESLint configuration file and it will be supplied to every rule being 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"

Cascading and Hierarchy

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

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

The configuration cascade works based on the location of the file being linted. If there is a .eslintrc file in the same directory as the file being linted, then that configuration takes precedence. ESLint then searches up the directory structure, merging any .eslintrc files it finds along the way until reaching either a .eslintrc file with root: true or the root directory.

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.json
  └── test.js

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

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 .eslintrc.* file or 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.

home
└── user
    └── projectA
        ├── .eslintrc.json  <- Not used
        └── lib
            ├── .eslintrc.json  <- { "root": true }
            └── main.js

The complete configuration hierarchy, from highest 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 (or CLIEngine equivalents):
    1. --global
    2. --rule
    3. --env
    4. -c, --config
  3. Project-level configuration:
    1. .eslintrc.* or package.json file in the same directory as the linted file
    2. Continue searching for .eslintrc.* and package.json files in ancestor directories up to and including the root directory or until a config with "root": true is found.

Please note that the home directory of the current user on your preferred operating system (~/) is also considered a root directory in this context and searching for configuration files will stop there as well. And with the removal of support for Personal Configuration Files from the 8.0.0 release forward, configuration files present in that directory will be ignored.

Extending Configuration Files

A configuration file, once extended, can inherit all the traits of another configuration file (including rules, plugins, and language options) and modify all the options. As a result, there are three configurations, as defined below:

The extends property value is either:

ESLint extends configurations recursively, so a base configuration can also have an extends property. Relative paths and shareable config names in an extends property are resolved from the location of the config file where they appear.

The eslint-config- prefix can be omitted from the configuration name. For example, airbnb resolves as eslint-config-airbnb.

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

Using a shareable configuration package

A sharable configuration is an npm package that exports a configuration object. Make sure that you have installed the package in your project root directory, so that ESLint can require it.

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

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

Example of a configuration file in YAML format:

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

Using eslint:recommended

Using "eslint:recommended" in the extends property enables a subset of core rules that report common problems (these rules are identified with a checkmark ✓ on the rules page).

Here's an example of extending eslint:recommended and overriding some of the set configuration options:

Example of a configuration file in JavaScript format:

module.exports = {
    "extends": "eslint:recommended",
    "rules": {
        // enable additional rules
        "indent": ["error", 4],
        "linebreak-style": ["error", "unix"],
        "quotes": ["error", "double"],
        "semi": ["error", "always"],

        // override configuration set by extending "eslint:recommended"
        "no-empty": "warn",
        "no-cond-assign": ["error", "always"],

        // disable rules from base configurations
         "for-direction": "off",
    }
}

Using a configuration from a plugin

A plugin is an npm package that can add various extensions to ESLint. A plugin can perform numerous functions, including but not limited to adding new rules and exporting shareable configurations. Make sure the package has been installed in a directory where ESLint can require it.

The plugins property value can omit the eslint-plugin- prefix of the package name.

The extends property value can consist of:

Example of a configuration file in JSON format:

{
    "plugins": [
        "react"
    ],
    "extends": [
        "eslint:recommended",
        "plugin:react/recommended"
    ],
    "rules": {
       "react/no-set-state": "off"
    }
}

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.

Example of a configuration file in JSON format:

{
    "extends": [
        "./node_modules/coding-standard/eslintDefaults.js",
        "./node_modules/coding-standard/.eslintrc-es6",
        "./node_modules/coding-standard/.eslintrc-jsx"
    ],
    "rules": {
        "eqeqeq": "warn"
    }
}

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 it at your own risk.

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 eslint:all, 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.

Example of a configuration file in JavaScript format:

module.exports = {
    "extends": "eslint:all",
    "rules": {
        // override default options
        "comma-dangle": ["error", "always"],
        "indent": ["error", 2],
        "no-cond-assign": ["error", "always"],

        // disable now, but enable in the future
        "one-var": "off", // ["error", "never"]

        // disable
        "init-declarations": "off",
        "no-console": "off",
        "no-inline-comments": "off",
    }
}

Configuration Based on Glob Patterns

v4.1.0+. Sometimes a more fine-controlled configuration is necessary, for example, if the configuration for files within the same directory has to be different. Therefore you can provide configurations under the overrides key that will only apply to files that match specific glob patterns, using the same format you would pass on the command line (e.g., app/**/*.test.js).

Glob patterns in overrides use minimatch syntax.

How do overrides work?

It is possible to override settings based on file glob patterns in your configuration by using the overrides key. An example of using the overrides key is as follows:

In your .eslintrc.json:

{
  "rules": {
    "quotes": ["error", "double"]
  },

  "overrides": [
    {
      "files": ["bin/*.js", "lib/*.js"],
      "excludedFiles": "*.test.js",
      "rules": {
        "quotes": ["error", "single"]
      }
    }
  ]
}

Here is how overrides work in a configuration file:

Relative glob patterns

project-root
├── app
│   ├── lib
│   │   ├── foo.js
│   │   ├── fooSpec.js
│   ├── components
│   │   ├── bar.js
│   │   ├── barSpec.js
│   ├── .eslintrc.json
├── server
│   ├── server.js
│   ├── serverSpec.js
├── .eslintrc.json

The config in app/.eslintrc.json defines the glob pattern **/*Spec.js. This pattern is relative to the base directory of app/.eslintrc.json. So, this pattern would match app/lib/fooSpec.js and app/components/barSpec.js but NOT server/serverSpec.js. If you defined the same pattern in the .eslintrc.json file within in the project-root folder, it would match all three of the *Spec files.

If a config is provided via the --config CLI option, the glob patterns in the config are relative to the current working directory rather than the base directory of the given config. For example, if --config configs/.eslintrc.json is present, the glob patterns in the config are relative to . rather than ./configs.

Specifying target files to lint

If you specified directories with CLI (e.g., eslint lib), ESLint searches target files in the directory to lint. The target files are *.js or the files that match any of overrides entries (but exclude entries that are any of files end with *).

If you specified the --ext command line option along with directories, the target files are only the files that have specified file extensions regardless of overrides entries.

Personal Configuration Files (deprecated)

⚠️ This feature has been deprecated. This feature will be removed in the 8.0.0 release. If you want to continue to use personal configuration files, please use the --config CLI option. For more information regarding this decision, please see RFC 28 and RFC 32.

~/ refers to the home directory of the current user on your preferred operating system. The personal configuration file being referred to here is ~/.eslintrc.* file, which is currently handled differently than other configuration files.

How does ESLint find personal configuration files?

If eslint could not find any configuration file in the project, eslint loads ~/.eslintrc.* file.

If eslint could find configuration files in the project, eslint ignores ~/.eslintrc.* file even if it's in an ancestor directory of the project directory.

How do personal configuration files behave?

~/.eslintrc.* files behave similarly to regular configuration files, with some exceptions:

~/.eslintrc.* files load shareable configs and custom parsers from ~/node_modules/ – similarly to require() – in the user's home directory. Please note that it doesn't load global-installed packages.

~/.eslintrc.* files load plugins from $CWD/node_modules by default in order to identify plugins uniquely. If you want to use plugins with ~/.eslintrc.* files, plugins must be installed locally per project. Alternatively, you can use the --resolve-plugins-relative-to CLI option to change the location from which ESLint loads plugins.