> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/eslint/eslint/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<CardGroup cols={3}>
  <Card title="AST-Based" icon="diagram-project">
    Uses an Abstract Syntax Tree to evaluate patterns in code
  </Card>

  <Card title="Pluggable" icon="puzzle-piece">
    Every single rule is a plugin - add more at runtime
  </Card>

  <Card title="Configurable" icon="sliders">
    Customize which rules to enforce and how
  </Card>
</CardGroup>

## 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.

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

### Understanding Rules

Each rule has:

<AccordionGroup>
  <Accordion title="Rule ID" icon="tag">
    A unique identifier like `semi`, `no-unused-vars`, or `prefer-const`.

    ```javascript theme={null}
    {
      rules: {
        "semi": "error",
        "no-unused-vars": "warn"
      }
    }
    ```
  </Accordion>

  <Accordion title="Severity Level" icon="signal">
    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)

    ```javascript theme={null}
    {
      rules: {
        "semi": "error",      // or 2
        "quotes": "warn",     // or 1
        "no-console": "off"   // or 0
      }
    }
    ```
  </Accordion>

  <Accordion title="Options" icon="cog">
    Many rules accept additional configuration options:

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

    The first item in the array is always the severity level.
  </Accordion>
</AccordionGroup>

### Rule Categories

ESLint rules fall into different categories:

<Tabs>
  <Tab title="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

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

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

  <Tab title="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 !=

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

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

  <Tab title="Layout">
    **Stylistic Issues**

    These rules enforce consistent code formatting:

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

    ```javascript theme={null}
    // With "semi": ["error", "always"]
    const x = 5;  // ✅
    const y = 10  // ❌

    // With "quotes": ["error", "double"]
    const msg = "hello";  // ✅
    const msg = 'hello';  // ❌
    ```
  </Tab>
</Tabs>

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

## Rule Fixes

Rules may provide automatic fixes for violations:

<CardGroup cols={2}>
  <Card title="Fixes 🔧" icon="wrench">
    **Safe, Automatic Corrections**

    * Don't change application logic
    * Applied with `--fix` CLI option
    * Available in editor extensions

    ```bash theme={null}
    npx eslint --fix file.js
    ```
  </Card>

  <Card title="Suggestions 💡" icon="lightbulb">
    **Manual Review Required**

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

    Must be applied manually in your editor.
  </Card>
</CardGroup>

## Configuration Files

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

```javascript eslint.config.js theme={null}
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"
    }
  }
]);
```

<Info>
  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
</Info>

[Learn more about Configuration →](./configuration)

## Shareable Configurations

Shareable configurations are ESLint configurations distributed via npm:

```javascript theme={null}
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"
    }
  }
]);
```

<CardGroup cols={2}>
  <Card title="eslint-config-airbnb-base" icon="plane">
    Popular Airbnb JavaScript style guide
  </Card>

  <Card title="eslint-config-standard" icon="star">
    JavaScript Standard Style
  </Card>

  <Card title="eslint-config-google" icon="google">
    Google JavaScript style guide
  </Card>

  <Card title="@eslint/js" icon="js">
    ESLint's recommended configuration
  </Card>
</CardGroup>

## 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

```javascript theme={null}
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"
    }
  }
]);
```

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

### Popular Plugins

<AccordionGroup>
  <Accordion title="@typescript-eslint" icon="code">
    TypeScript support for ESLint:

    ```javascript theme={null}
    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"
        }
      }
    ];
    ```
  </Accordion>

  <Accordion title="eslint-plugin-react" icon="react">
    React-specific linting rules:

    ```javascript theme={null}
    import reactPlugin from "eslint-plugin-react";

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

  <Accordion title="@angular-eslint" icon="a">
    Angular framework best practices:

    ```javascript theme={null}
    import angularPlugin from "@angular-eslint/eslint-plugin";

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

## Parsers

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

