quick-lint-js

Find bugs in JavaScript programs.

Configuration files for quick-lint-js

This page documents how to configure quick-lint-js.

Table of Contents

Description

The quick-lint-js CLI, and also quick-lint-js editor plugins, can be configured using a quick-lint-js.config file.

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' CLI.

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 do not support a dedicated comment syntax.

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 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 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 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"]
}