Writing a Custom ESLint Rule (2023)

We use it extensively on Depop's internet teamESLintName, a tool that analyzes code and flags issues at compile time based on a selected set of rules. This helps maintain code consistency, maintainability, and avoids common mistakes. In most cases, the wide selection of built-in standards and community rules serve us well.

But what happens when you want to enforce a rule that doesn't currently exist in the ESLint community? That was the situation we found ourselves in and is the subject of this article.

Problem

We follow a "backend to frontend" (BFF) pattern and have multiple web APIs that sit in front of a large collection of BE services spanning different domains. These web APIs act as a website presentation layer to provide data in the most useful way for our user interfaces.

As part of our web APIs, we useexpress segmentationand assign atypewrittenclass for each route method. For example, we have aTO TAKEmethod in our web product API that uses a fileproduct controllerclassroom. It contains a public method that fetches a single BE product.

To monitor any logic issues in our class functions, we have aobservation servicewhich allows us to observe the resource, and if it throws an error, we log that error on our login platform. Observing our basic methods is essential for gaining insight into production issues, but it's all too easy for an engineer to forget to add an observation service.to attendconstructor command:

(Video) 7. Create first custom rule in the ESLint & add it in config file. Add the ---rulesdir option.

After discussing this issue in the group, we decided that the best solution would be to create a custom ESLint rule that would complain if some public class method is not followed byobservation service. It wasn't something we'd done before and that's how the journey began. The following sections outline the steps that were taken to achieve this…

Creating an ESLint plugin

To create an ESLint rule, we needed an ESLint plugin to house the rule. Oofficial documentswe suggest using the Yeoman generator to create the plugin, but the generator doesn't support TypeScript, which we like (and is useful for creating rules). Instead, we took the manual route.

Here are the main steps required to generate a TypeScript-based plugin:

1. Create a new package, for example withnpm init
   - The package name must be in the formateslint-plugin-or if you want to group with scope@/eslint-plugin-
   - To set upversionto a suitable starting value, for example1.0.0
   - To set upprincipalTo dodist/index.js
