ESLint and the flat config

A linter reads the code without running it and reports the parts that are wrong, suspicious or merely untidy. ESLint does that with a set of rules, each with a severity, and a configuration file that decides which rules apply to which files. Since version 9 the file is eslint.config.js, an ordinary module that exports an array, and version 10 reads nothing else.

The lesson installs ESLint into a project, writes the smallest flat config that is worth keeping, runs it on one clean file and then on a folder with one deliberate mistake. The mistake stays in the folder, because the next lesson is about reading and repairing exactly that report.

The install

ESLint is a development tool, so it goes into devDependencies. The recommended rules live in a second package, @eslint/js, which the config imports; npm installs it as a dependency of ESLint but a project that imports it names it as well, so the version is visible in the manifest instead of being whatever ESLint brought along.

npm init -y
npm install --save-dev eslint@10.14.0 @eslint/js@10.0.1
npx eslint --version

v10.14.0

npx runs the binary from node_modules/.bin, so the command uses the version of the project and not a version installed globally. The pinned numbers are the ones the page was written with; the lesson on npx comes back to the lookup.

eslint.config.js

The file exports an array of configuration objects, and ESLint merges them in order: the later object wins where the two disagree. The first entry is the recommended set, and the second one says what kind of code the files are.

ecmaVersion: 'latest' is the syntax the parser accepts, which for a course is the newest one. sourceType: 'commonjs' makes require, module and exports known names; with 'module' the parser reads the file as an ES module instead. The globals block adds the names that Node.js provides and the language does not: without console in that list, every console.log is an undefined name.

The file eslint.config.js:

vi eslint.config.js

const js = require('@eslint/js'); module.exports = [ js.configs.recommended, { languageOptions: { ecmaVersion: 'latest', sourceType: 'commonjs', globals: { console: 'readonly', process: 'readonly', }, }, }, ];

The file is CommonJS because the package has no "type": "module"; in a module package the same file would use import and be called eslint.config.mjs, and the objects inside would be the same. The file is linted like every other file of the folder, which is why the config of a project usually passes its own rules.

A clean run and its report

The first file is the kind the rules were written for: a function, a module export, no unused name and no undefined one.

The file src/sum.js:

function sum(values) { return values.reduce((total, value) => total + value, 0); } module.exports = { sum };

npx eslint src/sum.js
echo "the exit status: $?"

the exit status: 0

A run with no problems prints nothing at all, which is the behaviour to expect from a check in a script: silence and the status 0 mean the same thing. The report becomes useful in the other direction, and the formatter decides its shape. --format json is the one a program can read, and the program below keeps the file name, the counts and every message.

The file summarise.js:

let text = ''; process.stdin.setEncoding('utf8'); process.stdin.on('data', (chunk) => { text += chunk; }); process.stdin.on('end', () => { const results = JSON.parse(text); for (const result of results) { const name = result.filePath.split('/').pop(); console.log(name + ': ' + result.errorCount + ' error(s), ' + result.warningCount + ' warning(s)'); for (const message of result.messages) { console.log(' ' + message.line + ':' + message.column + ' ' + message.ruleId + ' - ' + message.message); } } });

npx eslint --format json | node summarise.js

eslint.config.js: 0 error(s), 0 warning(s)
compare.js: 1 error(s), 0 warning(s)
  2:9 no-unused-vars - 'extra' is assigned a value but never used.
sum.js: 0 error(s), 0 warning(s)
summarise.js: 0 error(s), 0 warning(s)

The folder holds four JavaScript files and the report has one entry per file, because a JSON result is one entry per linted file and the summary above keeps only the last part of each path. The one problem belongs to src/compare.js, and its position is a line and a column inside the function.

The recommended set

js.configs.recommended is a list of 64 rules with the severity error and no options: they catch mistakes that are almost always bugs, and they leave style to the formatter of two lessons later. The file below breaks one of them, and the mistake is kept in the folder on purpose, because it is what this section is about.

The file src/compare.js:

function sameCount(a, b) { const extra = 3; return a == b; } module.exports = { sameCount };

The variable extra is written and never read, and the rule no-unused-vars reports it as an error. The == on the next line passes, because eqeqeq is not one of the recommended rules: a project that wants it adds it to the same array, which is what the next lesson does.

npx eslint .
echo "the exit status: $?"

the exit status: 1

One error among five clean files and the status is 1, which is what a pre-commit hook or a build server reads. The report above the status line names the file, the position, the rule and the message in one line per problem, and the JSON of the previous section carries the same four facts. A warning would print as well and leave the status at 0, which is the difference between the two severities.

Exercises

  1. Remove console from the globals and run the linter again. Which rule reports the first console.log, and why is the name unknown to the language?
  2. Change sourceType to 'module' and lint summarise.js. Which line of the config has to change as well, and which names become undefined?
  3. Add 'no-console': 'warn' to a rules object and lint the folder. Which file gets a warning, and what is the exit status now?
  4. Run npx eslint src instead of npx eslint .. Which file disappears from the report, and why does the config file disappear with it?
  5. Rename eslint.config.js to eslint.config.mjs and run the linter. Which line of the config fails, and what does the error say?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. Which file does ESLint 10 read its configuration from?

    Answer

    eslint.config.js

    The flat config replaced the old files, and the new loader reads nothing else.

  2. What does this program print? const severity = ["off", "warn", "error"]; console.log(severity[2]);

    Answer

    error

    The three severities are indexed from zero, and error is the last of them.

  3. Which property of a flat config holds ecmaVersion?

    Answer

    languageOptions

    The parser settings moved into languageOptions, which also holds the globals.

  4. What does this program print? const config = { languageOptions: { sourceType: "commonjs" } }; console.log(config.languageOptions.sourceType);

    Answer

    commonjs

    The nested object is read with the same key path that wrote it.

  5. What does a clean run of npx eslint . print?

    Answer

    Nothing, and it exits with 0

    A silent run is the success case, which is what makes the command usable in a script.

  6. What does this program print? const report = [{ filePath: "/app/src/a.js", errorCount: 2, warningCount: 1 }]; console.log(report[0].filePath.split("/").pop(), report[0].errorCount + report[0].warningCount);

    Answer

    a.js 3

    The last part of the path is the file name, and the two counts add up.

  7. What is the difference between the severities error and warn?

    Answer

    An error makes the exit status 1, a warning does not

    Both are reported; the status is what a pipeline reads, and only errors change it.

  8. Why does a Node.js project need console in the globals of the config?

    Answer

    Because console is provided by the runtime and not by the language

    no-undef asks the language for the name, and console is one of the globals Node.js adds.

  9. What does this program print? const rules = { "no-unused-vars": "error", "no-undef": "error" }; console.log(Object.keys(rules).length, rules["no-undef"]);

    Answer

    2 error

    The object has two keys, and the value of the second is the severity string.

  10. What does js.configs.recommended contain?

    Answer

    The rules of the recommended set, all with the severity error

    The package ships the list, and the project decides whether to extend it.

The programs and commands on this page were run with Node.js 24.22.1 and ESLint 10.14.0 with npm 11.12.1 on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev