Custom Angular ESLint rules #1106

jerone · 2022-08-15T15:37:41Z

jerone
Aug 15, 2022

I'm starting this discussion to create an overview of custom Angular ESLint rules that are not part of this repository.

It is not only about shameless promotion 😁, but also to share examples and discuss implementation issues.
It might be interested to see what others have created.

@maintainers If not allowed, please let me know and I'll delete this discussion.

jerone · 2022-08-15T15:38:26Z

jerone
Aug 15, 2022
Author

Let me start by introducing my own Angular ESLint rule: ESLint Angular Template consistent this.

This rule validates the use of explicit/implicit prefix properties, variables and template references with this. in Angular HTML templates.

There is no functional reason to start properties with this. It is solely aesthetic. But by giving developers the choice to apply it or not, the code will look inconsistent.

Example of incorrect property code:

<test *ngIf="foo">{{bar}}</test>
             ~~~    ~~~

Example of correct property code:

<test *ngIf="this.foo">{{this.bar}}</test>

0 replies

fetis · 2025-03-14T18:45:48Z

fetis
Mar 14, 2025

@jerone I'm trying to do the same right now for our company code and feeling huge pain -- zero documentation or guidelines. Basically, the only thing I have is eslint-plugin-template code and some docs on ESLint and typescript-eslint (both are not applicable directly)

I managed to make a small test rule, but struggled to make it testable with RuleTester.
What would be your recommendations on this path?

5 replies

jerone Mar 14, 2025
Author

Hi @fetis. Sorry, I moved on from Angular a few years ago, so I can only forward you to the tests in my rule that I shared here.

fetis Mar 14, 2025

thanks for reply anyway

KrystianDerdzinski Mar 17, 2025

Hi @fetis - I share the same pain at the moment, I managed to write a custom rule for Angular HTML templates, it's auto fixable as well. That's true - there is no sufficient documentation, figuring out things from the source code & guessing was 90% of the job.

Here is a fantastic talk that made it much clearer to me:
https://www.youtube.com/watch?v=JwpGFlkmP74

This article comes in handy as well:
https://fintech.theodo.com/blog-posts/eslint-on-steroids-with-custom-rules

Also, if you use nx, it is much easier to start (you can generate a rule config template). This video is worth watching even if you don't use nx.
https://www.youtube.com/watch?v=tEVNYmJ05Ew

General tips:

Use https://astexplorer.net/ with the proper parser chosen (@typescript-eslint/parser for TS files or @angular-eslint/template-parser for HTML component template) to inspect your Abstract Syntax Tree. It will allow you to target specific nodes in the rule (more in the videos above)
It is way easier to create a custom rule for TypeScript files than HTML component templates. Start your adventures with coding custom TS rule
The best way to test it is to run the lint check command from the terminal. Obviously, any console.log() that you write in the custom ESLint rule code will be displayed in the terminal as well if you need to debug
IDE may be a little laggy with scanning the files. If you use VS Code press cmd/ctrl + shift + P and type in "Developer: reload window" to refresh the window and test if the code targeted by the rule is reported as an error in the editor.

It is quite simple and not a lot of code if you figure it out - please get in touch with me if you face any problems, it is quite an interesting subject and I would like to explore it more.

reduckted Mar 19, 2025

I've written a few custom ESLint rules that check Angular templates. Once you have an understanding of the AST, it's really no different to writing an ESLint rule that checks JavaScript or TypeScript.

As @KrystianDerdzinski said, if you're not familiar with writing custom ESLint rules at all, then it's probably best to start with a regular rule that checks JavaScript or TypeScript before taking the extra step to write a rule for Angular templates.

Just in case you haven't seen them, there's some guides for custom rules on the eslint and typescript-eslint websites:

It's also worth understanding ESQuery. It's very powerful and a good selector can reduce the amount of code in the rule.

https://github.com/estools/esquery

Once you have an understanding of ESLint rules, taking the next step to check Angular templates is quite simple. The way you write the rule is the same - you're just checking a different kind of AST.

Here's a repo that demonstrates a really simple ESLint rule that checks Angular templates for blink elements:

