create-bluecopa-react-app

A CLI Tool for Bluecopa React Applications

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

• Installation
• Requirements
• Usage
• CLI Options
• Interactive Prompts
• Features
• Generated App
  • Tech Stack
  • Project Structure
  • Scripts
• Development
• Monorepo Integration
• License

Installation

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

Or run without installing:

npx create-bluecopa-react-app my-dashboard

Requirements

• Node.js >= 18.0.0
• npm >= 9, or pnpm (recommended). yarn is also supported.

Usage

# Interactive — prompts for name, template, git, package manager, install
create-bluecopa-react-app

# Non-interactive
create-bluecopa-react-app my-dashboard --yes

# Explicit options
create-bluecopa-react-app my-app --package-manager pnpm --no-git
create-bluecopa-react-app my-app --skip-install

CLI Options

Positional argument: [project-name] — name of the project directory (prompted if omitted).

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

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.

Interactive Prompts

When --yes is not passed, the CLI prompts (via inquirer) in order:

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.

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.

Features

• ⚛️ 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 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

Generated App

Tech Stack

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

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.

Project Structure

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()

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.

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

Working on the CLI itself (inside the monorepo):

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

Monorepo Integration

This CLI is part of the Bluecopa UI monorepo and pairs with:

• @bluecopa/react — React Query hooks over the Bluecopa API
• @bluecopa/core — the underlying TypeScript API SDK

License

MIT