{}
This page documents how to configure quick-lint-js.
Description
The
quick-lint-js CLI
and also quick-lint-js editor plugins, can be configured using a quick-lint-js.config
file.
These configuration options are not yet implemented.
Files
quick-lint-js uses the following algorithm to find its configuration:
-
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. Remove the last component of the absolute canonical path. Remember this path as the current directory.If the input JavaScript file has no path (e.g. if its contents are given using standard input), remember the current working directory as the current directory.
-
Look for a configuration file in the current directory:
-
Check if the file
quick-lint-js.config
exists. If so, use it as the configuration file and stop. -
Check if the file
.quick-lint-js.config
exists. If so, use it as the configuration file and stop. -
Check if the file
package.json
exists. If so, use it as the configuration file and stop. -
Go to step 3.
-
-
If the current directory is a filesystem root, assume no configuration file and stop.
-
Remove the last component of the current directory.
-
Go to step 2.
In short, quick-lint-js looks for quick-lint-js.config
, .quick-lint-js.config
, or package.json
in ancestor directories.
If multiple files are found, quick-lint-js.config
is used if present, otherwise .quick-lint-js.config
is used if present.
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
and .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
or .quick-lint-js.config
file with no configuration looks like this:
quick-lint-js.config
and .quick-lint-js.config
do not support a dedicated comment syntax.
To write a comment, you can create an object key starting a space character.
quick-lint-js will ignore an object property if its key starts with a space.
For example:
{
" ": "this file configures quick-lint-js",
"globals": {
" exported by Prototype.js": null,
"$": true,
"Ajax": true,
"Class": true,
"Element": true,
" exported by Google Charts": null,
"chart": true
}
}
package.json
files contain UTF-8-encoded JSON.
The quick-lint-js.config property of the top-level object contains quick-lint-js configuration properties.
If the quick-lint-js.config property is missing, it is assumed to be an empty object ({}).
A package.json
file might look like this:
{
"name": "my-npm-package",
"version": "0.1.0",
"quick-lint-js.config": {
"globals": {
"YUI": {"writable": false}
}
}
}
Options
The quick-lint-js configuration object can contain one or more of the following keys:
- globals
-
Optional. Global variables which programs can use. This configuration property is not yet implemented.
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. This configuration property is not yet implemented.
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.
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 E002, E033, E057, or E059 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.
- 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.
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}
}
}
Alternatively, the application might prefer to have fewer files in the project.
In this case, the application configures quick-lint-js in its package.json
file:
{
"name": "acme",
"version": "1.2.1",
"devDependencies": {
"jest": "3.0.1"
},
"quick-lint-js.config": {
"global-groups": ["browser", "ecmascript", "jest"],
"globals": {
"google": {"writable": false}
}
}
}
If you want to suppress E002, E033, E057, or E059, configure globals or global-groups.
For example, if you’re seeing a spurious warning E057 "use of undeclared variable: MyLibrary" (false positive), use the following configuration in quick-lint-js.config
:
{
"globals": {
"MyLibrary": true
}
}
If you are not seeing E002, E033, E057, or E059 (false negative), but you want to see E057 "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"]
}