eslint / eslint

Find and fix problems in your JavaScript code.

ESLint

Website | Configure ESLint | Rules | Contribute to ESLint | Report Bugs | Code of Conduct | Twitter | Discord | Mastodon

ESLint is a tool for identifying and reporting on patterns found in ECMAScript/JavaScript code. In many ways, it is similar to JSLint and JSHint with a few exceptions:

• ESLint uses Espree for JavaScript parsing.
• ESLint uses an AST to evaluate patterns in code.
• ESLint is completely pluggable, every single rule is a plugin and you can add more at runtime.

Table of Contents

1. Installation and Usage
2. Configuration
3. Code of Conduct
4. Filing Issues
5. Frequently Asked Questions
6. Releases
7. Security Policy
8. Semantic Versioning Policy
9. Stylistic Rule Updates
10. License
11. Team
12. Sponsors
13. Technology Sponsors

Installation and Usage

Prerequisites: Node.js (^18.18.0, ^20.9.0, or >=21.1.0) built with SSL support. (If you are using an official Node.js distribution, SSL is always built in.)

You can install and configure ESLint using this command:

npm init @eslint/config

After that, you can run ESLint on any file or directory like this:

./node_modules/.bin/eslint yourfile.js

Configuration

After running npm init @eslint/config, you'll have an eslint.config.js (or eslint.config.mjs) file in your directory. In it, you'll see some rules configured like this:

import pluginJs from "@eslint/js";
export default [ pluginJs.configs.recommended, ];

The names "semi" and "quotes" are the names of rules in ESLint. The first value is the error level of the rule and can be one of these values:

