Linting with ESLint

What a linter does

A linter is a program that checks your code for likely mistakes. It does this before you run the code. ESLint is the most widely used linter for JavaScript. It can find things like these:

• a misspelled variable name;
• a comparison your team chose not to use, like ==;
• code after a return, which can never run;
• a value you made and then never used.

ESLint only reads your code. It doesn't run your functions or click around your page. It reads the file and checks it against a list of rules. A rule is one named check, such as "no unknown names". When a rule finds a problem, ESLint gives you a message. Each message tells you three things:

• the rule id: the rule's name, like no-undef;
• the line and column: where the problem is in the file;
• the severity: how serious the problem is, either a warning or an error.

You met strict mode, semicolons, and coding style in earlier lessons. A linter checks those habits for you while you type. You'll see two commands in this lesson. The command npm init @eslint/config@latest sets ESLint up, and the command npx eslint runs it. A later lesson explains npm and package.json. For now, you only need to know what these two commands do.

1const userName = "Asha";2console.log(userName);

Line 1 creates a variable called userName and stores "Asha" in it. Line 2 prints that variable, so you see Asha. Now imagine that line 2 says userNmae instead. No variable has that name. The no-undef rule ("no undefined names") reports it before you run the code.

The picture and the step-through below check a different two-line file. Its line 2 has a typo: totla instead of total.

1const total = 1 + 2;Run2console.log(totla);

Linting helps even when the code runs fine. The next example prints Welcome with no error. But the no-unused-vars rule ("no unused variables") points at line 1. The name made there is never used. Often that means you forgot to show it, or forgot to delete it.

1const userName = "Asha";2console.log("Welcome");

Line 1 creates userName. Line 2 prints only the word Welcome. So the output is Welcome, and userName is never used. To fix the warning, use the name.

1const userName = "Asha";2console.log("Welcome", userName);

Line 1 is the same as before. Line 2 now prints userName too, so the output is Welcome Asha. The name is used, so no-unused-vars has nothing to report.

The list that ESLint prints is like a checklist. Each item is one message, and each message names the rule that found it. In the playground below:

• Pick a snippet with the buttons at the top.
• Turn rules on and off with the rule buttons.
• Read the messages. You see the messages from every rule that is on, all in one list.

For example, the "Loose equality" snippet uses ==. When the eqeqeq rule is on, ESLint reports it. The name eqeqeq means "equals, equals, equals": always use ===.

1if (score == "10") {2  console.log("match");3}

To read a message, ask four questions:

1. Which rule found it? The rule id tells you.
2. Where is it? The line and column tell you.
3. How serious is it? The severity tells you: warning or error.
4. Can ESLint fix it for you? Some rules can make a safe change by themselves.

You can search for any rule id online. The id no-undef means "a name was used but never created". The id prefer-const means "this let never changes, so use const".

A rule is one check, like "always use ===". A config is a file that lists which rules to use. ESLint reads the config before it checks your files. ESLint 9 looks for a config file called eslint.config.js. This kind of config is called a flat config, because it exports one plain list of settings. Most configs start with ESLint's recommended rules, then add a few choices of their own.

1import js from "@eslint/js";2 3export default [4  js.configs.recommended,5  {6    languageOptions: {7      globals: {8        document: "readonly",9        console: "readonly"10      }11    },12    rules: {13      eqeqeq: "error",14      "no-unused-vars": "warn"15    }16  }17];

Line by line:

1. Line 1 loads ESLint's recommended rules from the @eslint/js package.
2. Line 4 adds those recommended rules to the config list.
3. Lines 8 and 9 tell ESLint that document and console already exist, because the browser provides them.
4. Lines 13 and 14 turn on two rules and say how serious each one is.

ESLint reads this file in Node.js when it starts. The file never runs in your web page.

Each rule gets a severity. You can write it as a word or as a number:

• "off" or 0: the rule is turned off.
• "warn" or 1: ESLint shows a warning.
• "error" or 2: ESLint shows an error.

