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

npx create-reactbricks-app

Or install globally:

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:

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:

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

2. Install dependencies:

pnpm install

3. Build the project:

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:

{
  "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
• GitHub Issues
• React Bricks Dashboard