create-bluecopa-react-app 1.0.2 → 1.0.3

package/README.md

@@ -4,10 +4,11 @@ A CLI tool to bootstrap modern React applications for BlueCopa with built-in UI
 
 ## Features
 
-- 🚀 **Modern React Stack**: React 18, TypeScript, React Router v6, Vite
+- 🚀 **Modern React Stack**: React 18, TypeScript, React Router v6, Vite 7
+- 🌐 **Microfrontend Support**: Single-spa compatible with module federation
 - 📊 **Data Visualization**: Recharts integration for charts and analytics
 - 🎨 **UI Components**: Radix UI primitives with custom styling
-- 📡 **BlueCopa React Components**: Pre-configured @bluecopa/react package with hooks
+- 📡 **BlueCopa React Components**: Pre-configured @bluecopa/react package with hooks (includes TanStack Query integration)
 - 🎯 **Type Safety**: Full TypeScript support
 - 📱 **Responsive Design**: Tailwind CSS with mobile-first approach and BlueCopa design system
 - 🛠️ **Development Tools**: ESLint, TypeScript checking, and Vite fast build system
@@ -62,17 +63,31 @@ A foundational template that provides:
 "typescript": "^5.6.0"
 
 // UI and Styling
-"@radix-ui/*": "Latest versions"
+"@radix-ui/react-avatar": "^1.1.0"
+"@radix-ui/react-dropdown-menu": "^2.1.0"
+"@radix-ui/react-select": "^2.1.0"
+"@radix-ui/react-separator": "^1.1.0"
+"@radix-ui/react-slot": "^1.1.0"
+"@radix-ui/react-tabs": "^1.1.0"
 "tailwindcss": "^3.4.17"
 "lucide-react": "^0.445.0"
+"class-variance-authority": "^0.7.0"
+"clsx": "^2.1.0"
+"tailwind-merge": "^2.5.0"
+"tailwindcss-animate": "^1.0.7"
 
 // Data Visualization
 "recharts": "^2.12.0"
 
+// Microfrontend
+"single-spa": "^6.0.3"
+"single-spa-react": "^6.0.2"
+
 // Development and Build
-"vite": "^5.4.20"
+"vite": "^7.1.5"
 "eslint": "^8.57.0"
-"@vitejs/plugin-react": "^4.3.0"
+"@vitejs/plugin-react-swc": "^4.0.1"
+"@originjs/vite-plugin-federation": "^1.4.1"
 ```
 
 ## Project Structure
@@ -93,15 +108,16 @@ my-bluecopa-app/
 │   │   ├── Home.tsx        # Home page component
 │   │   └── Dashboard.tsx   # Dashboard page component
 │   ├── providers/          # React context providers
-│   │   └── query-provider.tsx  # TanStack Query provider
+│   │   └── query-provider.tsx  # TanStack Query provider via @bluecopa/react
 │   ├── types/              # TypeScript type definitions
 │   ├── App.tsx             # Main app component with routing
 │   ├── main.tsx            # Application entry point
+│   ├── single-spa.tsx      # Single-spa root component
 │   └── index.css           # Global styles and Tailwind imports
 ├── public/                 # Static assets
 ├── .env.example            # Environment variables template
 ├── package.json            # Dependencies and scripts
-├── vite.config.ts          # Vite configuration
+├── vite.config.ts          # Vite configuration with module federation
 ├── tailwind.config.js      # Tailwind CSS configuration
 ├── tsconfig.json           # TypeScript configuration
 ├── postcss.config.js       # PostCSS configuration
@@ -217,15 +233,19 @@ Required environment variables:
 VITE_BLUECOPA_API_TOKEN=your-bluecopa-api-token
 VITE_BLUECOPA_API_URL=https://develop.bluecopa.com/api/v1
 VITE_BLUECOPA_WORKSPACE_ID=your-workspace-id
+- **Vite Module Federation** - For microfrontend integration
 ```
 
 ## Available Scripts
 
 - `npm run dev` - Start Vite development server with hot reload
 - `npm run build` - Build for production (TypeScript + Vite optimization)
