axios-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.

Installation

To install the package, use npm or yarn:

npm install axios-cookie-auth
# or
yarn add axios-cookie-auth

Features

• 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.

Usage

Import and Setup

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));

API

useApi

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<string, string> | 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.

Example

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));

Interceptor Behavior

• 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.

CSRF Protection

• 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.

Types

This package is written in TypeScript and provides the following types:

• baseURL: string (Required)
• refreshEndpoint: string (Required)
• headers: Record<string, string> (Optional)
• useCsrf: boolean (Optional, default is false)
• logoutFn: () => void (Optional)

Contributing

See CONTRIBUTING.md for development guidelines.

License

This project is licensed under the MIT License.