# superagent: a fluent HTTP client for Node.js and the browser

> superagent is an MIT-licensed JavaScript HTTP client with the same fluent API on the server and in the browser. It suits teams that want one request idiom across both, and it is the wrong tool if you want an interceptor pipeline or automatic retries.

**forwardemail/superagent** — Ajax for Node.js and browsers (JS HTTP client). Maintained for @forwardemail, @ladjs, @spamscanner, @breejs, @cabinjs, and @lassjs.

- Repository: https://github.com/forwardemail/superagent
- Website: https://forwardemail.github.io/superagent/
- Stars: 16,635 · Forks: 1,322
- Language: JavaScript
- License: MIT
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/forwardemail-superagent

## The problem superagent solves: one request API for Node and the browser

Most JavaScript codebases end up with two HTTP idioms. Server code uses a Node client, browser code uses fetch or XMLHttpRequest, and the two diverge in how they set headers, serialize bodies, and surface errors. superagent is built around a single fluent chain that works in both places. The same call to superagent.post('/api/pet').send({...}).set('X-API-Key', 'foobar').end(callback) runs in Node and, through the browser build, in a script tag or a bundler. The package.json browser field maps ./src/node/index.js to ./src/client.js, so a bundler resolves the client implementation automatically instead of you maintaining two call sites.

The intended audience is narrow and identifiable. The README states the project is maintained for Forward Email and Lad, and the repository description lists @forwardemail, @ladjs, @spamscanner, @breejs, @cabinjs and @lassjs. That is a maintainer's own stack, not a general-purpose product roadmap. If your application sends JSON to an API, wants promise and callback styles in one library, and prefers chaining over configuration objects, superagent fits. If you need a full HTTP stack with interceptors, retry policies and a documented migration path, keep reading the limitations below before you commit.

## How the fluent chain, plugins and browser build fit together

The mechanism is a request builder. You call an HTTP verb method, attach body and header state with .send() and .set(), and the request is only dispatched when .end() is called. That is stated explicitly in the README comment: calling the end function will send the request. The same builder is then consumed three ways: a Node-style callback, a promise with then/catch, or await inside an async function. This is the part that makes the library easy to adopt incrementally, because you can convert one call site at a time.

Plugins are the extension mechanism, and they are applied per request with .use(), not globally. The README example attaches a URL prefix and a no-cache plugin to a single request, and the comment notes that the prefix applies only to that request. That per-request scope is a deliberate trade-off: it keeps behavior explicit at the call site, but it also means you repeat .use() on every request unless you build your own wrapper. The README lists plugins for caching, mocking, throttling, charset handling and HTTP timings, all maintained outside this repository.

On the browser side, the README says the minified build is 50 KB minified and gzipped, available through jsdelivr, unpkg, and the dist folder inside the installed package. The supported browser list comes from .browserslistrc and is printed with npx browserslist. Two features are called out as required: WeakRef and BigInt, with a polyfill bundle suggested for Opera 85 and iOS Safari 12.2 through 12.5. Node support starts at v14.18.0.

## Installing superagent and sending your first request

Installation is a single package from npm. The README gives both package managers, and there are no peer dependencies to resolve.

```bash
npm install superagent
```

or, with yarn:

```bash
yarn add superagent
```

The first real use is a POST with a JSON body, an API key header, and a callback. The README uses this exact example, and the comment about .end() is the part people miss: nothing is sent until you call it.

```js
const superagent = require('superagent');

superagent
  .post('/api/pet')
  .send({ name: 'Manny', species: 'cat' })
  .set('X-API-Key', 'foobar')
  .set('accept', 'json')
  .end((err, res) => {
    // Calling the end function will send the request
  });
```

If you prefer promises, the README shows the same call without .end(), using then/catch or await. In the browser without a bundler, load the polyfill bundle first, then the library from a CDN, and use window.superagent. The README notes you can assign window.request = superagent if you want the shorter name.

## What the README does not tell you about upgrades and rollback

The README has a section in its table of contents called Upgrading from previous versions, and that is the only upgrade guidance the README shows. There is no documented rollback procedure, no compatibility matrix between major versions, and no statement about how long older majors receive fixes. For a library at version 10.4.1, that is a real gap. The release history jumps from v10.3.0 on 2026-01-06 to v10.4.0 on 2026-09-22 and v10.4.1 the next day, so a reader cannot infer a predictable release cadence from the version numbers alone.

