Vercel Deployment Guide for do.dev Monorepo

This guide covers deploying applications from the do.dev monorepo to Vercel with Convex backend.

Prerequisites

1. A Vercel account
2. A Convex account and project
3. The repository connected to Vercel
4. Convex CLI installed locally

Deployment Architecture

• Frontend: Next.js apps deployed to Vercel
• Backend: Convex (serverless functions and database)
• Monorepo: Turborepo with pnpm workspaces

Environment Variables

Required for All Apps

# Convex Deployment URL (from Convex dashboard)
NEXT_PUBLIC_CONVEX_URL="https://your-project.convex.cloud"

# Auth.js Secret (generate with: openssl rand -base64 32)
AUTH_SECRET="your-auth-secret"

# Google OAuth (if using)
AUTH_GOOGLE_ID="your-google-client-id"
AUTH_GOOGLE_SECRET="your-google-client-secret"

# PostHog Analytics (optional)
NEXT_PUBLIC_POSTHOG_KEY="your-posthog-key"
NEXT_PUBLIC_POSTHOG_HOST="https://us.i.posthog.com"

App-Specific Variables

For DNS Management:

TECHNITIUM_DNS_URL="http://10.3.3.3:5380"
TECHNITIUM_USERNAME="admin"
TECHNITIUM_PASSWORD="your-password"

Step-by-Step Deployment

1. Deploy Convex Backend

# Navigate to the tools/convex directory
cd tools/convex

# Deploy to production
npx convex deploy

2. Import Project to Vercel

1. Go to https://vercel.com/new
2. Import your GitHub repository
3. Select the root directory (monorepo root)

3. Configure Build Settings

Create a vercel.json in the monorepo root:

{
  "buildCommand": "pnpm --filter <app-name> build",
  "outputDirectory": "apps/webs/<app-name>/.next",
  "installCommand": "pnpm install",
  "framework": "nextjs"
}

Replace <app-name> with your specific app (e.g., dodev, promptnow, etc.)

4. Add Environment Variables

In Vercel Project Settings > Environment Variables:

1. Add all required variables
2. Ensure they're set for all environments (Production, Preview, Development)
3. Copy the NEXT_PUBLIC_CONVEX_URL from your Convex dashboard

5. Deploy

Click Deploy. The build process will:

1. Install dependencies with pnpm
2. Build the specific Next.js app
3. Deploy to Vercel's edge network

Monorepo-Specific Configuration

Deploying Multiple Apps

For each app in the monorepo:

1. Create a new Vercel project
2. Use the same repository but different build commands:

// For dodev app
{
  "buildCommand": "pnpm --filter dodev build",
  "outputDirectory": "apps/webs/dodev/.next"
}

// For promptnow app
{
  "buildCommand": "pnpm --filter promptnow build",
  "outputDirectory": "apps/webs/promptnow/.next"
}

Root Directory Configuration

If Vercel has issues with the monorepo structure:

1. Go to Project Settings
2. Set Root Directory to: apps/webs/<app-name>
3. Update build command to just: pnpm build
4. Set output directory to: .next

Troubleshooting

Build Failures

1. "Module not found" errors

   • Ensure all workspace dependencies are properly linked
   • Check that pnpm install runs from the monorepo root

2. "NEXT_PUBLIC_CONVEX_URL is not defined"

   • Add the environment variable in Vercel dashboard
   • Redeploy after adding variables

3. Build timeouts

   • Consider using Vercel's build cache
   • Optimize build by excluding unused workspaces

Convex Connection Issues

1. "Failed to connect to Convex"

   • Verify NEXT_PUBLIC_CONVEX_URL is correct
   • Ensure Convex project is deployed
   • Check that the URL includes https://

2. Authentication failures

   • Verify AUTH_SECRET matches across environments
   • Ensure OAuth redirect URLs are configured for Vercel domains

Performance Optimization

Build Caching

Add to vercel.json:

{
  "buildCommand": "pnpm --filter <app-name> build",
  "outputDirectory": "apps/webs/<app-name>/.next",
  "installCommand": "pnpm install --frozen-lockfile"
}

Ignored Build Step

For apps that don't change often, add:

{
  "github": {
    "silent": true
  },
  "ignoreCommand": "git diff HEAD^ HEAD --quiet -- apps/webs/<app-name>"
}

Production Checklist

• Environment variables set for production
• Convex backend deployed
• Custom domain configured (if applicable)
• Preview deployments working
• Build optimizations applied
• Error tracking configured (e.g., Sentry)
• Analytics configured (PostHog)

Security Considerations

1. Environment Variables

   • Never commit .env files
   • Use Vercel's encrypted environment variables
   • Rotate AUTH_SECRET regularly

2. API Keys

   • Limit OAuth redirect URLs to your Vercel domains
   • Use environment-specific API keys

3. Branch Protection

   • Enable protection for main/production branches
   • Require PR reviews before deployment

Monitoring

After deployment:

• Monitor build times in Vercel dashboard
• Check Function logs for API errors
• Monitor Convex dashboard for backend performance
• Use Vercel Analytics for frontend metrics

Common Patterns

Deploying Preview Branches

Vercel automatically creates preview deployments for PRs. Ensure:

1. Preview environment variables are set
2. Convex has a dev/preview instance (optional)
3. OAuth providers accept preview URLs

Rollback Strategy

1. Use Vercel's instant rollback feature
2. Convex maintains version history
3. Keep environment variables versioned

For app-specific deployment instructions, see the README in each app's directory.