A lightweight Axios helper for managing httpOnly cookies and automatic token refresh with retries in TypeScript.
npm install axios-cookie-authaxios-cookie-auth



axios-cookie-auth is a reusable TypeScript utility that simplifies API interactions by providing an Axios instance configured for HTTP-only cookie support. It includes error handling, token refresh logic, CSRF protection, and customizable logout handling.
To install the package, use npm or yarn:
``bash`
npm install axios-cookie-author
yarn add axios-cookie-auth
- Simplifies API interaction with preconfigured Axios instance.
- Supports HTTP-only cookies for secure authentication.
- Automatically handles token refresh when encountering 401 Unauthorized errors.
- Supports CSRF protection for modifying requests.
- Allows custom headers and logout logic.
`typescript
import { useApi } from 'axios-cookie-auth';
const api = useApi(
'https://api.example.com', // Base URL for API
'/auth/refresh', // Endpoint for token refresh
{ 'Custom-Header': 'value' }, // Optional custom headers
true, // Enable CSRF protection (optional)
() => console.log('Logout triggered!'), // Optional logout handler
);
// Example API call
api
.get('/endpoint')
.then((response) => console.log(response.data))
.catch((error) => console.error(error));
`
#### Parameters
| Name | Type | Required | Description |
| ----------------- | ------------------------ | -------- | ------------------------------------------------------------------------------------- |
| baseURL | string | Yes | The base URL for all API requests. |refreshEndpoint
| | string | Yes | The endpoint used to refresh the authentication token. |headers
| | Record | No | Optional custom headers to include in each request. |useCsrf
| | boolean | No | Whether to include CSRF token protection for modifying requests (default is false). |logoutFn
| | () => void | No | Optional callback function to call when token refresh fails. |
#### Returns
AxiosInstance: A preconfigured Axios instance with interceptors for token refresh, CSRF protection, and error handling.
`typescript
const api = useApi(
'https://myapi.com',
'/refresh',
{ Authorization: 'Bearer token' },
true, // Enable CSRF protection
() => {
console.log('User logged out.');
},
);
api
.post('/data', { key: 'value' })
.then((response) => console.log(response.data))
.catch((error) => console.error(error));
`
- On success: Passes the response back to the calling function.
- On 401 Unauthorized: Automatically triggers the token refresh endpoint and retries the original request.
- On refresh failure: Calls the optional logoutFn if provided, then rejects the error.
- If useCsrf is set to true, the hook will look for a CSRF token stored in localStorage and automatically include it in the request headers as x-xsrf-token.
- This ensures that your API is protected against CSRF attacks when making modifications.
This package is written in TypeScript and provides the following types:
- baseURL: string (Required)refreshEndpoint
- : string (Required)headers
- : Record (Optional)useCsrf
- : boolean (Optional, default is false)logoutFn
- : () => void` (Optional)
See CONTRIBUTING.md for development guidelines.
This project is licensed under the MIT License.