eslint-plugin-listeners

1.5.1 verified Sat Apr 25 auth: no javascript

ESLint plugin that provides rules to prevent memory leaks caused by event listeners that are not removed. Current stable version is 1.5.1, with infrequent releases. It checks for missing removeEventListener calls, mismatched add/remove listener functions, and inline function listeners. Unlike generic linting approaches, this plugin is purpose-built for event listener hygiene in JavaScript/TypeScript projects.

Common errors

error Error: Failed to load plugin 'listeners' declared in '.eslintrc.json': Cannot find module 'eslint-plugin-listeners' ↓

cause The plugin is not installed or is installed globally while ESLint is local (or vice versa).

fix

Run npm install --save-dev eslint-plugin-listeners in the project directory.

error TypeError: Cannot read property 'map' of undefined (eslint-plugin-listeners) ↓

cause Rule configuration missing required options or using an unsupported format.

fix

Check rule configuration in .eslintrc; ensure it's an object with severity string (e.g., 'error') or array with options.

Warnings

gotcha Rule 'no-missing-remove-event-listener' requires add and remove functions to be called within the same scope. Cross-scope patterns (e.g., storing listener reference) may be missed. ↓

fix Ensure addEventListener and removeEventListener calls are in the same function scope or use proper references.

gotcha The plugin does not detect removals via removeAllListeners by default. Ensure to configure custom remove functions if using removeAllListeners. ↓

fix Use the 'removeAllListeners' option in rule configuration to include removeAllListeners calls.

gotcha Version 1.4.0 introduced TypeScript support via TSESLint. If using an older version, TypeScript AST may not be fully supported. ↓

fix Upgrade to >=1.4.0 for proper TypeScript support.

gotcha The plugin relies on ESLint's AST analysis and may not catch all dynamic listener additions/removals (e.g., using variables for function references). ↓

fix Use static function references whenever possible; manually review dynamic cases.

Install

npm install eslint-plugin-listeners

yarn add eslint-plugin-listeners

pnpm add eslint-plugin-listeners

Imports

no-missing-remove-event-listener

wrong

{
  "rules": {
    "eslint-plugin-listeners/no-missing-remove-event-listener": "error"
  }
}

correct

{
  "rules": {
    "listeners/no-missing-remove-event-listener": "error"
  }
}

In ESLint config, prefix the rule name with 'listeners/' not 'eslint-plugin-listeners/'.

matching-remove-event-listener

wrong

{
  "rules": {
    "matching-remove-event-listener": "error"
  }
}

correct

{
  "rules": {
    "listeners/matching-remove-event-listener": "error"
  }
}

When using the plugin, rules must be prefixed with 'listeners/'.

plugin:listeners/recommended
wrong
```
{
  "extends": ["listeners/recommended"]
}
```
correct
```
{
  "extends": ["plugin:listeners/recommended"]
}
```
Must include the 'plugin:' prefix when extending a config from an ESLint plugin.

Quickstart

Quickstart showing installation, configuration, and a rule violation detection using the plugin.

// Install:
// npm install --save-dev eslint eslint-plugin-listeners

// .eslintrc.json:
{
  "plugins": ["listeners"],
  "extends": ["plugin:listeners/recommended"],
  "rules": {
    "listeners/no-inline-function-event-listener": "error"
  }
}

// Example code that flags:
document.addEventListener('click', function() { // inline function
  console.log('clicked');
});