Vercel Deployment Guide

This document explains how to deploy the project to Vercel platform.

Prerequisites

1. Vercel Account: Register at vercel.com
2. Vercel CLI: Install Vercel command line tool
3. Environment Variables: Prepare production environment variables

Install Vercel CLI

# Global install Vercel CLI
pnpm add -g vercel

# Or use npm
npm install -g vercel

Quick Deployment

Method 1: Using Deployment Scripts (Recommended)

# 1. Link Vercel project before first deployment
pnpm vercel:link

# 2. Check environment variable configuration
pnpm deploy:check-env

# 3. Deploy to preview environment
pnpm deploy

# 4. Deploy to production environment
pnpm deploy:prod

Method 2: Using Vercel CLI Directly

# Deploy to preview environment
vercel

# Deploy to production environment
vercel --prod

Method 3: Via Vercel Dashboard

1. Visit vercel.com/new
2. Import GitHub/GitLab/Bitbucket repository
3. Configure environment variables
4. Click Deploy

Configuration

vercel.json Configuration

The vercel.json file in project root contains:

{
  "framework": "nextjs",
  "buildCommand": "pnpm build",
  "installCommand": "pnpm install",
  "regions": ["hkg1"],
  "functions": {
    "src/app/api/**/*.ts": {
      "maxDuration": 30
    }
  },
  "crons": [
    {
      "path": "/api/crontab/yearly-credits",
      "schedule": "0 0 1 * *"
    }
  ]
}

Configuration Options

Available Regions

Environment Variable Configuration

Required Environment Variables

Configure in Vercel Dashboard under Settings > Environment Variables:

Database (Configure at least one)

# Turso/LibSQL (Recommended for Serverless)
TURSO_DATABASE_URL=libsql://your-database.turso.io
TURSO_AUTH_TOKEN=your-auth-token

# PostgreSQL (Neon/Supabase/etc.)
POSTGRE_DATABASE_URL=postgresql://...

Authentication

BETTER_AUTH_SECRET=your-random-secret-key
BETTER_AUTH_URL=https://yourdomain.com/

Email Service

RESEND_API_KEY=re_xxxxxxxxxx
RESEND_FROM_EMAIL=noreply@yourdomain.com

Payment Gateway (Optional)

# Stripe
STRIPE_SECRET_KEY=sk_live_xxx
STRIPE_PUBLISHABLE_KEY=pk_live_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx

# Or Creem
CREEM_API_KEY=ck_prod_xxx
CREEM_WEBHOOK_SECRET=whsec_xxx

Configure Environment Variables via CLI

# Add environment variable
vercel env add BETTER_AUTH_SECRET

# Pull environment variables to local
vercel env pull .env.local

# Or use npm script
pnpm vercel:env:pull

Cron Jobs

The project has the following scheduled tasks configured:

Configure Cron Job API Key

Set in environment variables:

YEARLY_CREDITS_API_KEY=your-secure-api-key

Deployment Script Parameters

vercel-deploy.ts

# Deploy to preview environment (default)
pnpm deploy

# Deploy to production environment
pnpm deploy:prod

# Build only, no deployment
npx tsx scripts/deploy/vercel-deploy.ts --build-only

# Skip build, deploy directly
npx tsx scripts/deploy/vercel-deploy.ts --skip-build

# Specify environment variable file
npx tsx scripts/deploy/vercel-deploy.ts --env=.env.staging

check-env.ts

# Check default environment variable file
pnpm deploy:check-env

# Check specific file
npx tsx scripts/deploy/check-env.ts --env=.env.production

# Strict mode (exit if required variables missing)
npx tsx scripts/deploy/check-env.ts --strict

Custom Domain

1. Go to project settings in Vercel Dashboard
2. Click Domains
3. Add custom domain
4. Configure DNS records as prompted

DNS Configuration Example

# A Record
@ -> 76.76.21.21

# CNAME Record
www -> cname.vercel-dns.com

Deployment Checklist

Before deployment, confirm:

• Environment variables configured in Vercel
• Database created and accessible
• Email service configured
• Payment gateway webhook configured (if used)
• Custom domain configured (if needed)
• SSL certificate active

FAQ

Q: Deployment failed with "Build failed"

A: Check the following:

1. Confirm pnpm build runs successfully locally
2. Check if environment variables are complete
3. View Vercel build logs to locate specific errors

Q: API routes return 500 error

A:

1. Check database connection configuration
2. Confirm environment variables are correctly set
3. View Vercel Functions logs

Q: Cron jobs not executing

A:

1. Confirm cron configuration in vercel.json is correct
2. Check if YEARLY_CREDITS_API_KEY is configured
3. Note that Vercel Hobby plan does not support Cron Jobs

Q: How to rollback to previous version

A: In Vercel Dashboard Deployments page, find previous deployment, click "..." > "Promote to Production"

Related Resources

• Vercel Official Documentation
• Next.js Deployment Documentation
• Vercel CLI Documentation