Is Vercel free for Next.js hobby projects?

Vercel offers a free Hobby tier with usage limits on bandwidth, serverless function execution, and team features. Check vercel.com/pricing for current limits — they change over time. Personal projects and learning apps usually fit comfortably.

Why does my app work on localhost but return 500 on Vercel?

Most often a server-side environment variable exists in your local .env but was never added to Vercel. Less commonly, code assumes a filesystem path or SQLite file that does not exist in serverless. Check Vercel Runtime Logs for the stack trace.

Do I need to run npm start on Vercel?

No. Vercel runs next build during deploy and serves the output with its own infrastructure. You only configure the build command — not a long-running start process like Railway requires for Django.

What is the difference between App Router and Pages Router for deploy?

Both deploy to Vercel the same way. App Router (app/) uses Server Components and route.ts handlers; Pages Router (pages/) uses getServerSideProps and pages/api. Know which your project uses when debugging 404s and API errors.

Can I deploy Next.js on Railway instead?

Yes, but you configure the Node server yourself. Vercel is optimized for Next.js out of the box. Railway makes more sense when Next.js is one service in a larger backend-heavy project.

Deploy

Deploy Next.js for Beginners

Next.js is the default frontend stack in many AI-built projects — and Vercel, the company behind Next.js, is the most beginner-friendly place to host it. This guide covers when that pairing makes sense, how to prepare your repo, the exact Vercel deploy steps, environment variables (including the NEXT_PUBLIC_ prefix), and the error messages that waste hours on a first launch. If Cursor or another AI tool generated your project, you will also get a copy-ready prompt to audit it before you click Deploy.

Updated July 2026 · 12 min read

Written for AI makers using tools like Cursor, Bolt, Lovable, Replit, Claude, and ChatGPT.

Quick answer

Push your Next.js app to GitHub with a clean .gitignore, import the repo on Vercel, add environment variables from .env.example (NEXT_PUBLIC_ for browser-visible values), and deploy. Redeploy after every env change. Build failures usually mean a TypeScript error or missing dependency; runtime 500s usually mean a missing server-side env var.

Best for

Next.js apps from create-next-app or AI tools (Cursor, Bolt, v0)

Deploy to

Vercel — Hobby tier works for personal and learning projects

Main risk

Secrets in NEXT_PUBLIC_ vars or missing server-side env vars

What gets deployed

Next.js build output on Vercel's serverless infrastructure

Who this is for

You have a Next.js app that runs locally with npm run dev and you want a public URL
An AI tool built your project and you are not sure which env vars belong on Vercel
Your Vercel build failed or your live site shows errors that did not appear on your laptop

What you'll need

Next.js project on GitHub (no .env or secrets in the repo)
Vercel account (free Hobby tier works for personal projects)
Roughly 20–45 minutes for your first deploy

Key concept

When Vercel + Next.js is the right choice

Vercel is built for Next.js. Framework detection, build caching, edge middleware, and serverless API routes all work out of the box with minimal configuration. If your project was created with create-next-app or has next in package.json dependencies, Vercel is almost always your fastest path to production.

Choose Vercel when your app is primarily a React UI with optional API routes inside the Next.js project. Marketing sites, dashboards, SaaS frontends, and full-stack apps that fit the Next.js model deploy cleanly here. Vercel also handles preview deployments for every pull request — useful when you iterate with AI and want to test before merging.

Vercel is not the right host for a standalone Django, FastAPI, or long-running Node server that is not part of a Next.js app. If your backend is a separate Python project with manage.py, deploy that on Railway and keep Next.js on Vercel — or pick a host that runs both. See our Railway vs Vercel comparison if you are unsure.

You can deploy Next.js elsewhere (Railway, Render, self-hosted Docker), but you will configure more yourself. For a first launch, Vercel removes friction so you can focus on env vars and app logic instead of infrastructure.

Deploy settings

Prepare your repository before Vercel

Vercel pulls code from GitHub — it does not read files on your laptop. Your repo must be clean, complete, and free of secrets before you connect it.

Confirm package.json includes a build script (create-next-app sets "build": "next build" by default) and that npm run build succeeds locally. Fix TypeScript and lint errors now; Vercel will fail the same way your laptop would.

Add .env to .gitignore if it is not already there. Commit .env.example listing every variable name with placeholder values — this becomes your checklist on Vercel. Never push real API keys to GitHub.

Check next.config.js or next.config.ts for hardcoded localhost URLs, experimental flags you do not need in production, or image domains that must include your production hostname. AI-generated configs sometimes whitelist only localhost.

If you use the App Router (app/ directory), ensure each route exports correctly and that any server-only code does not import browser APIs. If you use the Pages Router (pages/ directory), confirm getServerSideProps and API routes in pages/api/ are committed.

npm run build passes locally before connecting Vercel
.env in .gitignore — .env.example committed
No secrets, node_modules, or .next/ folder on GitHub
README or .env.example documents required environment variables

Deploy settings

Deploy on Vercel step by step

