mdcms/velox-docs/pages/deploy-vercel.md

title	sort	section-id	keywords	description	language
Deploy to Vercel	100	deployment	Vercel, deployment, serverless, edge, CI/CD, deploy	Step-by-step guide to deploying a Velox application to Vercel	en

Deploy to Vercel

Vercel is the recommended hosting platform for Velox applications. The Velox Vercel adapter handles all configuration automatically — no manual vercel.json setup is required for most projects.

Prerequisites

• A Vercel account (vercel.com)
• The Vercel CLI: npm install -g vercel
• A Velox project committed to a Git repository (GitHub, GitLab, or Bitbucket)

Automatic Deployment via Git Integration

Step 1 — Push Your Project to Git

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/your-username/your-project.git
git push -u origin main

Step 2 — Import the Project on Vercel

1. Go to vercel.com/new
2. Click Add New Project → Import Git Repository
3. Select your repository
4. Vercel automatically detects Velox and sets the correct build settings:
   • Framework Preset: Velox
   • Build Command: velox build
   • Output Directory: .velox/output
   • Install Command: npm ci

Step 3 — Configure Environment Variables

In the Vercel project dashboard:

1. Go to Settings → Environment Variables
2. Add each variable from your .env.production file

Do not add PUBLIC_BASE_URL manually — Vercel sets VERCEL_URL automatically and the Velox Vercel adapter uses it.

Step 4 — Deploy

Click Deploy. Vercel will:

1. Clone your repository
2. Install dependencies
3. Run velox build
4. Deploy to its global edge network

Your site is live at https://your-project.vercel.app.

Vercel CLI Deployment

For manual or scripted deployments:

# Install adapter
npm install @velox/vercel

# Deploy to preview (equivalent to a branch deploy)
vercel

# Deploy to production
vercel --prod

Configuring the Vercel Adapter

Install and configure @velox/vercel:

npm install @velox/vercel

// velox.config.ts
import { defineConfig } from 'velox';
import { vercel } from '@velox/vercel';

export default defineConfig({
  adapter: vercel({
    // Route-level edge function configuration
    edgeRoutes: ['/api/stream', '/api/realtime'],

    // Override ISR revalidation for specific routes
    isr: {
      expiration: 60,             // default revalidation (seconds)
      bypassToken: process.env.VERCEL_ISR_BYPASS_TOKEN,
    },

    // Enable Vercel Image Optimisation (uses Vercel's CDN)
    images: {
      sizes: [640, 1080, 1920],
    },
  }),
});

Edge Functions

Mark individual routes to run on Vercel Edge instead of Node.js serverless:

// routes/api/stream+server.ts
export const config = { edge: true };

export const GET = defineHandler(async (req) => {
  // Runs on Vercel Edge — uses Web APIs only
  return new Response('Hello from edge!');
});

Edge functions are deployed globally in ~70 Vercel regions and have ~0ms cold start. Use them for latency-sensitive, stateless handlers.

Custom Domains

1. Go to your project on Vercel → Settings → Domains
2. Click Add Domain
3. Enter your domain (e.g., example.com)
4. Follow the DNS configuration instructions:
   • Add a CNAME record: www → cname.vercel-dns.com
   • Add an A record: @ → 76.76.21.21
5. SSL certificates are provisioned automatically via Let's Encrypt

Set the canonical base URL environment variable in Vercel:

PUBLIC_BASE_URL = https://example.com

Preview Deployments

Every pull request gets an automatic preview deployment at a unique URL (https://your-project-git-branch-name.vercel.app). This is configured by default and requires no additional setup.

To share preview deployments with your team, enable Password Protection under Settings → Deployment Protection.

Build Cache

Velox's Velocitor build cache is automatically persisted across deployments by the Vercel adapter. Subsequent deployments typically build 3–5× faster than the first.

vercel.json Reference

For advanced configuration, create a vercel.json at your project root:

{
  "regions": ["iad1", "fra1"],
  "cleanUrls": true,
  "trailingSlash": false,
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
      ]
    }
  ],
  "redirects": [
    { "source": "/old-path", "destination": "/new-path", "permanent": true }
  ]
}

Monitoring and Analytics

Enable Vercel Analytics and Speed Insights in your project dashboard. The Velox adapter hooks into these automatically — no code changes needed.

For custom event tracking:

import { track } from '@vercel/analytics';

track('button_clicked', { component: 'Hero', variant: 'primary' });