Vercel to Cloudflare Pages Migration Proposal

Date: January 2026
Project: Piston Labs React Application (Shop & Consumer Dashboards)
Current Stack: Next.js 15 + Supabase + Vercel
Target Stack: Next.js 15 + Supabase + Cloudflare Pages

Executive Summary

This document outlines the migration strategy from Vercel to Cloudflare Pages for the Piston Labs React application. The migration is feasible but requires careful handling of long-running API routes and some code adjustments for Cloudflare's runtime environment.

Recommendation: Proceed with migration using a phased approach, offloading heavy compute tasks to Cloudflare Workers with Queues.

Current Architecture Analysis

Tech Stack

External Services (Unchanged by Migration)

• Supabase - Database, Auth, Storage (keeping)
• OpenAI - GPT-4o-mini for document parsing
• Google Document AI - OCR processing
• OneSignal - Push notifications, Email, SMS
• TekMetric - Shop management webhooks
• AutoPi - Vehicle telemetry

API Routes Inventory (14 Routes)

Cloudflare Pages Capabilities

What Cloudflare Pages Supports

Cloudflare Workers Limits

Critical: The pdf-parse route requires up to 5 minutes. This requires:

1. Cloudflare Workers Paid plan ($5/mo)
2. Workers Unbound pricing model
3. Or: Offload to separate async processing

Vercel-Specific Code to Migrate

1. Route Segment Configs

Current (Vercel):

// app/api/pdf-parse/route.ts
export const maxDuration = 300 // 5 minutes
export const dynamic = 'force-dynamic'
export const runtime = 'nodejs'

Target (Cloudflare):

// app/api/pdf-parse/route.ts
export const runtime = 'edge' // or 'nodejs' with nodejs_compat

// For long-running tasks, use Cloudflare Queues
// See "Heavy Compute Strategy" below

2. Middleware (Supabase Auth)

Current: Works with Next.js middleware + Supabase SSR

Migration: Generally compatible. Update to use Cloudflare's request context.

3. Server-Side Supabase Client

Current:

import { cookies } from 'next/headers'

Migration: Works on Cloudflare Pages with @cloudflare/next-on-pages

4. Environment Variables

Current: Set in Vercel dashboard

Migration: Set in Cloudflare Pages dashboard or wrangler.toml

Required env vars:

NEXT_PUBLIC_SUPABASE_URL
NEXT_PUBLIC_SUPABASE_ANON_KEY
SUPABASE_SERVICE_ROLE_KEY
OPENAI_API_KEY
GOOGLE_CLOUD_PROJECT_ID
GOOGLE_DOCUMENT_AI_PROCESSOR_ID
GOOGLE_CLOUD_CREDENTIALS (base64)
ONESIGNAL_APP_ID
ONESIGNAL_REST_API_KEY
TEKMETRIC_API_KEY
AUTOPI_API_KEY
CRON_SECRET
INTERNAL_ACCESS_USER_IDS

Heavy Compute Strategy: PDF Processing

The /api/pdf-parse route is the main challenge:

• Google Document AI OCR (network I/O)
• OpenAI GPT-4o parsing (network I/O)
• File upload to Supabase Storage
• Database writes

Option A: Workers Unbound (Recommended)

Keep the existing architecture but use Cloudflare Workers Unbound pricing:

• Cost: ~$12.50/million requests + $0.02/million ms
• Duration: Up to 5 minutes per request
• Complexity: Low - minimal code changes

# wrangler.toml
[build]
command = "npx @cloudflare/next-on-pages"

[[routes]]
pattern = "/api/pdf-parse"
worker = "pdf-processor"

[workers.pdf-processor]
compatibility_flags = ["nodejs_compat"]

Option B: Queue-Based Processing (More Scalable)

Split into async processing:

1. Upload Handler (fast, edge):
   • Accept file upload
   • Store in Supabase Storage
   • Queue processing job
   • Return immediately
2. Queue Consumer (background worker):
   • Process OCR with Document AI
   • Parse with OpenAI
   • Update database
   • Notify via webhook/WebSocket

User Upload → Edge Worker → Supabase Storage
                   ↓
            Cloudflare Queue
                   ↓
         Background Worker (5 min limit)
                   ↓
            Supabase DB + Webhook

Advantages:

• Better user experience (instant upload response)
• More reliable (retries built-in)
• Scales better

Migration Steps

Phase 1: Setup (Day 1)

1. Create Cloudflare account / project
2. Install @cloudflare/next-on-pages
3. Add wrangler.toml configuration
4. Test local build with Wrangler

npm install @cloudflare/next-on-pages
npx wrangler login

Phase 2: Code Adjustments (Days 2-3)

1. Update route configs for Cloudflare compatibility
2. Add nodejs_compat flag where needed
3. Test all API routes locally
4. Implement queue-based PDF processing (if Option B)

Phase 3: Environment & Secrets (Day 4)

1. Configure all env vars in Cloudflare dashboard
2. Set up Google Cloud credentials (may need adjustment)
3. Verify Supabase connectivity from Cloudflare edge

Phase 4: Testing (Days 5-7)

1. Deploy to Cloudflare Pages preview
2. Test all user flows:
   • User authentication (sign in/out)
   • Shop dashboard access
   • Consumer dashboard access
   • PDF upload and parsing
   • Webhook reception
   • Push notifications
   • TekMetric integration

Phase 5: DNS & Cutover (Day 8)

1. Configure custom domain in Cloudflare
2. Update DNS records
3. Monitor for 24 hours
4. Decommission Vercel project

Cost Comparison

Current (Vercel)

Projected (Cloudflare Pages)

Estimated Savings: $10-15/month depending on usage

Risk Assessment

Rollback Plan

If critical issues arise:

1. Keep Vercel project active (don't delete)
2. Switch DNS back to Vercel
3. Full rollback in < 5 minutes

Recommendation

Proceed with migration using Option A (Workers Unbound) for initial release:

1. Minimal code changes
2. Maintains existing architecture
3. Cost-effective ($5-10/month total)
4. Can upgrade to queue-based (Option B) later if scale demands

Timeline: 8 working days for full migration

Prerequisites:

• Cloudflare account with Workers Unbound enabled
• All environment variables documented and ready
• Test environment for validation

Next Steps

1. Tyler approval of migration approach
2. Set up Cloudflare account and project
3. Create feature branch: feature/cloudflare-migration
4. Begin Phase 1 implementation

Document prepared by phil agent - January 2026