create-bluecopa-react-app/README.md

CLI tool to create bluecopa React applications

# create-bluecopa-react-app [![npm version](https://img.shields.io/npm/v/create-bluecopa-react-app)](https://www.npmjs.com/package/create-bluecopa-react-app) [![License](https://img.shields.io/npm/l/create-bluecopa-react-app)](LICENSE)

## A CLI Tool for BlueCopa React Applications

A command-line interface for bootstrapping modern React applications with BlueCopa integration, featuring opinionated best practices and pre-configured tooling.

## Table of Contents

- [Version](#version)
- [Installation](#installation)
- [Requirements](#requirements)
- [Configuration](#configuration)
- [Features](#features)
- [Usage](#usage)
- [API Documentation](#api-documentation)
- [Examples](#examples)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)

## Version

Current version: 1.0.5

## Installation

```bash
npm install -g create-bluecopa-react-app
# or
pnpm add -g create-bluecopa-react-app
```

## Requirements

- Node.js >= 18.0.0
- npm >= 9.0.0 or pnpm >= 8.0.0

## Configuration

The CLI uses environment variables for configuration:

```bash
# Optional configuration
export BLUECOPA_BOILERPLATE_REGISTRY=https://registry.npmjs.org
```

## Features

- 🚀 **Modern React Stack**: React 18, TypeScript, React Router v7, Vite 6
- 🌐 **Microfrontend Support**: Single-spa compatible with module federation
- 📊 **Data Visualization**: Recharts integration for charts and analytics
- 🎨 **UI Components**: shadcn/ui components built on Radix UI primitives
- 📡 **BlueCopa React Components**: Pre-configured [`@bluecopa/react`](packages/react:1) package with hooks (includes TanStack Query integration)
- 🎯 **Type Safety**: Full TypeScript support
- 📱 **Responsive Design**: Tailwind CSS v4 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
- 🔄 **Server-side Rendering**: React Router v7 with SSR support
- 🌙 **Dark Mode**: Built-in theme switching with next-themes
- 🗂️ **Data Tables**: TanStack Table with sorting, filtering, and pagination
- 🎯 **Drag & Drop**: DND Kit integration for interactive interfaces

## Usage

### Creating a New Application

```bash
# Create new app with default template
create-bluecopa-react-app my-dashboard

# Create new app with shadcn/ui template
create-bluecopa-react-app my-dashboard --template shadcn

# Or use npx
npx create-bluecopa-react-app my-dashboard
npx create-bluecopa-react-app my-dashboard --template shadcn
```

### Available Templates

- **Default Template**: Basic React Router setup with essential components
- **shadcn Template**: Full-featured template with shadcn/ui components, data tables, charts, and dark mode support

### CLI Options

| Option | Description |
|--------|-------------|
| `--skip-install` | Skip dependency installation |
| `--template` | Specify template (default, shadcn) |
| `--help` | Show help information |

## API Documentation

### `create-bluecopa-react-app [project-name] [options]`

Creates a new BlueCopa React application.

**Parameters:**
- `project-name`: Name of the new project directory
- `options`: CLI options (see above)

**Returns:**
- Creates project structure
- Installs dependencies
- Configures environment

## Examples

### Basic Usage

```bash
create-bluecopa-react-app my-dashboard
```

### Skipping Dependency Installation

```bash
create-bluecopa-react-app my-dashboard --skip-install
```

### Using npx (Recommended)

```bash
npx create-bluecopa-react-app my-dashboard
```

## Development

### 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

- **React 18** - Modern React with concurrent features
- **React Router v7** - Modern routing with SSR support
- **Vite 6** - Fast build tool and development server
- **TypeScript** - Full type safety and developer experience
- **[`@bluecopa/react`](packages/react:1)** - BlueCopa-specific React components and hooks
- **shadcn/ui** - Accessible component library built on Radix UI
- **Radix UI** - Unstyled, accessible UI primitives
- **TanStack Table** - Headless table library for React
- **Recharts** - Composable charting library for React
- **DND Kit** - Drag and drop toolkit for React
- **Tailwind CSS v4** - Utility-first CSS framework with BlueCopa design system
- **next-themes** - Theme switching with dark mode support
- **Lucide React** - Beautiful, customizable icons

## Monorepo Integration

This CLI tool is part of the BlueCopa UI monorepo and integrates with the following packages:

- **[`@bluecopa/react`](packages/react:1)** - BlueCopa-specific React components and hooks

### Standalone Development

The generated applications can also be developed independently:

1. **Self-contained**: All dependencies are properly installed
2. **Environment setup**: Includes proper environment variable configuration
3. **Build optimization**: Uses Vite for fast development and production builds
4. **Deployment ready**: Includes Docker configuration and deployment guides