Comprehensive Guide to Fixing White Screen Issues After Create-React-App Build: React Router Configuration and Deployment Optimization

Problem Phenomenon and Background Analysis

When building React applications with Create-React-App and deploying them to servers, developers frequently encounter a perplexing issue: the application works perfectly in local development environments but displays a blank page after production deployment, with no error messages in the browser console. This phenomenon, commonly referred to as the "white screen problem," can stem from various factors, but the most frequent root cause is mismatched routing configuration and deployment environment.

Core Problem Diagnosis: React Router Configuration

From the provided code examples, we can see that the application uses react-router-dom for routing management. In App.js, there's a critical issue with the BrowserRouter component configuration:

import React, { Component } from 'react';
import { Route, Switch, BrowserRouter } from 'react-router-dom';
import Agenda from './components/Agenda/Agenda';
import Planning from './components/Planning/Planning';

class App extends Component {
  render() {
    return (
      <div>
        <BrowserRouter basename="/">
          <Switch>
            <Route exact path="/" component={Agenda} />
            <Route path="/planning" component={Planning} />
          </Switch>
        </BrowserRouter>
      </div>
    );
  }
}

export default App;

When the application is deployed in a subdirectory like /React, the basename="/" configuration prevents proper route resolution. According to the React Router official documentation, the basename property specifies the base URL for all locations. If the application is served from a subdirectory on the server, this must be set to the subdirectory path.

Solution: Correct Configuration of basename and homepage

For deployment at https://dev.test.com/React/, two key configurations need modification:

1. Modify BrowserRouter's basename

<BrowserRouter basename="/React">
  <Switch>
    <Route exact path="/" component={Agenda} />
    <Route path="/planning" component={Planning} />
  </Switch>
</BrowserRouter>

Note: basename should start with a forward slash but not end with one. Proper formatting ensures React Router can correctly construct complete URLs for all routes.

2. Update the homepage field in package.json

{
  "name": "my-app",
  "version": "0.1.0",
  "homepage": "https://dev.test.com/React",
  "dependencies": {
    "react": "^16.13.1",
    "react-dom": "^16.13.1",
    "react-router-dom": "^5.2.0"
  }
}

The homepage field informs the Create-React-App build tool about the URL where the application will be deployed. By default, Create-React-App assumes the app is hosted at the server root. Setting the correct homepage ensures the build process generates proper resource paths.

Deployment Verification and Debugging Techniques

After implementing the configuration changes, rebuild the application and deploy it to the server. Verification steps include:

1. Check the built index.html file to confirm resource paths correctly include the /React prefix
2. Open browser developer tools to verify all resources load successfully
3. Test that routing correctly navigates to different pages

Other Common Issues and Solutions

Beyond the primary routing configuration problem, white screen issues may also arise from other factors:

1. Incomplete Build File Upload

Ensure all files from the build folder are uploaded to the server, including:

• index.html
• The static folder and all its contents
• asset-manifest.json
• manifest.json

2. Server Caching Issues

If problems persist after configuration changes, the server might be caching old versions of files. Check 404 errors in the browser console to confirm requested resource hashes match actual files in the build folder. If they don't match, clear the server cache.

3. Browser Compatibility

Ensure target browsers support all features required by the React application. Create-React-App supports modern browsers by default, but if older browser support is needed, adjustments to the browserslist configuration may be necessary.

Best Practices Summary

To prevent white screen issues after deployment, follow these best practices:

1. Consider deployment environments early in development, especially when applications need deployment in subdirectories
2. Use environment variables to dynamically set basename for different environments (development, testing, production)
3. Perform complete build testing before deployment, including local testing of built versions using serve or similar tools
4. Establish automated deployment processes to ensure complete build file uploads with each deployment
5. Monitor production environment error logs to promptly identify and resolve potential issues

By correctly configuring React Router's basename and package.json's homepage field, combined with comprehensive deployment verification, developers can effectively resolve white screen issues after Create-React-App builds, ensuring React applications run stably in production environments.