Skip to main content
This guide covers deploying Echoes of the Past to Vercel, including build configuration, environment setup, and production best practices.

​
Prerequisites

Before deploying, ensure you have:
  • A Vercel account
  • All required API keys and credentials (see Environment Variables)
  • Access to your Git repository (GitHub, GitLab, or Bitbucket)
  • Supabase project configured
  • Vapi AI account with web token
  • ElevenLabs API key
  • OpenAI API key
  • Upstash Redis instance

​
Build Configuration

The application uses Next.js 15 with the following build configuration:

​
Build Command

npm run build
This executes next build which:
  • Compiles TypeScript to JavaScript
  • Bundles and optimizes all pages and components
  • Generates static assets
  • Creates optimized production builds
  • Validates environment variables required at build time

​
Build Requirements

The following environment variables are required at build time and will cause the build to fail if not set:
  • NEXT_PUBLIC_SUPABASE_URL
  • NEXT_PUBLIC_VAPI_WEB_TOKEN
  • OPENAI_API_KEY
These are validated in next.config.ts:3 and various lib files during the build process.

​
Deploying to Vercel

1

Connect Repository

  1. Log in to Vercel Dashboard
  2. Click “Add New Project”
  3. Import your Git repository
  4. Select the repository containing Echoes of the Past
2

Configure Build Settings

Vercel auto-detects Next.js projects. Verify these settings:
  • Framework Preset: Next.js
  • Build Command: npm run build
  • Output Directory: .next (default)
  • Install Command: npm install
  • Node Version: 20.x or higher
3

Set Environment Variables

Add all required environment variables in the Vercel project settings:
  1. Navigate to “Settings” → “Environment Variables”
  2. Add each variable from the Environment Variables reference
  3. Set appropriate values for Production, Preview, and Development environments
Use different values for production and preview environments, especially for sensitive credentials and API endpoints.
4

Deploy

Click “Deploy” to start your first deployment. Vercel will:
  • Install dependencies
  • Run the build command
  • Deploy to a production URL
  • Set up automatic deployments for future commits

​
Method 2: Vercel CLI

For manual deployments or CI/CD pipelines: 
# Install Vercel CLI
npm i -g vercel

# Login to Vercel
vercel login

# Deploy to preview
vercel

# Deploy to production
vercel --prod

​
Environment Variables in Production

​
Setting Variables

Environment variables can be set in multiple ways: Via Vercel Dashboard: 
Project Settings → Environment Variables → Add New
Via Vercel CLI: 
vercel env add VARIABLE_NAME
Via vercel.json (not recommended for secrets): 
{
  "env": {
    "NEXT_PUBLIC_APP_URL": "https://echoes-of-the-past.vercel.app"
  }
}

​
Environment Scopes

Set different values for each environment:
  • Production: Used for vercel --prod deployments
  • Preview: Used for branch and PR deployments
  • Development: Used locally with vercel dev
Security Best Practice: Never commit .env files to version control. Use Vercel’s environment variable system for all deployments.

​
Domain Configuration

​
Adding a Custom Domain

1

Add Domain in Vercel

  1. Go to Project Settings → Domains
  2. Enter your custom domain (e.g., echoes.yourdomain.com)
  3. Click “Add”
2

Configure DNS

Add DNS records at your domain provider:For root domain:
Type: A
Name: @
Value: 76.76.21.21
For subdomain:
Type: CNAME
Name: echoes
Value: cname.vercel-dns.com
3

Update Environment Variables

Update NEXT_PUBLIC_APP_URL to match your custom domain:
NEXT_PUBLIC_APP_URL=https://echoes.yourdomain.com
4

Verify SSL

Vercel automatically provisions SSL certificates. Verify:
  • Certificate shows as “Active” in domain settings
  • Site loads with HTTPS
  • No mixed content warnings

​
Image Optimization

The application is configured to serve images from multiple sources (see next.config.ts:8-64):
  • Supabase Storage
  • CDN providers (Midjourney, Unsplash, etc.)
  • Wikipedia media
