How linters & formatters work

What linters and formatters do

A linter reads your code and reports problems, such as a variable you never use. A formatter prints your code again with a consistent layout, and never changes what it does. Both start by parsing the code into a tree.

import { Linter } from "eslint/universal";

const linter = new Linter();
const code = "let total = 0;\nlet unused = 1;\nif (total == 0) report(total);";
const messages = linter.verify(code, {
  rules: { "no-unused-vars": "error", "no-undef": "error", eqeqeq: "error" },
});
for (const message of messages) {
  console.log(message.line + ":" + message.column, message.ruleId);
}

Line 3 makes ESLint's Linter, the part that lints one piece of code. Lines 5 to 7 run three of ESLint's built-in rules on the code from line 4. Line 9 prints where each problem is, and which rule found it.

It prints 2:5 no-unused-vars for unused, 3:11 eqeqeq for the ==, and 3:17 no-undef for report, which was never declared. Each one is line:column.

Read each row of the table as: "this tool is this kind of tool, and works like this."

A rule is a visitor

An ESLint rule is an object with a create function. It returns a visitor, as in the codemods lesson. ESLint parses the code once, walks the tree once, and calls every rule's functions as it goes. A key can also end in :exit, to run when the walk leaves a node.

import { Linter } from "eslint/universal";

const found = [];
const spy = {
  create() {
    return {
      CallExpression(node) {
        if (node.callee.name === "alert") found.push("alert call on line " + node.loc.start.line);
      },
      "FunctionDeclaration:exit"(node) {
        found.push("left " + node.id.name);
      },
    };
  },
};

const code = 'function warn() {\n  alert("careful");\n}\nwarn();';
new Linter().verify(code, { plugins: { demo: { rules: { spy } } }, rules: { "demo/spy": "error" } });
console.log(found.join("\n"));

Line 7 runs for every call, and line 8 keeps the calls to alert. Line 10 adds :exit, so it runs as the walk leaves each function, after everything inside it has been visited.

Line 18 lints the code from line 17, and line 19 prints alert call on line 2, then left warn: the call inside the function comes first.

Keys can also be selectors, which pick nodes the way CSS selectors pick elements. CallExpression[callee.name='alert'] would do line 8's check for you. Selectors need ESLint's selector parser, which the esm.sh build used by this page can't load, so the example checks the name itself.

Read each row of the table as: "this part of a rule is used for this."

Scope analysis: variables and references

Some rules need more than the tree. To know whether a variable is used, ESLint must know which declaration each name belongs to. Before the rules run, it does scope analysis: it finds every scope, every variable in it, and every reference, a place where a name is read or written.

import { Linter } from "eslint/universal";

const report = [];
const showScope = {
  create(context) {
    return {
      "Program:exit"(node) {
        const scope = context.sourceCode.getScope(node);
        for (const variable of scope.variables) {
          if (variable.defs.length > 0) report.push(variable.name + ": " + variable.references.length + " references");
        }
        for (const reference of scope.through) report.push("not declared: " + reference.identifier.name);
      },
    };
  },
};

new Linter().verify("let cups = 2;\ncups += 1;\nshow(cups);", {
  languageOptions: { sourceType: "script" },
  plugins: { demo: { rules: { "show-scope": showScope } } },
  rules: { "demo/show-scope": "error" },
});
console.log(report.join("\n"));

Line 7 runs when the walk leaves the program. Line 8 asks for its scope. Line 10 lists the variables declared in the code, with how many references each has. Line 12 lists scope.through: references that no declaration in this scope matched.

Line 18 lints three lines, as a classic script. It prints cups: 3 references, one for each line, and not declared: show.

That is exactly how two built-in rules work. no-unused-vars reports variables that are never read. no-undef reports references that fall through every scope. The scope analysis lesson shows how engines build the same scopes.

Writing a custom lint rule

Teams write their own rules for their own conventions. Here is one that reports calls to an old function, and can fix them.

import { Linter } from "eslint/universal";