• "off" or 0 - turn the rule off
• "warn" or 1 - turn the rule on as a warning (doesn't affect exit code)
• "error" or 2 - turn the rule on as an error (exit code will be 1)

The three error levels allow you fine-grained control over how ESLint applies rules (for more configuration options and details, see the configuration docs).

Code of Conduct

ESLint adheres to the JS Foundation Code of Conduct.

Filing Issues

Before filing an issue, please be sure to read the guidelines for what you're reporting:

• Bug Report
• Propose a New Rule
• Proposing a Rule Change
• Request a Change

Frequently Asked Questions

I'm using JSCS, should I migrate to ESLint?

Yes. JSCS has reached end of life and is no longer supported.

We have prepared a migration guide to help you convert your JSCS settings to an ESLint configuration.

We are now at or near 100% compatibility with JSCS. If you try ESLint and believe we are not yet compatible with a JSCS rule/configuration, please create an issue (mentioning that it is a JSCS compatibility issue) and we will evaluate it as per our normal process.

Does Prettier replace ESLint?

No, ESLint and Prettier have different jobs: ESLint is a linter (looking for problematic patterns) and Prettier is a code formatter. Using both tools is common, refer to Prettier's documentation to learn how to configure them to work well with each other.

Why can't ESLint find my plugins?

• Make sure your plugins (and ESLint) are both in your project's package.json as devDependencies (or dependencies, if your project uses ESLint at runtime).
• Make sure you have run npm install and all your dependencies are installed.
• Make sure your plugins' peerDependencies have been installed as well. You can use npm view eslint-plugin-myplugin peerDependencies to see what peer dependencies eslint-plugin-myplugin has.

Does ESLint support JSX?

Yes, ESLint natively supports parsing JSX syntax (this must be enabled in configuration). Please note that supporting JSX syntax is not the same as supporting React. React applies specific semantics to JSX syntax that ESLint doesn't recognize. We recommend using eslint-plugin-react if you are using React and want React semantics.

What ECMAScript versions does ESLint support?

ESLint has full support for ECMAScript 3, 5, and every year from 2015 up until the most recent stage 4 specification (the default). You can set your desired ECMAScript syntax and other settings (like global variables) through configuration.

What about experimental features?

ESLint's parser only officially supports the latest final ECMAScript standard. We will make changes to core rules in order to avoid crashes on stage 3 ECMAScript syntax proposals (as long as they are implemented using the correct experimental ESTree syntax). We may make changes to core rules to better work with language extensions (such as JSX, Flow, and TypeScript) on a case-by-case basis.

In other cases (including if rules need to warn on more or fewer cases due to new syntax, rather than just not crashing), we recommend you use other parsers and/or rule plugins. If you are using Babel, you can use @babel/eslint-parser and @babel/eslint-plugin to use any option available in Babel.

Once a language feature has been adopted into the ECMAScript standard (stage 4 according to the TC39 process), we will accept issues and pull requests related to the new feature, subject to our contributing guidelines. Until then, please use the appropriate parser and plugin(s) for your experimental feature.

Which Node.js versions does ESLint support?

ESLint updates the supported Node.js versions with each major release of ESLint. At that time, ESLint's supported Node.js versions are updated to be:

1. The most recent maintenance release of Node.js
2. The lowest minor version of the Node.js LTS release that includes the features the ESLint team wants to use.
3. The Node.js Current release

ESLint is also expected to work with Node.js versions released after the Node.js Current release.

Refer to the Quick Start Guide for the officially supported Node.js versions for a given ESLint release.

Where to ask for help?

Open a discussion or stop by our Discord server.

Why doesn't ESLint lock dependency versions?

Lock files like package-lock.json are helpful for deployed applications. They ensure that dependencies are consistent between environments and across deployments.

Packages like eslint that get published to the npm registry do not include lock files. npm install eslint as a user will respect version constraints in ESLint's package.json. ESLint and its dependencies will be included in the user's lock file if one exists, but ESLint's own lock file would not be used.

We intentionally don't lock dependency versions so that we have the latest compatible dependency versions in development and CI that our users get when installing ESLint in a project.

The Twilio blog has a deeper dive to learn more.

Releases

We have scheduled releases every two weeks on Friday or Saturday. You can follow a release issue for updates about the scheduling of any particular release.

Security Policy

ESLint takes security seriously. We work hard to ensure that ESLint is safe for everyone and that security issues are addressed quickly and responsibly. Read the full security policy.

Semantic Versioning Policy

ESLint follows semantic versioning. However, due to the nature of ESLint as a code quality tool, it's not always clear when a minor or major version bump occurs. To help clarify this for everyone, we've defined the following semantic versioning policy for ESLint:

• Patch release (intended to not break your lint build)
  • A bug fix in a rule that results in ESLint reporting fewer linting errors.
  • A bug fix to the CLI or core (including formatters).
  • Improvements to documentation.
  • Non-user-facing changes such as refactoring code, adding, deleting, or modifying tests, and increasing test coverage.
  • Re-releasing after a failed release (i.e., publishing a release that doesn't work for anyone).
• Minor release (might break your lint build)
  • A bug fix in a rule that results in ESLint reporting more linting errors.
  • A new rule is created.
  • A new option to an existing rule that does not result in ESLint reporting more linting errors by default.
  • A new addition to an existing rule to support a newly-added language feature (within the last 12 months) that will result in ESLint reporting more linting errors by default.
  • An existing rule is deprecated.
  • A new CLI capability is created.
  • New capabilities to the public API are added (new classes, new methods, new arguments to existing methods, etc.).
  • A new formatter is created.
  • eslint:recommended is updated and will result in strictly fewer linting errors (e.g., rule removals).
• Major release (likely to break your lint build)
  • eslint:recommended is updated and may result in new linting errors (e.g., rule additions, most rule option updates).
  • A new option to an existing rule that results in ESLint reporting more linting errors by default.
  • An existing formatter is removed.
  • Part of the public API is removed or changed in an incompatible way. The public API includes:
    • Rule schemas
    • Configuration schema
    • Command-line options
    • Node.js API
    • Rule, formatter, parser, plugin APIs

According to our policy, any minor update may report more linting errors than the previous release (ex: from a bug fix). As such, we recommend using the tilde (~) in package.json e.g. "eslint": "~3.1.0" to guarantee the results of your builds.

Stylistic Rule Updates

Stylistic rules are frozen according to our policy on how we evaluate new rules and rule changes. This means:

• Bug fixes: We will still fix bugs in stylistic rules.
• New ECMAScript features: We will also make sure stylistic rules are compatible with new ECMAScript features.
• New options: We will not add any new options to stylistic rules unless an option is the only way to fix a bug or support a newly-added ECMAScript feature.

License

Team

These folks keep the project moving and are resources for help.

Technical Steering Committee (TSC)

The people who manage releases, review feature requests, and meet regularly to ensure ESLint is properly maintained.

Nicholas C. Zakas

Francesco Trotta

Milos Djermanovic

Reviewers

The people who review and implement new features.

唯然	Nitin Kumar

Committers

The people who review and fix bugs and help triage issues.

Bryan Mishkin

Josh Goldberg ✨

Tanuj Kanti

Website Team

Team members who focus specifically on eslint.org

Amaresh S M

Strek

Percy Ma

Sponsors

The following companies, organizations, and individuals support ESLint's ongoing maintenance and development. Become a Sponsor to get your logo on our README and website.

Platinum Sponsors

Gold Sponsors

Silver Sponsors

Bronze Sponsors

Technology Sponsors

• Site search (eslint.org) is sponsored by Algolia
• Hosting for (eslint.org) is sponsored by Netlify
• Password management is sponsored by 1Password

eslint's Issues

Add all rules from http://jslinterrors.com/ as issues

The site http://jslinterrors.com/ has explanations of all JSLint/JSHint errors. We should be sure that there is an issue for each rule that we haven't yet implemented.

Create way to pass configuration info to rules

I think we need a way to pass config data into rules. Right now, eslint.json allows you to set things as warnings (1) or errors (2), such as:

"rule-name": 1

Perhaps the best way is to make the value an array, like:

"rule-name": [ 1, "config value" ],

Where the second, third, etc. values are the configuration values for the rule.

0.0.3 currently published to npm doesn't work

◼ reginald/root /home/www/diner-beware/lib master npm -g ls jscheck
/usr/local/lib
└── [email protected]

◼ reginald/root /home/www/diner-beware/lib master jscheck data.js
: No such file or directory

I installed directly from the GitHub repo and that worked fine @be12afaf41fb0e363fb3e065b23a2343fa75a007.

Rule: Warn when undeclared variables are used

This rule should warn when a variable is used without being declared first. A prerequisite is adding support for /*global */.

The rule name should be no-undef

Add ability to add custom context and optional plug-ins

I had exactly the same idea about implementing linter for javascript some time ago, I even started writing it (using esprima and per node iterators). But what I wanted to do differently from jshint/jslint is to add an ability to identify frameworks that are used in the code and run custom rules on them.

For example, identifying that user is using Backbone, and running custom rules that would require all models to have initialize function. Or checking for complex selectors if they are using jQuery.

Rule: Warn when initializing to undefined

This rule should warn when a variable is initialized to undefined:

var foo = undefined;

// same as
var foo;

The rule ID should be "no-undef-init" and should be a warning by default.

Rule: Warn when there are unused variables

This rule should warn when a variable or named argument is declared but never used.

Possible exception would be in the case of a catch block, where declaring a variable is required whether you use it or not.

Rulename should be no-unused.

Formatter: JSLint-XML

JSHint offers a JSLint XML format as an output option. So should ESLint.

Formatter: Checkstyle

ESLint should provide checkstyle output like JSHint does.

Carriage return in bin file gives error

I get this error due to the carriage return in the bin file:

env: node\r: No such file or directory

Converting to unix line endings fixed it for me.

Shall I make a pull request for this?

Rule: No redefining

This rule should warn when trying to reassign native objects.

See: http://jslinterrors.com/redefinition-of-a/

The rule ID should be "no-redefine" and should be a warning by default

Feature: sourcemap support

It would be handy there was sourcemap support so errors can be linked to the original sourcecode.

Not only would this would give usefulness for linting output from altjs languages like TypeScript and CoffeeScript but also for vanilla JavaScript tools like uglify2 or grunt-concat-sourcemap.

Rule: Warn for "new" capitalization

This rule should warn when new is used prior to a function that doesn't have a capital letter as the first letter, such as:

var obj = new object();

Rule name should be new-cap.

Warn when switch statement has no cases

This should be covered by no-empty but isn't currently.

Rule: Warn on case fallthrough

We should warn when a case falls through only if:

1. There are statements in the case.
2. There is no comment at the end of the case that says "falls through".

The rule ID should be no-fallthrough

Rule: Warn for alert, confirm, prompt

This rule should warn when alert, confirm, or prompt are used.

The rule ID should be no-alert.

Rule: Warn on unreachable code

We should warn when code is unreachable, i.e., after a return or throw, there should be no other statements.

The rule ID should be no-unreachable.

Complex code breaks validation

If you lint this file using the default settings the validation explodes in (mostly) nonsensical errors:

proto.js: line 1, col 0, Warning - Missing semicolon.
proto.js: line 6, col 4, Warning - Found unexpected statement after a false.
proto.js: line 9, col 4, Warning - Found unexpected statement after a false.
proto.js: line 4, col 8, Warning - Found unexpected statement after a false.
proto.js: line 3, col 26, Warning - Octal literals should not be used.
proto.js: line 3, col 41, Warning - Missing semicolon.
proto.js: line 4, col 8, Warning - Missing semicolon.
proto.js: line 6, col 4, Warning - Missing semicolon.
proto.js: line 7, col 8, Warning - Missing semicolon.
proto.js: line 7, col 8, Warning - Unexpected console statement.
proto.js: line 7, col 20, Warning - Octal literals should not be used.
proto.js: line 11, col 0, Warning - Missing semicolon.
proto.js: line 13, col 4, Warning - Unexpected use of ==, use === instead.
proto.js: line 14, col 4, Warning - Missing semicolon.

14 problems

The line 7, col 8 and line 13, col 4 are expected, but the rest is a bit odd.

Rule: Warn for label that's same as identifier

See:
http://jslinterrors.com/a-is-a-statement-label/

The rule ID should be "no-label-var" and should be enabled as a warning by default.

Rule: Warn on trailing whitespace

This rule should warn when trailing whitespace exists (i.e., any number or combination of tabs or spaces before a newline character).

The rule name should be no-trailing, akin to JSHint's trailing option.

This is tricky because AST doesn't contain whitespace tokens, but Code Painter has a way around this by creating the token anyway. See the Code Painter Tokenizer, lines 105-110.

Hoping, at least, to start a discussion about whether we want to follow Code Painter's approach, submit a PR to esprima for a flag we can set to get whitespace tokens, do something else I haven't thought about or just punt on the whole thing entirely.

I'll submit a broken PR w/ the code that should pass once whitespace is supported.

Formatter: JUnit-XML

We should have a formatter to output results in JUnit XML format. See CSS Lint version:
https://github.com/stubbornella/csslint/blob/master/src/formatters/junit-xml.js

Output error / rule codes and map options to codes

This is not per se a feature request, more of a question if the architecture would allow something like it.

I'd like to have a formatter / post-processor that can group errors based on the rule that generated them. E.g. missing semicolon and indentation errors should get a different weight than undeclared variables and missing brackets. I originally wanted to solve this for JSHint and the SublimeLinter plugin, but it turns out that with JSHInt, there is no 1:1 reference between error codes and options, so it's not possible.

Create a wiki article to track all needed rules

It's hard to work off of jslinterrors, because not all rules are currently implementable (like http://jslinterrors.com/missing-name-in-function-declaration/) and some of them don't really make much sense (at least to me personally, like: http://jslinterrors.com/move-var-declarations-to-the-top-of-the-function/). It would be great to create a list of rules that needs to be ported with the links to the jslinterrors.com for each one. Maybe include the name of the rule as well.

Rule: Do not use 'new' for side effects

See:
http://jslinterrors.com/do-not-use-new-for-side-effects/

The rule ID should be "no-new" and should be enabled as a warning by default.

"DOS" newlines in bin/eslint.js

I tried installing eslint via npm (n i -g eslint which installed [email protected]) and got the following error when running eslint:
env: node\r: No such file or directory

Editing the file and converting it to unix format seemed to fix it. (I'm running on OS X 10.8.4.)

Files don't follow Contributing.md guide for maxlen

.jshintrc needs a maxlen: 80 and all of the files should conform to this rule, or we should remove the requirement from Contributing.md.

I'm happy to do either, it's your call @nzakas

new-parens gives false warning when passing function param to constructor

Run ESLint on this code:

var foo = new Thing(function() { });

You'll get a warning from the new-parens rule:

line 1, col 10, Warning - Missing '()' invoking a constructor

I expected no warning, as the constructor call is properly parenthesized.

This issue occurs when a function (or an object literal containing a function) is among the params passed to the constructor.

Rule: Warn for arguments.callee and arguments.caller

This rule should warn when the code contains arguments.callee or arguments.caller.

The rule name should be no-arg.

Rule: Warn on octal literals

This rule should warn when an octal literal is used.

The rule ID should be "no-octal" and should be a warning by default.

Rule: Warn for dangling commas

This rule should warn when a dangling comma is found in object literal syntax:

var o = {
    prop: value,
};

The rule ID should be "no-dangle"

Man I love this rule ID. :)

Some @fileoverview docstrings need updating

Just pulled down the source so I can start contributing and saw some docstrings that were copied/pasted but not updated (namely in the rules for no-console and no-debugger). Pull request incoming.

Really minor issue, but hey gotta start somewhere right? 👍

Rule: Warn on late definitions of variables/functions

This rule warns when a variable or function is used before it is declared, such as:

doIt();

function doIt() {
}

Rule name should be no-latedef

Rule: Warn when semicolons are missing

This rule should warn when semicolons are missing.

The rule name should be no-asi

Rule: No native assignment

This rule should warn when trying to reassign native objects.

See: http://jslinterrors.com/read-only/

The rule ID should be "no-native-assign" and should be a warning by default

Add EditorConfig file for consistent editor/IDE behavior

See EditorConfig for more information.

Don't report no-empty warnings when a parent is FunctionExpression / FunctionDeclaration

When target is

function t() {
}

or

(function () {
}());

eslint should not report no-empty warnings.

version is 0.0.7-dev master.

Move documentation to /docs

Per Mathias' and Evan's recommendation, the documentation should be moved from the wiki into a /docs directory.

This means:

1. Actually moving the documentation
2. Updating links correctly
3. Coming up with a way to turn the Markdown docs into HTML and publishing them to the gh-pages branch.

Rule: Warn on using constructors for wrapper objects

See:
http://jslinterrors.com/do-not-use-a-as-a-constructor/

The rule ID should be "no-new-wrappers" and should be enabled as a warning by default.

Implement Web UI

I already have eslint.org registered, now it would be nice to have a good web UI to put there. Probably best to use gh-pages in some way.

Rule: No assignement in return statement

This rule should warn when trying to assign a variable within return statement.

See: http://jslinterrors.com/did-you-mean-to-return-a-conditional/

The rule ID should be "no-return-assign" and should be a warning by default

Rule: The Function constructor is eval

See:
http://jslinterrors.com/the-function-constructor-is-eval/

The rule ID should be "no-function-ctor" and should be enabled as a warning by default.

Rule: Warn on missing '()' invoking a constructor

See:
http://jslinterrors.com/missing-invoking-a-constructor/

The rule ID should be "new-parens" and should be enabled as a warning by default.

Setup gh-pages with documentation

We need to set up the gh-pages branch with the content in /docs so that it's nice and pretty and will show up at nzakas.github.io/eslint. I've already registered eslint.org, which I can redirect there once we have some comments.

This is basically setting up a Jekyll repository with the docs we have now. Once this happens, I'll setup a script to automatically update that repository with stuff from /docs whenever it's updated.

Validate that files exist

Right now, if you pass in a file that doesn't exist to eslint, it explodes. We need to handle this nicely and exit with a non-zero exit code. Having a nice message like "Could not find file foo/bar.js" is a good idea.

Perhaps it also shouldn't continue if any one of the files can't be found, so make this a pre-pass before doing any actual linting.

Rule: Warn for unguarded for-in loops

Legacy from JSHint/JSLint: warn when you do this:

for (prop in obj) {
    // body
}

Instead of this:

for (prop in obj) {
    if (obj.hasOwnProperty(prop)) {

    }
}

Must also work even when the for-in loop body doesn't have braces around it (aka, whether or not there is a BlockStatement as the body).

Rule name should be guard-for-in

Upgrade the formatter api

I was adding a formatter but the current ESHint formatter api is over simplified, especially compared to the original JSHint reporter api.

Main thing is that ESHint's formatter API is less suited for usable report output when linting multiple files: it works per-file so if you lint 4 clean files you see 4 times the '0 problems' message. This makes it impossible to collect a nice 'found 8 problems in 4 files' type of summaries.

JSHint works a bit better because the reporter receiver all the data at once: they didn't get it right in first go either, but if you look past the legacy support you see that it gets an array with each element representing a single file, which then has some fields (like the file path) and an errors array with all the messages originating from that file.

And maybe it should be 'reporter' (and not just 'formatter') and have the actual output responsibility at the reporter's end (and not the validator).

Rule: Warn on unwrapped IIFEs

Should warn whenever we see this pattern:

var foo = function() {

}();

There should be parentheses around the function.

Rule name should be immed

Camelcase rule to accept leading underscores

This is probably a matter of taste, but since I think the leading underscore a pretty common pattern for marking private identifiers, I think the camelcase rule should probably not take it into account.

Going this way also would mean no special case for __dirname and __filename in nodeJs mode is required.

Submitting a pull request now...

Rule: Variables should not be deleted

This rule should warn when trying to delete a variable.

See: http://jslinterrors.com/variables-should-not-be-deleted/

The rule ID should be "no-delete-var" and should be a warning by default

Feature: Support /*global */

Both JSHint and JSLint support declaring globals via /*global */. JSCheck should too.

Unsure how to implement this, but most likely as a globals key on the config object.