Hono + Node Setup

​

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

• Node.js v18+ installed
• Git 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
   • 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:
     Copy

     npm install -g @humanoidz/builderbox && builderbox YOUR_PROJECT_ID
     

​

Step 2: Environment Configuration

​

2.1 Server Environment Variables

# 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

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

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

# From the root directory
pnpm install
pnpm run dev

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

​

4.2 Individual Services (Optional)

cd apps/server
pnpm run dev

cd apps/web
pnpm run dev

cd apps/cms
pnpm run dev

​

Step 5: Verify Setup

​

5.1 Check Services

• Frontend: http://localhost:3001
• Backend API: http://localhost:3000
• CMS: http://localhost:3003

​

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

​

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

​

Bundler Configuration

​

Webpack Configuration

// 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

# Build the server
cd apps/server
pnpm run build

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

​

Performance Considerations

​

Node.js vs Bun

​

Optimization Tips

1. Use PM2 for Production:
   Copy

   pnpm install -g pm2
   pm2 start dist/index.js --name "hono-server"
   

2. Enable Compression:
   Copy

   import { compress } from "hono/compress";
   app.use("*", compress());
   

3. Use Environment-Specific Configs:
   Copy

   const isDev = process.env.NODE_ENV === "development";
   const port = process.env.PORT || 3000;
   

​

Troubleshooting

​

Common Issues

# Install Node.js
# Visit https://nodejs.org/ and download the LTS version

# Kill existing processes
lsof -ti:3000 | xargs kill -9
lsof -ti:3001 | xargs kill -9

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

• Verify Google OAuth configuration
• Check BETTER_AUTH_SECRET is set
• Ensure CORS_ORIGIN is correct

# Clear node_modules and reinstall
rm -rf node_modules
pnpm install --force

​

Migration from Bun

1. Update Package Manager:
   Copy

   # Replace bun commands with npm
   bun install → npm install
   bun run dev → npm run dev
   

2. Update Scripts:
   Copy

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

3. Install Dependencies:
   Copy

   pnpm install tsx webpack webpack-cli ts-loader
   

​

Next Steps

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