🛠️ Reusable React Toolkit

A comprehensive collection of modular, reusable React features built with TypeScript, Tailwind CSS, Zod, React Query, and Zustand. Copy-paste ready components for authentication, real-time chat, user profiles, and payment processing.

📦 Modules

This toolkit contains four fully-featured, production-ready modules:

🔐 Auth Module

Complete authentication system with login, signup, password reset, and protected routes.

Features:

• User login and signup
• Password reset functionality
• Protected routes
• Form validation with Zod
• State management with Zustand
• API integration with React Query
• Fully typed with TypeScript

Quick Example:

import { AuthProvider, LoginForm, ProtectedRoute } from './auth';

function App() {
  return (
    <AuthProvider>
      <ProtectedRoute>
        <Dashboard />
      </ProtectedRoute>
    </AuthProvider>
  );
}

💬 Chat Module

Real-time chat system with WebSocket support, multiple rooms, and typing indicators.

Features:

• Real-time messaging with WebSocket
• Multiple chat rooms (direct, group, channel)
• Typing indicators
• Online/offline status
• Message history with pagination
• Unread message counts

Quick Example:

import { ChatProvider, ChatRoom, ChatRoomList } from './chat';

function App() {
  return (
    <ChatProvider wsUrl="ws://localhost:8080/chat">
      <ChatRoomList rooms={rooms} />
      <ChatRoom room={selectedRoom} />
    </ChatProvider>
  );
}

👤 Profile Module

User profile management with view, edit, avatar upload, and preferences.

Features:

• View and edit user profile
• Avatar and cover image upload
• Social links management
• Preferences and privacy settings
• Form validation

Quick Example:

import { ProfilePage, useCurrentProfile } from './profile';

function MyProfile() {
  return <ProfilePage currentUserId={user?.id} />;
}

💳 Payment Module

Payment processing system with card support, payment history, and subscription management.

Features:

• Process payments with card or saved methods
• Save and manage payment methods
• Payment history
• Invoice management
• Subscription management
• Card validation (Luhn algorithm)

Quick Example:

import { PaymentForm, PaymentHistory } from './payment';

function Checkout() {
  return (
    <PaymentForm
      defaultAmount={99.99}
      onSuccess={(payment) => console.log('Success!', payment)}
    />
  );
}

🚀 Quick Start

Installation

Each module is independent. Install the dependencies you need:

# For all modules
npm install @tanstack/react-query zustand zod react-hook-form @hookform/resolvers

# Optional: Better date formatting for chat module
npm install date-fns

Basic Setup

1. Choose your modules - Copy the folders you need into your project
2. Install dependencies - See each module's package.example.json
3. Configure APIs - Update service files with your backend URLs
4. Wrap your app - Add providers where needed

Example with all modules:

import { AuthProvider } from './auth';
import { ChatProvider } from './chat';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <AuthProvider>
        <ChatProvider wsUrl="ws://localhost:8080/chat">
          <YourApp />
        </ChatProvider>
      </AuthProvider>
    </QueryClientProvider>
  );
}

📚 Module Documentation

Each module has comprehensive documentation:

• Auth Module: See auth/README.md and auth/QUICKSTART.md
• Chat Module: See chat/README.md and chat/QUICKSTART.md
• Profile Module: See profile/README.md and profile/QUICKSTART.md
• Payment Module: See payment/README.md and payment/QUICKSTART.md

🎯 Tech Stack

All modules use the same technology stack for consistency:

• React 18+ - UI library
• TypeScript - Type safety
• Tailwind CSS - Styling
• Zod - Schema validation
• React Query - Data fetching and caching
• Zustand - State management
• React Hook Form - Form handling

📁 Project Structure

toolkit/
├── auth/              # Authentication module
│   ├── components/    # React components
│   ├── hooks/         # React Query hooks
│   ├── schemas/       # Zod validation schemas
│   ├── services/      # API service layer
│   ├── store/         # Zustand state store
│   └── types/         # TypeScript types
│
├── chat/              # Real-time chat module
│   ├── components/
│   ├── hooks/
│   ├── services/      # API + WebSocket services
│   └── ...
│
├── profile/           # Profile management module
│   └── ...
│
├── payment/           # Payment processing module
│   └── ...
│
└── README.md          # This file

🔧 Configuration

Environment Variables

Each module can be configured via environment variables or direct configuration:

Auth Module:

VITE_API_URL=https://api.yourdomain.com

Chat Module:

VITE_WS_URL=wss://yourdomain.com/chat
VITE_API_URL=https://api.yourdomain.com

Profile & Payment Modules:

VITE_API_URL=https://api.yourdomain.com

