White screen after deploying your React app? Here's the fix

Putting a React app online for the first time is an exciting moment. But things often tend to go wrong when you deploy for the first time. Sometimes, React apps could crash to a completely white screen like this one.

These white screen crashes often occur due to two main reasons. In this post, I will explain those reasons and walk you through how you can resolve them to get your app working again.

Why does this crash occur?

Usually, this crash occurs due to one of the following reasons.

• The browser failed to load the Javascript file that renders the app
• The browser encountered a Javascript error while rendering the app

Let's walk through each reason.

White screen due to a failed script load

This happens because React apps use Javascript to display what is shown in the browser. Most React apps consist of a mostly empty HTML webpage that is loaded by the browser. This webpage contains a script tag that links to the main Javascript file of a React app. Once that file is loaded, React initializes and starts rendering JSX elements. So when the browser fails to load the main Javascript file, you will see a white screen since the HTML page itself does not have any content.

To check if this is the issue that you are facing, you can open the developer tools and check for failed requests. Often, it will look something like this where the browser reports a 404 file not found error for the Javascript file. (The browser also throws a MIME type check error in this instance because it can't use the HTML error page returned by the server as a Javascript file)

How to fix it?

Often this issue occurs due to a wrong URL path set in the React app. By default, most React starter projects assume that the app will be hosted at the root of the domain, that is / or www.example.com. So the generated webpage tries to load the Javascript and CSS file relative to the root by default. But when you host your React app in a subdirectory path of a domain (e.g. www.example.com/my/react/app), this will not work. This is often the case when you use GitHub pages since it exposes the pages of a repository in a subdirectory path of a github.io subdomain (https://<user>.github.io/<repository>/).

To get your React app to work in a subdirectory path, you need to change the configuration of the project. If you are using Create React App, you need to a new field called homepage to the package.json file in your project and set the subdirectory path to it. For example, if you want to host your React app at <your-domain>/my/react/app, you need to set homepage like so.

{
    "name": "my-react-app",
    "version": "1.0.0",
+   "homepage": "/my/react/app",
    ...
}

If you are using Vite, you need to add a property called base to your Vite config, vite.config.js, with the subdirectory path.

export default defineConfig({
    plugins: [
        react(),
    ],
+   base: '/my/react/app',
});

White screen due to Javascript errors

This issue occurs when the browser encounters a Javascript error while running the Javascript file that renders the app. Since Javascript is used to display the elements on screen, when the browser encounters an error, it halts the process and leaves the page in its initial empty state.

These kinds of errors are harder to diagnose since they can be caused due to many kinds of runtime errors. The most common kind of runtime errors in Javascript are type errors and the most common type error is attempting to read a property from an undefined variable. Such an error would look like this in the developer console.

How to fix it?

Depending on the specific error that you have in the console, you need to debug your app and figure out what is causing that error to happen. Here are some ideas to help you get started.

Type errors

In the case of type errors where a property cannot be read from an undefined variable, pay attention to the name of that property and try to find instances in your codebase where a property of the same name is being read. You need to ensure that the object from which the property is being read from is always defined. If it isn't always defined, you need to check whether the object is defined before accessing a property on it.

For example, if you are attempting to read the property name from an object called person which is not always defined, you can either check whether person is defined before attempting to read name or you can use the optional chaining operator to prevent a type error from being raised.

// If this code fails with a TypeError since person can be undefined,
const errorName = person.name

// You can check whether person exists before attempting to read it
if (person) {
    const checkedName = person.name
}

// Or you can use the optional chaining operator instead which will not raise TypeErrors and will instead return undefined if person is undefined
const optionalName = person?.name

Failed API requests

The error could also be occurring due to a failed API call in the app where it fails to reach the backend or receives an unexpected response from it. Error handling code is often overlooked during development so make sure that you explicitly handle error scenarios in your app so that it doesn't crash the entire app and shows a meaningful error message to the user.

API calls to the backend can also fail due to misconfigured CORS policies so make sure that CORS is set up correctly on the backend.