> ## Documentation Index
> Fetch the complete documentation index at: https://docs.builderbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hono + Bun Setup

> This is the **default configuration** for Builder Box. Hono is a lightweight, fast web framework that works excellently with Bun's runtime.

### What You'll Get

* **Backend:** Hono web framework
* **Runtime:** Bun (fast JavaScript runtime)
* **Bundler:** Bun's built-in bundler
* **Performance:** Excellent startup time and memory usage
* **Structure:** Separate server and web applications

***

## Prerequisites

Before starting, ensure you have:

* [Bun](https://bun.sh) v1.0+ installed
* [Git](https://git-scm.com/) for version control
* Access to your Builder Box dashboard

***

## Step 1: Project Setup

### 1.1 Access Your Dashboard

1. **Visit the Dashboard**

   * Go to: [https://www.builderbox.ai/bought/main](https://www.builderbox.ai/bought/main)
   * Log in with your account credentials

2. **Create Your Project**

   * Click **"Create Project"** on your dashboard
   * Select **"Hono + Bun"** as your backend configuration
   * Fill out the project configuration form
   * Click **"Create Project"** to generate your boilerplate

3. **Install Your Project**
   * Run the provided installation command:
     ```bash theme={null}
     npm install -g @humanoidz/builderbox && builderbox YOUR_PROJECT_ID
     ```

***

## Step 2: Environment Configuration

### 2.1 Server Environment Variables

Create `apps/server/.env`:

```env theme={null}
# Database
DATABASE_URL=your_supabase_transaction_pooler_url
DIRECT_URL=your_supabase_session_pooler_url

# Authentication
BETTER_AUTH_SECRET=your_generated_secret
BETTER_AUTH_URL=http://localhost:3000
CORS_ORIGIN=http://localhost:3001

# Google OAuth
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

# Email
RESEND_API_KEY=re_your_api_key

# Payments
STRIPE_SECRET_KEY=sk_test_your_secret_key
STRIPE_TEST_PRODUCT=price_your_price_id
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret

# AI
OPENROUTER_API_KEY=your_openrouter_api_key
```

### 2.2 Web Environment Variables

Create `apps/web/.env`:

```env theme={null}
NEXT_PUBLIC_SERVER_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3001
PAYLOAD_PUBLIC_SERVER_URL=http://localhost:3003
```

### 2.3 CMS Environment Variables

Create `apps/cms/.env`:

```env theme={null}
DATABASE_URI=your_cms_supabase_url
PAYLOAD_SECRET=your_generated_cms_secret
```

***

## Step 3: Database Setup

### 3.1 Run Database Commands

```bash theme={null}
# Navigate to the project root
cd your-project-name

# Generate Prisma client
bun run db:generate

# Create initial migration
bun run db:migrate

# Push schema changes
bun run db:push
```

***

## Step 4: Start Development

### 4.1 Start All Services

```bash theme={null}
# From the root directory
bun dev
```

This will start:

* **Backend Server (Hono)** on port 3000
* **Frontend App (Next.js)** on port 3001
* **CMS** on port 3003

### 4.2 Individual Services (Optional)

If you prefer to run services separately:

**Terminal 1 - Backend Server:**

```bash theme={null}
cd apps/server
bun dev
```

**Terminal 2 - Frontend App:**

```bash theme={null}
cd apps/web
bun dev
```

**Terminal 3 - CMS:**

```bash theme={null}
cd apps/cms
bun dev
```

***

## Step 5: Verify Setup

### 5.1 Check Services

* **Frontend:** [http://localhost:3001](http://localhost:3001)
* **Backend API:** [http://localhost:3000](http://localhost:3000)
* **CMS:** [http://localhost:3003](http://localhost:3003)

### 5.2 Test API Endpoints

```bash theme={null}
# Health check
curl http://localhost:3000/trpc/healthCheck

# Should return: {"message":"OK"}
```

***

## Project Structure

```
your-project/
├── apps/
│   ├── server/          # Hono backend
│   │   ├── src/
│   │   │   ├── index.ts # Main server file
│   │   │   ├── routers/ # tRPC routers
│   │   │   └── lib/     # Utilities
│   │   └── package.json
│   ├── web/             # Next.js frontend
│   │   ├── src/
│   │   │   ├── app/     # Next.js app router
│   │   │   └── lib/     # Utilities
│   │   └── package.json
│   └── cms/             # Payload CMS
│       ├── src/
│       └── package.json
├── packages/            # Shared packages
└── package.json         # Root package.json
```

***

## Key Features

### Hono Backend Benefits

* **Lightweight:** Minimal overhead and fast startup
* **Type Safety:** Full TypeScript support
* **Middleware:** Rich middleware ecosystem
* **Performance:** Excellent request handling
* **Compatibility:** Works with any Node.js-compatible runtime

### Bun Runtime Benefits

* **Speed:** Faster startup and execution
* **Memory:** Lower memory usage
* **Bundler:** Built-in bundler for production builds
* **Compatibility:** Full Node.js compatibility
* **Developer Experience:** Fast package installation

***

## Development Commands

| Command           | Description            |
| ----------------- | ---------------------- |
| `bun dev`         | Start all services     |
| `bun build`       | Build for production   |
| `bun dev:web`     | Frontend only          |
| `bun dev:server`  | Backend only           |
| `bun check-types` | TypeScript validation  |
| `bun db:push`     | Update database schema |
| `bun db:studio`   | Database management UI |

***

## Troubleshooting

### Common Issues

**🔥 "Bun not found"**

```bash theme={null}
# Install Bun
curl -fsSL https://bun.sh/install | bash
```

**🔥 "Port already in use"**

```bash theme={null}
# Kill existing processes
lsof -ti:3000 | xargs kill -9
lsof -ti:3001 | xargs kill -9
```

**🔥 "Database connection failed"**

* Verify your Supabase connection strings
* Ensure your database is running
* Check environment variables

**🔥 "Authentication not working"**

* Verify Google OAuth configuration
* Check BETTER\_AUTH\_SECRET is set
* Ensure CORS\_ORIGIN is correct

***

## Next Steps

🎉 **Congratulations!** Your Hono + Bun setup is complete. Here's what you can do next:

1. **Customize the frontend** - Edit components in `apps/web/src/components`
2. **Add API endpoints** - Create new routes in `apps/server/src/routers`
3. **Configure CMS** - Add content types in `apps/cms/src/collections`
4. **Set up production** - Deploy to Vercel, Railway, or your preferred platform
5. **Add features** - Extend with additional integrations

**Happy building!** 🚀