API Configuration

Update the API base URLs in each module's service file:

• auth/services/authService.ts
• chat/services/chatService.ts
• profile/services/profileService.ts
• payment/services/paymentService.ts

Or use the exported setters:

import { setApiBaseUrl as setAuthApiBaseUrl } from './auth';
import { setApiBaseUrl as setChatApiBaseUrl } from './chat';

setAuthApiBaseUrl('https://api.yourdomain.com');
setChatApiBaseUrl('https://api.yourdomain.com');

🎨 Styling

All modules use Tailwind CSS for styling. Components are fully customizable:

1. Override with props - Pass custom className props
2. Modify components - Edit the component files directly
3. Tailwind config - Customize the design system

📝 Usage Examples

Complete Application Example

import { AuthProvider, ProtectedRoute } from './auth';
import { ChatProvider } from './chat';
import { ProfilePage } from './profile';
import { PaymentForm } from './payment';

function App() {
  return (
    <AuthProvider>
      <ChatProvider wsUrl={import.meta.env.VITE_WS_URL}>
        <Routes>
          <Route path="/login" element={<LoginPage />} />
          <Route
            path="/dashboard"
            element={
              <ProtectedRoute>
                <Dashboard />
              </ProtectedRoute>
            }
          />
          <Route path="/profile" element={<ProfilePage />} />
          <Route path="/checkout" element={<PaymentForm />} />
        </Routes>
      </ChatProvider>
    </AuthProvider>
  );
}

🔒 Security Considerations

Authentication

• Tokens are stored in localStorage (customize for your needs)
• All API requests include authentication headers
• Protected routes check authentication status

Payments

• ⚠️ CRITICAL: This module handles UI only
• Your backend MUST use a PCI-compliant payment processor
• Never store full card numbers in your database
• All payment processing should be done server-side
• Use HTTPS for all payment transactions

Chat

• WebSocket connections should be secured (WSS)
• Authenticate WebSocket connections with tokens
• Validate all messages server-side

🧪 Testing

Each module is designed to be testable:

import { render, screen } from '@testing-library/react';
import { LoginForm } from './auth';

test('renders login form', () => {
  render(<LoginForm />);
  expect(screen.getByLabelText(/email/i)).toBeInTheDocument();
});

🚀 Migration Guide

To use these modules in your project:

1. Copy the module folder(s) to your project
2. Install dependencies listed in each module's package.example.json
3. Configure API endpoints in the service files
4. Customize types to match your backend API
5. Update styling if needed (Tailwind config)
6. Start using the components and hooks!

Each module is completely independent - use only what you need!

📦 Module Dependencies

All modules share these core dependencies:

{
  "@tanstack/react-query": "^5.17.9",
  "zustand": "^4.4.7",
  "zod": "^3.22.4",
  "react-hook-form": "^7.49.3",
  "@hookform/resolvers": "^3.3.4"
}

Optional dependencies:

• date-fns - Better date formatting (used in chat module)

🎓 Learning Resources

Each module includes:

• Comprehensive README with full documentation
• Quick Start guide for 5-minute setup
• Example implementations
• Type definitions with JSDoc comments
• Configuration guides

🤝 Contributing

This is a reusable toolkit. Feel free to:

• Copy modules into your projects
• Modify them to fit your needs
• Extend functionality as required
• Share improvements back to the community

📄 License

These modules are provided as-is for reuse in your projects. Each module is designed to be:

• ✅ Modular and independent
• ✅ Fully typed with TypeScript
• ✅ Well-documented
• ✅ Production-ready
• ✅ Copy-paste friendly

🔗 Module Links

• Auth Module Documentation
• Chat Module Documentation
• Profile Module Documentation
• Payment Module Documentation

💡 Tips

1. Start Small - Begin with one module (usually Auth)
2. Read the Docs - Each module has detailed README
3. Check Examples - Look at the examples/ folder in each module
4. Customize - Modify components to match your design system
5. Test - Ensure API endpoints match your backend

🆘 Troubleshooting

Common Issues

Module not found errors:

• Ensure all dependencies are installed
• Check import paths are correct

API connection issues:

• Verify API base URLs are configured correctly
• Check CORS settings on your backend
• Ensure authentication tokens are valid

WebSocket connection fails:

• Check WebSocket URL is correct
• Verify WSS for production (not WS)
• Check authentication token is passed

Payment processing issues:

• Remember: This is UI only - backend must handle payments
• Use a PCI-compliant payment processor
• Never store card details

For module-specific issues, check each module's README.md file.

---

Happy coding! 🚀

For detailed documentation, see each module's README.md file.