react-cookie-auth

A secure authentication library for React applications that implements HTTP-only cookie-based authentication with automatic token refresh, Page Visibility API integration, and Redux state management.

Table of Contents

• Key Features
• Installation
• Quick Start
• Configuration
• Components
• API Reference
• Security Benefits
• Comparison with Other Solutions
• Advanced Usage
• Troubleshooting
• Storybook
• License

Key Features

• Secure Authentication: HTTP-only cookie-based auth that mitigates XSS attacks
• Complete Flow: Login, logout, and token refresh functionality out of the box
• Sleep/Wake Protection: Page Visibility API integration prevents refresh token storms
• State Management: Redux integration with useful selectors and actions
• UI Components: Ready-to-use auth modals with customization options
• Developer Experience: TypeScript support and comprehensive documentation

Installation

npm install react-cookie-auth

Quick Start

import { Auth, AuthModal, LogoutModal, initAuth } from 'react-cookie-auth';
import React from 'react';
import { Provider } from 'react-redux';

// Step 1: Initialize the auth library with your API endpoints
const { store, hooks, actions, selectors } = initAuth({
  apiBaseUrl: 'https://api.example.com',
  loginEndpoint: '/auth/login/', // Your login endpoint
  refreshTokenEndpoint: '/auth/token/refresh/', // Token refresh endpoint
  logoutEndpoint: '/auth/logout/', // Logout endpoint
  refreshTokenInterval: 15 * 60 * 1000, // Refresh every 15 minutes
  maxRetryAttempts: 3, // Max retry attempts on failure
  retryDelay: 1000, // Delay between retries
  onLoginSuccess: user => console.log('User logged in', user),
  onLogoutSuccess: () => console.log('User logged out'),
  onAuthError: error => console.error('Auth error', error),
});

// Step 2: Use in your app component
function App() {
  // Extract hooks for auth operations
  const { useRefreshToken, useLoginMutation, useLogoutMutation } = hooks;
  const [loginMutation] = useLoginMutation();
  const [logoutMutation] = useLogoutMutation();
  const [refreshTokenMutation] = useRefreshTokenMutation();

  // Create the refresh function using the hook
  const refreshFunction = useRefreshToken(refreshTokenMutation);

  return (
    <Provider store={store}>
      {/* Step 3: Add Auth wrapper to manage token refresh */}
      <Auth
        refreshFunction={refreshFunction}
        refreshInterval={15 * 60 * 1000}
        onAuthStateChange={isLoggedIn => console.log('Auth state changed', isLoggedIn)}
      >
        {/* Step 4: Use auth modals where needed */}
        <AuthModal
          isOpen={showLoginModal}
          onClose={() => setShowLoginModal(false)}
          onSubmit={credentials => loginMutation(credentials)}
          config={{
            title: 'Login to Your Account',
            submitButtonText: 'Login',
          }}
        />

        <LogoutModal
          isOpen={showLogoutModal}
          onClose={() => setShowLogoutModal(false)}
          onLogout={() => logoutMutation()}
          config={{
            title: 'Logout',
            message: 'Are you sure you want to logout?',
            confirmButtonText: 'Yes, logout',
            cancelButtonText: 'Cancel',
          }}
        />

        {/* Your app content */}
      </Auth>
    </Provider>
  );
}

Configuration

The initAuth function accepts the following configuration options:

| Option | Type | Description | | -------------------- | -------- | -------------------------------------------------- | | apiBaseUrl | string | Base URL for API requests | | loginEndpoint | string | Endpoint for login requests | | refreshTokenEndpoint | string | Endpoint for refresh token requests | | logoutEndpoint | string | Endpoint for logout requests | | refreshTokenInterval | number | Interval in milliseconds between token refreshes | | maxRetryAttempts | number | Maximum number of retry attempts for token refresh | | retryDelay | number | Delay between retry attempts in milliseconds | | onLoginSuccess | function | Callback function when login is successful | | onLogoutSuccess | function | Callback function when logout is successful | | onAuthError | function | Callback function when auth error occurs |

Components

Auth

The main authentication component that handles token refresh logic and Page Visibility API integration.

