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

10 hits · last 30 days

node

Resources

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

packagereturn-fetch ↗

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