@metadiv-studio/axios-configurator

A React component package that provides automatic Axios configuration with authentication, retry logic, and internationalization support for MetaDev applications.

🚀 Quick Start

Installation

npm install @metadiv-studio/axios-configurator

Basic Usage

The AxiosConfigurator component must be placed in your app first before any Axios requests are made. This component configures Axios globally with authentication, retry logic, and other essential features.

import AxiosConfigurator from '@metadiv-studio/axios-configurator';

function App() {
  return (
    <>
      {/* Place this component at the top level of your app */}
      <AxiosConfigurator loginRoute="/login" />
      
      {/* Your app components */}
      <YourApp />
    </>
  );
}

📖 Description

The @metadiv-studio/axios-configurator package automatically configures Axios with:

• Authentication: Automatic token injection from localStorage
• Retry Logic: Smart retry mechanism for failed requests
• Token Refresh: Automatic token refresh for expired sessions
• Internationalization: Locale header injection
• Error Handling: Intelligent error handling with user-friendly alerts
• Role-based Authentication: Support for both system admin and system user roles

🔧 Configuration

Required Props

| Prop | Type | Description | Required | |------|------|-------------|----------| | loginRoute | string | The route to redirect users when authentication fails | Yes |

Environment Variables

Set the following environment variable in your .env.local or .env file:

NEXT_PUBLIC_API_HOST=https://your-api-domain.com

🔑 Exported Constants

The package exports several constants that you can use in your application:

Local Storage Keys

import {
  STORAGE_KEY_ACCESS_TOKEN,
  STORAGE_KEY_LOCALE,
  STORAGE_KEY_SYSTEM_ROLE,
  STORAGE_KEY_WORKSPACE_MEMBER
} from '@metadiv-studio/axios-configurator';

// Usage examples:
localStorage.setItem(STORAGE_KEY_ACCESS_TOKEN, 'your-token');
localStorage.setItem(STORAGE_KEY_LOCALE, 'en');
localStorage.setItem(STORAGE_KEY_SYSTEM_ROLE, 'system_user');
localStorage.setItem(STORAGE_KEY_WORKSPACE_MEMBER, JSON.stringify(workspaceData));

| Constant | Value | Description | |----------|-------|-------------| | STORAGE_KEY_ACCESS_TOKEN | "token" | Key for storing authentication token | | STORAGE_KEY_LOCALE | "locale" | Key for storing user locale preference | | STORAGE_KEY_SYSTEM_ROLE | "system_role" | Key for storing user role (system_admin or system_user) | | STORAGE_KEY_WORKSPACE_MEMBER | "workspace_member" | Key for storing workspace member information |

MetaDev Headers

import { METADEV_HEADER_LOCALE } from '@metadiv-studio/axios-configurator';

// This constant is automatically used by the configurator
// Value: "X-Locale"

| Constant | Value | Description | |----------|-------|-------------| | METADEV_HEADER_LOCALE | "X-Locale" | Header key for locale information |

🚨 Important Notes

1. Component Placement

CRITICAL: The AxiosConfigurator component must be rendered before any Axios requests are made. Place it at the top level of your application to ensure proper configuration.

2. Authentication Flow

The configurator automatically:

• Injects the access token from localStorage into all requests
• Refreshes expired tokens automatically
• Redirects to the specified login route on authentication failure

3. Retry Logic

The package includes intelligent retry logic:

• 401/403 errors: Automatic token refresh and retry
• 413 errors: File size validation with user notification
• Public endpoints: No retry for public routes

4. Role-based Token Refresh

• System Admin: Uses admin refresh token endpoint
• System User: Uses user refresh token endpoint with workspace context

📱 Example Implementation

import React from 'react';
import AxiosConfigurator from '@metadiv-studio/axios-configurator';
import axios from 'axios';

function App() {
  const handleApiCall = async () => {
    try {
      // Axios is now automatically configured with authentication
      const response = await axios.get('/api/users');
      console.log(response.data);
    } catch (error) {
      console.error('API call failed:', error);
    }
  };

  return (
    <div>
      {/* Place configurator first */}
      <AxiosConfigurator loginRoute="/auth/login" />
      
      <button onClick={handleApiCall}>
        Make API Call
      </button>
    </div>
  );
}

export default App;

🔒 Security Features

• Automatic Token Injection: All requests automatically include authentication headers
• Secure Token Storage: Uses localStorage for token persistence
• Automatic Logout: Redirects to login on authentication failure
• Role-based Access: Different refresh token endpoints for different user roles

🌐 Internationalization Support

• Locale Header: Automatically injects user locale preference into all requests
• Localized Error Messages: User-friendly error messages in the user's preferred language

📦 Dependencies

This package has the following peer dependencies:

• React ^18
• React DOM ^18

And includes these core dependencies:

• axios ^1.11.0
• axios-retry ^4.5.0

🚀 Getting Started Checklist

1. ✅ Install the package: npm install @metadiv-studio/axios-configurator
2. ✅ Set NEXT_PUBLIC_API_HOST environment variable
3. ✅ Place AxiosConfigurator component at the top of your app
4. ✅ Configure the loginRoute prop
5. ✅ Ensure your app has the required localStorage keys set
6. ✅ Start making Axios requests (they'll be automatically configured!)

🤝 Support

For issues, questions, or contributions, please refer to the package repository or contact the MetaDev Studio team.

Happy coding with automatic Axios configuration! 🎉