const noFetchUser = {
  meta: {
    type: "suggestion",
    fixable: "code",
    messages: { renamed: "{{name}} was renamed to getUser." },
  },
  create(context) {
    return {
      CallExpression(node) {
        if (node.callee.type !== "Identifier" || node.callee.name !== "fetchUser") return;
        context.report({
          node,
          messageId: "renamed",
          data: { name: node.callee.name },
          fix: (fixer) => fixer.replaceText(node.callee, "getUser"),
        });
      },
    };
  },
};

const linter = new Linter();
const config = { plugins: { shop: { rules: { "no-fetch-user": noFetchUser } } }, rules: { "shop/no-fetch-user": "error" } };
const code = "fetchUser(7);\napi.fetchUser(8);";
for (const message of linter.verify(code, config)) console.log(message.line + ":" + message.column, message.message);
console.log(linter.verifyAndFix(code, config).output);

Lines 4 to 8 are the rule's meta. fixable: "code" says it can fix what it finds, and messages holds its message, with a {{name}} placeholder.

Line 12 skips anything that isn't a plain call to fetchUser. Line 13 reports the call. Line 16 fills in the placeholder, and line 17 offers a fix that replaces the callee's text.

Line 25 gives the rule a plugin name, shop, and turns it on. Line 27 prints 1:1 fetchUser was renamed to getUser.. Line 28 applies the fixes and prints getUser(7); and api.fetchUser(8);. The second call has a different shape, so the rule doesn't touch it.

How Prettier prints: the doc format

Prettier doesn't keep any of your layout. It parses the code, then turns the tree into a doc: a description of the code with marks for where it may break. Only then does a printer decide the lines, using printWidth.

import { doc } from "prettier/standalone";

const { group, indent, line, softline, join } = doc.builders;
const call = group([
  "show(",
  indent([softline, join([",", line], ["cupsOfTea", "slicesOfCake"])]),
  softline,
  ")",
]);

for (const printWidth of [40, 20]) {
  console.log(doc.printer.printDocToString(call, { printWidth, tabWidth: 2 }).formatted);
}

Lines 4 to 9 build a group. Inside it, softline means "nothing, or a new line", and line means "a space, or a new line". indent on line 6 indents any new lines inside it.

Line 12 prints it at two widths. At 40 the group fits, so it prints show(cupsOfTea, slicesOfCake). At 20 it doesn't, so every line in the group breaks, and it takes four lines.

1import { doc } from "prettier/standalone";2 3const { group, indent, line, softline, join } = doc.builders;4const call = group([Run5  "show(",6  indent([softline, join([",", line], ["cupsOfTea", "slicesOfCake"])]),7  softline,8  ")",9]);10 11for (const printWidth of [40, 20]) {12  console.log(doc.printer.printDocToString(call, { printWidth, tabWidth: 2 }).formatted);13}

Press Step to watch the printer measure the group, then break it line by line. This replays the example code; it isn't a view inside the JavaScript engine.

Prettier builds docs like this for every node. Here it formats a messy line of real code:

import { format } from "prettier/standalone";
import * as babel from "prettier/plugins/babel";
import * as estree from "prettier/plugins/estree";

const code = "const order={cups:2,tea:'green'};if(order.cups>1){serve(order)}";
console.log(await format(code, { parser: "babel", plugins: [babel, estree] }));

Line 6 formats the code from line 5. It prints four lines: spaces around = and inside the braces, double quotes, a semicolon after serve(order), and the if body on its own line. Prettier ends the code with a line break.

Type-aware linting

Some problems can't be seen in one file's tree. In the code below, nothing says that save returns a promise, except its type.

async function save(order: { cups: number }): Promise<void> {
  if (order.cups > 10) throw new Error("too many cups");
}

export function checkout() {
  save({ cups: 2 });
  return "done";
}

Line 1 returns a Promise, and line 2 can throw. Line 6 calls save without await, so if it throws, nobody hears about it: it is a floating promise.

typescript-eslint's no-floating-promises rule reports line 6, column 3: "Promises must be awaited, end with a call to .catch, end with a call to .then with a rejection handler or be explicitly marked as ignored with the `void` operator."

To get the types, the rule asks TypeScript. You turn that on in your ESLint config:

// eslint.config.js
import js from "@eslint/js";
import { defineConfig } from "eslint/config";
import tseslint from "typescript-eslint";

