Vercel Deployment

AdRecon is designed to deploy to Vercel as a static site with serverless API functions. This guide covers the deployment workflow, configuration, and best practices.

Overview

The deployment architecture includes:

Static Frontend: Vite-built React SPA served from /dist
SPA Rewrites: Client-side routing handled by vercel.json rewrites
Serverless Functions: API routes in /api/* for media proxying, admin operations, and webhooks
Branch-Based Deployments: Strict two-lane flow (staging → production)

Vercel Configuration

The vercel.json:1-90 file defines the build and routing configuration.

Build Settings

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist"
}

The build process:

Runs npm run build which executes scripts/build-site.mjs
Outputs to dist/ directory containing:
- dist/index.html - Auth shell for /
- dist/app/index.html - Main SPA entry
- dist/app/assets/* - Bundled JS, CSS, and assets

SPA Rewrites

All application routes rewrite to the SPA entry point for client-side routing:

{
  "rewrites": [
    { "source": "/", "destination": "/app/index.html" },
    { "source": "/index.html", "destination": "/app/index.html" },
    { "source": "/admin", "destination": "/app/index.html" },
    { "source": "/admin/:path*", "destination": "/app/index.html" },
    { "source": "/profile", "destination": "/app/index.html" },
    { "source": "/profile/:path*", "destination": "/app/index.html" },
    { "source": "/download", "destination": "/app/index.html" },
    { "source": "/download/:path*", "destination": "/app/index.html" },
    { "source": "/app/assets/:path*", "destination": "/app/assets/:path*" },
    { "source": "/app", "destination": "/app/index.html" },
    { "source": "/app/:path*", "destination": "/app/index.html" }
  ]
}

Key routes:

/ - Root route (auth shell)
/app - Main application
/admin - Admin dashboard (requires admin role)
/profile - User profile and settings
/download - Landing page download interface
/app/assets/* - Static assets (served directly)

Serverless Function Configuration

Certain API routes require extended timeouts for heavy operations:

{
  "functions": {
    "api/download-page.js": { "maxDuration": 120 },
    "api/admin/scrape.js": { "maxDuration": 60 },
    "api/landing-ripper/jobs.js": { "maxDuration": 60 },
    "api/landing-ripper/webhook.js": { "maxDuration": 120 },
    "api/landing-ripper/download/[token].js": { "maxDuration": 60 }
  }
}

Functions:

api/download-page.js - HTML page archival (120s timeout)
api/admin/scrape.js - Admin scraping operations (60s)
api/landing-ripper/* - Apify integration webhooks and downloads

Deployment Workflow

AdRecon uses a strict two-lane deployment flow to maintain environment consistency.

Branch Strategy

The deployment script enforces branch requirements. Attempting to deploy from the wrong branch will fail with a clear error message.

Environment	Branch	Command	Vercel Target
Staging	`staging`	`npm run deploy:staging`	Preview
Production	`main`	`npm run deploy:production`	Production

Deploy to Staging

Switch to staging branch

Ensure you’re on the staging branch:

git checkout staging

Run staging deploy

Execute the staging deployment script:

npm run deploy:staging

This runs scripts/deploy-vercel.sh:21-28 which:

Verifies you’re on the staging branch
Runs vercel deploy -y for a preview deployment

Verify deployment

Vercel will output a preview URL like:

https://adrecon-xyz123.vercel.app

Test the deployment thoroughly before promoting to production.

Deploy to Production

Production deploys must be made from the main branch. The script will block deployments from other branches.

Merge to main

After testing staging, merge staging into main:

git checkout main
git merge staging
git push origin main

Run production deploy

Execute the production deployment script:

npm run deploy:production

This runs scripts/deploy-vercel.sh:31-37 which:

Verifies you’re on the main branch
Runs vercel deploy --prod -y for a production deployment

Verify production

Check your production URL and verify:

Application loads correctly
Authentication works (Magic Link + Google OAuth)
Database connections are active
API functions respond correctly

Deployment Script Details

The scripts/deploy-vercel.sh:1-38 script provides branch enforcement:

#!/usr/bin/env bash
set -euo pipefail

lane="${1:-}"

if [[ "$lane" != "staging" && "$lane" != "production" ]]; then
  echo "Usage: scripts/deploy-vercel.sh staging|production"
  exit 1
fi

branch="$(git rev-parse --abbrev-ref HEAD)"

if [[ "$lane" == "staging" ]]; then
  if [[ "$branch" != "staging" ]]; then
    echo "ERROR: Staging deploys must run from 'staging' branch"
    exit 1
  fi
  vercel deploy -y
fi

if [[ "$lane" == "production" ]]; then
  if [[ "$branch" != "main" ]]; then
    echo "ERROR: Production deploys must run from 'main' branch"
    exit 1
  fi
  vercel deploy --prod -y
fi

Branch Protection

The script prevents common deployment mistakes:

Cannot deploy to production from staging branch
Cannot deploy to staging from main branch
Clear error messages indicate which branch is required

Environment Variables

Configure environment variables in Vercel Dashboard:

Navigate to environment settings

Go to your Vercel project → Settings → Environment Variables

Add variables for each environment

Add all required variables from the Environment Variables page.Set the scope for each variable:

Production: Used for main branch deploys
Preview: Used for staging and other preview deploys
Development: Used for local vercel dev command

Redeploy after changes

After adding or updating environment variables, redeploy your application:

npm run deploy:staging  # or deploy:production

Required Variables

At minimum, configure these for production:

VITE_SUPABASE_URL="https://your-project.supabase.co"
VITE_SUPABASE_ANON_KEY="your-anon-key"
SUPABASE_URL="https://your-project.supabase.co"
SUPABASE_SERVICE_ROLE_KEY="your-service-role-key"
FANBASIS_API_KEY="your-fanbasis-key"
APIFY_TOKEN="apify_api_..."
APIFY_LANDING_RIPPER_ACTOR_ID="your-actor-id"

Build Ignore Strategy

The vercel.json:4 ignoreCommand prevents builds on non-protected branches:

if [ "$VERCEL_GIT_COMMIT_REF" != "staging" ] && 
   [ "$VERCEL_GIT_COMMIT_REF" != "main" ]; then
  echo "Skipping branch (allowed: staging, main)"
  exit 0
fi

This saves build time and resources by only building staging and main branches.

Monitoring & Debugging

View Deployment Logs

Go to Vercel Dashboard → Deployments
Click on a deployment to view build logs
Check “Functions” tab for serverless function logs

Common Issues

Build Failures:

Check build logs in Vercel dashboard
Verify all environment variables are set
Ensure package.json dependencies are up to date

Runtime Errors:

Check function logs in Vercel → Deployments → Functions
Verify Supabase connection (check SUPABASE_URL and keys)
Ensure Supabase RLS policies allow access

Routing Issues:

Verify vercel.json rewrites are correct
Check that SPA routes are handled by React Router
Clear browser cache and test in incognito mode

Rollback Strategy

If a production deployment has issues:

Identify last good deployment

Go to Vercel Dashboard → Deployments and find the last working deployment.

Promote previous deployment

Click the three dots (•••) next to the deployment → “Promote to Production”

Fix and redeploy

Fix the issue locally, test on staging, then redeploy to production.

Performance Optimization

Caching Strategy

Vercel automatically caches static assets in dist/app/assets/*:

JS bundles are cache-busted with content hashes
CSS files include content hashes
Images and fonts are cached indefinitely

Edge Network

Vercel deploys to a global edge network:

Static assets served from nearest edge location
Serverless functions run in the optimal region
Automatic DDoS protection and SSL

Next Steps

After deploying to Vercel:

Configure custom domain in Vercel → Settings → Domains
Update Supabase redirect URLs to include production domain
Set up monitoring with Vercel Analytics
Configure alerts for function errors
Review security headers in Vercel settings

Setup

Operations

Vercel Deployment

Overview

Vercel Configuration

Build Settings

SPA Rewrites

Serverless Function Configuration

Deployment Workflow

Branch Strategy

Deploy to Staging

Deploy to Production

Deployment Script Details

Branch Protection

Environment Variables

Required Variables

Build Ignore Strategy

Monitoring & Debugging

View Deployment Logs

Common Issues

Rollback Strategy

Performance Optimization

Caching Strategy

Edge Network

Next Steps

Build docs developers (and LLMs) love

Setup

Operations

​Overview

​Vercel Configuration

​Build Settings

​SPA Rewrites

​Serverless Function Configuration

​Deployment Workflow

​Branch Strategy

​Deploy to Staging

​Deploy to Production

​Deployment Script Details

​Branch Protection

​Environment Variables

​Required Variables

​Build Ignore Strategy

​Monitoring & Debugging

​View Deployment Logs

​Common Issues

​Rollback Strategy

​Performance Optimization

​Caching Strategy

​Edge Network

​Next Steps

Build docs developers (and LLMs) love

Overview

Vercel Configuration

Build Settings

SPA Rewrites

Serverless Function Configuration

Deployment Workflow

Branch Strategy

Deploy to Staging

Deploy to Production

Deployment Script Details

Branch Protection

Environment Variables

Required Variables

Build Ignore Strategy

Monitoring & Debugging

View Deployment Logs

Common Issues

Rollback Strategy

Performance Optimization

Caching Strategy

Edge Network

Next Steps