React build shows a blank page

npm start works. npm run build finishes with "Compiled successfully". Then the built app is a white screen and <div id="root"> is empty.

Open the console (F12 → Console) before changing anything. A blank React build almost always leaves one message, and the message tells you which of the causes below it is. This page covers Create React App (react-scripts) and hand-rolled webpack setups; for Vite, see Vite build shows a blank page.

Match the console message to the cause

What the console or Network tab shows Cause Section
Failed to load resource: net::ERR_FILE_NOT_FOUND for /static/js/… Opened from disk; absolute paths Opened build/index.html
No error, empty root, opened from disk or GitHub Pages React Router matched no route The router renders nothing
404 for https://user.github.io/static/js/main.….js homepage doesn't match the sub-path GitHub Pages and sub-paths
Uncaught SyntaxError: Unexpected token '<' The .js request got index.html back Unexpected token '<'
Home page fine, any other URL 404 on refresh Server has no SPA fallback Refresh 404
Cannot read properties of undefined near process.env.… Variable missing at build time Environment variables
process is not defined / Buffer is not defined webpack 5 dropped Node polyfills Environment variables
ChunkLoadError: Loading chunk 3 failed Lazy chunk path wrong, or deleted by a new deploy Unexpected token '<'

Create React App also tells you at build time. Read the last lines of npm run build:

The project was built assuming it is hosted at /.
You can control this with the homepage field in your package.json.

If / is not where the build will live, that line is your bug.

Check it away from your machine

See your page the way someone else will

Drop the HTML or paste it. It opens on a shareable page, so you can confirm the fix works for a reader, not just on your laptop.

Your file is read in this tab and nothing is uploaded until you publish. Creating an account is free, and reading a shared link never needs one.

You opened build/index.html from disk

By default CRA writes absolute paths:

<script defer="defer" src="/static/js/main.3f2a1b9c.js"></script>

On a web server /static/… means "from the site root". On a file:/// page it means the root of your disk, so every file is ERR_FILE_NOT_FOUND. Make the paths relative and rebuild:

// package.json
{ "homepage": "." }

Unlike Vite, CRA emits classic <script defer> tags, not module scripts, so there is no CORS error from origin 'null' once the paths are relative. That fixes apps without a router. Apps with one usually stay blank — next section.

For a plain webpack config the equivalent setting is output.publicPath. webpack 5 defaults to 'auto' (relative to the script), but most configs copied from a tutorial set publicPath: '/' so the dev server's deep links work — and that is the line that breaks file://.

The router renders nothing

The bundle loads, there's no error, and the root is still empty. React Router is matching routes against window.location.pathname, and nothing matches:

Where the build is open pathname the router sees
From disk /Users/you/app/build/index.html
GitHub Pages project site /repo/
Behind a proxy at /app/ /app/

None of those is /, so <Route path="/"> never renders. Two fixes:

// Sub-path host: tell the router where it lives
<BrowserRouter basename={process.env.PUBLIC_URL}>

process.env.PUBLIC_URL is derived from homepage, so the two can't drift.

// Opened from disk, or a path you don't control: hash routing
import { HashRouter } from "react-router-dom";
<HashRouter>

With hash routing URLs look like index.html#/settings. The browser never treats the part after # as a path, so the router works from disk, on any sub-path and on hosts with no fallback. A catch-all <Route path="*"> that renders a "not found" message is worth adding either way: a wrong path becomes a visible page instead of a white one.

GitHub Pages and other sub-paths

A project site lives at https://user.github.io/repo/, but the default build asks for https://user.github.io/static/js/… and gets a 404.

// package.json
{
  "homepage": "https://user.github.io/repo",
  "scripts": { "predeploy": "npm run build", "deploy": "gh-pages -d build" }
}

Then add basename={process.env.PUBLIC_URL} from the section above. Two more things that trip people on Pages specifically:

  • Publish build/, not the repo root. The source public/index.html has no script tags — CRA injects them at build time — so deploying it gives a blank page with no error at all.
  • Custom domain. With www.example.com pointed at the site, the app lives at / again. Change homepage to the domain or ".", or every asset 404s.

