Deploy at Vercel

Overview

ZeroStarter can be deployed to Vercel for both the frontend (Next.js) and backend (Hono) applications. This guide covers the deployment configuration for both parts of the application.

Prerequisites

1. A Vercel account
2. Your repository pushed to GitHub, GitLab, or Bitbucket
3. A PostgreSQL database (e.g., Neon, Supabase, or Railway)

Frontend Deployment

Configuration

Each workspace includes a vercel.json with the correct install, build, and framework settings. Vercel reads this automatically when you set the root directory.

Environment Variables

.env.example is the source of truth for the full variable set. Add at least these in Vercel project settings:

NODE_ENV=production
NEXT_PUBLIC_APP_URL=https://your-frontend-domain.vercel.app
NEXT_PUBLIC_API_URL=https://your-backend-domain.vercel.app

# Optional: Analytics
NEXT_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com
NEXT_PUBLIC_POSTHOG_KEY=your_posthog_key

# Optional: Feedback
NEXT_PUBLIC_USERJOT_URL=your_userjot_url

NEXT_PUBLIC_NODE_ENV is required by the web env schema but is derived automatically from NODE_ENV, so you do not set it as a separate variable.

Backend Deployment

Configuration

Migrations on deploy

The backend build command runs .github/scripts/migrate-on-deploy.ts before building. That script applies pending migrations with bun run db:migrate, but only when VERCEL_ENV=production or VERCEL_GIT_COMMIT_REF=canary; PR previews skip it (an unmerged migration must not run against the shared database). Because the migration runs at build time, production and canary builds need a reachable POSTGRES_URL available during the build.

Environment Variables

.env.example is the source of truth for the full variable set. Add at least these in Vercel project settings:

NODE_ENV=production
HONO_APP_URL=https://your-backend-domain.vercel.app
HONO_TRUSTED_ORIGINS=https://your-frontend-domain.vercel.app
BETTER_AUTH_SECRET=your_secret_key
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
POSTGRES_URL=your_postgres_connection_string

HONO_PORT exists in the env schema (default 4000) but is unused on Vercel, where the serverless runtime manages the port, so there is no need to set it.

Deployment Steps

Frontend and backend must be deployed as two separate Vercel projects. Each project has its own configuration, environment variables, and deployment lifecycle.

Backend Project (deploy first)

1. Go to Vercel dashboard and click "Add New Project"
2. Select your ZeroStarter repository
3. Set Root Directory to api/hono
4. Add backend environment variables (see above)
5. Click "Deploy"
6. Copy the deployment URL (e.g., https://your-api.vercel.app)

Frontend Project

1. Go to Vercel dashboard and click "Add New Project"
2. Select the same ZeroStarter repository
3. Set Root Directory to web/next
4. Add frontend environment variables, using the backend URL from step 6 above for NEXT_PUBLIC_API_URL
5. Click "Deploy"

Custom Domains

After deployment, configure custom domains:

1. Go to your project settings in Vercel
2. Navigate to "Domains"
3. Add your custom domain
4. Update DNS records as instructed
5. Update environment variables with the new domain URLs

Notes

• Deploy the backend first to get the API URL for the frontend environment variables
• Make sure to update OAuth callback URLs in GitHub/Google with your production domains
• For production, use a managed PostgreSQL service with connection pooling