Customizing ESLint with eslintrc

Learn how to create a project that uses ESLint and configure ESLint with the eslintrc file.

Table of Contents 📖

• What is ESLint?
• Creating an ESLint Project
• Installing and Configuring ESLint
• Running ESLint against Project Directory
• eslintrc File
• eslintrc Environment
• eslintrc ParserOptions
• eslintrc overrides

What is ESLint?

ESLint is a tool that analyzes JavaScript code for problems, whether it be code quality or style issues. It does this by following a set of configurable/customizable rules defined inside a file called eslintrc, the configuration file for ESLint. The eslintrc file tells ESLint what to look for and enforce in JavaScript code.

Creating an ESLint Project

To start working with ESLint, create a directory to hold our JavaScript code and ESLint configuration.

mkdir customizing-eslint-with-eslintrc
cd customizing-eslint-with-eslintrc

Now, lets initialize our project as an ES6 npm project by running npm init es6 -y.

npm init es6 -y

Now create a src folder to hold our source code and add an index.js file to it.

mkdir src
cd src
touch index.js

Now lets add some simple code to this index.js file that we can pass to ESLint to check for code quality/style.

const hello = "hello";
const longLine = "aslkfdja;sdlkfja;dslfkja;dslfkja;sdlfkjas;dlfkjad;slfkjads;lfkjasd;lfkjasd;lfkajds;flkajdfkl"

Installing and Configuring ESLint

Now lets install ESLint, which is simply an npm package called eslint. Install it as a development dependency by tagging on -D.

npm i eslint -D

Now, set up an ESLint configuration file by running the command npm init @eslint/config.

npm init @eslint/config

This command creates the eslintrc file to configure ESLint. Select the options displayed in the GIF below. Each selected option will alter the end result of the ESLint configuration file.

The contents of the ESLint configuration file should be as follows.

module.exports = {
    'env': {
        'es2021': true,
        'node': true
    },
    'extends': 'eslint:recommended',
    'overrides': [
        {
            'env': {
                'node': true
            },
            'files': [
                '.eslintrc.{js,cjs}'
            ],
            'parserOptions': {
                'sourceType': 'script'
            }
        }
    ],
    'parserOptions': {
        'ecmaVersion': 'latest',
        'sourceType': 'module'
    },
    'rules': {
        'indent': [
            'error',
            'tab'
        ],
        'linebreak-style': [
            'error',
            'unix'
        ],
        'quotes': [
            'error',
            'single'
        ],
        'semi': [
            'error',
            'always'
        ]
    }
};

Running ESLint against Project Directory

Now that we have ESLint installed and configured, we can create a script to run it against certain files or directories. Inside package.json, add the following under scripts.

"lint": "eslint ./src"

This command runs our src folder through ESLint to check for errors based on our eslintrc configuration file. To run this command, run npm run lint in the terminal.

npm run lint
1:7    error  'hello' is assigned a value but never used            no-unused-vars
1:15   error  Strings must use singlequote                          quotes
2:7    error  'longLine' is assigned a value but never used         no-unused-vars
2:18   error  Strings must use singlequote                          quotes
2:112  error  Missing semicolon                                     semi
  
✖ 5 problems (5 errors, 0 warnings)
  3 errors and 0 warnings potentially fixable with the `--fix` option.

Here, ESLint uses our eslintrc file to see the standards that the JavaScript code inside the src folder should follow.

eslintrc File

The eslintrc file exports an object that is used to configure ESLint. Each key and property in this file tells ESLint what the syntax and style of our code should be. The rules key of this exported object contains an object where each key is an ESLint rule. Here, we have 4 rules: indent, linebreak-style, quotes, and semi.

'rules': {
    'indent': [
        'error',
        'tab'
    ],
    'linebreak-style': [
        'error',
        'unix'
    ],
    'quotes': [
        'error',
        'single'
    ],
    'semi': [
        'error',
        'always'
    ]
}

Each of these rules takes an array where the first argument is the error level of the rule. Here, each rule is set to error meaning if that quality/style is not followed it will be an error. There are two other options.

• off - the rule is turned off
• warn - the rule is only a warning and does not affect the code

The linebreak-style rule enforces consistent line endings. If they aren't unix, or \n, then there will be an error. The semi rule says that we require semicolons at the end of statements. The quotes rule requires that we use single quotes. The indent rule enforces the indentation style to be tabs. It is because of these rules that we see the following output when we lint our index.js file.

npm run lint
1:7    error  'hello' is assigned a value but never used            no-unused-vars
1:15   error  Strings must use singlequote                          quotes
2:7    error  'longLine' is assigned a value but never used         no-unused-vars
2:18   error  Strings must use singlequote                          quotes
2:112  error  Missing semicolon                                     semi
  
