axios-token-refresh

axios-token-refresh is a lightweight and powerful utility for handling token refresh logic in Axios. It seamlessly integrates with Axios interceptors to automatically retry failed requests after token expiration. Perfect for managing authentication flows in modern web applications.

Table of Contents

• Features
• Installation
• Demo
• Example Usage
• Configuration Options
• Contributing
• License

Features

• Automatically retries requests after refreshing tokens.
• Configurable retry logic and status codes.
• Lightweight and easy to integrate with Axios.

Installation

With npm:

1npm install axios-token-refresh

With yarn:

1yarn add axios-token-refresh

With bun:

1bun add axios-token-refresh

Demo

You can see quickly demo here.

Example

Here is an example of how to use axios-token-refresh in your project:

1import axios from 'axios';
2import registerAxiosTokenRefresh from 'axios-token-refresh';
3
4// Create an Axios instance
5const apiClient = axios.create({
6  baseURL: 'https://api.example.com',
7});
8
9// Define the refresh token function
10const refreshAuthLogic = (failedRequest) =>
11  axios.post('https://api.example.com/refresh-token', {
12    token: localStorage.getItem('refreshToken'),
13  }).then((tokenRefreshResponse) => {
14    localStorage.setItem('accessToken', tokenRefreshResponse.data.accessToken);
15    failedRequest.response.config.headers['Authorization'] = 'Bearer ' + tokenRefreshResponse.data.accessToken;
16    return Promise.resolve(failedRequest);
17  });
18
19// Add the interceptor to the Axios instance
20registerAxiosTokenRefresh(apiClient, { refreshRequest: refreshAuthLogic });
21
22// Example API request
23apiClient.get('/protected-resource', {
24  headers: {
25    Authorization: 'Bearer ' + localStorage.getItem('accessToken'),
26  },
27}).then((response) => {
28  console.log('Protected resource data:', response.data);
29}).catch((error) => {
30  console.error('Error fetching protected resource:', error);
31});

Configuration Options

Below is a table describing the available options for configuring token refresh behavior:

Option	Type	Description	Default
refreshRequest	(error: any) => Promise<any>	The function that will be called to refresh the token. It should return a promise.	Required
statusCodes	number[]	(Optional) List of status codes that should trigger a token refresh.	[401]
shouldRetry	(error: AxiosError) => boolean	(Optional) A custom function to determine whether to refresh. If provided, statusCodes will be ignored.	undefined
retryTimes	number	(Optional) The number of times to retry the request.	1
onRetry	(requestConfig: AxiosRequestConfig) => AxiosRequestConfig | Promise<AxiosRequestConfig>	(Optional) A callback function that is called before each refreshRequest. It can modify and return the request configuration.	undefined

Why Use This Package?

• Lightweight: Minimal overhead, designed to integrate seamlessly with Axios.
• Customizable: Configure retry logic, status codes, and token refresh behavior.
• Easy to Use: Simple API for quick integration into your project.
• Reliable: Automatically retries failed requests after token expiration.
• Flexible: Works with any authentication flow, including OAuth and JWT.

Contributing

Contributions are welcome! Please see the CONTRIBUTING.md file for guidelines on how to contribute to this project.

Support

If you encounter any issues or have questions, please open an issue on GitHub or start a discussion in the Discussions section.

License

This project is licensed under the MIT License. See the LICENSE file for details.

axios-token-refresh is a utility for handling token refresh logic in Axios. It is ideal for managing authentication flows, retrying failed requests, and integrating with OAuth or JWT-based systems. Lightweight, customizable, and easy to use.