Introduction
Linters are effective tools that help ensure that you're always writing your best code. By performing a static analysis of your codebase, linters provide a systematic way to minimize coding errors, ensure adherence to existing standards, and offer ways to apply a uniform style across a project.
Since JavaScript is fundamental to building applications on Stacks, you'll be introduced to a JavaScript linter in these tutorials. While there are many effective and well-known open-source linters currently available ( ESLint, JSLint, JSHint, and the JSCS JavaScript Linter ), this tutorial will focus on getting you up and running with ESLint. ESLint is a flexible and feature-rich linter with the ability to directly integrate with your development workflow while also providing a robust, command-line functionality.
NOTE:
This tutorial is NodeJS- and ESLint-specific.
This tutorial will walk you through the following steps:
Installing ESLint
Configuring ESLint
Prerequisites
Node.js (version 16.0.0 or later).
NOTE:
You can verify your installation by opening up Terminal (MacOs) or a command prompt/PowerShell window (Windows) and running the following command:
node --version
or,
node -v
Step 1: Installing ESLint
To install ESLint, run one of the following commands in a terminal window.
For a local install, navigate to the workspace folder and then run:
npm install eslint
or,
For a global install, run:
npm install -g eslint
Step 2: Configuring ESLint
One of the ways that ESLint distinguishes itself is through its use of configuration files. If your project requires it, the standard JavaScript rule set can be extended with the use of custom, modular configuration files applied to specific parts of your file hierarchy.
However, ESLint is fully functional right out of the box with the standard .eslintrc configuration file placed in your project's root directory.
NOTE:
If you would like additional information about advanced operations in ESLint, please refer to the Learning More section of this tutorial.
Prerequisites (configuration)
The ESLint configuration file set-up process assumes you already have a package.json file. If you don't, please follow the procedures below.
In a terminal window, run:
npm init
npm will echo with:
This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sensible defaults.
See `npm help init` for definitive documentation on these fields
and exactly what they do.
Use `npm install \<pkg>` afterwards to install a package and
save it as a dependency in the package.json file.
Press \^C at any time to quit.
Follow the prompts to continue setting up the package.json file.
After the package.json file has be created, run the following in a terminal window to install the package you have just created:
npm install config
If the installation was successful, npm will echo with:
added n packages, and audited m packages in 1s
found 0 vulnerabilities
Creating the configuration file (.eslintrc)
In a terminal window, run:
npm init @eslint/config
npm will echo with a series of configuration questions. Choose the responses that best apply to your development workflow.
✓ How would you like to use ESLint?
✓ What type of modules does your project use?
✓ Which framework does your project use?
✓ Does your project use TypeScript?
✓ Where does your code run?
✓ What format do you want your config file to be in?
NOTE:
If you had previously chosen a global installation of ESLint, the installer will notify you of the following:
Local ESLint installation not found.
The config that you\'ve selected requires the following dependencies:
eslint@latest
✓ Would you like to install them now with npm? No / Yes
Select Yes to install the required dependencies.
If successful, npm will echo with:
Installing eslint@latest
added n packages, and audited m packages in 6s
x packages are looking for funding
run `npm fund` for details
found 0 vulnerabilities
A config file was generated, but the config file itself may not follow your linting rules.
Successfully created .eslintrc.{ js | json\ | yml } file in \<file path>
Getting familiar with the configuration file
At this point, you should have a .eslintrc.{ js | json | yml } file in your directory.
In it, you'll find several landmarks relating to ESLint rule sets that you should become familiar with.
Extends
{
"extends": eslint:recommended
}
With this line in place, all of the rules marked with a ✓ on the rules page will be active (please see the ESLint rules section below). For more information about extending rule sets, please see the Learning More section of the tutorial.
Rules
{
"rules": {
// your rules go here
}
}
This section of the configuration file is reserved for customization of the existing ESLint rules.
NOTE:
For a discussion about the ESLint rules, please see the ESLint rule section below.
ESLint rules
A full listing of ESLint rules and their respective definitions can be found on the ESLint project site.
Categories
ESLint recognizes 3 categories of rules:
Possible problems - rules that relate to possible logic errors in code
Suggestions - rules that suggest alternate ways of doing things
Layout & Formatting - rules concerned with how the code looks rather than how it executes
Types
In addition, these categories are further distinguished with 3 different types, each denoted with a different icon on the rule page:
Icon | How the rule is handled by ESLint |
---|---|
✓ | Indicates that a rule is enabled if the "extends":"eslint:recommended" property is present in a configuration file. |
🔧 | Indicates that problems reported by the rule are automatically correctable by the --fix command-line option. |
💡 | Indicates that problems reported by the rule can be corrected manually. Suggestions are provide either through the editor (if the ESLint extension is present) or through command-line application of the eslint command. |
Customization
As noted above, ESLint allows you to tailor the behavior of rules by editing the rules property of the configuration file.
In general, adjustments are made by adding a comma-separated list of <property>-<value*> pairs in the following format:
"<rule>" : [ "<error level>", <option>]
Error level
There are 3 possible error levels for ESLint rules:
Error Level | Alternate Value | Description |
---|---|---|
off | 0 | Disables the rule |
warn | 1 | Enables the rule as a warning (no effect on exit code) |
error | 2 | Enables the rule as an error (exit code of 1) |
Exit codes
When linting files, ESLint will exit with one of the following exit codes:
Exit code | Definition |
---|---|
0 | Linting was successful and there are no linting errors |
1 | Linting was successful and there is at least one linting error, or there are more linting warnings than allowed by the --max-warnings option |
2 | Linting was unsuccessful due to a configuration problem or an internal error |
Option
This values instructs ESLint on how it should interpret a particular rule when parsing code.
NOTE:
When an option for a rule is a compound expression (e.g, a \<property>-\<value> pair), enclose the entire option in curly brackets.
Example
Consider the following rules property of this .eslintrc configuration:
{
"rules": {
"function-paren-newline": ["error", "multiline"],
"keyword-spacing": ["error", { "after": true }],
"semi": ["error", "always"]
}
}
In the sample rules property defined above, the second entry specifies how ESLint should parse the rule for keyword-spacing. In this instance, the rule is configured with the following properties:
<error level> = error
<option> = "after": true
Since the option is a compound expression, curly brackets will need to be used when writing the rules configuration following the format defined above:
"<rule>" : [ "<error level>", <option> ]
So, in the case for keyword-spacing, the configuration becomes:
"keyword-spacing": ["error", { "after": true } ]
Reference
Rules | Options | Definition |
---|---|---|
function-paren-newline | "always", "never", "multiline", "multiline-arguments", "consistent", "minItems": value | enforces consistent line breaks inside function parentheses |
keyword-spacing | "before": true, "before": false, "after": true, "after": false, "overrides" | enforces consistent spacing before and after keywords |
semi | "always", "never" | requires or disallows semicolons instead of automatic semicolon insertion (ASI) |