Vercel

Deploy your app to Vercel as a serverless application with zero infrastructure management.

How it works

The generated project includes a packages/deploy/vercel directory with everything needed:

• vercel.json — build commands, rewrites, serverless function config, and cron schedule
• api/index.js — a single serverless function entry point that re-exports the backend

Vercel builds the backend and frontend together, serves the frontend as static files, and routes /api/* requests to the serverless function.

Setup

Copy the deploy files to your project root:

cp -r packages/deploy/vercel/* .

Important: In the Vercel dashboard, keep the Root Directory set to the repository root (leave it empty). Vercel may auto-detect packages/backend or another subdirectory — this is wrong. The vercel.json at the root already handles build commands for all packages. See Root Directory for more details.

Environment variables

Set these in the Vercel dashboard under Settings > Environment Variables.

Required

If ORGANIZATION_MODE is set to multi-domain:

Background jobs

Optional

Database

Vercel works best with serverless-compatible PostgreSQL providers:

• Neon
• Supabase

These handle connection pooling automatically, which is important for serverless environments where each function invocation may open a new connection.

Important: Create your database in the same region as your Vercel deployment. Vercel defaults to Washington, D.C. (iad1). Mismatched regions add significant latency to every database query.

Background jobs

Inline mode (recommended for Hobby plan)

Set BACKGROUND_JOB_MODE=inline. Jobs run immediately after being added, blocking the request until complete. No external scheduling needed — this is the simplest option and works well for most use cases.

Cron mode (recommended for Pro plan)

Set BACKGROUND_JOB_MODE=cron. The vercel.json includes a cron job that calls /api/background-jobs/process:

"crons": [
  {
    "path": "/api/background-jobs/process",
    "schedule": "0 0 * * *"
  }
]

The default schedule runs once daily. On a Pro plan, change to every minute for near-real-time processing:

"schedule": "* * * * *"

Set CRON_SECRET in your environment variables when using cron mode.

Deploy

Via CLI

# Install Vercel CLI
npm i -g vercel
 
# Preview deployment
vercel
 
# Production deployment
vercel --prod

Via GitHub

Connect your repository in the Vercel dashboard for automatic deployments on every push.

After deployment

Once deployed, copy your app URL (e.g. https://your-app.vercel.app) and set both FRONTEND_URL and BACKEND_URL to that URL in the Vercel dashboard. Both must point to the same URL since the backend runs as a serverless function on the same domain. Redeploy after updating.

Multi-domain subdomains

If your project uses multi-domain organization mode, each organization gets its own subdomain (e.g., tenant.yourdomain.com). Vercel supports this with wildcard domains.

Add a wildcard domain

Wildcard domains require Vercel's nameservers to issue wildcard SSL certificates.

1. Point your domain's nameservers to ns1.vercel-dns.com and ns2.vercel-dns.com at your domain registrar.
2. In the Vercel dashboard, go to Settings > Domains.
3. Add your apex domain (e.g., yourdomain.com).
4. Add a wildcard domain: *.yourdomain.com.

Any subdomain (e.g., tenant1.yourdomain.com, tenant2.yourdomain.com) will now automatically resolve to your Vercel deployment with SSL.

Note: DNS changes can take up to 48 hours to propagate. Use WhatsMyDNS to check status.

Environment variables

Update these variables in the Vercel dashboard for multi-domain:

Both the apex domain and all subdomains point to the same Vercel deployment. The application reads the subdomain from the request to identify the tenant.

Limitations

Other limitations:

• Cold starts — serverless functions have startup latency on first request
• No persistent connections — WebSockets require an external service
• No background workers — use cron or inline mode instead

For long-running jobs or WebSocket support, consider the VM deployment option.