https://github.com/reduckted/eslint-angular-rule-demo

Here are the main differences from a rule that checks JavaScript or TypeScript.

Node names

The node names come from the Angular compiler. As @KrystianDerdzinski mentioned, using https://astexplorer.net/ is an excellent way to understand the AST that represents the HTML from the template. Just be aware that the template parser that it uses is quite old (it's from Angular 14). It still shows the correct AST for most things.

You can find the node names here:

angular-eslint/packages/template-parser/src/index.ts

Lines 38 to 74 in b55ccf1

    
           const KEYS: VisitorKeys = { 
        
             ASTWithSource: ['ast'], 
        
             Binary: ['left', 'right'], 
        
             BoundAttribute: ['value'], 
        
             BoundEvent: ['handler'], 
        
             BoundText: ['value'], 
        
             Call: ['receiver', 'args'], 
        
             SafeCall: ['receiver', 'args'], 
        
             Conditional: ['condition', 'trueExp', 'falseExp'], 
        
             Element$1: ['children', 'inputs', 'outputs', 'attributes'], 
        
             Interpolation$1: ['expressions'], 
        
             PrefixNot: ['expression'], 
        
             Program: ['templateNodes'], 
        
             PropertyRead: ['receiver'], 
        
             Template: ['templateAttrs', 'children', 'inputs'], 
        
             BindingPipe: ['exp'], 
        
             DeferredBlock: [ 
        
               'children', 
        
               'placeholder', 
        
               'loading', 
        
               'error', 
        
               'triggers', 
        
               'prefetchTriggers', 
        
             ], 
        
             DeferredBlockLoading: ['children'], 
        
             DeferredBlockError: ['children'], 
        
             DeferredBlockPlaceholder: ['children'], 
        
             Object: ['when'], 
        
             BoundDeferredTrigger: ['value'], 
        
             IfBlock: ['branches'], 
        
             IfBlockBranch: ['children', 'expression'], 
        
             SwitchBlock: ['cases', 'expression'], 
        
             SwitchBlockCase: ['children', 'expression'], 
        
             ForLoopBlock: ['children', 'empty', 'expression', 'trackBy'], 
        
             ForLoopBlockEmpty: ['children'], 
        
             Content: ['children'], 
        
           };

The only one I know of that is not listed there is Text$3. I have no idea where it comes from, nor do I know what the "$3" means (just like I have no idea what the "$1" means in Element$1 🤷‍♂️)

Reporting Problems

When reporting a problem in a normal rule, you would be able to specify the node to report the problem on. Because the rule is working with a different kind of AST, that's not possible. Instead, you can specify the location of the problem. You can convert a node from the AST into a location using the TemplateParserServices.

Testing

Testing is quite simple. Use the repo I linked to above to see how to set up the environment. That repo uses Jest, but you should be able to use any testing framework. I've used Mocha before. It's all just a matter of getting the test runner to work with TypeScript.

Use the RuleTester class from @angular-eslint/test-utils. When you create the RuleTester, you need to tell it to use the parser from @angular-eslint/template-parser so that it can parse the HTML. That's the only special thing you need to do for Angular template rules.

With the RuleTester, you provide it valid code (or HTML in our case) and invalid code. For each invalid test case, you need to provide the expected errors. You can use the convertAnnotatedSourceToFailureCase function from @angular-eslint/test-utils, which makes it easy to specify where the problems should be reported in the code. You don't have to use that though. In the repo I linked above, I've specified the location of the expected errors using line and column numbers.

For example, in the repo above, I specified the invalid test case like this:

{
    code: '<blink></blink>',
    errors: [
        {
            messageId: 'doNotBlink',
            line: 1,
            column: 1,
            endLine: 1,
            endColumn: 8,
        },
    ],
},

But I could also specify it like this:

convertAnnotatedSourceToFailureCase({
    description: 'test',
    annotatedSource: `
        <blink></blink>
        ~~~~~~~
    `,
    messageId: 'doNotBlink',
});

Debugging

This is just a general tip for debugging ESLint rules. If you use VS Code, use the JavaScript Debug Terminal for stepping through your rule. The easiest way to do this is:

