create-bluecopa-react-app 1.0.1 → 1.0.3

package/README.md

@@ -4,13 +4,16 @@ A CLI tool to bootstrap modern React applications for BlueCopa with built-in UI
 
 ## Features
 
-- 🚀 **Modern React Stack**: React 18, TypeScript, Next.js 14
+- 🚀 **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
+- 📡 **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
-- 🛠️ **Development Tools**: ESLint, TypeScript checking, and Next.js build optimization
+- 📱 **Responsive Design**: Tailwind CSS with mobile-first approach and BlueCopa design system
+- 🛠️ **Development Tools**: ESLint, TypeScript checking, and Vite fast build system
+- ⚡ **Fast Development**: Hot module replacement with Vite
+- 🔄 **Client-side Routing**: React Router v6 for SPA navigation
 
 ## Quick Start
 
@@ -36,17 +39,18 @@ npm run dev
 
 ## Template Included
 
-### BlueCopa Next.js Template
+### BlueCopa React Router Template
 
 A foundational template that provides:
 
-- **Modern Next.js Setup**: Next.js 14 with React 18, TypeScript and App Router
-- **BlueCopa Components**: Pre-configured @bluecopa/react component library
+- **Modern React Setup**: React 18 with TypeScript, React Router v6, and Vite
+- **BlueCopa Components**: Pre-configured @bluecopa/react component library with hooks
 - **UI Foundation**: Radix UI primitives with custom styling system
 - **Data Visualization**: Recharts for charts and analytics
-- **Styling System**: Tailwind CSS with BlueCopa design tokens
-- **Development Setup**: ESLint, TypeScript configuration, and Next.js optimization
+- **Styling System**: Tailwind CSS with BlueCopa design tokens and navy theme
+- **Development Setup**: ESLint, TypeScript configuration, and Vite optimization
 - **Environment Configuration**: Ready-to-use environment variable setup
+- **Client-side Routing**: React Router v6 for smooth SPA navigation
 
 #### Key Dependencies Included
 
@@ -54,20 +58,36 @@ A foundational template that provides:
 // Core BlueCopa and React ecosystem
 "@bluecopa/react": "^0.1.3"
 "react": "^18.3.0"
-"next": "^14.2.0"
+"react-dom": "^18.3.0"
+"react-router-dom": "^6.26.0"
 "typescript": "^5.6.0"
 
 // UI and Styling
-"@radix-ui/*": "Latest versions"
-"tailwindcss": "^3.4.0"
+"@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": "^7.1.5"
 "eslint": "^8.57.0"
-"eslint-config-next": "^14.2.0"
+"@vitejs/plugin-react-swc": "^4.0.1"
+"@originjs/vite-plugin-federation": "^1.4.1"
 ```
 
 ## Project Structure
@@ -77,47 +97,78 @@ The generated project follows a clean, scalable structure:
 ```text
 my-bluecopa-app/
 ├── src/
-│   ├── app/                 # Next.js App Router pages
-│   │   ├── layout.tsx       # Root layout component
-│   │   ├── page.tsx         # Home page component
-│   │   └── globals.css      # Global styles and Tailwind imports
-│   ├── components/
-│   │   ├── ui/              # Reusable UI components
-│   │   ├── charts/          # Chart components using Recharts
-│   │   └── layouts/         # Layout components
-│   ├── lib/                 # Utilities and helpers
-│   │   ├── utils.ts         # Common utility functions
-│   │   └── cn.ts            # Tailwind class name utilities
-│   └── types/               # TypeScript type definitions
-├── public/                  # Static assets
-├── .env                     # Environment variables
-├── .env.example             # Environment variables template
-├── package.json             # Dependencies and scripts
-├── next.config.js           # Next.js configuration
-├── tailwind.config.js       # Tailwind CSS configuration
-├── tsconfig.json            # TypeScript configuration
-├── postcss.config.js        # PostCSS configuration
-└── README.md                # Project documentation
+│   ├── components/          # Reusable UI components
+│   │   ├── ui/             # Base UI components (buttons, cards, etc.)
+│   │   └── navbar.tsx      # Navigation component
+│   ├── hooks/              # Custom React hooks
+│   │   └── use-api.ts      # Bluecopa API hooks
+│   ├── lib/                # Utilities and helpers
+│   │   └── utils.ts        # Helper functions and utilities
+│   ├── pages/              # Route components
+│   │   ├── Home.tsx        # Home page component
+│   │   └── Dashboard.tsx   # Dashboard page component
+│   ├── providers/          # React context providers
+│   │   └── 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 with module federation
+├── tailwind.config.js      # Tailwind CSS configuration
+├── tsconfig.json           # TypeScript configuration
+├── postcss.config.js       # PostCSS configuration
+└── README.md               # Project documentation
 ```
 
 ## Getting Started with Development
 
-### Adding BlueCopa Components
+### Adding BlueCopa Components and Hooks
 
-The template includes @bluecopa/react components. Start building by importing and using them:
+The template includes @bluecopa/react components and hooks. Start building by importing and using them:
 
 ```typescript
