ESLint Rule Extender Utility

0.0.1 · active · verified Sun Apr 19

eslint-rule-extender is a utility library designed to facilitate the extension and modification of existing ESLint rules without needing to rewrite them entirely. It provides a programmatic API to override aspects of an `ESLintRule` object, allowing developers to customize `meta` properties, add new AST visitors, or modify the reporting behavior of a rule. This can be particularly useful for creating highly specific linting rules based on established ones, or for adapting third-party rules to fit unique project requirements. As of version 0.0.1, it focuses on core functionality, offering a lean approach to rule customization. Its release cadence is not explicitly defined, but as a utility, updates would likely follow ESLint API changes or community-driven feature requests. A key differentiator is its focus on *extending* rather than *composing* rules, providing granular control over specific aspects.

Common errors

```
Error: Cannot find module 'eslint-plugin-example'
```
cause The quickstart example uses `eslint-plugin-example` as a placeholder for an original rule. This plugin does not actually exist on npm.

fix Replace `require('eslint-plugin-example')` with an actual ESLint rule import, for example, `require('eslint/lib/rules/no-debugger')` for a built-in rule, or the path to a rule from an installed plugin.
```
TypeError: Cannot read properties of undefined (reading 'meta')
```
cause The `originalRule` passed to `ruleExtender` is undefined or not a valid ESLint rule object, which typically has a `meta` property.

fix Ensure that `originalRule` is correctly imported and is a valid ESLint rule object with at least a `meta` property, or that the path to the rule is correct.

Warnings

gotcha The package is at version 0.0.1, indicating early development. API stability is not guaranteed, and future versions may introduce breaking changes without a major version bump.
Fix: Review the package's GitHub repository for the latest status and any new releases before integrating into production systems. Pin the exact version in `package.json`.
gotcha The README examples use `require()`, suggesting primary support for CommonJS. While bundlers might handle ESM `import` statements, direct Node.js ESM environments might require explicit configuration or may not be supported at this early version.
Fix: If using in an ESM-only Node.js project, test `import ruleExtender from 'eslint-rule-extender';` thoroughly. You might need to add `"type": "module"` to your `package.json` or consult the package's repository for ESM support plans.
gotcha When overriding `meta` properties, ensure that the original rule's messages are preserved or correctly merged if you intend to still use them. The `metaOverrides` will fully replace properties, so careful merging is necessary for objects like `messages`.
Fix: Use the spread operator (`...originalRule.meta.messages`) when defining `metaOverrides.messages` to ensure all original message IDs are available alongside new ones, or explicitly define all required messages.

Install

npm install eslint-rule-extender npm
yarn add eslint-rule-extender yarn
pnpm add eslint-rule-extender pnpm

Imports

ruleExtender
```
const ruleExtender = require('eslint-rule-extender');
```
Primary CommonJS import pattern. Given the 0.0.1 version, CommonJS is the expected module system.
ruleExtender
wrong:
```
import { ruleExtender } from 'eslint-rule-extender';
```
correct:
```
import ruleExtender from 'eslint-rule-extender';
```
ESM import for `ruleExtender`. The package at 0.0.1 likely doesn't have explicit ESM exports, so this might require bundler configuration or be unsupported. It's a default export.

Quickstart

This example demonstrates how to use `eslint-rule-extender` to customize an existing rule by overriding its `meta` properties, adding new visitor callbacks, and conditionally suppressing reports.

const ruleExtender = require('eslint-rule-extender');
const { originalRule } = require('eslint-plugin-example'); // Replace with a real ESLint rule import

// Example: Define a placeholder originalRule for demonstration
const mockOriginalRule = {
  meta: {
    type: 'problem',
    docs: {
      description: 'Disallow direct use of ThisExpression (mock)',
      category: 'Possible Problems',
      recommended: true
    },
    schema: [],
    messages: {
      defaultMessage: 'Avoid ThisExpression.'
    }
  },
  create(context) {
    return {
      ThisExpression(node) {
        context.report({
          node,
          messageId: 'defaultMessage'
        });
      }
    };
  }
};

// In a real scenario, you'd import an actual rule, e.g., from 'eslint/lib/rules/no-console'
// const originalRule = require('eslint/lib/rules/no-console');

const extendedRule = ruleExtender(mockOriginalRule, {
  metaOverrides: {
    type: 'suggestion',
    fixable: false,
    messages: {
        anAdditionalSuggestion: 'Arrow functions are fine here!',
        ...mockOriginalRule.meta.messages
    }
  },
  createAdditionalVisitors(context) {
    return {
      ArrowFunctionExpression(node) {
        context.report({ node, messageId: 'anAdditionalSuggestion' });
      }
    };
  },
  reportOverrides(meta) {
    // Only report if the node type is NOT 'ThisExpression'
    return meta.node.type !== 'ThisExpression';
  }
});

// To use this extended rule, you would typically export it from an ESLint plugin:
// module.exports = {
//   rules: {
//     'my-extended-rule': extendedRule
//   }
// };

console.log('Extended Rule Meta:', extendedRule.meta);
// Simulate a rule execution for demonstration (not how ESLint actually runs it)
// In a real ESLint setup, this rule would be applied to source code.
// For now, we just show it's configured.

view raw JSON →