How to use eslint
How to use eslint
Why (and how) to use eslint in your project
npmjs.org has 100s of thousands of packages, but that doesn’t mean they are of equal quality. Its important to check how well managed your direct dependencies are. No single missing management practice should eliminate a package from your consideration if the features are right, but when you have a choice of packages, pick ones that are well managed — or be prepared to maintain the package yourself!
I intend to write about a handful of the practices I use to evaluate projects:
Today’s topic is linting.
Why lint your JavaScript?
Well run projects have clear consistent coding conventions, with automated enforcement. When I review a project, and its code looks like a house built by a child using nothing but a hatchet and a picture of a house, it doesn’t inspire confidence that the code is functional.
Not having coding conventions is also a barrier to attracting contributions, and depending on a project that does not welcome (quality!) contributions is itself a risk.
Besides checking style, linters are also excellent tools for finding certain classes of bugs, such as those related to variable scope. Assignment to undeclared variables (these leak into the global scope, contaminating it and possibly causing very difficult to find bugs) and use of undefined variables are examples of errors that are detectable at lint time.
How to configure eslint?
eslint is the dominant tool for linting Node.js packages, and can be configured to enforce multiple coding styles. It is possible to define your own style definitions, but here I will show how to use the StrongLoop style. There are others, but StrongLoop’s style is unremarkable (a good thing, coding style should not attract attention), and is similar to that used in many open-source Node.js projects.
Install and save package dependencies:
Setup eslint to use the strongloop configuration by running:
With this setup, configure eslint to run automatically before your tests by changing your package.json to have a pretest script. It should look similar to this:
Commit the eslint automation support:
Once this is complete, run the linter:
Do not get discouraged if your console is awash in a sea of errors!
How do we get existing code to lint clean?
One reason some avoid using eslint is that cleaning up never-before-linted code can feel like cleaning the Augean stables. I recommend doing as Hercules did: get help from tools.
eslint can automatically fix many syntactic problems automatically, this should be the first tool you use to clean up your source:
If you have an eslint pretest script, you can also do:
You may find that your code uses a consistent style, but is not StrongLoop’s style. If it is close, you can customize the StrongLoop style, and publish it as your own. If your style is radically different, it could make sense to just write and publish your own reuseable configuration.
Once your code lints cleanly (check with npm run pretest ), commit the result:
Automate it
There are two levels of automation, project wide policy, and your own personal setup.
In terms of project wide policy, because eslint is configured to run with your tests, there is nothing more to do. Unless you don’t run your tests automatically for your project, in which case it is time to start!
In terms of my own personal setup, I prefer eslint to be run on every one of my commits, so any problems I introduce are caught on my machine before they are caught by CI. I do this with a git “pre-commit” hook. To set this up, use the example hook as a base:
The last lines of the file will look like this:
Change it to look like:
Congratulations!
Developer Guide
This guide is intended for those who wish to:
In order to work with ESLint as a developer, it’s recommended that:
If that sounds like you, then continue reading to get started.
Section 1: Get the Source Code
Before you can get started, you’ll need to get a copy of the ESLint source code. This section explains how to do that and a little about the source code structure.
Section 2: Set up a Development Environment
Developing for ESLint is a bit different than running it on the command line. This section shows you how to set up a development environment and get you ready to write code.
Section 3: Run the Unit Tests
There are a lot of unit tests included with ESLint to make sure that we’re keeping on top of code quality. This section explains how to run the unit tests.
Section 4: Working with Rules
You’re finally ready to start working with rules. You may want to fix an existing rule or create a new one. This section explains how to do all of that.
Section 5: Working with Plugins
You’ve developed library-specific rules for ESLint and you want to share them with the community. You can publish an ESLint plugin on npm.
Section 6: Working with Custom Parsers
If you aren’t going to use the default parser of ESLint, this section explains about using custom parsers.
Section 7: Node.js API
If you’re interested in writing a tool that uses ESLint, then you can use the Node.js API to get programmatic access to functionality.
Section 8: Contributing
Once you’ve made changes that you want to share with the community, the next step is to submit those changes back via a pull request.
ESLint
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:
Table of Contents
Installation and Usage
You can install and configure ESLint using this command:
After that, you can run ESLint on any file or directory like this:
Configuration
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:
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
Filing Issues
Before filing an issue, please be sure to read the guidelines for what you’re reporting:
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 does both traditional linting (looking for problematic patterns) and style checking (enforcement of conventions). You can use ESLint for everything, or you can combine both using Prettier to format your code and ESLint to catch possible errors.
Why can’t ESLint find my plugins?
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 (default), 2015, 2016, 2017, 2018, 2019, 2020, 2021 and 2022. You can set your desired ECMAScript syntax (and other settings, like global variables or your target environments) 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.
Where to ask for help?
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.
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:
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:
License
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.
Reviewers
The people who review and implement new features.
Committers
The people who review and fix bugs and help triage issues.
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.
eslint/eslint
Use Git or checkout with SVN using the web URL.
Work fast with our official CLI. Learn more.
Launching GitHub Desktop
If nothing happens, download GitHub Desktop and try again.
Launching GitHub Desktop
If nothing happens, download GitHub Desktop and try again.
Launching Xcode
If nothing happens, download Xcode and try again.
Launching Visual Studio Code
Your codespace will open once ready.
There was a problem preparing your codespace, please try again.
Latest commit
Git stats
Files
Failed to load latest commit information.
README.md
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:
Table of Contents
Installation and Usage
You can install and configure ESLint using this command:
After that, you can run ESLint on any file or directory like this:
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:
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
Before filing an issue, please be sure to read the guidelines for what you’re reporting:
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 does both traditional linting (looking for problematic patterns) and style checking (enforcement of conventions). You can use ESLint for everything, or you can combine both using Prettier to format your code and ESLint to catch possible errors.
Why can’t ESLint find my plugins?
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 (default), 2015, 2016, 2017, 2018, 2019, 2020, 2021 and 2022. You can set your desired ECMAScript syntax (and other settings, like global variables or your target environments) 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.
Where to ask for help?
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.
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.
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.
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:
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:
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.
The people who review and implement new features.
The people who review and fix bugs and help triage issues.
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.
About
Find and fix problems in your JavaScript code.
Command Line Interface
ESLint requires Node.js for installation. Follow the instructions in the Getting Started Guide to install ESLint.
Most users use npx to run ESLint on the command line like this:
Please note that when passing a glob as a parameter, it will be expanded by your shell. The results of the expansion can vary depending on your shell, and its configuration. If you want to use node glob syntax, you have to quote your parameter (using double quotes if you need it to run in Windows), as follows:
Note: You can also use alternative package managers such as Yarn or pnpm to run ESLint. Please refer to your package manager’s documentation for the correct syntax.
Options
Basic configuration
—no-eslintrc
This option allows you to specify an additional configuration file for ESLint (see Configuring ESLint for more).
This example uses the configuration file at
This option enables specific environments. Details about the global variables defined by each environment are available on the Specifying Environments documentation. This option only enables environments; it does not disable environments set in other configuration files. To specify multiple environments, separate them using commas, or use the option multiple times.
This option allows you to specify which file extensions ESLint will use when searching for target files in the directories you specify. By default, ESLint lints *.js files and the files that match the overrides entries of your configuration.
—global
This option defines global variables so that they will not be flagged as undefined by the no-undef rule. Any specified global variables are assumed to be read-only by default, but appending :true to a variable’s name ensures that no-undef will also allow writes. To specify multiple global variables, separate them using commas, or use the option multiple times.
—parser
This option allows you to specify a parser to be used by ESLint. By default, espree will be used.
—parser-options
This option allows you to specify parser options to be used by ESLint. Note that the available parser options are determined by the parser being used.
—resolve-plugins-relative-to
Changes the folder where plugins are resolved from. By default, plugins are resolved from the current working directory. This option should be used when plugins were installed by someone other than the end user. It should be set to the project directory of the project that has a dependency on the necessary plugins. For example:
Specifying rules and plugins
—plugin
This option specifies a plugin to load. You can omit the prefix eslint-plugin- from the plugin name.
Before using the plugin, you have to install it using npm.
—rulesdir
Deprecated: Use rules from plugins instead.
This option allows you to specify another directory from which to load rules files. This allows you to dynamically load new rules at run time. This is useful when you have custom rules that aren’t suitable for being bundled with ESLint.
Fixing problems
This option instructs ESLint to try to fix as many issues as possible. The fixes are made to the actual files themselves and only the remaining unfixed issues are output. Not all problems are fixable using this option, and the option does not work in these situations:
—fix-dry-run
Because the default formatter does not output the fixed code, you’ll have to use another one (e.g. json ) to get the fixes. Here’s an example of this pattern:
This flag can be useful for integrations (e.g. editor plugins) which need to autofix text from the command line without saving it to the filesystem.
—fix-type
You can specify one or more fix type on the command line. Here are some examples:
This option is helpful if you are using another program to format your code but you would still like ESLint to apply other types of fixes.
Ignoring files
—ignore-path
—no-ignore
—ignore-pattern
Using stdin
—stdin
This option tells ESLint to read and lint source code from STDIN instead of from files. You can use this to pipe code to ESLint.
—stdin-filename
This option allows you to specify a filename to process STDIN as. This is useful when processing files from STDIN and you have rules which depend on the filename.
Handling warnings
—quiet
This option allows you to disable reporting on warnings. If you enable this option, only errors are reported by ESLint.
—max-warnings
This option allows you to specify a warning threshold, which can be used to force ESLint to exit with an error status if there are too many warning-level rule violations in your project.
Output
Enable report to be written to a file.
When specified, the given format is output into the provided file name.
This option specifies the output format for the console. Possible formats are:
You can also use a custom formatter from the command line by specifying a path to the custom formatter file.
An npm-installed formatter is resolved with or without eslint-formatter- prefix.
When specified, the given format is output to the console. If you’d like to save that output into a file, you can do so on the command line like so:
This saves the output into the results.txt file.
Inline configuration comments
—no-inline-config
This option prevents inline comments like /*eslint-disable*/ or /*global foo*/ from having any effect. This allows you to set an ESLint config without files modifying it. All inline config comments are ignored, e.g.:
—report-unused-disable-directives
This option causes ESLint to report directive comments like // eslint-disable-line when no errors would have been reported on that line anyway. This can be useful to prevent future errors from unexpectedly being suppressed, by cleaning up old eslint-disable comments which are no longer applicable.
Warning: When using this option, it is possible that new errors will start being reported whenever ESLint or custom rules are upgraded. For example, suppose a rule has a bug that causes it to report a false positive, and an eslint-disable comment is added to suppress the incorrect report. If the bug is then fixed in a patch release of ESLint, the eslint-disable comment will become unused since ESLint is no longer generating an incorrect report. This will result in a new reported error for the unused directive if the report-unused-disable-directives option is used.
Caching
—cache
Note: Autofixed files are not placed in the cache. Subsequent linting that does not trigger an autofix will place it in the cache.
—cache-file
—cache-location
Important note: If the directory for the cache does not exist make sure you add a trailing / on *nix systems or \ in windows. Otherwise the path will be assumed to be a file.
—cache-strategy
The content strategy can be useful in cases where the modification time of your files change even if their contents have not. For example, this can happen during git operations like git clone because git does not track file modification time.
Miscellaneous
The resulting configuration file will be created in the current directory.
—env-info
This option outputs information about the execution environment, including the version of Node, npm, and local and global installations of ESLint. The ESLint team may ask for this information to help solve bugs.
—no-error-on-unmatched-pattern
—exit-on-fatal-error
This option causes ESLint to exit with exit code 2 if one or more fatal parsing errors occur. Without this option, fatal parsing errors are reported as rule violations.
—debug
This option outputs the help menu, displaying all of the available options. All other options are ignored when this is present.
This option outputs the current ESLint version onto the console. All other options are ignored when this is present.
—print-config
This option outputs the configuration to be used for the file passed. When present, no linting is performed and only config-related options are valid.
Ignoring files from linting
A more detailed breakdown of supported patterns and directories ESLint ignores by default can be found in Ignoring Code.
Exit codes
When linting files, ESLint will exit with one of the following exit codes: