create-bluecopa-react-app 1.0.43 → 1.0.45

package/README.md

@@ -2,26 +2,31 @@
 
 ## 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.
+A command-line interface for scaffolding a Bluecopa microfrontend (MFE) React
+application, pre-wired for the Bluecopa platform: `@bluecopa/react` data hooks,
+single-spa + Module Federation mounting, the Dream Light design system on
+Tailwind CSS v4, AG Grid tables and ECharts charts.
+
+> The generated app is a **single-spa / Module Federation microfrontend** that
+> mounts inside the Bluecopa shell (it also runs standalone for local dev). It is
+> not a plain React Router SPA.
 
 ## Table of Contents
 
-- [Version](#version)
 - [Installation](#installation)
 - [Requirements](#requirements)
-- [Configuration](#configuration)
-- [Features](#features)
 - [Usage](#usage)
-- [API Documentation](#api-documentation)
-- [Examples](#examples)
+- [CLI Options](#cli-options)
+- [Interactive Prompts](#interactive-prompts)
+- [Features](#features)
+- [Generated App](#generated-app)
+  - [Tech Stack](#tech-stack)
+  - [Project Structure](#project-structure)
+  - [Scripts](#scripts)
 - [Development](#development)
-- [Contributing](#contributing)
+- [Monorepo Integration](#monorepo-integration)
 - [License](#license)
 
-## Version
-
-Current version: 1.0.5
-
 ## Installation
 
 ```bash
@@ -30,142 +35,159 @@ npm install -g create-bluecopa-react-app
 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:
+Or run without installing:
 
 ```bash
-# Optional configuration
-export BLUECOPA_BOILERPLATE_REGISTRY=https://registry.npmjs.org
+npx create-bluecopa-react-app my-dashboard
 ```
 
-## Features
+## Requirements
 
-- 🚀 **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
+- Node.js >= 18.0.0
+- npm >= 9, or pnpm (recommended). yarn is also supported.
 
 ## Usage
 
-### Creating a New Application
-
 ```bash
-# Create new app with default template
-create-bluecopa-react-app my-dashboard
+# Interactive — prompts for name, template, git, package manager, install
+create-bluecopa-react-app
 
-# Create new app with shadcn/ui template
-create-bluecopa-react-app my-dashboard --template shadcn
+# Non-interactive
+create-bluecopa-react-app my-dashboard --yes
 
-# Or use npx
-npx create-bluecopa-react-app my-dashboard
-npx create-bluecopa-react-app my-dashboard --template shadcn
+# Explicit options
+create-bluecopa-react-app my-app --package-manager pnpm --no-git
+create-bluecopa-react-app my-app --skip-install
 ```
 
-### Available Templates
+## CLI Options
 
-- **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
+Positional argument: `[project-name]` — name of the project directory (prompted if omitted).
 
-### CLI Options
+| Option                             | Alias | Description                            | Default    |
+| ---------------------------------- | ----- | -------------------------------------- | ---------- |
+| `--template <template>`            | `-t`  | Template to use (only `latest` exists) | `latest`   |
+| `--package-manager <manager>`      |       | Package manager: `npm`, `yarn`, `pnpm` | `auto`     |
+| `--skip-install`                   |       | Skip dependency installation           | installs   |
+| `--git` / `--no-git`               |       | Initialize (or skip) a git repository  | `--git`    |
+| `--yes`                            |       | Skip all prompts and use defaults      | off        |
+| `--typescript` / `--no-typescript` |       | Template language flag (see note)      | TypeScript |
+| `--version`                        |       | Print the CLI version                  |            |
+| `--help`                           |       | Show help                              |            |
 
-| Option           | Description                        |
-| ---------------- | ---------------------------------- |
-| `--skip-install` | Skip dependency installation       |
-| `--template`     | Specify template (default, shadcn) |
-| `--help`         | Show help information              |
+> **Note:** only a single TypeScript template (`latest`) ships today. The
+> `--typescript` / `--no-typescript` flags are parsed but there is no JavaScript
+> template, so they have no effect.
 
-## API Documentation
+## Interactive Prompts
 
-### `create-bluecopa-react-app [project-name] [options]`
+When `--yes` is not passed, the CLI prompts (via inquirer) in order:
 
-Creates a new Bluecopa React application.
+1. **Project name** — defaults to a random `my-<adjective>-<noun>`; validated against npm naming rules.
+2. **Template** — `latest` (Bluecopa MFE React app).
+3. **Initialize git repository?** — default yes (unless `--no-git`).
+4. **Package manager** — pnpm (recommended) / npm / auto-detect.
+5. **Install dependencies now?** — default depends on `--skip-install`.
 
-**Parameters:**
+If the target directory already exists, it asks to overwrite (auto-overwrites with `--yes`). After copying the template it sets `package.json` `name`, replaces `{{APP_NAME}}` placeholders in the HTML entry points, and (when git is enabled) writes a `.gitignore` and creates an initial commit.
 
-- `project-name`: Name of the new project directory
-- `options`: CLI options (see above)
+## Features
 
-**Returns:**
+- ⚛️ **React 18 + TypeScript** with the SWC-based Vite plugin
+- 🧩 **Microfrontend-ready** — single-spa mount/unmount + Module Federation (`@originjs/vite-plugin-federation`), SystemJS output
+- 📡 **Bluecopa data layer** — pre-configured [`@bluecopa/react`](https://www.npmjs.com/package/@bluecopa/react) hooks (TanStack Query under the hood)
+- 🎨 **Dream Light design system** on **Tailwind CSS v4** with the `copa:` prefix, plus shadcn/ui (`new-york`) + Radix UI primitives
+- 🗂️ **AG Grid** tables (community + enterprise) with a server-side datasource helper
+- 📊 **ECharts** charts via a `ChartProvider` and themed chart components
+- 🔔 **Toasts** with sonner, icons from lucide-react and Tabler
+- 🧭 **React Router v7** routing
+- ⚡ **Vite** dev server + fast build, `~/` path alias to `app/`
+- 🐳 **Deployment ready** — Dockerfile and `.env.example` included
 
-- Creates project structure
-- Installs dependencies
-- Configures environment
+## Generated App
 
-## Examples
+### Tech Stack
 
-### Basic Usage
+| Area          | Libraries                                                                                                          |
+| ------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Framework     | React `^18.3.1`, react-dom `^18.3.1`, react-router-dom `^7.16.0`                                                   |
+| Build         | Vite `8.0.16`, `@vitejs/plugin-react-swc`, `vite-tsconfig-paths`, TypeScript `^5.8.3`                              |
+| Data layer    | `@bluecopa/react` `0.1.117` (TanStack Query)                                                                       |
+| Styling       | Tailwind CSS v4 (`@tailwindcss/vite`), `tw-animate-css`, `cva`, `clsx`, `tailwind-merge`                           |
+| UI            | shadcn/ui (`new-york`), Radix UI (dialog, dropdown, tabs, tooltip, …), lucide-react, `@tabler/icons-react`, sonner |
+| Tables        | `ag-grid-community`, `ag-grid-enterprise`, `ag-grid-react` (v34)                                                   |
+| Charts        | `echarts` v6 + `echarts-for-react` (also `ag-charts-enterprise` available)                                         |
+| Microfrontend | `single-spa` `6.0.3`, `@originjs/vite-plugin-federation`                                                           |
 
-```bash
-create-bluecopa-react-app my-dashboard
-```
+`package.json` `overrides` pin security-sensitive transitive deps: `axios` `1.16.0`, `rollup` `4.59.0`, `ajv` `8.18.0`, `protobufjs` `>=7.5.8 <8`, `postcss` `>=8.5.10`, `ws` `>=8.20.1 <9`.
 
-### Skipping Dependency Installation
+### Project Structure
 
-```bash
-create-bluecopa-react-app my-dashboard --skip-install
+The source root is `app/` (aliased as `~/`), not `src/`:
+
+```
+my-app/
+├── index.html            # standalone entry ({{APP_NAME}} placeholder)
+├── preview/index.html    # preview build entry
+├── vite.config.ts        # dev server :8080, Module Federation, SystemJS output
+├── tsconfig.json         # ES2022, bundler resolution, ~/* → app/*
+├── components.json        # shadcn config (new-york, copa prefix, @bluecopa-ui registry)
+├── Dockerfile, .env.example, .gitignore
+├── CLAUDE.md, Agent.md    # agent/dev guides
+├── public/                # favicons
+└── app/
+    ├── app.tsx            # root: QueryClient, ChartProvider, AppProvider, MFE config
+    ├── main.tsx           # standalone BrowserRouter entry
+    ├── single-spa.tsx     # MFE MemoryRouter entry (manualMount / manualUnmount)
+    ├── app.css            # Tailwind v4 + Dream Light theme tokens
+    ├── components/        # bluecopa-logo, error-boundary, loading-screen
+    │   ├── ui/            # shadcn components (button, card, sidebar, ag-grid-table, …)
+    │   ├── charts/        # ECharts: bar-chart, donut-chart, chart-provider, chart-theme
+    │   └── layouts/       # app-layout, app-sidebar, nav-main, nav-user, site-header
+    ├── contexts/          # app-context
+    ├── hooks/             # use-mobile, use-permissions
+    ├── pages/             # dashboard, payments, settings
+    ├── routes/            # index route table
+    ├── constants/, types/ # MfeProps, EnvConfig, …
+    └── utils/             # ag-grid-datasource, ag-grid-license, ag-grid-theme,
+                           # component-style, style-drivers, cn()
 ```
 
-### Using npx (Recommended)
+The Vite config exposes `./App` → `app/single-spa.tsx` under the federation name
+`__copa_ext_app__react_route` (`remoteEntry.js`), externalizes `react`/`react-dom`,
+and emits SystemJS (`format: "system"`) so the Bluecopa shell can mount it.
 
-```bash
-npx create-bluecopa-react-app my-dashboard
-```
+### Scripts
+
+| Script      | Command                              | Purpose                       |
+| ----------- | ------------------------------------ | ----------------------------- |
+| `dev`       | `vite`                               | Dev server on port 8080       |
+| `build`     | `tsc && vite build`                  | Type-check + production build |
+| `start`     | `npx serve dist -l 3001 --cors`      | Serve the production build    |
+| `preview`   | `npx serve ./preview -l 8080 --cors` | Serve the preview build       |
+| `typecheck` | `tsc`                                | Type-check without emitting   |
 
 ## 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
+Working on the CLI itself (inside the monorepo):
 
-## Monorepo Integration
+```bash
+# From packages/boilerplate/react
+node bin/create-bluecopa-react-app.js my-test-app   # run the CLI locally
+pnpm format                                          # format with Prettier
+```
+
+The template lives in `templates/latest/`. Edit files there to change what gets
+scaffolded. Keep the CLI's `.version()` in `bin/create-bluecopa-react-app.js` in
+sync with `package.json` when publishing.
 
-This CLI tool is part of the Bluecopa UI monorepo and integrates with the following packages:
+## Monorepo Integration
 
-- **[`@bluecopa/react`](packages/react:1)** - Bluecopa-specific React components and hooks
+This CLI is part of the Bluecopa UI monorepo and pairs with:
 
-### Standalone Development
+- [`@bluecopa/react`](https://www.npmjs.com/package/@bluecopa/react) — React Query hooks over the Bluecopa API
+- [`@bluecopa/core`](https://www.npmjs.com/package/@bluecopa/core) — the underlying TypeScript API SDK
 
-The generated applications can also be developed independently:
+## License
 
-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
+MIT

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

@@ -17,7 +17,7 @@ const __dirname = path.dirname(__filename);
 const program = new Command();
 
 program
-  .version("1.0.5")
+  .version("1.0.45")
   .name("create-bluecopa-react-app")
   .description("Create a new Bluecopa React application")
   .argument("[project-name]", "Name of the project")
@@ -28,7 +28,7 @@ program
   .option(
     "--package-manager <manager>",
     "Package manager to use (npm, yarn, pnpm)",
-    "auto"
+    "auto",
   )
   .option("--git", "Initialize git repository", true)
   .option("--no-git", "Skip git initialization")
@@ -49,7 +49,7 @@ Templates:
 
 For more information, visit:
   https://github.com/bluecopa/blui/tree/dev/packages/boilerplate/react
-`
+`,
   )
   .action(async (projectName, options) => {
     try {
@@ -178,7 +178,7 @@ async function createApp(projectName, options) {
     // When using --yes flag, validate required options
     if (!appName) {
       console.error(
-        chalk.red("Project name is required when using --yes flag")
+        chalk.red("Project name is required when using --yes flag"),
       );
       process.exit(1);
     }
@@ -189,7 +189,7 @@ async function createApp(projectName, options) {
   if (!validTemplates.includes(selectedTemplate)) {
     console.error(chalk.red(`Invalid template: ${selectedTemplate}`));
     console.error(
-      chalk.yellow(`Available templates: ${validTemplates.join(", ")}`)
+      chalk.yellow(`Available templates: ${validTemplates.join(", ")}`),
     );
     process.exit(1);
   }
@@ -199,12 +199,12 @@ async function createApp(projectName, options) {
   if (!validation.validForNewPackages) {
     console.error(
       chalk.red("Invalid project name:"),
-      validation.errors?.[0] || validation.warnings?.[0]
+      validation.errors?.[0] || validation.warnings?.[0],
     );
     console.error(
       chalk.yellow(
-        "Project names must be lowercase, contain no spaces, and follow npm naming conventions."
-      )
+        "Project names must be lowercase, contain no spaces, and follow npm naming conventions.",
+      ),
     );
     process.exit(1);
   }
@@ -215,7 +215,7 @@ async function createApp(projectName, options) {
   if (fs.existsSync(targetDir)) {
     if (options.yes) {
       console.log(
-        chalk.yellow(`Directory ${appName} already exists. Overwriting...`)
+        chalk.yellow(`Directory ${appName} already exists. Overwriting...`),
       );
       await fs.remove(targetDir);
     } else {
@@ -238,7 +238,9 @@ async function createApp(projectName, options) {
   }
 
   console.log(
-    chalk.blue(`Creating a new Bluecopa React app in ${chalk.green(targetDir)}`)
+    chalk.blue(
+      `Creating a new Bluecopa React app in ${chalk.green(targetDir)}`,
+    ),
   );
   console.log(chalk.gray(`Template: ${selectedTemplate}`));
   console.log();
@@ -256,15 +258,15 @@ async function createApp(projectName, options) {
     if (!options.skipInstall) {
       const detectedPackageManager = await detectPackageManager(packageManager);
       spinner.start(
-        `Installing dependencies with ${detectedPackageManager}...`
+        `Installing dependencies with ${detectedPackageManager}...`,
       );
       await installDependencies(targetDir, detectedPackageManager);
       spinner.succeed("Dependencies installed");
     } else {
       console.log(
         chalk.yellow(
-          "Skipping dependency installation. You can run it manually later."
-        )
+          "Skipping dependency installation. You can run it manually later.",
+        ),
       );
     }
 
@@ -276,7 +278,7 @@ async function createApp(projectName, options) {
     }
 
     spinner.succeed(
-      chalk.green("Success! Created " + appName + " at " + targetDir)
+      chalk.green("Success! Created " + appName + " at " + targetDir),
     );
 
     console.log();
@@ -336,8 +338,8 @@ async function createApp(projectName, options) {
     console.log(chalk.gray("Need help? Check out the documentation:"));
     console.log(
       chalk.gray(
-        "  https://github.com/bluecopa/blui/tree/main/packages/boilerplate/react"
-      )
+        "  https://github.com/bluecopa/blui/tree/main/packages/boilerplate/react",
+      ),
     );
   } catch (error) {
     spinner.fail("Failed to create project");
@@ -356,7 +358,7 @@ async function createProjectStructure(targetDir, appName, options) {
   // Validate template directory exists
   if (!(await fs.pathExists(templateDir))) {
     throw new Error(
-      `Template '${options.template}' not found at ${templateDir}`
+      `Template '${options.template}' not found at ${templateDir}`,
     );
   }
 
@@ -400,8 +402,8 @@ async function detectPackageManager(preferredManager) {
     } catch {
       console.log(
         chalk.yellow(
-          `Warning: ${preferredManager} not found, falling back to auto-detection`
-        )
+          `Warning: ${preferredManager} not found, falling back to auto-detection`,
+        ),
       );
     }
   }
@@ -437,7 +439,7 @@ async function installDependencies(targetDir, packageManager) {
     execSync(installCommand, { stdio: "inherit" });
   } catch (error) {
     throw new Error(
-      `Failed to install dependencies with ${packageManager}: ${error.message}`
+      `Failed to install dependencies with ${packageManager}: ${error.message}`,
     );
   }
 }
@@ -466,7 +468,7 @@ pnpm-debug.log*
     if (!fs.existsSync(gitignorePath)) {
       fs.writeFileSync(gitignorePath, gitignoreContent.trimStart());
     }
-    
+
     // Initialize git repository
     execSync("git init", { stdio: "ignore" });
     // Create initial commit

package/package.json

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

package/templates/latest/.env.example

@@ -1,8 +1,18 @@
 # API base URL for the Bluecopa platform
-VITE_BLUECOPA_API_URL=https://api.bluecopa.com
+VITE_BLUECOPA_API_URL=https://develop.bluecopa.com/api/v1
 
 # Workspace ID for standalone development
 VITE_BLUECOPA_WORKSPACE_ID=YOUR_WORKSPACE_ID
 
-# AG Grid Enterprise license key (optional — watermarks shown without it)
+# ─── Auth / identity (standalone dev) ───────────────────────────────
+VITE_BLUECOPA_API_TOKEN=
+VITE_BLUECOPA_USER_ID=
+
+# ─── AG Grid Enterprise license ─────────────────────────────────────
 VITE_AG_GRID_LICENSE_KEY=
+
+# ─── Solution context (Input Table V2 / deployed solutions) ─────────
+# Flow through to the x-bluecopa-solution-* SDK headers.
+VITE_BLUECOPA_SOLUTION_ID=
+VITE_BLUECOPA_SOLUTION_BRANCH=main
+VITE_BLUECOPA_SOLUTION_BRANCH_TYPE=REMOTE