2. Create the following empty directoriesdocuments/rules,library/rulesEUtests/lib/rules. We'll add them later.
3. To addtsconfig.jsonto configure the repository as a TypeScript repository. For more information about the different optionsClick here. Some of the main compiler options we use are"of": "ES5","module": "CommonJS"EU"lib": ["ESNext"]. To addlibfolder to the include path i.e."include:": ["lib']because this will be the build source. Make sure the output directory is set to the same folder as defined inprincipalw package.json (tj."outDir": "distance"). You will also need a tool to compile the TS code to the JS we usetscwhich can be accessed by addingtypewrittenas a repo dependency.
4. You will probably want to add some tools likeESLintNameEUmore beautifulto ensure the source code is good and consistent. (Yes, even your custom ESLint rule needs to be destroyed!). Configuring these tools is beyond the scope of this article.

At this point, we had an empty ESLint plugin and could start writing our custom rule…

Skeletonize a custom ESLint rule

There is a very useful tool called@typescript-eslint/utilswhich acts as a replacement package forESLintName. It exports all the same objects and types, but withtyped eslintsupport (seeHerewhy do we need it). To add@typescript-eslint/utilsas a dependency to start using it.

Before creating a rule, it's important to think carefully about what name you want to give the rule. The name of the rule should make sense to both its maintainers and its consumers. In conclusion, we wanted to create a rule that warned if public class methods were not observed by the programobservation service. we went to snapsclass-methods-observation-service-observation.

The first file to be created is for the rule itself and it makes sense to give this file the same name as the rule, for examplewatch.ts-service-watch.ts-methods-class. This needs to be addedlibrary/rulesfile. To start, add the following template there:

importuj { ESLintUtils, TSESTree } z „@typescript-eslint/utils”;
const createRule = ESLintUtils.RuleCreator(
(name) =>
`https://github.com/myrepo/blob/master/docs/rules/${nazwa}.md`
);
export permanent rule = create rule({
create(context) {
turn back {};
},
name: '',
half: {
type: "issue", // "issue", "suggestion" ou "layout".
documents: {
description:
"",
recommended: "error",
},
The news: {},
schema: [], // Add schema if rule has options
},
default options: [],
});

The first thing to do is replace it.with the actual name of the rule, for exampleclass-methods-observation-service-observation.

cmetaobject change the following:

• Fortypechoose one ofproblem,suggestionlubricantsystem. Settings can be foundHere, but in our case we were creating one of the typesproblem.
• withindocumentsSection:
  - Add a short description of what the rule does, e.g.Ensures that public class methods are observed by the ObservationService's Watch method
  - Add a recommendation level for the rule. choose one oferror,strict,to warnlubricantFALSEHOOD. This is used by build tools to generate configurations from presets. we went toerror.
• OThe newsthe object is where you define the messages the rule consumer will see. The key is the identifier that will be referenced when writing the rule, and the value is the error message itself. In our case, we only had 1 type of problem that we were interested in, so our object looked like this:

rule logic

Writing custom ESLint rules requires heavy usageabstract syntax trees(AST). If you're not familiar with AST, you should definitely read this.articlefor a brief introduction before moving on, as it is beyond the scope of this article.

To help you write the rule, you'll need help finding the right nodes for the lines of code you're creating. Here tools likeEksplorator ASTyou are your friend. In the left pane of the explorer, you can paste sample code that would represent the problem your rule is trying to solve. Then clicking on different parts of the code will update the right side with the appropriate nodes.

The main logic of the rule must go into the return blockto createmethod insidecreate a rulehelper:

export permanent rule = create rule({
create(context) {
turn back {
// Rule logic
};
}
}

In the case of our rule, the first step was to determine whether the file under analysis contained a class. visitingEksplorator ASTwe could release sample code of what a typical class-based file would look like:

interfejs ProductControllerArgs {
watchService: IWatchService;
}
klasa eksportu ProductController {
konstruktor(argument: ProductControllerArgs) {
this.fetchSingleProduct = args.observationService.watch(
this.fetchSingleProduct,
{
classFunctionName: 'ProductController.fetchSingleProduct',
layer name: Layer.Controller,
}
);
}
public fetchSingleProduct = () => {
// implementation code
}
}

Then clicking onclassroomkeyword in the left pane of the explorer, the right pane showed something like this:

Oclass declarationhighlighted in blue is a node that represents a class, so our creation method looks like this:

export permanent rule = create rule({
create(context) {
turn back {
Class declaration: (node) => {
}
};
}
}

We are usingclass declarationas the key in the return block and the value is a function that takes a node as an argument. In theory, a function can be called multiple times (since there can be multiple classes in the same file), but in our world there should always be only one class per file. This node argument represents a class in our code.

Let's take a moment to think about what our rule is supposed to do. Basically, we want to show a warning if any public method of the class is not followed byobservation service. The approach we take is to first find all the public methods in the class and then check if any of them are followed byobservation service.

If we go back to AST Explorer and click onDownload a single product(which is an example of a public method we want to see), we can see that in the right panel it is highlighted:

With this information we can add the following code in the fileclass declarationmethod to find all public methods:

Class declaration: (node) => {
const publicMethods = node.body.body.filter(
(position): the position is TSESTree.PropertyDefinition =>
item.type === TSESTree.AST_NODE_TYPES.PropertyDefinition &&
item.accessibility === 'public' &&
item.value?.type === TSESTree.AST_NODE_TYPES.ArrowFunctionExpression
);
}

We check items inbody. bodyan array that has typeDefinition of property, availability valuepublicEUvalue typeis an arrow function. You will also notice that the callback function has been passed tonode.body.body.filter()is a guardian of sorts. This is to enjoy@typescript-eslinttypes. Sometimes we need to narrow our choices to get useful type suggestions and that's exactly what we're here to do.public methodsthe array has a typeTSESTree.PropertyDefinition[]not something bigger. With that, we now have an array of all public methods of the class.

Now we want to go through all these public methods and see if any of them are observed by the program.observation servicewatch method. we know thatobservewacjaService.watchThe method is initialized in the class constructor, so that's where we should start. Clicking on the builder in the AST Explorer shows this in the right pane:

(Video) Live with Kent: Writing an ESLint plugin

The first potential linting error is the lack of a constructor in the class. We can verify the constructor by adding the following code:

publicMethods.forEach((publicMethod) => {
if (publicMethod.key.type === TSESTree.AST_NODE_TYPES.Identifier) ​​{
let expected method name = publicMethod.key.name;
conststructorMatch = node.body.body.find(
(position): The position is TSESTree.MethodDefinition =>
item.type === TSESTree.AST_NODE_TYPES.MethodDefinition &&
item.kind === 'builder'
);
if (!constructorMatch) {
return context.report({
MessageId: 'publicClassMethodsMustBeWatched',
no: public method,
});
}
}
}

The constructor exists in the frameworkbody.knot.bodyat the. It shouldMethod definitiontype and set the value to "kind".constructor. If there is no match for the constructor, we can trigger our first linting error.

You will remember that wepreviously definedidentification messagepublicClassMethodsMustBeWatchedwithinmetapart of our rule. To trigger a linting error, we need to callcontext report, passing it the object zmessage idwe want to use and the node that started it. In that casemessage idANDpublicClassMethodsMustBeWatchedand node is the current node infor allloop that triggered the warning:

if (!constructorMatch) {
return context.report({
MessageId: 'publicClassMethodsMustBeWatched',
no: public method,
});
}

Alive! Our principle is to finally do something useful.

The last linting we need is for when there is a constructor but the public method is not observed by the program.observation service. We should already know how to identify the correct part of the code in a fileEksplorator AST. Remember it's importantobservewacjaService.watchcalling the class constructor would look something like this:

this.fetchSingleProduct = args.observationService.watch(
this.fetchSingleProduct,
{
classFunctionName: 'ProductController.fetchSingleProduct',
layer name: Layer.Controller,
}
);

The following code can be added below the previous onecontext reportcall for inspection:

const watchMatch = konstruktorMatch.value.body?.body.find(
(declaration) => {
With (
instruction.type ===
TSESTree.AST_NODE_TYPES.ExpressionStatement &&
declaration.expression.type ===
TSESTree.AST_NODE_TYPES.AssignmentExpression &&
declaration.expression.type.right ===
TSESTree.AST_NODE_TYPES.CallExpression &&
statement.expression.right.callee.type ===
TSESTree.AST_NODE_TYPES.MemberExpression &&
((statement.expression.right.callee.object.type ===
TSESTree.AST_NODE_TYPES.MemberExpression &&
statement.expression.right.callee.object.property.type ===
TSESTree.AST_NODE_TYPES.Identyfikator &&
statement.expression.right.call.object.property.name ===
"observation service") ||
(statement.expression.right.callee.object.type ===
TSESTree.AST_NODE_TYPES.Identyfikator &&
statement.expression.right.call.object.name ===
'observation service')) &&
statement.expression.right.callee.property.type ===
TSESTree.AST_NODE_TYPES.Identyfikator &&
statement.expression.right.callee.property.name === "follow" &&
declaration.expression.right.arguments[0].type ===
TSESTree.AST_NODE_TYPES.MemberExpression &&
statement.expression.right.arguments[0].object.type ===
TSESTree.AST_NODE_TYPES.ThisExpression &&
statement.expression.right.arguments[0].property.type ===
TSESTree.AST_NODE_TYPES.Identyfikator &&
statement.expression.right.arguments[0].property.name ===
expected method name
) {
return true;
}
returns false;
}
);

Now I admit that at first glance it is not very pretty. A big part of verbosity is making sure we reduce types properly. So let's try to find out...

Initially, we pass through the constructorvalue.body.bodyarray to find all the methods that are in the constructor.

so findobservewacjaService.watchgive us a call and we'll do some checksstatement.expression.right.callee.object.property.name === 'observationService'together withstatement.expression.right.callee.property.name === 'watch'.

So we have a check forstatement.expression.right.arguments[0].object.type === TSESTree.AST_NODE_TYPES.ThisExpressiontogether withstatement.expression.right.arguments[0].property.name === nome_método esperadoto check if the first argument was passed toobservewacjaService.watchis the name of the expected method, for examplethis.fetchSingleProduct

If all of these conditions match in the find method, we returnTRUEotherwise we come backFALSEHOOD.The result is attributed towatch matchconstant. If there is no match, we run the same linting error as before:

if (!watchMatch) {
return context.report({
MessageId: 'publicClassMethodsMustBeWatched',
no: public method,
});
}

The logic is now complete and our lint rule can detect that no public methods are being watched. The final version of our rule is as follows:

export permanent rule = create rule({
create(context) {
turn back {
Class declaration: (node) => {
const publicMethods = node.body.body.filter(
(position): the position is TSESTree.PropertyDefinition =>
item.type === TSESTree.AST_NODE_TYPES.PropertyDefinition &&
item.accessibility === 'public' &&
item.value?.type === TSESTree.AST_NODE_TYPES.ArrowFunctionExpression
);
publicMethods.forEach((publicMethod) => {
if (publicMethod.key.type === TSESTree.AST_NODE_TYPES.Identifier) ​​{
let expected method name = publicMethod.key.name;
conststructorMatch = node.body.body.find(
(position): The position is TSESTree.MethodDefinition =>
item.type === TSESTree.AST_NODE_TYPES.MethodDefinition &&
item.kind === 'builder'
);
if (!constructorMatch) {
return context.report({
MessageId: 'publicClassMethodsMustBeWatched',
no: public method,
});
}
const watchMatch = konstruktorMatch.value.body?.body.find(
(declaration) => {
With (
instruction.type ===
TSESTree.AST_NODE_TYPES.ExpressionStatement &&
declaration.expression.type ===
TSESTree.AST_NODE_TYPES.AssignmentExpression &&
declaration.expression.type.right ===
TSESTree.AST_NODE_TYPES.CallExpression &&
statement.expression.right.callee.type ===
TSESTree.AST_NODE_TYPES.MemberExpression &&
((statement.expression.right.callee.object.type ===
TSESTree.AST_NODE_TYPES.MemberExpression &&
statement.expression.right.callee.object.property.type ===
TSESTree.AST_NODE_TYPES.Identyfikator &&
statement.expression.right.call.object.property.name ===
"observation service") ||
(statement.expression.right.callee.object.type ===
TSESTree.AST_NODE_TYPES.Identyfikator &&
statement.expression.right.call.object.name ===
'observation service')) &&
statement.expression.right.callee.property.type ===
TSESTree.AST_NODE_TYPES.Identyfikator &&
statement.expression.right.callee.property.name === "follow" &&
declaration.expression.right.arguments[0].type ===
TSESTree.AST_NODE_TYPES.MemberExpression &&
statement.expression.right.arguments[0].object.type ===
TSESTree.AST_NODE_TYPES.ThisExpression &&
statement.expression.right.arguments[0].property.type ===
TSESTree.AST_NODE_TYPES.Identyfikator &&
statement.expression.right.arguments[0].property.name ===
expected method name
) {
return true;
}
returns false;
}
);
if (!watchMatch) {
return context.report({
MessageId: 'publicClassMethodsMustBeWatched',
no: public method,
});
}
}
});
},
};
},
nome: 'observation-service-observation-class-methods',
half: {
type: "issue", // "issue", "suggestion" ou "layout".
documents: {
description:
"Ensures that public class methods are observed by the observation method ObservationService",
recommended: "error",
},
The news: {
publicClassMethodsMustBeWatched:
'Each method of a public class must be observed by an observer',
},
schema: [], // Add schema if rule has options
},
default options: [],
});

It's worth mentioning that this rule is not bulletproof, there may be code variations that cause false positives when using it, but it served us well as a good v1!

exporting a rule

After creating a rule, you need to export it. at the rootlibthe folder we createdindex. tsfile with the following content:

importe a regra como classMethodsObservationServiceWatch } de "./rules/class-methods-observation-service-watch";
fixed configuration = {
rules: {
'observation-observation-class-methods':
classMethodsObservationServiceWatch,
},
};
export = configuration;

key inrulesthe object must match the name of the rule defined in the filecreate a rulehelper, which in our case isclass-methods-observation-service-observation. The value is defined for the imported rule.

Weirdexport = configurationSyntax is how the CommonJS module system is handled in a compiled rule. More informationHere.

writing tests

ESLint rules should always have tests written for them. In addition to protecting against future regressions, the somewhat isolated nature of writing ESLint rules adds extra value to writing tests as it provides immediate feedback on whether your rule is working as expected.

To start, add a file in the formattests/lib/rulesfolder with the filename named according to the new rule (you can name it whatever you like, but that would be a logical naming convention). In our case, we callclass-methods-observation-service-watch.test.ts.

In the new test file, add the following template:

import {ESLintUtils} from "@typescript-eslint/utils";
import {rule} from "../../../lib/rules/";
const ruleTester = new ESLintUtils.RuleTester({
analisador: '@typescript-eslint/parser',
});
ruleTester.run('', rule, {
important: [
{
code: ``,
}
],
invalid: [
{
code: ``,
errors: [{message id: '' }],
},
],
});

To updatein the import statement to indicate the new rule and also to updateto match the name of the new rule. For our rule, the valueclass-methods-observation-service-observationwas used for both.

Core test logic is handled internallyruleTester.run()helper. You need to provide him with correct code examples that won't cause linting errors, as well as incorrect code examples that do. For each example of invalid code provided, you must also specifymessage idthe linting error you expect, for examplepublicClassMethodsMustBeWatched. This is the message ID that was setpreviously.

The code examples you provide to the helper can be large blocks of code (for example, try to reduce the code examples to the minimum amount of code that proves the linting rule is correct. Also try to think of all the different ways to write the code (for example, the rule may require work on both arrow functions AND function declarations) and give examples of all of them.

An example test file for our rule looks like this:

import {ESLintUtils} from "@typescript-eslint/utils";
import {reguła} z „../../../lib/rules/class-methods-observation-service-watch”;
const ruleTester = new ESLintUtils.RuleTester({
analisador: '@typescript-eslint/parser',
});
ruleTester.run('observation-service-observation-class-methods', rule, {
important: [
{
code: `
interface IMyControllerArgs {
watchService: IWatchService;
}
export class MyController {
constructor(arguments: IMyControllerArgs) {
this.doCoś = args.observationService.watch(this.doCoś, {
classFunctionName: 'MeuController.doCoś',
layer name: Layer.Controller
});
}
public do something = async() => {
// realization
};
}
`,
}
],
invalid: [
{
code: `
interface IMyControllerArgs {
watchService: IWatchService;
}
export class MyController {
constructor(arguments: IMyControllerArgs) {}
public do something = async() => {
// realization
};
}
`,
errors: [{Message ID: 'publicClassMethodsMustBeWatched' }],
}
],
});

Once the tests are done, you just need to run them with a suitable test environment likeAND.

Documentation

Each shredding rule should have a document describing how that rule should be applied. An example of where this document is linked is in the code editor when a linting error is triggered, for example when hovering over a linting error a tooltip appears and the hyperlink launches the rule document for the rule triggered in the user's browser:

To start, add a file in the formatdocuments/rulesa folder whose file name is derived from the name of the new rule, but with the extension a.mdenlargement. In our case, we callclass-methods-watch-service-watch.md. The most important thing to note is that the location of the document must match the path defined when creating our rule:

const createRule = ESLintUtils.RuleCreator(
(name) =>
`https://github.com/myrepo/blob/master/docs/rules/${nazwa}.md`
);

In the new markdown file, add the following template:

# Guarantee that...
## Rule details
This regra visa...
Examples of **invalid** code for this rule:
Examples of **correct** code for this rule:
## When not to use

Now just fill in the blanks! Provide a general description of the rule at the top, then go into more detail with examples of valid and invalid code. Finally, you can add details about when not to use the rule.

You can, of course, organize the content of the rules document however you like, but it's a good baseline for what you want to include. The main thing you need to keep in mind is to think about what someone completely new to your rule would want to know when they use it.

local development

You've just completed the main steps required to create a custom ESLint rule! Add a build step to compile the plug-in source files into the final version ina witnessfile.

You'll want to fully test the new rule before publishing it, so you'll need a separate repository where you can add this new plugin as a dependency. Many tools are available to symbolically link your consumer repository to your plugin repository, for example,link npmEUyalc(we use yalc) so choose what works best for you.

The name of the package to be addedpackage.jsonyour consumer repository is in the formateslint-plugin-(Lub@/eslint-plugin-for scoped packages).

Once connected, add the plugin name to the fileplugsboard ineslintrcyour consumer repository file:

{
"plug-ins": [
""
]
}

Observation: If you created a scoped package for your plugin, add the scope as a prefix to the plugin name, for example@/

Then add the rules you want to enable in the filerulesepisode of the sameeslintrcfile:

{
"rules": {
"/": "error"
}
}

Observation: If you created a scoped package for your plugin, add the scope as a prefix to the plugin name, for example@//: "error"

For the rule we created in this article,it would be the sameclass-methods-observation-service-observation.

Publishing to NPM

After installing the new plugin, it remains only to publish it in the registry, which will most likely benp. We use a really cool tool calledsemantic editingwho takes care of the entire release process for you. Once published, it will be available worldwide! (Or just for your organization when using private scoped packages).

final thoughts

While not the easiest thing you can do, creating a custom ESLint rule provides a lot of value in catching build-stage issues for any custom patterns you might want to enforce in your code. Getting familiar with abstract parse trees is the key to progress, but once you get used to them, it becomes quite straightforward.

The rule described in this article can be improved in several ways. For example, handling more extreme cases of input code style, adding more test cases, and also deploying a fileauto repair functionfor users to callobservewacjaService.watchcode to automatically generate when they runeslintz- To repairflag. These are all improvements we want to add to our rule to make sure we get the most out of it and learn new things too!

We hope this guide has helped you understand the steps involved in taking off!

(Video) Custom ESLint Rules with Nick Taylor!

You can see the complete rule code created in this article here:https://github.com/depolabs/eslint-plugin-depop-demo