superagent

Small progressive client-side HTTP request library, and Node.js module with the same API, supporting many high-level HTTP client features. Maintained for Forward Email and Lad.

Table of Contents

• Install
• Usage
  • Node
  • Browser
• Supported Platforms
  • Required Browser Features
• Plugins
• Upgrading from previous versions
• Contributors
• License

Install

npm:

1npm install superagent

yarn:

1yarn add superagent

Usage

Node

1const superagent = require('superagent');
2
3// callback
4superagent
5  .post('/api/pet')
6  .send({ name: 'Manny', species: 'cat' }) // sends a JSON post body
7  .set('X-API-Key', 'foobar')
8  .set('accept', 'json')
9  .end((err, res) => {
10    // Calling the end function will send the request
11  });
12
13// promise with then/catch
14superagent.post('/api/pet').then(console.log).catch(console.error);
15
16// promise with async/await
17(async () => {
18  try {
19    const res = await superagent.post('/api/pet');
20    console.log(res);
21  } catch (err) {
22    console.error(err);
23  }
24})();

Browser

The browser-ready, minified version of superagent is only 50 KB (minified and gzipped).

Browser-ready versions of this module are available via jsdelivr, unpkg, and also in the node_modules/superagent/dist folder in downloads of the superagent package.

Note that we also provide unminified versions with .js instead of .min.js file extensions.

VanillaJS

This is the solution for you if you're just using <script> tags everywhere!

1<script src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=WeakRef,BigInt"></script>
2<script src="https://cdn.jsdelivr.net/npm/superagent"></script>
3<!-- if you wish to use unpkg.com instead: -->
4<!-- <script src="https://unpkg.com/superagent"></script> -->
5<script type="text/javascript">
6  (function() {
7    // superagent is exposed as `window.superagent`
8    // if you wish to use "request" instead please
9    // uncomment the following line of code:
10    // `window.request = superagent;`
11    superagent
12      .post('/api/pet')
13      .send({ name: 'Manny', species: 'cat' }) // sends a JSON post body
14      .set('X-API-Key', 'foobar')
15      .set('accept', 'json')
16      .end(function (err, res) {
17        // Calling the end function will send the request
18      });
19  })();
20</script>

Bundler

If you are using browserify, webpack, rollup, or another bundler, then you can follow the same usage as Node above.

Supported Platforms

• Node: v14.18.0+

• Browsers (see .browserslistrc):

  1npx browserslist

  1and_chr 102
  2and_ff 101
  3and_qq 10.4
  4and_uc 12.12
  5android 101
  6chrome 103
  7chrome 102
  8chrome 101
  9chrome 100
  10edge 103
  11edge 102
  12edge 101
  13firefox 101
  14firefox 100
  15firefox 91
  16ios_saf 15.5
  17ios_saf 15.4
  18ios_saf 15.2-15.3
  19ios_saf 15.0-15.1
  20ios_saf 14.5-14.8
  21ios_saf 14.0-14.4
  22ios_saf 12.2-12.5
  23kaios 2.5
  24op_mini all
  25op_mob 64
  26opera 86
  27opera 85
  28safari 15.5
  29safari 15.4
  30samsung 17.0
  31samsung 16.0

Required Browser Features

We recommend using https://cdnjs.cloudflare.com/polyfill/ (specifically with the bundle mentioned in VanillaJS above):

1<script src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=WeakRef,BigInt"></script>

• WeakRef is not supported in Opera 85, iOS Safari 12.2-12.5
• BigInt is not supported in iOS Safari 12.2-12.5

Plugins

SuperAgent is easily extended via plugins.

1const nocache = require('superagent-no-cache');
2const superagent = require('superagent');
3const prefix = require('superagent-prefix')('/static');
4
5superagent
6  .get('/some-url')
7  .query({ action: 'edit', city: 'London' }) // query string
8  .use(prefix) // Prefixes *only* this request
9  .use(nocache) // Prevents caching of *only* this request
10  .end((err, res) => {
11    // Do something
12  });

Existing plugins:

• superagent-no-cache - prevents caching by including Cache-Control header
• superagent-prefix - prefixes absolute URLs (useful in test environment)
• superagent-suffix - suffix URLs with a given path
• superagent-mock - simulate HTTP calls by returning data fixtures based on the requested URL
• superagent-mocker — simulate REST API
• superagent-cache - A global SuperAgent patch with built-in, flexible caching
• superagent-cache-plugin - A SuperAgent plugin with built-in, flexible caching
• superagent-jsonapify - A lightweight json-api client addon for superagent
• superagent-serializer - Converts server payload into different cases
• superagent-httpbackend - stub out requests using AngularJS' $httpBackend syntax
• superagent-throttle - queues and intelligently throttles requests
• superagent-charset - add charset support for node's SuperAgent
• superagent-verbose-errors - include response body in error messages for failed requests
• superagent-declare - A simple declarative API for SuperAgent
• superagent-node-http-timings - measure http timings in node.js
• superagent-cheerio - add cheerio to your response content automatically. Adds res.$ for HTML and XML response bodies.
• @certible/superagent-aws-sign - Sign AWS endpoint requests, it uses the aws4 to authenticate the SuperAgent requests

Please prefix your plugin with superagent-* so that it can easily be found by others.

For SuperAgent extensions such as couchdb and oauth visit the wiki.

Upgrading from previous versions

Please see GitHub releases page for the current changelog.

Our breaking changes are mostly in rarely used functionality and from stricter error handling.

• 6.0 to 6.1
  • Browser behaviour changed to match Node when serializing application/x-www-form-urlencoded, using arrayFormat: 'indices' semantics of qs library. (See: https://www.npmjs.com/package/qs#stringifying)
• 5.x to 6.x:
  • Retry behavior is still opt-in, however we now have a more fine-grained list of status codes and error codes that we retry against (see updated docs)
  • A specific issue with Content-Type matching not being case-insensitive is fixed
  • Set is now required for IE 9, see Required Browser Features for more insight
• 4.x to 5.x:
  • We've implemented the build setup of Lass to simplify our stack and linting
  • Unminified browserified build size has been reduced from 48KB to 20KB (via tinyify and the latest version of Babel using @babel/preset-env and .browserslistrc)
  • Linting support has been added using caniuse-lite and eslint-plugin-compat
  • We can now target what versions of Node we wish to support more easily using .babelrc
• 3.x to 4.x:
  • Ensure you're running Node 6 or later. We've dropped support for Node 4.
  • We've started using ES6 and for compatibility with Internet Explorer you may need to use Babel.
  • We suggest migrating from .end() callbacks to .then() or await.
• 2.x to 3.x:
  • Ensure you're running Node 4 or later. We've dropped support for Node 0.x.
  • Test code that calls .send() multiple times. Invalid calls to .send() will now throw instead of sending garbage.
• 1.x to 2.x:
  • If you use .parse() in the browser version, rename it to .serialize().
  • If you rely on undefined in query-string values being sent literally as the text "undefined", switch to checking for missing value instead. ?key=undefined is now ?key (without a value).
  • If you use .then() in Internet Explorer, ensure that you have a polyfill that adds a global Promise object.
• 0.x to 1.x:
  • Instead of 1-argument callback .end(function(res){}) use .then(res => {}).

Contributors

Name
Kornel Lesiński
Peter Lyons
Hunter Loftis
Nick Baugh

License

MIT © TJ Holowaychuk