Superagent HTTP Client

Common errors

• ReferenceError: require is not defined

  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`).
  fix Change `const superagent = require('superagent');` to `import superagent from 'superagent';`.

• TypeError: (0 , hexoid_1.hexoid) is not a function

  cause 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.

  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.
  fix Ensure all `superagent` promise chains include a `.catch(errorCallback)` and all `async/await` calls are wrapped in `try...catch` blocks.

Warnings

• breaking 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.
  Fix: Upgrade your Node.js environment to version 14.18.0 or newer. Consider using an LTS version for stability.
• gotcha 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`.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Upgrade `superagent` to version 10.1.1 or higher. This issue was resolved by a dependency fix in that release.

Install

• npm install superagent npm
• yarn add superagent yarn
• pnpm add superagent pnpm

Imports

• superagent
  wrong:

  import { superagent } from 'superagent';

  correct:

  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.

Quickstart

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);