---
name: deploy-nextjs-to-vercel
description: Deploys a Next.js app to Vercel with environment variables, a custom domain and preview deployments per branch. Use when the user wants to ship, host, publish or go live with a Next.js or React site on Vercel, or mentions vercel deploy, production URL or domains.
license: CC-BY-4.0
compatibility: Requires Node 20+, git and the Vercel CLI
metadata:
  category: deployment
  tags: "nextjs,vercel,react,hosting"
  author: johnny-bravo
  version: "1.1"
  updated: "2026-10-31"
  status: published
---

# Deploy Next.js to Vercel

## When to use
- Shipping a Next.js app for the first time, or adding a domain or preview environment.

## Steps
1. Check `npm run build` passes locally; fix type and lint errors first.
2. `npm i -g vercel`, then `vercel link` in the project root (or import the GitHub repo in the dashboard).
3. Set env vars per environment: `vercel env add NAME production` (see [env vars](references/env-vars.md)). Pull them locally with `vercel env pull .env.local`.
4. `vercel` for a preview URL; `vercel --prod` for production. Confirm the production URL loads and API routes respond.
5. Domain: Project > Settings > Domains, add your apex domain and its `www` subdomain, then set the DNS records Vercel shows (A/ALIAS for apex, CNAME for www).
6. Connect the Git repo so every branch push gets a preview URL and `main` deploys to production.

## Gotchas
- Server env vars without `NEXT_PUBLIC_` are not exposed to the browser; client code needs the prefix.
- Changing an env var needs a redeploy to take effect.
- Hobby plan is for personal, non-commercial use only. A business or commercial site (selling or advertising a product or service, taking payments, showing ads, or built by someone paid to make it) needs Pro: US$20 per month per developer seat, plus tax, as listed on vercel.com/pricing on 2026-10-31. Details: https://vercel.com/docs/limits/fair-use-guidelines

## Example prompt
"Put this on Vercel with my domain."