CodFlow Storefront Vercel Deploy

CodFlow Storefront — Vercel Deployment Runbook

cod-astro/theme01 is the customer-facing storefront theme for CodFlow (Astro 7). While the CodFlow backend (cod-server) and merchant dashboard (cod-client-astro) run on Cloudflare Workers (using D1, R2, and KV), the storefront supports dynamic deployment targets (DEPLOY_TARGET=vercel or DEPLOY_TARGET=cloudflare).

Deploying the storefront to Vercel is often preferred because:

1. Solves Cloudflare Error 1042 (Worker-to-Worker block): When cod-server is deployed on a free *.workers.dev subdomain without a custom domain, Cloudflare blocks another Cloudflare Worker on *.workers.dev from fetching it. Vercel runs outside Cloudflare's internal network, allowing the storefront to fetch cod-server on *.workers.dev without needing a custom domain.
2. Generous Global Edge Bandwidth: Vercel includes generous bandwidth and Edge CDN caching for storefront traffic.
3. Automatic Preview Deployments: Every Git branch/PR can have its own preview URL for testing theme changes.

Required Environment Variables

Before deploying, collect these values:

[!IMPORTANT] STORE_API_KEY is secret. It is used on the server side in SSR routes and API proxies. Never expose it in client-side bundles.

Deployment Methods

Choose Method 1 (Vercel CLI) for automated/terminal deployments, or Method 2 (Vercel Dashboard / Git) for continuous deployment from GitHub.

Method 1: Deploy via Vercel CLI (Recommended for AI Agents)

1. Prerequisites

• Ensure Vercel CLI is accessible via npx vercel (or installed globally).
• Check authentication:

  npx vercel whoami

  If not logged in:
  • If a browser is available: npx vercel login
  • If headless/CI: Set VERCEL_TOKEN in the environment (export VERCEL_TOKEN="<token>").

2. Configure and Link Project

Navigate to the storefront directory:

cd cod-astro/theme01

Run initial setup:

npx vercel link

Follow the interactive prompts (or provide flags in non-interactive sessions):

• Link to existing project? No (or Yes if linking existing)
• Project name: <project>-storefront (e.g. mystore-storefront)
• In which directory is your code located? ./

3. Set Environment Variables

Add the required production environment variables using the CLI:

# 1. Deployment Target
printf "vercel" | npx vercel env add DEPLOY_TARGET production

# 2. Backend API URL (must start with https://)
printf "https://<your-cod-server-domain>" | npx vercel env add COD_SERVER_URL production

# 3. Store API Key
printf "<your-raw-store-api-key>" | npx vercel env add STORE_API_KEY production

# 4. Optional: Media Domain (if R2 custom domain is configured)
printf "<media.yourdomain.com>" | npx vercel env add MEDIA_DOMAIN production

(Optional: also add them to preview and development environments if you plan to use preview branches).

4. Build and Deploy to Production

Execute production deployment with the Vercel adapter:

cd cod-astro/theme01
npx vercel --prod

Vercel will upload the project, execute npm run build:vercel (or astro build with DEPLOY_TARGET=vercel), compile the SSR serverless/edge functions, and provide the live production URL (e.g. https://<project>-storefront.vercel.app).

Method 2: Deploy via Vercel Dashboard (Git Integration)

Use this method when connecting a GitHub / GitLab / Bitbucket repository:

1. Import Repository in Vercel:

   • In the Vercel Dashboard, click Add New... → Project.
   • Select the codflow-os repository.

2. Configure Project Settings:

   • Project Name: e.g. codflow-storefront
   • Framework Preset: Astro
   • Root Directory: Click Edit and choose cod-astro/theme01. Check the option "Include source files outside of the Root Directory in the Build Step" (needed because workspace dependencies resolve to root node_modules).
   • Build Command: Toggle Override and set:

     npm run build:vercel

     (Or leave default astro build if DEPLOY_TARGET=vercel is set in Environment Variables).
   • Output Directory: Leave default (.vercel/output).
   • Install Command: Leave default (npm install / root workspace install).

3. Configure Environment Variables: Under Environment Variables, add:

   • DEPLOY_TARGET = vercel
   • COD_SERVER_URL = https://<your-cod-server-domain>
   • STORE_API_KEY = <your-raw-store-api-key>
   • MEDIA_DOMAIN = <media.yourdomain.com> (optional)

4. Deploy:

   • Click Deploy. Vercel will build the workspace, bundle the Astro site with @astrojs/vercel, and assign a production URL.