Note: This page covers the most recent rule format for ESLint >= 3.0.0. There is also a deprecated rule format.
Each rule in ESLint has three files named with its identifier (for example, no-extra-semi).
lib/rules directory: a source file (for example, no-extra-semi.js)tests/lib/rules directory: a test file (for example, no-extra-semi.js)docs/rules directory: a Markdown documentation file (for example, no-extra-semi)Important: If you submit a core rule to the ESLint repository, you must follow some conventions explained below.
Here is the basic format of the source file for a rule:
/**
* @fileoverview Rule to disallow unnecessary semicolons
* @author Nicholas C. Zakas
*/
"use strict";
//------------------------------------------------------------------------------
// Rule Definition
//------------------------------------------------------------------------------
module.exports = {
meta: {
docs: {
description: "disallow unnecessary semicolons",
category: "Possible Errors",
recommended: true,
url: "https://eslint.org/docs/rules/no-extra-semi"
},
fixable: "code",
schema: [] // no options
},
create: function(context) {
return {
// callback functions
};
}
}; The source file for a rule exports an object with the following properties.
meta (object) contains metadata for the rule:
docs (object) is required for core rules of ESLint:
description (string) provides the short description of the rule in the rules index
category (string) specifies the heading under which the rule is listed in the rules index
recommended (boolean) is whether the "extends": "eslint:recommended" property in a configuration file enables the ruleurl (string) specifies the URL at which the full documentation can be accessedIn a custom rule or plugin, you can omit docs or include any properties that you need in it.
fixable (string) is either "code" or "whitespace" if the --fix option on the command line automatically fixes problems reported by the rule
Important: Without the fixable property, ESLint does not apply fixes even if the rule implements fix functions. Omit the fixable property if the rule is not fixable.
schema (array) specifies the options so ESLint can prevent invalid rule configurations
deprecated (boolean) indicates whether the rule has been deprecated. You may omit the deprecated property if the rule has not been deprecated.
create (function) returns an object with methods that ESLint calls to “visit” nodes while traversing the abstract syntax tree (AST as defined by ESTree) of JavaScript code:
:exit, ESLint calls that visitor function while going up the treeA rule can use the current node and its surrounding tree to report or fix problems.
Here are methods for the array-callback-return rule:
function checkLastSegment (node) {
// report problem for function if last code path segment is reachable
}
module.exports = {
meta: { ... },
create: function(context) {
// declare the state of the rule
return {
ReturnStatement: function(node) {
// at a ReturnStatement node while going down
},
// at a function expression node while going up:
"FunctionExpression:exit": checkLastSegment,
"ArrowFunctionExpression:exit": checkLastSegment,
onCodePathStart: function (codePath, node) {
// at the start of analyzing a code path
},
onCodePathEnd: function(codePath, node) {
// at the end of analyzing a code path
}
};
}
}; The context object contains additional functionality that is helpful for rules to do their jobs. As the name implies, the context object contains information that is relevant to the context of the rule. The context object has the following properties:
parserOptions - the parser options configured for this run (more details here).id - the rule ID.options - an array of the configured options for this rule. This array does not include the rule severity. For more information, see here.settings - the shared settings from configuration.parserPath - the name of the parser from configuration.parserServices - an object containing parser-provided services for rules. The default parser does not provide any services. However, if a rule is intended to be used with a custom parser, it could use parserServices to access anything provided by that parser. (For example, a TypeScript parser could provide the ability to get the computed type of a given node.)Additionally, the context object has the following methods:
getAncestors() - returns an array of the ancestors of the currently-traversed node, starting at the root of the AST and continuing through the direct parent of the current node. This array does not include the currently-traversed node itself.getDeclaredVariables(node) - returns a list of variables declared by the given node. This information can be used to track references to variables. VariableDeclaration, all variables declared in the declaration are returned.VariableDeclarator, all variables declared in the declarator are returned.FunctionDeclaration or FunctionExpression, the variable for the function name is returned, in addition to variables for the function parameters.ArrowFunctionExpression, variables for the parameters are returned.ClassDeclaration or a ClassExpression, the variable for the class name is returned.CatchClause, the variable for the exception is returned.ImportDeclaration, variables for all of its specifiers are returned.ImportSpecifier, ImportDefaultSpecifier, or ImportNamespaceSpecifier, the declared variable is returned.getFilename() - returns the filename associated with the source.getScope() - returns the scope of the currently-traversed node. This information can be used track references to variables.getSourceCode() - returns a SourceCode object that you can use to work with the source that was passed to ESLint.markVariableAsUsed(name) - marks a variable with the given name in the current scope as used. This affects the no-unused-vars rule. Returns true if a variable with the given name was found and marked as used, otherwise false.report(descriptor) - reports a problem in the code (see the dedicated section).Note: Earlier versions of ESLint supported additional methods on the context object. Those methods were removed in the new format and should not be relied upon.
This method returns the scope which has the following types:
| AST Node Type | Scope Type |
|---|---|
Program | global |
FunctionDeclaration | function |
FunctionExpression | function |
ArrowFunctionExpression | function |
ClassDeclaration | class |
ClassExpression | class |
BlockStatement ※1 | block |
SwitchStatement ※1 | switch |
ForStatement ※2 | for |
ForInStatement ※2 | for |
ForOfStatement ※2 | for |
WithStatement | with |
CatchClause | catch |
| others | ※3 |
※1 Only if the configured parser provided the block-scope feature. The default parser provides the block-scope feature if parserOptions.ecmaVersion is not less than 6.
※2 Only if the for statement defines the iteration variable as a block-scoped variable (E.g., for (let i = 0;;) {}).
※3 The scope of the closest ancestor node which has own scope. If the closest ancestor node has multiple scopes then it chooses the innermost scope (E.g., the Program node has a global scope and a module scope if Program#sourceType is "module". The innermost scope is the module scope.).
The main method you’ll use is context.report(), which publishes a warning or error (depending on the configuration being used). This method accepts a single argument, which is an object containing the following properties:
message - the problem message.node - (optional) the AST node related to the problem. If present and loc is not specified, then the starting location of the node is used as the location of the problem.loc - (optional) an object specifying the location of the problem. If both loc and node are specified, then the location is used from loc instead of node. start - An object of the start location. line - the 1-based line number at which the problem occurred.column - the 0-based column number at which the problem occurred.end - An object of the end location. line - the 1-based line number at which the problem occurred.column - the 0-based column number at which the problem occurred.data - (optional) placeholder data for message.fix - (optional) a function that applies a fix to resolve the problem.Note that at least one of node or loc is required.
The simplest example is to use just node and message:
context.report({
node: node,
message: "Unexpected identifier"
}); The node contains all of the information necessary to figure out the line and column number of the offending text as well the source text representing the node.
You can also use placeholders in the message and provide data:
context.report({
node: node,
message: "Unexpected identifier: {{ identifier }}",
data: {
identifier: node.name
}
}); Note that leading and trailing whitespace is optional in message parameters.
The node contains all of the information necessary to figure out the line and column number of the offending text as well the source text representing the node.
messageIdsInstead of typing out messages in both the context.report() call and your tests, you can use messageIds instead.
This allows you to avoid retyping error messages. It also prevents errors reported in different sections of your rule from having out-of-date messages.
// in your rule
module.exports = {
meta: {
messages: {
avoidName: "Avoid using variables named '{{ name }}'"
}
},
create(context) {
return {
Identifier(node) {
if (node.name === "foo") {
context.report({
node,
messageId: "avoidName",
data: {
name: "foo",
}
});
}
}
};
}
};
// in the file to lint:
var foo = 2;
// ^ error: Avoid using variables named 'foo'
// In your tests:
var rule = require("../../../lib/rules/my-rule");
var RuleTester = require("eslint").RuleTester;
var ruleTester = new RuleTester();
ruleTester.run("my-rule", rule, {
valid: ["bar", "baz"],
invalid: [
{
code: "foo",
errors: [
{
messageId: "avoidName"
}
]
}
]
}); If you’d like ESLint to attempt to fix the problem you’re reporting, you can do so by specifying the fix function when using context.report(). The fix function receives a single argument, a fixer object, that you can use to apply a fix. For example:
context.report({
node: node,
message: "Missing semicolon",
fix: function(fixer) {
return fixer.insertTextAfter(node, ";");
}
}); Here, the fix() function is used to insert a semicolon after the node. Note that a fix is not immediately applied, and may not be applied at all if there are conflicts with other fixes. After applying fixes, ESLint will run all of the enabled rules again on the fixed code, potentially applying more fixes. This process will repeat up to 10 times, or until no more fixable problems are found. Afterwards, any remaining problems will be reported as usual.
Important: Unless the rule exports the meta.fixable property, ESLint does not apply fixes even if the rule implements fix functions.
The fixer object has the following methods:
insertTextAfter(nodeOrToken, text) - inserts text after the given node or tokeninsertTextAfterRange(range, text) - inserts text after the given rangeinsertTextBefore(nodeOrToken, text) - inserts text before the given node or tokeninsertTextBeforeRange(range, text) - inserts text before the given rangeremove(nodeOrToken) - removes the given node or tokenremoveRange(range) - removes text in the given rangereplaceText(nodeOrToken, text) - replaces the text in the given node or tokenreplaceTextRange(range, text) - replaces the text in the given rangeThe above methods return a fixing object. The fix() function can return the following values:
fixing object.fixing objects.fixing objects. Especially, the fix() function can be a generator.If you make a fix() function which returns multiple fixing objects, those fixing objects must not be overlapped.
Best practices for fixes:
fix().For example, suppose a fixer would like to surround an object key with quotes, but it’s not sure whether the user would prefer single or double quotes.
({ foo : 1 })
// should get fixed to either
({ 'foo': 1 })
// or
({ "foo": 1 }) This fixer can just select a quote type arbitrarily. If it guesses wrong, the resulting code will be automatically reported and fixed by the quotes rule.
Some rules require options in order to function correctly. These options appear in configuration (.eslintrc, command line, or in comments). For example:
{
"quotes": ["error", "double"]
} The quotes rule in this example has one option, "double" (the error is the error level). You can retrieve the options for a rule by using context.options, which is an array containing every configured option for the rule. In this case, context.options[0] would contain "double":
module.exports = {
create: function(context) {
var isDouble = (context.options[0] === "double");
// ...
}
}; Since context.options is just an array, you can use it to determine how many options have been passed as well as retrieving the actual options themselves. Keep in mind that the error level is not part of context.options, as the error level cannot be known or modified from inside a rule.
When using options, make sure that your rule has some logical defaults in case the options are not provided.
The SourceCode object is the main object for getting more information about the source code being linted. You can retrieve the SourceCode object at any time by using the getSourceCode() method:
module.exports = {
create: function(context) {
var sourceCode = context.getSourceCode();
// ...
}
}; Once you have an instance of SourceCode, you can use the methods on it to work with the code:
getText(node) - returns the source code for the given node. Omit node to get the whole source.getAllComments() - returns an array of all comments in the source.getCommentsBefore(nodeOrToken) - returns an array of comment tokens that occur directly before the given node or token.getCommentsAfter(nodeOrToken) - returns an array of comment tokens that occur directly after the given node or token.getCommentsInside(node) - returns an array of all comment tokens inside a given node.getJSDocComment(node) - returns the JSDoc comment for a given node or null if there is none.isSpaceBetweenTokens(first, second) - returns true if there is a whitespace character between the two tokens.getFirstToken(node, skipOptions) - returns the first token representing the given node.getFirstTokens(node, countOptions) - returns the first count tokens representing the given node.getLastToken(node, skipOptions) - returns the last token representing the given node.getLastTokens(node, countOptions) - returns the last count tokens representing the given node.getTokenAfter(nodeOrToken, skipOptions) - returns the first token after the given node or token.getTokensAfter(nodeOrToken, countOptions) - returns count tokens after the given node or token.getTokenBefore(nodeOrToken, skipOptions) - returns the first token before the given node or token.getTokensBefore(nodeOrToken, countOptions) - returns count tokens before the given node or token.getFirstTokenBetween(nodeOrToken1, nodeOrToken2, skipOptions) - returns the first token between two nodes or tokens.getFirstTokensBetween(nodeOrToken1, nodeOrToken2, countOptions) - returns the first count tokens between two nodes or tokens.getLastTokenBetween(nodeOrToken1, nodeOrToken2, skipOptions) - returns the last token between two nodes or tokens.getLastTokensBetween(nodeOrToken1, nodeOrToken2, countOptions) - returns the last count tokens between two nodes or tokens.getTokens(node) - returns all tokens for the given node.getTokensBetween(nodeOrToken1, nodeOrToken2) - returns all tokens between two nodes.getTokenByRangeStart(index, rangeOptions) - returns the token whose range starts at the given index in the source.getNodeByRangeIndex(index) - returns the deepest node in the AST containing the given source index.getLocFromIndex(index) - returns an object with line and column properties, corresponding to the location of the given source index. line is 1-based and column is 0-based.getIndexFromLoc(loc) - returns the index of a given location in the source code, where loc is an object with a 1-based line key and a 0-based column key.commentsExistBetween(nodeOrToken1, nodeOrToken2) - returns true if comments exist between two nodes.
skipOptionsis an object which has 3 properties;skip,includeComments, andfilter. Default is{skip: 0, includeComments: false, filter: null}.
skipis a positive integer, the number of skipping tokens. Iffilteroption is given at the same time, it doesn’t count filtered tokens as skipped.includeCommentsis a boolean value, the flag to include comment tokens into the result.filteris a function which gets a token as the first argument, if the function returnsfalsethen the result excludes the token.
countOptionsis an object which has 3 properties;count,includeComments, andfilter. Default is{count: 0, includeComments: false, filter: null}.
countis a positive integer, the maximum number of returning tokens.includeCommentsis a boolean value, the flag to include comment tokens into the result.filteris a function which gets a token as the first argument, if the function returnsfalsethen the result excludes the token.
rangeOptionsis an object which has 1 property:includeComments.
includeCommentsis a boolean value, the flag to include comment tokens into the result.
There are also some properties you can access:
hasBOM - the flag to indicate whether or not the source code has Unicode BOM.text - the full text of the code being linted. Unicode BOM has been stripped from this text.ast - the Program node of the AST for the code being linted.scopeManager - the ScopeManager object of the code.visitorKeys - the visitor keys to traverse this AST.lines - an array of lines, split according to the specification’s definition of line breaks.You should use a SourceCode object whenever you need to get more information about the code being linted.
Please note that the following methods have been deprecated and will be removed in a future version of ESLint:
getComments() - replaced by getCommentsBefore(), getCommentsAfter(), and getCommentsInside()
getTokenOrCommentBefore() - replaced by getTokenBefore() with the { includeComments: true } optiongetTokenOrCommentAfter() - replaced by getTokenAfter() with the { includeComments: true } optionRules may export a schema property, which is a JSON schema format description of a rule’s options which will be used by ESLint to validate configuration options and prevent invalid or unexpected inputs before they are passed to the rule in context.options.
There are two formats for a rule’s exported schema. The first is a full JSON Schema object describing all possible options the rule accepts, including the rule’s error level as the first argument and any optional arguments thereafter.
However, to simplify schema creation, rules may also export an array of schemas for each optional positional argument, and ESLint will automatically validate the required error level first. For example, the yoda rule accepts a primary mode argument, as well as an extra options object with named properties.
// "yoda": [2, "never", { "exceptRange": true }]
module.exports = {
meta: {
schema: [
{
"enum": ["always", "never"]
},
{
"type": "object",
"properties": {
"exceptRange": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
}; In the preceding example, the error level is assumed to be the first argument. It is followed by the first optional argument, a string which may be either "always" or "never". The final optional argument is an object, which may have a Boolean property named exceptRange.
To learn more about JSON Schema, we recommend looking at some examples to start, and also reading Understanding JSON Schema (a free ebook).
Note: Currently you need to use full JSON Schema object rather than array in case your schema has references ($ref), because in case of array format ESLint transforms this array into a single schema without updating references that makes them incorrect (they are ignored).
If your rule needs to get the actual JavaScript source to work with, then use the sourceCode.getText() method. This method works as follows:
// get all source var source = sourceCode.getText(); // get source for just this AST node var nodeSource = sourceCode.getText(node); // get source for AST node plus previous two characters var nodeSourceWithPrev = sourceCode.getText(node, 2); // get source for AST node plus following two characters var nodeSourceWithFollowing = sourceCode.getText(node, 0, 2);
In this way, you can look for patterns in the JavaScript text itself when the AST isn’t providing the appropriate data (such as location of commas, semicolons, parentheses, etc.).
While comments are not technically part of the AST, ESLint provides a few ways for rules to access them:
This method returns an array of all the comments found in the program. This is useful for rules that need to check all comments regardless of location.
These methods return an array of comments that appear directly before, directly after, and inside nodes, respectively. They are useful for rules that need to check comments in relation to a given node or token.
Keep in mind that the results of this method are calculated on demand.
Finally, comments can be accessed through many of sourceCode’s methods using the includeComments option.
Shebangs are represented by tokens of type "Shebang". They are treated as comments and can be accessed by the methods outlined above.
ESLint analyzes code paths while traversing AST. You can access that code path objects with five events related to code paths.
Each bundled rule for ESLint core must have a set of unit tests submitted with it to be accepted. The test file is named the same as the source file but lives in tests/lib/. For example, if the rule source file is lib/rules/foo.js then the test file should be tests/lib/rules/foo.js.
ESLint provides the RuleTester utility to make it easy to write tests for rules.
To keep the linting process efficient and unobtrusive, it is useful to verify the performance impact of new rules or modifications to existing rules.
When developing in the ESLint core repository, the npm run perf command gives a high-level overview of ESLint running time with all core rules enabled.
$ git checkout master Switched to branch 'master' $ npm run perf CPU Speed is 2200 with multiplier 7500000 Performance Run #1: 1394.689313ms Performance Run #2: 1423.295351ms Performance Run #3: 1385.09515ms Performance Run #4: 1382.406982ms Performance Run #5: 1409.68566ms Performance budget ok: 1394.689313ms (limit: 3409.090909090909ms) $ git checkout my-rule-branch Switched to branch 'my-rule-branch' $ npm run perf CPU Speed is 2200 with multiplier 7500000 Performance Run #1: 1443.736547ms Performance Run #2: 1419.193291ms Performance Run #3: 1436.018228ms Performance Run #4: 1473.605485ms Performance Run #5: 1457.455283ms Performance budget ok: 1443.736547ms (limit: 3409.090909090909ms)
ESLint has a built-in method to track performance of individual rules. Setting the TIMING environment variable will trigger the display, upon linting completion, of the ten longest-running rules, along with their individual running time and relative performance impact as a percentage of total rule processing time.
$ TIMING=1 eslint lib Rule | Time (ms) | Relative :-----------------------|----------:|--------: no-multi-spaces | 52.472 | 6.1% camelcase | 48.684 | 5.7% no-irregular-whitespace | 43.847 | 5.1% valid-jsdoc | 40.346 | 4.7% handle-callback-err | 39.153 | 4.6% space-infix-ops | 35.444 | 4.1% no-undefined | 25.693 | 3.0% no-shadow | 22.759 | 2.7% no-empty-class | 21.976 | 2.6% semi | 19.359 | 2.3%
To test one rule explicitly, combine the --no-eslintrc, and --rule options:
$ TIMING=1 eslint --no-eslintrc --rule "quotes: [2, 'double']" lib Rule | Time (ms) | Relative :------|----------:|--------: quotes | 18.066 | 100.0%
The rule naming conventions for ESLint are fairly simple:
no- such as no-eval for disallowing eval() and no-debugger for disallowing debugger.The thing that makes ESLint different from other linters is the ability to define custom rules at runtime. This is perfect for rules that are specific to your project or company and wouldn’t make sense for ESLint to ship with. With runtime rules, you don’t have to wait for the next version of ESLint or be disappointed that your rule isn’t general enough to apply to the larger JavaScript community, just write your rules and include them at runtime.
Runtime rules are written in the same format as all other rules. Create your rule as you would any other and then follow these steps:
eslint_rules).rules key. Your rule will not run unless it has a value of 1 or 2 in the configuration file.--rulesdir option to specify the location of your runtime rules.
© JS Foundation and other contributors
Licensed under the MIT License.
https://eslint.org/docs/developer-guide/working-with-rules