NextAPI + Node Setup

​

What You’ll Get

• Backend: Next.js API routes
• Runtime: Node.js
• Bundler: Webpack (Next.js default)
• Performance: Standard Node.js performance
• Structure: API routes within Next.js app

​

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 “NextAPI + 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:
     npm install -g @humanoidz/builderbox && builderbox YOUR_PROJECT_ID
     

​

Step 2: Environment Configuration

​

2.1 Web Environment Variables (Combined)

# 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:3001
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

# Frontend Configuration
NEXT_PUBLIC_SERVER_URL=http://localhost:3001
NEXT_PUBLIC_APP_URL=http://localhost:3001
PAYLOAD_PUBLIC_SERVER_URL=http://localhost:3003

​

2.2 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 run dev

• Frontend App (Next.js + API routes) on port 3001
• CMS on port 3003

​

4.2 Individual Services (Optional)

cd apps/web
pnpm run dev

cd apps/cms
pnpm run dev

​

Step 5: Verify Setup

​

5.1 Check Services

• Frontend + API: http://localhost:3001
• CMS: http://localhost:3003

​

5.2 Test API Endpoints

# Health check
curl http://localhost:3001/api/trpc/healthCheck

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

​

Project Structure

your-project/
├── apps/
│   ├── web/             # Next.js frontend + API routes
│   │   ├── src/
│   │   │   ├── app/     # Next.js app router
│   │   │   │   └── api/ # API routes
│   │   │   └── lib/     # Utilities
│   │   └── package.json
│   └── cms/             # Payload CMS
│       ├── src/
│       └── package.json
├── packages/            # Shared packages
└── package.json         # Root package.json

​

Key Features

​

Next.js API Routes Benefits

• Unified Codebase: Frontend and backend in one project
• Type Safety: Full TypeScript support
• Middleware: Next.js middleware support
• Deployment: Easy deployment to Vercel
• Familiarity: Standard Next.js patterns

​

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

​

Environment Variables Management

​

Important Notes

1. Single Environment File: All variables are in apps/web/.env
2. API Routes Access: Environment variables are accessible in API routes
3. Client Variables: Use NEXT_PUBLIC_ prefix for client-side variables
4. Security: Never expose sensitive variables to the client

​

Variable Categories

# Server-side only (not exposed to client)
DATABASE_URL=...
BETTER_AUTH_SECRET=...
STRIPE_SECRET_KEY=...

# Client-side accessible
NEXT_PUBLIC_APP_URL=...
NEXT_PUBLIC_SERVER_URL=...

​

Troubleshooting

​

Common Issues

• Ensure all variables are in apps/web/.env
• Check for typos in variable names
• Restart the development server

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

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

• Verify your Supabase connection strings
• Ensure your database is running
• Check environment variables in apps/web/.env

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

​

Migration from Hono

1. Copy Environment Variables:
   # Copy all variables from server/.env to web/.env
   cp apps/server/.env apps/web/.env
   
2. Update URLs:
   # Change from localhost:3000 to localhost:3001
   BETTER_AUTH_URL=http://localhost:3001
   NEXT_PUBLIC_SERVER_URL=http://localhost:3001
   
3. Update API Calls:
   // Change from /trpc/ to /api/trpc/
   const result = await trpc.healthCheck.query();
   

​

Next Steps

1. Customize the frontend - Edit components in apps/web/src/components
2. Add API endpoints - Create new routes in apps/web/src/app/api
3. Configure CMS - Add content types in apps/cms/src/collections
4. Set up production - Deploy to Vercel for optimal performance
5. Add features - Extend with additional integrations