Deploy Your First App to Vercel (No DevOps Experience)

So you built something with Cursor, v0, or Claude — and it works on your laptop. Now what?

Right now your app only exists at localhost:3000, which means exactly one person on Earth can see it: you. Deploying puts it on a server that’s always on, with a URL anyone can open. This takes about 15 minutes with Vercel’s free tier, and you don’t need to know anything about servers.

This guide covers importing a repository, checking the build settings, and inspecting a deployment. Before using Vercel for a commercial site, check its plan requirements; Hobby is for personal, non-commercial use.

What you’ll need

• A GitHub account (free)
• A Vercel account (free — you sign up with GitHub, one click)
• Your app building locally without errors
• About 15 minutes

Step 0: Make sure your project builds

Run this in your project folder:

npm run build

If the local build fails, resolve that error before pushing. Record the first failing command and its error output; a deployment wrapper’s exit code is not enough to diagnose it.

Step 1: Push your code to GitHub

Vercel deploys straight from a Git repository, so your code needs to live on GitHub first.

Create a repo at github.com/new. Two choices that matter:

• Private is fine. Vercel deploys from private repos. Your code stays hidden; only the built site is public.
• Don’t add a README or .gitignore if your project already has files — it just creates a merge conflict on your first push.

Then:

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/yourname/your-app.git
git push -u origin main

Before pushing: exclude private .env files and inspect staged files with git diff --cached. Use git ls-files to detect secrets already tracked by Git; adding a file to .gitignore does not untrack it. Rotate any credential that has been published.

Step 2: Import the project in Vercel

1. Sign up at vercel.com with Continue with GitHub — this connects your repos automatically.
2. Go to vercel.com/new and click Import next to your project.
3. Vercel detects your framework (Next.js, Vite, Astro…) and fills in the build settings. Confirm the detected framework, build command, and output directory against your project.
4. Click Deploy.

The build takes 60–90 seconds. When it finishes: confetti, and your app is live at your-app.vercel.app.

Open the URL and click through every page. Things that worked on localhost occasionally break in production — better you find it than your first user.

Step 3: Add your environment variables

If your app uses API keys (OpenAI, Supabase, Stripe…), it works locally because of your .env — which you correctly did not push. Production needs those values too:

1. In your Vercel project: Settings → Environment Variables.
2. Add each key-value pair from your .env.
3. Redeploy — variables only apply to new deployments. Deployments → ⋯ → Redeploy.

After changing a variable, create a new deployment and check the environment scope it uses.

One naming trap: variables prefixed with NEXT_PUBLIC_ (or VITE_ in Vite) get baked into the browser bundle and are publicly visible. Never put secret keys behind those prefixes — only values that are safe to expose, like a Supabase anon key.

These are Vercel’s rules, and they’re the ones I’d learn first. But heads up for later: if you move this project to Cloudflare Pages — common once a site starts earning, since the free plan permits commercial use — the same variable can sit in the dashboard and still read as undefined at build time, because that platform splits variables and secrets across a runtime boundary Vercel doesn’t have. See the four causes and how to tell them apart so a migration doesn’t cost you the evening this step just saved.

Step 4: Understand what you just set up

This is the part that makes it worth it:

• Every push to main redeploys automatically. Your workflow from now on: ask AI for changes → commit → push → site updates in about a minute.
• Pull requests get preview URLs. Work in a branch, and each PR deploys to its own temporary URL for testing.
• HTTPS is automatic. Vercel provisions and renews the certificate; you never touch it.
• Rollbacks are one click. Deployed something broken? Deployments → ⋯ → Promote an older deployment.

How to redeploy your app (without pushing code)

Pushing to main redeploys automatically — but sometimes you need to rebuild the same code: you added environment variables, a build flaked out halfway, or you just want a clean slate.

Go to your project’s Deployments tab, find the latest deployment, click ⋯ → Redeploy. One dialog appears with a single meaningful choice: “Use existing Build Cache.”

• Checked (default): faster, reuses cached dependencies and build artifacts. Fine for picking up new env vars.
• Unchecked: a full clean build. Choose this if you changed dependencies, or a previous build left something weird in the cache and you’re getting errors that make no sense.

Two things beginners get wrong here:

1. Redeploy rebuilds the same commit. It does not pull your newest local code — if you want new changes live, push them.
2. Redeploy ≠ rollback. Redeploy rebuilds the current version; to go back to an older working version, use ⋯ → Promote on that older deployment instead.

Common first-deploy errors

Error	Cause	Fix
Module not found: './Components/...'	macOS/Windows ignore file-name casing; Linux servers don’t	Match the exact casing in your imports (components vs Components)
Environment variable is undefined	Vars not added in Vercel, or added but never redeployed	Settings → Environment Variables, then redeploy
Build succeeds but page is blank	Client-side JS error or wrong router base path	Open DevTools console on the live site — the error is there
npm ERR! peer dep during build	Dependency conflict your local install tolerated	Run npm install locally, commit the updated package-lock.json, push
Deploy hangs or times out	A dev-server command ended up in your build script	Check the framework preset — build must produce output and exit

Blank page, or 404 on refresh? If the page renders but a deep link 404s the moment you refresh it, that’s a client-side routing problem, not a render crash. See how to fix 404s on refresh for Vercel, Netlify, and Cloudflare Pages. The row above is for when the page never renders at all.

That first error, Module not found, deserves special mention — it’s the one that works locally and only breaks on Vercel, and the fix is usually a single character. See why Module not found happens on Vercel but not locally (file casing, mostly) in its own guide.

For errors earlier in the build, use the build-stage diagnostic table.

And if there’s no error to copy — you pushed, GitHub has the commit, and Vercel shows no deployment whatsoever — none of this applies. That’s the trigger never firing, and the fix when Vercel shows no deployment after a push begins with a question you can answer in five seconds: did the Vercel Bot comment on your commit? Otherwise, copy the exact error from the Vercel build log and paste it into your AI tool along with “my Vercel deploy fails with this error.” Deploy errors are one of the things AI debugs best, because build logs are extremely literal.

What the free tier actually covers

Hobby gives you 100 GB of bandwidth a month, unlimited sites, and everything above. For a new project that’s effectively unlimited — you’d need tens of thousands of monthly visitors to notice the ceiling.

The two restrictions worth knowing: Hobby is licensed for non-commercial use, and serverless functions have execution time limits. Neither matters on day one. By the time it does, you’ll happily pay the $20/month for Pro.

Next steps

Your .vercel.app subdomain works, but it screams “weekend project.” A custom domain costs about $10 a year and takes 20 minutes to connect — the Vercel custom domain setup guide walks through it with Namecheap and Cloudflare. Don’t have a domain yet? Start with how to buy one and set up DNS. (And no, you don’t need to transfer your domain to Vercel — pointing it is enough.) If the domain attaches but the browser still warns you the connection isn’t private, don’t go buy a certificate — that’s a config error with a short list of causes, and these are the fixes. Then set up analytics, because watching your first real visitor arrive is the moment this stops being a toy.

And when the app is live and you’re ready to charge for it: before you open a Stripe account, read merchant of record vs payment processor — the difference decides who files your sales tax, and picking wrong is expensive. While you’re at it, settle the other question every solo dev asks at this point: no, you don’t need an LLC to sell digital products — here’s when the entity actually pays for itself.

Official references

• Vercel deployment overview
• Project configuration