# React Build Shows a Blank Page — Create React App, webpack and React Router

Canonical: https://commareports.com/fix/react-build-blank-page
Published: 2026-11-17

> `npm start` works, but `npm run build` gives a white screen. The console message behind each cause — the homepage field, `Unexpected token '<'`, React Router on file:// and GitHub Pages, webpack publicPath, undefined REACT_APP_ vars — and the fix for each.

# 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](/fix/vite-build-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.

## You opened build/index.html from disk

By default CRA writes absolute paths:

```html
<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:

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

Unlike Vite, CRA emits classic `<script defer>` tags, not module scripts, so
there is no [CORS error from origin 'null'](/fix/cors-error-file-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:

```jsx
// 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.

```jsx
// 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.

```json
// 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](/fix/gitlab-pages-report-404)), 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`):

```js
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:

```js
// 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](/fix/vite-build-blank-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](/share-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 →](https://commareports.com/)**

### Related

- [Vite build shows a blank page](/fix/vite-build-blank-page)
- [CORS error from origin 'null'](/fix/cors-error-file-origin-null)
- [ERR_FILE_NOT_FOUND in Chrome](/fix/err-file-not-found)
- [GitLab Pages report 404s](/fix/gitlab-pages-report-404)
- [The localhost link doesn't work for others](/fix/localhost-link-doesnt-work-for-others)
- [Share a Next.js static export](/share-nextjs-static-export) · [Share an Angular build](/share-angular-build)
- [Free HTML inliner](/tools/html-inliner)
