Build Your Own ESLint Rules

ESLint is a fantastic tool for maintaining code quality and consistency. While it comes with a ton of built-in rules, sometimes you need something more specific to your project or team’s workflow. That’s where building your own custom ESLint rules comes in.

Let’s break down how to do it. It’s not as daunting as it might seem.

Understanding ASTs

Before we write any code, we need to understand what ESLint actually looks at: the Abstract Syntax Tree (AST). When ESLint analyzes your JavaScript code, it doesn’t read it as plain text. Instead, it parses it into a tree-like structure that represents the code’s grammatical structure. Tools like AST Explorer are invaluable for visualizing these trees. You can paste your code and see how it translates into nodes.

Each node in the AST represents a part of your code, like a variable declaration, a function call, or an if statement. Your custom ESLint rule will essentially navigate this tree to find specific patterns or structures you want to enforce or disallow.

The Structure of a Custom Rule

An ESLint rule is a JavaScript module that exports an object. This object typically has a few key properties:

• meta: Contains metadata about the rule, like its description, category, and whether it can be automatically fixed.
• create: A function that returns an object. This returned object contains methods named after AST node types (like CallExpression, Identifier, VariableDeclaration). ESLint calls these methods whenever it encounters a node of that type in your code.

Creating Your First Rule

Let’s create a simple rule that disallows the use of console.log. This is a common practice in production code.

First, create a directory for your custom rules, maybe named eslint-rules in your project’s root.

Inside eslint-rules, create a file named no-console-log.js:

1
module.exports = {
2
  meta: {
3
    type: "problem", // Or "suggestion", "layout"
4
    docs: {
5
      description: "Disallow the use of console.log",
6
      category: "Best Practices",
7
      recommended: true,
8
    },
9
    fixable: null, // Or "code", "whitespace"
10
    schema: [], // If your rule accepts options, define them here
11
  },
12
  create: function(context) {
13
    // The `context` object provides information about the file being linted
14
    // and methods to report problems.
15
    return {
16
      CallExpression(node) {
17
        // Check if the callee is a console object and the method is log
18
        if (
19
          node.callee.type === "MemberExpression" &&
20
          node.callee.object.name === "console" &&
21
          node.callee.property.name === "log"
22
        ) {
23
          context.report({
24
            node: node, // The node where the problem was found
25
            message: "Unexpected console.log found. Remove it before committing.",
26
          });
27
        }
28
      },
29
    };
30
  },
31
};

In this rule:

• meta.type: “problem” indicates it’s a code error.
• meta.docs.description: Explains what the rule does.
• create: Returns an object with a CallExpression visitor.
• CallExpression(node): This function is called for every function call in the code.
• Inside CallExpression, we check if the function being called is console.log.
• context.report: If it is console.log, we report an error with a message.

Integrating Your Rule

To use your custom rule, you need to tell ESLint where to find it. You can do this in your .eslintrc.js (or .json, .yml) file.

First, install ESLint if you haven’t already:

1
npm install eslint --save-dev

Then, configure your .eslintrc.js:

1
module.exports = {
2
  // ... other configurations
3
  plugins: [
4
    // ... other plugins
5
    './eslint-rules' // Path to your custom rules directory
6
  ],
7
  rules: {
8
    // ... other rules
9
    'no-console-log': 'error', // Enable your custom rule
10
  },
11
};

Make sure the path in plugins is correct relative to your .eslintrc.js file.

Now, when you run ESLint, it will check for console.log statements and report them as errors.

Making Rules Fixable

For rules like our no-console-log example, you might want ESLint to automatically fix the problem. To do this:

1. Set meta.fixable to "code" in your rule’s meta object.
2. Modify your context.report call to include a fix function.

Here’s the updated no-console-log.js for a fixable rule:

1
module.exports = {
2
  meta: {
3
    type: "problem",
4
    docs: {
5
      description: "Disallow the use of console.log",
6
      category: "Best Practices",
7
      recommended: true,
8
    },
9
    fixable: "code", // Set to "code" to enable auto-fixing
10
    schema: [],
11
  },
12
  create: function(context) {
13
    return {
14
      CallExpression(node) {
15
        if (
16
          node.callee.type === "MemberExpression" &&
17
          node.callee.object.name === "console" &&
18
          node.callee.property.name === "log"
19
        ) {
20
          context.report({
21
            node: node,
22
            message: "Unexpected console.log found. Remove it.",
23
            fix: function(fixer) {
24
              // Remove the entire function call expression
25
              return fixer.remove(node);
26
            },
27
          });
28
        }
29
      },
30
    };
31
  },
32
};

With this change, you can run ESLint with the --fix flag (eslint --fix .), and ESLint will automatically remove all console.log statements it finds.

Conclusion

Building custom ESLint rules is a powerful way to enforce project-specific standards, improve code quality, and maintain consistency across your codebase. By understanding ASTs and the structure of ESLint rules, you can create powerful tools to automate code checks and even fixes. It’s a worthwhile skill for any serious JavaScript developer.