Local Development

This guide covers local development for the API, web app, and docs site. Ports are fixed to match production defaults.

Prerequisites

• Install dependencies: bun install
• Wrangler env files live in apps/server/.dev.vars and apps/web/.dev.vars

Quick Start (Node.js)

The fastest way to develop locally using Next.js and Bun dev servers:

# Start all apps in parallel
bun run dev

• API: http://localhost:3000
• Web: http://localhost:3001

Run in Workers Runtime (Cloudflare)

Use this to test your app in the actual Cloudflare Workers runtime before deploying.

Web (Next.js + OpenNext)

# Production config
bun --cwd apps/web run preview

# Staging config
bun --cwd apps/web run preview:staging

• URL: http://localhost:8787

The preview command builds with OpenNext and starts wrangler dev.

API (Hono)

bun --cwd apps/server run preview

• URL: http://localhost:3000

Docs (Fumadocs)

bun --cwd apps/fumadocs run preview

• URL: http://localhost:4000

Production Builds (Node.js)

Build and run production bundles locally without Cloudflare:

API build

bun --cwd apps/server run build
bun --cwd apps/server run start

Web build

bun --cwd apps/web run build
bun --cwd apps/web run start

Docs build

bun --cwd apps/fumadocs run build
bun --cwd apps/fumadocs run start

Environment Files

For local Wrangler development, create .dev.vars files:

apps/server/.dev.vars

DATABASE_URL=postgresql://...
BETTER_AUTH_SECRET=your-secret
BETTER_AUTH_URL=http://localhost:3000
CORS_ORIGIN=http://localhost:3001

apps/web/.dev.vars

NEXT_PUBLIC_SERVER_URL=http://localhost:3000

See Cloudflare Deployment for the full list of environment variables.