The same rules apply to GitLab Pages (also publish to public/ — see GitLab Pages report 404s), an S3 prefix, or any reverse proxy that mounts the app below /.

"Uncaught SyntaxError: Unexpected token '<'"

Uncaught SyntaxError: Unexpected token '<' (at main.3f2a1b9c.js:1:1)

The browser asked for a .js file and got HTML, whose first character is <. A host configured for single-page apps answers any missing path with index.html and a 200, so a wrong path never shows up as a 404. The usual reasons:

  • Relative paths plus a nested route. With "homepage": ".", a refresh on /users/42 asks for /users/static/js/main.js. Use an absolute homepage with BrowserRouter, or hash routing.
  • Wrong homepage or publicPath — the GitHub Pages case above, with a fallback hiding the 404.
  • A stale index.html. A CDN or the CRA service worker (serviceWorker.register() in older templates) cached the old entry page, which references hashed files the new deploy deleted. Hard-reload (Ctrl+Shift+R) to confirm, then serve index.html with Cache-Control: no-cache and unregister the worker. The same mismatch, hit by a lazy import(), is ChunkLoadError.

Refresh or a deep link 404s

The home page loads, links work, but refreshing /settings returns 404. The route only exists in JavaScript; the server looks for a file called settings and has none.

Host Fallback to index.html
GitHub Pages Copy build/index.html to build/404.html after the build
Netlify public/_redirects: /* /index.html 200
Vercel vercel.json: {"rewrites":[{"source":"/(.*)","destination":"/"}]}
Cloudflare Pages Automatic when there is no 404.html at the root
nginx try_files $uri $uri/ /index.html;
serve npx serve -s build — the -s is the fallback
webpack dev server devServer: { historyApiFallback: true }

Where you can't configure the server, use HashRouter.

An environment variable is undefined

Create React App replaces process.env.* when npm run build runs, and only for names that start with REACT_APP_ (plus NODE_ENV and PUBLIC_URL):

process.env.REACT_APP_API_URL; // baked into the bundle
process.env.API_URL; // undefined, always

The classic blank page: .env.local exists on your laptop, the CI build doesn't have it, the value is undefined, and the first component that calls a method on it throws. There is no runtime to set it in afterwards — set it in the build environment, and rebuild.

Plain webpack 5 has no process in the browser at all. Code — yours or a dependency's — that reads process.env.X or uses Buffer throws process is not defined on the first render:

// webpack.config.js
const webpack = require("webpack");
module.exports = {
  plugins: [
    new webpack.DefinePlugin({ "process.env.API_URL": JSON.stringify(process.env.API_URL) }),
    new webpack.ProvidePlugin({ Buffer: ["buffer", "Buffer"], process: "process/browser" }),
  ],
};

Upgrading react-scripts from 4 to 5 is the same webpack 5 change, which is why an app can go blank with no code change of your own.

Two more that only show up in the build

  • A crash during the first render. Without an error boundary, any exception in a top-level component unmounts the whole tree — white screen. Minified, the stack trace is useless; CRA writes source maps by default, so serve the build with npx serve -s build and the console points at your real file and line.
  • Case-sensitive imports. import Header from "./header" finds Header.js on macOS and Windows, then fails on the Linux CI runner.

Create React App itself was deprecated in February 2025. None of the fixes above need a migration, but if you are touching the build config anyway, Vite's equivalents are in the Vite version of this page.

Stop sending the build folder

Every file-based fix above has a ceiling: the person you send the build to still needs the right folder, the right path and, often, a local server. A build preview works best as a URL.

Comma takes the build/ folder or a zip of it and returns one link. Assets upload alongside the entry page with their references rewritten, so the absolute-path and file:// problems disappear, and reviewers comment on the exact element they mean instead of sending a screenshot. The same flow works for any static build — see share a Vite build for the API call to run from CI.

Two honest caveats. Reports run in a sandboxed iframe with scripts enabled but no same-origin access, so code that touches localStorage or cookies without a try/catch throws there — guard it. And build the preview with HashRouter so every view has a working link.

Publish a build preview →

Related

Have an HTML report to share? Publish it free and send one link people can comment on.