# React Bricks CLI

The command-line interface tool for creating React Bricks apps with a starter templates and API validation rewritten in Clack.

## Overview

The React Bricks CLI (`create-reactbricks-app`) is a comprehensive tool that streamlines the process of creating new React Bricks projects. It provides an interactive setup experience that guides users through authentication, app selection/creation, project configuration, and starter template selection.

## What is React Bricks?

React Bricks is a CMS with visual editing based on React components. It allows developers to create websites and applications with a visual editing interface while maintaining full control over the codebase.

## Features

- 🔐 **Authentication System**: Secure login with session management
- 📱 **Multi-App Support**: Create or select from existing React Bricks apps
- 🎨 **Multiple Framework Support**: Next.js (App Router & Pages Router), Astro, Remix, and Gatsby
- 🌐 **Template Varieties**: Choose from "Website and Blog with Tailwind" or "Empty project" starters
- 📦 **Package Manager Detection**: Automatically detects and uses npm, yarn, or pnpm
- 🛠️ **Environment Setup**: Automatic environment variable configuration
- 📄 **Content Seeding**: Optional default content and image setup
- 🔧 **Git Integration**: Automatic git repository initialization
- 📊 **Error Tracking**: Built-in Sentry integration for monitoring

## Technology Stack

- **Language**: TypeScript
- **Runtime**: Node.js (>=20.18.0)
- **Build Tool**: unbuild
- **Package Manager**: pnpm (with workspace support)
- **CLI Framework**: @clack/prompts for interactive prompts
- **HTTP Client**: axios for API communications
- **Process Management**: execa for running shell commands
- **Authentication**: configstore for persistent login sessions
- **Monitoring**: @sentry/node for error tracking

## Installation

The CLI is designed to be used with npx (no installation required):

```bash
npx create-reactbricks-app
```

Or install globally:

```bash
npm install -g create-reactbricks-app
# or
yarn global add create-reactbricks-app
# or
pnpm add -g create-reactbricks-app
```

## Usage

Simply run the command and follow the interactive prompts:

```bash
npx create-reactbricks-app
```

### Interactive Flow

1. **Authentication**: Login with your React Bricks account credentials
2. **App Selection**: Choose an existing app or create a new one
3. **Environment Selection**: Select the environment (main, staging, etc.)
4. **Project Configuration**: Set project name and folder
5. **Starter Template**: Choose from available frameworks and templates
6. **Content Setup**: Optionally load default content and images
7. **Installation**: Automatic dependency installation and git initialization

### Supported Frameworks and Templates

#### Next.js with App Router

- Website and Blog with Tailwind (recommended)
- Empty project

#### Next.js with Pages Router

- Website and Blog with Tailwind (recommended)
- Empty project

#### Astro (Node.js v22 required)

- Website and Blog with Tailwind (recommended)
- Empty project

#### Remix

- Website and Blog with Tailwind (recommended)
- Empty project

#### Gatsby

- Website and Blog with Tailwind (recommended)
- Empty project

## Project Structure

```
src/
├── index.ts              # Main CLI entry point
├── starters.json         # Template configurations
└── helpers/
    ├── api.ts           # React Bricks API interactions
    ├── auth.ts          # Authentication prompts and logic
    ├── fs.ts            # File system utilities
    ├── starters.ts      # Starter template types and utilities
    ├── tasks.ts         # Project creation tasks (git, dependencies, etc.)
    └── utils.ts         # General utility functions
```

## Development

### Prerequisites

- Node.js >= 20.18.0 (Astro starter requires >= 22.0.0)
- pnpm >= 10.7.0

### Setup

1. Clone the repository:

```bash
git clone https://github.com/ReactBricks/create-reactbricks-app.git
cd create-reactbricks-app
```

2. Install dependencies:

```bash
pnpm install
```

3. Build the project:

```bash
pnpm build
```

### Scripts

- `pnpm build` - Build the project using unbuild
- `pnpm copy:starters` - Copy starters.json to dist directory
- `pnpm prepack` - Run build before packaging

### Build Process

The project uses `unbuild` for building:

- Compiles TypeScript to JavaScript (ESM)
- Generates type declarations
- Copies `starters.json` to the dist directory
- Creates a single `index.mjs` entry point

## Configuration

### Environment Variables

The CLI creates environment files based on the selected starter template:

- **Next.js**: `.env.local`
- **Astro**: `.env`
- **Remix**: `.env`
- **Gatsby**: `.env.production`

### Starter Configuration

Each starter template in `starters.json` contains:

```json
{
  "framework": "Framework name",
  "starterProject": "Project type",
  "language": "TypeScript",
  "repoUrl": "GitHub repository URL",
  "startYarnCommand": "yarn dev",
  "startPnpmCommand": "pnpm dev",
  "startNpmCommand": "npm run dev",
  "envVariables": {
    "apiKey": "API_KEY",
    "appId": "APP_ID",
    "appEnv": "ENVIRONMENT"
  },
  "envFile": ".env.local",
  "importRbUI": false,
  "defaultImages": [...],
  "defaultContent": [...],
  "minimalImages": [...],
  "minimalContent": [...]
}
```

## API Integration

The CLI integrates with the React Bricks API for:

- User authentication and session management
- App creation and retrieval
- Environment management
- Content and media upload
- Admin operations for default content setup

### API Endpoints Used

- `POST /v2/account/session` - Authentication
- `GET /v2/account/apps` - Retrieve user apps
- `POST /v2/account/apps` - Create new app
- `POST /v2/admin/session` - Admin authentication
- `POST /v2/admin/pages` - Create pages
- `POST /v2/admin/media/images/create_from_url` - Upload images

## Error Handling

The CLI includes comprehensive error handling:

- Network connectivity issues
- Authentication failures
- File system permissions
- Git configuration problems
- Package installation errors

Errors are automatically reported to Sentry for monitoring and improvement.

### Code Style

- TypeScript with strict mode enabled
- ESM modules
- Async/await for asynchronous operations
- Comprehensive error handling
- Clear, descriptive variable and function names

## Support

- [React Bricks Documentation](https://docs.reactbricks.com/)
- [GitHub Issues](https://github.com/ReactBricks/create-reactbricks-app/issues)
- [React Bricks Dashboard](https://dashboard.reactbricks.com/)