wonderful-fetch

Site | NPM Module | GitHub Repo

wonderful-fetch is a powerful wrapper around the native fetch API that works in Node.js and the browser.

Features

• Works in both Node.js and browser environments (including Webpack)
• Automatic JSON response parsing
• Automatic retries with exponential backoff
• Request timeouts via AbortController
• Authorization header management
• Query parameter building
• Cache busting
• File downloads (Node.js only)
• Error objects enriched with HTTP status codes

Install

npm

npm install wonderful-fetch

// ESM
import fetch from 'wonderful-fetch';

// CommonJS
const fetch = require('wonderful-fetch');

CDN

<script src="https://cdn.jsdelivr.net/npm/wonderful-fetch@latest/dist/wonderful-fetch.min.js"></script>
<script>
  WonderfulFetch('https://api.example.com/data', { response: 'json' })
    .then(data => console.log(data));
</script>

Usage

Basic request

const res = await fetch('https://httpbin.org/status/200');
console.log(res.status); // 200

JSON response

const data = await fetch('https://httpbin.org/json', { response: 'json' });
console.log(data);

POST with JSON body

const data = await fetch('https://httpbin.org/post', {
  method: 'post',
  body: { hello: 'world' },
  response: 'json',
});

Complete output (status + headers + body)

const result = await fetch('https://httpbin.org/get', {
  response: 'json',
  output: 'complete',
});
console.log(result.status);  // 200
console.log(result.headers); // { ... }
console.log(result.body);    // { ... }

Retries with backoff

const data = await fetch('https://httpbin.org/get', {
  response: 'json',
  tries: 3,       // Retry up to 3 times
  timeout: 10000, // 10 second timeout per attempt
});

Authorization

// Automatically prefixes "Bearer " if no prefix is present
const data = await fetch('https://httpbin.org/get', {
  response: 'json',
  authorization: 'my-token',
});

// Or use an existing prefix
const data = await fetch('https://httpbin.org/get', {
  response: 'json',
  authorization: 'Basic abc123',
});

Download file (Node.js only)

const result = await fetch('https://httpbin.org/image/png', {
  download: './image',
});
console.log(result.path); // ./image.png (extension auto-detected)

Error handling

Errors from non-2xx responses include the HTTP status code:

try {
  await fetch('https://httpbin.org/status/404');
} catch (err) {
  console.log(err.message); // Response body text
  console.log(err.status);  // 404
}

Options

Option	Type	Default	Description
method	string	'get'	HTTP method (get, post, put, delete, patch)
response	string	'raw'	Response format: 'raw', 'json', or 'text'
output	string	'body'	Output format: 'body' (parsed response only) or 'complete' ({ status, headers, body })
timeout	number	60000	Request timeout in milliseconds
tries	number	1	Number of retry attempts. 0 for infinite retries
headers	object	{}	Custom request headers
body	any	null	Request body. Objects are auto-stringified as JSON
query	object	{}	URL query parameters
authorization	string|false	false	Sets Authorization header. Auto-prefixes Bearer if no prefix
cacheBreaker	boolean|any	true	Appends ?cb={timestamp} to URL. Pass false to disable
contentType	string	''	Force content type (e.g. 'json')
download	string|false	false	File path to download response to (Node.js only)
attachResponseHeaders	boolean	false	Attach response headers to error objects
log	boolean	false	Enable debug logging

Final words

If you are still having difficulty, we would love for you to post a question to the Wonderful Fetch issues page. It is much easier to answer questions that include your code and relevant files! So if you can provide them, we'd be extremely grateful (and more likely to help you find the answer!)

Projects using this library

Somiibo: A Social Media Bot with an open-source module library.
JekyllUp: A website devoted to sharing the best Jekyll themes.
Slapform: A backend processor for your HTML forms on static sites.
SoundGrail Music App: A resource for producers, musicians, and DJs.
Hammock Report: An API for exploring and listing backyard products.

Ask us to have your project listed! :)