Core Concepts

Understanding the fundamental building blocks of ESLint including rules, plugins, parsers, and more

Core Concepts

ESLint is a configurable JavaScript linter that helps you find and fix problems in your code. This page covers the core concepts you need to understand to use ESLint effectively.

What is ESLint?

ESLint is a tool for identifying and reporting on patterns found in ECMAScript/JavaScript code. Problems can be anything from potential runtime bugs, to not following best practices, to styling issues.

AST-Based

Uses an Abstract Syntax Tree to evaluate patterns in code

Pluggable

Every single rule is a plugin - add more at runtime

Configurable

Customize which rules to enforce and how

Rules

Rules are the core building block of ESLint. A rule validates if your code meets a certain expectation, and what to do if it doesn’t.

ESLint contains hundreds of built-in rules that you can use. You can also create custom rules or use rules from plugins.

Understanding Rules

Each rule has:

Rule ID

A unique identifier like semi, no-unused-vars, or prefer-const.

{
  rules: {
    "semi": "error",
    "no-unused-vars": "warn"
  }
}

Severity Level

Three severity levels control enforcement:

• "off" or 0 - Turn the rule off
• "warn" or 1 - Turn on as a warning (doesn’t affect exit code)
• "error" or 2 - Turn on as an error (exit code will be 1)

{
  rules: {
    "semi": "error",      // or 2
    "quotes": "warn",     // or 1
    "no-console": "off"   // or 0
  }
}

Options

Many rules accept additional configuration options:

{
  rules: {
    "semi": ["error", "always"],
    "quotes": ["error", "double"],
    "no-unused-vars": ["error", { 
      "argsIgnorePattern": "^_" 
    }]
  }
}

The first item in the array is always the severity level.

Rule Categories

ESLint rules fall into different categories:

Problem

Possible Errors

These rules identify code that could cause runtime errors:

• no-unused-vars - Variables that are declared but never used
• no-undef - Undefined variables
• use-isnan - Require isNaN() when checking for NaN

// ❌ Bad
let x = 5;
if (y != NaN) { } // y is not defined, NaN comparison

// ✅ Good
let x = 5;
console.log(x);
if (!Number.isNaN(x)) { }

Suggestion

Best Practices

These rules suggest better ways to write your code:

• prefer-const - Use const for variables that are never reassigned
• no-else-return - Disallow unnecessary else after return
• eqeqeq - Require === and !== instead of == and !=

// ❌ Bad
let x = 5;
if (condition) {
  return true;
} else {
  return false;
}

// ✅ Good
const x = 5;
if (condition) {
  return true;
}
return false;

Layout

Stylistic Issues

These rules enforce consistent code formatting:

• semi - Require or disallow semicolons
• indent - Enforce consistent indentation
• quotes - Enforce consistent quote style

// With "semi": ["error", "always"]
const x = 5;  // ✅
const y = 10  // ❌

// With "quotes": ["error", "double"]
const msg = "hello";  // ✅
const msg = 'hello';  // ❌

Many formatting rules are being deprecated in favor of dedicated formatters like Prettier or ESLint Stylistic.

Rule Fixes

Rules may provide automatic fixes for violations:

Fixes 🔧

Safe, Automatic Corrections

• Don’t change application logic
• Applied with --fix CLI option
• Available in editor extensions

npx eslint --fix file.js

Suggestions 💡

Manual Review Required

• May change application logic
• Require manual review
• Only available in editors

Must be applied manually in your editor.

Configuration Files

An ESLint configuration file is where you configure ESLint for your project:

eslint.config.js

import { defineConfig } from "eslint/config";
import js from "@eslint/js";

export default defineConfig([
  {
    files: ["**/*.js"],
    plugins: { js },
    extends: ["js/recommended"],
    rules: {
      "prefer-const": "warn",
      "no-constant-binary-expression": "error"
    }
  }
]);

Configuration files can include:

• Built-in rules and their enforcement levels
• Plugins with custom rules
• Shareable configurations
• File patterns to apply rules to
• Language options (ECMAScript version, globals, etc.)
• Parser configuration

Learn more about Configuration →

Shareable Configurations

Shareable configurations are ESLint configurations distributed via npm:

import airbnbConfig from "eslint-config-airbnb-base";
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    files: ["**/*.js"],
    extends: [airbnbConfig],
    rules: {
      // Override specific rules
      "no-console": "off"
    }
  }
]);

eslint-config-airbnb-base

Popular Airbnb JavaScript style guide

eslint-config-standard

JavaScript Standard Style

eslint-config-google

Google JavaScript style guide

@eslint/js

ESLint’s recommended configuration

Plugins

Plugins are npm modules that can contain:

• Rules - Custom ESLint rules
• Configurations - Predefined rule configurations
• Processors - Extract JavaScript from other file types
• Environments - Predefined global variables

Using Plugins

import reactPlugin from "eslint-plugin-react";
import typescriptPlugin from "@typescript-eslint/eslint-plugin";
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    files: ["**/*.jsx"],
    plugins: {
      react: reactPlugin
    },
    rules: {
      "react/jsx-uses-react": "error",
      "react/jsx-uses-vars": "error"
    }
  },
  {
    files: ["**/*.ts"],
    plugins: {
      "@typescript-eslint": typescriptPlugin
    },
    rules: {
      "@typescript-eslint/no-explicit-any": "warn"
    }
  }
]);

When using plugin rules, prefix the rule ID with the plugin namespace: "plugin-namespace/rule-name"

Popular Plugins

@typescript-eslint

TypeScript support for ESLint:

import tsPlugin from "@typescript-eslint/eslint-plugin";
import tsParser from "@typescript-eslint/parser";

export default [
  {
    files: ["**/*.ts"],
    plugins: { "@typescript-eslint": tsPlugin },
    languageOptions: { parser: tsParser },
    rules: {
      "@typescript-eslint/no-unused-vars": "error"
    }
  }
];

eslint-plugin-react

React-specific linting rules:

import reactPlugin from "eslint-plugin-react";

export default [
  {
    files: ["**/*.jsx"],
    plugins: { react: reactPlugin },
    rules: {
      "react/prop-types": "error",
      "react/jsx-key": "error"
    }
  }
];

@angular-eslint

Angular framework best practices:

import angularPlugin from "@angular-eslint/eslint-plugin";

export default [
  {
    files: ["**/*.component.ts"],
    plugins: { "@angular-eslint": angularPlugin },
    rules: {
      "@angular-eslint/component-selector": "error"
    }
  }
];

Parsers

Parsers convert code into an Abstract Syntax Tree (AST) that ESLint can evaluate:

Espree (Default)

Built-in JavaScript Parser

ESLint’s default parser, compatible with standard JavaScript runtimes:

export default [
  {
    languageOptions: {
      // espree is used by default
      ecmaVersion: "latest",
      sourceType: "module"
    }
  }
];

Supports all standard ECMAScript features.

@typescript-eslint/parser

TypeScript Parser

Parse TypeScript code:

import tsParser from "@typescript-eslint/parser";

export default [
  {
    files: ["**/*.ts"],
    languageOptions: {
      parser: tsParser,
      parserOptions: {
        project: "./tsconfig.json"
      }
    }
  }
];

@babel/eslint-parser

Babel Parser

Parse experimental JavaScript features:

import babelParser from "@babel/eslint-parser";

export default [
  {
    languageOptions: {
      parser: babelParser,
      parserOptions: {
        requireConfigFile: false
      }
    }
  }
];

Custom parsers are often included as part of shareable configurations or plugins, so you may not need to configure them directly.

Processors

Processors extract JavaScript code from other file types or manipulate code before parsing:

import markdown from "@eslint/markdown";
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    files: ["**/*.md"],
    plugins: { markdown },
    processor: "markdown/markdown"
  },
  {
    files: ["**/*.md/*.js"],
    rules: {
      // Rules for JavaScript code blocks in Markdown
      "no-console": "off"
    }
  }
]);

@eslint/markdown

Lint JavaScript code inside Markdown code blocks

eslint-plugin-vue

Extract and lint JavaScript from Vue single-file components

Formatters

Formatters control the appearance of linting results in the CLI:

stylish (default)

npx eslint --format stylish file.js

Human-readable format with colors and context.

json

npx eslint --format json file.js

JSON output for programmatic processing.

html

npx eslint --format html file.js > report.html

Visual HTML report for browsers.

Custom

npx eslint --format ./my-formatter.js file.js

Use your own custom formatter.

Learn more about Formatters →

Integrations

ESLint integrates with many development tools:

VS Code

ESLint Extension provides real-time feedback

WebStorm

Built-in ESLint support

Vim

ALE and Syntastic plugins

Webpack

eslint-webpack-plugin

Rollup

@rollup/plugin-eslint

Git Hooks

Lint on pre-commit

Learn more about Integrations →

CLI & Node.js API

CLI

Command Line Interface

Execute linting from the terminal:

npx eslint [options] [file|dir|glob]*

The CLI has many options for:

• Specifying files to lint
• Configuring output format
• Enabling auto-fix
• Setting up caching
• And much more

View CLI Documentation →

Node.js API

Programmatic API

Use ESLint programmatically:

import { ESLint } from "eslint";

const eslint = new ESLint();
const results = await eslint.lintFiles(["src/**/*.js"]);
const formatter = await eslint.loadFormatter("stylish");
const resultText = formatter.format(results);
console.log(resultText);

Useful for:

• Developing plugins and integrations
• Building custom tools
• Programmatic linting in Node.js

Unless you are extending ESLint in some way, you should use the CLI.

How ESLint Works

1. Parse Code

   ESLint uses a parser (default: Espree) to convert your code into an Abstract Syntax Tree (AST).

2. Traverse AST

   ESLint walks through the AST nodes, triggering rule checks at specific node types.

3. Apply Rules

   Each rule examines AST nodes and reports violations based on configured severity.

4. Generate Report

   ESLint collects all violations and formats them using the selected formatter.

5. Apply Fixes (Optional)

   If --fix is used, ESLint applies safe automatic fixes to your code.

Quick Reference

Rule Severity Levels

Level	String	Number	Behavior
Off	"off"	0	Rule is disabled
Warning	"warn"	1	Reported but doesn’t affect exit code
Error	"error"	2	Reported and causes exit code 1

Configuration File Names

• eslint.config.js - JavaScript (ESM or CommonJS)
• eslint.config.mjs - JavaScript (ESM only)
• eslint.config.cjs - JavaScript (CommonJS only)
• eslint.config.ts - TypeScript (requires jiti)
• eslint.config.mts - TypeScript ESM
• eslint.config.cts - TypeScript CommonJS

Common CLI Commands

# Basic linting
npx eslint .

# Auto-fix issues
npx eslint --fix .

# Use specific config
npx eslint -c my-config.js src/

# Output JSON
npx eslint --format json src/

# Initialize config
npx eslint --init

Exit Codes

• 0 - Linting successful, no errors
• 1 - Linting successful, but errors found
• 2 - Linting failed (configuration problem or internal error)

Related Resources

Configuration

Learn how to configure ESLint

Rules

Configure rule severity and options

Command Line

CLI options and usage

Formatters

Output format options