Skip to main content

​
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 v1.0+ installed
  • Git for version control
  • Access to your Builder Box dashboard

​
Step 1: Project Setup

​
1.1 Access Your Dashboard

  1. Visit the Dashboard
  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: 
      npm install -g @humanoidz/builderbox && builderbox YOUR_PROJECT_ID

​
Step 2: Environment Configuration

​
2.1 Server Environment Variables

Create apps/server/.env: 
# 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: 
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: 
DATABASE_URI=your_cms_supabase_url
PAYLOAD_SECRET=your_generated_cms_secret

​
Step 3: Database Setup

​
3.1 Run Database Commands

# 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

# 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: 
cd apps/server
bun dev
Terminal 2 - Frontend App: 
cd apps/web
bun dev
Terminal 3 - CMS: 
cd apps/cms
bun dev

​
Step 5: Verify Setup

​
5.1 Check Services

​
5.2 Test API Endpoints

# 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

CommandDescription
bun devStart all services
bun buildBuild for production
bun dev:webFrontend only
bun dev:serverBackend only
bun check-typesTypeScript validation
bun db:pushUpdate database schema
bun db:studioDatabase management UI

​
Troubleshooting

​
Common Issues

🔥 “Bun not found” 
# Install Bun
curl -fsSL https://bun.sh/install | bash
🔥 “Port already in use” 
# 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! 🚀