superagent

Small progressive client-side HTTP request library, and Node.js module with the same API, sporting many high-level HTTP client features

Table of Contents

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

Install

npm:

npm install superagent

yarn:

yarn add superagent

Usage

Node

const superagent = require('superagent');

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

Browser

The browser-ready, minified version of superagent is only 19 KB!

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

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

VanillaJS

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

<script src="https://cdn.jsdelivr.net/npm/superagent"></script>
<!-- if you wish to use unpkg.com instead: -->
<!-- <script src="https://unpkg.com/superagent"></script> -->
<script type="text/javascript">
  (function() {
    // superagent is exposed as `window.superagent`
    // if you wish to use "request" instead please
    // uncomment the following line of code:
    // `window.request = superagent;`
    superagent
      .post('/api/pet')
      .send({ name: 'Manny', species: 'cat' }) // sends a JSON post body
      .set('X-API-Key', 'foobar')
      .set('accept', 'json')
      .end((err, res) => {
        // Calling the end function will send the request
      });
  })();
</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: v8.8.1+ (we use the core http2 package)

• Browsers (see .browserslistrc):

  cd superagent
  npx browserslist

  and_chr 69
  and_ff 62
  and_qq 1.2
  and_uc 11.8
  android 67
  android 4.4.3-4.4.4
  baidu 7.12
  bb 10
  bb 7
  chrome 69
  chrome 68
  chrome 67
  edge 17
  edge 16
  firefox 62
  firefox 61
  ie 11
  ie 10
  ie 9
  ie_mob 11
  ie_mob 10
  ios_saf 11.3-11.4
  ios_saf 11.0-11.2
  op_mini all
  op_mob 46
  op_mob 12.1
  opera 55
  opera 54
  safari 12
  safari 11.1
  samsung 7.2
  samsung 6.2

IE9 requires a polyfill for window.FormData (we recommend formdata-polyfill)

Plugins

SuperAgent is easily extended via plugins.

const nocache = require('superagent-no-cache');
const superagent = require('superagent');
const prefix = require('superagent-prefix')('/static');

superagent
  .get('/some-url')
  .query({ action: 'edit', city: 'London' }) // query string
  .use(prefix) // Prefixes *only* this request
  .use(nocache) // Prevents caching of *only* this request
  .end((err, res) => {
    // Do something
  });

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

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

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

• 4.x to 5.x:
  • Ensure you're running Node 8.8.1 or later. We've dropped support for Node 6 and use the core http2 module now
  • We've implemented the build setup of Lass to simplify our stack and linting
  • Browserified build size has been reduced from 48KB to 19KB (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 | Website | | ------------------- | -------------------------- | | TJ Holowaychuk | http://tjholowaychuk.com | | Kornel Lesiński | | | Peter Lyons | | | Hunter Loftis | | | Nick Baugh | |

License

MIT © TJ Holowaychuk