@sam.mills/eslint-config

Eslint Config

An opinionated custom ESLint configuration since 2019 with rigid rules for spacing, bracket and comma usage. This ESLint configuration extends the eslint:recommended preset. Justifications for the ruleset can be found on my blog, the emphasis on the chosen rule values are to ensure readability and consistency.

Notable rule values include:

• Indentation: 4 spaces.
• Quotes: double.
• Commas: always after and multiline dangling.
• Semi colons: always.
• Line length: comments and code, 120 characters.
• Brace style: stroustrup.
• Operator newlines: always before.
• One variable per line.
• Spaces around operators.

Install

First ensure Node.js and the Node Package Manager (NPM) is installed on the machine and open a terminal within the root directory of the project that will have ESLint and this configuration installed and applied, then install this configuration module from NPM:

npm install @sam.mills/eslint-confg --save-dev

The eslint module is marked as a peer dependency and should be installed automatically alongside the configuration module in newer versions of NPM (>=8), this simplifies the installation process such that installing and updating the configuration module will install or update the eslint module version.

Finally, create an .eslintrc.json file within the project root directory, and extend the default configuration:

{
    "root": true,
    "env": {
        "node": true,
        "mocha": true
    },
    "parserOptions": {
        "ecmaVersion": "latest"
    },
    "extends": [
        "@sam.mills/eslint-config/default"
    ]
}

The .eslintrc.json file is used to inform the eslint module which linting rules should be applied, as well as supplementary information about the environment, including the European Computer Manufacturers Association (ECMA) Script (ECMAScript/ECMA-262/ES) version, runtime environment, and the use of testing frameworks.

It is recommended to use a JavaScript Object Notation (JSON) format instead of a JavaScript (JS) file for configuration values to reduce risk of unexpected code execution and to benefit from editor schema validation.

The configuration provided is intended for a Node.js environment with the mocha testing framework, with JavaScript versions ES6 (ES2015) to ES12 (ES2021). TypeScript is not supported by the provided configuration, but could be easily modified to do so.

IDE Integration: Editor Config File

To assist the Integrated Development Environment (IDE) with application of certain rules, a .editorconfig file can be included:

# editorconfig.org
root = true

[*]
end_of_line = lf
charset = utf-8
max_line_length = 120

# Whitespace Control
insert_final_newline = true
trim_trailing_whitespace = true

# Indentation Style
indent_style = space
indent_size = 4

The editorconfig file will enforce the following rules across all files (regardless of file extension):

• Unix-style line endings.
• 8-bit Unicode Transformation Format (UTF-8) character encoding.
• Max line length: 120 characters.
• Ensure blank line at the end of the file.
• Ensure no trailing whitespace.
• Ensure indents are always 4 spaces, and not using tab.

Once created or updated, the IDE may need to restart in order to read and apply the editorconfig.

ESLint Ignore

An ignore file can be included at .eslintignore or within the package.json file itself, consisting of a list of files for which ESLint should not apply.

Default rules:

• Dot-files (files and folders beginning with a period: .)
• Node Modules (./node_modules).

If dot-files are required to be linted, then they should be added to the list, preceded with an exclamation-mark: !, akin to the .gitignore syntax.

Proposed .eslintignore file:

build/
coverage/
dist/
doc/
logs/
out/

NPM Scripts

For convenience, ESLint commands can be declared within the package.json file and executed with npm run. Notation for script naming is recommended as ${script}:${action} where script defines the script, e.g. lint and action defines the activity that the script will perform:

• lint: Performs default linting of the code, flags all errors and warnings.
• lint:config: Returns the config for a given file.
• lint:fix: Performs linting and fixing where possible. Unfixable errors and warnings are still flagged.

An example package.json script object is provided:

{
    "lint": "eslint .",
    "lint:config": "eslint --print-config src/index.js",
    "lint:fix": "eslint . --fix"
}

Usage

ESLint is used to find errors and warnings within JavaScript code, depending on a given ruleset, log or fix them automatically. Within the NPM Scripts section, example commands are defined.

To process files and fix ESLint problems automatically without the NPM script defined:

eslint . --fix

To process files and fix ESLint problems automatically with the defined NPM script:

npm run lint:fix

Use of the NPM script is preferred for reducing human error and enabling compatibility with IDEs that prevent execution of non-scoped commands.