Vercel automatically optimizes these images using Next.js Image Optimization.
Image optimization is included in Vercel’s Pro plan and above. On the Hobby plan, you get 1,000 source images optimized per month.

​
Monitoring Setup

​
Vercel Analytics

The application includes Vercel Analytics (see app/layout.tsx:40): 
import { Analytics } from '@vercel/analytics/next'

<Analytics />
This provides:
  • Real-time visitor analytics
  • Page view tracking
  • Performance metrics
  • Web Vitals monitoring

​
Umami Analytics

Production deployments also include Umami analytics (see app/layout.tsx:43): 
{process.env.NODE_ENV === 'production' && (
  <Script 
    defer 
    src="https://cloud.umami.is/script.js" 
    data-website-id="e2be9698-2b5e-432b-b846-a02a0a9b7733" 
  />
)}

​
Custom Monitoring

For additional monitoring, consider:
  • Error Tracking: Sentry, LogRocket, or Datadog
  • Performance: Vercel Speed Insights
  • Uptime: UptimeRobot, Pingdom
  • Logs: Vercel Logs or external log aggregation

​
Production Checklist

Before going live, verify:
1

Environment Variables

  • All required variables set in Vercel
  • Production API keys (not test/development keys)
  • NEXT_PUBLIC_APP_URL matches production domain
  • Redis credentials point to production instance
  • Supabase points to production project
2

Authentication

  • Google OAuth configured with production callback URL
  • Supabase auth providers enabled
  • Redirect URLs whitelist updated
3

APIs & Services

  • Vapi AI production token configured
  • ElevenLabs API key with sufficient quota
  • OpenAI API key with appropriate rate limits
  • Upstash Redis production instance
4

Performance

  • Build completes without warnings
  • No console errors in production
  • Images load and optimize correctly
  • Voice calls connect successfully
5

Security

  • HTTPS enabled with valid certificate
  • CORS configured correctly
  • API keys secured and not exposed
  • Rate limiting configured in Redis

​
Continuous Deployment

Vercel automatically deploys:
  • Production: Commits to main branch
  • Preview: Pull requests and other branches

​
Deployment Protection

Configure deployment protection for production:
  1. Go to Project Settings → Git
  2. Enable “Production Branch” protection
  3. Require approval for production deployments (optional)

​
Build Performance

Optimize build times: 
// package.json
{
  "scripts": {
    "build": "next build",
    "postinstall": "prisma generate" // if using Prisma
  }
}
Vercel caches:
  • node_modules (if package.json unchanged)
  • Next.js build cache
  • npm/yarn global cache

​
Troubleshooting

​
Build Failures

Error: Environment variable not set 
Error: NEXT_PUBLIC_SUPABASE_URL is not set
Solution: Add the missing variable in Vercel project settings. Error: TypeScript compilation failed Solution: Run npm run build locally to identify and fix type errors.

​
Runtime Issues

OAuth callback fails Verify:
  • NEXT_PUBLIC_APP_URL matches your domain
  • Callback URL registered in Google Console: https://yourdomain.com/auth/callback
  • Supabase redirect URLs include production domain
Voice calls not connecting Check:
  • NEXT_PUBLIC_VAPI_WEB_TOKEN is set correctly
  • NEXT_PUBLIC_SERVER_URL points to production webhook endpoint
  • ElevenLabs API key is valid and has quota
Redis connection errors Verify:
  • UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN are correct
  • Redis instance is accessible from Vercel’s network
  • Instance has not hit connection limits

​
Rollback Strategy

If issues occur in production:

​
Instant Rollback

  1. Go to Deployments tab in Vercel
  2. Find the last working deployment
  3. Click “Promote to Production”

​
Via CLI

# List deployments
vercel ls

# Promote specific deployment
vercel promote [deployment-url]

​
Next Steps

  • Review Environment Variables reference
  • Set up monitoring and alerts
  • Configure backup strategies
  • Implement CI/CD testing pipelines
  • Review Vercel usage and quotas

Build docs developers (and LLMs) love

Get started for freeTalk to us