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! :)