Node.js API

While ESLint is designed to be run on the command line, it’s possible to use ESLint programmatically through the Node.js API. The purpose of the Node.js API is to allow plugin and tool authors to use the ESLint functionality directly, without going through the command line interface.

Note: Use undocumented parts of the API at your own risk. Only those parts that are specifically mentioned in this document are approved for use and will remain stable and reliable. Anything left undocumented is unstable and may change or be removed at any point.

SourceCode

The SourceCode type represents the parsed source code that ESLint executes on. It’s used internally in ESLint and is also available so that already-parsed code can be used. You can create a new instance of SourceCode by passing in the text string representing the code and an abstract syntax tree (AST) in ESTree format (including location information, range information, comments, and tokens):

In this way, you can retrieve the text and AST used for the last run of linter.verify().

CLIEngine

The primary Node.js API is CLIEngine, which is the underlying utility that runs the ESLint command line interface. This object will read the filesystem for configuration and file information but will not output any results. Instead, it allows you direct access to the important information so you can deal with the output yourself.

You can get a reference to the CLIEngine by doing the following:

varCLIEngine=require("eslint").CLIEngine;

The CLIEngine is a constructor, and you can create a new instance by passing in the options you want to use. The available options are:

configFile - The configuration file to use (default: null). Corresponds to -c.

In this code, a new CLIEngine instance is created that sets two environments, "browser" and "mocha", disables loading of .eslintrc and package.json files, and enables the semi rule as an error. You can then call methods on cli and these options will be used to perform the correct action.

executeOnFiles()

If you want to lint one or more files, use the executeOnFiles() method. This method accepts a single argument, which is an array of files and/or directories to traverse for files. You can pass the same values as you would using the ESLint command line interface, such as "." to search all JavaScript files in the current directory. Here’s an example:

varCLIEngine=require("eslint").CLIEngine;varcli=newCLIEngine({envs:["browser","mocha"],useEslintrc:false,rules:{semi:2}});// lint myfile.js and all files in lib/varreport=cli.executeOnFiles(["myfile.js","lib/"]);

The return value is an object containing the results of the linting operation. Here’s an example of a report object:

{results:[{filePath:"./myfile.js",output:"foo;",messages:[{fatal:false,severity:2,ruleId:"semi",severity:2,line:1,column:23,message:"Expected a semicolon."}],errorCount:1,warningCount:0}],errorCount:1,warningCount:0}

The top-level report object has a results array containing all linting results for files that had warnings or errors (any files that did not produce a warning or error are omitted). Each file result includes the filePath, a messages array, errorCount, warningCount, and optionally output. The messages array contains the result of calling linter.verify() on the given file. The errorCount and warningCount give the exact number of errors and warnings respectively on the given file. The output property gives the source code for the file with as many fixes applied as possible, so you can use that to rewrite the files if necessary. The top-level report object also has errorCount and warningCount which give the exact number of errors and warnings respectively on all the files.

Once you get a report object, it’s up to you to determine how to output the results.

resolveFileGlobPatterns()

You can pass filesystem-style or glob patterns to ESLint and have it function properly. In order to achieve this, ESLint must resolve non-glob patterns into glob patterns before determining which files to execute on. The resolveFileGlobPatterns() methods uses the current settings from CLIEngine to resolve non-glob patterns into glob patterns. Pass an array of patterns that might be passed to the ESLint CLI and it will return an array of glob patterns that mean the same thing. Here’s an example:

getConfigForFile()

If you want to retrieve a configuration object for a given file, use the getConfigForFile() method. This method accepts one argument, a file path, and returns an object represented the calculated configuration of the file. Here’s an example:

executeOnText()

If you already have some text to lint, then you can use the executeOnText() method to lint that text. The linter will assume that the text is a file in the current working directory, and so will still obey any .eslintrc and .eslintignore files that may be present. Here’s an example:

varCLIEngine=require("eslint").CLIEngine;varcli=newCLIEngine({envs:["browser","mocha"],useEslintrc:false,rules:{semi:2}});// lint the supplied text and optionally set// a filename that is displayed in the reportvarreport=cli.executeOnText("var foo = 'bar';","foo.js");

The report returned from executeOnText() is in the same format as from executeOnFiles(), but there is only ever one result in report.results.

addPlugin()

Loads a plugin from configuration object with specified name. Name can include plugin prefix (“eslint-plugin-“)

or the full path to a JavaScript file containing a custom formatter. You can also omit the argument to retrieve the default formatter.

varCLIEngine=require("eslint").CLIEngine;varcli=newCLIEngine({envs:["browser","mocha"],useEslintrc:false,rules:{semi:2}});// lint myfile.js and all files in lib/varreport=cli.executeOnFiles(["myfile.js","lib/"]);// get the default formattervarformatter=cli.getFormatter();// Also could do...// var formatter = cli.getFormatter("compact");// var formatter = cli.getFormatter("./my/formatter.js");// output to consoleconsole.log(formatter(report.results));

Note: Also available as a static function on CLIEngine.

// get the default formatter by calling the static functionvarformatter=CLIEngine.getFormatter();

Important: You must pass in the results property of the report. Passing in report directly will result in an error.

getErrorResults()

This is a static function on CLIEngine. It can be used to filter out all the non error messages from the report object.

varCLIEngine=require("eslint").CLIEngine;varcli=newCLIEngine({envs:["browser","mocha"],useEslintrc:false,rules:{semi:2}});// lint myfile.js and all files in lib/varreport=cli.executeOnFiles(["myfile.js","lib/"]);// only get the error messagesvarerrorReport=CLIEngine.getErrorResults(report.results)

Important: You must pass in the results property of the report. Passing in report directly will result in an error.

outputFixes()

This is a static function on CLIEngine that is used to output fixes from report to disk. It does by looking for files that have an output property in their results. Here’s an example:

varCLIEngine=require("eslint").CLIEngine;varcli=newCLIEngine({envs:["browser","mocha"],useEslintrc:false,rules:{semi:2}});// lint myfile.js and all files in lib/varreport=cli.executeOnFiles(["myfile.js","lib/"]);// output fixes to diskCLIEngine.outputFixes(report);

Deprecated APIs

cli - the cli object has been deprecated in favor of CLIEngine. As of v1.0.0, cli is no longer exported and should not be used by external tools.