axios-jwt

library4.0.3jsnpmunverified

Axios interceptor library for automatic JWT token storage, transmission, and refresh. Current stable version 4.0.3 (released Oct 2023), actively maintained. Supports both web (localStorage/sessionStorage) and React Native (AsyncStorage). Key differentiator: parses JWT expiration to proactively refresh before every request, preventing 401 errors. Requires explicit token refresh function provided by user, supports rotating refresh tokens. ESM/CJS compatible, ships TypeScript types. Peer dependencies: @react-native-async-storage/async-storage (React Native only) and axios ^1.4.0.

security

npm install axios-jwt

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AXIOS-JWT

axios-jwt

securityjavascriptv4.0.3

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.

applyAuthTokenInterceptor

✓ import { applyAuthTokenInterceptor } from 'axios-jwt'

✗ const applyAuthTokenInterceptor = require('axios-jwt').applyAuthTokenInterceptor

ESM import preferred. CJS require works but may have issues with TypeScript types.

setAuthTokens

✓ import { setAuthTokens } from 'axios-jwt'

✗ import setAuthTokens from 'axios-jwt'

This is a named export, not default. Common mistake when using default import.

getBrowserLocalStorage

✓ import { getBrowserLocalStorage } from 'axios-jwt'

✗ import { getBrowserLocalStorage } from 'axios-jwt/storage'

All utilities are exported from the main module. No subpath exports.

Demonstrates setup of axios-jwt interceptor with token refresh, login, and logout functions.

import axios from 'axios'; import { applyAuthTokenInterceptor, getBrowserLocalStorage, setAuthTokens, clearAuthTokens } from 'axios-jwt'; const BASE_URL = 'https://api.example.com'; const axiosInstance = axios.create({ baseURL: BASE_URL }); const requestRefresh = async (refreshToken) => { const response = await axios.post(`${BASE_URL}/auth/refresh`, { token: refreshToken }); return response.data.accessToken; }; applyAuthTokenInterceptor(axiosInstance, { requestRefresh, getStorage: getBrowserLocalStorage }); async function login(email, password) { const response = await axiosInstance.post('/auth/login', { email, password }); await setAuthTokens({ accessToken: response.data.accessToken, refreshToken: response.data.refreshToken }); } async function logout() { await clearAuthTokens(); }

Debug

Known issues

gotchaDo not use the same axios instance for token refresh that you supplied to applyAuthTokenInterceptor

fix

Use the global axios client or a different axios instance inside the requestRefresh function to avoid infinite loops.

affects: >=0.0.0

breakingVersion 2.0.0 migrated from localStorage to configurable storage with getStorage option

fix

Update to use getBrowserLocalStorage or provide custom storage implementation.

affects: <2.0.0

deprecatedgetStorage should be provided explicitly; auto-detection of environment is removed.

fix

Pass getBrowserLocalStorage for web, or create a custom storage for React Native.

affects: >=2.0.0

gotchaAccess tokens must be JWT with an 'exp' claim for expiration checking to work

fix

Ensure your access token is a valid JWT with expiration. The library will not refresh if exp is missing.

affects: >=0.0.0

gotchaToken refresh function must not throw on 401; library does not handle refresh failures gracefully

fix

Implement error handling inside requestRefresh, e.g., redirect to login on failure.

affects: >=0.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'accessToken')

Token refresh function returns undefined or malformed response.

fix

Ensure requestRefresh returns a string (accessToken) or IAuthTokens object with accessToken property.

Error: getStorage is not defined

Missing getStorage option or incorrect import.

fix

Import getBrowserLocalStorage from 'axios-jwt' and pass it in config: { requestRefresh, getStorage: getBrowserLocalStorage }

Unhandled Promise Rejection: Error: Tokens not found

Trying to get access token before setting it with setAuthTokens.

fix

Call setAuthTokens after successful login, or check isLoggedIn() before attempting to get tokens.

Upgrade

Version history

4.0.3latest on npm

Audit

Dependencies

@react-native-async-storage/async-storageoptionalRequired only for React Native projects to store tokens persistently.

axiosrequiredPeer dependency for the axios instance that interceptors are applied to.

Agent activity

16 hits · last 30 days

node

Resources

githubhttps://github.com/jetbridge/axios-jwt ↗

packageaxios-jwt ↗

homepagehttps://github.com/jetbridge/axios-jwt ↗