export default defineConfig(
  js.configs.recommended,
  tseslint.configs.recommendedTypeChecked,
  {
    languageOptions: {
      parserOptions: { projectService: true, tsconfigRootDir: import.meta.dirname },
    },
  },
);

Line 8 adds typescript-eslint's rules that need types. Line 11's projectService: true asks TypeScript for each file's types, using your tsconfig.json.

Without it, ESLint refuses to run these rules, with an error that you have used a rule which requires type information. The price is speed: TypeScript must understand the whole project, so typed linting is slower than normal linting.

Linters and formatters together

Pick a printWidth and edit the code. The playground formats it with the real Prettier, and shows the doc Prettier built for it.

At 80, the serve call fits on one line. At 50, its object breaks. At 30, the order object breaks too. In the doc, look for group, indent and line: they are the same building blocks as above.

How teams usually set them up:

• Let the formatter own layout. eslint-config-prettier turns off ESLint rules that are unnecessary or might conflict with Prettier.
• Run Prettier when you save, and ESLint in your editor, so problems show while you type.
• Run both in continuous integration, and fail the build on lint errors.
• Turn on type-aware rules where promises and types matter most, and accept the slower lint.

Common mix-ups

Most mix-ups come from mixing up the two jobs: finding problems and laying out code.

• "A formatter finds bugs." No. It only changes layout. A linter or a test finds bugs.
• "Linters search the text." No. They walk the tree, and many rules use scope analysis.
• "Prettier keeps your line breaks." Mostly no. It builds a new layout from the tree; it keeps only a few things, such as blank lines between statements.
• "Every rule can be fixed automatically." No. Only rules with fixable offer fixes, and many problems need a person to decide.
• "Type-aware rules work like any other rule." No. They need the TypeScript project and are slower.

The table below puts three of these side by side. Read each row as: "people often think this, but this is true."

Practice exercises

Most exercises run ESLint or Prettier for real. Guess first, then run it.

import { Linter } from "eslint/universal";

const code = "const a = 1;\nlet b = 2;\nconsole.log(a);";
const messages = new Linter().verify(code, { rules: { "prefer-const": "error", "no-unused-vars": "error" } });
console.log(messages.map((message) => message.line + ":" + message.ruleId).join(" "));

import { Linter } from "eslint/universal";

const code = "const a = 1;\nlet b = 2;\nconsole.log(a);";
const messages = new Linter().verify(code, { rules: { "prefer-const": "error", "no-unused-vars": "error" } });
console.log(messages.map((message) => message.line + ":" + message.ruleId).join(" "));

import { Linter } from "eslint/universal";

const report = [];
const showScope = {
  create(context) {
    return {
      "Program:exit"(node) {
        const scope = context.sourceCode.getScope(node);
        for (const variable of scope.variables) {
          if (variable.defs.length > 0) report.push(variable.name + ": " + variable.references.length + " references");
        }
        for (const reference of scope.through) report.push("not declared: " + reference.identifier.name);
      },
    };
  },
};

new Linter().verify("let n = 1;\nn = n + 1;\nlog(n);", {
  languageOptions: { sourceType: "script" },
  plugins: { demo: { rules: { "show-scope": showScope } } },
  rules: { "demo/show-scope": "error" },
});
console.log(report.join("\n"));

import { Linter } from "eslint/universal";

const report = [];
const showScope = {
  create(context) {
    return {
      "Program:exit"(node) {
        const scope = context.sourceCode.getScope(node);
        for (const variable of scope.variables) {
          if (variable.defs.length > 0) report.push(variable.name + ": " + variable.references.length + " references");
        }
        for (const reference of scope.through) report.push("not declared: " + reference.identifier.name);
      },
    };
  },
};

new Linter().verify("let n = 1;\nn = n + 1;\nlog(n);", {
  languageOptions: { sourceType: "script" },
  plugins: { demo: { rules: { "show-scope": showScope } } },
  rules: { "demo/show-scope": "error" },
});
console.log(report.join("\n"));

import { Linter } from "eslint/universal";

