feat(web): design overhaul

apps/web/content/docs/cli-commands.mdx

@@ -0,0 +1,462 @@
+---
+title: CLI Commands
+description: Complete reference for all Better-T-Stack CLI commands and options
+---
+
+## Commands Overview
+
+| Command | Description |
+|---------|-------------|
+| `init` (default) | Create a new Better-T-Stack project |
+| `add` | Add addons or deployment configurations to existing projects |
+| `sponsors` | Display project sponsors |
+| `docs` | Open documentation in browser |
+| `builder` | Open web-based stack builder |
+
+---
+
+## `init` - Create Project (Default)
+
+The primary command for creating new Better-T-Stack projects.
+
+### Basic Usage
+
+```bash
+# Interactive setup
+npx create-better-t-stack@latest
+
+# With project name
+npx create-better-t-stack@latest my-project
+
+# With specific directory
+npx create-better-t-stack@latest ./path/to/project
+
+# Use current directory
+npx create-better-t-stack@latest .
+```
+
+### Flags Reference
+
+#### General Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--yes, -y` | boolean | `false` | Skip prompts, use defaults |
+| `--help, -h` | boolean | - | Show help information |
+| `--version, -V` | boolean | - | Show CLI version |
+
+#### Frontend Options
+
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| `--frontend` | Multiple values | `tanstack-router` | Frontend frameworks to include |
+
+**Available Frontend Values:**
+- `tanstack-router` - React with TanStack Router
+- `react-router` - React with React Router
+- `tanstack-start` - React with TanStack Start (SSR)
+- `next` - Next.js framework
+- `nuxt` - Vue.js with Nuxt
+- `svelte` - SvelteKit
+- `solid` - SolidJS
+- `native-nativewind` - React Native with NativeWind
+- `native-unistyles` - React Native with Unistyles
+- `none` - No frontend
+
+**Examples:**
+```bash
+# Single web frontend
+--frontend tanstack-router
+
+# Web + Mobile
+--frontend tanstack-router native-nativewind
+
+# Multiple frontends
+--frontend next solid
+
+# No frontend (API-only)
+--frontend none
+```
+
+#### Backend Options
+
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| `--backend` | Single value | `hono` | Backend framework |
+
+**Available Backend Values:**
+- `hono` - Hono web framework
+- `express` - Express.js
+- `fastify` - Fastify framework
+- `elysia` - Elysia framework
+- `next` - Next.js API routes
+- `convex` - Convex backend-as-a-service
+- `none` - No backend
+
+**Examples:**
+```bash
+--backend hono
+--backend convex
+--backend none
+```
+
+#### Runtime Options
+
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| `--runtime` | Single value | `bun` | Runtime environment |
+
+**Available Runtime Values:**
+- `bun` - Bun runtime
+- `node` - Node.js runtime
+- `workers` - Cloudflare Workers (Hono only)
+- `none` - No runtime (Convex/none backend)
+
+**Examples:**
+```bash
+--runtime bun
+--runtime workers  # Only with --backend hono
+```
+
+#### Database Options
+
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| `--database` | Single value | `sqlite` | Database type |
+
+**Available Database Values:**
+- `sqlite` - SQLite database
+- `postgres` - PostgreSQL
+- `mysql` - MySQL
+- `mongodb` - MongoDB
+- `none` - No database
+
+**Examples:**
+```bash
+--database postgres
+--database none
+```
+
+#### ORM Options
+
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| `--orm` | Single value | `drizzle` | ORM/Database toolkit |
+
+**Available ORM Values:**
+- `drizzle` - Drizzle ORM (TypeScript-first)
+- `prisma` - Prisma ORM (feature-rich)
+- `mongoose` - Mongoose (MongoDB only)
+- `none` - No ORM
+
+**Examples:**
+```bash
+--orm drizzle
+--orm prisma
+--orm none
+```
+
+#### API Layer Options
+
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| `--api` | Single value | `trpc` | API layer type |
+
+**Available API Values:**
+- `trpc` - tRPC (end-to-end type safety)
+- `orpc` - oRPC (OpenAPI compatible)
+- `none` - No API layer
+
+**Examples:**
+```bash
+--api trpc
+--api orpc
+--api none
+```
+
+#### Authentication Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--auth` | boolean | `true` | Enable authentication |
+| `--no-auth` | boolean | - | Disable authentication |
+
+**Examples:**
+```bash
+--auth        # Enable auth
+--no-auth     # Disable auth
+```
+
+#### Addons Options
+
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| `--addons` | Multiple values | `turborepo` | Additional features |
+
+**Available Addon Values:**
+- `turborepo` - Turborepo build system
+- `pwa` - Progressive Web App support
+- `tauri` - Desktop app with Tauri
+- `biome` - Biome linter/formatter
+- `husky` - Git hooks with Husky
+- `starlight` - Documentation site
+- `none` - No addons
+
+**Examples:**
+```bash
+--addons turborepo pwa
+--addons biome husky
+--addons none
+```
+
+#### Examples Options
+
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| `--examples` | Multiple values | `[]` | Example applications |
+
+**Available Example Values:**
+- `todo` - Todo CRUD application
+- `ai` - AI chat interface
+- `none` - No examples
+
+**Examples:**
+```bash
+--examples todo
+--examples todo ai
+--examples none
+```
+
+#### Database Setup Options
+
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| `--db-setup` | Single value | `none` | Database hosting setup |
+
+**Available Database Setup Values:**
+- `turso` - Turso SQLite hosting
+- `neon` - Neon PostgreSQL
+- `supabase` - Supabase PostgreSQL
+- `prisma-postgres` - Prisma PostgreSQL
+- `mongodb-atlas` - MongoDB Atlas
+- `d1` - Cloudflare D1 (Workers only)
+- `docker` - Local Docker setup
+- `none` - Manual setup
+
+**Examples:**
+```bash
+--db-setup neon
+--db-setup docker
+--db-setup none
+```
+
+#### Deployment Options
+
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| `--web-deploy` | Single value | `none` | Web deployment setup |
+
+**Available Deployment Values:**
+- `workers` - Cloudflare Workers
+- `none` - No deployment setup
+
+**Examples:**
+```bash
+--web-deploy workers
+--web-deploy none
+```
+
+#### Project Management Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--git` | boolean | `true` | Initialize git repository |
+| `--no-git` | boolean | - | Skip git initialization |
+| `--install` | boolean | `true` | Install dependencies |
+| `--no-install` | boolean | - | Skip dependency installation |
+| `--package-manager` | string | auto-detect | Package manager to use |
+
+**Package Manager Values:**
+- `npm` - Use npm
+- `pnpm` - Use pnpm
+- `bun` - Use bun
+
+**Examples:**
+```bash
+--git --install --package-manager pnpm
+--no-git --no-install
+```
+
+---
+
+## `add` - Add to Existing Project
+
+Add addons or deployment configurations to existing Better-T-Stack projects.
+
+### Usage
+
+```bash
+# Interactive addon selection
+npx create-better-t-stack@latest add
+
+# Add specific addons
+npx create-better-t-stack@latest add --addons pwa tauri
+
+# Add deployment
+npx create-better-t-stack@latest add --web-deploy workers
+
+# Add both
+npx create-better-t-stack@latest add --addons biome --web-deploy workers
+```
+
+### Flags
+
+| Flag | Values | Description |
+|------|--------|-------------|
+| `--addons` | Multiple values | Addons to add (same as init) |
+| `--web-deploy` | Single value | Deployment to add |
+| `--project-dir` | string | Target project directory (default: current) |
+| `--install` | boolean | Install dependencies after adding |
+| `--no-install` | boolean | Skip dependency installation |
+| `--package-manager` | string | Package manager to use |
+
+### Examples
+
+```bash
+# Add PWA support to current project
+npx create-better-t-stack@latest add --addons pwa
+
+# Add multiple addons with dependency installation
+npx create-better-t-stack@latest add --addons biome husky --install
+
+# Add to specific project directory
+npx create-better-t-stack@latest add --project-dir ./my-project --addons tauri
+```
+
+---
+
+## `sponsors` - View Sponsors
+
+Display Better-T-Stack project sponsors.
+
+### Usage
+
+```bash
+npx create-better-t-stack@latest sponsors
+```
+
+Shows a list of project sponsors with their GitHub profiles and websites.
+
+---
+
+## `docs` - Open Documentation
+
+Open Better-T-Stack documentation in your default browser.
+
+### Usage
+
+```bash
+npx create-better-t-stack@latest docs
+```
+
+Opens: https://better-t-stack.dev/docs
+
+---
+
+## `builder` - Open Stack Builder
+
+Open the web-based interactive stack builder.
+
+### Usage
+
+```bash
+npx create-better-t-stack@latest builder
+```
+
+Opens: https://better-t-stack.dev/new
+
+The web builder provides a visual interface for configuring your stack and generates the corresponding CLI command.
+
+---
+
+## Complete Examples
+
+### Full-Stack Web Application
+
+```bash
+npx create-better-t-stack@latest my-webapp \
+  --frontend tanstack-router \
+  --backend hono \
+  --runtime bun \
+  --database postgres \
+  --orm drizzle \
+  --api trpc \
+  --auth \
+  --db-setup neon \
+  --addons pwa turborepo \
+  --examples todo ai
+```
+
+### Mobile + Web Application
+
+```bash
+npx create-better-t-stack@latest my-mobile-app \
+  --frontend tanstack-router native-nativewind \
+  --backend hono \
+  --database sqlite \
+  --orm drizzle \
+  --auth \
+  --db-setup turso \
+  --addons turborepo
+```
+
+### Cloudflare Workers Project
+
+```bash
+npx create-better-t-stack@latest my-workers-app \
+  --frontend tanstack-router \
+  --backend hono \
+  --runtime workers \
+  --database sqlite \
+  --orm drizzle \
+  --db-setup d1 \
+  --web-deploy workers
+```
+
+### API-Only Project
+
+```bash
+npx create-better-t-stack@latest my-api \
+  --frontend none \
+  --backend fastify \
+  --runtime node \
+  --database postgres \
+  --orm prisma \
+  --api trpc \
+  --db-setup docker
+```
+
+### Quick Defaults
+
+```bash
+# Use all defaults with immediate setup
+npx create-better-t-stack@latest my-project --yes
+
+# Convex full-stack (automatically configures compatible options)
+npx create-better-t-stack@latest my-convex-app --backend convex
+```
+
+---
+
+## Compatibility Notes
+
+Some options have compatibility requirements:
+
+- **Cloudflare Workers**: Only with `--backend hono`, `--orm drizzle`, `--runtime workers`
+- **MongoDB**: Requires `--orm mongoose` or `--orm prisma`
+- **Convex**: Incompatible with custom database/ORM/API options
+- **PWA**: Requires compatible web frontend
+- **Tauri**: Requires compatible web frontend
+- **AI Examples**: Not compatible with `--backend elysia` or `--frontend solid`
+
+The CLI will validate compatibility and show helpful error messages for invalid combinations.