+- `npm run start` - Start production build locally
 - `npm run preview` - Preview production build locally
 - `npm run lint` - Run ESLint for code quality
+- `npm run lint:fix` - Fix linting issues
 - `npm run type-check` - Run TypeScript type checking without emitting files
+- `npm run clean` - Clean build artifacts and dependencies
 
 ## Technologies Used
 
@@ -233,9 +253,9 @@ VITE_BLUECOPA_WORKSPACE_ID=your-workspace-id
 - **React Router v6** - Declarative routing for React SPAs
 - **Vite** - Fast build tool and development server
 - **TypeScript** - Full type safety and developer experience
-- **@bluecopa/react** - BlueCopa-specific React components and hooks
-- **TanStack Query** - Powerful data synchronization for React
+- **@bluecopa/react** - BlueCopa-specific React components and hooks (includes TanStack Query)
 - **Radix UI** - Unstyled, accessible UI primitives
+- **Single-spa** - Microfrontend framework support
 - **Recharts** - Composable charting library for React
 - **Tailwind CSS** - Utility-first CSS framework with BlueCopa design system
 - **Lucide React** - Beautiful, customizable icons

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bluecopa-react-app",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "CLI tool to create bluecopa React applications",
   "main": "./bin/create-bluecopa-react-app.js",
   "bin": {
@@ -37,4 +37,4 @@
   "engines": {
     "node": ">=18.0.0"
   }
-}
+}

package/templates/latest/Agent.md

@@ -12,7 +12,7 @@ This template is designed to work seamlessly with AI coding assistants for rapid
 - **Frontend**: React 18 + TypeScript + React Router v6
 - **Build Tool**: Vite (fast HMR and building)
 - **Styling**: TailwindCSS with BlueCopa design system
-- **UI Components**: Radix UI primitives
+- **UI Components**: Radix UI primitives (add via shadcn-ui for pre-styled components)
 - **Data Fetching**: TanStack Query with @bluecopa/react hooks
 - **Charts**: Recharts for data visualization
 - **Icons**: Lucide React
@@ -20,13 +20,13 @@ This template is designed to work seamlessly with AI coding assistants for rapid
 ### Key Directories
 ```
 src/
-├── components/ui/       # Reusable UI components (Button, Card, etc.)
-├── components/         # Business logic components (Navbar, etc.)
-├── hooks/             # Custom React hooks and API integration
+├── components/ui/       # Reusable UI components (e.g., Button, Card via shadcn-ui; bluecopa-logo)
+├── components/         # Business logic components (Navbar, DashboardLayout, etc.)
+├── hooks/             # Custom React hooks (if needed; primarily use @bluecopa/react)
 ├── pages/             # Route components (Home, Dashboard)
-├── providers/         # React context providers
-├── lib/               # Utility functions and helpers
-└── types/             # TypeScript type definitions
+├── providers/         # React context providers (e.g., QueryProvider)
+├── lib/               # Utility functions and helpers (e.g., utils.ts with cn)
+└── types/             # TypeScript type definitions (e.g., api.ts)
 ```
 
 ## 🔧 Development Patterns
@@ -38,8 +38,13 @@ When asked to create a new page:
 1. **Create the page component** in `src/pages/NewPage.tsx`:
 ```tsx
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { useUser } from '@bluecopa/react';
 
 export default function NewPage() {
+  const { data: userData, isLoading } = useUser();
+
+  if (isLoading) return <div>Loading...</div>;
+
   return (
     <div className="container mx-auto py-6">
       <Card>
@@ -48,6 +53,7 @@ export default function NewPage() {
         </CardHeader>
         <CardContent>
           {/* Page content */}
+          <p>Welcome, {userData?.name}!</p>
         </CardContent>
       </Card>
     </div>
@@ -63,8 +69,10 @@ import NewPage from '@/pages/NewPage';
 <Route path="/new-page" element={<NewPage />} />
 ```
 
