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

# NextAPI + Node Setup

> This configuration uses Next.js API routes as the backend with Node.js runtime. The key difference is that all server environment variables need to be copied to the web application.

<Warning>
  **Important:** For NextAPI configurations, you need to copy all variables from
  `server/.env` to `web/.env` because the API routes run within the Next.js
  application.
</Warning>

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

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 **"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:
     ```bash theme={null}
     npm install -g @humanoidz/builderbox && builderbox YOUR_PROJECT_ID
     ```

***

## Step 2: Environment Configuration

### 2.1 Web Environment Variables (Combined)

Create `apps/web/.env` with **ALL** environment variables:

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

<Info>
  **Key Difference:** Unlike Hono configurations, all environment variables are
  in `apps/web/.env` because the API routes run within the Next.js application.
</Info>

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

This will start:

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

### 4.2 Individual Services (Optional)

If you prefer to run services separately:

**Terminal 1 - Frontend + API:**

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

**Terminal 2 - CMS:**

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

***

## Step 5: Verify Setup

### 5.1 Check Services

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

### 5.2 Test API Endpoints

```bash theme={null}
# 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

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

***

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

```env theme={null}
# 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

**🔥 "Environment variables not found"**

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

**🔥 "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:3001 | xargs kill -9
```

**🔥 "Database connection failed"**

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

**🔥 "Authentication not working"**

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

***

## Migration from Hono

If you're migrating from a Hono setup:

1. **Copy Environment Variables:**

   ```bash theme={null}
   # Copy all variables from server/.env to web/.env
   cp apps/server/.env apps/web/.env
   ```

2. **Update URLs:**

   ```env theme={null}
   # Change from localhost:3000 to localhost:3001
   BETTER_AUTH_URL=http://localhost:3001
   NEXT_PUBLIC_SERVER_URL=http://localhost:3001
   ```

3. **Update API Calls:**
   ```typescript theme={null}
   // Change from /trpc/ to /api/trpc/
   const result = await trpc.healthCheck.query();
   ```

***

## Next Steps

🎉 **Congratulations!** Your NextAPI + 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/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

**Happy building!** 🚀