create-bluecopa-react-app

# AI Agent Guide for BlueCopa React shadcn/ui Template This guide helps AI assistants and developers understand the project structure, patterns, and best practices for working with this BlueCopa React application template. ## 🏗️ Project Architecture Overview ### Core Stack - **React 18** with TypeScript - **React Router v7** with SSR support - **shadcn/ui** components built on Radix UI - **Tailwind CSS v4** with CSS variables - **Vite 6** for build tooling - **TanStack Query** (via @bluecopa/react) ### Key Directories ``` app/ ├── components/ # Reusable UI components │ ├── ui/ # shadcn/ui components │ ├── app-sidebar.tsx # Main navigation │ ├── data-table.tsx # TanStack Table wrapper │ └── chart-*.tsx # Recharts components ├── hooks/ # Custom React hooks ├── lib/ # Utilities and configurations ├── routes/ # React Router pages └── dashboard/ # Sample data and components ``` ## 🎨 Component Patterns ### shadcn/ui Components All UI components follow shadcn/ui patterns: - Located in `app/components/ui/` - Built on Radix UI primitives - Styled with Tailwind CSS - Use `cn()` utility for class merging - Support dark mode via CSS variables ### Custom Components - Use TypeScript interfaces for props - Follow React best practices (hooks, memo, etc.) - Implement proper accessibility - Use semantic HTML elements ### Example Component Structure ```tsx import { cn } from "~/lib/utils" interface ComponentProps { className?: string children: React.ReactNode } export function Component({ className, children }: ComponentProps) { return ( <div className={cn("base-styles", className)}> {children} </div> ) } ``` ## 🔧 Development Patterns ### State Management - Use React hooks (useState, useReducer, useContext) - TanStack Query for server state - Local state for UI interactions - Avoid prop drilling with context ### Data Fetching - Use `@bluecopa/react` hooks for API calls - Implement loading and error states - Use TanStack Query for caching - Handle optimistic updates ### Styling Guidelines - Use Tailwind CSS classes - Leverage CSS variables for theming - Follow mobile-first responsive design - Use `cn()` utility for conditional classes ## 📊 Data Visualization ### Charts (Recharts) - Interactive charts with hover states - Responsive design - Customizable colors via CSS variables - Accessible with proper ARIA labels ### Tables (TanStack Table) - Sortable columns - Filtering capabilities - Pagination support - Row selection - Custom cell renderers ## 🎯 Common Tasks & Solutions ### Adding New Pages 1. Create route file in `app/routes/` 2. Export default component 3. Add navigation link in sidebar 4. Implement proper TypeScript types ### Adding New Components 1. Create component file in appropriate directory 2. Define TypeScript interface for props 3. Use shadcn/ui components as base 4. Implement responsive design 5. Add proper accessibility attributes ### Working with Forms 1. Use shadcn/ui form components 2. Implement validation with Zod 3. Handle form state with React hooks 4. Show loading and error states 5. Use proper form semantics ### API Integration 1. Use `@bluecopa/react` hooks 2. Handle loading states 3. Implement error boundaries 4. Use TanStack Query for caching 5. Add optimistic updates where appropriate ## 🚀 Performance Optimization ### Code Splitting - Use React.lazy() for route-based splitting - Implement proper loading states - Avoid unnecessary re-renders ### Bundle Optimization - Use Vite's built-in optimizations - Implement proper tree shaking - Optimize images and assets ### Runtime Performance - Use React.memo() for expensive components - Implement proper key props - Avoid inline object/function creation ## 🧪 Testing Strategies ### Component Testing - Test component behavior, not implementation - Use React Testing Library - Mock external dependencies - Test accessibility features ### Integration Testing - Test user workflows - Mock API responses - Test error scenarios - Verify responsive behavior ## 🔒 Security Considerations ### Data Handling - Sanitize user inputs - Validate data on client and server - Use proper TypeScript types - Implement proper error handling ## 📱 Responsive Design ### Breakpoints - Mobile-first approach - Use Tailwind's responsive prefixes - Test on multiple devices - Implement touch-friendly interactions ### Layout Patterns - Use CSS Grid and Flexbox - Implement proper spacing - Handle overflow scenarios - Ensure proper scrolling ## 🌙 Dark Mode Implementation ### Theme System - Use next-themes for theme switching - Implement CSS variables for colors - Test both light and dark modes - Ensure proper contrast ratios ### Component Theming - Use semantic color tokens - Implement proper hover states - Test theme transitions - Ensure accessibility compliance ## 🐛 Debugging Tips ### Common Issues - Check TypeScript errors first - Verify component imports - Check Tailwind class names - Validate API responses ### Development Tools - Use React DevTools - Leverage Vite's HMR - Check browser console - Use TypeScript strict mode ## 📚 Useful Resources ### Documentation - [React Router v7 Docs](https://reactrouter.com/) - [shadcn/ui Components](https://ui.shadcn.com/) - [Tailwind CSS v4](https://tailwindcss.com/) - [TanStack Table](https://tanstack.com/table) - [Recharts](https://recharts.org/) ### BlueCopa Specific - [@bluecopa/react Package](packages/react:1) - BlueCopa Design System - API Integration Patterns ## 🎯 Best Practices Summary 1. **Always use TypeScript** - Define proper interfaces and types 2. **Follow shadcn/ui patterns** - Use established component structure 3. **Implement accessibility** - Use semantic HTML and ARIA attributes 4. **Optimize for performance** - Use proper React patterns and code splitting 5. **Test thoroughly** - Write tests for components and user workflows 6. **Handle errors gracefully** - Implement proper error boundaries and fallbacks 7. **Follow responsive design** - Mobile-first approach with proper breakpoints 8. **Use proper state management** - Choose appropriate patterns for different data types 9. **Implement proper loading states** - Show feedback during async operations 10. **Follow security best practices** - Validate inputs and secure API calls ## 🔄 Common Workflows ### Adding a New Feature 1. Create feature branch 2. Implement components with TypeScript 3. Add proper styling with Tailwind 4. Implement responsive design 5. Add tests 6. Update documentation 7. Test in both light and dark modes ### Debugging Issues 1. Check browser console for errors 2. Verify TypeScript compilation 3. Test component isolation 4. Check API responses 5. Verify responsive behavior 6. Test accessibility features This guide should help AI assistants and developers work effectively with this BlueCopa React template, ensuring consistent patterns and best practices are followed throughout development.