A warning is like a sticky note: worth reading, but your work can go on. An error is like a stop sign. When npx eslint finds an error, the check fails. Teams often run the same check automatically before new code joins the shared project. That automatic check is called CI, short for "continuous integration". An error makes CI fail too. Use errors for real bugs and for rules your team never wants broken.

Warnings don't make the check fail. If you want warnings to fail it too, run npx eslint . --max-warnings 0. This is a choice each project makes. It doesn't change any rule.

The table below lists the config words you'll see most. Read each row as: the word, what it means, and an example.

A global is a name your file can use without creating it, because the place where the code runs provides it. In a browser, document is the web page. Node.js has no web page, so it has no document. Tell ESLint where your code runs. Then it won't report real names like document as typos. Mark these names readonly, unless your code is meant to replace them.

1const score = 10;2// eslint-disable-next-line eqeqeq -- legacy form value3if (score == "10") console.log("Ready");

Line by line:

1. Line 1 stores the number 10.
2. Line 2 is the disable comment. It turns off eqeqeq for the next line only. The text after -- is the reason: the value comes from an old form.
3. Line 3 uses == on purpose and prints Ready.

Keep an exception this small. Suppose line 3 changes later and no longer breaks the rule. Then ESLint can tell you that the comment isn't needed any more, if that check is turned on in the config.

ESLint can fix some problems by itself. A rule that can do this is called fixable. ESLint only makes a fix when it is sure the fix is safe. Take prefer-const. If a variable is made with let and never gets a new value, ESLint can change let to const. The program still prints the same thing.

Other rules need you to decide. If you typed totla, the no-undef rule can't know what you meant. You might have meant total, or you might want a new variable. So ESLint reports the problem and leaves the fix to you.

1let limit = 3;Run2console.log(limit);

Don't change every let to const. Use let when the variable really changes. In the next example, line 2 gives score a new value. ESLint sees that, so prefer-const reports nothing. The program prints 2.

1let score = 1;2score = 2;3console.log(score);

Line 1 sets the score to 1. Line 2 changes it to 2. Line 3 prints 2. The change on line 2 is on purpose, so let is the right choice. A lint rule is feedback about this code. It isn't an order to use one keyword everywhere.

You can also run ESLint in a terminal: the window where you type commands. The command npx eslint . checks the whole project and lists the problems. The dot means "this folder". The command npx eslint . --fix does the same, and also makes the safe fixes. The npm lesson explains npx later. For now, read it as "run ESLint on this project".

1npm init @eslint/config@latest2npx eslint .3npx eslint . --fix4npx eslint . --max-warnings 0

Line by line:

1. Line 1 starts ESLint's setup helper, which creates a config file for you.
2. Line 2 checks every file in the folder and lists the problems.
3. Line 3 does the same, and also makes the safe fixes.
4. Line 4 makes the check fail if even one warning is left.

ESLint helps most when you see its messages while you type. In VS Code, install the ESLint extension. An extension is an add-on for the editor. The ESLint extension does four things:

• It reads your project's config.
• It draws a wavy line, called a squiggle, under each problem.
• It offers quick fixes that you can click.
• It can make the safe fixes each time you save the file.

To fix on save, add the setting below to your VS Code settings. Recent versions of VS Code use the value "explicit". It means "fix when I save the file myself", not when the editor saves by itself. Older examples use true instead.

1{2  "editor.codeActionsOnSave": {3    "source.fixAll.eslint": "explicit"4  }5}

1let limit = 3;2console.log(limit);

1{2  "editor.codeActionsOnSave": {3    "source.fixAll.eslint": "explicit"4  }5}

Line 3 is the setting that matters. The name source.fixAll.eslint means "make all of ESLint's safe fixes".

The extension doesn't replace learning the rules. When you see a squiggle, read the message and look at the line. Then choose one of these:

• accept the quick fix;
• change the code yourself;
• or, if the line must break the rule, add a disable comment with a reason.

With that habit, lint messages teach you something each time.

