Installation Guide

This guide covers everything you need to know about installing and configuring ESLint for your JavaScript or TypeScript project.

System Requirements

Node.js Version

Required: ^20.19.0, ^22.13.0, or >=24ESLint requires Node.js built with SSL support (included in all official distributions).

Package Manager

Supported: npm, yarn, pnpm, or bunAny modern JavaScript package manager will work with ESLint.

Check your Node.js version: node --versionIf you need to upgrade, visit nodejs.org to download the latest LTS version.

Quick Installation

The fastest way to get started is with the interactive configuration tool:

npm init @eslint/config@latest

This command will:

Guide you through project-specific setup questions
Install ESLint and required dependencies
Create an eslint.config.js configuration file
Set up appropriate plugins (React, TypeScript, etc.)

The initialization wizard was moved from eslint --init to npm init @eslint/config@latest in ESLint v10. The old command still works but redirects to the new one.

Manual Installation

npm
yarn
pnpm
bun

Install ESLint

npm install --save-dev eslint

Install Recommended Config

npm install --save-dev @eslint/js

Create Configuration File

Create eslint.config.js in your project root:

eslint.config.js

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

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

Install ESLint

yarn add --dev eslint

Install Recommended Config

yarn add --dev @eslint/js

Create Configuration File

Create eslint.config.js in your project root:

eslint.config.js

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

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

Install ESLint

pnpm add --save-dev eslint

Configure pnpm for ESLint

pnpm requires special configuration for optimal ESLint compatibility.

Create or update .npmrc in your project root:

.npmrc

auto-install-peers=true
node-linker=hoisted

These settings ensure pnpm:

Automatically installs peer dependencies
Uses a hoisted structure compatible with ESLint’s plugin resolution

Install Recommended Config

pnpm add --save-dev @eslint/js

Create Configuration File

Create eslint.config.js in your project root:

eslint.config.js

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

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

Install ESLint

bun add --dev eslint

Install Recommended Config

bun add --dev @eslint/js

Create Configuration File

Create eslint.config.js in your project root:

eslint.config.js

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

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

Framework-Specific Setup

TypeScript

Install TypeScript Parser

npm install --save-dev @typescript-eslint/parser @typescript-eslint/eslint-plugin

Configure for TypeScript

eslint.config.js

import { defineConfig } from "eslint/config";
import tsParser from "@typescript-eslint/parser";
import tsPlugin from "@typescript-eslint/eslint-plugin";

export default defineConfig([
  {
    files: ["**/*.ts", "**/*.tsx"],
    languageOptions: {
      parser: tsParser,
      parserOptions: {
        project: "./tsconfig.json",
      },
    },
    plugins: {
      "@typescript-eslint": tsPlugin,
    },
    rules: {
      "@typescript-eslint/no-unused-vars": "error",
      "@typescript-eslint/no-explicit-any": "warn",
    },
  },
]);

This setup is based on ESLint’s own TypeScript configuration found in eslint.config.js:331-349

React

Install React Plugin

npm install --save-dev eslint-plugin-react eslint-plugin-react-hooks

Configure for React

eslint.config.js

import { defineConfig } from "eslint/config";
import js from "@eslint/js";
import react from "eslint-plugin-react";
import reactHooks from "eslint-plugin-react-hooks";

export default defineConfig([
  js.configs.recommended,
  {
    files: ["**/*.jsx", "**/*.tsx"],
    languageOptions: {
      parserOptions: {
        ecmaFeatures: {
          jsx: true,
        },
      },
    },
    plugins: {
      react,
      "react-hooks": reactHooks,
    },
    rules: {
      "react/jsx-uses-react": "error",
      "react/jsx-uses-vars": "error",
      "react-hooks/rules-of-hooks": "error",
      "react-hooks/exhaustive-deps": "warn",
    },
  },
]);

ESLint natively supports JSX syntax parsing. The React plugin adds semantic rules specific to React development.

Vue

Install Vue Plugin

npm install --save-dev eslint-plugin-vue

Configure for Vue

eslint.config.js

import { defineConfig } from "eslint/config";
import vue from "eslint-plugin-vue";

export default defineConfig([
  ...vue.configs["flat/recommended"],
  {
    files: ["**/*.vue"],
    rules: {
      "vue/multi-word-component-names": "warn",
      "vue/no-unused-vars": "error",
    },
  },
]);

Node.js

Install Node Plugin

npm install --save-dev eslint-plugin-n

Configure for Node.js

eslint.config.js

import { defineConfig } from "eslint/config";
import js from "@eslint/js";
import nodePlugin from "eslint-plugin-n";

export default defineConfig([
  js.configs.recommended,
  {
    files: ["**/*.js", "**/*.cjs", "**/*.mjs"],
    plugins: {
      n: nodePlugin,
    },
    rules: {
      "n/no-unsupported-features/node-builtins": "error",
      "n/no-missing-import": "error",
    },
  },
]);

Configuration File Formats

ESLint supports multiple configuration file formats. Choose based on your project setup:

ESM (eslint.config.js)
CommonJS (eslint.config.cjs)
ESM (eslint.config.mjs)

Recommended for modern projects

eslint.config.js

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

export default defineConfig([
  js.configs.recommended,
  {
    files: ["**/*.js"],
    rules: {
      "prefer-const": "warn",
    },
  },
]);

Uses ES module syntax
Supports top-level await
Default for new projects

For projects using CommonJS

eslint.config.cjs

const { defineConfig } = require("eslint/config");
const js = require("@eslint/js");

module.exports = defineConfig([
  js.configs.recommended,
  {
    files: ["**/*.js"],
    rules: {
      "prefer-const": "warn",
    },
  },
]);

Uses CommonJS require() syntax
Ideal for Node.js projects with "type": "commonjs" in package.json
This is the format ESLint itself uses (see eslint.config.js:1-370)

Force ES modules in CommonJS projects

eslint.config.mjs

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

export default defineConfig([
  js.configs.recommended,
  {
    files: ["**/*.js"],
    rules: {
      "prefer-const": "warn",
    },
  },
]);

Forces ES module syntax even if package.json doesn’t specify "type": "module"
Useful for mixing module systems

Understanding the Config Structure

ESLint uses a flat config structure. Here’s a breakdown of the key components from the source:

eslint.config.js

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

export default defineConfig([
  // 1. Global ignores - files to never lint
  globalIgnores([
    "node_modules/**",
    "dist/**",
    "build/**",
    "coverage/**",
  ]),
  
  // 2. Extend recommended rules
  js.configs.recommended,
  
  // 3. File-specific configuration
  {
    name: "my-app/javascript",  // Optional: name your config
    files: ["**/*.js", "**/*.cjs", "**/*.mjs"],
    languageOptions: {
      ecmaVersion: "latest",  // Support latest ECMAScript features
      sourceType: "module",   // Use ES modules
    },
    rules: {
      "prefer-const": "warn",
      "no-unused-vars": "error",
    },
  },
  
  // 4. Override for specific directories
  {
    files: ["tests/**/*.js"],
    rules: {
      "no-unused-expressions": "off",  // Allow in tests
    },
  },
]);

Key Configuration Options

files

Glob patterns for which files to lint:

files: ["**/*.js", "src/**/*.jsx"]

ignores

Patterns to exclude from linting:

ignores: ["dist/**", "*.min.js"]

languageOptions

Parser and language settings:

languageOptions: {
  ecmaVersion: 2024,
  sourceType: "module",
  globals: {
    window: "readonly",
  },
}

rules

Individual rule configuration:

rules: {
  "no-console": "warn",
  "quotes": ["error", "double"],
}

Recommended Rules Reference

ESLint’s recommended configuration includes 74 carefully selected rules. Here are some key ones from eslint-recommended.js:1-76:

Problem Detection
Best Practices
ES6+ Features

Rules that catch actual bugs:

Rule	Description
`no-unused-vars`	Disallow unused variables
`no-undef`	Disallow undefined variables
`no-unreachable`	Disallow unreachable code after return/throw
`no-constant-binary-expression`	Disallow constant binary expressions
`no-dupe-keys`	Disallow duplicate keys in object literals
`no-dupe-args`	Disallow duplicate function arguments
`no-func-assign`	Disallow reassigning function declarations
`no-import-assign`	Disallow reassigning imported bindings

Rules that prevent common mistakes:

Rule	Description
`no-cond-assign`	Disallow assignment in conditionals
`no-empty`	Disallow empty block statements
`no-fallthrough`	Require break in switch cases
`no-self-assign`	Disallow self assignment
`use-isnan`	Require isNaN() for NaN checks
`valid-typeof`	Enforce valid typeof comparisons
`require-yield`	Require yield in generator functions

Rules for modern JavaScript:

Rule	Description
`constructor-super`	Require super() in constructors
`no-class-assign`	Disallow reassigning classes
`no-const-assign`	Disallow reassigning const variables
`no-dupe-class-members`	Disallow duplicate class members
`no-this-before-super`	Disallow this before super()

Environment-Specific Setup

Browser Projects

Configure globals for browser environments:

npm install --save-dev globals

eslint.config.js

import { defineConfig } from "eslint/config";
import globals from "globals";

export default defineConfig([
  {
    languageOptions: {
      globals: {
        ...globals.browser,
      },
    },
  },
]);

This adds globals like window, document, localStorage, etc.

Node.js Projects

Configure for Node.js runtime:

eslint.config.js

import { defineConfig } from "eslint/config";
import globals from "globals";

export default defineConfig([
  {
    languageOptions: {
      globals: {
        ...globals.node,
      },
    },
  },
]);

This adds globals like process, __dirname, Buffer, etc.

Test Environments

Configure for testing frameworks:

eslint.config.js