-import { SomeBlueCopaComponent } from '@bluecopa/react';
+import { useUserData, useMetricDataDemo, useDatasetDataDemo } from '@/hooks/use-api';
 
 function MyComponent() {
+  const { data: userData, isLoading, error } = useUserData();
+  const { data: metrics } = useMetricDataDemo();
+  
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  
   return (
     <div>
-      <SomeBlueCopaComponent />
+      <h1>Welcome, {userData?.user?.firstName}!</h1>
     </div>
   );
 }
 ```
 
+### Adding Routes
+
+Add new routes in `src/App.tsx`:
+
+```typescript
+import { Routes, Route } from 'react-router-dom';
+import NewPage from '@/pages/NewPage';
+
+export default function App() {
+  return (
+    <QueryProvider>
+      <Routes>
+        <Route path="/" element={<Home />} />
+        <Route path="/dashboard" element={<Dashboard />} />
+        <Route path="/new-page" element={<NewPage />} />
+      </Routes>
+    </QueryProvider>
+  );
+}
+```
+
 ### Adding UI Components
 
 Use the included Radix UI components with Tailwind styling:
@@ -168,36 +219,76 @@ function ChartComponent() {
 }
 ```
 
-### Styling and Theming
+### Environment Configuration
 
-- Modify `tailwind.config.js` for custom design tokens
-- Update CSS variables in `src/app/globals.css` for theme customization
-- All components support consistent styling through Tailwind utilities
-- Use the `cn()` utility function for conditional class names
+Create a `.env.local` file from the example:
 
-## Environment Configuration
-
-Copy the included `.env.example` to `.env` and configure as needed:
+```bash
+cp .env.example .env.local
+# Edit .env.local with your Bluecopa credentials from dashboard → Settings → API Tokens
+```
 
+Required environment variables:
 ```bash
-cp .env.example .env
+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 Next.js development server with hot reload
-- `npm run build` - Build for production (Next.js optimization)
-- `npm run start` - Start production server
+- `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
 
 - **React 18** - Modern React with concurrent features
-- **Next.js 14** - Full-stack React framework with App Router
+- **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
+- **@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
+- **Tailwind CSS** - Utility-first CSS framework with BlueCopa design system
 - **Lucide React** - Beautiful, customizable icons
+
+## CLI Usage
+
+The CLI will prompt you for project details and automatically:
+
+- Create the project structure
+- Copy template files
+- Update package.json with your project name
+- Install dependencies (unless `--skip-install` is used)
+- Provide next steps for development
+
+Example output:
+
+```bash
+✔ Creating project structure...
+✔ Dependencies installed
+✔ Success! Created my-dashboard at /path/to/my-dashboard
+
+Inside that directory, you can run several commands:
+
+  npm run dev
+    Starts the development server.
+
+  npm run build
+    Bundles the app into static files for production.
+
+We suggest that you begin by typing:
+
+  cd my-dashboard
+  npm run dev
+
+Happy coding with Bluecopa! 🚀
+```

package/bin/create-bluecopa-react-app.js

