{"id":12103,"library":"superagent","title":"Superagent HTTP Client","description":"Superagent is a lightweight, progressive HTTP request client library designed for both Node.js and browser environments, offering a consistent and fluent API. It is currently at stable version 10.3.0 and exhibits an active development cadence, with frequent patch and minor releases addressing bugs, dependency updates, and minor enhancements. Its key differentiators include a minimal footprint for browser use (approx. 50KB minified and gzipped), a highly chainable request builder API, and robust support for various HTTP features like redirects, retries, and multipart requests. Superagent supports traditional callback-based APIs, Promises for `.then().catch()` patterns, and `async/await` for modern JavaScript concurrency. It serves as a popular alternative to `axios`, `fetch` API (especially in environments requiring broad browser compatibility), or `node-fetch`, providing a unified interface across different JavaScript runtimes.","status":"active","version":"10.3.0","language":"javascript","source_language":"en","source_url":"git://github.com/ladjs/superagent","tags":["javascript","agent","ajax","api","async","await","axios","cancel"],"install":[{"cmd":"npm install superagent","lang":"bash","label":"npm"},{"cmd":"yarn add superagent","lang":"bash","label":"yarn"},{"cmd":"pnpm add superagent","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Superagent exports as a default module for ESM usage. Named imports like `{ superagent }` will not work.","wrong":"import { superagent } from 'superagent';","symbol":"superagent","correct":"import superagent from 'superagent';"},{"note":"This is the standard CommonJS import pattern for Node.js environments.","symbol":"superagent","correct":"const superagent = require('superagent');"},{"note":"In browser environments using a `<script>` tag, `superagent` is exposed globally on the `window` object.","symbol":"superagent","correct":"window.superagent.get('/api/data').end(...);"}],"quickstart":{"code":"import superagent from 'superagent';\n\nconst API_BASE = 'https://jsonplaceholder.typicode.com'; // Example API\n\nasync function fetchUserData(userId) {\n  try {\n    // Make a GET request to an example API\n    const userResponse = await superagent\n      .get(`${API_BASE}/users/${userId}`)\n      .set('Accept', 'application/json');\n\n    console.log(`Fetched user ${userId}:`, userResponse.body);\n\n    // Make a POST request with JSON payload\n    const postResponse = await superagent\n      .post(`${API_BASE}/posts`)\n      .send({ title: 'foo', body: 'bar', userId: userId })\n      .set('Content-Type', 'application/json')\n      .set('Accept', 'application/json');\n\n    console.log('Created post:', postResponse.body);\n\n  } catch (err) {\n    if (err.response) {\n      // The request was made and the server responded with a status code\n      // that falls out of the range of 2xx\n      console.error('API Error:', err.response.status, err.response.body);\n    } else if (err.request) {\n      // The request was made but no response was received\n      console.error('Network Error:', err.request);\n    } else {\n      // Something happened in setting up the request that triggered an Error\n      console.error('Request Setup Error:', err.message);\n    }\n  }\n}\n\nfetchUserData(1);","lang":"typescript","description":"This quickstart demonstrates how to use `superagent` with `async/await` for both GET and POST requests, including proper error handling for network and API responses."},"warnings":[{"fix":"Upgrade your Node.js environment to version 14.18.0 or newer. Consider using an LTS version for stability.","message":"Superagent v10.x requires Node.js version 14.18.0 or higher. Running on older Node.js versions will result in compatibility issues or failures.","severity":"breaking","affected_versions":">=10.0.0"},{"fix":"Include polyfills such as `https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=WeakRef,BigInt` before loading the `superagent` script in your HTML.","message":"When using `superagent` in a browser environment, especially targeting older browsers, you may need to include polyfills for modern JavaScript features like `WeakRef` and `BigInt`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"In ESM modules, use `import superagent from 'superagent';`. In CommonJS modules, use `const superagent = require('superagent');`. Ensure your project's module configuration (e.g., `package.json` `type: 'module'`) aligns with your chosen import style.","message":"Mixing CommonJS `require()` with ES Module `import` syntax can lead to 'require is not defined' errors in modern Node.js environments configured for ESM or in bundlers. Superagent is primarily consumed as a default export.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always include error handling. For promises, use `.catch(errorCallback)` or wrap `await` calls in `try...catch`. For callback-based requests, ensure your `end()` function handles the `err` argument.","message":"Forgetting to add a `.catch()` block or `.end((err, res) => ...)` callback to a `superagent` promise chain can lead to unhandled promise rejections, which crash Node.js processes or result in silent failures in browsers.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade `superagent` to version 10.1.1 or higher. This issue was resolved by a dependency fix in that release.","message":"Versions of `superagent` prior to v10.1.1 might encounter a 'hexoid is not a function' error when bundled with Webpack, due to a dependency issue.","severity":"gotcha","affected_versions":"<10.1.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const superagent = require('superagent');` to `import superagent from 'superagent';`.","cause":"Attempting to use CommonJS `require()` syntax in an ES Module context (e.g., a `.mjs` file or a project with `\"type\": \"module\"` in `package.json`).","error":"ReferenceError: require is not defined"},{"fix":"Update `superagent` to version 10.1.1 or newer to resolve this internal dependency conflict.","cause":"A dependency issue with `hexoid` when bundled with Webpack, affecting older versions of Superagent.","error":"TypeError: (0 , hexoid_1.hexoid) is not a function"},{"fix":"Ensure all `superagent` promise chains include a `.catch(errorCallback)` and all `async/await` calls are wrapped in `try...catch` blocks.","cause":"A `superagent` request using promises (`.then()`) or `async/await` failed, and no `.catch()` handler or `try...catch` block was provided to handle the error.","error":"UnhandledPromiseRejectionWarning: Unhandled promise rejection."}],"ecosystem":"npm"}