Adding ESLint to Your Project is Now Easier than Ever

In Get Started with ESLint, I walked through the basics of installing and configuring ESLint 1.0.0. If you haven't started using ESLint yet, now is a great time to give it a try. ESLint has a beta release for version 2.0.0, and one of its new features makes it even easier to start using on your existing projects. This post will explain what this feature is and how to use it.

eslint --version

In order to use the steps in this guide, you will need to install the latest version of ESLint, which currently is 2.0.0-beta.3. To install it, you'll need to run:

npm i eslint@next --save-dev  

For more information about this version and its changes, read the blog post. If you are already familiar with ESLint 1.0, there is a migration guide as well.

The Challenge

ESLint is a very powerful and flexible tool. It currently has about 200 rules built in, new rules are routinely added, and hundreds more are available through plugins. Out of the box, none of these rules are turned on. There is a small set of eslint:recommended rules which you can (and should) enable, but there are many other style rules for which there is no "one-size-fits-all" recommendation. Until now, if you wanted to start using ESLint to its full potential, you needed to read through the hundreds of rule descriptions, decide which ones to enable, and then learn how to configure each one to match your desired style. This can be a daunting, joyless task.

Introducing Automatic Configuration

Chances are good that you have some conventions that you already use in your projects. Maybe you prefer to use single quotes and indent with spaces. Or you use double quotes and tabs. You might already be enforcing these conventions with another linter like JSLint, JSHint, or JSCS. Wouldn't it be great if ESLint could simply look at your code and figure out for itself which ESLint rules you should be using? That's exactly what the new Automatic Configuration feature does.

How Does it Work?

Because it is a linter, ESLint already has the ability to examine your code and determine whether it passes a particular set of rules. That's what it is designed to do. When you run automatic configuration, ESLint will generate multiple sets of rules using different rule configurations and will lint your code using each set. It will then examine the results, find configurations which did not cause linting errors, and choose the most appropriate configuration for each rule.

Limitations

As of the time of this writing (January 29, 2016), there is an issue preventing autoconfig for JSX code.

Additionally, it will not yet work for code which uses experimental JavaScript (ES7+) features. It is planned to add support for such code in a future version.

Try It Out

I recommend installing ESLint locally within your project to avoid headaches later on. So, once you have the latest version installed using the command above, you can kick off the initialization tool from your project's root directory:

node_modules/.bin/eslint --init  

This will present you with three options.

Choose A Method

? How would you like to configure ESLint?
  Answer questions about your style
  Use a popular style guide
❯ Inspect your JavaScript file(s)

There are a few different ways to quickly get started using ESLint. In summary:

  1. Answer questions about your style
    This is the simplest option, and will result in the most loose configuration. You will be asked a few questions about your coding style, and the generated config file will be based on your answers. This is what was shown in my previous post.

  2. Use a popular style guide
    There are many community-developed style guides available as shared ESLint configs. This option was added in ESLint 1.10.0, and allows you to choose from several popular guides (Currently Google, Airbnb, and Standard). The chosen sharable config will be installed into your project if you use this option.

  3. Inspect your JavaScript file(s)
    This is the automatic configuration option we are covering in this post. It will result in the most strict configuration (enabling the most rules) out of the three --init options.

Arrow down and select the third option, Inspect your JavaScript file(s), and press enter.

Choose your Files

? Which file(s), path(s), or glob(s) should be examined?

ESLint needs to know which files should be linted, just like when you run ESLint normally. In fact, in this step you should specify the same files you plan to lint with the configuration that will be generated. The format is the same that is used on the eslint cli. Provide a space-separated list of files, directories, or globs, such as:

bin/cli.js lib tests/**/*{-test,-spec}.js  

The example above would examine the file bin/cli.js, any files with the .js extension within the ./lib/ directory, and any files within the ./tests/ directory ending in -test.js or -spec.js.

Choose a Config File Format

? What format do you want your config file to be in?
❯ JavaScript
  YAML
  JSON

Support for multiple configuration file formats was introduced in ESLint 1.10.0, so you can choose the one you are most comfortable with. Your choice will determine what type of config file is generated at the end of this --init process.

Answer Questions About your Code

Because ESLint is about to parse and lint your code, it needs to know a few things about what to expect. Your answers will allow automatic configuration to occur, and will also be put into the generated configuration so that ESLint runs correctly once you start using it.

? Are you using ECMAScript 6 features? (y/N)

ESLint's default parser, Espree, fully understands all valid ES6 syntax, but it needs to know if those language features are used in your code. If you answer y to this question, you will be asked a follow-up:

? Are you using ES6 modules? (y/N)

Answer y to this question if you are using ES6 Modules (import and export) in your code.

? Where will your code run? (Press <space> to select)
❯◯ Node
 ◉ Browser

Your answer to this question will determine which variables ESLint considers to be globally available because of the environment (and therefore, it won't flag them as undefined). If you are writing code for the browser, you the next question you see will be:

? Do you use CommonJS? (y/N)

If you are using a tool like Browserify or Webpack to use require() in your browser code, answer y.

? Do you use JSX? (y/N)
? Do you use React (y/N)

The parser needs to know if it should expect to find JSX in your code, and if you're using React, ESLint will install the popular eslint-plugin-react for you.

Let It Work

After you have answered all the questions that ESLint needs, it will begin to analyze your code and build a configuration. You'll get a progress bar to watch, because depending on the size of your code, this process could take a while.

Determining Config: 45% [========---------] 7.8s elapsed, eta 9.7s  

If everything completes successfully, you'll get a status message like:

Enabled 149 out of 198 rules based on 252 files.  
Successfully created .eslintrc.json file in <path>  

Examine the Results

You should now be able to run ESLint against the same files you specified earlier.

node_modules/.bin/eslint <files|paths|globs>  

Hopefully, you won't see any linting errors. But if you do, they will be from the recommended rules.

Recommended Rules

If you open the generated config file, you will notice that it extends from the eslint:recommended set of rules. These are rules that the ESLint team believes every project should enable, because they can prevent serious bugs or other problems. So, even if your code was found to fail these rules during automatic configuration, they won't be disabled. If those rules are failing, you have the choice of fixing those problems in your code, or disabling the rules in your config.

Tweak Your Config (Optional)

Hopefully the generated configuration file is a good starting point to get you up-and-running with a meaningful set of rules matching the styles you're already using on your project. But some rules are impossible to automatically configure, so for the best results you should read through the rule documentation and customize your config file. By learning the rules and their options, you can enforce exactly the style and conventions you use on your projects.

Opportunities for Improvement

Of course the automatic configuration feature is not perfect, and there are some ways which it could be improved. Here are some ideas:

  • Currently, a single failure will cause a rule to be disabled. So, if you use double quotes everywhere except for one string, the quotes rule will not be turned on. That one failure is likely a problem that should be fixed, so a threshold could be used to enable rules with a small number of errors.

  • For some rules, ESLint is able to automatically fix errors which it finds. So, if the above idea is implemented, it might be possible to not only enable the rule, but fix the errors at the same time.

  • The React plugin has a large number of custom rules. It would be great to be able to automatically configure those rules as well. Or even automatically configure any given plugin.

How You Can Help

Do you have other ideas or suggestions for how to improve automatic configuration? Did you find a bug or have problems using it? Please swing by our gitter to chat, or file a bug report. I'm @IanVS on GitHub, and I'd love to hear from you.