Registry / http-networking / superagent

superagent

JSON →
library0.0.0jsnpmunverified

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.

npm install superagent
INSTALL
IMPORT
SIG · SUPERAGENT
S
superagent
http-networkingjavascriptv0.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

superagent
import superagent from 'superagent';
import { superagent } from 'superagent';
Superagent exports as a default module for ESM usage. Named imports like `{ superagent }` will not work.
superagent
const superagent = require('superagent');
This is the standard CommonJS import pattern for Node.js environments.
superagent
window.superagent.get('/api/data').end(...);
In browser environments using a `<script>` tag, `superagent` is exposed globally on the `window` object.

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.

import superagent from 'superagent'; const API_BASE = 'https://jsonplaceholder.typicode.com'; // Example API async function fetchUserData(userId) { try { // Make a GET request to an example API const userResponse = await superagent .get(`${API_BASE}/users/${userId}`) .set('Accept', 'application/json'); console.log(`Fetched user ${userId}:`, userResponse.body); // Make a POST request with JSON payload const postResponse = await superagent .post(`${API_BASE}/posts`) .send({ title: 'foo', body: 'bar', userId: userId }) .set('Content-Type', 'application/json') .set('Accept', 'application/json'); console.log('Created post:', postResponse.body); } catch (err) { if (err.response) { // The request was made and the server responded with a status code // that falls out of the range of 2xx console.error('API Error:', err.response.status, err.response.body); } else if (err.request) { // The request was made but no response was received console.error('Network Error:', err.request); } else { // Something happened in setting up the request that triggered an Error console.error('Request Setup Error:', err.message); } } } fetchUserData(1);
Debug
Known issues
breakingSuperagent v10.x requires Node.js version 14.18.0 or higher. Running on older Node.js versions will result in compatibility issues or failures.
fix
Upgrade your Node.js environment to version 14.18.0 or newer. Consider using an LTS version for stability.
affects: >=10.0.0
gotchaWhen using `superagent` in a browser environment, especially targeting older browsers, you may need to include polyfills for modern JavaScript features like `WeakRef` and `BigInt`.
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.
affects: >=1.0.0
gotchaMixing 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.
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.
affects: >=1.0.0
gotchaForgetting 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.
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.
affects: >=1.0.0
gotchaVersions 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.
fix
Upgrade `superagent` to version 10.1.1 or higher. This issue was resolved by a dependency fix in that release.
affects: <10.1.1
Errors
Common errors & fixes
ReferenceError: require is not defined
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`).
fix
Change `const superagent = require('superagent');` to `import superagent from 'superagent';`.
TypeError: (0 , hexoid_1.hexoid) is not a function
A dependency issue with `hexoid` when bundled with Webpack, affecting older versions of Superagent.
fix
Update `superagent` to version 10.1.1 or newer to resolve this internal dependency conflict.
UnhandledPromiseRejectionWarning: Unhandled promise rejection.
A `superagent` request using promises (`.then()`) or `async/await` failed, and no `.catch()` handler or `try...catch` block was provided to handle the error.
fix
Ensure all `superagent` promise chains include a `.catch(errorCallback)` and all `async/await` calls are wrapped in `try...catch` blocks.
Upgrade
Version history
0.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
12 hits · last 30 days
node
10
OpenAI (training)
1
Resources