Vercel Deployment
Overview
Vercel is a cloud platform for deploying frontend frameworks and serverless functions with automatic CI/CD, preview deployments, and edge infrastructure. Projects are configured via vercel.json (or programmatic vercel.ts), the Vercel dashboard, or the Vercel CLI.
When to use: Static sites, SSR frameworks (Next.js, SvelteKit, Nuxt), serverless API routes, edge functions, preview environments per pull request, monorepo deployments.
When NOT to use: Long-running backend processes (use containers), WebSocket servers (use dedicated infrastructure), heavy compute workloads (use cloud VMs), applications requiring persistent file system access.
Quick Reference
| Pattern |
Tool / API |
Key Points |
| Project config |
vercel.json or vercel.ts |
Root of project, controls builds/routing/functions |
| Rewrites |
rewrites array |
Routes request to destination, URL unchanged |
| Redirects |
redirects array |
Changes URL, permanent: true for 301 |
| Headers |
headers array |
Custom response headers per path pattern |
| Clean URLs |
cleanUrls: true |
Strips .html extensions |
| Trailing slash |
trailingSlash: false |
Consistent URL format |
| Environment vars |
Dashboard or vercel env |
Scoped to production, preview, development |
| Custom domains |
Project Settings > Domains |
A record for apex, CNAME for subdomains |
| Preview deploys |
Automatic per PR |
Each push gets unique URL |
| Edge functions |
export const runtime = 'edge' |
V8 isolates, low latency, limited Node.js APIs |
| Serverless functions |
api/ directory or framework routes |
Node.js runtime, full API access |
| Deploy via CLI |
vercel or vercel --prod |
Preview by default, --prod for production |
| Promote deploy |
vercel promote <url> |
Promote existing preview to production |
| Monorepo |
Root directory setting per project |
One repo, multiple Vercel projects |
| GitHub integration |
Automatic on push |
Zero-config CI/CD with preview per branch |
| Programmatic config |
vercel.ts with @vercel/config |
Typed, dynamic configuration alternative |
| Fluid compute |
Enabled by default for new projects |
Multi-request workers, 300s default duration |
| Rolling releases |
Incremental rollout with monitoring |
Gradual traffic shift with auto-rollback triggers |
| Firewall rules |
vercel.json WAF configuration |
Block threats via dashboard, API, or config file |
Common Mistakes
| Mistake |
Correct Pattern |
Using .env.production for preview-specific values |
Use Vercel environment variables scoped to preview environment |
Expecting VERCEL_URL to include protocol |
Prepend https:// manually; use VERCEL_PROJECT_PRODUCTION_URL for stable production URL |
Adding only apex domain without www |
Add both yourdomain.com and www.yourdomain.com to avoid 404 on one |
| Using Node.js APIs in edge functions |
Edge runtime uses V8 only; fs, path, process are unavailable |
| Exceeding 1024 static redirects |
Use bulkRedirects property for large redirect sets (CSV/JSON/JSONL) |
| Creating QueryClient or fetching in edge without streaming |
Use streaming responses for long operations in edge functions |
Setting maxDuration above plan limit |
Fluid compute default: 300s; Hobby: 60s, Pro: 300s, Enterprise: 900s max |
| Conflicting DNS records for custom domain |
Remove duplicate A records; keep only the Vercel-pointing record |
| Not awaiting build in CI before deploy |
Use vercel build then vercel deploy --prebuilt for reliable CI deploys |
| Ignoring monorepo root directory setting |
Set root directory per project in Vercel dashboard for correct builds |
Delegation
- Infrastructure review: Use
Task agent to audit deployment configuration
- Environment debugging: Use
Explore agent to trace environment variable issues
- CI/CD pipeline review: Use
code-reviewer agent for GitHub Actions workflow review
References
- Configuration: vercel.json, builds, rewrites, redirects, headers
- Environment variables and custom domains
- Edge and serverless functions
- CLI commands and CI/CD integration
1---2name: vercel-deployment3description: Vercel deployment configuration, preview environments, and edge functions. Covers vercel.json and vercel.ts configuration, rewrites, redirects, headers, environment variables across production/preview/development, custom domains, DNS setup, edge and serverless functions, Vercel CLI, GitHub Actions CI/CD, and monorepo deployments. Use when deploying to Vercel, configuring builds, setting up preview branches, managing environment variables, configuring custom domains, or using edge/serverless functions. Use for vercel, deploy, preview, edge-function, serverless, vercel-json, environment-variables, domains, monorepo.4license: MIT5---6
7# Vercel Deployment
8
9## Overview
10
11Vercel is a cloud platform for deploying frontend frameworks and serverless functions with automatic CI/CD, preview deployments, and edge infrastructure. Projects are configured via `vercel.json` (or programmatic `vercel.ts`), the Vercel dashboard, or the Vercel CLI.
12
13**When to use:** Static sites, SSR frameworks (Next.js, SvelteKit, Nuxt), serverless API routes, edge functions, preview environments per pull request, monorepo deployments.
14
15**When NOT to use:** Long-running backend processes (use containers), WebSocket servers (use dedicated infrastructure), heavy compute workloads (use cloud VMs), applications requiring persistent file system access.
16
17## Quick Reference
18
19| Pattern | Tool / API | Key Points |
20| -------------------- | ------------------------------------ | -------------------------------------------------- |
21| Project config | `vercel.json` or `vercel.ts` | Root of project, controls builds/routing/functions |
22| Rewrites | `rewrites` array | Routes request to destination, URL unchanged |
23| Redirects | `redirects` array | Changes URL, `permanent: true` for 301 |
24| Headers | `headers` array | Custom response headers per path pattern |
25| Clean URLs | `cleanUrls: true` | Strips `.html` extensions |
26| Trailing slash | `trailingSlash: false` | Consistent URL format |
27| Environment vars | Dashboard or `vercel env` | Scoped to production, preview, development |
28| Custom domains | Project Settings > Domains | A record for apex, CNAME for subdomains |
29| Preview deploys | Automatic per PR | Each push gets unique URL |
30| Edge functions | `export const runtime = 'edge'` | V8 isolates, low latency, limited Node.js APIs |
31| Serverless functions | `api/` directory or framework routes | Node.js runtime, full API access |
32| Deploy via CLI | `vercel` or `vercel --prod` | Preview by default, `--prod` for production |
33| Promote deploy | `vercel promote <url>` | Promote existing preview to production |
34| Monorepo | Root directory setting per project | One repo, multiple Vercel projects |
35| GitHub integration | Automatic on push | Zero-config CI/CD with preview per branch |
36| Programmatic config | `vercel.ts` with `@vercel/config` | Typed, dynamic configuration alternative |
37| Fluid compute | Enabled by default for new projects | Multi-request workers, 300s default duration |
38| Rolling releases | Incremental rollout with monitoring | Gradual traffic shift with auto-rollback triggers |
39| Firewall rules | `vercel.json` WAF configuration | Block threats via dashboard, API, or config file |
40
41## Common Mistakes
42
43| Mistake | Correct Pattern |
44| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
45| Using `.env.production` for preview-specific values | Use Vercel environment variables scoped to preview environment |
46| Expecting `VERCEL_URL` to include protocol | Prepend `https://` manually; use `VERCEL_PROJECT_PRODUCTION_URL` for stable production URL |
47| Adding only apex domain without `www` | Add both `yourdomain.com` and `www.yourdomain.com` to avoid 404 on one |
48| Using Node.js APIs in edge functions | Edge runtime uses V8 only; `fs`, `path`, `process` are unavailable |
49| Exceeding 1024 static redirects | Use `bulkRedirects` property for large redirect sets (CSV/JSON/JSONL) |
50| Creating QueryClient or fetching in edge without streaming | Use streaming responses for long operations in edge functions |
51| Setting `maxDuration` above plan limit | Fluid compute default: 300s; Hobby: 60s, Pro: 300s, Enterprise: 900s max |
52| Conflicting DNS records for custom domain | Remove duplicate A records; keep only the Vercel-pointing record |
53| Not awaiting build in CI before deploy | Use `vercel build` then `vercel deploy --prebuilt` for reliable CI deploys |
54| Ignoring monorepo root directory setting | Set root directory per project in Vercel dashboard for correct builds |
55
56## Delegation
57
58- **Infrastructure review**: Use `Task` agent to audit deployment configuration
59- **Environment debugging**: Use `Explore` agent to trace environment variable issues
60- **CI/CD pipeline review**: Use `code-reviewer` agent for GitHub Actions workflow review
61
62## References
63
64- [Configuration: vercel.json, builds, rewrites, redirects, headers](references/configuration.md)
65- [Environment variables and custom domains](references/environment-and-domains.md)
66- [Edge and serverless functions](references/edge-and-serverless.md)
67- [CLI commands and CI/CD integration](references/cli-and-ci.md)
oakoss