JavaScripting

The definitive source of the best
JavaScript libraries, frameworks, and plugins.


  • ×

    Superagent

    Ajax with less suck - (and node.js HTTP client to match)
    Filed under  › 

    • 🔾87%Overall
    • 14,573
    • 5 days
    • 🕩1215
    • 👥16

    superagent

    build status code coverage code style styled with prettier made with lass license

    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"></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"></script>
    
    • IE 9-10 requires a polyfill for Promise, Array.from, Symbol, Object.getOwnPropertySymbols, and Object.setPrototypeOf
    • IE 9 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:

    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:
      • 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

    ##

    Show All