Deploying Next.js to Vercel is the closest thing to a one-click experience in web dev. But “almost zero config” is not “zero config”. The defaults are right for roughly 90% of projects; the last 10% (environment variables, custom domain, next/image domains, function regions) is where first-time deployers lose half a day. This walkthrough gets you from a local repo to a live custom domain, with the exact commands, the response headers to check, and the four mistakes that produce the most support threads.
TL;DR
- Push to GitHub, import at vercel.com, and Vercel auto-detects Next.js. First build is usually 60–120 seconds.
- Env vars live in the dashboard, not in
.env.local(Vercel never reads.env.local). A missing key is the #1 cause of “works locally,undefinedin production”. - The free Hobby plan is non-commercial only and capped at 100 GB Fast Data Transfer per month (as of June 2026). Commercial or team use needs Pro at $20 per seat per month.
- External images need an allowlist in
next.config.js(images.remotePatterns) ornext/imagethrowsInvalid src prop. - Functions default to the
iad1region (Washington, D.C.). Override per project if your users live elsewhere.
Hobby vs Pro: what actually changes
The Hobby plan is genuinely free and good enough to launch on, but it is explicitly non-commercial. The moment you put up a pricing page, run ads, or invite a teammate, Vercel’s terms require Pro. Here are the limits that matter for an indie launch, as of June 2026:
| Limit (per month) | Hobby (free) | Pro ($20/seat) |
|---|---|---|
| Commercial use | Not allowed | Allowed |
| Fast Data Transfer | 100 GB | 1 TB included, then pay-as-you-go |
| Function invocations | 1,000,000 | 1,000,000 included |
| Edge requests | 1,000,000 | 10,000,000 included |
| Build execution | 6,000 minutes | Included credit |
| Image Optimization (sources) | 1,000 images | 5,000 included |
| Deployments per day | 100 | 6,000 |
| Concurrent builds | 1 | 12 |
| Build time per deploy | 45 min max | 45 min max |
Hobby has one trap worth calling out: if you exceed a usage cap, the affected feature is paused until the 30-day window rolls over. Pro instead bills overage on a pay-as-you-go basis ($0.15/GB Fast Data Transfer beyond the first 1 TB, for example), with a $20 included credit each month. For most side projects, Hobby’s 100 GB is plenty; a content site doing real traffic will cross it.
Is Vercel the right fit?
Reach for Vercel when:
- You have a Next.js project in a GitHub, GitLab, or Bitbucket repo.
- You want a preview URL on every pull request without standing up your own CI.
- You are fine with usage-based billing once Hobby limits are reached.
It is the company behind Next.js, so the integration is unmatched: auto-detected framework, preview deploys per PR, edge-cached static assets, and first-class Incremental Static Regeneration (ISR). The trade-off is usage-based billing at scale and some lock-in to Vercel-specific features. If you run a high-bandwidth static site, Cloudflare Pages or Firebase Hosting can be cheaper; if you already run on AWS or GCP, sharing that infrastructure may beat a second platform. For a head-to-head, see Firebase vs Vercel.
Step by step
1. Push your Next.js project to GitHub
If you do not have a git history yet:
git init
git add .
git commit -m "initial commit"
# With the gh CLI installed:
gh repo create my-next-app --public --source=. --push
# Otherwise create the repo at github.com first, then:
git remote add origin https://github.com/you/my-next-app.git
git branch -M main
git push -u origin main2. Import the repo
Sign in at vercel.com with the same Git provider (OAuth), click Add New → Project, find the repo, and click Import. Vercel auto-detects Next.js and fills in:
Framework Preset: Next.js
Build Command: next build
Output Directory: .next (leave empty — automatic)
Install Command: npm installYou almost never need to touch these. The one common edit is the Node.js version under Settings → General if your project pins something specific in package.json’s engines field.
3. Add environment variables
On the same import screen, paste env vars under Environment Variables, one KEY=VALUE per line:
DATABASE_URL=postgresql://user:pass@host:5432/db
NEXT_PUBLIC_SITE_URL=https://yoursite.com
RESEND_API_KEY=re_xxxxxxxxxxxxxxxxUse the checkboxes on each row to pick environments (Production / Preview / Development). The same key can hold different values per environment. Keep a .env.local for local dev, but know that Vercel does not read .env.local — it only uses what is in the dashboard. Anything you want in the browser must be prefixed NEXT_PUBLIC_; everything else stays server-side.
4. Deploy
Click Deploy. The first build usually takes 60–120 seconds. You get a project-hash.vercel.app URL.
5. Verify the deployment
Open the generated *.vercel.app URL. In DevTools → Console, watch for hydration errors (Hydration failed because the initial UI does not match what was rendered on the server — usually caused by Date.now(), Math.random(), or window checks during render). In DevTools → Network, click any _next/static/* asset and check the headers:
x-vercel-cache: HIT # static assets are served from the edge cache
age: 123 # seconds since the cache was filledA HIT confirms the asset is being served from Vercel’s CDN rather than re-rendered.
6. Add a custom domain
Go to Settings → Domains → Add, enter yoursite.com, then add the DNS records Vercel shows at your DNS provider. As of June 2026, Vercel issues newer apex IPs for new projects, so use the exact values the dashboard gives you rather than copying from any guide. A typical set looks like:
Type Name Value
A @ 216.198.79.1 (or 76.76.21.21 — use what the dashboard shows)
CNAME www cname.vercel-dns.comOn Cloudflare, switch the proxy to DNS only (grey cloud) so Vercel can issue its own SSL certificate; leaving the orange cloud on causes SSL handshake errors. Verify:
dig yoursite.com +short
# should return the A record IP from the dashboard
curl -sI https://yoursite.com | head -5
# HTTP/2 200
# server: Vercel7. Allowlist external images for next/image
To load images from external hosts, add them to images.remotePatterns in next.config.js, or next/image throws Invalid src prop ... hostname is not configured under images in your next.config.js:
// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
images: {
remotePatterns: [
{ protocol: 'https', hostname: 'images.unsplash.com' },
{ protocol: 'https', hostname: 'cdn.yoursite.com' },
],
},
};
module.exports = nextConfig;See Next.js Image Optimization Basics for sizing and priority tuning. Note Hobby includes 1,000 optimized source images per month; heavy image sites will want to watch that cap.
8. (Optional) Set the function region
Vercel Functions default to iad1 (Washington, D.C.). For users concentrated in Asia, switch to hnd1 (Tokyo) or sin1 (Singapore). Create vercel.json in the project root:
{
"functions": {
"app/api/**": {
"maxDuration": 60,
"regions": ["hnd1"]
}
}
}With Fluid Compute (the default for new projects as of 2026), the function maxDuration default is 300 seconds on every plan; Hobby caps at 300 seconds and Pro can go up to 800 seconds (about 13 minutes). For latency-sensitive routes, you can opt into the edge runtime per route in the App Router instead:
// app/api/hello/route.ts
export const runtime = 'edge';9. Confirm PR previews work
Push a branch and open a PR:
git checkout -b test-preview
echo "<!-- test -->" >> README.md
git commit -am "test preview"
git push -u origin test-preview
gh pr create --fillVercel posts a branch-hash.vercel.app preview URL as a PR check. Reviewers click straight into the per-branch deployment, which runs the same code on the same compute as production but with the env vars you scoped to Preview.
The four mistakes that cost the most time
- Forgetting environment variables. A field that works locally returns
undefinedin production because Vercel does not read.env.local. Add every key in the dashboard and scope it to Production. - Setting
output: 'export'by accident. Static export disables image optimization, API routes, ISR, and middleware. If you need any of those, leave it off. - Skipping
images.remotePatterns.next/imagerefuses to optimize any external host you have not allowlisted, and the error only surfaces at runtime. - Leaving the region as
iad1for a non-US audience. Setregionsinvercel.jsonor move latency-critical routes toexport const runtime = 'edge'.
One more: treat preview URLs as previews. They share production’s compute limits but carry Preview-scoped env vars, so test a build before you “Promote to Production”.
FAQ
- Do I have to use Vercel for Next.js? No. Next.js runs on any Node host — AWS, Cloudflare (via OpenNext), or self-hosted. Vercel just has the deepest integration, and moving off costs you ISR-at-the-edge and image optimization conveniences.
- Is the Hobby tier really free? Yes, for non-commercial use, with 100 GB Fast Data Transfer and 1M function invocations per month as of June 2026. A pricing page, ads, or a teammate pushes you to Pro at $20 per seat per month.
- Does Vercel auto-deploy on every push? Yes.
maindeploys to production; other branches deploy to preview URLs. You can disable specific branches under Settings → Git. - Can I roll back instantly? Yes. Go to Deployments, find the previous good build, and click Promote to Production. The rollback is instant because the old deployment is already built.
- How long does the first build take? Typically 60–120 seconds for a fresh Next.js app. Builds are capped at 45 minutes on every plan; if you approach that, lean on ISR so fewer pages render at build time.
- What happens if I blow past Hobby’s 100 GB? The affected feature pauses until the 30-day window resets. To avoid downtime on a growing project, upgrade to Pro before you hit the cap.