vercel

Vercel for SaaS

Core Insight: Optimize three axes: operational control (CLI-first), cost control (avoid accidental builds), correctness (caching + auth without breaking SSR).

Table of Contents

• THE EXACT PROMPT
• Architecture Decision
• Quick Start
• Stop Build Credit Burn
• Environment Variables
• Workflow Checklist
• Critical Gotchas
• Core Commands
• AGENTS.md Blurb
• References

---

THE EXACT PROMPT

Set up [Next.js app / SaaS] on Vercel with:
1. Cloudflare DNS at: [domain.com]
2. Supabase project: [project-ref]
3. Build control: [manual deploys only / CI-triggered / default]
4. Cost offload: [R2 for assets / Cloudflare Pages for marketing / none]

Follow vercel-for-saas skill patterns.

Architecture Decision

Where should traffic go?
│
├─ Authenticated app (SSR/RSC) ─────► Vercel (app.example.com)
│  • DNS-only in Cloudflare (no proxy)
│  • Manual deploys, prebuilt artifacts
│
├─ Marketing/docs (static) ─────────► Cloudflare Pages (www.example.com)
│  • Direct Upload for deploy control
│  • Aggressive caching, cheap bandwidth
│
└─ Uploads/assets (storage) ────────► Cloudflare R2 (assets.example.com)
   • Worker-signed URLs
   • No egress fees

Why this split: Vercel does NOT recommend reverse-proxying. Hostname splitting gets Cloudflare benefits without breaking Vercel's edge.

Quick Start: Manual Deploy

# 1. Pull settings + env (creates .vercel/)
vercel pull --yes --token $VERCEL_TOKEN

# 2. Build locally (skips Vercel build minutes)
vercel build --prod

# 3. Upload prebuilt artifact
vercel deploy --prebuilt --prod --token $VERCEL_TOKEN

This is the highest-leverage pattern for cost control.

Stop Build Credit Burn

Method	How	Effectiveness
Disable auto-deploys	vercel.json: "git": { "deploymentEnabled": false }	★★★★★
Prebuilt workflow	Build outside Vercel, upload with --prebuilt	★★★★☆
Ignored Build Step	Exit 0 = skip, Exit 1 = build (commonly reversed!)	★★☆☆☆
Deploy Hooks	HTTP-triggered deploys only	★★★☆☆

Config-as-code (recommended):

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "git": { "deploymentEnabled": false }
}

Details: BUILD-CONTROL.md

Environment Variables

# List
vercel env ls

# Add secret (interactive)
vercel env add SECRET_NAME production

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

# Bulk sync via REST (for agents)
curl -X POST "https://api.vercel.com/v10/projects/$PROJECT/env?upsert=true" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -d '{"key":"VAR","value":"val","target":["production"]}'

For OIDC + Vault: TOKEN-AND-KEY-MANAGEMENT.md

Domain Setup

# Add domain to Vercel
vercel domains add example.com --token $VERCEL_TOKEN

# Then in Cloudflare DNS (DNS-only, not proxied):
# A record → Vercel IP  OR
# CNAME → cname.vercel-dns.com

Workflow Checklist

Phase 1: Initial Setup

• Install CLIs: vercel, supabase, wrangler, jq
• Set tokens: VERCEL_TOKEN, CLOUDFLARE_API_TOKEN
• Link project: vercel link --yes
• Pull env: vercel pull --yes

Phase 2: Cost Optimization

• Add "git": { "deploymentEnabled": false } to vercel.json
• Set up prebuilt deploy workflow in CI
• Move marketing to Cloudflare Pages — CLOUDFLARE-OFFLOAD.md
• Move assets to R2 — CLOUDFLARE-OFFLOAD.md

Phase 3: Secrets & Auth

• Store secrets via vercel env add or REST API
• Configure OIDC for cloud credentials — TOKEN-AND-KEY-MANAGEMENT.md
• Set up Supabase auth integration

Phase 4: Database

• Create migrations: supabase migration new
• Apply: supabase migration up (local) / supabase db push (CI)
• Generate types: supabase gen types typescript

Two-Button Deploy (Agent-Friendly)

# Marketing (Cloudflare Pages)
pnpm -C apps/marketing build
npx wrangler pages deploy apps/marketing/dist --branch=main

# App (Vercel prebuilt)
vercel pull --yes && vercel build --prod && vercel deploy --prebuilt --prod

Critical Gotchas

Gotcha	Fix
Ignored Build Step exits reversed	0 = skip, 1 = build (not intuitive)
Ignored builds still count toward quotas	Use git.deploymentEnabled: false instead
Cloudflare proxy + Vercel = problems	Use DNS-only for Vercel domains
.vercel/ folder committed	Add to .gitignore
Secrets in config files	Use vercel env or wrangler secret put

Full list: FOOTGUNS.md

Core Commands

Task	Command
Deploy preview	vercel
Deploy prod	vercel --prod
Pull settings	vercel pull
Build locally	vercel build
Deploy prebuilt	vercel deploy --prebuilt
List env vars	vercel env ls
Add env var	vercel env add NAME target
Pull env to file	vercel env pull

Full CLI reference: CLI-COMMANDS.md

---

AGENTS.md Blurb

Copy this to your project's AGENTS.md:

### Vercel

Vercel CLI is installed and authenticated.

Project: `<PROJECT_NAME>`

Common commands:

\`\`\`bash
vercel pull --yes         # Fetch settings + env
vercel build --prod       # Build locally (saves build minutes)
vercel deploy --prebuilt --prod  # Deploy prebuilt artifact
vercel env ls             # List env vars
vercel env add SECRET production  # Add secret
\`\`\`

**Cost tip:** Use prebuilt workflow to avoid burning build credits.

References

Topic	Reference
Architecture & cost model	ARCHITECTURE.md
Stopping build burn	BUILD-CONTROL.md
API-based build control	API-BUILD-CONTROL.md
All CLI commands	CLI-COMMANDS.md
Secrets, env, OIDC, Vault	TOKEN-AND-KEY-MANAGEMENT.md
R2 + Pages cost offload	CLOUDFLARE-OFFLOAD.md
Full automation blueprint	AUTOMATION-BLUEPRINT.md
Common mistakes	FOOTGUNS.md

Token Setup (Non-Interactive Auth)

# Vercel: https://vercel.com/account/tokens
export VERCEL_TOKEN=xxx

# Cloudflare: https://dash.cloudflare.com/profile/api-tokens
export CLOUDFLARE_API_TOKEN=xxx

# Supabase: project settings → API
export SUPABASE_ACCESS_TOKEN=xxx

All CLIs read these automatically. No interactive login needed.