Create a test with the template that you want to debug your rule with.
Set some breakpoints in your rule.
Open a JavaScript Debug Terminal.
Run the command to execute the tests (for example, npm run test).

VS Code will run the command and attach the debugger to the process. It will then hit your breakpoints in the rule and you can step through it line by line to see what it's doing.

Hope that helps!

reduckted Mar 22, 2025

The only one I know of that is not listed there is Text$3. I have no idea where it comes from, nor do I know what the "$3" means (just like I have no idea what the "$1" means in Element$1 🤷‍♂️)

Looks like the $number suffix means it was not yet a stable API. See #2320.

fetis · 2025-03-20T09:25:30Z

fetis
Mar 20, 2025

@KrystianDerdzinski @reduckted, thank you very much for the information. I have managed to make a package and test rule that works fine so far, but I stumbled upon applying proper testing via RulerTester. The IDE generates strange error for me

import("mypackagename/node_modules/@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"msgId1", [], unknown, import("mypackagename/node_modules/@typescript-eslint/
utils/dist/ts-eslint/Rule").RuleListener>
is not assignable to parameter of type
import("mypackage/node_modules/@typescript-eslint/rule-tester/node_modules/@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"msgId1", [], unknown, import("mypackage/node_modules/@typescript-eslint/rule-tester/node_modules/@typescript-eslint...

which goes down to

Type
import("mypackagename/node_modules/@typescript-eslint/scope-manager/dist/referencer/Reference").Reference
is not assignable to type
import("mypackagename/node_modules/@typescript-eslint/utils/node_modules/@typescript-eslint/scope-manager/dist/referencer/Reference").Reference

That's how I create the rule

import { ESLintUtils, TSESTree, ASTUtils } from '@typescript-eslint/utils';

const createRule = ESLintUtils.RuleCreator(
    () => `https://example.com/docs`,
);

 export const testRule = createRule({
 ...rule meta and context
 });

and that's how I create test suite

import { RuleTester, RuleTesterConfig } from '@typescript-eslint/rule-tester';
import { testRule } from '../rules/test-rule';

 const ruleTester = new RuleTester({});

At the same time, it works fine from the console, but when I add languageOptions for the Angular parser I get the error from the Jest but not from the IDE 🤯

    tests/test-rule.spec.ts:5:5 - error TS2353: Object literal may only specify known properties, and 'languageOptions' does not exist in type 'RuleTesterConfig'.

It looks for me now like a problem with tsconfig/jest config, but I cannot figure out the cause for it. If you faced anything similar that would be realy helpful to get a tip on how to fix it.

Does it make any difference what version of ESLint you specify in your peerDependencies? I've started with v8 (as what we use internally), but the plain config comes only with v9.

1 reply

reduckted Mar 20, 2025

"Type X is not assignable to type Y" is usually a sign that you have different versions of the same dependencies. For example, @typescript-eslint/scope-manager and @typescript-eslint/utils are different versions, which means you have two different versions of @typescript-eslint/scope-manager in the dependency tree.

JamesHenry · 2025-06-29T18:05:33Z

JamesHenry
Jun 29, 2025
Maintainer

I added a dedicated guide for this here: https://github.com/angular-eslint/angular-eslint/blob/5fecab92335b02be3d47b7156d851c5eddf1761f/docs/WRITING_CUSTOM_RULES.md

If things are unclear/missing please report them as an issue and we can enhance it

0 replies

Custom Angular ESLint rules #1106

Uh oh!

Uh oh!

Replies: 4 comments · 6 replies

Uh oh!

Uh oh!

jerone Aug 15, 2022 Author

Uh oh!

Uh oh!

jerone Mar 14, 2025 Author

Uh oh!

Uh oh!

Uh oh!

Node names

Reporting Problems

Testing

Debugging

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JamesHenry Jun 29, 2025 Maintainer

Replies: 4 comments 6 replies

jerone
Aug 15, 2022
Author

jerone Mar 14, 2025
Author

JamesHenry
Jun 29, 2025
Maintainer