Sign up at vercel.com with your GitHub account. Click Add New → Project → Import your repository. Vercel usually detects Next.js automatically and sets Framework Preset to Next.js, Build Command to next build, and Output Directory to the default (leave blank for standard Next.js).

Before clicking Deploy, open Environment Variables. Add each name from .env.example. Use Production, Preview, and Development scopes unless you have a reason to limit them. Skipping this step causes runtime errors that look like mysterious 500 pages.

Click Deploy and watch the build log. A successful deploy ends with a green checkmark and a URL like your-project.vercel.app. Open it in an incognito window to avoid cached local auth cookies.

Every git push to your main branch triggers a new production deploy. Pushes to other branches create preview URLs — handy for testing AI-generated changes before they go live.

To add a custom domain later, go to Project Settings → Domains. Update any OAuth callback URLs, NEXT_PUBLIC_ site URLs, and CORS settings when the domain changes.

Framework: Next.js · Build: next build
Output directory: leave blank (default)
Add env vars before first Deploy click
Test *.vercel.app in incognito

Key concept

Environment variables: NEXT_PUBLIC_ vs server-only

Next.js splits environment variables into two worlds. Variables without a special prefix are server-only — they exist during build and on the server at request time, but never ship to the browser. Use these for database URLs, secret API keys, and signing secrets.

Variables prefixed with NEXT_PUBLIC_ are embedded into the client-side JavaScript bundle. Anyone can read them in the browser dev tools. Only put values in NEXT_PUBLIC_ that are safe to expose — public Supabase anon keys (with RLS enabled), public Stripe publishable keys, or your production API base URL if it is not secret.

A common AI mistake is putting a secret key in NEXT_PUBLIC_STRIPE_SECRET or NEXT_PUBLIC_OPENAI_KEY. That exposes credentials to every visitor. Move secrets to server-only names and call them from Server Components, Route Handlers (app/api), or API routes (pages/api).

Vercel does not read your local .env file automatically. You must enter each variable in the dashboard. After adding or changing any variable, trigger a redeploy — env changes do not apply to already-built bundles for NEXT_PUBLIC_ vars until a new build runs.

For local development, .env.local holds your values. For production, Vercel's dashboard is the source of truth. Keep .env.example in sync when you add new features that need new keys.

Server-only vars: no prefix — DATABASE_URL, secret keys
Browser-safe vars: NEXT_PUBLIC_ prefix only
Redeploy after every env change on Vercel

App Router vs Pages Router on deploy

Next.js has two routing systems. The App Router uses an app/ folder with layout.tsx and page.tsx files. The Pages Router uses a pages/ folder. Both deploy to Vercel, but the errors differ when something is misconfigured.

App Router server components run only on the server — they can read secret env vars directly. Client components (marked with "use client") cannot access server-only env vars; use NEXT_PUBLIC_ or pass data from a server parent as props.

Dynamic routes in the App Router use folders like app/blog/[slug]/page.tsx. If a live URL 404s but works locally, check that the dynamic segment folder name matches your links and that you did not forget to export a default page component.

Pages Router API routes live in pages/api/. App Router Route Handlers live in app/api/.../route.ts. Mixing conventions in one project confuses beginners — know which one your AI tool used before debugging API failures.

Watch out

Common Next.js deploy errors and fixes

Build fails on Vercel but works locally: usually a case-sensitive import (Linux build servers are strict), a missing dependency not listed in package.json, or a TypeScript error you ignored locally. Read the last 30 lines of the Vercel build log — the first error in the stack trace is the fix target.

500 Internal Server Error on every page: often a missing server-side environment variable. Check DATABASE_URL, API keys, and auth secrets in Vercel settings, then redeploy.

Blank page or hydration mismatch: client and server rendered different HTML — common when Date.now(), random values, or browser-only APIs run in server components. Fix in code or move logic to useEffect in a client component.

Module not found: package installed globally or only in devDependencies but imported in production code. Move it to dependencies and push again.

Image optimization errors: add remote image hostnames to images.domains or images.remotePatterns in next.config. AI templates often allow only localhost until you update config for production URLs.

After your first successful deploy

Test signup, login, payments, and any AI features on the live URL — not just the homepage. Auth callbacks must use your vercel.app domain (or custom domain) in the provider dashboard, not http://localhost:3000.

Enable Vercel Analytics or connect an error monitoring tool if you expect real users soon. Free tiers have limits — check current Vercel pricing if traffic grows.

When you fix bugs locally, commit and push. Vercel rebuilds automatically. If you only changed environment variables, use Redeploy from the dashboard without a new commit.

Run a launch readiness scan on your repo before sharing widely — AI projects often ship with debug logging, missing .env.example entries, or insecure NEXT_PUBLIC_ usage that a scan catches in minutes.

Next.js vs React/Vite deploy

Criteria	Next.js	React + Vite
Typical host	Vercel (optimized)	Vercel, Netlify, Cloudflare Pages
Build command	`next build`	`npm run build`
Output	Vercel-managed (leave output blank)	`dist/` folder
Env prefix	`NEXT_PUBLIC_` (client) + server-only vars	`VITE_` (client only)
Server needed?	Serverless on Vercel — API routes included	Static files only — separate backend elsewhere

