Vercel Deployment

Deploy ZeroStarter to Vercel with zero configuration

Deploy both the Next.js frontend and Hono API to Vercel using the included configuration files.

Prerequisites

• Vercel account
• GitHub repository with your ZeroStarter project
• PostgreSQL database (Vercel Postgres, Neon, or other provider)

Project Structure

ZeroStarter includes Vercel configuration files for both services:

zerostarter/
├── api/hono/
│   └── vercel.json
└── web/next/
    └── vercel.json

Configuration Files

Hono API Configuration

The API service uses this configuration (api/hono/vercel.json):

api/hono/vercel.json

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": "hono",
  "installCommand": "cd ../.. && bun install --ignore-scripts",
  "buildCommand": "cd ../.. && turbo build --filter=@api/hono",
  "outputDirectory": "dist",
  "bunVersion": "1.3.7"
}

The API is configured to use Bun runtime and Turborepo for optimal build performance.

Next.js Configuration

The web service uses this configuration (web/next/vercel.json):

web/next/vercel.json

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": "nextjs",
  "installCommand": "cd ../.. && bun install --ignore-scripts",
  "buildCommand": "cd ../.. && turbo build --filter=@web/next",
  "bunVersion": "1.3.7"
}

Deployment Steps

1. Create Vercel Projects

   Create two separate Vercel projects:

   1. API Project - Point to api/hono directory
   2. Web Project - Point to web/next directory

   You must create separate projects because Vercel doesn’t support monorepo multi-service deployment from a single project.

2. Deploy API Service

   In your Vercel dashboard:

   1. Create a new project
   2. Import your GitHub repository
   3. Set Root Directory to api/hono
   4. Vercel will auto-detect the vercel.json configuration
   5. Configure environment variables (see below)
   6. Deploy

   After deployment, note your API URL (e.g., https://api.yourproject.vercel.app)

3. Deploy Web Service

   In your Vercel dashboard:

   1. Create another new project
   2. Import the same GitHub repository
   3. Set Root Directory to web/next
   4. Configure environment variables (see below)
   5. Use the API URL from the previous step
   6. Deploy

Environment Variables

API Service Environment Variables

Configure these in your API Vercel project:

Required

NODE_ENV=production
BETTER_AUTH_SECRET=your-secret-here
POSTGRES_URL=your-postgres-connection-string
HONO_APP_URL=https://api.yourproject.vercel.app
HONO_TRUSTED_ORIGINS=https://yourproject.vercel.app

Web Service Environment Variables

Configure these in your Web Vercel project:

NEXT_PUBLIC_APP_URL=https://yourproject.vercel.app
NEXT_PUBLIC_API_URL=https://api.yourproject.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

Generate BETTER_AUTH_SECRET using:

openssl rand -base64 32

Database Setup

1. Set up PostgreSQL

   Choose a PostgreSQL provider:

   • Vercel Postgres - Integrated with Vercel
   • Neon - Serverless Postgres with free tier
   • Supabase - Postgres with additional features
   • Railway - Simple deployment platform
2. Run migrations

   Install dependencies and run migrations locally:

   bun install
   bun run db:generate
   bun run db:migrate
   
3. Verify schema

   Use Drizzle Studio to verify your schema:

   bun run db:studio
   

Custom Domains

1. Configure API domain

   In your API Vercel project:

   1. Go to Settings > Domains
   2. Add your API domain (e.g., api.yourdomain.com)
   3. Update HONO_APP_URL environment variable
   4. Redeploy
2. Configure Web domain

   In your Web Vercel project:

   1. Go to Settings > Domains
   2. Add your domain (e.g., yourdomain.com)
   3. Update NEXT_PUBLIC_APP_URL and NEXT_PUBLIC_API_URL variables
   4. Update HONO_TRUSTED_ORIGINS in API project
   5. Redeploy both projects

Continuous Deployment

Vercel automatically deploys when you push to your repository:

• Production - Pushes to main branch
• Preview - Pull requests and other branches

Environment Variables per Branch

Configure different variables for preview deployments:

1. Go to project Settings > Environment Variables
2. Select environment scope:
   • Production
   • Preview
   • Development

Monorepo Build Configuration

Both vercel.json files use Turborepo for efficient builds:

• installCommand: Installs dependencies from monorepo root
• buildCommand: Uses Turbo filters to build only required packages
• --ignore-scripts: Skips postinstall scripts for faster builds

Troubleshooting

Build fails with 'turbo not found'

Ensure turbo is listed in root package.json devDependencies:

package.json

{
  "devDependencies": {
    "turbo": "catalog:"
  }
}

CORS errors in production

Verify HONO_TRUSTED_ORIGINS includes your web URL:

HONO_TRUSTED_ORIGINS=https://yourproject.vercel.app,https://www.yourproject.vercel.app

Separate multiple origins with commas.

Environment variables not updating

After changing environment variables:

1. Go to Deployments
2. Click ”…” on latest deployment
3. Select “Redeploy”
4. Check “Use existing Build Cache” is unchecked

Database connection fails

Check your POSTGRES_URL format:

postgresql://user:password@host:port/database?sslmode=require

Ensure SSL is enabled if required by your provider.

Performance Optimization

Edge Runtime

Hono API runs on Vercel’s Edge Runtime by default, providing:

• Low latency worldwide
• Automatic scaling
• Pay-per-execution pricing

Next.js Configuration

Optimize your Next.js deployment:

next.config.ts

export default {
  // Enable compression
  compress: true,

  // Optimize images
  images: {
    formats: ['image/avif', 'image/webp'],
  },

  // Enable React strict mode
  reactStrictMode: true,
}

Next Steps

Production Checklist

Complete the production readiness checklist

Analytics & Monitoring

Set up PostHog analytics and monitoring