skip to content

ESLint

ESLint's rule engine with flat config, plugins, typescript-eslint and autofix, run in editor and CI. Asked because nearly every JavaScript repo gates merges on an ESLint config someone must extend.

on this pageshow

explore

questions

29

What exit code does the ESLint CLI return when a run finds only warnings, and how do you make CI fail on them?

level: juniorimportance: must knowfreq 38%

answer

  1. three exit codes, not two
  2. warn is reported, not failing
  3. a threshold flag, default -1
  4. zero turns warnings into a gate
  5. 2 means ESLint itself could not finish

basics

~20 s

Exit code 0: warnings alone never fail an ESLint run, and only errors return 1. Add --max-warnings 0 and any warning makes ESLint exit with 1; exit code 2 means ESLint itself hit a configuration problem or crashed.

solid answer

~40 s

The ESLint CLI has three exit codes. `0` means no errors, and no more warnings than `--max-warnings` allows when that flag is set. `1` means at least one error, or more warnings than `--max-warnings` allows. `2` means linting did not succeed because of a configuration problem or an internal error. A rule set to `"warn"` is reported but never changes the exit code on its own, so a CI step running `eslint .` stays green however many warnings it prints. `--max-warnings` defaults to `-1`, meaning no threshold; `--max-warnings 0` makes a single warning exit with `1` and prints `ESLint found too many warnings (maximum: 0).` The warnings stay warnings in the report; only the exit code changes.

code

bash · 10 lines
bash
$ npx eslint .
✖ 37 problems (0 errors, 37 warnings)
$ echo $?
0
$ npx eslint --max-warnings 0 .
✖ 37 problems (0 errors, 37 warnings)

ESLint found too many warnings (maximum: 0).
$ echo $?
1

go deeper

for a junior

Recall the three codes: 0 clean, 1 an error or too many warnings, 2 ESLint could not run. Know that warnings alone return 0 and that --max-warnings 0 changes that.

for a middle

Explain that severity decides what is reported while the exit code decides what fails, and that --max-warnings bridges them without touching the config. Show where the threshold check counts.

for a senior

When a lint step goes red, read the exit code first: 2 sends you to the config, formatter or patterns, 1 to the code. Know that a parsing error is exit 1 unless --exit-on-fatal-error is set.

for a principal

Weigh a zero-warning gate against a numeric ceiling: zero makes every warn rule a blocker, a ceiling stops growth without forcing a cleanup. Either way, keep the flag in the shared script, not only in CI.

