superagent

Superagent is a long-running HTTP client for JavaScript that presents the same chainable, promise-friendly API whether the code runs in Node.js or in a browser bundle. Requests are built by chaining methods like .set(), .query(), .send(), and .attach() onto a verb call such as .get() or .post(), then resolved with a callback, .then()/await, or the .end() callback style — all three interoperate on the same request object.

Under the hood it separates a shared request-base mixin (serialization, parsing, retry logic, redirects, timeouts) from platform-specific transports: a Node implementation built on http/https/http2 with gzip/deflate/brotli decompression and multipart form support via formidable/form-data, and a browser implementation built on XMLHttpRequest. This lets the same fluent surface support very different underlying I/O.

It has shipped since 2011 (originally by TJ Holowaychuk) and is now maintained by the Forward Email/Lad/Breejs organizations, with a large ecosystem of third-party superagent-* plugins for caching, mocking, throttling, and request signing plugged in via .use().

What You Get

• A single chainable request API (.get()/.post()/.set()/.query()/.send()/.attach()/.end()) that behaves the same in Node and in a browserify/webpack bundle
• Built-in retry support via .retry(count, fn) with a fine-grained, overridable list of retryable status codes and error codes
• Automatic gzip/deflate/brotli response decompression and multipart form/file upload handling (formidable, form-data) on the Node side
• A .use(plugin) extension point that the community has built dozens of superagent-* packages around (caching, mocking, throttling, prefixing, AWS request signing)
• Callback, Promise/await, and .end()-callback styles all usable interchangeably on the same request object
• A dedicated superagent.agent() for persisting cookies/headers across a series of requests, similar to a session client

Common Use Cases

• Calling internal or third-party JSON/REST APIs from a Node.js backend with a chainable, readable request syntax
• Sharing one HTTP-calling code path between a Node service and its browser-bundled frontend via browserify/webpack
• Uploading multipart form data or files to an API endpoint using .attach() and .field()
• Adding transient-failure resilience to outbound API calls with .retry() instead of hand-rolled retry loops
• Writing integration tests against Express/Node servers, driving requests with superagent and asserting on .end()/.then() responses

Under The Hood

Architecture Execution starts from the top-level request(method, url) factory exported by src/node/index.js (or src/client.js in a browser bundle), which constructs a Request object. Request mixes in RequestBase (src/request-base.js, ~780 lines) — a platform-neutral layer owning .query(), .send(), .set(), retry state (_retry, _shouldRetry), timeout handling, and response-type negotiation — onto a platform-specific transport: src/node/index.js (~1435 lines) wraps Node’s http/https/http2 modules plus gzip/deflate/brotli decompression (src/node/decompress.js, src/node/unzip.js) and multipart parsing (formidable), while src/client.js (~1050 lines) wraps XMLHttpRequest for the browser build. A separate superagent.agent() (src/node/agent.js) wraps the same Request machinery to persist cookies/headers across calls. This split lets one fluent chain compile to two very different I/O backends without either half knowing about the other’s transport details.

Tech Stack Plain CommonJS JavaScript with no TypeScript; runtime dependencies are narrowly scoped utility packages — qs for query serialization, form-data/formidable for multipart bodies, cookiejar for cookie handling, component-emitter for the event-emitter mixin, debug for diagnostics, and fast-safe-stringify for safe JSON encoding. The browser bundle is produced via browserify + babelify + tinyify, targeted by a .browserslistrc and linted for browser-compat with eslint-plugin-compat. .babelrc variants (.lib.babelrc, .dist.babelrc, .test.babelrc) drive separate build passes for the Node lib, the minified dist bundle, and the transpiled test suite.