use-fetch

library0.0.7jsnpmunverified

A thin fetch wrapper (v0.0.7) providing useful defaults like JSON handling, retry logic, timeout, and error types (HTTPError, ParseError, TimeoutError). Inspired by got. Actively maintained on GitHub with regular updates. Key differentiators: lightweight, no dependencies, ESM and CJS support, bundled for browsers via unpkg, and extensible via createFetch. Unlike ky or node-fetch, it focuses on minimal overhead while adding essential features.

devops

npm install use-fetch

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · USE-FETCH

use-fetch

devopsjavascriptv0.0.7

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default (usefetch)

✓ import usefetch from 'use-fetch'

✗ const usefetch = require('use-fetch')

Package exports ESM and CJS; default export is a configured fetch function.

createFetch

✓ import { createFetch } from 'use-fetch'

✗ const { createFetch } = require('use-fetch')

Named export for creating custom fetch instances with overridden defaults.

HTTPError

✓ import { HTTPError } from 'use-fetch'

✗ import HTTPError from 'use-fetch'

Named export; not part of default export.

ParseError

✓ import { ParseError } from 'use-fetch'

✗ const { ParseError } = require('use-fetch')

Named export; use ESM import for consistency.

TimeoutError

✓ import { TimeoutError } from 'use-fetch'

✗ const TimeoutError = require('use-fetch').TimeoutError

Named export; avoid destructuring from require.

Demonstrates basic GET request with JSON parsing and error handling for HTTP and timeout errors.

import usefetch from 'use-fetch'; async function getMessages() { try { const response = await usefetch('/messages', { json: true }); console.log(response.body); // parsed JSON } catch (error) { if (error instanceof usefetch.HTTPError) { console.error('HTTP error:', error.status, error.statusText); } else if (error instanceof usefetch.TimeoutError) { console.error('Request timed out'); } } } getMessages();

Debug

Known issues

gotchaThe `json` option automatically parses response body and sets Content-Type to application/json; do NOT call response.json() manually.

fix

Access parsed data via response.body.

affects: >=0.0.0

gotchaDefault timeout is 0 (no timeout). Requests may hang indefinitely if server does not respond.

fix

Set timeout option to a positive number to avoid hanging requests.

affects: >=0.0.0

gotchaRetry logic only applies to methods: GET, PUT, HEAD, DELETE, OPTIONS, TRACE. POST and PATCH are not retried by default.

fix

Override the methods array in retry option to include POST if needed.

affects: >=0.0.0

gotchaThe library does not ship with a fetch polyfill; if used in older browsers (e.g., IE11), you must provide one (e.g., unfetch).

fix

Add a fetch polyfill like unfetch before importing use-fetch.

affects: >=0.0.0

gotchaTimeouts rely on AbortController. In environments without it (e.g., older Node.js < 14), timeout may not work and will resolve after default fetch timeout.

fix

Polyfill AbortController or use Node.js >= 14.

affects: >=0.0.0

Errors

Common errors & fixes

TypeError: usefetch.HTTPError is not a constructor

Attempting to instantiate HTTPError directly; HTTPError is a class meant to be thrown internally, not constructed manually.

fix

Do not use new usefetch.HTTPError(); errors are automatically created by usefetch on failed requests.

Unhandled Rejection: Error: JSON parse error: Unexpected token <

The json: true option expects a JSON response but server returned HTML (e.g., 404 page).

fix

Check response.status before parsing JSON, or set json: false and parse manually.

TimeoutError: The operation was aborted

Request exceeded the timeout value set in options. Default is 0 (no timeout), but if timeout is set, this error occurs when server takes too long.

fix

Increase timeout value or investigate server response time.

Upgrade

Version history

0.0.7latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/sullenor/use-fetch ↗

packageuse-fetch ↗

homepagehttps://github.com/sullenor/use-fetch#readme ↗