Skip to content
Back to Deployment

Deploying with Vercel

Zero-config deployment for Next.js, Astro, and static sites with edge functions and preview deploys.

PlatformsBeginner

Why

Vercel eliminates infrastructure management for frontend-fullstack apps. Git push triggers build, preview deploy, and production promotion automatically.

Edge functions run close to users globally with sub-50ms cold starts.

When

Choose Vercel for Next.js/Astro/Remix apps, teams wanting preview deploys per PR, and projects needing edge middleware without Kubernetes complexity.

How

1. Install Vercel CLI — npm i -g vercel 2. Link project — run "vercel" in project root, import or create project 3. Configure build — vercel.json for framework overrides, env vars, routes 4. Preview deploy — every git push creates a preview URL automatically 5. Production deploy — merge to main branch or run "vercel --prod" 6. Custom domain — add in dashboard, configure DNS CNAME or nameservers 7. Edge functions — create functions in /api with export const config = { runtime: "edge" }

Example

// vercel.json — Astro project config { "framework": "astro", "buildCommand": "npm run build", "outputDirectory": "dist_astro", "functions": { "api/*.ts": { "runtime": "edge" } }, "headers": [ { "source": "/(.*)", "headers": [ { "key": "X-Content-Type-Options", "value": "nosniff" }, { "key": "X-Frame-Options", "value": "DENY" } ] } ], "redirects": [ { "source": "/old-path", "destination": "/new-path", "permanent": true } ] } // Edge function — api/geo.ts export const config = { runtime: "edge" }; export default function handler(req: Request) { const country = req.headers.get("x-vercel-ip-country") || "unknown"; return Response.json({ country, message: `Hello from ${country}` }); }

Common Problems

  • ⚠Build fails on Vercel but passes locally — missing environment variable not set in dashboard
  • ⚠Edge function exceeds 1MB limit — dynamic imports or large dependencies blow the bundle
  • ⚠Hobby plan 100GB bandwidth exceeded — image optimization or video streaming consumes quota fast
  • ⚠Cold start latency on serverless functions — first request after idle takes 2-5 seconds

Best Practices

  • ✓Use preview deploys for every PR — catch integration issues before merge
  • ✓Set environment variables in Vercel dashboard, not in .env files committed to git
  • ✓Enable Skew Protection for Next.js — handles dual-version deploys during rollout
  • ✓Use vercel.json rewrites for SPA fallback, not for API proxying — use edge functions instead

FAQ

Why does my build fail on Vercel but pass locally?

Vercel uses a read-only filesystem except /tmp and caches node_modules differently. Check that your build doesn't write to the project root and that your Node version matches (set via .nvmrc or vercel.json).

How do I set environment variables for preview vs production?

In the Vercel dashboard, scope env vars per environment. Mark secrets as Encrypted and never commit them. Preview env vars apply to all preview deployments unless scoped to a specific Git branch.

Why is my Next.js app slow on Vercel?

You're likely using SSR on every page. Convert static pages to SSG (getStaticProps) or ISR (revalidate). Vercel Analytics shows which routes are SSR and their TTFB.

How do I deploy a monorepo to Vercel?

Set rootDirectory in vercel.json to the app folder; Vercel builds only that workspace. Use Turborepo for caching — Vercel natively supports it and skips unchanged apps.

What's the difference between vercel deploy and vercel --prod?

vercel deploy creates a preview deployment (unique URL, doesn't affect production). vercel --prod promotes to the production domain. Always test on preview first, then promote.