Knowledge > Integrations > Vercel

Vercel Integration

Vercel hosts all three active Next.js codebases and manages environment variables, deployments, CDN caching, and cron jobs. Each codebase has a separate Vercel project linked to its GitHub repository. The voice agent is NOT on Vercel — it runs on LiveKit Cloud.

Account Info

Field	Value
Account	churchwiseai-5386
Account email	john@churchwiseai.com
CLI login	Already logged in
Team	churchwiseai-5386

How Used Per Product

Product	Vercel Project	Deploy Branch	URL
ChurchWiseAI (main)	churchwiseai-web	main	churchwiseai.com
SermonWise AI	churchwiseai-web (hostname rewrite)	main	sermonwise.ai
ShareWiseAI	churchwiseai-web (hostname rewrite)	main	sharewiseai.com
PewSearch	pewsearch-web	master	pewsearch.com
IllustrateTheWord	sermon-illustrations	master	illustratetheword.com

Key Environment Variables

Environment variables are managed per-project in Vercel. Never check secrets into code. Variables prefixed NEXT_PUBLIC_ are bundled into the client-side build — treat them as public.

Variable	Scope	Purpose
NEXT_PUBLIC_SUPABASE_URL	Client + Server	Supabase project URL
NEXT_PUBLIC_SUPABASE_ANON_KEY	Client + Server	Supabase public anon key
SUPABASE_SERVICE_ROLE_KEY	Server	Supabase admin key (bypasses RLS)
STRIPE_SECRET_KEY	Server	Stripe API key
STRIPE_WEBHOOK_SECRET	Server	Stripe webhook signing secret
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY	Client	Stripe frontend key
RESEND_API_KEY	Server	Transactional email
NEXT_PUBLIC_SITE_URL	Client + Server	Canonical site URL (https://churchwiseai.com etc.)
APP_SECRET	Server	HMAC signing secret for admin session tokens (churchwiseai-web)
FOUNDER_TOKEN	Server	Internal founder-only API auth
OPS_ALERT_PHONE	Server	Phone number for WatchTower P0 SMS alerts
TWILIO_ACCOUNT_SID	Server	Twilio auth
TWILIO_AUTH_TOKEN	Server	Twilio auth
TWILIO_SMS_FROM	Server	Twilio sending number for ops alerts

CLI Patterns & Gotchas

Managing Environment Variables

Agents MUST manage env vars via CLI — never send the founder to the Vercel dashboard for this.

# List all env vars for the current project
vercel env ls

# Pull production env vars to .env.local
vercel env pull

# Add a new env var (pipe bypasses interactive prompt)
echo "secret-value" | vercel env add VAR_NAME production

# Add to multiple environments
echo "secret-value" | vercel env add VAR_NAME production
echo "secret-value" | vercel env add VAR_NAME preview
echo "secret-value" | vercel env add VAR_NAME development

# Remove an env var
vercel env rm VAR_NAME production

The pipe-based pattern (echo "val" | vercel env add) is essential — the CLI's interactive prompt doesn't work well in non-TTY environments.

Deployments

# Trigger production deploy
vercel --prod

# View deployment logs (follow mode)
vercel logs --tail

# List recent deployments
vercel deployments list

All pushes to the deploy branch (main/master) trigger automatic deploys via GitHub integration. Feature branches get preview deployments automatically.

Local Development Ports

Each project runs on a different port to avoid conflicts when running simultaneously:

Codebase	Port
churchwiseai-web	3002
pewsearch/web	3000
sermon-illustrations	3000

Run churchwiseai-web with: pnpm dev (starts on 3002 per package.json config).

Working Directory for CLI

Always run Vercel CLI commands from the project's root directory (where package.json or vercel.json lives), not from C:\dev.

Cron Jobs (churchwiseai-web)

Defined in churchwiseai-web/vercel.json:

Path	Schedule	Purpose
/api/ops/collect	Every 15 minutes	WatchTower: collects ops metrics, checks Twilio balance, logs to Supabase
/api/cron/daily-audit	7:00 AM daily	Daily audit — checks system health, surfaces anomalies
/api/founder/sync-knowledge	7:30 AM daily	Syncs knowledge to Google Drive

Cron jobs are Vercel Pro features. They invoke the specified API routes on schedule. If a cron job fails, check Vercel logs for the route — the function itself handles error reporting.

Middleware Routing

churchwiseai-web Middleware

Located at churchwiseai-web/src/middleware.ts. Handles:

1. Supabase PKCE code forwarding — catches ?code= on any path and forwards to /auth/callback. Supabase email confirmation sometimes ignores emailRedirectTo and sends the code to the site root.
2. sermonwise.ai hostname rewrite — any request with host: sermonwise.ai rewrites to /sermons/* internally.
3. sharewiseai.com hostname rewrite — any request with host: sharewiseai.com rewrites to /social/* internally.
4. Sermon app auth (/sermons/app) — validates Supabase Auth session; redirects to /sermons/login if unauthenticated.
5. Social app auth (/social/app) — validates Supabase Auth session; redirects to /social/login if unauthenticated.
6. Cookie-based admin session — validates cw_session cookie against church_admin_sessions table via Supabase REST.
7. Legacy URL token fallback — /admin/[token] still works during migration period.

Matcher excludes _next/static, _next/image, favicon.ico, embed/, sitemaps.

pewsearch/web Middleware

Located at pewsearch/web/src/middleware.ts. Handles one thing:

• Subdomain routing — {slug}.pewsearch.com rewrites to /s/{slug} internally. Sets x-is-subdomain: 1 header so the layout hides site chrome.
• Skips localhost (no subdomains possible).
• Skips reserved subdomains (www, api, admin, app).

Caching / ISR Strategy

churchwiseai-web

• Marketing pages: default Next.js caching (static at build time or per-request for dynamic pages)
• Admin routes (/admin/*): no-store (never cached)
• API routes: no-store unless explicitly cached

pewsearch/web

Route Pattern	Cache	SWR
/directory/*	s-maxage=3600 (1 hour)	stale-while-revalidate=86400 (1 day)
/denominations/*	s-maxage=3600	stale-while-revalidate=86400
/s/* (Pro Website)	s-maxage=3600	stale-while-revalidate=86400
/claim/*	no-store	—
/admin/*	no-store	—

The /s/[slug] Pro Website page also uses Next.js revalidate = 3600 (ISR).

Failure Modes & Recovery

Failure	Symptom	Recovery
Deploy fails	Vercel shows failed deployment	Check vercel logs for build errors. Most common: TypeScript errors, missing env vars, ESLint. Run pnpm build locally first.
Missing env var	Runtime 500 error, undefined values in logs	vercel env ls to audit, `echo "val"
Cron job not firing	WatchTower data missing, no daily audit emails	Check Vercel cron logs in dashboard. Verify vercel.json is correct. Cron requires Vercel Pro.
Preview deploy breaks main	Feature branch deploy shows error	Preview deploys are isolated. Check if env vars are missing in preview environment.
Middleware rewrite misconfigured	sermonwise.ai / sharewiseai.com shows wrong content	Check middleware.ts hostname matching. Verify domains are pointed at the Vercel project.
Build cache stale	Old code served after deploy	Force redeploy: vercel --prod --force
Serverless function timeout	504 errors on long operations	Vercel serverless default timeout is 10s (Hobby) / 60s (Pro). Long-running AI calls may need streaming responses.

Cost Model / Usage Limits

• All three projects are on Vercel Pro (or higher) to support cron jobs and higher function timeouts.
• Bandwidth, function invocations, and build minutes are metered.
• ISR and edge caching reduce function invocation counts for high-traffic directory pages on PewSearch.
• Cron jobs count toward function invocation limits.
• Preview deployments are automatically created for every PR branch — they consume build minutes.

See Also

• Supabase — database that all serverless functions connect to
• Stripe — webhook endpoints hosted on Vercel
• Twilio — SMS webhook endpoint hosted on Vercel
• LiveKit — voice agent is NOT on Vercel (runs on LiveKit Cloud)