## The three exit codes A CI system decides pass or fail from the **exit code** a command returns: `0` is success, anything else is failure. The ESLint CLI documents exactly three codes: | Exit code | Meaning | |---|---| | `0` | Linting succeeded and found no errors. If `--max-warnings n` is set, there are at most `n` warnings. | | `1` | Linting succeeded and found at least one error, or more warnings than `--max-warnings` allows. | | `2` | Linting was unsuccessful because of a configuration problem or an internal error. | The split between `1` and `2` matters when you read a red pipeline. Code `1` means ESLint did its job and found at least one error, or more warnings than the threshold allows. Code `2` means ESLint could not do its job at all, and the fix is in the setup, not in the source files. ## Why warnings never fail a run by default Every rule has a **severity**: `"off"` (`0`), `"warn"` (`1`) or `"error"` (`2`). ESLint's own glossary describes `"warn"` as running the rule without exiting with a non-zero status because of its violations, with `--max-warnings` as the only exception. So a codebase whose config sets most rules to `"warn"` can print hundreds of warnings on every pull request and still return `0`. The report is visible; nothing enforces it. This is the most common surprise for someone new to a lint job: the log is full of yellow, and the check is green. ## Turning warnings into a gate with `--max-warnings` `--max-warnings` takes an integer threshold. Its default is `-1`, which means no threshold. When the flag is set and the total warning count is **greater** than the number you pass, ESLint exits with `1` and prints `ESLint found too many warnings (maximum: n).` after the report. 1. `eslint --max-warnings 0 .` fails on the first warning, which makes every warning-level rule a merge blocker without editing the config. 2. `eslint --max-warnings 25 .` passes with 25 warnings and fails at 26, so the count cannot grow past today's number. 3. Errors are not affected by the flag: one error still returns `1` whatever the warning count. The flag changes only the exit code. The warnings are still printed as warnings, and their rules keep their configured severity. If you want a rule to be an error everywhere, that is a change to its severity in the config, not a CLI flag. ## What exit code 2 points at Code `2` is ESLint saying it never produced a trustworthy result. Typical causes: - the config file throws while loading, or no `eslint.config.*` file can be found; - the formatter named with `-f` cannot be loaded; - a file pattern on the command line matches no files; - an unexpected crash, printed under `Oops! Something went wrong! :(` with the ESLint version. A **parsing error** in one file is different. By default ESLint reports it as an error-level message on that file, so the run returns `1` like any other error. Only `--exit-on-fatal-error` turns a parsing error into exit code `2`. ## How other flags move the exit code A few flags change what the exit code is computed from, and it pays to know which: - `--fix` writes fixes to the files first; the remaining, unfixed problems are what gets reported and what decides between `0` and `1`. - `--quiet` hides warnings from the report but does not change the code: a warnings-only run returns `0` with or without it. - `--exit-on-fatal-error` moves parsing errors from `1` to `2`, so a file ESLint cannot parse is treated like a setup failure rather than a rule violation. - `--max-warnings` is the only flag that lets warnings decide the result. ## Reading the result in CI The report format does not change the exit code. `-f json -o eslint-report.json` writes a JSON report to a file for another tool to read, while the step still passes or fails on the same `0`, `1` or `2`. The default console format is `stylish`, which ends with a summary line such as `✖ 37 problems (0 errors, 37 warnings)`. ```bash npx eslint . echo $? # 0: warnings only npx eslint --max-warnings 0 . echo $? # 1: too many warnings ``` Three habits follow from this: - Treat `2` as an infrastructure failure: read the message ESLint printed before looking at any source file. - Put `--max-warnings` in the same script developers run locally, so the local run and the CI step agree on what fails. - Do not reach for `--quiet` to make a warnings-only run pass. It hides warnings from the output, and a run with only warnings already returns `0`.

  • A CI step running ESLint exits with 2 instead of 1. Where do you look first?
    At the message ESLint printed, not at the source files. Exit code `2` means linting itself failed: a config file that throws or cannot be found, a formatter named with `-f` that cannot be loaded, a file pattern that matches nothing, or a crash shown under `Oops! Something went wrong!`. A rule violation, even a parsing error, gives `1` unless `--exit-on-fatal-error` is set.
  • Does `--max-warnings 0` turn the warnings into errors in the report?
    No. Each problem keeps its configured severity and is printed as a warning; only the exit code changes, and ESLint adds `ESLint found too many warnings (maximum: 0).` after the report. To make a rule an error in the report and in the editor, change its severity in the config instead.
  • How do you save a machine-readable report without changing whether the step fails?
    Choose a format with `-f` and a destination with `-o`, for example `eslint -f json -o eslint-report.json .`. The report goes to the file instead of the console, and the exit code is still computed from the same errors and warnings, so the step passes or fails exactly as before.

  • A rule set to warn will fail the build once enough warnings pile up.
  • The default value of --max-warnings is 0.
  • Exit code 2 means the code has more serious lint problems than exit code 1.
  • --max-warnings 0 rewrites every warning as an error in the report.
  • Errors are let through as long as the warning count stays under --max-warnings.
open as a page

In ESLint 10, what does `eslint.config.js` export, and how do you apply a rule only to test files?

level: juniorimportance: must knowfreq 40%

basics

~20 s

An eslint.config.js file exports an array of configuration objects, usually wrapped in defineConfig(). To target tests, append an object whose files key holds a test glob such as **/*.test.js and whose rules apply only to those files.

open as a page

In ESLint 10's flat config, how do you load a plugin, and how are its rules then named in the `rules` object?

level: juniorimportance: must knowfreq 35%

basics

~10 s

Import the plugin in eslint.config.js and register it in a config object's plugins object under a namespace you choose; each of its rules is then configured as namespace/rule-name, for example crew/no-raw-dates.

open as a page

In ESLint, what do the rule severities "off", "warn" and "error" do, and which one makes a lint run fail?

level: juniorimportance: must knowfreq 42%

basics

~20 s

"off" (0) disables a rule, "warn" (1) reports its violations without touching ESLint's exit code, and "error" (2) reports them and makes the run exit with code 1, so only error-level rules fail a build by default.

open as a page

Why can't ESLint lint a TypeScript file with its default parser, and what does the typescript-eslint package add so that it can?

level: juniorimportance: must knowfreq 28%

basics

~20 s

ESLint's default parser, Espree, reads only JavaScript, so a type annotation is a parsing error. The typescript-eslint package adds a parser that turns TypeScript into ESLint's tree format, a plugin of TypeScript rules, and presets that wire both in.

open as a page

In an ESLint 10 flat config, when several configuration objects match one file, which settings win, and where do `extends` entries land?

level: middleimportance: must knowfreq 28%

basics

~20 s

Every matching object applies, merged in array order, and the later object wins a conflict however broad its glob. defineConfig() expands each extends entry into its own object placed just before the extending object, whose own settings then override the preset.

open as a page

In ESLint 10's flat config, when two stacked presets set the same rule differently, which setting wins, and where must your own override go?

level: middleimportance: must knowfreq 26%

basics

~20 s

The preset that comes later in the flattened config array wins for files both match. Put your overrides after every preset: in a later object, or in the rules of the object whose extends lists the presets.

open as a page

In ESLint, how far do eslint-disable, eslint-disable-line and eslint-disable-next-line comments reach, and why name the rule and add a -- reason?

level: middleimportance: must knowfreq 30%

basics

~20 s

/* eslint-disable / silences rules until / eslint-enable */ or the end of the file, eslint-disable-line covers its own line and eslint-disable-next-line the following one. Naming the rule limits the silence; a -- reason records why.

