Fix a React App Showing a Blank Page After Deploy

Your React app works perfectly on your computer. You deploy it, open the URL, and get… a white page. No error, no content. This is one of the most common deploy problems, and it's almost always one of five causes.

Step 1: Open the browser console

A blank page is never actually silent — the browser knows what went wrong. Right-click the page, choose Inspect, and open:

the Console tab, for errors in red;
the Network tab (then reload), for files that failed to load — look for red rows or 404s.

(Browser developer tools for beginners explains these tabs.)

What you see points straight to the cause.

Cause 1: Files are loading from the wrong path

Symptom: Network tab shows 404s for files like /assets/index-3f9a2c.js. Console says "Failed to load module script" or shows an HTML file where JavaScript was expected.

Why: your app is served from a sub-path (like https://user.github.io/my-app/), but it was built to load files from the site root (/assets/...).

Fix: tell the build tool the base path. In a Vite app:

// vite.config.ts
export default defineConfig({
  base: "/my-app/",
});

Rebuild and redeploy. If you're serving from the root of your own domain, base should stay /.

Cause 2: Missing environment variables

Symptom: Console shows an error like "supabaseUrl is required" or "Cannot read properties of undefined" right at startup.

Why: your .env file exists on your computer but not on the host. Frontend variables (VITE_..., NEXT_PUBLIC_...) are baked in when the app is built, so the build on your host ran without them.

Fix: add the variables in your host's settings, then rebuild — not just restart. See environment variables explained and what is Vite?.

Cause 3: A JavaScript error crashes the whole app

Symptom: a red error in the Console, like TypeError: Cannot read properties of undefined.

Why: in React, an uncaught error during rendering unmounts the entire app — leaving a blank page. Production can trigger errors development didn't: different data, an empty database, an API that returns an error.

Fix: read the error and fix the cause (cannot read properties of undefined). Then add an error boundary — a component that shows a friendly "Something went wrong" instead of a white screen when part of the app crashes.

Cause 4: Routing

Symptom: the home page works, but other pages are blank or 404 — especially after refreshing.

Why: single-page apps handle routes in the browser. The server must send index.html for every path, or deep links fail. If you're using BrowserRouter with a sub-path, it also needs a basename.

Fix: see 404 on page refresh.

Cause 5: An old version is cached

Symptom: some people see the new site, some see a blank or broken one; it fixes itself after a hard refresh.

Why: a browser or CDN cached an old index.html that points to JavaScript files your new deploy deleted.

Fix: make sure index.html isn't cached for long (Cache-Control: no-cache), while hashed asset files can be cached forever. Try Ctrl+Shift+R / Cmd+Shift+R to confirm. See HTTP caching headers.

Test the production build locally first

Most of these are visible before you deploy. Build and preview locally:

npm run build
npm run preview

If the preview is blank, the problem is in the build — not the host — and it's much faster to debug on your own machine.

The summary

A blank page always leaves clues in the Console and Network tabs.
Usual causes: wrong base path, missing build-time env vars, a render crash, SPA routing, stale caches.
Rebuild after changing frontend environment variables.
Preview the production build locally before deploying.

EasySpawn gives Claude Code a server where it can build your app, serve it on your real domain with HTTPS, and check the result — so "blank after deploy" shows up while it's still working, not after you've shared the link. See how it works or join the waitlist.

React App Shows a Blank Page After Deploying? Here's How to Fix It