import { defineConfig } from "eslint/config";
import globals from "globals";

export default defineConfig([
  {
    files: ["tests/**/*.js", "**/*.test.js"],
    languageOptions: {
      globals: {
        ...globals.jest,  // or globals.mocha, globals.vitest
      },
    },
    rules: {
      "no-unused-expressions": "off",
    },
  },
]);

Package.json Scripts

Add these scripts to your package.json for convenient linting:

package.json

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint --fix .",
    "lint:report": "eslint --format json --output-file eslint-report.json .",
    "lint:check": "eslint --max-warnings 0 ."
  }
}

The --max-warnings 0 flag treats warnings as errors, useful for CI/CD pipelines where you want to enforce zero issues.

Verifying Installation

After installation, verify everything is working:

Check ESLint Version

npx eslint --version
# Should output: v10.0.1 or newer

Verify Configuration

npx eslint --print-config src/index.js

This outputs the resolved configuration for a specific file, useful for debugging.

Test on a File

npx eslint src/

If no errors appear and ESLint runs without issues, you’re all set!

Troubleshooting

Module Resolution Errors

Error: Cannot find module 'eslint-plugin-*'Solution: Ensure plugins are installed in the same location as ESLint. With pnpm, make sure your .npmrc has node-linker=hoisted.

# Reinstall with correct settings
pnpm install --shamefully-hoist

Config File Not Found

Error: ESLint couldn't find a configuration fileSolution: ESLint looks for eslint.config.js, eslint.config.mjs, or eslint.config.cjs in the project root. Check:

File is in the correct location
File name is spelled correctly
File exports a valid configuration

You can also specify a config explicitly:

npx eslint -c ./path/to/config.js src/

Parsing Errors with TypeScript

Error: Parsing error: Unexpected tokenSolution: Install the TypeScript parser:

npm install --save-dev @typescript-eslint/parser

Update your config:

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

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

Slow Linting Performance

Issue: ESLint is running slowly on large codebasesSolutions:

Enable caching:

npx eslint --cache --cache-location .eslintcache .

Use parallel processing (ESLint automatically uses available CPU cores):

npx eslint --concurrency auto .

Ignore unnecessary files:

import { globalIgnores } from "eslint/config";

export default [
  globalIgnores(["node_modules/**", "dist/**", "*.min.js"]),
];

Node.js Version Mismatch

Error: ESLint requires Node.js version ^20.19.0 || ^22.13.0 || >=24Solution: Upgrade Node.js to a supported version:

# Check current version
node --version

# Download from nodejs.org or use nvm
nvm install 22
nvm use 22

Next Steps

Configure Rules

Learn how to customize individual rules for your project

Integrations

Set up ESLint with your editor, build tools, and CI/CD

Create Plugins

Build custom plugins to extend ESLint’s functionality

Migration Guide

Upgrading from an older ESLint version? Check the migration guide

Additional Resources

Source Code: The ESLint installation is defined in package.json:1-221 with the binary at bin/eslint.js:1-196
CLI Options: Full reference in lib/options.js:1-150+
Config API: Exported from lib/config-api.js
GitHub: github.com/eslint/eslint
Discord: eslint.org/chat

​Installation Guide

​System Requirements

Node.js Version

Package Manager

​Quick Installation

​Manual Installation

​Install ESLint

​Install Recommended Config

​Create Configuration File

​Install ESLint

​Install Recommended Config

​Create Configuration File

​Install ESLint

​Configure pnpm for ESLint

​Install Recommended Config

​Create Configuration File

​Install ESLint

​Install Recommended Config

​Create Configuration File

​Framework-Specific Setup

​Install TypeScript Parser

​Configure for TypeScript

​Install React Plugin

​Configure for React

​Install Vue Plugin

​Configure for Vue

​Install Node Plugin

​Configure for Node.js

​Configuration File Formats

​Understanding the Config Structure

​Key Configuration Options

files

ignores

languageOptions

rules

​Recommended Rules Reference

​Environment-Specific Setup

​Package.json Scripts

​Verifying Installation

​Troubleshooting

​Next Steps

Configure Rules

Integrations

Create Plugins

Migration Guide

​Additional Resources

Installation Guide

System Requirements

Quick Installation

Manual Installation

Install ESLint

Install Recommended Config

Create Configuration File

Install ESLint

Install Recommended Config

Create Configuration File

Install ESLint

Configure pnpm for ESLint

Install Recommended Config

Create Configuration File

Install ESLint

Install Recommended Config

Create Configuration File

Framework-Specific Setup

Install TypeScript Parser

Configure for TypeScript

Install React Plugin

Configure for React

Install Vue Plugin

Configure for Vue

Install Node Plugin

Configure for Node.js

Configuration File Formats

Understanding the Config Structure

Key Configuration Options

Recommended Rules Reference

Environment-Specific Setup

Package.json Scripts

Verifying Installation

Troubleshooting

Next Steps

Additional Resources