Customizing ESLint

From the blog:
SurviveJS - Webpack - v1.8

Even though you can get far with vanilla ESLint, there are certain techniques you should be aware of. For instance, sometimes you might want to skip some rules per file. You might even want to implement rules of your own. We'll cover these cases briefly next.

Skipping ESLint Rules#

Sometimes, you'll want to skip certain rules per file or per line. This can be useful when you happen to have some exceptional case in your code where some rule doesn't make sense. As usual, exception confirms the rule. Consider the following examples:

// everything
/* eslint-disable */
...
/* eslint-enable */
// specific rule
/* eslint-disable no-unused-vars */
...
/* eslint-enable no-unused-vars */
// tweaking a rule
/* eslint no-comma-dangle:1 */
// disable rule per line
alert('foo'); // eslint-disable-line no-alert

Note that the rule specific examples assume you have the rules in your configuration in the first place! You cannot specify new rules here. Instead, you can modify the behavior of existing rules.

Setting Environment#

Sometimes, you may want to run ESLint in a specific environment, such as Node or Mocha. These environments have certain conventions of their own. For instance, Mocha relies on custom keywords (e.g., describe, it) and it's good if the linter doesn't choke on those.

ESLint provides two ways to deal with this: local and global. If you want to set it per file, you can use a declaration at the beginning of a file:

/*eslint-env node, mocha */

Global configuration is possible as well. In this case, you can use env key like this:

.eslintrc.js

module.exports = {
  "env": {
    "browser": true,
    "commonjs": true,
    "es6": true,
    "node": true,
  },
  ...
};

Writing ESLint Plugins#

ESLint plugins rely on Abstract Syntax Tree (AST) definition of JavaScript. It is a data structure that describes JavaScript code after it has been lexically analyzed. There are tools, such as recast, that allow you to perform transformations on JavaScript code by using AST transformations. The idea is that you match some structure, then transform it somehow and convert AST back to JavaScript.

Understanding AST#

To get a better idea of how AST works and what it looks like, you can check Esprima online JavaScript AST visualization or AST Explorer by Felix Kling. Alternately, you can install recast and examine the output it gives. That is the structure we'll be working with for ESLint rules.

Codemod allows you to perform large scale changes to your codebase through AST based transformations.

Writing a Plugin#

In ESLint's case, we want to check the structure and report in case something is wrong. Getting a simple rule done is simple:

  1. Set up a new project named eslint-plugin-custom. You can replace custom with whatever you want. ESLint follows this naming convention.
  2. Execute npm init -y to create a dummy package.json
  3. Set up index.js in the project root with content like this:

eslint-plugin-custom/index.js

module.exports = {
  rules: {
    demo: {
      docs: {
        description: 'Demo rule',
        category: 'Best Practices',
        recommended: true,
      },
      schema: [{
        type: 'object',
        // JSON Schema to describe properties
        properties: {},
        additionalProperties: false,
      }],
      create: function(context) {
        return {
          Identifier: function(node) {
            context.report(node, 'This is unexpected!');
          },
        };
      },
    },
  },
};

In this case, we report for every identifier found. In practice, you'll likely want to do something more complex than this, but this is a good starting point.

Next, you need to execute npm link within eslint-plugin-custom. This will make your plugin visible within your system. npm link allows you to easily consume a development version of a library you are developing. To reverse the link you can execute npm unlink when you feel like it.

If you want to do something serious, you should point to your plugin through package.json.

We need to alter our project configuration to make it find the plugin and the rule within.

.eslintrc

{
  ...
  "plugins": [
"react",
"react", "custom"
], "rules": {
"custom/demo": 1,
... } }

If you invoke ESLint now, you should see a bunch of warnings. Of course, the rule doesn't do anything useful yet. To move forward, I recommend checking out the official documentation about plugins and rules.

You can also check out some of the existing rules and plugins for inspiration to see how they achieve certain things. ESLint allows you to extend these rulesets through extends property. It accepts either a path to it ("extends": "./node_modules/coding-standard/.eslintrc") or an array of paths. The entries are applied in the given order, and later ones override the former.

ESLint Resources#

Besides the official documentation available at eslint.org, you should check out the following blog posts:

If you want a starting point, you can pick one of eslint-config- packages or go with the standard style.

This book is available through Leanpub. By purchasing the book you support the development of further content. A part of profit (~30%) goes to Tobias Koppers, the author of Webpack.

Need help?