{"id":10827,"library":"eslint-plugin-promise","title":"ESLint Plugin for Promises","description":"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.","status":"active","version":"7.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/eslint-community/eslint-plugin-promise","tags":["javascript","eslint","eslintplugin","eslint-plugin","promise","promises"],"install":[{"cmd":"npm install eslint-plugin-promise","lang":"bash","label":"npm"},{"cmd":"yarn add eslint-plugin-promise","lang":"bash","label":"yarn"},{"cmd":"pnpm add eslint-plugin-promise","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This is an ESLint plugin and requires ESLint to run. Peer dependency aligns with ESLint v7, v8, and v9.","package":"eslint","optional":false}],"imports":[{"note":"For use in `eslint.config.js` with ESLint's new flat configuration system (ESLint v9+).","symbol":"ESLint Flat Config","correct":"import pluginPromise from 'eslint-plugin-promise';"},{"note":"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.","wrong":"import { rules } from 'eslint-plugin-promise'","symbol":"Legacy .eslintrc Configuration","correct":"{ \"plugins\": [\"promise\"] }"},{"note":"Applies the plugin's recommended set of rules for common best practices in `.eslintrc.*`.","symbol":"Recommended Ruleset (Legacy)","correct":"{ \"extends\": [\"plugin:promise/recommended\"] }"},{"note":"Utilizes the plugin's recommended flat configuration object, typically spread into the `export default []` array in `eslint.config.js`.","symbol":"Recommended Ruleset (Flat Config)","correct":"pluginPromise.configs['flat/recommended']"}],"quickstart":{"code":"import pluginPromise from 'eslint-plugin-promise';\nimport globals from 'globals';\n\nexport default [\n  {\n    files: ['**/*.js'],\n    languageOptions: {\n      ecmaVersion: 'latest',\n      sourceType: 'module',\n      globals: {\n        ...globals.node,\n        ...globals.browser\n      }\n    },\n    plugins: {\n      promise: pluginPromise\n    },\n    rules: {\n      ...pluginPromise.configs['flat/recommended'].rules,\n      // Override or add specific rules\n      'promise/always-return': 'error',\n      'promise/no-nesting': 'warn',\n      'promise/prefer-await-to-then': 'error'\n    }\n  }\n];\n\n// Example file: src/async.js\n// async function fetchData() {\n//   return fetch('/api/data')\n//     .then(response => response.json())\n//     .catch(error => console.error('Fetch error:', error));\n// }\n//\n// const badPromise = new Promise(resolve => {\n//   resolve('first');\n//   resolve('second'); // Will be flagged by no-multiple-resolved\n// });\n//\n// function processData(data, cb) {\n//   Promise.resolve(data).then(() => {\n//     cb(null, data); // Will be flagged by no-callback-in-promise\n//   });\n// }\n//\n// fetchData();","lang":"javascript","description":"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."},"warnings":[{"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`).","message":"Version 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.","severity":"breaking","affected_versions":">=7.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=6.6.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=6.2.0"},{"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.","message":"With 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.","severity":"breaking","affected_versions":">=7.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install eslint-plugin-promise --save-dev` or `yarn add eslint-plugin-promise --dev`.","cause":"The eslint-plugin-promise package was not installed or not installed correctly in the project.","error":"Error: Failed to load plugin 'promise' declared in '.eslintrc.js': Cannot find module 'eslint-plugin-promise'"},{"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 }`.","cause":"In ESLint's flat configuration, plugins must be explicitly imported and then mapped in the `plugins` object within your configuration.","error":"ESLint couldn't find the plugin \"promise\". (While processing 'eslint.config.js')"},{"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/`).","cause":"The plugin is loaded, but ESLint cannot find the specified rule. This often happens if the plugin is not correctly associated with its rules.","error":"Definition for rule 'promise/always-return' was not found."}],"ecosystem":"npm"}