The last lesson showed Prettier, which is a formatter. A formatter fixes how code looks: spaces, line breaks, and indentation. Then nobody has to argue about layout. A linter looks for code that is probably wrong, such as:

• names that are never used;
• names that were never created;
• code that can never run;
• code that breaks a rule your team chose.

The table compares the two tools. Read each row as: the tool, what it checks, and what it does.

Where you'll use linting

In a real project, ESLint runs in three places:

1. In your editor, which shows squiggles while you type.
2. In a terminal, where you check the whole project before you share your work.
3. In CI, the automatic check that runs before code joins the shared project.

Imagine you are building a small shopping-cart page. A linter can't tell you whether the checkout page looks good. But it can catch mistakes like these:

• cartTotal typed as cartTtoal;
• code after a return, which never runs;
• two keys in one object with the same name, where the second one quietly replaces the first.

1const limit = 3;2console.log(limit);

This is the code after the prefer-const fix. Line 1 uses const, because limit never changes. Line 2 prints 3. The fix changed line 1, but the output is still 3.

1const cart = { total: 12 };2if (cart.total == 0) {3  console.log("Your cart is empty");4} else {5  console.log("Ready to pay");6}

Line 1 makes a cart with a total of 12. Line 2 checks whether the total is 0. It isn't, so the else branch runs and prints Ready to pay. The code works, but the eqeqeq rule still reports the == on line 2. Exercise 6 asks you to fix it.

1const cart = { total: 12 };2if (cart.total === 0) {3  console.log("Your cart is empty");4} else {5  console.log("Ready to pay");6}

Only the operator changed, from == to ===. The total is still 12, so the code still prints Ready to pay. Before it compares, == can quietly turn a value into another type. For example, "0" == 0 is true, because the text "0" becomes the number 0. The === operator never does that. That's why many teams turn on eqeqeq.

1function getDrink() {2  return "tea";3  console.log("not reached");4}5 6console.log(getDrink());

Line 2 ends getDrink right away and gives back "tea". Line 3 comes after the return, so it can never run. The no-unreachable rule reports it. Line 6 prints tea. If you need line 3, move it above the return. If you don't, delete it.

1const settings = {2  theme: "dark",3  theme: "light",4};5console.log(settings.theme);

The object has two properties named theme. JavaScript keeps the last one, so line 5 prints light. This is allowed JavaScript, so nothing crashes. But it is easy to miss when you read the code. The no-dupe-keys rule ("no duplicate keys") catches it.

1const lintMessages = ["no-undef"];2const shouldMerge = lintMessages.length === 0;3console.log(shouldMerge ? "Ready to merge" : "Fix lint messages first");4console.log("First rule:", lintMessages[0]);

This code pretends to be a CI check. Line by line:

1. Line 1 is a list of lint messages. It holds one rule id: no-undef.
2. Line 2 checks whether the list is empty. It isn't, so shouldMerge is false.
3. Line 3 prints Fix lint messages first, because shouldMerge is false.
4. Line 4 prints the first rule: First rule: no-undef.

A real CI check runs ESLint itself. But the idea is the same: an error stops the code from joining the shared project.

Common misconceptions

1const cart = { total: 12 };2const discount = 20;3console.log(cart.total - discount);

ESLint finds no problem in these three lines. But line 3 prints -8: a discount of 20 taken off a cart total of 12. Can a discount be bigger than the total? ESLint can't know that. Your team decides that rule, and tests check it.

Try each question before you open the explanations. Some wrong choices look right on purpose, so read each one carefully.

Key takeaways

• A linter reads your code before it runs and reports anything that breaks a rule.
• Each ESLint message gives a rule id, a severity, a line, a column, and a short message. Some also offer a safe fix.
• A config lists the rules to use. In ESLint 9, the config file is eslint.config.js.
• Use error for problems that must stop the work, and warn for advice.
• Squiggles and fix on save in your editor let you see and fix problems while you type.
• A formatter fixes layout. A linter finds likely mistakes.

Coming next: Thinking like a developer.