const noAlert = {
  meta: { messages: { toast: "Use showToast instead of alert." } },
  create(context) {
    return {
      CallExpression(node) {
        // Report calls to alert(...) with the "toast" message.
      },
    };
  },
};

const code = 'alert("saved");\nshowToast("saved");\nwindow.alert("hi");';
const messages = new Linter().verify(code, { plugins: { ui: { rules: { "no-alert": noAlert } } }, rules: { "ui/no-alert": "error" } });
console.log(messages.length, messages.map((message) => message.line).join(" "));

import { Linter } from "eslint/universal";

const noAlert = {
  meta: { messages: { toast: "Use showToast instead of alert." } },
  create(context) {
    return {
      CallExpression(node) {
        if (node.callee.type === "Identifier" && node.callee.name === "alert") context.report({ node, messageId: "toast" });
      },
    };
  },
};

const code = 'alert("saved");\nshowToast("saved");\nwindow.alert("hi");';
const messages = new Linter().verify(code, { plugins: { ui: { rules: { "no-alert": noAlert } } }, rules: { "ui/no-alert": "error" } });
console.log(messages.length, messages.map((message) => message.line).join(" "));

import { Linter } from "eslint/universal";

const strict = {
  meta: { fixable: "code", messages: { strict: "Use === instead of ==." } },
  create(context) {
    return {
      BinaryExpression(node) {
        if (node.operator !== "==") return;
        context.report({ node, messageId: "strict" });
      },
    };
  },
};

const code = "if (a == b) go();\nif (c === d) stop();";
const config = { plugins: { team: { rules: { strict } } }, rules: { "team/strict": "error" } };
console.log(new Linter().verifyAndFix(code, config).output);

import { Linter } from "eslint/universal";

const strict = {
  meta: { fixable: "code", messages: { strict: "Use === instead of ==." } },
  create(context) {
    return {
      BinaryExpression(node) {
        if (node.operator !== "==") return;
        const token = context.sourceCode.getFirstTokenBetween(node.left, node.right, (t) => t.value === "==");
        context.report({ node, messageId: "strict", fix: (fixer) => fixer.replaceText(token, "===") });
      },
    };
  },
};

const code = "if (a == b) go();\nif (c === d) stop();";
const config = { plugins: { team: { rules: { strict } } }, rules: { "team/strict": "error" } };
console.log(new Linter().verifyAndFix(code, config).output);

import { doc } from "prettier/standalone";

const { group, indent, line, softline, join } = doc.builders;
const list = group(["[", indent([softline, join([",", line], ["1", "2", "3"])]), softline, "]"]);

console.log(doc.printer.printDocToString(list, { printWidth: 20, tabWidth: 2 }).formatted);
console.log(doc.printer.printDocToString(list, { printWidth: 6, tabWidth: 2 }).formatted);

import { doc } from "prettier/standalone";

const { group, indent, line, softline, join } = doc.builders;
const list = group(["[", indent([softline, join([",", line], ["1", "2", "3"])]), softline, "]"]);

console.log(doc.printer.printDocToString(list, { printWidth: 20, tabWidth: 2 }).formatted);
console.log(doc.printer.printDocToString(list, { printWidth: 6, tabWidth: 2 }).formatted);

async function save() {
  await null;
  console.log("saved");
}

function checkout() {
  save();
  console.log("done");
}

checkout();

async function save() {
  await null;
  console.log("saved");
}

async function checkout() {
  await save();
  console.log("done");
}

checkout();

Check your understanding

For each question, ask whether it is about finding problems or about layout, and what information the tool needs. Each answer explains why it's right or wrong.

Key takeaways

Linters and formatters both read your code as a tree, then do two different jobs with it.

• A lint rule is a visitor; ESLint walks the tree once and calls every rule.
• Selectors pick nodes by shape, and :exit runs on the way out.
• Scope analysis links every reference to its variable; no-unused-vars and no-undef depend on it.
• A rule reports with context.report, and can offer a fix.
• Prettier turns the tree into a doc; each group is printed on one line if it fits, or broken if not.
• Type-aware rules ask TypeScript for types, which finds more problems but is slower.

Coming next: Source maps in depth. They map minified and compiled code back to the lines you wrote.