Crafting a Custom JavaScript ESLint Rule

ESLint has become an indispensable tool for maintaining code quality and consistency in modern JavaScript projects. While it comes with a vast collection of built-in rules, there are times when you need to enforce a specific coding convention or pattern that isn't covered. This is where the power of custom ESLint rules comes in. In this post, we'll dive deep into the world of custom ESLint rules, exploring how to create your own rules to enforce your team's unique coding standards. We'll cover the fundamentals of Abstract Syntax Trees (ASTs), the core of ESLint's rule engine, and walk through the process of creating a custom rule from scratch, including testing and integration.

Understanding the Foundation: Abstract Syntax Trees (ASTs)

Before we can write custom ESLint rules, we need to understand the data structure that ESLint uses to represent and analyze code: the Abstract Syntax Tree (AST). An AST is a tree-like representation of your code's syntactic structure. Each node in the tree represents a construct in the code, such as a function declaration, a variable declaration, or an expression.

ESLint uses a parser (by default, Espree) to convert your JavaScript code into an AST that conforms to the ESTree specification. This standardized format allows ESLint and other tools to work with a consistent representation of the code, regardless of the original source formatting.

To get a better sense of what an AST looks like, you can use a tool like the AST Explorer. Paste in some JavaScript code, and it will show you the corresponding AST. This is an invaluable tool for understanding the structure of your code and identifying the nodes you'll need to target in your custom rule.

Here's a simple example. Consider this line of code:

const greeting = "Hello, world!";

The AST for this code would look something like this (simplified for clarity):

{
  "type": "VariableDeclaration",
  "declarations": [
    {
      "type": "VariableDeclarator",
      "id": {
        "type": "Identifier",
        "name": "greeting"
      },
      "init": {
        "type": "Literal",
        "value": "Hello, world!",
        "raw": "\"Hello, world!\""
      }
    }
  ],
  "kind": "const"
}

As you can see, the AST breaks down the code into its constituent parts, making it easy to programmatically analyze and manipulate.

The Anatomy of an ESLint Rule

An ESLint rule is a JavaScript module that exports an object with a create method. This create method returns an object with methods that ESLint calls as it traverses the AST. The names of these methods correspond to the type of the AST nodes you want to visit.

Here's the basic structure of a custom ESLint rule:

module.exports = {
  meta: {
    type: "suggestion", // "problem", "suggestion", or "layout"
    docs: {
      description: "A description of your rule",
      category: "Best Practices",
      recommended: false,
    },
    fixable: "code", // or "whitespace"
    schema: [] // options for the rule
  },

  create: function(context) {
    return {
      // visitor methods go here
    };
  }
};

Let's break down the meta object:

• type: Indicates the type of rule.
  • "problem": The rule is flagging a potential error in the code.
  • "suggestion": The rule is suggesting a better way to do something.
  • "layout": The rule is concerned with whitespace, semicolons, etc.
• docs: Provides documentation for the rule.
• fixable: Specifies whether the rule can automatically fix the problems it finds.
• schema: Defines the options that can be passed to the rule.

The create function is the heart of your rule. It takes a context object as an argument, which provides information about the code being linted and allows you to report problems. The create function should return an object containing "visitor" methods. These methods are called when ESLint encounters a node of a specific type in the AST.

Creating a Custom Rule: no-restricted-globals

Let's create a custom rule that disallows the use of a specific global variable. For this example, we'll create a rule called no-restricted-globals that prevents the use of the alert global.

First, we'll create the rule file, no-restricted-globals.js:

module.exports = {
  meta: {
    type: "problem",
    docs: {
      description: "Disallow the use of the 'alert' global",
      category: "Best Practices",
      recommended: true,
    },
    fixable: null,
    schema: [],
  },

  create: function (context) {
    return {
      Identifier(node) {
        if (node.name === "alert") {
          context.report({
            node: node,
            message: "The 'alert' global is not allowed.",
          });
        }
      },
    };
  },
};

In this rule, we're visiting every Identifier node in the AST. Inside the Identifier visitor method, we check if the name of the identifier is "alert". If it is, we use the context.report() method to report a problem.

Testing Your Rule

Testing is a crucial part of developing a custom ESLint rule. ESLint provides a RuleTester utility that makes it easy to write tests for your rules.

Here's an example of how you would test our no-restricted-globals rule:

const { RuleTester } = require("eslint");
const rule = require("../../../lib/rules/no-restricted-globals");

const ruleTester = new RuleTester();

ruleTester.run("no-restricted-globals", rule, {
  valid: [
    {
      code: "console.log('Hello, world!');",
    },
  ],

  invalid: [
    {
      code: "alert('Hello, world!');",
      errors: [{ message: "The 'alert' global is not allowed." }],
    },
  ],
});

The RuleTester takes two arrays of test cases: valid and invalid. The valid cases are code snippets that should not trigger the rule. The invalid cases are code snippets that should trigger the rule, and they include the expected error message.

Integrating Your Custom Rule

To use your custom rule in a project, you have a few options:

1. Local Rules: You can include your custom rule directly in your project. A common approach is to use the eslint-plugin-local-rules package. This allows you to keep your rules within your project's repository without having to publish them to npm.
2. ESLint Plugin: For rules that you want to share across multiple projects, you can create an ESLint plugin. An ESLint plugin is an npm package that exports a set of rules, configurations, and processors. The official ESLint documentation provides a comprehensive guide on creating plugins.

Conclusion

Creating custom ESLint rules is a powerful way to enforce your team's coding standards and improve the quality of your codebase. By understanding the fundamentals of ASTs and the ESLint rule structure, you can create rules that are tailored to your specific needs. The ability to write, test, and integrate your own linting logic will not only make your code more consistent but will also deepen your understanding of the JavaScript language itself.

Resources

• ESLint: Custom Rules
• AST Explorer
• ESTree Specification
• typescript-eslint: Custom Rules