<Tabs>
  <Tab title="Espree (Default)">
    **Built-in JavaScript Parser**

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

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

    Supports all standard ECMAScript features.
  </Tab>

  <Tab title="@typescript-eslint/parser">
    **TypeScript Parser**

    Parse TypeScript code:

    ```javascript theme={null}
    import tsParser from "@typescript-eslint/parser";

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

  <Tab title="@babel/eslint-parser">
    **Babel Parser**

    Parse experimental JavaScript features:

    ```javascript theme={null}
    import babelParser from "@babel/eslint-parser";

    export default [
      {
        languageOptions: {
          parser: babelParser,
          parserOptions: {
            requireConfigFile: false
          }
        }
      }
    ];
    ```
  </Tab>
</Tabs>

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

## Processors

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

```javascript theme={null}
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"
    }
  }
]);
```

<CardGroup cols={2}>
  <Card title="@eslint/markdown" icon="markdown">
    Lint JavaScript code inside Markdown code blocks
  </Card>

  <Card title="eslint-plugin-vue" icon="v">
    Extract and lint JavaScript from Vue single-file components
  </Card>
</CardGroup>

## Formatters

Formatters control the appearance of linting results in the CLI:

<Tabs>
  <Tab title="stylish (default)">
    ```bash theme={null}
    npx eslint --format stylish file.js
    ```

    Human-readable format with colors and context.
  </Tab>

  <Tab title="json">
    ```bash theme={null}
    npx eslint --format json file.js
    ```

    JSON output for programmatic processing.
  </Tab>

  <Tab title="html">
    ```bash theme={null}
    npx eslint --format html file.js > report.html
    ```

    Visual HTML report for browsers.
  </Tab>

  <Tab title="Custom">
    ```bash theme={null}
    npx eslint --format ./my-formatter.js file.js
    ```

    Use your own custom formatter.
  </Tab>
</Tabs>

[Learn more about Formatters →](./formatters)

## Integrations

ESLint integrates with many development tools:

<CardGroup cols={3}>
  <Card title="VS Code" icon="microsoft">
    ESLint Extension provides real-time feedback
  </Card>

  <Card title="WebStorm" icon="w">
    Built-in ESLint support
  </Card>

  <Card title="Vim" icon="code">
    ALE and Syntastic plugins
  </Card>

  <Card title="Webpack" icon="cube">
    eslint-webpack-plugin
  </Card>

  <Card title="Rollup" icon="circle">
    @rollup/plugin-eslint
  </Card>

  <Card title="Git Hooks" icon="git-alt">
    Lint on pre-commit
  </Card>
</CardGroup>

[Learn more about Integrations →](./integrations)

## CLI & Node.js API

<Tabs>
  <Tab title="CLI">
    **Command Line Interface**

    Execute linting from the terminal:

    ```bash theme={null}
    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 →](./command-line)
  </Tab>

  <Tab title="Node.js API">
    **Programmatic API**

    Use ESLint programmatically:

    ```javascript theme={null}
    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
  </Tab>
</Tabs>

<Note>
  Unless you are extending ESLint in some way, you should use the CLI.
</Note>

## How ESLint Works

<Steps>
  <Step title="Parse Code">
    ESLint uses a parser (default: Espree) to convert your code into an Abstract Syntax Tree (AST).
  </Step>

  <Step title="Traverse AST">
    ESLint walks through the AST nodes, triggering rule checks at specific node types.
  </Step>

  <Step title="Apply Rules">
    Each rule examines AST nodes and reports violations based on configured severity.
  </Step>

  <Step title="Generate Report">
    ESLint collects all violations and formats them using the selected formatter.
  </Step>

  <Step title="Apply Fixes (Optional)">
    If `--fix` is used, ESLint applies safe automatic fixes to your code.
  </Step>
</Steps>

## Quick Reference

<AccordionGroup>
  <Accordion title="Rule Severity Levels" icon="signal">
    | 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       |
  </Accordion>

  <Accordion title="Configuration File Names" icon="file">
    * `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
  </Accordion>

  <Accordion title="Common CLI Commands" icon="terminal">
    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Exit Codes" icon="door-open">
    * **0** - Linting successful, no errors
    * **1** - Linting successful, but errors found
    * **2** - Linting failed (configuration problem or internal error)
  </Accordion>
</AccordionGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="./configuration">
    Learn how to configure ESLint
  </Card>

  <Card title="Rules" icon="ruler" href="./rule-configuration">
    Configure rule severity and options
  </Card>

  <Card title="Command Line" icon="terminal" href="./command-line">
    CLI options and usage
  </Card>

  <Card title="Formatters" icon="paint-brush" href="./formatters">
    Output format options
  </Card>
</CardGroup>