-3. **Update navigation** in `src/components/navbar.tsx`:
+3. **Update navigation** in `src/components/page/navbar.tsx` (import icon from lucide-react):
 ```tsx
+import { Settings } from 'lucide-react';
+
 const navigation = [
   // ... existing routes
   { name: 'New Page', href: '/new-page', icon: Settings },
@@ -73,30 +81,38 @@ const navigation = [
 
 ### 2. Using BlueCopa API Hooks
 
-Always use the pre-configured hooks from `@/hooks/use-api.ts`:
+Install @bluecopa/react if not present: `npm install @bluecopa/react`
+
+Use the pre-configured hooks from `@bluecopa/react`:
 
 ```tsx
-import { useUserData, useMetricDataDemo, useDatasetDataDemo } from '@/hooks/use-api';
+import { useUser, useMetric, useDataset } from '@bluecopa/react';
 
 function DataComponent() {
-  const { data: userData, isLoading, error } = useUserData();
-  const { data: metrics } = useMetricDataDemo();
+  const { data: userData, isLoading: userLoading, error: userError } = useUser();
+  const { data: metrics } = useMetric({ metricId: 'example' });
+  const { data: datasets } = useDataset({ datasetId: 'example' });
   
-  if (isLoading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error.message}</div>;
+  if (userLoading) return <div>Loading...</div>;
+  if (userError) return <div>Error: {userError.message}</div>;
   
   return <div>Data: {JSON.stringify(userData)}</div>;
 }
 ```
 
+For custom hooks, create in `src/hooks/` and wrap TanStack Query.
+
 ### 3. UI Component Patterns
 
+Add shadcn-ui components if needed: `npx shadcn-ui@latest add card button tabs`
+
 Use the existing UI components from `src/components/ui/`:
 
 ```tsx
 import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
+import { cn } from '@/lib/utils';
 
 // Example usage
 <Card>
@@ -104,7 +120,7 @@ import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
     <CardTitle>Dashboard</CardTitle>
   </CardHeader>
   <CardContent>
-    <Tabs defaultValue="overview">
+    <Tabs defaultValue="overview" className={cn("w-full")}>
       <TabsList>
         <TabsTrigger value="overview">Overview</TabsTrigger>
         <TabsTrigger value="analytics">Analytics</TabsTrigger>
@@ -119,12 +135,20 @@ import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
 
 ### 4. Chart Integration
 
+Install Recharts if not present: `npm install recharts`
+
 Use Recharts for data visualization:
 
 ```tsx
 import { LineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer } from 'recharts';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 
-function ChartComponent({ data }: { data: any[] }) {
+interface ChartData {
+  name: string;
+  value: number;
+}
+
+function ChartComponent({ data }: { data: ChartData[] }) {
   return (
     <Card>
       <CardHeader>
@@ -177,27 +201,28 @@ function ChartComponent({ data }: { data: any[] }) {
 ## 🛠️ Common Tasks for Agents
 
 ### Adding a New Dashboard Card
-1. Create component in appropriate location
-2. Use Card component wrapper
-3. Include loading and error states
-4. Use BlueCopa hooks for data
+1. Create component in `src/components/` (e.g., NewCard.tsx)
+2. Use Card component wrapper from ui/
+3. Include loading and error states with TanStack Query
+4. Use @bluecopa/react hooks for data (e.g., useMetric)
 
 ### Creating Forms
-1. Use Radix UI form components
-2. Add TypeScript types for form data
-3. Include validation and error handling
+1. Use Radix UI form components (add via shadcn-ui: `npx shadcn-ui@latest add form`)
+2. Add TypeScript types for form data in `src/types/`
+3. Include validation with Zod and error handling
 4. Follow BlueCopa styling patterns
 
 ### Adding Data Tables
-1. Consider using AG Grid (@bluecopa/aggrid) for complex tables
+1. For complex tables, install and use AG Grid (@bluecopa/aggrid)
 2. For simple tables, use HTML table with Tailwind styling
 3. Include sorting, filtering, and pagination as needed
+4. Integrate with @bluecopa/react for data
 
 ### Implementing Search
-1. Add search state management
-2. Use debounced input for API calls
+1. Add search state management with React state or form libraries
+2. Use debounced input for API calls (e.g., via useMetric with query params)
 3. Show loading states during search
-4. Handle empty states gracefully
+4. Handle empty states gracefully with conditional rendering
 
 ## 🚨 Important Notes for Agents
 
@@ -209,18 +234,20 @@ const apiUrl = import.meta.env.VITE_BLUECOPA_API_URL;
 ```
 
 ### Imports
