superagent
Small progressive client-side HTTP request library, and Node.js module with the same API, supporting many high-level HTTP client features
Table of Contents
Install
npm:
npm install superagent
yarn:
yarn add superagent
Usage
Node
const superagent = require('superagent');
// callback
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
});
// promise with then/catch
superagent.post('/api/pet').then(console.log).catch(console.error);
// promise with async/await
(async () => {
try {
const res = await superagent.post('/api/pet');
console.log(res);
} catch (err) {
console.error(err);
}
})();
Browser
The browser-ready, minified version of superagent
is only 6 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!
<script src="https://polyfill.io/v3/polyfill.min.js?features=Array.from,Promise,Symbol,Object.setPrototypeOf,Object.getOwnPropertySymbols,Set"></script>
<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(function (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: v6.x+
-
Browsers (see .browserslistrc):
npx browserslist
and_chr 71 and_ff 64 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 73 chrome 72 chrome 71 edge 18 edge 17 firefox 66 firefox 65 ie 11 ie 10 ie 9 ie_mob 11 ie_mob 10 ios_saf 12.0-12.1 ios_saf 11.3-11.4 op_mini all op_mob 46 op_mob 12.1 opera 58 opera 57 safari 12 safari 11.1 samsung 8.2 samsung 7.2-7.4
Required Browser Features
We recommend using https://polyfill.io (specifically with the bundle mentioned in VanillaJS above):
<script src="https://polyfill.io/v3/polyfill.min.js?features=Array.from,Promise,Symbol,Object.setPrototypeOf,Object.getOwnPropertySymbols,Set"></script>
- IE 9-10 requires a polyfill for
Promise
,Array.from
,Symbol
,Object.getOwnPropertySymbols
, andObject.setPrototypeOf
- IE 9 requires a polyfill for
window.FormData
(we recommend formdata-polyfill) andSet
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
- superagent-declare - A simple declarative API for SuperAgent
- superagent-node-http-timings - measure http timings in node.js
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.
-
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
andeslint-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()
orawait
.
-
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 globalPromise
object.
- If you use
- 0.x to 1.x:
- Instead of 1-argument callback
.end(function(res){})
use.then(res => {})
.
- Instead of 1-argument callback
Contributors
Name |
---|
Kornel Lesiński |
Peter Lyons |
Hunter Loftis |
Nick Baugh |
License
MIT © TJ Holowaychuk