create-bluecopa-react-app 1.0.4 → 1.0.6

package/templates/latest/Agent.md

@@ -0,0 +1,254 @@
+# 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.

package/templates/latest/Dockerfile

@@ -0,0 +1,22 @@
+FROM node:20-alpine AS development-dependencies-env
+COPY . /app
+WORKDIR /app
+RUN npm ci
+
+FROM node:20-alpine AS production-dependencies-env
+COPY ./package.json package-lock.json /app/
+WORKDIR /app
+RUN npm ci --omit=dev
+
+FROM node:20-alpine AS build-env
+COPY . /app/
+COPY --from=development-dependencies-env /app/node_modules /app/node_modules
+WORKDIR /app
+RUN npm run build
+
+FROM node:20-alpine
+COPY ./package.json package-lock.json /app/
+COPY --from=production-dependencies-env /app/node_modules /app/node_modules
+COPY --from=build-env /app/build /app/build
+WORKDIR /app
+CMD ["npm", "run", "start"]