blog

White Screen After Deploying to Vercel: How to Fix It

Your Vite or React app works locally but shows a blank white page on Vercel. Here are the real causes, how to spot each one and how to fix it.

6 min readVercelFixesBlank screen

You push your app to Vercel. The build log is green, the deployment says Ready — and the live site is a plain white page. Locally, npm run dev and even npm run build && npm run preview look fine.

A white screen means the browser got something from Vercel, but your app never drew anything. The reasons are few, and each one leaves a clear trace in the browser. This guide shows where to look and how to fix each cause, with real cases from Vercel's community forum.

First, look at the console and the Network tab

Everything below starts here, so do this first:

  1. Open your live site (the Vercel address or your domain) in Chrome or Edge.
  2. Right-click the page and choose Inspect, or press F12 (Cmd + Option + I on a Mac).
  3. Open the Network tab and reload the page.
  4. Look for rows in red, especially files ending in .js or .css. Note their status: 404 (not found) or 500 (server error).
  5. Open the Console tab. Red messages are errors. Copy the first one.

Then match what you see:

  • .js or .css files return 404 → the base path is wrong (next section).
  • Files load, the console is quiet, nothing renders → the router's basename, or no entry script.
  • A red error about a missing value, such as supabaseUrl is required → environment variables.
  • Files return 500 → something on the server answers for your static files (middleware).

JS and CSS files return 404: check base in vite.config

In one Vercel community thread, a Vite app showed a white screen on Vercel while the same build worked on GitLab Pages. The Network tab showed the CSS and JavaScript returning 404 from addresses like /commercial-cleaning/assets/index-….css — with the project's name in the path.

The cause was the base option in vite.config.ts. Vite's config reference describes base as the "base public path when served in development or production", with the default /. A value like '/my-repo/' is what you set for a site served from a subfolder, which is common on GitHub Pages and GitLab Pages. On Vercel your site is served from the root of its domain, so the files are looked for in the wrong place.

Fix:

  1. Open vite.config.ts (or vite.config.js) in the root of your project.
  2. Find the base line. Change it to '/', or delete the line so Vite uses its default:
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  base: "/",
});
  1. Commit and push. Vercel redeploys.
  2. Reload the live site with the Network tab open: the .js and .css files should now return 200.

The page loads but nothing renders: router basename

In the same thread, fixing base made the files load — but the page was still white. The last piece was the router: a Vercel team member suggested setting the router's basename to the app's root route, and that fixed it. A router basename says which path your app lives under; if it doesn't match the address the site is actually served from, the router finds no matching page and draws nothing.

Fix: search your code for basename (usually in main.tsx, App.tsx or a routes file), for example:

<BrowserRouter basename="/my-repo">

If your site lives at the root of its domain, remove basename or set it to /:

<BrowserRouter>

The rule: base in vite.config and the router's basename must both match the path your site is served from. On Vercel, that's /.

If the home page works but other pages give a 404 only after you refresh them, that's a different issue — see Vercel 404 NOT_FOUND on page refresh.

index.html is missing the entry script

In another community thread, the build log looked perfect, but it said only 2 modules transformed and produced just dist/index.html — no JavaScript at all. The cause: index.html was missing the script tag that loads the React app. Adding it solved the problem.

Vite's guide explains why this matters: in a Vite project, index.html is the entry point of your application, and Vite resolves the <script type="module" src="..."> that references your JavaScript source. No script tag means nothing to build and nothing to run.

Fix: open index.html in the root of your project and make sure it has a root element and the module script, pointing to your real entry file (often /src/main.tsx or /src/main.jsx):

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My app</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

Then check your next build log: it should list your JavaScript files in dist/assets, not only index.html.

Missing environment variables

If the console shows supabaseUrl is required or an error about an undefined value right at startup, your app was built without its settings. Locally they come from .env, which usually isn't uploaded. In Vercel, add them under Settings → Environment Variables, with the exact names your code uses and the VITE_ prefix for Vite apps, then redeploy — Vite puts the values into the app when it builds.

The full walkthrough is in Error: supabaseUrl is required — how to fix it after deploy.

Wrong Output Directory or framework preset in Vercel

Vercel only serves what's in your project's Output Directory. Vercel's build configuration docs say that when Vercel detects your framework, the output directory is configured automatically. Vite writes its build to dist by default (Vite's build.outDir option).

Problems start when the preset is wrong. Vercel's docs note that the "Other" preset uses public if it exists, or the project root — not dist.

Fix:

  1. In the Vercel dashboard, open your project → Settings in the sidebar → Build and Deployment.
  2. Set Framework Preset to Vite.
  3. Check that Output Directory is dist (or that the override is off, so the preset's default is used).
  4. Redeploy.

Next.js or v0 app: middleware catches your static files

Apps built with v0 are usually Next.js apps, and they can go white for a different reason. In this thread, a v0 app worked in preview, the build log was clean, but the live site was blank and the Network tab was full of 500 errors.

The build log couldn't help, because the errors happened at request time. A Vercel team member pointed to the request logs: the app's static files were being handled by the server instead of being served as files, most likely by middleware that matched too much. Fixing the middleware solved it.

Where to see these errors: in the Vercel dashboard, open the project and choose Logs in the sidebar. Vercel's Runtime Logs docs describe this section as the place to view, search and inspect your runtime logs — separate from the build log. Filter by the failing path or by status 500 to see the real error.

Fix: limit the middleware with a matcher. Next.js's docs say that without a matcher it runs on every request, including static files (_next/static), image optimization (_next/image) and files in public/, and that auth logic or redirects can then block CSS, JS or images from loading. Their example of excluding these paths:

export const config = {
  matcher: [
    // Exclude API routes, static files, image optimizations, and .png files
    "/((?!api|_next/static|_next/image|.*\\.png$).*)",
  ],
};

Note the file name: in Next.js 16 the middleware file convention was renamed to proxy (proxy.ts); older versions use middleware.ts. The matcher works the same way in both. Adjust the pattern to your app — for example, add other file types from public/ that your app uses.

Still blank? Check if it's Vercel

If none of the above matches and the white screen appeared suddenly without a deploy, check whether Vercel itself has a problem: our live Vercel status page shows Vercel's official status and our own check. Our guide Vercel site down? How to tell if it's you or Vercel walks through the rest, including rolling back to the last working deployment.

If your app was built with Lovable or Bolt, these guides cover causes specific to them: Lovable app showing a blank white screen and Why is my Bolt.new app not working after deploy.

FAQ

Why does my app work locally but show a white screen on Vercel?
Usually because something differs between your computer and the deployed build: the base path in vite.config, the router's basename, a missing entry script in index.html, missing environment variables, or the wrong Output Directory. The browser console and the Network tab tell you which one it is.
The build log on Vercel shows no errors. Where do I look?
A successful build only means the files were produced. Open the live site with the browser's developer tools to see what fails in the browser. If files answer with 500, open your project's Logs in the Vercel dashboard: those are runtime logs, separate from the build log.
What should base be in vite.config for Vercel?
For a site served from the root of its domain, '/'. That's also Vite's default, so you can usually just remove the base line. Values like '/repo-name/' are meant for sites served from a subfolder, such as GitHub Pages.
My v0 or Next.js app is blank and its files return 500. Why?
Often middleware (proxy in Next.js 16) runs on every request, including the app's own JavaScript and CSS, and breaks them. Add a matcher that leaves out _next/static, _next/image and public files.

Fixed it? Run a free Pingbuddy checkup on your live site. It shows whether your site answers and how fast, when your SSL certificate and domain expire, whether your Supabase project is paused and whether secret keys are visible in your public code.

Run free checkup →