<Auth
  refreshFunction={refreshFunction} // Function to refresh the token
  refreshInterval={refreshInterval} // How often to refresh (ms)
  onAuthStateChange={handleAuthStateChange} // Called when auth state changes
  invalidateAuthTags={invalidateTags} // Optional: refresh cached data
>
  {children}
</Auth>

AuthModal

A modal component for login/signup forms.

<AuthModal
  isOpen={isOpen} // Controls visibility
  onClose={handleClose} // Called when modal is closed
  onSubmit={handleSubmit} // Called with form data on submit
  config={{
    // Customize appearance
    title: 'Login',
    submitButtonText: 'Submit',
  }}
/>

LogoutModal

A modal component for confirming logout actions.

<LogoutModal
  isOpen={isOpen} // Controls visibility
  onClose={handleClose} // Called when modal is closed
  onLogout={handleLogout} // Called when logout is confirmed
  config={{
    // Customize appearance
    title: 'Logout',
    message: 'Are you sure?',
    confirmButtonText: 'Yes',
    cancelButtonText: 'No',
  }}
/>

API Reference

Hooks

• useRefreshToken: Creates a function to refresh the authentication token
• useLoginMutation: RTK Query hook for login requests
• useLogoutMutation: RTK Query hook for logout requests
• useRefreshTokenMutation: RTK Query hook for refresh token requests

Actions

• setUser: Redux action to set the current user in the store

Selectors

• isAuthenticated: Selector to check if the user is authenticated
• getUser: Selector to get the current user from the store

Security Benefits

• HTTP-Only Cookies: Prevents JavaScript from accessing authentication tokens, protecting against XSS attacks
• Automatic Token Refresh: Maintains authentication state securely without user intervention
• Page Visibility Handling: Prevents refresh token storms after device sleep/wake cycles
• Secure State Management: Integrates with Redux for predictable state management
• No Local Storage: Avoids storing sensitive auth information in vulnerable browser storage

Comparison with Other Solutions

| Feature | react-cookie-auth | JWT in localStorage | Auth0/Okta | | ------------------------- | ----------------- | ------------------- | ----------- | | XSS Protection | ✅ High | ❌ Low | ✅ High | | Automatic Token Refresh | ✅ Built-in | ⚠️ Manual | ✅ Built-in | | Sleep/Wake Cycle Handling | ✅ Built-in | ❌ None | ⚠️ Varies | | Implementation Complexity | Medium | Low | High | | External Service Required | ❌ No | ❌ No | ✅ Yes |

Advanced Usage

Custom Auth Components

You can create custom authentication components by using the hooks and actions provided by the library:

import { initAuth } from 'react-cookie-auth';
import { useSelector } from 'react-redux';

const { hooks, actions, selectors } = initAuth({
  // configuration
});

function CustomLoginForm() {
  const [loginMutation, { isLoading, error }] = hooks.useLoginMutation();

  const handleSubmit = async event => {
    event.preventDefault();
    const username = event.target.username.value;
    const password = event.target.password.value;

    try {
      await loginMutation({ username, password }).unwrap();
    } catch (error) {
      console.error('Login failed', error);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input name="username" type="text" placeholder="Username" />
      <input name="password" type="password" placeholder="Password" />
      <button type="submit" disabled={isLoading}>
        {isLoading ? 'Logging in...' : 'Login'}
      </button>
      {error && <div className="error">{error.message}</div>}
    </form>
  );
}

Troubleshooting

Common Issues

• Token Not Refreshing: Ensure your backend supports the refresh token endpoint and returns proper HTTP-only cookies.

• Authentication State Lost: Check if SameSite and Secure attributes are set correctly on your cookies.

• CORS Issues: Your backend needs to allow credentials and have proper CORS headers set.

  Access-Control-Allow-Credentials: true
  Access-Control-Allow-Origin: https://yourdomain.com

• Redux Integration: If using with existing Redux store, make sure to properly combine the auth reducer with your application's reducers.

Storybook

This library includes a Storybook setup to showcase and document the components.

Running Storybook

npm run storybook

This will launch Storybook on http://localhost:6006 where you can browse and interact with all the components.

Documented Components

• Auth: Authentication wrapper component with different configurations
• AuthModal: Login form modal with various states and styling options
• LogoutModal: Logout confirmation modal with different configurations

Building Storybook

To build a static version of Storybook for deployment:

npm run build-storybook

License

MIT