Step-by-step

1
Step 1
Verify build locally
Run npm run build in your project folder. Fix every error before touching Vercel. Confirm .env is gitignored and .env.example lists all variables.
2
Step 2
Push to GitHub
Commit and push via Cursor, GitHub Desktop, or git. Open github.com and confirm no .env or secrets appear in the file list.
3
Step 3
Import on Vercel
vercel.com → Add New → Project → import your repo. Keep Next.js defaults unless you have a custom monorepo root.
4
Step 4
Add environment variables
Copy names from .env.example into Vercel Environment Variables. Use NEXT_PUBLIC_ only for browser-safe values. Redeploy after saving.
5
Step 5
Deploy and test live
Click Deploy, wait for the build, open the *.vercel.app URL in incognito. Walk through your main user flow and check Vercel function logs if anything fails.

Common mistakes

Putting secret API keys in NEXT_PUBLIC_ variables
What happens: Every visitor can read secrets in browser DevTools — immediate security exposure.
How to fix it: Rename to server-only env vars and access them from Server Components, Route Handlers, or pages/api — never from client components.
Expecting Vercel to read your local .env file
What happens: Runtime 500 errors because DATABASE_URL and other server vars are undefined on Vercel.
How to fix it: Manually add every variable in Vercel Project Settings → Environment Variables, then redeploy.
Deploying without running npm run build locally first
What happens: Same TypeScript or dependency errors fail on Vercel with less helpful context.
How to fix it: Fix TypeScript and dependency errors locally — the Vercel log will show the same failures with less context.
Leaving OAuth redirect URIs pointing at localhost
What happens: Auth works locally but login redirects fail or loop on the live Vercel URL.
How to fix it: Update Google, GitHub, Clerk, or Auth0 callback URLs to https://your-app.vercel.app/api/auth/callback/... (exact path depends on your auth library).
Deploying Django or a separate Python API to Vercel alongside Next.js without understanding serverless limits
What happens: Python backend fails or times out — Vercel is not built for long-running Django servers.
How to fix it: Host Python backends on Railway; use Vercel for the Next.js frontend only, or pick one full-stack host.

Copy-ready prompt

Prompt: prepare Next.js app for Vercel deploy

Paste this into Cursor, Claude, ChatGPT, Bolt, Lovable, or your AI coding tool.

Ready to paste

I am deploying this Next.js app to Vercel. Audit the project for production readiness.

1. Confirm package.json has correct build and start scripts for Vercel.
2. List every environment variable. Mark each as server-only or NEXT_PUBLIC_ (browser-safe only).
3. Find any secret keys incorrectly prefixed with NEXT_PUBLIC_ and fix them.
4. Check next.config for image domains, redirects, and hardcoded localhost URLs.
5. Identify whether this uses App Router (app/) or Pages Router (pages/) and flag any routing issues.
6. Create or update .env.example with placeholders — no real secrets.
7. Confirm .env and .next are in .gitignore.
8. List anything that will cause the Vercel build to fail or runtime 500 errors.

Do not commit real API keys. Tell me the exact variables to add in the Vercel dashboard.

Paste this into Cursor, Claude, ChatGPT, Bolt, Lovable, or your AI coding tool.

Ready check

Before you deploy

Work through these checks before you connect a host.

npm run build succeeds locally
.env gitignored — .env.example committed with all variable names
Code pushed to GitHub — no secrets visible on github.com
Vercel project imported from GitHub with Next.js preset
Server secrets added without NEXT_PUBLIC_ prefix
Browser-safe values use NEXT_PUBLIC_ prefix only
OAuth and auth callback URLs updated for production domain
First deploy succeeded — main user flow tested on live URL
Redeploy triggered after any env variable change

Frequently asked questions

Is Vercel free for Next.js hobby projects?: Vercel offers a free Hobby tier with usage limits on bandwidth, serverless function execution, and team features. Check vercel.com/pricing for current limits — they change over time. Personal projects and learning apps usually fit comfortably.
Why does my app work on localhost but return 500 on Vercel?: Most often a server-side environment variable exists in your local .env but was never added to Vercel. Less commonly, code assumes a filesystem path or SQLite file that does not exist in serverless. Check Vercel Runtime Logs for the stack trace.
Do I need to run npm start on Vercel?: No. Vercel runs next build during deploy and serves the output with its own infrastructure. You only configure the build command — not a long-running start process like Railway requires for Django.
What is the difference between App Router and Pages Router for deploy?: Both deploy to Vercel the same way. App Router (app/) uses Server Components and route.ts handlers; Pages Router (pages/) uses getServerSideProps and pages/api. Know which your project uses when debugging 404s and API errors.
Can I deploy Next.js on Railway instead?: Yes, but you configure the Node server yourself. Vercel is optimized for Next.js out of the box. Railway makes more sense when Next.js is one service in a larger backend-heavy project.