React Components Library

A professional, modular React component library designed for large-scale applications with modern tooling. Built with Zod, React Query, React Hook Form, and Shadcn/ui for the best developer experience.

✨ Modern Stack

• 🎯 Zod - Type-safe validation schemas
• 🚀 React Query - Powerful data fetching & caching
• 📝 React Hook Form - Performant forms with easy validation
• 🎨 Shadcn/ui - Beautiful, accessible UI components
• 🌙 Dark Mode - Built-in theme system
• 📱 Responsive - Mobile-first design
• ⚡ Tree-shakable - Import only what you need

🏗️ Architecture

This package follows a domain-driven design with clear separation of concerns:

• Features: Domain-specific modules (auth, dashboard, profile, etc.)
• Shared Components: Reusable UI components
• Hooks: Custom React hooks for common functionality
• Contexts: Application-wide state management
• Utils: Helper functions and utilities
• Types: TypeScript definitions
• Constants: Application constants
• Styles: Theme and styling definitions

📁 Folder Structure

src/
├── index.jsx                    # Main export hub
├── features/                    # Domain-specific features
│   ├── auth/                   # Authentication feature
│   │   ├── components/         # Feature-specific components
│   │   │   ├── LoginForm.jsx
│   │   │   ├── SignupForm.jsx
│   │   │   └── AuthLayout.jsx
│   │   ├── hooks/              # Feature-specific hooks
│   │   │   ├── useAuth.js
│   │   │   ├── useLogin.js
│   │   │   └── useSignup.js
│   │   ├── context/            # Feature-specific contexts
│   │   │   └── AuthContext.jsx
│   │   ├── utils/              # Feature-specific utilities
│   │   │   ├── authHelpers.js
│   │   │   └── validation.js
│   │   ├── types/              # Feature-specific types
│   │   │   └── auth.types.js
│   │   ├── constants/          # Feature-specific constants
│   │   │   └── authConstants.js
│   │   └── index.js            # Feature export hub
│   ├── dashboard/              # Dashboard feature
│   ├── profile/                # Profile feature
│   └── settings/               # Settings feature
├── components/                  # Shared components
│   ├── ui/                     # Basic UI components
│   │   ├── Button/
│   │   │   ├── Button.jsx
│   │   │   ├── Button.css
│   │   │   └── index.js
│   │   ├── Input/
│   │   ├── Modal/
│   │   └── index.js
│   ├── layout/                 # Layout components
│   ├── forms/                  # Form components
│   ├── data-display/           # Data display components
│   ├── feedback/               # Feedback components
│   ├── navigation/             # Navigation components
│   ├── media/                  # Media components
│   └── index.js
├── hooks/                      # Shared custom hooks
│   ├── useLocalStorage.js
│   ├── useDebounce.js
│   ├── useToggle.js
│   └── index.js
├── contexts/                   # Shared contexts
│   ├── ThemeContext.jsx
│   ├── NotificationContext.jsx
│   └── index.js
├── utils/                      # Utility functions
│   ├── validation.js
│   ├── string.js
│   ├── date.js
│   └── index.js
├── types/                      # TypeScript definitions
│   ├── common.types.js
│   ├── component.types.js
│   └── index.js
├── constants/                  # Application constants
│   ├── ui.js
│   ├── api.js
│   └── index.js
└── styles/                     # Styling and themes
    ├── theme.js
    ├── tokens.js
    └── index.js

🚀 Installation

npm install @your-org/react-components

🚀 Quick Start

1. Installation

npm install @your-org/react-components

2. Setup Providers

import { QueryProvider, ThemeProvider } from '@your-org/react-components'

function App() {
  return (
    <QueryProvider>
      <ThemeProvider>
        <YourApp />
      </ThemeProvider>
    </QueryProvider>
  )
}

3. Use Components

import { 
  Button, 
  LoginForm, 
  useAuth, 
  useForm, 
  zodResolver, 
  z 
} from '@your-org/react-components'

// Define validation schema
const schema = z.object({
  name: z.string().min(2, 'Name required'),
  email: z.string().email('Invalid email'),
})

function MyForm() {
  const form = useForm({
    resolver: zodResolver(schema),
    defaultValues: { name: '', email: '' }
  })

  return (
    <form onSubmit={form.handleSubmit(console.log)}>
      <Button type="submit">Submit</Button>
    </form>
  )
}

📖 Detailed Setup

👉 Complete Setup Guide - Step-by-step instructions with examples

Feature-Specific Imports

// Import entire feature
import { LoginForm, useAuth, AuthProvider } from '@your-org/react-components';

// Or import from specific feature (tree-shaking friendly)
import { LoginForm } from '@your-org/react-components/features/auth';
import { useAuth } from '@your-org/react-components/hooks';

Component Categories

UI Components

import { 
  Button, 
  Input, 
  Modal, 
  Card, 
  Badge 
} from '@your-org/react-components';

Hooks

import { 
  useLocalStorage, 
  useDebounce, 
  useToggle 
} from '@your-org/react-components';

Contexts

import { 
  ThemeProvider, 
  useTheme,
  AuthProvider 
} from '@your-org/react-components';

🎨 Theming

import { ThemeProvider, useTheme } from '@your-org/react-components';

function App() {
  return (
    <ThemeProvider defaultTheme="system">
      <MyApp />
    </ThemeProvider>
  );
}

function MyComponent() {
  const { theme, setTheme, isDark } = useTheme();
  
  return (
    <button onClick={() => setTheme(isDark ? 'light' : 'dark')}>
      Toggle theme
    </button>
  );
}

🔧 Development

Setup

# Install dependencies
npm install

# Start development
npm run dev

# Run tests
npm test

# Build package
npm run build

# Lint code
npm run lint

Adding New Features

1. Create feature folder in src/features/
2. Add components, hooks, context, utils as needed
3. Create feature index.js to export all modules
4. Add feature export to main src/index.jsx

Example new feature structure:

src/features/my-feature/
├── components/
│   └── MyComponent.jsx
├── hooks/
│   └── useMyHook.js
├── context/
│   └── MyContext.jsx
├── utils/
│   └── myHelpers.js
└── index.js

Adding Shared Components

1. Create component folder in src/components/ui/
2. Add component file and styles
3. Create component index.js
4. Export from src/components/ui/index.js
5. Export from main src/components/index.js

📦 Build Output

The package builds to both CommonJS and ES modules:

• dist/index.js - CommonJS build
• dist/index.esm.js - ES modules build
• dist/index.d.ts - TypeScript definitions

🌳 Tree Shaking

This package is optimized for tree shaking. Import only what you need:

// ✅ Good - only imports Button
import { Button } from '@your-org/react-components';

// ❌ Avoid - imports everything
import * as Components from '@your-org/react-components';

🧪 Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm test -- --coverage

📝 Contributing

1. Follow the established folder structure
2. Write tests for new components/hooks
3. Update documentation
4. Follow ESLint rules
5. Use TypeScript where applicable

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• GitHub Repository
• Documentation
• NPM Package