UNPKG

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