{"canonical_url":"https://engineer.company/glossary/eslint/","content_markdown":"# ESLint\n\n## What it is\n\nESLint is an open-source static analysis tool that reads JavaScript source code,\ntests it against a configured set of rules and reports each place the code\nbreaks one, repairing the simpler cases itself when asked. On the command line\nit is the `eslint` command, installed from npm as a development dependency of\nthe project it checks. Nicholas C. Zakas started it in June 2013, and the\nproject still introduces itself as a configurable JavaScript linter.\n\nIt never runs the program. A parser turns each file into an abstract syntax tree\nin the ESTree format, and every rule is a small module that asks to be called at\nparticular kinds of node: each function, each comparison, each `await`. The rule\nlooks at what it is handed and, if something is wrong, reports a message and a\nlocation. Some rules also carry a fix, an edit the project only accepts when it\ncorrects the problem without changing what the program does, and `eslint --fix`\napplies those to the files. Others offer suggestions instead, which may change\nbehaviour and are therefore applied one at a time, by a person, in an editor.\n\nNearly everything around that core can be swapped. Plugins are npm packages\nthat add rules, shareable configurations, processors or support for other\nlanguages. A different parser lets ESLint read syntax the default one does not\nunderstand, such as TypeScript. Processors pull JavaScript out of other files,\nfor instance the code blocks in a Markdown document, and formatters change how\nthe report is printed. The project's own account of its philosophy is that every\nrule stands alone, can be switched off, and can be set to warn or to fail on its\nown terms.\n\nAll of this is set in one JavaScript file at the root of the project, usually\n`eslint.config.js` or its `.mjs` and `.cjs` variants, which exports an array of\nobjects. Each object names the files it applies to and the rules, globals and\nparser options that hold for them, and later objects override earlier ones. That\nlayout, called flat config, became the default in ESLint v9.0.0 on 5 April 2024.\nESLint v10.0.0, released on 6 February 2026, removed the older `.eslintrc`\nformat and the `.eslintignore` file outright.\n\n## Why it matters\n\nA linter earns its place at one moment: when it stops a change from merging.\nESLint makes that call through its exit code, and the exit code follows\nseverity. Every rule is set to `\"off\"`, `\"warn\"` or `\"error\"`. An error makes\nthe command exit with 1. A warning is printed and the command still exits with\n0, unless `--max-warnings` sets a ceiling, and that ceiling is disabled by\ndefault. Exit code 2 is reserved for a broken configuration or an internal\ncrash.\n\nSo the decision a team really makes with ESLint is what a warning means. A\nwarning that never fails a build is advice, and advice in a terminal gets\nscrolled past once there are forty lines of it. Teams that want the linter to\nhold a line either set every rule they care about to `\"error\"` or run the gate\nwith `--max-warnings 0`. Either way a healthy branch lints clean, and a single\nnew line is news someone reads.\n\nThe payoff is in what JavaScript lets through. The language will load a file\nthat refers to a variable nobody declared, defines the same key twice in an\nobject literal, compares a value with `NaN` using `===`, or leaves code after a\n`return` that can never run. These problems can survive loading and remain unnoticed, or cause wrong\nbehaviour when the code runs, including in production. The rules in ESLint's recommended set catch all four\nbefore review, which leaves the reviewer free to read for design.\n\nThere are costs. A configuration accumulates opinions, and a rule that fires on\ncorrect code teaches people to stop reading the output, which is worse than\nhaving no rule. A linter is also only as good as the moment it runs: one that\nruns only in an editor, on some machines, checks some of the code some of the\ntime.\n\n## What it looks like in practice\n\nESLint was one of six linters behind\n[a zero-warnings bar set across six languages](/portfolio/set-a-zero-warnings-bar-across-six-languages/),\nwhere it checked TypeScript beside golangci-lint for Go, SQLFluff for SQL, Ruff\nfor Python, ShellCheck for shell scripts and markdownlint for Markdown. What\nmade the bar hold was the severity question above, settled once for everyone:\nevery linter diagnostic is an error, there is no \"warn\" tier to hide in, and\ninline suppressions are banned. Pre-commit and pre-push hooks run the linters and the tests; failures in the\ncovered rule and test set block the corresponding commit or push.\n\nThe same repository then needed rules no published package ships, the ones\nabout how that particular codebase is meant to work.\n[Fifteen custom ESLint rules hold the house patterns in TypeScript](/portfolio/built-a-268-check-guard-engine-for-the-repo/),\nalongside 274 check scripts, 268 of them registered into the commit hooks. One\nof those validators checks that nobody quietly added an inline suppression. The\nguards have 146 tests of their own, because a broken guard passes everything and\nnobody finds out, and the page names the price plainly: committing is slow.\n\nThis site holds its own build scripts to the same standard on a smaller scale.\nIts `eslint.config.mjs` starts from `js.configs.recommended` and adds only rules\nthe code already passed when they were measured; the comments record a\nre-measurement on 2026-10-15 across all 199 non-deprecated rules that enabled 21\nmore whose subject is correctness rather than taste. Every rule is an error.\n`reportUnusedDisableDirectives`, a warning by default, is raised to an error\ntoo, so a disable comment that has stopped suppressing anything fails the run.\nThe scripts declare Node and browser globals together, because the function\nbodies they hand to `page.evaluate` run inside a browser, a few lines away from\ncode that runs in Node.\n\n## Where it goes wrong\n\nMost ESLint trouble is the linter doing exactly what its configuration says,\nwhich is not always what the team believes it says.\n\n**The build is green and the terminal is full of warnings.** Warnings leave the\nexit code at 0, so continuous integration passes while the list grows by a few\nlines a week, and after a while a real defect sits in it unread. Decide which\nrules matter, set them to `\"error\"`, switch the rest off, and add\n`--max-warnings 0` to the gate so that a warning can no longer accumulate.\n\n**A disable comment outlives its reason.** A line was silenced for a good reason\nonce; the code beneath it changed, the comment stayed, and now it hides the next\nproblem on that line or nothing at all. Set\n`linterOptions.reportUnusedDisableDirectives` to `\"error\"` so directives that\nsuppress nothing fail the run, and ask for a reason after `--` on the ones that\nremain, so a reviewer can judge them:\n\n```js\n// eslint-disable-next-line no-console -- printing is this CLI's output\nconsole.log(report);\n```\n\n**An upgrade changes which files are checked.** After moving to v10, paths that\n`.eslintignore` used to skip are suddenly reported, or one folder starts\nfollowing different rules. Version 10 no longer honours `.eslintrc.*` or\n`.eslintignore`, and it begins its search for `eslint.config.*` in each linted\nfile's own directory, so a stray config in a subfolder now governs that\nsubfolder. Move ignores into a global `ignores` entry, convert the old file with\n`npx @eslint/migrate-config .eslintrc.json` and review what it writes, then list\nevery `eslint.config.*` in the tree and remove the ones nobody meant to keep.\n\n**Browser code is reported as undefined.** A Node script that hands functions to\na browser gets `no-undef` errors on `document` and `window`, and someone turns\n`no-undef` off, which also hides genuine typos. Declare every environment the\ncode really runs in through `languageOptions.globals`, for the files that run\nthere.\n\n**A custom rule passes everything.** A rule whose visitor names a node type that\nnever occurs, or whose condition is inverted, simply never reports, and silence\nlooks exactly like compliance. Test each custom rule with ESLint's `RuleTester`,\ngiving it code that must pass and code that must fail, so a rule that stops\nreporting fails its own test before it fails the codebase.\n\n## Further reading\n\n- [Core Concepts](https://eslint.org/docs/latest/use/core-concepts/) — rules,\n  fixes, plugins, parsers and processors, as the project defines them.\n- [Configuration Files](https://eslint.org/docs/latest/use/configure/configuration-files)\n  — the flat config array, file patterns, global ignores and how objects merge.\n- [Configure Rules](https://eslint.org/docs/latest/use/configure/rules) —\n  severities, rule options and the comments that disable a rule for a line.\n- [Command Line Interface Reference](https://eslint.org/docs/latest/use/command-line-interface)\n  — every flag, `--max-warnings` among them, and what each exit code means.\n- [ESLint v10.0.0 released](https://eslint.org/blog/2026/02/eslint-v10.0.0-released/)\n  — the removal of eslintrc and the new configuration lookup, in the release\n  notes.\n- [Custom Rules](https://eslint.org/docs/latest/extend/custom-rules) — writing a\n  rule against the syntax tree and proving it with `RuleTester`.\n\n\u003chttps://engineer.company/glossary/eslint/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"How ESLint reads JavaScript as a syntax tree, why its two severities decide whether a build fails, and how a config quietly stops checking.","formats":{"gemtext":"https://engineer.company/glossary/eslint/index.gmi","gopher":"https://engineer.company/glossary/eslint/gophermap","html":"https://engineer.company/glossary/eslint/","json":"https://engineer.company/glossary/eslint/index.json","markdown":"https://engineer.company/glossary/eslint/index.md","pdf":"https://engineer.company/glossary/eslint/index.pdf"},"kind":"page","language":"en","title":"What is ESLint?","url":"https://engineer.company/glossary/eslint/","version":1}