My React App Builds Locally, But Blank Page on Hosting Platforms โ€“ what's the deal?

Author
Amira Mahmoud Author
|
1 week ago Asked
|
19 Views
|
2 Replies
0

quick update after trying out some deployment strategies from the last thread. got npm run build working like a charm locally!

but here's the kicker: the app builds perfectly and runs fine with serve -s build on my machine, yet when i push it to various hosting platforms (tried a couple now for SPA hosting), it's just a blank white page. no errors in the browser console usually, just... nothing, which is super helpful.

          > [email protected] build
          > react-scripts build

          Creating an optimized production build...
          Compiled successfully.

          File sizes after gzip:

            41.28 KB  build/static/js/main.f8e7c1d3.js
            2.39 KB   build/static/css/main.a4b3c2d1.css
            1.72 KB   build/static/js/787.e6f5d4c3.chunk.js

          The project was built assuming it is hosted at the server root.
          You can control this with the homepage field in your package.json.
          For example, add "homepage": "http://mywebsite.com" to build it for http://mywebsite.com/
        

...then just a blank page when viewing the deployed site.

why would it work perfectly locally with serve -s build but totally die online? what common config or build step am i overlooking for different hosting platforms and SPA hosting setups?

help a brother out please...

2 Answers

0
Neha Sharma
Answered 1 week ago
Hey Amira Mahmoud, Ah, the classic "works on my machine but not in production" scenario โ€“ a rite of passage for many developers, and frankly, super annoying when it's just a blank page! That console output about the `homepage` field is a big hint. Your React app, being a Single Page Application (SPA), has a few common gotchas when moving from local development to various hosting platforms. Here's what's typically going on and how to fix it:
  • The `homepage` Field in `package.json`: Your build output explicitly mentions this. By default, Create React App assumes your app is hosted at the root of a domain (e.g., `https://yourdomain.com/`). If you're deploying to a sub-path (like `https://yourdomain.com/my-react-app/` or GitHub Pages, which often uses `username.github.io/repo-name/`), the paths to your static assets (JS, CSS, images) will be incorrect.

    To fix this, add a homepage field to your package.json file.
    • If deploying to the root of a custom domain: You usually don't need to set homepage, or you can set it to "." (though often unnecessary).
    • If deploying to a sub-path (e.g., GitHub Pages, or a specific folder on your server): Set it to the full URL or relative path where your app will reside. For example: "homepage": "https://yourdomain.com/my-app" or "homepage": "/my-app".
    After changing this, run npm run build again and redeploy.
  • Client-Side Routing and Server Fallback: This is crucial for SPAs. Your React app uses client-side routing (e.g., React Router) to navigate between different "pages" without full page reloads. However, when a user directly accesses a route like `yourdomain.com/about` or refreshes that page, the server needs to know what to do. Since there's no physical `about.html` file, the server will typically return a 404. For static site hosting, you need to configure your server to always serve your `index.html` file for any route that doesn't correspond to a static asset.

    Most modern SPA hosting platforms handle this easily:
    • Netlify/Vercel: Often automatically configured, but you might need a _redirects file (for Netlify) or vercel.json/netlify.toml with a rewrite rule like: /* /index.html 200.
    • Firebase Hosting: Add a rewrite rule in your firebase.json:
      "rewrites": [
        {
          "source": "**",
          "destination": "/index.html"
        }
      ]
    • Apache: Use an .htaccess file with RewriteRule.
    • Nginx: Configure try_files.
    This ensures that regardless of the URL, your `index.html` (and thus your React app) loads, allowing your client-side router to take over and render the correct component.
  • Browser Console, Revisited: Even if you usually see nothing, check the "Network" tab for failed resource loads (404s for JS/CSS files) and the "Console" tab for any JavaScript errors that might appear *after* the initial blank page. Sometimes the errors are subtle or delayed.
Start with the `homepage` field, as that's the most common culprit indicated by your build log. Then, confirm your hosting platform's configuration for client-side routing fallbacks. Did checking the network tab in the browser console reveal any 404s for your JS or CSS bundles?
0
Amira Mahmoud
Answered 1 week ago

Okay, the homepage field in package.json was totally it! Knew it had to be something simple like that after the build log mentioned it. After adding "homepage": ".", everything loaded perfectly on Netlify. Big relief tbh.

Your Answer

You must Log In to post an answer and earn reputation.