How to fix the Whitescreen After a Static Deployment with create-react-app

It’s one of the most annoying situations after deploying a static React app: After all that work, you finally deployed your app for production. But as you visit the site – instead of your freshly deployed app – you see … nothing.

A blank, white, screen.

The reason for this could be practically everything. For example, a critical error somewhere in your JavaScript, who knows?

To find out what’s wrong, it’s always a good idea to open your browser’s console and check it for error messages.

Loading failed for the <script> with source …

A very common thing you might see there in a “white-screen-situation”, is that your app failed to load the JavaScript bundle – and that’s what we’re going to fix today.

Now let’s have a look where the files actually live. In my case, I put them into a sub-directory react-app, so the correct URL is…

If you check the DOM of your index.html, you’ll see, that the JavaScript bundle’s links are absolute URLs – from the root of your application:

<script src="/static/js/1.3aec9dfa.chunk.js"></script>
<script src="/static/js/main.72f93e60.chunk.js"></script>

And that’s the root of our problem. Your app does not know it’s own location to build absolute URLs.

Webpack’s publicPath Setting

There is the publicPath setting in your Webpack configuration to tell an app what its root path is. In our example, that would be

If set correctly, it will base links like above from that URL – and your application will load like expected.

If you created your React app with create-react-app, you probably can’t access your webpack configuration. (Except you’ve ejected, but that’s not relevant for now)

So where do we put that information?

I’ll tell you the secret sauce: It’s called “homepage” and it lives in your package.json

Specifiying “homepage”

If you’re using create-react-app, you won’t have to deal with Webpack configs. (Which is nice 😛 ) Instead – ejected or not –  we just have to specify “homepage” in our package.json:

The way how create-react-app has it’s webpack configuration set up, this will replace the publicPath with the correct base URL for your app. (If you want to know more about the publicPath setting,  have a look at the Webpack documentation)

Now that we told your app it’s base URL, run npm run build again and copy the app to your web space to find your app up and running.

Note: If you experience routing-issues with react-router on your static deployment, this article might be helpful for you.

Wrapping up

The next time you get a white screen after deploying a React app, remember the steps you’ve learned today:

  1. Check the browser’s console for errors
  2. Does the app link to the wrong bundle?
  3. Update the “homepage” setting in your package.json
  4. Build your app again and put it on your web space
  5. Success!

Improve your React Skills!

Learn about React concepts, helpful libraries or get tips & tricks for deploying your app and many more topics.

I semi regularly post about React. Don't miss out on my future posts! Sign up below to get them delivered directly into your inbox!

Photo by Andrew Guan on Unsplash

27 thoughts on “How to fix the Whitescreen After a Static Deployment with create-react-app”

  1. Hi, Thank you so much.I couldn’t work it out as different browsers would behave differently and even the same one would be inconsistent.

  2. This solution will not work in an enterprise infrastructure where you have a multiple environments for integration, testing, and production. You would have to maintain multiple package.json files and move the correct file into place during a deployment.

    1. You’re right – I’m not 100% sure if it works for all edge cases, but in this case setting homepage to “.” should help

  3. Why this solution does not work for me. I have changed the homepage setting but still pointing the webroot path instead of homepage path.

    1. Did you rebuild your app?

      Try deleting the build folder with ‘rm -fr build’ and then running ‘npm run build’ again.

  4. Not working for me either unfortunately. Trying different paths, but I am a bit confused in regards of the “react-app” part at the end of the url you’ve shown. Is that an actual path in your app? Is it just some indicator as base? Does it need to match the name in your package.json.
    Would love some clarification on that

    1. Hi!
      The problem I described here is, that I didn’t put my React app into the root directory of my web hosting, but in a sub folder called “react-app”.
      In my case, that’s because in the root directory there’s already my blog.
      But if you put the react app into a subdirectory, the app will still search for the JavaScript packages in the root folder instead of the sub folder, where they’re actually at.

      That’s why you should change the publicPath Setting to the actual URL where your app is placed.

      Let me know if there’s still anything to clarify.

      1. Oh ok, got ya! That’s not my configuration, I must be having some other issue. Cheers for clarifying that Andreas!

  5. I’ve literally spent the last 24 hours trying to find the solution to my problem with no avail avail.
    After installing polyfills, my home screen finally showed up, but any other screen is a blank white screen.
    ** This only happens in iPhones and when opening it from the Facebook Mobile Browser.

    The only hint I have is this error “Undefined is not an object (evaluating ‘navigator.permissions.query’)”
    No answers over at Stackoverflow.

    Any ideas would be seriously appreciated.
    I’ve used create-react-app, I host on Firebase and I use a basic routet with a custom history object.

    1. Hey! Just sending this message to you – no need to approve this or my previous comment. I solved it. I was trying to check for the mic and camera permissions from iOs devices and through the Facebook browser, which I guess make the whole thing fail, as these don’t exist in those environments. Once I’ve moved that query to the component that only loads if it is not a mobile device, my error fixed.

      Appreciate the help!

  6. Hi Andreas,

    Adding homepage fixed my white screen issue. However, becomes which causes 404. Would you please advise me on this?

    1. Hi Leo!

      Looks like the problem is with your Route setup.
      Can you show me how you defined your routes?

  7. Thanks a lot for this article. You made my day Sir. But whenever I refresh, I cannot access the app page again but rather showing not found. I think the error could be from from router system.

    Normally in dev mode my route is like /http://localhost:3000/the-app-routewhich work fine.

    But now in my server side after changing adding “homepage”:”http://localhost/build”, to the package.json, ‘http://localhost/build displays my app but actually show the customized 404 page bacause it does’nt macth any route on my app. I know this kind of error is expected but I click on suggested link on the 404 page it works by chaging the url to
    “http://localhost/the-route like “http://localhost/home* but when I refresh the “http://localhost/home*, there server does not see the app again. Is the error like the basepath or basename or something?

  8. Yep that definitely solves the problem. My only question is can this be configured at build time? If I want to deploy it to different servers with different host names or subdomains is there a way I can pass this to the “npm run build” script?

  9. Hi Andreas,

    Another method is also available especially if you plan to move your app from a directory to another without having to rebuild your app.

    Instead of the URL, a simple “.” in the homepage line will do the job:

    “homepage”: “.”,

    This will make sure that all the asset paths are relative to index.html regardless the directory hosting your app and without having to rebuild it!

  10. Uncaught SyntaxError: Unexpected token ‘<‘

    well the issue is same but with a different kind of error. this is what i am getting from my console after production build. In local host everything works fine.

  11. I didn’t have this error while setting up the React page and deploying it at first, but it happened when I deployed it as an Azure virtual application. Thanks for the article, saved my day.

Leave a Reply

Your email address will not be published. Required fields are marked *