Repository files navigation

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

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

npm:

npm install superagent

yarn:

yarn add superagent

constsuperagent=require('superagent');// callbacksuperagent.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/catchsuperagent.post('/api/pet').then(console.log).catch(console.error);// promise with async/await(async()=>{try{constres=awaitsuperagent.post('/api/pet');console.log(res);}catch(err){console.error(err);}})();

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

Browser-ready versions of this module are available viajsdelivr,unpkg, and also in thenode_modules/superagent/dist folder in downloads of thesuperagent package.

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

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

<scriptsrc="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=WeakRef,BigInt"></script><scriptsrc="https://cdn.jsdelivr.net/npm/superagent"></script><!-- if you wish to use unpkg.com instead: --><!-- <script src="https://unpkg.com/superagent"></script> --><scripttype="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>

If you are usingbrowserify,webpack,rollup, or another bundler, then you can follow the same usage asNode above.

• Node: v14.18.0+

• Browsers (see.browserslistrc):

  npx browserslist

  and_chr 102and_ff 101and_qq 10.4and_uc 12.12android 101chrome 103chrome 102chrome 101chrome 100edge 103edge 102edge 101firefox 101firefox 100firefox 91ios_saf 15.5ios_saf 15.4ios_saf 15.2-15.3ios_saf 15.0-15.1ios_saf 14.5-14.8ios_saf 14.0-14.4ios_saf 12.2-12.5kaios 2.5op_mini allop_mob 64opera 86opera 85safari 15.5safari 15.4samsung 17.0samsung 16.0

We recommend usinghttps://cdnjs.cloudflare.com/polyfill/ (specifically with the bundle mentioned inVanillaJS above):

<scriptsrc="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

SuperAgent is easily extended via plugins.

constnocache=require('superagent-no-cache');constsuperagent=require('superagent');constprefix=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 lightweightjson-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 simpledeclarative API for SuperAgent
• superagent-node-http-timings - measure http timings in node.js
• superagent-cheerio - addcheerio to your response content automatically. Addsres.$ 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 withsuperagent-* so that it can easily be found by others.

For SuperAgent extensions such as couchdb and oauth visit thewiki.

Please seeGitHub 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 serializingapplication/x-www-form-urlencoded, usingarrayFormat: 'indices' semantics ofqs 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, seeRequired Browser Features for more insight
• 4.x to 5.x:
  • We've implemented the build setup ofLass to simplify our stack and linting
  • Unminified browserified build size has been reduced from 48KB to 20KB (viatinyify and the latest version of Babel using@babel/preset-env and.browserslistrc)
  • Linting support has been added usingcaniuse-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 thebrowser version, rename it to.serialize().
  • If you rely onundefined 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.
• 0.x to 1.x:
  • Instead of 1-argument callback.end(function(res){}) use.then(res => {}).

MIT © TJ Holowaychuk