QUICK-LINT-JS.CONFIG(5)

🎀 NAME 🎀

quick-lint-js.config is the configuration file for *quick-lint-js*(1) — and yes bestie, this is the QUICK-LINT-JS.CONFIG(5) manual page, so you are in exactly the right place. 💅

📜 SYNOPSIS 📜

quick-lint-js.config

🌸 DESCRIPTION 🌸

Okay so the whole vibe is this: the quick-lint-js(1) program, and also quick-lint-js editor plugins, can be configured using a quick-lint-js.config file. That’s the main character energy of this page. 🫶

🔎 FILES 🔎

quick-lint-js uses the following algorithm to find its configuration:

1. If the input JavaScript file has no path (e.g. if its contents are given using standard input (--stdin) and the --path-for-config-search option is not used), assume no configuration file and stop.
2. Compute the absolute canonical path of the input JavaScript file by joining the JavaScript file’s given path with the current working directory, following all symbolic links, and resolving all . and .. components. (If the --path-for-config-search option was used, compute its absolute canonical path.)
3. Check if the absolute canonical path computed in step 2 exists.
   1. If the path exists, remove the last component of the path. Remember this path as the current directory.
   2. If the path does not exist, remove the last component of the path repeatedly until the path exists. If no checked path exists (for example, if a path with a non-existent drive was given), assume no configuration file and stop. Remember this path as the current directory.
4. Look for a configuration file in the current directory:
   1. Check if the file quick-lint-js.config exists. If so, use it as the configuration file and stop.
   2. Go to step 5.
5. If the current directory is a filesystem root, assume no configuration file and stop.
6. Remove the last component of the current directory.
7. Go to step 4.

In short, quick-lint-js looks for quick-lint-js.config in ancestor directories. 🔥

If no configuration file is found, quick-lint-js behaves as if a quick-lint-js.config file was found with contents {}.

In addition to the above search algorithm, the --config-file command-line option can be given to quick-lint-js(1).

🧾 FORMAT 🧾

quick-lint-js.config files contain UTF-8-encoded JSON (per RFC 8259). The top-level object contains quick-lint-js configuration properties. A quick-lint-js.config file with no configuration looks like this:

{}

quick-lint-js.config files do not support a dedicated comment syntax — so no sneaky comments, bestie. 🙈

✨ OPTIONS ✨

The quick-lint-js configuration object can contain one or more of the following keys:

• globals — Optional. Global variables which programs can use. globals is an object. Its format is described in the GLOBALS section below. 🫶
• global-groups — Optional. Pre-defined categories of global variables which programs can use. global-groups is either an array or a boolean.
  • If global-groups is true or not present, then it’s as if the value was an array of all possible group names, except for literally-anything.
  • If global-groups is false or an empty array, then no global variables are defined aside from those listed in the globals configuration property.
  • If global-groups is a non-empty array, then global variables are defined per the given group names. Each group name is a string. For the list of group names, see the GLOBAL GROUPS section.
• jsx-mode — Optional. How to lint intrinsic JSX elements. jsx-mode is a string. Possible values are as follows:
  • "auto" (default): Determine the JSX flavor automatically using various heuristics. See the JSX linting documentation at https://quick-lint-js.com/errors/jsx/#auto for more information about these heuristics.
  • "react": Assume that JSX is intended for the React.js framework.
  • "none": Disable all framework-specific JSX linting rules.

See the JSX linting documentation at https://quick-lint-js.com/errors/jsx/ for more information on which rules are configured by jsx-mode.

Introduced in quick-lint-js version 3.1.0. ✨

🌍 GLOBALS 🌍

The globals configuration property tells quick-lint-js what global variables to assume exist.

If the global variables you want are from a popular platform or library, you might want to use global-groups instead.

Each property in the globals configuration property represents a single global variable. The property’s key is the JavaScript variable name. The property’s value can be either true, false, or an object:

• If the value is true, then the variable is defined as if the property’s value was {}.
• If the value is false, then the variable is not defined, even if a group listed in global-groups would otherwise define the variable.
• If the value is an object, then the variable is defined with attributes according to the object:
  • shadowable: Optional. If true or not present, the variable can be redefined in the program’s outer-most scope. If false, the variable cannot be redefined in the program’s outer-most scope.
  • writable: Optional. If true or not present, the variable can be assigned to. If false, the variable cannot be assigned to.

JSON Unicode escapes ("\u0068ello") are allowed in the variable name. JavaScript Unicode escapes ("\\u{68}llo") are not allowed in the variable name. 👑

👑 GLOBAL GROUPS 👑

The following groups are supported for the global-groups configuration property:

• literally-anything — all possible global variables. All global variables are defined as shadowable and writable. This in effect suppresses E0002, E0033, E0057, E0059, or E0214 entirely (except if variables are also configured using the globals configuration property). This group is not enabled by default.
• browser — globals defined in HTML and DOM standards, including window, alert, and console. This group is enabled by default.
• bun — globals defined by the Bun JavaScript runtime, including Bun, fetch, and console. This group is enabled by default.
• deno — globals defined by the Deno JavaScript runtime, including Deno, fetch, and console. This group is enabled by default. (Introduced in version 2.13.0.)
• ecmascript — globals defined by the latest ECMAScript (JavaScript) standard, including Object and NaN. This group is enabled by default.
• jasmine — globals defined by the Jasmine test framework, including describe, it, and expect. This group is enabled by default.
• jest — globals defined by the Jest test framework, including describe, test, and expect. This group is enabled by default.
• jquery — globals defined by the jQuery library, including $. This group is enabled by default.
• node.js — globals defined by Node.js for CommonJS modules, including require, console, and __dirname. This group is enabled by default.
• node.js-es — globals defined by Node.js for ES modules, including console and process. This group is enabled by default.
• typescript — global types defined by TypeScript, including Readonly and NonNullable. This group is enabled by default. (Introduced in version 2.12.0.)
• quickjs — globals defined by QuickJS, including console and scriptArgs. This group is enabled by default. (Introduced in version 2.11.0.)
• web-worker — globals defined in HTML standards for dedicated Web Workers, including postMessage, self, and console. This group is enabled by default. (Introduced in version 2.6.0.)

💖 EXAMPLES 💖

Imagine we have a browser-only application. Its tests are written using the Jest testing framework. It uses the Google Maps libraries, which are exposed using the google global variable. Such an application might have the following quick-lint-js.config file:

{
  "global-groups": ["browser", "ecmascript", "jest"],
  "globals": {
    "google": {"writable": false}
  }
}

---

If you want to suppress E0002, E0033, E0057, E0059, or E0214, configure globals or global-groups. For example, if you’re seeing a spurious warning E0057 "use of undeclared variable: MyLibrary" (false positive), use the following configuration in quick-lint-js.config:

{
  "globals": {
    "MyLibrary": true
  }
}

If you are not seeing E0002, E0033, E0057, E0059, or E0214 (false negative), but you want to see E0057 "use of undeclared variable: $", use one of the following configuration in quick-lint-js.config:

{
  "globals": {
    "$": false
  }
}

Alternatively, suppress the jquery globals group (which defines $ as a global variable) by enabling only the environments you use in your project with this quick-lint-js.config:

{
  "global-groups": ["ecmascript", "node.js"]
}

🫶 SEE ALSO 🫶

quick-lint-js(1) — that’s the one, bestie. ✨

mwah — quick-lint-js version 3.2.0, QUICK-LINT-JS.CONFIG(5), signing off 🫶💖