Registry / testing / eslint-plugin-promise

eslint-plugin-promise

library7.2.1jsnpmunverified

eslint-plugin-promise is an ESLint plugin designed to enforce best practices and prevent common pitfalls when working with JavaScript Promises. It ensures proper promise chain construction, error handling, and discourages anti-patterns like callbacks inside `then()` blocks. The current stable version is `7.2.1`, released in November 2024, indicating an active development and maintenance cadence with several releases throughout the year addressing bugs and adding features. Key differentiators include its comprehensive set of rules covering various promise use cases, from enforcing `catch()` or `return` to disallowing multiple resolutions and improper nesting, thereby enhancing code readability and reliability in asynchronous operations. It supports both legacy `.eslintrc.*` configurations and modern ESLint flat configurations.

testing

npm install eslint-plugin-promise

github ↗package ↗

INSTALL

IMPORT

SIG · ESLINT-PLUGIN-PROM

eslint-plugin-promise

testingjavascriptv7.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ESLint Flat Config

✓ import pluginPromise from 'eslint-plugin-promise';

For use in `eslint.config.js` with ESLint's new flat configuration system (ESLint v9+).

Legacy .eslintrc Configuration

✓ { "plugins": ["promise"] }

✗ import { rules } from 'eslint-plugin-promise'

In legacy `.eslintrc.*` files, plugins are referenced by their short name in the `plugins` array. The plugin is loaded by ESLint itself; direct JavaScript imports are not used for configuration.

Recommended Ruleset (Legacy)

✓ { "extends": ["plugin:promise/recommended"] }

Applies the plugin's recommended set of rules for common best practices in `.eslintrc.*`.

Recommended Ruleset (Flat Config)

✓ pluginPromise.configs['flat/recommended']

Utilizes the plugin's recommended flat configuration object, typically spread into the `export default []` array in `eslint.config.js`.

Demonstrates setting up `eslint-plugin-promise` in an `eslint.config.js` (flat config) file, including importing the plugin, applying its recommended rules, and illustrating some problematic promise patterns the plugin targets.

import pluginPromise from 'eslint-plugin-promise'; import globals from 'globals'; export default [ { files: ['**/*.js'], languageOptions: { ecmaVersion: 'latest', sourceType: 'module', globals: { ...globals.node, ...globals.browser } }, plugins: { promise: pluginPromise }, rules: { ...pluginPromise.configs['flat/recommended'].rules, // Override or add specific rules 'promise/always-return': 'error', 'promise/no-nesting': 'warn', 'promise/prefer-await-to-then': 'error' } } ]; // Example file: src/async.js // async function fetchData() { // return fetch('/api/data') // .then(response => response.json()) // .catch(error => console.error('Fetch error:', error)); // } // // const badPromise = new Promise(resolve => { // resolve('first'); // resolve('second'); // Will be flagged by no-multiple-resolved // }); // // function processData(data, cb) { // Promise.resolve(data).then(() => { // cb(null, data); // Will be flagged by no-callback-in-promise // }); // } // // fetchData();

Debug

Known issues

breakingVersion 7.0.0 updated Node.js and ESLint peer dependency versions to align with ESLint v9, which means Node.js versions prior to 18.18.0 and ESLint versions older than 7.0.0 are no longer officially supported.

fix

Upgrade Node.js to `^18.18.0 || ^20.9.0 || >=21.1.0` and ESLint to `^7.0.0 || ^8.0.0 || ^9.0.0`. For ESLint v9, use the flat configuration (`eslint.config.js`).

affects: >=7.0.0

gotchaThe `prefer-await-to-then` rule, when used with the `strict` option, will disallow `.then()` or `.catch()` following `await` expressions, which can be useful for enforcing full `async/await` syntax but might break existing codebases using mixed patterns.

fix

If enabling `strict` mode for `prefer-await-to-then`, refactor code to use `try/catch` blocks for error handling with `await` instead of `.catch()`. Otherwise, disable the `strict` option if mixed `async/await` and promise chaining is acceptable.

affects: >=6.6.0

gotchaThe `no-callback-in-promise` rule can sometimes trigger false positives, especially in complex scenarios or when using specific patterns that mimic callbacks but are not true anti-patterns for promises.

fix

Review affected code; if the rule is incorrectly flagging legitimate code, consider using the `timeoutsErr` option (`no-callback-in-promise": ["error", { "timeoutsErr": true }]`) or disable the rule for specific lines/files with ESLint comments if a false positive cannot be re-architected.

affects: >=6.2.0

breakingWith the introduction of ESLint's flat configuration system (ESLint v9+), the way plugins are configured has changed. The `extends` property with `plugin:promise/recommended` in `.eslintrc.*` is for legacy configurations.

fix

For ESLint v9 and `eslint.config.js`, explicitly import the plugin (`import pluginPromise from 'eslint-plugin-promise'`) and use `pluginPromise.configs['flat/recommended']` within your configuration array. Ensure you also map the plugin in the `plugins` object for rule definitions.

affects: >=7.0.0

Errors

Common errors & fixes

Error: Failed to load plugin 'promise' declared in '.eslintrc.js': Cannot find module 'eslint-plugin-promise'

The eslint-plugin-promise package was not installed or not installed correctly in the project.

fix

Run `npm install eslint-plugin-promise --save-dev` or `yarn add eslint-plugin-promise --dev`.

ESLint couldn't find the plugin "promise". (While processing 'eslint.config.js')

In ESLint's flat configuration, plugins must be explicitly imported and then mapped in the `plugins` object within your configuration.

fix

Ensure `import pluginPromise from 'eslint-plugin-promise';` is at the top of `eslint.config.js`, and the plugin is mapped in `plugins: { promise: pluginPromise }`.

Definition for rule 'promise/always-return' was not found.

The plugin is loaded, but ESLint cannot find the specified rule. This often happens if the plugin is not correctly associated with its rules.

fix

Verify that `plugins: { promise: pluginPromise }` is correctly defined in your flat config, or that `"plugins": ["promise"]` is in your `.eslintrc.*` and that the rule name is correctly prefixed (`promise/`).

Upgrade

Version history

7.2.1latest on npm

Audit

Dependencies

eslintrequiredThis is an ESLint plugin and requires ESLint to run. Peer dependency aligns with ESLint v7, v8, and v9.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/eslint-community/eslint-plugin-promise ↗

packagehttps://www.npmjs.com/package/eslint-plugin-promise ↗