Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

A Create React App build loads blank because the asset paths are wrong

ErrorCan't build create-react-app project with custom PUBLIC_URL

Short answer

A Create React App build assumes it is served from the server root. Deployed under a subpath, its script and CSS links point at the wrong place and the page stays blank. Set the homepage field in package.json, or PUBLIC_URL for a full address, rebuild, and give the router the same base.

  • Applies to react-scripts 5, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open the built index.html and look at the paths it uses for scripts and styles.

    grep -oE '(src|href)="[^"]+"' build/index.html
  2. 2Match what you see, then jump to its fix

    1. 1index.html has src="/static/js/..." but the app lives at /my-app/homepage is not set for a subpathFix
    2. 2Assets load from the wrong host or path after exporting PUBLIC_URLPUBLIC_URL is set with or without a host and not rebuiltFix
    3. 3The page loads but every route shows a 404 or nothingThe router does not know the subpathFix

What does the error look like?

  • Can't build create-react-app project with custom PUBLIC_URL
  • Blank page after npm run build when the app is served from a subfolder
  • Script and CSS files under /static/ are requested from the wrong path

Cause 1 of 3

homepage is not set for a subpath

1Check

By default the build assumes the app is hosted at the server root. The homepage field tells it the real root.

grep -n homepage package.json

2Fix

Set homepage to the final address, or to a dot to make paths relative when you do not use history-based routing. Rebuild.

// package.json
"homepage": "https://example.com/my-app",
// or relative paths:
"homepage": ".",

3Verify

The built index.html now prefixes its paths.

npm run build
grep -oE '(src|href)=\"[^\"]+\"' build/index.html

Confirmed by create-react-app.dev

Did this fix it?

Cause 2 of 3

PUBLIC_URL is set with or without a host and not rebuilt

1Check

PUBLIC_URL is used in development and production. Create React App normally ignores the hostname; PUBLIC_URL forces assets to be referenced exactly as given, hostname included.

echo $PUBLIC_URL; grep -n PUBLIC_URL .env* 2>/dev/null

2Fix

Set it to the full address you want in the output and run the build again in the same shell.

PUBLIC_URL=https://cdn.example.com/my-app npm run build

3Verify

The asset links in the built index.html begin with that address.

grep -oE '(src|href)="[^"]+"' build/index.html

Confirmed by create-react-app.dev

Did this fix it?

Cause 3 of 3

The router does not know the subpath

1Check

With client-side routing under a subpath the router needs the same base. The Create React App guide uses the basename prop of BrowserRouter.

grep -rn "BrowserRouter" src/

2Fix

Give the router the subpath.

<BrowserRouter basename="/my-app">

3Verify

Open a nested route directly.

curl -I https://example.com/my-app/

Confirmed by create-react-app.dev

Did this fix it?

How do I stop it coming back?

  • Set homepage once in package.json and treat it as part of the deployment.
  • Open the built index.html after every build when the target is a subpath.
  • Keep the router base and homepage in step.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.