Registry / security / axios-auth-refresh

axios-auth-refresh

library5.0.2jsnpmunverified

Axios plugin for automatic token refresh via request interceptors. Current stable version 5.0.2, actively maintained. Key differentiator: it stalls concurrent requests during token refresh and resolves them once a new token is available, preventing duplicate refresh calls. Requires axios >= 1.0.0 as a peer dependency. Ships TypeScript definitions. The library itself is lightweight (~1.2kB minified) and only intercepts 401 status codes by default, but allows custom status codes via options.

security

npm install axios-auth-refresh

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AXIOS-AUTH-REFRESH

axios-auth-refresh

securityjavascriptv5.0.2

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.

createAuthRefresh

✓ import { createAuthRefresh } from 'axios-auth-refresh';

✗ import createAuthRefresh from 'axios-auth-refresh';

Named export, not default. This is the main function to set up the interceptor.

AxiosAuthRefreshRequestConfig

✓ import { AxiosAuthRefreshRequestConfig } from 'axios-auth-refresh';

✗ import { AxiosAuthRefreshRequestConfig } from 'axios';

TypeScript only. Used to extend AxiosRequestConfig with the skipAuthRefresh option.

AxiosAuthRefreshOptions

✓ import type { AxiosAuthRefreshOptions } from 'axios-auth-refresh';

✗ import { AxiosAuthRefreshOptions } from 'axios-auth-refresh';

TypeScript only. Can be imported as type if using type-only imports. Represents the options object for createAuthRefresh.

Sets up automatic token refresh on 401 errors: interceptor calls refreshAuthLogic, updates Authorization header, and retries the original request.

import axios from 'axios'; import { createAuthRefresh } from 'axios-auth-refresh'; const refreshAuthLogic = async (failedRequest: any) => { const response = await axios.post('https://example.com/auth/refresh', { refreshToken: localStorage.getItem('refreshToken') }); localStorage.setItem('token', response.data.token); failedRequest.response.config.headers['Authorization'] = 'Bearer ' + response.data.token; return Promise.resolve(); }; createAuthRefresh(axios, refreshAuthLogic); axios.get('https://example.com/protected').then(response => { console.log(response.data); }).catch(error => { console.error('Request failed even after refresh', error); });

Debug

Known issues

gotchaThe refreshAuthLogic function must return a Promise (or be async). If it returns nothing, the interceptor will hang and never retry the failed request.

fix

Ensure the function returns a promise: const refreshAuthLogic = async (failedRequest) => { await refresh(); };

affects: >=0.0.0

breakingVersion 5.0.0 dropped support for axios < 1.0.0. The package now requires axios >= 1.0.0 as a peer dependency.

fix

Upgrade axios to 1.x or stay on axios-auth-refresh v4.x if using axios 0.x.

affects: >=5.0.0

gotchaThe interceptor only runs on 401 status codes by default. To change this, pass the 'statusCodes' option to createAuthRefresh.

fix

Use: createAuthRefresh(axios, refreshAuthLogic, { statusCodes: [401, 403] });

affects: >=0.0.0

deprecatedThe 'interceptNetworkError' options (boolean) has been deprecated and may be removed in future versions. Use 'shouldRefresh' callback instead.

fix

Replace { interceptNetworkError: true } with { shouldRefresh: (error) => !error.response }

affects: >=4.0.0

gotchaWhen using the skipAuthRefresh option in a request config, TypeScript will complain about unknown property unless you cast the config to AxiosAuthRefreshRequestConfig.

fix

Import AxiosAuthRefreshRequestConfig and use: axios.get('/url', { skipAuthRefresh: true } as AxiosAuthRefreshRequestConfig);

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: createAuthRefresh is not a function

Using default import instead of named import. The library exports { createAuthRefresh } as named export.

fix

Replace 'import createAuthRefresh from "axios-auth-refresh";' with 'import { createAuthRefresh } from "axios-auth-refresh";'

Cannot read properties of undefined (reading 'config')

In refreshAuthLogic, accessing failedRequest.response.config but failedRequest.response is undefined (e.g., network error without a response).

fix

Check if failedRequest.response exists before accessing config, or use the shouldRefresh option to avoid network errors.

Uncaught (in promise) TypeError: axios is not a function

Passing an axios instance that is not yet fully initialized (e.g., importing axios before the default export is available) or using axios.create() but not awaiting it.

fix

Ensure the axios instance is created before calling createAuthRefresh: const axiosInstance = axios.create(); createAuthRefresh(axiosInstance, ...);

Upgrade

Version history

5.0.2latest on npm

Audit

Dependencies

axiosrequiredPeer dependency – the library intercepts axios requests and requires an axios instance as the first argument

Agent activity

20 hits · last 30 days

node

Resources

githubhttps://github.com/Flyrell/axios-auth-refresh ↗

packageaxios-auth-refresh ↗

homepagehttps://github.com/Flyrell/axios-auth-refresh#readme ↗