ESLint

Common errors

• ESLint: Node.js v18.x is no longer supported. Please upgrade to a supported version.

  cause Running ESLint v10 on an unsupported Node.js version (e.g., Node.js 18).
  fix Upgrade your Node.js installation to v20.19.0, v22.13.0, or >=24.

• TypeError: ESLint is not a constructor

  cause Attempting to use `require('eslint').ESLint` in an ESM context, or incorrectly mixing CJS and ESM, or not importing it correctly.
  fix Ensure you are using `import { ESLint } from 'eslint';` in an ESM module context.

• ERR_REQUIRE_ESM: Must use import to load ES Module: .../node_modules/eslint/lib/eslint/eslint.js

  cause Attempting to `require()` an ESLint module that is ESM-only, or trying to load an `eslint.config.js` file with `require` syntax.
  fix Convert your project or specific file to use ESM `import` statements, and ensure your `eslint.config.js` is also ESM.

• Error: Cannot find module '@eslint/js/configs/eslint-recommended'

  cause Occurs with `pnpm` if peer dependencies are not correctly hoisted or automatically installed.
  fix Add `auto-install-peers=true` and `node-linker=hoisted` to your `.npmrc` file and reinstall dependencies.

• TS2307: Cannot find module 'eslint' or its corresponding type declarations.

  cause TypeScript version is too old for ESLint's type definitions, or `eslint` is not correctly installed.
  fix Update TypeScript to version 5.3 or later, or ensure `eslint` is properly installed in your `node_modules`.

Warnings

• breaking ESLint v10 requires Node.js v20.19.0, v22.13.0, or >=24. Older Node.js versions are not supported.
  Fix: Upgrade Node.js to a supported version.
• breaking Configuration files (`eslint.config.js`) must be written in ESM format (`import/export` syntax). CommonJS (`require/module.exports`) is no longer supported for config files.
  Fix: Refactor your `eslint.config.js` to use `import` and `export` statements, for example, `export default defineConfig(...)`.
• breaking Programmatic usage of ESLint, including the `ESLint` class, is primarily designed for ESM environments. While a CJS entry point may exist, it is largely deprecated and can lead to module resolution issues.
  Fix: Ensure your project is configured for ESM, and use `import { ESLint } from 'eslint';`.
• gotcha Using `pnpm` requires specific `.npmrc` settings (`auto-install-peers=true`, `node-linker=hoisted`) to avoid dependency resolution errors related to peer dependencies.
  Fix: Add `auto-install-peers=true` and `node-linker=hoisted` to your `.npmrc` file and reinstall dependencies.
• gotcha If you use ESLint's TypeScript type definitions, TypeScript 5.3 or later is required.
  Fix: Ensure your project's `typescript` dependency is at version 5.3 or newer.

Install

• npm install eslint npm
• yarn add eslint yarn
• pnpm add eslint pnpm

Imports

• ESLint
  wrong:

  const { ESLint } = require('eslint');

  correct:

  import { ESLint } from 'eslint';

  ESLint v9+ is designed for ESM environments. While a CJS entry point exists, it is largely deprecated, and configuration files (`eslint.config.js`) must be ESM.

Quickstart

This example demonstrates how to programmatically use the ESLint class to lint a string of JavaScript code with a custom configuration, reporting any found issues.

import { ESLint } from 'eslint';

async function lintCode(code: string): Promise<void> {
  const eslint = new ESLint({
    useEslintrc: false, // Don't use .eslintrc.* files
    overrideConfigFile: true, // Use this config file
    overrideConfig: {
      languageOptions: {
        ecmaVersion: 2022,
        sourceType: "module",
        globals: {
          console: "readonly"
        }
      },
      rules: {
        "no-unused-vars": "warn",
        "prefer-const": "error"
      }
    }
  });

  const results = await eslint.lintText(code);

  console.log(`Linting results for: "${code}"`);
  results.forEach(result => {
    result.messages.forEach(message => {
      console.log(
        `  Line ${message.line}, Col ${message.column}: ${message.message} (${message.ruleId})`
      );
    });
  });
}

lintCode(`
  var x = 1; // no-unused-vars (warn), prefer-const (error)
  console.log('hello');
  const y = 2;
`).catch(console.error);