✖ 5 problems (5 errors, 0 warnings)
  3 errors and 0 warnings potentially fixable with the `--fix` option.

Note the name of the rule causing the error on the right. However, there is a rule here that isn't specified in the rules array but it is still being checked. This is the no-unused-vars rule. This rule comes from the extends part of our eslintrc file.

'extends': 'eslint:recommended',

The extends property extends from a set of rule configurations from the value provided to it. Here this is the eslint:recommended configuration which is the base recommended ESLint rules. If we want to overwrite the no-unused-vars rule behavior we can set it to off in the rules section of eslintrc.

'no-unused-vars': [
    'off'
],

Now if we lint our src folder again we will see that this error has disappeared.

npm run lint
1:15   error  Strings must use singlequote  quotes
2:18   error  Strings must use singlequote  quotes
2:112  error  Missing semicolon             semi

✖ 3 problems (3 errors, 0 warnings)
3 errors and 0 warnings potentially fixable with the `--fix` option.

ESLint rules are separated into different categories such as styling and formatting, suggestions, or possible problems. Lets add a rule not included in the recommended extension. The max line length rule.

'max-len': [
    'error',
    {
        'code': 60
    }
]

Because of this rule, ESLint will now show an error whenever there is a line longer than 60 characters. We can also see that the second argument provided to each rule array is dependent on the rule. For example, this max length rule takes an object while the quotes rule takes one of the strings double, single, or backtick. One of the properties provided to the max length rule is code which enforces the maximum line length and has a default value of 80. Now if we run our linter again we will see the max length error.

npm run lint
1:15   error  Strings must use singlequote                          quotes
2:1    error  This line has a length of 111. Maximum allowed is 60  max-len
2:18   error  Strings must use singlequote                          quotes
2:112  error  Missing semicolon                                     semi

✖ 4 problems (4 errors, 0 warnings)
3 errors and 0 warnings potentially fixable with the `--fix` option.

eslintrc Environment

The behavior of ESLint is also impacted by the env property of eslintrc. The env property defines the environment that the JavaScript code is expected to run in.

'env': {
	'es2021': true,
	'node': true
},

Here we set the env to node and es2021. This means ESLint will expect global node and ECMAScript 2021 variables. For example, if we try to use the window variable eslint will throw a no-undef error. To demonstrate, add window to our index.js file.

const hello = "hello";
const longLine = "aslkfdja;sdlkfja;dslfkja;dslfkja;sdlfkjas;dlfkjad;slfkjads;lfkjasd;lfkjasd;lfkajds;flkajdfkl"
window.alert();

Then run npm run lint.

npm run lint
/Users/wittcode/Desktop/custom-eslint-rules/src/index.js
1:15   error  Strings must use singlequote                          quotes
2:1    error  This line has a length of 111. Maximum allowed is 60  max-len
2:18   error  Strings must use singlequote                          quotes
2:112  error  Missing semicolon                                     semi
3:1    error  'window' is not defined                               no-undef

✖ 5 problems (5 errors, 0 warnings)
3 errors and 0 warnings potentially fixable with the`--fix` option.

Here window is undefined as the env is set to node. ESLint would not throw a no-undef error for the window variable if we set the env to browser.

eslintrc ParserOptions

The behavior of ESLint is also impacted by the parserOptions property. This property enables support for JavaScript language options such as JSX.

'parserOptions': {
	'ecmaVersion': 'latest',
	'sourceType': 'module'
},

Here, we have sourceType set to module which enables ECMAScript modules or import/export. The ecmaVersion key specifies the version of ECMAScript syntax to use. By default this is ECMAScript 5.

eslintrc overrides

The final part of our eslintrc file to discuss is the overrides key. The overrides section allows us to provide configurations to a specific glob pattern.

'overrides': [
	{
		'env': {
			'node': true
		},
		'files': [
			'.eslintrc.{js,cjs}'
		],
		'parserOptions': {
			'sourceType': 'script'
		}
	}
],

Here, we are saying that the .eslintrc.js or .eslintrc.cjs files have the environment set to node and the sourceType set to script. This is different from the rest of the ESLint configuration which has sourceType set to module. To further demonstrate, lets create another override for a file called special.js.

{
	'files': [
		'special.js'
	],
	'rules': {
		'quotes': [
			'error',
			'double'
		]
	}
}

This makes it so if quotes are not double quotes inside special.js, then ESLint will see this as an error. Now create our special.js file inside the src folder.

cd src
touch special.js

Now add a variable that uses single quotes.

const special = 'this is a special file';

Then run npm run lint.

npm run lint
/Users/wittcode/Desktop/custom-eslint-rules/src/special.js
1:17  error  Strings must use doublequote quotes

We can now see a separate output for the special.js file indicating that strings must use double quotes. This is different from our index.js file which uses single quotes.