superagent
Ajax for Node.js and browsers (JS HTTP client). Maintained for @forwardemail, @ladjs, @spamscanner, @breejs, @cabinjs, and @lassjs.
Top Related Projects
Promise based HTTP client for the browser and node.js
🏊🏾 Simplified HTTP request client.
A light-weight module that brings the Fetch API to Node.js
🌐 Human-friendly and powerful HTTP request library for Node.js
🕷 Super-agent driven library for testing node.js HTTP servers using a fluent API. Maintained for @forwardemail, @ladjs, @spamscanner, @breejs, @cabinjs, and @lassjs.
Quick Overview
Superagent is a lightweight, flexible, and feature-rich HTTP client library for Node.js and browsers. It provides a high-level abstraction for making HTTP requests with a chainable API, making it easy to send and receive data in various formats.
Pros
- Simple and intuitive API for making HTTP requests
- Supports both Node.js and browser environments
- Extensive plugin ecosystem for additional functionality
- Built-in support for promises and async/await
Cons
- May be overkill for simple projects with basic HTTP needs
- Some users report occasional issues with certain edge cases
- Documentation could be more comprehensive for advanced use cases
Code Examples
- Making a GET request:
const superagent = require('superagent');
async function fetchData() {
try {
const response = await superagent.get('https://api.example.com/data');
console.log(response.body);
} catch (error) {
console.error('Error:', error.message);
}
}
- Sending a POST request with JSON data:
const superagent = require('superagent');
async function createUser(userData) {
try {
const response = await superagent
.post('https://api.example.com/users')
.send(userData)
.set('Content-Type', 'application/json');
console.log('User created:', response.body);
} catch (error) {
console.error('Error:', error.message);
}
}
- Handling file uploads:
const superagent = require('superagent');
async function uploadFile(filePath) {
try {
const response = await superagent
.post('https://api.example.com/upload')
.attach('file', filePath);
console.log('File uploaded:', response.body);
} catch (error) {
console.error('Error:', error.message);
}
}
Getting Started
To use Superagent in your project, follow these steps:
- Install the package:
npm install superagent
- Import and use in your code:
const superagent = require('superagent');
async function makeRequest() {
try {
const response = await superagent.get('https://api.example.com/data');
console.log(response.body);
} catch (error) {
console.error('Error:', error.message);
}
}
makeRequest();
This example demonstrates how to make a simple GET request using Superagent. You can build upon this to create more complex requests and handle various response types.
Competitor Comparisons
Promise based HTTP client for the browser and node.js
Pros of Axios
- Built-in support for request and response interceptors
- Automatic request and response transformations
- Better TypeScript support and type definitions
Cons of Axios
- Larger bundle size compared to SuperAgent
- Less flexible API for handling file uploads
- Fewer browser compatibility options for older versions
Code Comparison
Axios:
axios.get('/user?ID=12345')
.then(function (response) {
console.log(response);
})
.catch(function (error) {
console.log(error);
});
SuperAgent:
superagent
.get('/user')
.query({ ID: 12345 })
.end((err, res) => {
if (err) console.log(err);
else console.log(res);
});
Both Axios and SuperAgent are popular HTTP client libraries for JavaScript. Axios offers a more modern API with built-in features like interceptors and automatic transformations, making it easier to handle complex requests. It also provides better TypeScript support, which is beneficial for large-scale projects.
However, Axios has a larger bundle size, which may be a concern for smaller applications or those prioritizing performance. SuperAgent, on the other hand, has a more flexible API for handling file uploads and offers more options for browser compatibility with older versions.
The code comparison shows that both libraries have similar syntax for making HTTP requests, with Axios using Promises and SuperAgent using a callback-based approach. The choice between the two often depends on specific project requirements and personal preferences.
🏊🏾 Simplified HTTP request client.
Pros of Request
- More mature and widely adopted project with a larger ecosystem
- Simpler API for basic HTTP requests
- Better support for streaming large files
Cons of Request
- No longer actively maintained (deprecated)
- Lacks some modern features like promise support out of the box
- Larger bundle size compared to SuperAgent
Code Comparison
Request:
const request = require('request');
request('https://api.example.com', (error, response, body) => {
if (!error && response.statusCode == 200) {
console.log(body);
}
});
SuperAgent:
const superagent = require('superagent');
superagent
.get('https://api.example.com')
.end((err, res) => {
if (res.ok) {
console.log(res.body);
}
});
Both libraries provide similar functionality for making HTTP requests, but SuperAgent offers a more modern and chainable API. Request uses a callback-based approach, while SuperAgent supports both callbacks and promises.
SuperAgent is actively maintained and provides better support for modern JavaScript features. However, Request still has a larger ecosystem due to its long-standing popularity.
For new projects, SuperAgent is generally recommended due to its active development and modern features. Existing projects using Request may consider migrating to SuperAgent or other alternatives, as Request is no longer maintained.
A light-weight module that brings the Fetch API to Node.js
Pros of node-fetch
- Lightweight and focused on providing a minimal, Promise-based HTTP client
- Closely mimics the browser's Fetch API, making it easier to write isomorphic code
- Supports streaming responses, which can be beneficial for large payloads
Cons of node-fetch
- Less feature-rich compared to SuperAgent, requiring additional libraries for advanced functionality
- Limited built-in support for more complex request scenarios (e.g., retries, progress tracking)
- Doesn't provide as many convenience methods for common operations
Code Comparison
node-fetch:
const fetch = require('node-fetch');
fetch('https://api.example.com/data')
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
SuperAgent:
const superagent = require('superagent');
superagent
.get('https://api.example.com/data')
.end((err, res) => {
if (err) console.error('Error:', err);
else console.log(res.body);
});
Summary
node-fetch provides a lightweight and standards-compliant HTTP client that closely resembles the browser's Fetch API. It's ideal for projects that prioritize simplicity and isomorphic code. SuperAgent, on the other hand, offers a more feature-rich API with additional convenience methods and built-in functionality for complex scenarios. The choice between the two depends on the specific requirements of your project and personal preference for API style.
🌐 Human-friendly and powerful HTTP request library for Node.js
Pros of Got
- Simpler API with a more modern, Promise-based approach
- Better performance and smaller bundle size
- Built-in request retrying and pagination support
Cons of Got
- Less mature and potentially less stable than SuperAgent
- Fewer plugins and middleware options available
- May require more setup for complex use cases
Code Comparison
SuperAgent:
const superagent = require('superagent');
superagent
.get('https://api.example.com/data')
.query({ param: 'value' })
.end((err, res) => {
if (err) console.error(err);
console.log(res.body);
});
Got:
const got = require('got');
(async () => {
try {
const response = await got('https://api.example.com/data', {
searchParams: { param: 'value' }
});
console.log(response.body);
} catch (error) {
console.error(error);
}
})();
Both SuperAgent and Got are popular HTTP client libraries for Node.js. SuperAgent has been around longer and offers a more extensive plugin ecosystem, while Got provides a more modern API with built-in features like retrying and pagination. SuperAgent uses a chaining API with callbacks, whereas Got leverages Promises and async/await for cleaner code. The choice between the two depends on specific project requirements and personal preferences.
🕷 Super-agent driven library for testing node.js HTTP servers using a fluent API. Maintained for @forwardemail, @ladjs, @spamscanner, @breejs, @cabinjs, and @lassjs.
Pros of supertest
- Specifically designed for testing HTTP servers
- Provides a high-level abstraction for making assertions about HTTP responses
- Integrates well with testing frameworks like Mocha and Jest
Cons of supertest
- Limited to server-side testing, not suitable for browser-based requests
- May have a steeper learning curve for those unfamiliar with testing concepts
Code comparison
supertest:
const request = require('supertest');
const express = require('express');
const app = express();
request(app)
.get('/user')
.expect('Content-Type', /json/)
.expect(200, done);
superagent:
const superagent = require('superagent');
superagent
.get('/user')
.end((err, res) => {
// Handle response
});
Key differences
- supertest is built on top of superagent, extending its functionality for testing purposes
- supertest provides a more declarative API for making assertions about HTTP responses
- superagent is more general-purpose and can be used for both client-side and server-side requests
Use cases
- supertest: Ideal for writing automated tests for Node.js HTTP servers and APIs
- superagent: Better suited for making HTTP requests in both browser and Node.js environments, with a focus on flexibility and ease of use
Community and maintenance
Both projects are actively maintained and have strong community support. superagent has a larger user base due to its broader applicability, while supertest is more focused on the testing niche.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
superagent
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
-
Node: v14.18.0+
-
Browsers (see .browserslistrc):
npx browserslist
and_chr 102 and_ff 101 and_qq 10.4 and_uc 12.12 android 101 chrome 103 chrome 102 chrome 101 chrome 100 edge 103 edge 102 edge 101 firefox 101 firefox 100 firefox 91 ios_saf 15.5 ios_saf 15.4 ios_saf 15.2-15.3 ios_saf 15.0-15.1 ios_saf 14.5-14.8 ios_saf 14.0-14.4 ios_saf 12.2-12.5 kaios 2.5 op_mini all op_mob 64 opera 86 opera 85 safari 15.5 safari 15.4 samsung 17.0 samsung 16.0
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>
- WeakRef is not supported in Opera 85, iOS Safari 12.2-12.5
- BigInt is not supported in iOS Safari 12.2-12.5
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:
- 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 lightweight json-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 simple declarative API for SuperAgent
- superagent-node-http-timings - measure http timings in node.js
- superagent-cheerio - add cheerio to your response content automatically. Adds
res.$
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 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.
- 6.0 to 6.1
- Browser behaviour changed to match Node when serializing
application/x-www-form-urlencoded
, usingarrayFormat: 'indices'
semantics ofqs
library. (See: https://www.npmjs.com/package/qs#stringifying)
- Browser behaviour changed to match Node when serializing
- 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, see Required Browser Features for more insight
- 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
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 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 globalPromise
object.
- If you use
- 0.x to 1.x:
- Instead of 1-argument callback
.end(function(res){})
use.then(res => {})
.
- Instead of 1-argument callback
Contributors
Name |
---|
Kornel LesiÅski |
Peter Lyons |
Hunter Loftis |
Nick Baugh |
License
MIT © TJ Holowaychuk
Top Related Projects
Promise based HTTP client for the browser and node.js
🏊🏾 Simplified HTTP request client.
A light-weight module that brings the Fetch API to Node.js
🌐 Human-friendly and powerful HTTP request library for Node.js
🕷 Super-agent driven library for testing node.js HTTP servers using a fluent API. Maintained for @forwardemail, @ladjs, @spamscanner, @breejs, @cabinjs, and @lassjs.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot