new-rule.md

Creating a new rule

Prerequisite

• Ensure ESLint doesn't already have the rule built-in.
• Read the ESLint docs on creating a new rule.
• Look at the commit for how previous rules were added as inspiration. For example, the no-unused-properties rule.

Tip

Use the astexplorer site with the espree parser and ESLint v4 transform to interactively create the initial rule implementation. It lets you inspect the full AST as you would get from ESLint and you can even see the result of your auto-fixer implementation.

Steps

• Run npm run create-rule to create files for the new rule.
• Open “test/{RULE_ID}.mjs” and write some tests before implementing the rule.
• Open “rules/{RULE_ID}.js” and implement the rule logic.
• Add the correct meta.type to the rule.
• Open “docs/rules/{RULE_ID}.js” and write some documentation.
• Double check configs/recommended.js and readme.md, make sure the new rule is correctly added.
• Run npm test to ensure the tests pass.
• Run npm run integration to run the rules against real projects to ensure your rule does not fail on real-world code.
• Open a pull request with a title in exactly the format Add `rule-name` rule, for example, Add `no-unused-properties` rule.
• The pull request description should include the issue it fixes, for example, Fixes #123.
• Run npm run run-rules-on-codebase to run the rules against codebase to ensure code in the repository are following your rule, you can ignore this step until your PR is reviewed.

Implementation note

1. Try your best to provide an autofix if possible.

2. Try to provide a suggestion if an autofix is not possible.

3. Make sure the autofix doesn't change the runtime result.

4. Make sure the suggestion doesn't cause a syntax error.

5. Make sure that edge cases needing parentheses are considered in the fix function.

   const foo = 1;
   foo.toString()

   When changing foo to something else, make sure it works without ().

   // Good
   (1).toString()
   
   // Bad, will cause syntax error
   1.toString()

6. Make sure that edge cases needing leading semicolons are considered in the fix function.

   foo
   const bar = [1]
   bar.forEach(number => {
   	console.log(number)
   })

   When changing bar to something that starts with [ or (.

   // Good
   foo
   ;[1].forEach(number => {
   	console.log(number)
   })
   
   // Bad
   foo
   [1].forEach(number => {
   	console.log(number)
   })

7. If replacing a node that starts or ends with a symbol like {, make sure to add space before if the replacement starts with a letter.

   The following is valid JavaScript code:

   for(const{foo}of[]);

   When replacing {foo} with something that starts with a letter, space around is needed.

   // Good
   for(const foo of[]);
   
   // Bad
   for(constfooof[]);

8. Try not to remove comments in the fix function.