open as a page

In typescript-eslint, why does the @typescript-eslint/no-floating-promises rule need type information, and how do you enable typed linting in a flat config?

level: middleimportance: must knowfreq 22%

basics

~20 s

Whether a call like saveRefill(order) returns a Promise depends on its declared type, often in another file, which only TypeScript's checker knows. Use recommendedTypeChecked and set parserOptions.projectService to true so the parser asks TypeScript for each file's types.

open as a page

With ESLint 10, what does the --quiet flag change, and how does it interact with --max-warnings?

level: middleimportance: should knowfreq 16%

basics

~20 s

With ESLint 10, --quiet reports only errors and, since ESLint 9.0.0, does not even run rules set to warn. Add --max-warnings and the warn rules run again: their warnings stay hidden but still count toward the threshold.

open as a page

In VS Code, how do you set up the ESLint extension so it applies ESLint's fixes on save in a repository with several packages?

level: middleimportance: should knowfreq 24%

basics

~10 s

Add source.fixAll.eslint set to explicit under editor.codeActionsOnSave; the extension then applies ESLint's fixes on each save. eslint.codeActionsOnSave.mode picks all, the default, or the faster problems, and eslint.workingDirectories says where ESLint runs.

open as a page

In ESLint 10's flat config, why does `ignores: ["dist/"]` beside `rules` skip nothing, while `globalIgnores(["dist/"])` skips the folder?

level: middleimportance: should knowfreq 18%

basics

~20 s

An ignores key next to other keys only removes files from that one object, and such patterns match files, not directories, so dist/ matches nothing. Alone, or through globalIgnores(), ignores applies to every object and may match directories.

open as a page

In ESLint 10, how do `--print-config` and `--inspect-config` help when a rule you configured never seems to reach a file?

level: middleimportance: should knowfreq 12%

basics

~10 s

--print-config <file> prints the final computed configuration for that file as JSON, showing what applies. --inspect-config starts ESLint's config inspector, which shows which named configuration objects match a file. Neither lints anything.

open as a page

In ESLint 10's flat config, how do you consume a plugin's preset and an in-house shareable config package such as `@crewdeck/eslint-config`?

level: middleimportance: should knowfreq 20%

basics

~20 s

Presets are config objects or arrays. Reference a plugin's preset by string, such as js/recommended, after registering the plugin in the same object, or insert the exported object; a shareable config is an installed package you import and extend.

open as a page

In ESLint 10's flat config, what happens to a rule's options when a later config object or inline comment sets only its severity?

level: middleimportance: should knowfreq 16%

basics

~20 s

The earlier options survive: a later "warn" or ["warn"] replaces only the severity, so ["error", "never"] becomes ["warn", "never"]. A later array that carries options replaces the earlier options entirely, and since ESLint 9.0.0 inline comments follow the same rule.

open as a page

With ESLint 10, what does linterOptions.reportUnusedDisableDirectives report, what is its default, and what changes when you set it to "error"?

level: middleimportance: should knowfreq 12%

basics

~20 s

It reports eslint-disable and eslint-enable comments that suppressed nothing. In ESLint 10 it defaults to "warn", so stale directives appear as warnings; set to "error", each one counts as an error and fails the run with exit code 1.

open as a page

With typescript-eslint, how does parserOptions.projectService find each file's type information differently from parserOptions.project, and why is it now the recommended option?

level: middleimportance: should knowfreq 12%

basics

~20 s

parserOptions.project uses tsconfig files you name, or each file's nearest one with true. projectService asks TypeScript's project service, the machinery editors use, for each file's nearest tsconfig.json: no paths to maintain, and lint types match the editor's.

open as a page

How does ESLint's --cache decide a file can be skipped, and why can cached results be wrong on CI checkouts or with typed rules?

level: seniorimportance: should knowfreq 14%

basics

~20 s

ESLint's --cache reuses a file's stored result while the file and its config look unchanged, judged by modification time and size by default. A fresh clone resets those, so use --cache-strategy content; cross-file rules, typed ones included, can report stale results.

open as a page

