A powerful Axios wrapper with automatic token refresh, HttpOnly cookie support, and Next.js SSR compatibility.
npm install axios-xtraA powerful Axios wrapper with built-in HttpOnly cookie support, automatic token refresh with concurrency handling, and Next.js SSR compatibility.
- π Automatic Token Refresh: Handles 401/expired token errors automatically.
- π€ Concurrency Handling: Queue multiple requests while refreshing tokens to prevent redundant calls.
- πͺ HttpOnly Cookie Support: Built-in support for credentials in browser and SSR environments.
- π Next.js SSR Ready: Easy cookie synchronization for Server Components and getServerSideProps.
- π¦ Unwrap Response: Option to directly return res.data for cleaner code.
- π Retry Mechanism: Automatic retry for network errors.
``bash`axios-xtra ιθ¦δΈ axios δΈθ΅·δ½Ώη¨ (peerDependency)
npm install axios-xtra axiosor
yarn add axios-xtra axios
`typescript
import { createAxiosPlus } from 'axios-xtra';
export const api = createAxiosPlus({
baseURL: 'https://api.example.com',
refreshUrl: '/auth/refresh',
accessExpirationCode: 401,
unwrapResponse: true,
});
// Use it like regular axios
const user = await api.get('/user/profile');
`
Creates an enhanced Axios instance.
| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| baseURL | string | - | The base URL for all requests. |refreshUrl
| | string | - | The endpoint URL to call when a token needs to be refreshed. |accessExpirationCode
| | number \| string | 401 | The error code that triggers a token refresh. |getErrorCode
| | (res) => code | - | Optional. A function to extract a custom error code from the response body if your API returns 200 OK with an error code in the body. |unwrapResponse
| | boolean | false | If true, the promise will resolve with response.data instead of the full Axios response object. |retryCount
| | number | 0 | Number of times to retry a failed request (for transient network errors). |retryDelay
| | number | 1000 | Delay between retries in milliseconds. |timeout
| | number | 10000 | Request timeout in milliseconds. |onBeforeRefresh
| | () => void | - | Callback function executed just before the refresh request starts. |onRefreshFailed
| | (error) => void | - | Callback function executed if the token refresh fails (e.g., to redirect to login). |onLoadingChange
| | (loading) => void | - | Callback triggered whenever the global loading state changes (useful for progress bars). |onError
| | (error) => void | - | A global error handler for all requests. |debug
| | boolean | false | Enables detailed console logging for requests and responses. |cookie
| | string` | - | (Request level) Manually pass a cookie string. Highly useful for Next.js SSR cookie forwarding. |
For more advanced scenarios like Next.js SSR or custom error handling, please refer to the Usage Guide.
MIT