There is a second limitation worth stating plainly. superagent does not ship retries, circuit breaking, or request cancellation as described features in the README. The plugin list includes superagent-throttle for queueing and throttling, and superagent-cache for caching, but both live in other repositories with their own maintenance status. If your service needs exponential backoff on 5xx responses or a deadline on every call, you are writing that yourself on top of the chain. The same applies to mocking: superagent-mock and superagent-mocker exist, but the README does not describe a built-in test transport.

Browser support is also bounded by the .browserslistrc output rather than by a promise of broad compatibility. The list shown in the README includes Chrome 100 through 103, Firefox 100 and 101, Safari 15.4 and 15.5, and iOS Safari down to 12.2-12.5 with a polyfill. Older targets are not covered.

## superagent versus axios: chaining and plugins against interceptors

The closest comparison for most teams is axios, and the difference is architectural rather than cosmetic. axios centers on a configuration object and an interceptor pipeline: you register request and response interceptors once, and every call passes through them. That makes cross-cutting concerns such as auth headers, logging and error normalization a single registration. superagent centers on a mutable chain that you build per call, with .use() applying a plugin to that request only. Cross-cutting behavior is therefore either repeated at each call site or wrapped in your own helper.

That trade-off cuts both ways. Interceptors hide behavior, which is convenient until you need to know why a header appeared on one request and not another. superagent's per-request .use() keeps that visible at the call site, and the README's own comment that the prefix applies to only that request is the design stated out loud. If your team values explicit call sites and wants the same code to run in Node and the browser without a build-time shim, superagent's shape is the reason to pick it. If your team wants one place to register retry, auth and logging policy, axios's interceptor model matches that intent more directly.

## Licence, maintenance and the cost of keeping up

superagent is MIT licensed, and the repository carries a LICENSE file at the top level. MIT is permissive: you can use it in closed-source products, and the main obligation is preserving the copyright notice and licence text. That is the general shape of the licence, not legal advice for your situation.

The repository is not archived, and the last push was on 2026-09-23, which is five days before this writing. Releases v10.4.0 and v10.4.1 both landed on 2026-09-22 and 2026-09-23, so the project is being touched. The maintenance signal to weigh is not activity but ownership: the README states the library is maintained for Forward Email and Lad, and the package metadata points bugs at the ladjs/superagent issue tracker rather than at the forwardemail organisation. That means the roadmap follows the maintainers' own products. A feature you want that does not serve those products is more likely to arrive as a plugin in someone else's repository than as a change here.

Upgrade cost is mostly the dist and build surface. The package ships both src and lib trees, with separate .lib.babelrc and .dist.babelrc files and a browser field redirecting node entry points to client files. If you consume the published package and a bundler, upgrades are a version bump. If you vendor or patch the source, you inherit the Babel and browserify configuration in the Makefile, which is a heavier thing to carry.

## Conclusion

Adopt superagent when one fluent request API has to work in Node and in the browser, and when the plugin list covers what you need. Do not adopt it if you expect an interceptor pipeline, automatic retries, or a documented rollback path between major versions, because the README does not describe any of those. Before upgrading, run npm install superagent and check the dist folder and the .browserslistrc output against your own targets.

## FAQ

### What is superagent in Node.js?

It is an HTTP client module for Node.js with a fluent API, where you build a request with methods such as .post(), .send() and .set(), and dispatch it by calling .end(). The README notes that the same API is available in the browser, and that Node support starts at v14.18.0.

### How do you use superagent?

Install it with npm install superagent, require it, then chain the verb, body and headers before calling .end() with a callback. The README also shows promise usage with then/catch and with async/await, where no .end() call is needed.

### What is superagent?

superagent is a small client-side HTTP request library and a Node.js module with the same API, supporting high-level HTTP client features. It is MIT licensed and maintained for Forward Email and Lad.

## Sources

- [forwardemail/superagent on GitHub](https://github.com/forwardemail/superagent)
- [License: MIT](https://github.com/forwardemail/superagent/blob/master/LICENSE)
- [Project website](https://forwardemail.github.io/superagent/)
- [README](https://github.com/forwardemail/superagent/blob/master/README.md)
- [Releases](https://github.com/forwardemail/superagent/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/forwardemail-superagent