1 | # superagent
|
2 |
|
3 | [![build status](https://img.shields.io/travis/ladjs/superagent.svg)](https://travis-ci.org/ladjs/superagent)
|
4 | [![code coverage](https://img.shields.io/codecov/c/github/ladjs/superagent.svg)](https://codecov.io/gh/ladjs/superagent)
|
5 | [![code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/sindresorhus/xo)
|
6 | [![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
|
7 | [![made with lass](https://img.shields.io/badge/made_with-lass-95CC28.svg)](https://lass.js.org)
|
8 | [![license](https://img.shields.io/github/license/ladjs/superagent.svg)](LICENSE)
|
9 |
|
10 | > 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](https://github.com/forwardemail) and [Lad](https://github.com/ladjs).
|
11 |
|
12 |
|
13 | ## Table of Contents
|
14 |
|
15 | * [Install](#install)
|
16 | * [Usage](#usage)
|
17 | * [Node](#node)
|
18 | * [Browser](#browser)
|
19 | * [Supported Platforms](#supported-platforms)
|
20 | * [Required Browser Features](#required-browser-features)
|
21 | * [Plugins](#plugins)
|
22 | * [Upgrading from previous versions](#upgrading-from-previous-versions)
|
23 | * [Contributors](#contributors)
|
24 | * [License](#license)
|
25 |
|
26 |
|
27 | ## Install
|
28 |
|
29 | [npm][]:
|
30 |
|
31 | ```sh
|
32 | npm install superagent
|
33 | ```
|
34 |
|
35 | [yarn][]:
|
36 |
|
37 | ```sh
|
38 | yarn add superagent
|
39 | ```
|
40 |
|
41 |
|
42 | ## Usage
|
43 |
|
44 | ### Node
|
45 |
|
46 | ```js
|
47 | const superagent = require('superagent');
|
48 |
|
49 | // callback
|
50 | superagent
|
51 | .post('/api/pet')
|
52 | .send({ name: 'Manny', species: 'cat' }) // sends a JSON post body
|
53 | .set('X-API-Key', 'foobar')
|
54 | .set('accept', 'json')
|
55 | .end((err, res) => {
|
56 | // Calling the end function will send the request
|
57 | });
|
58 |
|
59 | // promise with then/catch
|
60 | superagent.post('/api/pet').then(console.log).catch(console.error);
|
61 |
|
62 | // promise with async/await
|
63 | (async () => {
|
64 | try {
|
65 | const res = await superagent.post('/api/pet');
|
66 | console.log(res);
|
67 | } catch (err) {
|
68 | console.error(err);
|
69 | }
|
70 | })();
|
71 | ```
|
72 |
|
73 | ### Browser
|
74 |
|
75 | **The browser-ready, minified version of `superagent` is only 50 KB (minified and gzipped).**
|
76 |
|
77 | 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.
|
78 |
|
79 | > Note that we also provide unminified versions with `.js` instead of `.min.js` file extensions.
|
80 |
|
81 | #### VanillaJS
|
82 |
|
83 | This is the solution for you if you're just using `<script>` tags everywhere!
|
84 |
|
85 | ```html
|
86 | <script src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=WeakRef,BigInt"></script>
|
87 | <script src="https://cdn.jsdelivr.net/npm/superagent"></script>
|
88 | <!-- if you wish to use unpkg.com instead: -->
|
89 | <!-- <script src="https://unpkg.com/superagent"></script> -->
|
90 | <script type="text/javascript">
|
91 | (function() {
|
92 | // superagent is exposed as `window.superagent`
|
93 | // if you wish to use "request" instead please
|
94 | // uncomment the following line of code:
|
95 | // `window.request = superagent;`
|
96 | superagent
|
97 | .post('/api/pet')
|
98 | .send({ name: 'Manny', species: 'cat' }) // sends a JSON post body
|
99 | .set('X-API-Key', 'foobar')
|
100 | .set('accept', 'json')
|
101 | .end(function (err, res) {
|
102 | // Calling the end function will send the request
|
103 | });
|
104 | })();
|
105 | </script>
|
106 | ```
|
107 |
|
108 | #### Bundler
|
109 |
|
110 | If you are using [browserify][], [webpack][], [rollup][], or another bundler, then you can follow the same usage as [Node](#node) above.
|
111 |
|
112 |
|
113 | ## Supported Platforms
|
114 |
|
115 | * Node: v14.18.0+
|
116 | * Browsers (see [.browserslistrc](.browserslistrc)):
|
117 |
|
118 | ```sh
|
119 | npx browserslist
|
120 | ```
|
121 |
|
122 | ```sh
|
123 | and_chr 102
|
124 | and_ff 101
|
125 | and_qq 10.4
|
126 | and_uc 12.12
|
127 | android 101
|
128 | chrome 103
|
129 | chrome 102
|
130 | chrome 101
|
131 | chrome 100
|
132 | edge 103
|
133 | edge 102
|
134 | edge 101
|
135 | firefox 101
|
136 | firefox 100
|
137 | firefox 91
|
138 | ios_saf 15.5
|
139 | ios_saf 15.4
|
140 | ios_saf 15.2-15.3
|
141 | ios_saf 15.0-15.1
|
142 | ios_saf 14.5-14.8
|
143 | ios_saf 14.0-14.4
|
144 | ios_saf 12.2-12.5
|
145 | kaios 2.5
|
146 | op_mini all
|
147 | op_mob 64
|
148 | opera 86
|
149 | opera 85
|
150 | safari 15.5
|
151 | safari 15.4
|
152 | samsung 17.0
|
153 | samsung 16.0
|
154 | ```
|
155 |
|
156 | ### Required Browser Features
|
157 |
|
158 | We recommend using <https://cdnjs.cloudflare.com/polyfill/> (specifically with the bundle mentioned in [VanillaJS](#vanillajs) above):
|
159 |
|
160 | ```html
|
161 | <script src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=WeakRef,BigInt"></script>
|
162 | ```
|
163 |
|
164 | * WeakRef is not supported in Opera 85, iOS Safari 12.2-12.5
|
165 | * BigInt is not supported in iOS Safari 12.2-12.5
|
166 |
|
167 |
|
168 | ## Plugins
|
169 |
|
170 | SuperAgent is easily extended via plugins.
|
171 |
|
172 | ```js
|
173 | const nocache = require('superagent-no-cache');
|
174 | const superagent = require('superagent');
|
175 | const prefix = require('superagent-prefix')('/static');
|
176 |
|
177 | superagent
|
178 | .get('/some-url')
|
179 | .query({ action: 'edit', city: 'London' }) // query string
|
180 | .use(prefix) // Prefixes *only* this request
|
181 | .use(nocache) // Prevents caching of *only* this request
|
182 | .end((err, res) => {
|
183 | // Do something
|
184 | });
|
185 | ```
|
186 |
|
187 | Existing plugins:
|
188 |
|
189 | * [superagent-no-cache](https://github.com/johntron/superagent-no-cache) - prevents caching by including Cache-Control header
|
190 | * [superagent-prefix](https://github.com/johntron/superagent-prefix) - prefixes absolute URLs (useful in test environment)
|
191 | * [superagent-suffix](https://github.com/timneutkens1/superagent-suffix) - suffix URLs with a given path
|
192 | * [superagent-mock](https://github.com/M6Web/superagent-mock) - simulate HTTP calls by returning data fixtures based on the requested URL
|
193 | * [superagent-mocker](https://github.com/shuvalov-anton/superagent-mocker) — simulate REST API
|
194 | * [superagent-cache](https://github.com/jpodwys/superagent-cache) - A global SuperAgent patch with built-in, flexible caching
|
195 | * [superagent-cache-plugin](https://github.com/jpodwys/superagent-cache-plugin) - A SuperAgent plugin with built-in, flexible caching
|
196 | * [superagent-jsonapify](https://github.com/alex94puchades/superagent-jsonapify) - A lightweight [json-api](http://jsonapi.org/format/) client addon for superagent
|
197 | * [superagent-serializer](https://github.com/zzarcon/superagent-serializer) - Converts server payload into different cases
|
198 | * [superagent-httpbackend](https://www.npmjs.com/package/superagent-httpbackend) - stub out requests using AngularJS' $httpBackend syntax
|
199 | * [superagent-throttle](https://github.com/leviwheatcroft/superagent-throttle) - queues and intelligently throttles requests
|
200 | * [superagent-charset](https://github.com/magicdawn/superagent-charset) - add charset support for node's SuperAgent
|
201 | * [superagent-verbose-errors](https://github.com/jcoreio/superagent-verbose-errors) - include response body in error messages for failed requests
|
202 | * [superagent-declare](https://github.com/damoclark/superagent-declare) - A simple [declarative](https://en.wikipedia.org/wiki/Declarative_programming) API for SuperAgent
|
203 | * [superagent-node-http-timings](https://github.com/webuniverseio/superagent-node-http-timings) - measure http timings in node.js
|
204 | * [superagent-cheerio](https://github.com/mmmmmrob/superagent-cheerio) - add [cheerio](https://www.npmjs.com/package/cheerio) to your response content automatically. Adds `res.$` for HTML and XML response bodies.
|
205 | * [@certible/superagent-aws-sign](https://github.com/certible/superagent-aws-sign) - Sign AWS endpoint requests, it uses the aws4 to authenticate the SuperAgent requests
|
206 |
|
207 | Please prefix your plugin with `superagent-*` so that it can easily be found by others.
|
208 |
|
209 | For SuperAgent extensions such as couchdb and oauth visit the [wiki](https://github.com/ladjs/superagent/wiki).
|
210 |
|
211 |
|
212 | ## Upgrading from previous versions
|
213 |
|
214 | Please see [GitHub releases page](https://github.com/ladjs/superagent/releases) for the current changelog.
|
215 |
|
216 | Our breaking changes are mostly in rarely used functionality and from stricter error handling.
|
217 |
|
218 | * [6.0 to 6.1](https://github.com/ladjs/superagent/releases/tag/v6.1.0)
|
219 | * Browser behaviour changed to match Node when serializing `application/x-www-form-urlencoded`, using `arrayFormat: 'indices'` semantics of `qs` library. (See: <https://www.npmjs.com/package/qs#stringifying>)
|
220 | * [5.x to 6.x](https://github.com/ladjs/superagent/releases/tag/v6.0.0):
|
221 | * 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)
|
222 | * A specific issue with Content-Type matching not being case-insensitive is fixed
|
223 | * Set is now required for IE 9, see [Required Browser Features](#required-browser-features) for more insight
|
224 | * [4.x to 5.x](https://github.com/ladjs/superagent/releases/tag/v5.0.0):
|
225 | * We've implemented the build setup of [Lass](https://lass.js.org) to simplify our stack and linting
|
226 | * 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`)
|
227 | * Linting support has been added using `caniuse-lite` and `eslint-plugin-compat`
|
228 | * We can now target what versions of Node we wish to support more easily using `.babelrc`
|
229 | * [3.x to 4.x](https://github.com/ladjs/superagent/releases/tag/v4.0.0-alpha.1):
|
230 | * Ensure you're running Node 6 or later. We've dropped support for Node 4.
|
231 | * We've started using ES6 and for compatibility with Internet Explorer you may need to use Babel.
|
232 | * We suggest migrating from `.end()` callbacks to `.then()` or `await`.
|
233 | * [2.x to 3.x](https://github.com/ladjs/superagent/releases/tag/v3.0.0):
|
234 | * Ensure you're running Node 4 or later. We've dropped support for Node 0.x.
|
235 | * Test code that calls `.send()` multiple times. Invalid calls to `.send()` will now throw instead of sending garbage.
|
236 | * [1.x to 2.x](https://github.com/ladjs/superagent/releases/tag/v2.0.0):
|
237 | * If you use `.parse()` in the *browser* version, rename it to `.serialize()`.
|
238 | * 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).
|
239 | * If you use `.then()` in Internet Explorer, ensure that you have a polyfill that adds a global `Promise` object.
|
240 | * 0.x to 1.x:
|
241 | * Instead of 1-argument callback `.end(function(res){})` use `.then(res => {})`.
|
242 |
|
243 |
|
244 | ## Contributors
|
245 |
|
246 | | Name |
|
247 | | ------------------- |
|
248 | | **Kornel Lesiński** |
|
249 | | **Peter Lyons** |
|
250 | | **Hunter Loftis** |
|
251 | | **Nick Baugh** |
|
252 |
|
253 |
|
254 | ## License
|
255 |
|
256 | [MIT](LICENSE) © TJ Holowaychuk
|
257 |
|
258 |
|
259 | ##
|
260 |
|
261 | [npm]: https://www.npmjs.com/
|
262 |
|
263 | [yarn]: https://yarnpkg.com/
|
264 |
|
265 | [jsdelivr]: https://www.jsdelivr.com/
|
266 |
|
267 | [unpkg]: https://unpkg.com/
|
268 |
|
269 | [browserify]: https://github.com/browserify/browserify
|
270 |
|
271 | [webpack]: https://github.com/webpack/webpack
|
272 |
|
273 | [rollup]: https://github.com/rollup/rollup
|