-Use path aliases consistently:
+Use path aliases consistently (configured in tsconfig.json):
 ```tsx
 import { Button } from '@/components/ui/button';
-import { useUserData } from '@/hooks/use-api';
+import { useUser } from '@bluecopa/react';
 import { cn } from '@/lib/utils';
 ```
 
 ### TypeScript
 Always include proper TypeScript types:
 ```tsx
+import { User } from '@/types/api';
+
 interface ComponentProps {
-  data: UserData[];
+  data: User[];
   onSelect: (id: string) => void;
 }
 
@@ -241,10 +268,12 @@ if (!data) return <div className="p-4 text-gray-500">No data available</div>;
 
 - [React Router Documentation](https://reactrouter.com)
 - [TailwindCSS Documentation](https://tailwindcss.com)
-- [Radix UI Documentation](https://radix-ui.com)
+- [Radix UI Documentation](https://www.radix-ui.com)
+- [shadcn/ui Documentation](https://ui.shadcn.com)
 - [Recharts Documentation](https://recharts.org)
-- [TanStack Query Documentation](https://tanstack.com/query)
-- [BlueCopa React Package](https://github.com/bluecopa/blui/packages/react)
+- [TanStack Query Documentation](https://tanstack.com/query/latest)
+- [Lucide React Icons](https://lucide.dev)
+- [BlueCopa React Package](https://www.npmjs.com/package/@bluecopa/react)
 
 ## 🔄 Development Workflow
 

package/templates/latest/README.md

@@ -41,10 +41,10 @@ npx create-bluecopa-react-app my-dashboard
 1. **Clone or copy the template**:
    ```bash
    # If using as part of the blui monorepo
-   cd packages/boilerplate/react/templates/react-router
+   cd packages/boilerplate/react/templates/latest
    
    # Or copy the template to your project location
-   cp -r packages/boilerplate/react/templates/react-router my-bluecopa-app
+   cp -r packages/boilerplate/react/templates/latest my-bluecopa-app
    cd my-bluecopa-app
    ```
 
@@ -112,9 +112,11 @@ npx create-bluecopa-react-app my-dashboard
 
 ```
 src/
-├── components/          # Reusable UI components
-│   ├── ui/             # Base UI components (buttons, cards, etc.)
-│   └── navbar.tsx      # Navigation component
+├── components/          # Reusable components
+│   ├── layout/         # Layout components (dashboard-header.tsx, dashboard-layout.tsx, sidebar.tsx)
+│   ├── page/           # Page-specific components (dashboard.tsx, navbar.tsx)
+│   ├── tables/         # Table components (data-grid.tsx)
+│   └── ui/             # Base UI components (alert.tsx, avatar.tsx, badge.tsx, bluecopa-logo.tsx, button.tsx, card.tsx, dropdown-menu.tsx, input.tsx, label.tsx, select.tsx)
 ├── hooks/              # Custom React hooks
 │   └── use-api.ts      # Bluecopa API hooks
 ├── lib/                # Utility functions
@@ -125,9 +127,12 @@ src/
 ├── providers/          # React context providers
 │   └── query-provider.tsx  # TanStack Query provider
 ├── types/              # TypeScript type definitions
+│   └── api.ts          # API type definitions
 ├── App.tsx             # Main app component with routing
+├── index.css           # Global styles
 ├── main.tsx            # Application entry point
-└── index.css           # Global styles
+├── single-spa.tsx      # Single-spa configuration
+└── vite-env.d.ts       # Vite environment types
 ```
 
 ## 🔧 Configuration
@@ -178,7 +183,7 @@ export default function App() {
 ```
 
 ### Adding Navigation Links
-Update the navigation in `src/components/navbar.tsx`:
+Update the navigation in `src/components/page/navbar.tsx`:
 
 ```tsx
 const navigation = [