What is node-fetch?
The node-fetch package is a light-weight module that brings window.fetch to Node.js. It is designed to provide a fetch-first, URL-friendly way to access resources across the network.
What are node-fetch's main functionalities?
Simple GET Request
This code performs a simple GET request to the GitHub API and logs the response data.
const fetch = require('node-fetch');
fetch('https://api.github.com/users/github')
.then(response => response.json())
.then(data => console.log(data));
POST Request with JSON
This code sends a POST request with a JSON body to httpbin.org and logs the response JSON.
const fetch = require('node-fetch');
fetch('https://httpbin.org/post', {
method: 'post',
body: JSON.stringify({foo: 'bar'}),
headers: { 'Content-Type': 'application/json' },
})
.then(res => res.json())
.then(json => console.log(json));
Handling Network Errors
This code attempts to fetch a resource from an invalid domain and catches network errors.
const fetch = require('node-fetch');
fetch('https://domain.invalid')
.catch(err => console.error('Network error:', err));
Stream Response
This code fetches an image from GitHub and streams it to a file.
const fetch = require('node-fetch');
const fs = require('fs');
fetch('https://assets-cdn.github.com/images/modules/logos_page/Octocat.png')
.then(res => {
const dest = fs.createWriteStream('./octocat.png');
res.body.pipe(dest);
});
Other packages similar to node-fetch
axios
Axios is a promise-based HTTP client for the browser and Node.js. It supports interceptors, request/response transformations, and automatic transforms for JSON data. Axios is often considered more feature-rich than node-fetch, with built-in support for interceptors and a wider range of HTTP request methods.
got
Got is a human-friendly and powerful HTTP request library for Node.js. It provides a simpler and more comprehensive API than node-fetch, with features like retries, pagination, and streams. Got is designed to be a more robust and versatile alternative to node-fetch, with additional convenience methods and options.
superagent
Superagent is a small progressive client-side HTTP request library, and Node.js module with the same API, sporting many high-level HTTP client features. Compared to node-fetch, Superagent offers a more fluent and flexible API, with methods for building queries and handling responses in a more expressive way.
request
Request is a simplified HTTP request client for Node.js, which has been deprecated. It was known for its simplicity and wide adoption but has been replaced by more modern libraries like node-fetch. Despite its deprecation, it was once a popular alternative with a callback-based API.
node-fetch
A light-weight module that brings window.fetch
to node.js & io.js
Motivation
I really like the notion of Matt Andrews' isomorphic-fetch: it bridges the API gap between client-side and server-side http requests, so developers have less to worry about.
Instead of implementing XMLHttpRequest
in node to run browser-specific fetch polyfill, why not go from node's http
to fetch
API directly? Node has native stream support, browserify build targets (browsers) don't, so underneath they are going to be vastly different anyway.
Hence node-fetch
, minimal code for a window.fetch
compatible API on node.js/io.js runtime.
Features
- Stay consistent with
window.fetch
API. - Make conscious trade-off when following whatwg fetch spec and stream spec implementation details, document known difference.
- Use native promise, but allow substituting it with [insert your favorite promise library].
- Use native stream for body, on both request and response.
- Decode content encoding (gzip/deflate) properly, and convert string output (such as
res.text()
and res.json()
) to utf-8 automatically. - Useful extensions such as timeout, redirect limit, response size limit.
Difference from client-side fetch
- See Known limits for details.
- If you happen to use a missing feature that
window.fetch
offers, feel free to open an issue. - Pull requests are welcomed too!
Install
npm install node-fetch --save
Usage
var fetch = require('node-fetch');
fetch('https://github.com/')
.then(function(res) {
return res.text();
}).then(function(body) {
console.log(body);
});
fetch('https://api.github.com/users/github')
.then(function(res) {
return res.json();
}).then(function(json) {
console.log(json);
});
fetch('https://github.com/')
.then(function(res) {
console.log(res.ok);
console.log(res.status);
console.log(res.statusText);
console.log(res.headers.raw());
console.log(res.headers.get('content-type'));
});
fetch('http://httpbin.org/post', { method: 'POST', body: 'a=1' })
.then(function(res) {
return res.json();
}).then(function(json) {
console.log(json);
});
var resumer = require('resumer');
var stream = resumer().queue('a=1').end();
fetch('http://httpbin.org/post', { method: 'POST', body: stream })
.then(function(res) {
return res.json();
}).then(function(json) {
console.log(json);
});
var FormData = require('form-data');
var form = new FormData();
form.append('a', 1);
fetch('http://httpbin.org/post', { method: 'POST', body: form, headers: form.getHeaders() })
.then(function(res) {
return res.json();
}).then(function(json) {
console.log(json);
});
var co = require('co');
co(function *() {
var res = yield fetch('https://api.github.com/users/github');
var json = yield res.json();
console.log(res);
});
See test cases for more examples.
API
fetch(url, options)
Returns a Promise
Url
Should be an absolute url, eg http://example.com/
Options
default values are shown, note that only method
, headers
and body
are allowed in window.fetch
, others are node.js extensions.
{
method: 'GET'
, headers: {} // request header, format {a:1} or {b:[1,2,3]}
, follow: 20 // maximum redirect count, 0 to not follow redirect
, timeout: 0 // req/res timeout in ms, 0 to disable, timeout reset on redirect
, compress: true // support gzip/deflate content encoding, false to disable
, size: 0 // maximum response body size in bytes, 0 to disable
, body: empty // request body, can be a string or readable stream
, agent: null // custom http.Agent instance
}
License
MIT
Acknowledgement
Thanks to github/fetch for providing a solid implementation reference.