{"id":14734,"library":"node-fetch-retry","title":"node-fetch-retry","description":"node-fetch-retry is a lightweight wrapper library designed to enhance `node-fetch` with automatic retry capabilities. It enables developers to specify a fixed number of retry attempts for network requests, introduce a pause duration between retries, and execute a custom callback function before each attempt. The current stable version is 2.0.1. Its release cadence appears to be infrequent, with the last notable activity several years ago, suggesting it is in maintenance mode or effectively abandoned. This library differentiates itself by offering a straightforward, integrated retry mechanism directly within the `fetch` options, making it a simple choice for adding basic request resilience without complex configurations often found in more feature-rich alternatives. It's best suited for Node.js environments requiring basic retry logic for transient network failures.","status":"maintenance","version":"2.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/greatjapa/node-fetch-retry","tags":["javascript","node","fetch","retry","request","microservice"],"install":[{"cmd":"npm install node-fetch-retry","lang":"bash","label":"npm"},{"cmd":"yarn add node-fetch-retry","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-fetch-retry","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package wraps `node-fetch` to provide retry functionality. It implicitly depends on `node-fetch` for its core HTTP request capabilities.","package":"node-fetch","optional":false}],"imports":[{"note":"This library is primarily designed for CommonJS (`require`) environments. While Node.js supports ESM, the examples and common usage for this specific package are with `require`. Direct `import` might not work without specific ESM configuration or if the package itself does not provide an `exports` field for ESM.","wrong":"import fetch from 'node-fetch-retry';","symbol":"fetch","correct":"const fetch = require('node-fetch-retry');"},{"note":"For using `node-fetch-retry` in an ESM module or to dynamically load it in a CommonJS module that might interact with ESM-only dependencies, an async `import()` call is generally required. However, this pattern is typically used when the underlying `node-fetch` dependency is ESM-only (v3+), which may conflict with this wrapper's CJS nature.","wrong":"import { fetch } from 'node-fetch-retry';","symbol":"fetch (async import)","correct":"const fetch = (...args) => import('node-fetch-retry').then(({ default: fetch }) => fetch(...args));"}],"quickstart":{"code":"import * as process from 'process';\n\nconst fetch = require('node-fetch-retry');\n\nasync function fetchDataWithRetry() {\n  const targetUrl = 'https://httpstat.us/503?sleep=1000'; // Example URL that returns 503 after a delay\n  const retries = 3;\n  const pauseMs = 1000; // 1 second pause\n\n  console.log(`Attempting to fetch from ${targetUrl} with ${retries} retries...`);\n\n  try {\n    let opts = {\n      method: 'GET',\n      retry: retries,\n      pause: pauseMs,\n      callback: (retryAttempt) => {\n        console.log(`Retry attempt: ${retryAttempt}. Waiting ${pauseMs}ms before next attempt.`);\n      },\n      silent: false // Set to true to suppress pause messages\n    };\n\n    // Make the fetch request with retry options\n    const res = await fetch(targetUrl, opts);\n\n    if (res.ok) {\n      const text = await res.text();\n      console.log('Fetch successful after retries!');\n      console.log('Response:', text.substring(0, 100) + '...');\n    } else {\n      console.error(`Fetch failed after all retries with status: ${res.status}`);\n    }\n  } catch (error) {\n    console.error('An unhandled error occurred during fetch operation:', error.message);\n  }\n}\n\nfetchDataWithRetry();\n","lang":"javascript","description":"Demonstrates fetching a URL with a specified number of retries and a pause between attempts, including a callback to log each retry attempt."},"warnings":[{"fix":"If encountering `ERR_REQUIRE_ESM`, ensure your project and `node-fetch-retry` are compatible with `node-fetch@2`. Alternatively, rewrite your application to use ESM and consider `node-fetch` directly with custom retry logic or an ESM-compatible retry wrapper.","message":"This library explicitly uses `require` in its examples and is likely a CommonJS module. If `node-fetch-retry` internally depends on `node-fetch` version 3 or higher, it might lead to `ERR_REQUIRE_ESM` errors when imported via `require` in a CommonJS context, as `node-fetch` v3+ is ESM-only. Users should ensure compatibility with `node-fetch` v2 if sticking to CommonJS.","severity":"gotcha","affected_versions":">=2.0.1"},{"fix":"Assess the library's stability and feature set against your needs. For actively maintained alternatives with more advanced retry features (e.g., exponential backoff, retry on specific status codes), consider libraries like `fetch-retry` or `@adobe/node-fetch-retry`.","message":"The library's GitHub repository shows the last commit was several years ago. This indicates that the project is not actively maintained, which could mean no new features, bug fixes, or security patches. Users should consider this for long-term project stability and security.","severity":"gotcha","affected_versions":">=2.0.1"},{"fix":"Only use retry logic for idempotent methods like GET, PUT, and DELETE where repeating a request has no additional side effects. For non-idempotent requests, implement transactional logic or unique request IDs to ensure operations are only performed once.","message":"Retrying non-idempotent HTTP methods (e.g., POST, PATCH) can lead to unintended side effects, such as duplicate resource creation or multiple charges, if the original request succeeded but the response was not received.","severity":"gotcha","affected_versions":">=2.0.1"},{"fix":"For complex retry scenarios, consider libraries like `fetch-retry` which offer configurable `retryDelay` functions (for exponential backoff) and `retryOn` options for specific status codes.","message":"This library provides basic retry capabilities (fixed retries, fixed pause). It lacks more advanced features like exponential backoff, configurable retry conditions based on HTTP status codes, or custom error handling for different failure types, which are common in more robust retry solutions.","severity":"gotcha","affected_versions":">=2.0.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Either convert your project or the specific file to CommonJS (`.js` extension without `\"type\": \"module\"`) or use dynamic `import()` if `node-fetch-retry` supports it, or use an alternative library designed for ESM.","cause":"Attempting to use `require('node-fetch-retry')` in an ECMAScript Module (ESM) file (e.g., a file with `\"type\": \"module\"` in `package.json` or a `.mjs` extension).","error":"ReferenceError: require is not defined"},{"fix":"Ensure `node-fetch-retry` is correctly installed (`npm install node-fetch-retry`) and that the `require` statement is at the top level of your CommonJS module. Verify `node-fetch` is a compatible version with `node-fetch-retry` (likely `node-fetch@2`).","cause":"The `node-fetch-retry` package or its underlying `node-fetch` dependency was not correctly installed, resolved, or imported, leading to the `fetch` symbol being undefined.","error":"TypeError: fetch is not a function"},{"fix":"Downgrade your direct or indirect `node-fetch` dependency to version 2 (e.g., `npm install node-fetch@2`) if `node-fetch-retry` doesn't explicitly state ESM compatibility. Alternatively, migrate your project to ESM if feasible, or use `import('node-fetch').then(...)` for dynamic loading if supported.","cause":"This error occurs when a CommonJS `require()` call attempts to load an ESM-only module. If `node-fetch-retry` has an internal dependency on `node-fetch` v3+, and your project uses `require`, this conflict can arise.","error":"ERR_REQUIRE_ESM"}],"ecosystem":"npm"}