refresh-fetch

library0.9.0jsnpmunverified

A wrapper around the fetch API that automatically handles authentication token refreshing. Current stable version is 0.9.0. It intercepts fetch responses, detects token expiry via a configurable `shouldRefreshToken` callback, performs token refresh via a `refreshToken` function, and retries the original request. Unlike manual token management, refresh-fetch abstracts the retry logic and ensures concurrent requests are serialized during token refresh. Requires ES6 Promise and fetch. Suitable for single-page apps using bearer tokens with expiry.

security

npm install refresh-fetch

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REFRESH-FETCH

refresh-fetch

securityjavascriptv0.9.0

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.

configureRefreshFetch

✓ import { configureRefreshFetch } from 'refresh-fetch'

✗ const refreshFetch = require('refresh-fetch'); const { configureRefreshFetch } = refreshFetch

The library is ESM-only; named export must be destructured. No default export.

fetchJSON

✓ import { fetchJSON } from 'refresh-fetch'

✗ import fetchJSON from 'refresh-fetch'

fetchJSON is a named export, not default. Used for convenience to parse JSON responses.

configureRefreshFetch (TypeScript)

✓ import type { RefreshFetchConfig, RefreshFetch } from 'refresh-fetch'; import { configureRefreshFetch } from 'refresh-fetch'

✗ import { configureRefreshFetch, RefreshFetchConfig } from 'refresh-fetch'

Types are exported alongside the function; you can import them as type-only for cleaner transpilation.

Demonstrates configuring refresh-fetch with fetchJSON, handling 401 errors, and making a request.

import { configureRefreshFetch, fetchJSON } from 'refresh-fetch'; const fetch = configureRefreshFetch({ fetch: fetchJSON, shouldRefreshToken: error => error.response?.status === 401, refreshToken: () => fetchJSON('/auth/refresh', { method: 'POST' }).then(() => {}), }); fetch('https://api.example.com/data') .then(({ response, body }) => console.log('Success:', body)) .catch(error => console.error('Error:', error));

Debug

Known issues

breakingfetchJSON is no longer a default export; it must be imported as a named export

fix

Change import from `import fetchJSON from 'refresh-fetch'` to `import { fetchJSON } from 'refresh-fetch'`

affects: >=0.6.0

deprecatedThe `retryToken` option was deprecated in favor of `refreshToken`

fix

Rename `retryToken` to `refreshToken` in configuration

affects: >=0.5.0 <0.6.0

gotchaconfigureRefreshFetch returns a new function, so the original fetch is unchanged and can still be used directly

fix

Always use the returned function for authenticated requests; do not call original fetch

affects: all

gotchaAll errors are passed through to the catch chain; the library does not swallow errors

fix

Always attach a .catch handler to avoid unhandled promise rejections

affects: all

Errors

Common errors & fixes

Uncaught TypeError: fetch is not a function

configureRefreshFetch requires fetch to be passed as an option, but Node.js versions <18 do not have global fetch

fix

Pass a fetch polyfill like node-fetch: `import fetch from 'node-fetch'; const rf = configureRefreshFetch({ fetch, ... })`

TypeError: Cannot destructure property 'response' of 'error' as it is undefined.

shouldRefreshToken callback receives a non-standard error object; if error.response is undefined, accessing status fails

fix

Use optional chaining: `error.response?.status === 401`

Failed to execute 'fetch' on 'Window': Illegal invocation

The fetch function passed may be bound to window; when used internally as a reference, the context is lost

fix

Pass `window.fetch.bind(window)` or use an arrow function wrapper `(url, opts) => fetch(url, opts)`

Upgrade

Version history

0.9.0latest on npm

Audit

Dependencies

fetchoptionalnative fetch API is required as a peer dependency

Agent activity

18 hits · last 30 days

node

Resources

githubhttps://github.com/vlki/refresh-fetch ↗

packagerefresh-fetch ↗

homepagehttps://github.com/vlki/refresh-fetch ↗