How to Deploy a Next.js App to Vercel: Complete Step-by-Step Guide (2026)
Deploy a modern Next.js App Router application to Vercel: verify the production build, connect GitHub, configure environment variables, set up a custom domain, and troubleshoot failed deployments.
Build and test your Next.js app locally with npm run build, push the repository to GitHub, then create a Vercel project by importing that repository. Confirm the detected framework and root directory, add production and preview environment variables, and deploy. Every non-production branch can receive a preview deployment; merges or pushes to the configured production branch create production deployments.
1. Why deploy a Next.js app to Vercel?
Next.js can run on many Node.js hosts, in Docker, or as a static export when its feature set allows it. Vercel is a common choice because it understands Next.js conventions, creates deployments from Git commits, provides preview URLs, and handles HTTPS for verified domains. It is not required for Next.js; choose it when its Git workflow and managed platform fit your application.
| Need | What happens |
|---|---|
| Review a change before it is live | A push to a non-production branch can create a Preview deployment with its own URL. |
| Publish a release | A push or merge to the configured production branch creates a Production deployment. |
| Use framework conventions | Vercel detects Next.js and uses the project build settings you review during import. |
| Use a domain securely | After DNS verification, Vercel provisions and renews HTTPS certificates automatically. |
2. What you need before deploying
Prepare these first
- A Next.js project that starts locally and has a committed lockfile.
- A Node.js version supported by your version of Next.js and your dependencies.
- A GitHub account and a repository you can push to.
- A Vercel account connected to GitHub, or a plan to use the Vercel CLI.
- Values for every production environment variable, plus a safe plan for preview values.
- A domain you control if you want a custom domain.
node --version
npm --version
git --version
Helpful SovranCode setup guides
3. Create a Next.js app with create-next-app
If you already have an application, skip to the local build check. For a new App Router project, create-next-app asks which options you want and writes the application into a new folder. The command below uses the current starter defaults interactively.
npx create-next-app@latest my-next-app
cd my-next-app
npm run dev
Choose TypeScript, ESLint, and the App Router when they suit your project. The initializer can also create a src directory and configure an import alias. Do not copy a list of flags from an old tutorial without checking the prompts from your installed create-next-app release.
4. Run and test the application locally
A development server proves that source files can be served; it does not prove that a production build succeeds. Run the build before you hand the project to a deployment platform. Then start the built application and check important routes, forms, and server behavior.
# Development server
npm run dev
# Stop the development server, then create the production build
npm run build
# Serve the generated production build locally
npm run start
Before you push
- npm run build exits successfully.
- Your production start command serves expected pages.
- There are no secrets in .env files that Git will track.
- Your .gitignore excludes .next, node_modules, and local environment files.
- You know which runtime values are needed in Production and Preview.
5. Push your Next.js project to GitHub
Vercel's Git integration needs a repository it can read. Create an empty repository on GitHub first, then use its exact HTTPS or SSH URL. If GitHub creates starter files, pull or reconcile them before your first push instead of overwriting work blindly.
git init
git add .
git commit -m "Create Next.js app"
git branch -M main
git remote add origin https://github.com/YOUR_ACCOUNT/YOUR_REPOSITORY.git
git push -u origin main
6. Connect GitHub to Vercel
- 01
Sign in to Vercel
Open the Vercel dashboard and sign in, then connect GitHub when prompted or from your account integrations.
- 02
Grant the smallest repository access that works
Authorize the repositories or organization access needed for this project. Organization owners may need to approve the Vercel GitHub app.
- 03
Confirm the correct account or team
Choose the personal account or team that should own billing, domains, environment variables, and deployment access.
7. Import your project into Vercel
- 01
Choose New Project
In the Vercel dashboard, select New Project and choose the GitHub repository.
- 02
Review project settings
Set a clear project name, confirm the Framework Preset is Next.js, and choose a root directory only if the app is inside a subfolder or monorepo.
- 03
Keep defaults unless the repository requires changes
A standard Next.js project normally supplies its own build and start behavior. Change install, build, output, or root settings only for a documented project reason.
- 04
Add environment variables before the first deploy
Enter the values needed by the app and select the environments that should receive each value.
- 05
Select Deploy
Vercel clones the selected commit, installs dependencies, runs the build, and shows the build log and deployment URL.
8. Configure project settings and environment variables
Add values in Project Settings → Environment Variables and choose Development, Preview, Production, or a specific preview branch when appropriate. Variable changes apply to new deployments, not deployments that already exist, so redeploy after changing a value.
# Server-only: do not expose this value to browser code
DATABASE_URL=postgresql://...
STRIPE_SECRET_KEY=sk_...
# Safe to expose only when the value is intentionally public
NEXT_PUBLIC_API_BASE_URL=https://api.example.com
| Variable | Who can read it? | Use it for |
|---|---|---|
| DATABASE_URL | Server code only, when not imported into a client bundle | Database connection strings and private credentials. |
| NEXT_PUBLIC_API_BASE_URL | Included in browser JavaScript at build time | Public configuration such as a public API origin. |
| STRIPE_SECRET_KEY | Server code only | Private provider credentials and signing operations. |
9. Deploy your Next.js application
The import flow creates an initial deployment. Read its logs rather than relying only on the success badge. Open the URL, test a representative route, and verify server-dependent features with a safe test account or non-production data.
- 01
Read the build output
Look for the install command, Node.js version, build command, routes, and the first actual error if the deployment fails.
- 02
Open the deployment URL
Test pages that use dynamic routes, images, redirects, authentication boundaries, and APIs—not only the home page.
- 03
Promote only what you verified
Use a preview deployment for changes first. Production should refer to the reviewed commit, not an untested local state.
10. Set up a custom domain and HTTPS
In the project Domains settings, add the domain you own. Vercel shows the DNS record it needs. Add exactly that record at your DNS provider, wait for it to propagate, and then inspect the domain status in Vercel. Vercel issues HTTPS after domain verification; do not upload a separate certificate unless your architecture requires it.
| Domain | Typical DNS action | Decision to make |
|---|---|---|
| example.com | Use the record Vercel specifies for the apex domain | Choose whether the apex or www is canonical. |
| www.example.com | Use the CNAME target Vercel specifies | Redirect or assign it consistently with the apex. |
| app.example.com | Use the CNAME target Vercel specifies | Use it as an application subdomain only when that separation is intentional. |
11. Configure production and preview environments
Vercel has Local, Preview, and Production environments. Preview deployments normally come from branches other than the production branch; production comes from the configured production branch, commonly main. Keep separate values when a preview should use a test database, test payment keys, or a non-production callback URL.
| Environment | Use it for | Example variable approach |
|---|---|---|
| Development | Your local machine | Local database and local callback URLs in .env.local. |
| Preview | Pull requests and branch testing | Isolated or test services; never point destructive tests at production data. |
| Production | Your public domain | Production database, secret keys, and canonical URLs only. |
12. Enable automatic deployments from GitHub
After Git import, Vercel automatically deploys new commits. A branch that is not the production branch produces a Preview deployment. When a reviewed pull request merges into the production branch, Vercel creates a Production deployment. You can change the production branch in project settings if main is not your release branch.
git checkout -b feature/profile-page
git add .
git commit -m "Add profile page
git push -u origin feature/profile-page
# Open the Preview URL from Vercel or the pull request, review it, then merge to main.
13. Deploy using the Vercel CLI
The dashboard is convenient for the first import; the CLI is useful when you need to link a local folder, pull environment values, deploy from a terminal, inspect logs, or use a Git provider that is not connected to Vercel.
# Install the CLI globally with npm
npm install --global vercel
# Authenticate, then link this directory to a project
vercel login
vercel link
# Pull development values into a local file (keep it out of Git)
vercel env pull .env.local
# Create a Preview deployment
vercel deploy
# Create a Production deployment
vercel deploy --prod
# List configured variables without printing their values
vercel env ls
# Inspect errors for a deployment
vercel logs --deployment <deployment-url-or-id> --level error
# Confirm a route through a deployment
vercel curl / --deployment <deployment-url>
14. Common deployment errors and how to fix them
| Symptom | Likely cause | Useful next step |
|---|---|---|
| Build fails locally and on Vercel | A real TypeScript, lint, dependency, or build error | Run npm run build locally and fix the first error before redeploying. |
| Node.js version or engine failure | The project's engines field or a dependency needs a different Node.js version | Check package.json and the build log, then select a supported version deliberately rather than suppressing the warning. |
| Module not found on Vercel | Case mismatch, missing committed file, or dependency not listed | Check Git status, filename casing, and package.json; macOS can hide case mistakes. |
| Environment variable is undefined | Missing value, wrong environment target, or no redeploy after a change | Add the variable to the right Vercel environment and create a fresh deployment. |
| Works locally but fails in production | Local .env values, a local service, or runtime assumption is missing | Compare non-secret configuration names and use production-safe dependencies. |
| Server function times out or errors | Slow external work, an unhandled error, or a route that assumes local state | Inspect runtime logs, add bounded timeouts, and move long-running work to a suitable asynchronous architecture. |
| 404 on a dynamic route | Route, deployment, rewrite, or link differs from the tested path | Open the exact route in Preview and inspect Next.js route definitions and redirects. |
| Image host is rejected | next/image does not allow an unconfigured remote source | Add the exact trusted host to Next.js image configuration, then build and test again. |
| Domain is not verified | DNS record is absent, conflicts, or has not propagated | Use Vercel's current DNS instructions and inspect the domain status before changing more records. |
15. Performance and production best practices
- Run npm run build in CI or before a production merge; do not rely only on next dev.
- Use Next.js Image for suitable remote or local images and configure allowed remote sources deliberately.
- Keep server-only data access and secrets out of Client Components and NEXT_PUBLIC_ variables.
- Use Preview deployments for review, then test critical production flows after release.
- Set a canonical production URL in your application metadata and use it consistently in redirects, OAuth callbacks, and sitemap generation.
- Watch build and runtime logs after changes to authentication, database access, payments, or environment variables.
- Keep dependencies current with deliberate upgrade testing rather than unbounded automatic updates.
Keep learning
16. Vercel pricing: free versus paid plans
Vercel pricing and included usage change, so confirm the official pricing page before you choose a plan or promise a budget. Vercel documents Hobby as a free plan for personal projects, while Pro is aimed at professional work and team collaboration; Enterprise is priced by agreement. Usage limits, commercial-use terms, and plan features can change.
| Plan family | Typical fit | Check before committing |
|---|---|---|
| Hobby | Personal projects and individual experimentation | Current acceptable use, included usage, limits, and any feature restrictions. |
| Pro | Professional projects, clients, and teams | Per-seat pricing, included usage, collaboration, spend controls, and custom-environment needs. |
| Enterprise | Organizations needing contractual support and advanced governance | Security, SLA, support, access control, and contract details. |
Current plan details
17. Conclusion and next steps
A dependable deployment is a repeatable path: a clean local build, a reviewed Git commit, correctly scoped environment variables, a Preview deployment, and a production release with a rollback plan. Once that path works, document the project-specific commands and variables so the next developer can reproduce it.
- 01
Ship one small change through Preview
Use a branch, inspect the Preview URL, and confirm the commit that produced it.
- 02
Add a production readiness checklist
List required environment variable names, domain ownership, migrations, smoke tests, and rollback actions in the repository.
- 03
Make the deployment observable
Know where to find Vercel build logs, runtime logs, provider dashboards, and error reports before an incident.
Frequently asked questions
Is Vercel free for Next.js?
Vercel has a Hobby plan with free included usage for eligible personal projects. Plans, usage limits, and terms can change, so check Vercel's current plans and pricing pages before relying on it for a specific workload or commercial use.
Do I need a vercel.json file for a Next.js app?
Usually not. A standard Next.js app can be detected and deployed from its repository. Add vercel.json only when you have a documented need for a Vercel configuration that cannot live in your application or dashboard settings.
Are Next.js environment variables secure on Vercel?
Vercel stores configured environment variables outside your source repository, but access still depends on project permissions. Server-only variables must not use the NEXT_PUBLIC_ prefix or be imported into browser code. Rotate a value if it was exposed.
How do Preview deployments work?
With a connected Git repository, Vercel normally creates a Preview deployment for a push to a branch other than the production branch. It gives that commit a separate URL for testing and review before you merge it to production.
Why did my Vercel deployment fail when npm run dev works?
next dev and next build exercise different paths. Run npm run build locally, then read the first Vercel build error. Common causes are type errors, a missing dependency, filename case mismatches, or a missing environment variable.
Can I use my own domain with Vercel?
Yes. Add the domain in your Vercel project, create the exact DNS record Vercel requests at your DNS provider, and wait for verification. Vercel then provisions HTTPS for the verified domain.
Should Preview use the production database?
Usually no. Preview deployments should use isolated or test-safe services and credentials. Pointing branch previews at production can expose user data or allow test behavior to alter live records.
Can I deploy without GitHub?
Yes. The Vercel CLI can link a local directory and deploy it. Git integration is still valuable for automatic Preview and Production deployments tied to a reviewable commit history.
