create-bluecopa-react-app 1.0.0 → 1.0.2

package/README.md

@@ -4,13 +4,15 @@ A CLI tool to bootstrap modern React applications for BlueCopa with built-in UI
 
 ## Features
 
-- 🚀 **Modern React Stack**: React 18, TypeScript, Vite
-- 📊 **Data Visualization**: Integration ready for charts and analytics
-- 🎨 **UI Components**: shadcn/ui with Radix UI primitives  
-- 📡 **BlueCopa React Components**: Pre-configured @bluecopa/react package
+- 🚀 **Modern React Stack**: React 18, TypeScript, React Router v6, Vite
+- 📊 **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
 - 🎯 **Type Safety**: Full TypeScript support
-- 📱 **Responsive Design**: Tailwind CSS with mobile-first approach
-- 🛠️ **Development Tools**: ESLint, TypeScript checking, and modern build tools
+- 📱 **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,33 +38,41 @@ npm run dev
 
 ## Template Included
 
-### BlueCopa Basic Template
+### BlueCopa React Router Template
 
 A foundational template that provides:
 
-- **Modern React Setup**: React 18 with TypeScript and Vite
-- **BlueCopa Components**: Pre-configured @bluecopa/react component library
-- **UI Foundation**: Complete shadcn/ui component suite with Radix UI primitives
-- **Styling System**: Tailwind CSS with BlueCopa design tokens
-- **Development Setup**: ESLint, TypeScript configuration, and build optimization
+- **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 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
 
 ```typescript
 // Core BlueCopa and React ecosystem
 "@bluecopa/react": "^0.1.3"
-"react": "^18.2.0"
-"typescript": "^5.0.2"
+"react": "^18.3.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.3.0"
-"lucide-react": "^0.263.1"
+"tailwindcss": "^3.4.17"
+"lucide-react": "^0.445.0"
+
+// Data Visualization
+"recharts": "^2.12.0"
 
 // Development and Build
-"vite": "^4.4.5"
-"@vitejs/plugin-react": "^4.0.3"
+"vite": "^5.4.20"
+"eslint": "^8.57.0"
+"@vitejs/plugin-react": "^4.3.0"
 ```
 
 ## Project Structure
@@ -72,43 +82,80 @@ The generated project follows a clean, scalable structure:
 ```text
 my-bluecopa-app/
 ├── src/
-│   ├── components/
-│   │   └── ui/              # shadcn/ui components
-│   ├── lib/                 # Utilities and helpers
-│   ├── App.tsx              # Main application component
-│   ├── main.tsx             # Application entry point
-│   ├── index.css            # Global styles and Tailwind imports
-│   └── vite-env.d.ts        # Vite type declarations
-├── public/                  # Static assets
-├── .env.example             # Environment variables template
-├── package.json             # Dependencies and scripts
-├── tailwind.config.js       # Tailwind CSS configuration
-├── tsconfig.json            # TypeScript configuration
-├── vite.config.ts           # Vite build 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
+│   ├── types/              # TypeScript type definitions
+│   ├── App.tsx             # Main app component with routing
+│   ├── main.tsx            # Application entry point
+│   └── 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
+├── 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 shadcn/ui components for consistent styling:
+Use the included Radix UI components with Tailwind styling:
 
 ```typescript
 import { Button } from '@/components/ui/button';
@@ -128,24 +175,54 @@ function Dashboard() {
 }
 ```
 
-### Styling and Theming
+### Adding Charts and Data Visualization
+
+Use Recharts for data visualization:
+
+```typescript
+import { LineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer } from 'recharts';
+
+const data = [
+  { name: 'Jan', value: 400 },
+  { name: 'Feb', value: 300 },
+  { name: 'Mar', value: 600 },
+];
+
+function ChartComponent() {
+  return (
+    <ResponsiveContainer width="100%" height={300}>
+      <LineChart data={data}>
+        <CartesianGrid strokeDasharray="3 3" />
+        <XAxis dataKey="name" />
+        <YAxis />
+        <Tooltip />
+        <Line type="monotone" dataKey="value" stroke="#8884d8" />
+      </LineChart>
+    </ResponsiveContainer>
+  );
+}
+```
 
-- Modify `tailwind.config.js` for custom design tokens
-- Update CSS variables in `src/index.css` for theme customization
-- All shadcn/ui components support dark/light mode automatically
+### Environment Configuration
 
-## Environment Configuration
+Create a `.env.local` file from the example:
 
-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
 ```
 
 ## Available Scripts
 
-- `npm run dev` - Start development server with hot reload
-- `npm run build` - Build for production (TypeScript compilation + Vite build)
+- `npm run dev` - Start Vite development server with hot reload
+- `npm run build` - Build for production (TypeScript + Vite optimization)
 - `npm run preview` - Preview production build locally
 - `npm run lint` - Run ESLint for code quality
 - `npm run type-check` - Run TypeScript type checking without emitting files
@@ -153,10 +230,45 @@ cp .env.example .env
 ## Technologies Used
 
 - **React 18** - Modern React with concurrent features
-- **TypeScript** - Full type safety and developer experience
+- **React Router v6** - Declarative routing for React SPAs
 - **Vite** - Fast build tool and development server
-- **@bluecopa/react** - BlueCopa-specific React components
-- **shadcn/ui** - High-quality, accessible component library
+- **TypeScript** - Full type safety and developer experience
+- **@bluecopa/react** - BlueCopa-specific React components and hooks
+- **TanStack Query** - Powerful data synchronization for React
 - **Radix UI** - Unstyled, accessible UI primitives
-- **Tailwind CSS** - Utility-first CSS framework
+- **Recharts** - Composable charting library for React
+- **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! 🚀');
 
