return-fetch

library0.4.8jsnpmunverified

return-fetch v0.4.8 is a lightweight TypeScript library (under 1KB gzipped) that wraps the native fetch API to provide request/response interceptors, base URL prefixing, and default headers. It is designed as a higher-order function, returning an enhanced fetch function with the same interface, making it ideal for Next.js App Router (which uses a patched fetch) and isomorphic usage. Unlike Axios or ky, it does not introduce new APIs or create custom adapters; instead, it composes naturally with existing fetch patterns. The library is ESM-first with CommonJS fallback, ships TypeScript definitions, and is actively maintained with regular releases.

devops testing

npm install return-fetch

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · RETURN-FETCH

return-fetch

devopsjavascriptv0.4.8

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.

returnFetch

✓ import returnFetch from 'return-fetch'

✗ import { returnFetch } from 'return-fetch'

This is a default export. Named import will fail in ESM environments.

ReturnFetchDefaultOptions

✓ import returnFetch, { type ReturnFetchDefaultOptions } from 'return-fetch'

✗ import { ReturnFetchDefaultOptions } from 'return-fetch'

TypeScript types are exported as named exports. Use 'import type' for clearer intent.

returnFetch (CommonJS)

✓ const returnFetch = require('return-fetch').default

✗ const returnFetch = require('return-fetch')

In CommonJS, the default export is under .default due to ESM/CJS interop.

Creates an enhanced fetch with base URL, default headers, and request/response interceptors for logging and error handling.

import returnFetch from 'return-fetch'; const api = returnFetch({ baseUrl: 'https://jsonplaceholder.typicode.com', headers: { 'Content-Type': 'application/json' }, interceptors: { request: async ([url, init]) => { console.log('Request:', url.toString()); return [url, init]; }, response: async (args, response) => { if (!response.ok) throw new Error(`HTTP ${response.status}`); return response; }, }, }); async function run() { const response = await api('/todos/1'); const data = await response.json(); console.log(data); } run().catch(console.error);

Debug

Known issues

gotchaUsing returnFetch in the browser without a native fetch polyfill may fail in older browsers.

fix

Ensure the environment supports fetch, or add a polyfill like 'whatwg-fetch'.

affects: >=0.1.0

gotchaWhen using CommonJS require(), the default export is nested under .default.

fix

Use const returnFetch = require('return-fetch').default;

affects: >=0.3.0

gotchaHeaders passed to returnFetch are merged with request headers, not overwritten by request headers.

fix

To override a default header, explicitly set it in the request object passed to the returned fetch function.

affects: >=0.0.1

breakingIn v0.3.0, the interceptor signature changed from (args) => args to async (args) => [url, init].

fix

Update interceptor to return a tuple [url, init] instead of the full args array.

affects: <0.3.0

deprecatedThe 'returnFetch.default' export is deprecated; use the default import directly.

fix

Switch to `import returnFetch from 'return-fetch'`.

affects: >=0.4.0

Errors

Common errors & fixes

Cannot find module 'return-fetch' or its corresponding type declarations.

Missing package or incorrect TypeScript configuration.

fix

Install the package: npm install return-fetch. Ensure tsconfig.json includes 'moduleResolution': 'node' or 'bundler'.

TypeError: returnFetch is not a function

Using named import instead of default import in ESM, or using require() incorrectly.

fix

Use `import returnFetch from 'return-fetch'` in ESM, or `const returnFetch = require('return-fetch').default` in CJS.

'baseUrl' is not recognized as a valid option

Using a version older than 0.4.0 that only supported 'baseUrl' as 'baseUrl' (lowercase).

fix

Upgrade to v0.4.0+ and use the option as specified. In older versions, use 'baseUrl' (lowercase 'u') if available.

Upgrade

Version history

0.4.8latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/myeongjae-kim/return-fetch ↗

packagereturn-fetch ↗

homepagehttps://return-fetch.myeongjae.kim ↗