superagent README

The project's README from github.com/forwardemail/superagent. As one markdown file: README.md.

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. Maintained for Forward Email and Lad.

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 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!

<script src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=WeakRef,BigInt"></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

Required Browser Features

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

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

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

Please see GitHub releases page for the current changelog.

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

Contributors

Name
Kornel Lesiński
Peter Lyons
Hunter Loftis
Nick Baugh

License

MIT © TJ Holowaychuk

superagent (forwardemail/superagent)

http-client
Searching Database…

16.6K ·GitHub
Superagent
What is this?Superagent is a small, progressive HTTP request library with the same API in the browser and in Node.js, supporting many high-level HTTP client features.
Is this a browser thing or a Node.js thing?Both — it is isomorphic. One API covers Node and the browser, where a ready-made build weighs just 50 KB minified and gzipped, served via jsdelivr, unpkg or the package's dist folder.
How do I add it to my project?Install it from npm or yarn (npm install superagent). In the browser you can skip bundling: load the prebuilt minified file from a CDN or from the package's dist folder.
Do I need a specific Node version?Node.js 14.18.0 or newer, per the declared engines field. On the browser side nothing beyond a script tag or a bundler import is required.
Anything to watch out for when upgrading from an older version?Upgrade friction is the main one: breaking changes concentrate in rarely used functionality and in stricter error handling, so check the GitHub releases changelog between versions.
Will it work in mobile browsers, or is it desktop-only?It works in both. The supported browser range includes recent Chrome, Firefox, Edge, Opera and Safari, plus iOS Safari, Android Chrome, Samsung Internet, QQ and UC mobile, and KaiOS 2.5.
How do I make a request with query parameters?Chain it: superagent.get('/some-url').query({ action: 'edit', city: 'London' }).end((err, res) => { ... }) — the same fluent chain also accepts plugins via .use().
Does it have a plugin system?Yes — plugins attach per request with .use(). The ecosystem covers caching, throttling, mocking, URL prefixing, charset handling, cheerio parsing (res.$) and AWS request signing; plugin names should be prefixed with superagent-.
Is superagent still actively maintained?Yes. It is maintained for Forward Email and Lad — the @forwardemail and @ladjs teams, alongside @spamscanner, @breejs, @cabinjs and @lassjs — and has been around since 2011, with changelogs published on GitHub releases.
What are similar projects?pdf.js, fetch, ky, vue-resource, dragula, ua-parser-js, socket.io-client, axios
Which topics is it in?isomorphic, vanilla-javascript, http-client, plugins, node, http, javascript-library, browser, rest-api, mobile, desktop, npm
Creator
forwardemail
Size
7 MB
Stars
16.6K
Updated
CommitSep 23Releasev10.4.1Sep 23
Age
15y
Commits · 90 Days