How to deploy a Next.js app to Vercel

Status: 🟩 COMPLETE Last updated: 2026-06-19 Plain-English tagline: From a Next.js app on your laptop to a live URL on the internet — in about 10 minutes.

Goal

You have a Next.js app working locally (npm run dev shows it at http://localhost:3000). At the end of this guide, that same app will be live on the public internet at a .vercel.app URL, automatically redeploying every time you push to GitHub.

Prerequisites

A Next.js app that runs locally. If you don’t have one yet, run npx create-next-app@latest my-app and follow the prompts.
A GitHub account. Free at github.com. The app needs to live in a GitHub repository for Vercel to deploy it. (Vercel also supports GitLab and Bitbucket, but GitHub is the most common path.)
A Vercel account. Free at vercel.com. Sign up using your GitHub account so the two are linked from the start.
Git installed locally and configured with your name and email. Test with git --version. If missing, install from git-scm.com.
Node.js installed (already required to have built the Next.js app). Test with node --version — should be 20 or higher in 2026.

Steps

1. Make sure the app builds locally

Before deploying anywhere, prove that the production build works on your machine. This catches problems that npm run dev lets slide.

npm run build

This should finish with no errors. If it fails, fix the errors first — Vercel will fail the same way. The most common build-time errors are:

TypeScript errors (tsc failures)
Missing environment variables that are required at build time
Import paths that resolve in dev but not in production (case-sensitivity matters on Linux, which is what Vercel runs on, but not on Windows/macOS by default)

💡 Habit: Run npm run build before every push to main. The minute it takes locally is much cheaper than waiting for Vercel to fail.

2. Push the project to GitHub

If the project isn’t already in a GitHub repository:

# from inside the project folder
git init
git add .
git commit -m "initial commit"

Then create a new repository on GitHub.com (call it whatever you want; can be public or private), and follow the instructions GitHub shows you to “push an existing repository from the command line.” It looks like:

git remote add origin https://github.com/YOUR-USERNAME/YOUR-REPO.git
git branch -M main
git push -u origin main

After this, refresh your GitHub repo page — you should see all your files there.

3. Import the repository on Vercel

Go to vercel.com/new.
You’ll see a list of your GitHub repositories. (If your repo isn’t listed, click “Adjust GitHub App Permissions” and grant Vercel access to the repository.)
Click Import next to your repository.

4. Configure the project

Vercel will detect that it’s a Next.js project automatically. The defaults are correct for almost every project:

Framework Preset: Next.js
Root Directory: ./ (unless the Next.js app is in a subfolder — e.g. a monorepo — in which case set it accordingly)
Build Command: next build (auto)
Output Directory: (Vercel handles this; leave blank)
Install Command: npm install (auto)

If your app uses environment variables (e.g. Supabase URL, API keys), expand the “Environment Variables” section and add each one. Paste the value, click “Add,” repeat. You can copy these from your local .env.local file. Don’t ever paste a service_role key or any secret into a NEXT_PUBLIC_* variable — those are exposed to the browser.

5. Deploy

Click Deploy. Vercel will:

Clone your repo.
Run npm install.
Run npm run build.
Upload the built output to Vercel’s CDN.
Give you a live URL — usually your-repo-name.vercel.app (sometimes your-repo-name-{hash}.vercel.app for branch deploys).

The first deploy typically takes 1–3 minutes. Subsequent deploys are usually faster because of build caching.

6. Verify

Open the live URL in your browser. Confirm the app loads and works.
Open the Vercel dashboard → your project → Deployments. You should see your deployment listed as “Ready.”
Open Functions tab — any serverless functions or server actions you wrote will be listed there. Make sure the region matches what you expect (default is iad1 — Washington DC; you can change it in vercel.json).
Push a tiny change (e.g. edit a heading) and git push. Within seconds, Vercel will trigger a new deployment automatically — this is the whole point.

Common failures and fixes

”Type error” during build

The build logs in the Vercel dashboard will quote the exact TypeScript error. Open the file locally, fix the type, commit, push. Vercel auto-redeploys.

💡 Avoid: Setting ignoreBuildErrors: true in next.config.js. It hides real bugs that will hit you in production.

”Module not found” — works locally but not on Vercel

The almost-certain cause is case sensitivity. Vercel runs on Linux, which treats Button.tsx and button.tsx as different files. Windows and macOS (by default) don’t. Check your import paths exactly match file names, character for character.

”Environment variable is undefined” in production

Three checks:

Did you add the env var to Vercel? Local .env.local doesn’t deploy. You must add each variable in the Vercel project’s Settings → Environment Variables.
Did you use the right prefix? Server-side variables can be named anything (e.g. DATABASE_URL). Client-side variables must start with NEXT_PUBLIC_ (e.g. NEXT_PUBLIC_SUPABASE_URL). Without that prefix, the browser will see undefined.
Did you redeploy after adding the variable? Vercel does NOT automatically pick up env var changes on existing deployments. Go to Deployments → click ”…” → “Redeploy.”

Build succeeds, but the site shows the wrong page or errors at runtime

Open the Vercel function logs (Project → Logs) or the browser console. The Vercel logs show server-side errors; the browser console shows client-side ones. Both are essential. Don’t rely on the static “Ready” status — that just means the build finished, not that the app actually works.

”Domain not pointing to the right place”

If you set up a custom domain and it shows the wrong content (or a Vercel “404 — not found”), see the separate guide Connect a custom domain.

What just happened, conceptually

You set up a continuous deployment pipeline:

Your code lives in GitHub (version control).
Vercel watches the main branch.
Every push to main triggers a build on Vercel’s machines.
If the build succeeds, the new version replaces the old one almost instantly (no downtime).
Vercel keeps every previous deployment around — you can roll back to any past version with a single click from the dashboard.

This pattern (git push → build → deploy → serve) is called CI/CD (Continuous Integration / Continuous Deployment). Vercel is one way to do it; the same idea applies to Netlify, Cloudflare Pages, AWS Amplify, and many others.

Tech & AI, Explained

Explorer

deploy-nextjs-to-vercel