@@ -123,7 +123,7 @@ async function createApp(projectName, options) {
 }
 
 async function createProjectStructure(targetDir, appName, options) {
-  const templateDir = path.join(__dirname, '../templates/basic');
+  const templateDir = path.join(__dirname, '../templates/latest');
   
   // Create base directory
   await fs.ensureDir(targetDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bluecopa-react-app",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "CLI tool to create bluecopa React applications",
   "main": "./bin/create-bluecopa-react-app.js",
   "bin": {

package/templates/latest/.env.example

@@ -0,0 +1,14 @@
+# Bluecopa API Configuration
+# Copy this file to .env.local and update with your actual values
+
+# Bluecopa API Authentication
+# Get this from your Bluecopa dashboard -> Settings -> API Tokens
+VITE_BLUECOPA_API_TOKEN=your-bluecopa-api-token-here
+
+# Bluecopa API Base URL
+# Use the develop environment for testing
+VITE_BLUECOPA_API_URL=https://develop.bluecopa.com/api/v1
+
+# Bluecopa Workspace ID
+# Get this from your Bluecopa dashboard workspace settings
+VITE_BLUECOPA_WORKSPACE_ID=your-workspace-id-here

package/templates/latest/.eslintrc.cjs

@@ -0,0 +1,42 @@
+module.exports = {
+  root: true,
+  env: { 
+    browser: true, 
+    es2020: true,
+    node: true 
+  },
+  extends: [
+    'eslint:recommended',
+  ],
+  ignorePatterns: ['dist', '.eslintrc.cjs'],
+  parserOptions: {
+    ecmaVersion: 'latest',
+    sourceType: 'module',
+    ecmaFeatures: {
+      jsx: true,
+    },
+  },
+  plugins: ['react-refresh'],
+  rules: {
+    'react-refresh/only-export-components': [
+      'warn',
+      { allowConstantExport: true },
+    ],
+    'no-unused-vars': 'off', // Turned off for TypeScript
+    'no-undef': 'off', // TypeScript handles this
+  },
+  overrides: [
+    {
+      files: ['*.ts', '*.tsx'],
+      parser: '@typescript-eslint/parser',
+      plugins: ['@typescript-eslint'],
+      rules: {
+        'no-unused-vars': 'off',
+        // Basic TypeScript rules without extending the recommended config
+        '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+        '@typescript-eslint/no-explicit-any': 'warn',
+        '@typescript-eslint/no-inferrable-types': 'warn',
+      },
+    },
+  ],
+}

package/templates/latest/Agent.md

@@ -0,0 +1,259 @@
+# 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
+- **Data Fetching**: TanStack Query with @bluecopa/react hooks
+- **Charts**: Recharts for data visualization
+- **Icons**: Lucide React
+
+### Key Directories
+```
+src/
+├── components/ui/       # Reusable UI components (Button, Card, etc.)
+├── components/         # Business logic components (Navbar, etc.)
+├── hooks/             # Custom React hooks and API integration
+├── pages/             # Route components (Home, Dashboard)
+├── providers/         # React context providers
+├── lib/               # Utility functions and helpers
+└── types/             # TypeScript type definitions
+```
+
+## 🔧 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';
+
+export default function NewPage() {
+  return (
+    <div className="container mx-auto py-6">
+      <Card>
+        <CardHeader>
+          <CardTitle>New Page</CardTitle>
+        </CardHeader>
+        <CardContent>
+          {/* Page content */}
+        </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/navbar.tsx`:
+```tsx
+const navigation = [
+  // ... existing routes
+  { name: 'New Page', href: '/new-page', icon: Settings },
+];
+```
+
+### 2. Using BlueCopa API Hooks
+
+Always use the pre-configured hooks from `@/hooks/use-api.ts`:
+
+```tsx
+import { useUserData, useMetricDataDemo, useDatasetDataDemo } from '@/hooks/use-api';
+
+function DataComponent() {
+  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>Data: {JSON.stringify(userData)}</div>;
+}
+```
+
+### 3. UI Component Patterns
+
+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';
+
+// Example usage
+<Card>
+  <CardHeader>
+    <CardTitle>Dashboard</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <Tabs defaultValue="overview">
+      <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
+
+Use Recharts for data visualization:
+
+```tsx
+import { LineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer } from 'recharts';
+
+function ChartComponent({ data }: { data: any[] }) {
+  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 appropriate location
+2. Use Card component wrapper
+3. Include loading and error states
+4. Use BlueCopa hooks for data
+
+### Creating Forms
+1. Use Radix UI form components
+2. Add TypeScript types for form data
+3. Include validation and error handling
+4. Follow BlueCopa styling patterns
+
+### Adding Data Tables
+1. Consider using AG Grid (@bluecopa/aggrid) for complex tables
+2. For simple tables, use HTML table with Tailwind styling
+3. Include sorting, filtering, and pagination as needed
+
+### Implementing Search
+1. Add search state management
+2. Use debounced input for API calls
+3. Show loading states during search
+4. Handle empty states gracefully
+
+## 🚨 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:
+```tsx
+import { Button } from '@/components/ui/button';
+import { useUserData } from '@/hooks/use-api';
+import { cn } from '@/lib/utils';
+```
+
+### TypeScript
+Always include proper TypeScript types:
+```tsx
+interface ComponentProps {
+  data: UserData[];
+  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://radix-ui.com)
+- [Recharts Documentation](https://recharts.org)
+- [TanStack Query Documentation](https://tanstack.com/query)
+- [BlueCopa React Package](https://github.com/bluecopa/blui/packages/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.