- Configuration File Formats
- Using Configuration Files
- Adding Shared Settings
- Cascading and Hierarchy
- Extending Configuration Files
- Configuration Based on Glob Patterns
- Personal Configuration Files
ESLint supports configuration files in several formats:
- JavaScript - use
.eslintrc.jsand export an object containing your configuration. - JavaScript (ESM) - use
.eslintrc.cjswhen running ESLint in JavaScript packages that specify"type":"module"in theirpackage.json. Note that ESLint does not support ESM configuration at this time. - YAML - use
.eslintrc.yamlor.eslintrc.ymlto define the configuration structure. - JSON - use
.eslintrc.jsonto define the configuration structure. ESLint's JSON files also allow JavaScript-style comments. - package.json - create an
eslintConfigproperty in yourpackage.jsonfile and define your configuration there.
If there are multiple configuration files in the same directory, ESLint will only use one. The priority order is as follows:
.eslintrc.js.eslintrc.cjs.eslintrc.yaml.eslintrc.yml.eslintrc.jsonpackage.json
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/*"]
}
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
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"
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:
- Inline configuration
/*eslint-disable*/and/*eslint-enable*//*global*//*eslint*//*eslint-env*/
- Command line options (or CLIEngine equivalents):
--global--rule--env-c,--config
- Project-level configuration:
.eslintrc.*orpackage.jsonfile in the same directory as the linted file- Continue searching for
.eslintrc.*andpackage.jsonfiles in ancestor directories up to and including the root directory or until a config with"root": trueis 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.
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:
- Base config: the configuration that is extended.
- Derived config: the configuration that extends the base configuration.
- Resulting actual config: the result of merging the derived configuration into the base configuration.
The extends property value is either:
- a string that specifies a configuration (either a path to a config file, the name of a shareable config,
eslint:recommended, oreslint:all) - an array of strings where each additional configuration extends the preceding configurations
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:
- 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"]
- Base config:
- 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"]
- Base config:
- override options for rules given as object from base configurations:
- Base config:
"max-lines": ["error", { "max": 200, "skipBlankLines": true, "skipComments": true }] - Derived config:
"max-lines": ["error", { "max": 100 }] - Resulting actual config:
"max-lines": ["error", { "max": 100 }]whereskipBlankLinesandskipCommentsdefault tofalse
- Base config:
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" 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",
}
}
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:
plugin:- the package name (from which you can omit the prefix, for example,
reactis short foreslint-plugin-react) /- the configuration name (for example,
recommended)
Example of a configuration file in JSON format:
{
"plugins": [
"react"
],
"extends": [
"eslint:recommended",
"plugin:react/recommended"
],
"rules": {
"react/no-set-state": "off"
}
}
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"
}
}
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",
}
}
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.
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:
- The patterns are applied against the file path relative to the directory of the config file. For example, if your config file has the path
/Users/john/workspace/any-project/.eslintrc.jsand the file you want to lint has the path/Users/john/workspace/any-project/lib/util.js, then the pattern provided in.eslintrc.jswill be executed against the relative pathlib/util.js. - Glob pattern overrides have higher precedence than the regular configuration in the same config file. Multiple overrides within the same config are applied in order. That is, the last override block in a config file always has the highest precedence.
- A glob specific configuration works almost the same as any other ESLint config. Override blocks can contain any configuration options that are valid in a regular config, with the exception of
rootandignorePatterns.- A glob specific configuration can have an
extendssetting, but therootproperty in the extended configs is ignored. TheignorePatternsproperty in the extended configs is used only for the files the glob specific configuration matched. - Nested
overridessetting will be applied only if the glob patterns of both of the parent config and the child config matched. This is the same when the extended configs have anoverridessetting.
- A glob specific configuration can have an
- Multiple glob patterns can be provided within a single override block. A file must match at least one of the supplied patterns for the configuration to apply.
- Override blocks can also specify patterns to exclude from matches. If a file matches any of the excluded patterns, the configuration won't apply.
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.
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.
--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.
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.
~/.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.