Why does a pre-commit hook running `eslint --max-warnings 0` on the staged file list fail on generated files the ESLint config ignores, and what fixes it?

level: seniorimportance: should knowfreq 9%

basics

~20 s

ESLint skips an ignored file named on the command line but reports a one-line File ignored warning for it, and --max-warnings 0 turns that warning into exit code 1. Add --no-warn-ignored so ignored files stay skipped and silent.

open as a page

After upgrading from ESLint 8 to ESLint 10, why do files starting with `/* eslint-env browser */` fail linting, and what replaces the comment?

level: seniorimportance: should knowfreq 10%

basics

~20 s

eslint-env comments belonged to the removed eslintrc format, and ESLint 10 reports each one as an error. Remove them and declare the globals in eslint.config.js under languageOptions.globals, scoped with files, usually from the globals package.

open as a page

With ESLint 10 in a monorepo, why does `eslint .` at the root now apply `packages/map-tiles/eslint.config.js` to that package, and how do you control it?

level: seniorimportance: should knowfreq 8%

basics

~20 s

ESLint 10 looks for eslint.config.* from each linted file's directory upward, so files under packages/map-tiles use the nearest config, and only that one. ESLint 9 started at the working directory. --config names one file and stops the search.

open as a page

In ESLint 10's flat config, how do you wire eslint-plugin-react-hooks' preset, and what changes if you choose `recommended-latest` instead of `recommended`?

level: seniorimportance: should knowfreq 15%

basics

~10 s

Install eslint-plugin-react-hooks, 7.1.0 or later for ESLint 10, and add reactHooks.configs.flat.recommended to the config; recommended-latest is the same plus the plugin's bleeding-edge experimental React Compiler rules.

open as a page

In ESLint 10, adding `@crewdeck/eslint-config` beside an app's own eslint-plugin-react-hooks import fails with `Cannot redefine plugin "react-hooks"` - what causes it, and what fixes it?

level: seniorimportance: should knowfreq 12%

basics

~20 s

Two config objects matching the same file map the namespace react-hooks to different plugin objects, usually two installed copies of the plugin. Register it once, from one copy, and configure its rules in later objects.

open as a page

With ESLint 10, how do you turn no-unused-vars and eqeqeq on as errors in a legacy codebase without first fixing every existing violation?

level: seniorimportance: should knowfreq 8%

basics

~10 s

Set both rules to "error", then run eslint --fix --suppress-rule no-unused-vars --suppress-rule eqeqeq. ESLint writes the remaining violations to eslint-suppressions.json; commit it, and later runs report only new violations.

open as a page

After a TypeScript repository switched to typescript-eslint's type-checked presets, its ESLint job went from 40 seconds to 6 minutes — why, and how do you find what to fix?

level: seniorimportance: should knowfreq 10%

basics

~20 s

Typed linting makes TypeScript build and analyse the whole project before typed rules can run, so lint time approaches type-check time. Time a plain tsc run as the baseline, profile rules with TIMING=1, then check wide tsconfig includes, default-project files and memory.

open as a page

An ESLint 10 lint job on a large repository takes nine minutes; what does --concurrency change, and when does it not help?

level: seniorimportance: nice to knowfreq 6%

basics

~20 s

--concurrency, added in ESLint 9.34.0 and off by default, lints files on worker threads. A number sets the thread count; auto starts one per 50 files, capped at half the cores. Each worker reloads the config, so small runs gain nothing.

open as a page

In ESLint 10, how do you lint JavaScript code blocks inside Markdown files with a processor, and how does that differ from a `language` such as `json/jsonc`?

level: seniorimportance: nice to knowfreq 6%

basics

~20 s

A processor such as markdown/markdown extracts each code block as a virtual child file that JavaScript rules lint; a language such as json/jsonc, available since ESLint 9.7.0, makes ESLint parse the whole file as that language.

open as a page

With ESLint 10 bulk suppressions, why does a run exit with code 2 after someone fixes a suppressed violation, and what happens when one more is added?

level: seniorimportance: nice to knowfreq 5%

basics

~20 s

eslint-suppressions.json stores a count per file and rule. Fewer violations than recorded leaves a stale entry, so ESLint exits 2 until --prune-suppressions; more than recorded and every violation of that rule in that file is reported.

open as a page

With ESLint 10 and typescript-eslint's projectService, eslint.config.js and scripts/*.mjs fail with "was not found by the project service" — how do you fix each?

level: seniorimportance: nice to knowfreq 7%

basics

~20 s

No tsconfig.json includes those files, so the project service cannot type them. Add them to tsconfig.json's include, list a few in projectService.allowDefaultProject, or turn typed linting off for them with a files-scoped disableTypeChecked object; ignore files you never lint.

open as a page