> ## 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 + Node Setup

> This configuration uses the Hono web framework with Node.js runtime. It provides the lightweight benefits of Hono with the familiar Node.js ecosystem.

### What You'll Get

* **Backend:** Hono web framework
* **Runtime:** Node.js
* **Bundler:** Webpack or esbuild
* **Performance:** Good performance with Node.js
* **Structure:** Separate server and web applications

***

## Prerequisites

Before starting, ensure you have:

* [Node.js](https://nodejs.org/) v18+ 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 + Node"** 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
pnpm run db:generate

# Create initial migration
pnpm run db:migrate

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

***

## Step 4: Start Development

### 4.1 Start All Services

```bash theme={null}
# From the root directory
pnpm install
pnpm run 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
pnpm run dev
```

**Terminal 2 - Frontend App:**

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

**Terminal 3 - CMS:**

```bash theme={null}
cd apps/cms
pnpm run 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

### Node.js Runtime Benefits

* **Ecosystem:** Full Node.js package ecosystem
* **Compatibility:** Works with all Node.js libraries
* **Stability:** Mature and well-tested runtime
* **Tooling:** Rich development tooling
* **Community:** Large community support

***

## Development Commands

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

***

## Bundler Configuration

### Webpack Configuration

The project uses webpack for bundling the Hono server:

```javascript theme={null}
// apps/server/webpack.config.js
module.exports = {
  target: "node",
  entry: "./src/index.ts",
  module: {
    rules: [
      {
        test: /\.ts$/,
        use: "ts-loader",
        exclude: /node_modules/,
      },
    ],
  },
  resolve: {
    extensions: [".ts", ".js"],
  },
};
```

### Build Process

```bash theme={null}
# Build the server
cd apps/server
pnpm run build

# The built server will be in dist/index.js
```

***

## Performance Considerations

### Node.js vs Bun

| Aspect                  | Node.js | Bun   |
| ----------------------- | ------- | ----- |
| Startup Time            | ⭐⭐⭐     | ⭐⭐⭐⭐⭐ |
| Memory Usage            | ⭐⭐⭐     | ⭐⭐⭐⭐⭐ |
| Package Installation    | ⭐⭐⭐     | ⭐⭐⭐⭐⭐ |
| Ecosystem Compatibility | ⭐⭐⭐⭐⭐   | ⭐⭐⭐⭐  |

### Optimization Tips

1. **Use PM2 for Production:**

   ```bash theme={null}
   pnpm install -g pm2
   pm2 start dist/index.js --name "hono-server"
   ```

2. **Enable Compression:**

   ```typescript theme={null}
   import { compress } from "hono/compress";
   app.use("*", compress());
   ```

3. **Use Environment-Specific Configs:**
   ```typescript theme={null}
   const isDev = process.env.NODE_ENV === "development";
   const port = process.env.PORT || 3000;
   ```

***

## Troubleshooting

### Common Issues

**🔥 "Node.js not found"**

```bash theme={null}
# Install Node.js
# Visit https://nodejs.org/ and download the LTS version
```

**🔥 "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

**🔥 "Build errors"**

```bash theme={null}
# Clear node_modules and reinstall
rm -rf node_modules
pnpm install --force
```

***

## Migration from Bun

If you're migrating from Bun to Node.js:

1. **Update Package Manager:**

   ```bash theme={null}
   # Replace bun commands with npm
   bun install → npm install
   bun run dev → npm run dev
   ```

2. **Update Scripts:**

   ```json theme={null}
   {
     "scripts": {
       "dev": "tsx watch src/index.ts",
       "build": "webpack --mode production",
       "start": "node dist/index.js"
     }
   }
   ```

3. **Install Dependencies:**
   ```bash theme={null}
   pnpm install tsx webpack webpack-cli ts-loader
   ```

***

## Next Steps

🎉 **Congratulations!** Your Hono + Node 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 Railway, DigitalOcean, or your preferred platform
5. **Add features** - Extend with additional integrations

**Happy building!** 🚀