Works locally but fails when deployed — how to fix (Vercel & Netlify)

The symptom

It runs perfectly with npm run dev on your machine, but the moment you push it to Vercel or Netlify you get a blank white screen, a "Module not found" build error, or data that never loads. This is the single most common problem when you first deploy a vibe-coded app — and the cause is almost always one of five things.

The root reason is simple: your PC and the deploy server are two different "environments." Settings, files, and URLs that only existed on your computer aren't there on the server. Work through the five checks below in order and you'll fix most cases.

1. You never added the env vars on the deploy platform — most common

The .env file on your PC lives only on your PC. It's usually not committed to git, so Vercel and Netlify have no idea it exists. That means values like API keys and database URLs are empty in production, and the app crashes.

Fix — Vercel:

1. Vercel dashboard → open your project
2. Top nav Settings → left sidebar Environment Variables
3. Enter Key (e.g. VITE_SUPABASE_URL) and Value → check Production, Preview, and Development → Save
4. Go to the Deployments tab → ⋯ next to the latest deployment → Redeploy

> Important: Vercel applies env var changes to *new* deployments only, never to existing ones. After adding a value you must redeploy for it to take effect.

Fix — Netlify:

1. Netlify dashboard → open your site
2. Site configuration → Environment variables → Add a variable
3. Enter Key/Value → Save
4. Deploys tab → Trigger deploy → Clear cache and deploy site

Watch out: browser-facing values need a specific prefix

Env vars read by your frontend (browser) code only reach the page if they carry the right prefix. Without it, the value comes back undefined.

Anything with these prefixes is exposed in the browser bundle, so never put a real secret (like a database password) behind one.

2. You changed an env var but didn't redeploy

Env var values get baked into the code at build time and freeze there. Next.js, Vite, and Create React App all inline the values during the build. So even after you edit a value in the dashboard, the old value stays until you rebuild.

Fix: After changing a value, hit Redeploy (Vercel) / Trigger deploy (Netlify) once more to force a fresh build.

3. A filename's letter case doesn't match — "Module not found"

macOS and Windows treat Button.tsx and button.tsx as the same file (case-insensitive). But Vercel and Netlify build on Linux, which is strictly case-sensitive. So if the real file is Button.tsx but your import uses lowercase, it passes locally and fails on deploy with "Module not found."

Fix: Make the import path match the real filename exactly, letter for letter — folder names too.

// Real file: src/components/Header.tsx

import Header from './components/Header'  // OK
import Header from './components/header'  // FAILS on deploy: Module not found

4. You hardcoded a localhost API URL

If you write a URL like http://localhost:3000 straight into your code, it works locally because that's your own server. But on the deployed site that address points at "the visitor's own computer," so nothing comes back.

Fix: Move the URL into an env var and register the real deployed address using method 1.

// Wrong — a local address baked into the code
fetch('http://localhost:3000/api/users')

// Fixed — pull the address from an env var (Vite example)
fetch(`${import.meta.env.VITE_API_URL}/api/users`)

5. Local runs dev, deploy runs build — errors that only show in the build

npm run dev is a development server and forgives many problems. Deploying runs npm run build (a production build), which is far stricter about type errors and import errors.

Fix: Before you push, run the exact same build locally to catch problems in advance.

npm run build

Whatever error prints here is the reason your deploy fails. Clear those errors locally, then push.

Final checklist

• Did you add every .env value into Vercel/Netlify too?
• Do browser-facing vars carry the NEXT_PUBLIC_ / VITE_ / REACT_APP_ prefix?
• Did you redeploy after adding or changing a value?
• Do import paths match the real filenames, case included?
• Is there no hardcoded localhost URL in the code?
• Does npm run build finish with no errors on your machine?

Get all six right and the "works locally, breaks on deploy" problem is almost always gone.