@@ -100,19 +100,19 @@ async function createApp(projectName, options) {
     console.log();
     console.log('Inside that directory, you can run several commands:');
     console.log();
-    console.log(chalk.cyan('  npm start'));
+    console.log(chalk.cyan('  npm run dev'));
     console.log('    Starts the development server.');
     console.log();
     console.log(chalk.cyan('  npm run build'));
     console.log('    Bundles the app into static files for production.');
     console.log();
-    console.log(chalk.cyan('  npm test'));
-    console.log('    Starts the test runner.');
+    console.log(chalk.cyan('  npm run preview'));
+    console.log('    Preview the production build locally.');
     console.log();
     console.log('We suggest that you begin by typing:');
     console.log();
     console.log(chalk.cyan('  cd'), appName);
-    console.log(chalk.cyan('  npm start'));
+    console.log(chalk.cyan('  npm run dev'));
     console.log();
     console.log('Happy coding with Bluecopa! 🚀');
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bluecopa-react-app",
-  "version": "1.0.1",
+  "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

@@ -0,0 +1,288 @@
+# Agent Development Guide - BlueCopa React Template
+
+This document provides guidance for AI agents working with BlueCopa React applications built from this template.
+
+## 🤖 Agent Overview
+
+This template is designed to work seamlessly with AI coding assistants for rapid development of BlueCopa dashboard applications. The project structure and patterns are optimized for AI-assisted development.
+
+## 📋 Project Context
+
+### Technology Stack
+- **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 (add via shadcn-ui for pre-styled components)
+- **Data Fetching**: TanStack Query with @bluecopa/react hooks
+- **Charts**: Recharts for data visualization
+- **Icons**: Lucide React
+
+### Key Directories
+```
+src/
+├── 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 (e.g., QueryProvider)
+├── lib/               # Utility functions and helpers (e.g., utils.ts with cn)
+└── types/             # TypeScript type definitions (e.g., api.ts)
+```
+
+## 🔧 Development Patterns
+
+### 1. Adding New Pages/Routes
+
+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>
+        <CardHeader>
+          <CardTitle>New Page</CardTitle>
+        </CardHeader>
+        <CardContent>
+          {/* Page content */}
+          <p>Welcome, {userData?.name}!</p>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+```
+
+2. **Add the route** in `src/App.tsx`:
+```tsx
+import NewPage from '@/pages/NewPage';
+
+// Add to Routes
+<Route path="/new-page" element={<NewPage />} />
+```
+
+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 },
+];
+```
+
+### 2. Using BlueCopa API Hooks
+
+Install @bluecopa/react if not present: `npm install @bluecopa/react`
+
+Use the pre-configured hooks from `@bluecopa/react`:
+
+```tsx
+import { useUser, useMetric, useDataset } from '@bluecopa/react';
+
+function DataComponent() {
+  const { data: userData, isLoading: userLoading, error: userError } = useUser();
+  const { data: metrics } = useMetric({ metricId: 'example' });
+  const { data: datasets } = useDataset({ datasetId: 'example' });
+  
+  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>
+  <CardHeader>
+    <CardTitle>Dashboard</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <Tabs defaultValue="overview" className={cn("w-full")}>
+      <TabsList>
+        <TabsTrigger value="overview">Overview</TabsTrigger>
+        <TabsTrigger value="analytics">Analytics</TabsTrigger>
+      </TabsList>
+      <TabsContent value="overview">
+        <Button>Action</Button>
+      </TabsContent>
+    </Tabs>
+  </CardContent>
+</Card>
+```
+
+### 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';
+
+interface ChartData {
+  name: string;
+  value: number;
+}
+
+function ChartComponent({ data }: { data: ChartData[] }) {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Analytics</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <ResponsiveContainer width="100%" height={300}>
+          <LineChart data={data}>
+            <CartesianGrid strokeDasharray="3 3" />
+            <XAxis dataKey="name" />
+            <YAxis />
+            <Tooltip />
+            <Line type="monotone" dataKey="value" stroke="#041e42" />
+          </LineChart>
+        </ResponsiveContainer>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+## 🎨 Design System Guidelines
+
+### Colors
+- **Primary**: Navy blue (`#041e42`) - BlueCopa brand color
+- **Background**: Light gray (`bg-gray-50`)
+- **Cards**: White with subtle shadow (`bg-white shadow-sm`)
+- **Text**: Gray scale (`text-gray-900`, `text-gray-600`)
+
+### Layout Patterns
+- **Container**: `container mx-auto py-6` for page layouts
+- **Grid**: `grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6` for responsive grids
+- **Spacing**: Use Tailwind spacing scale (`p-4`, `mb-6`, etc.)
+
+### Component Structure
+```tsx
+// Standard page layout
+<div className="container mx-auto py-6">
+  <div className="mb-6">
+    <h1 className="text-2xl font-bold text-gray-900">Page Title</h1>
+    <p className="text-gray-600">Page description</p>
+  </div>
+  
+  <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+    {/* Cards or components */}
+  </div>
+</div>
+```
+
+## 🛠️ Common Tasks for Agents
+
+### Adding a New Dashboard Card
+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 (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. 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 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 with conditional rendering
+
+## 🚨 Important Notes for Agents
+
+### Environment Variables
+Always reference environment variables correctly for Vite:
+```tsx
+const apiToken = import.meta.env.VITE_BLUECOPA_API_TOKEN;
+const apiUrl = import.meta.env.VITE_BLUECOPA_API_URL;
+```
+
+### Imports
+Use path aliases consistently (configured in tsconfig.json):
+```tsx
+import { Button } from '@/components/ui/button';
+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: User[];
+  onSelect: (id: string) => void;
+}
+
+function Component({ data, onSelect }: ComponentProps) {
+  // Component implementation
+}
+```
+
+### Error Handling
+Include proper error boundaries and loading states:
+```tsx
+if (isLoading) return <div className="p-4">Loading...</div>;
+if (error) return <div className="p-4 text-red-600">Error: {error.message}</div>;
+if (!data) return <div className="p-4 text-gray-500">No data available</div>;
+```
+
+## 📚 Reference Links
+
+- [React Router Documentation](https://reactrouter.com)
+- [TailwindCSS Documentation](https://tailwindcss.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/latest)
+- [Lucide React Icons](https://lucide.dev)
+- [BlueCopa React Package](https://www.npmjs.com/package/@bluecopa/react)
+
+## 🔄 Development Workflow
+
+When working on this project:
+
+1. **Start development server**: `npm run dev`
+2. **Type checking**: `npm run type-check`
+3. **Linting**: `npm run lint`
+4. **Building**: `npm run build`
+5. **Preview build**: `npm run preview`
+
+The development server supports hot module replacement, so changes will be reflected immediately in the browser.