React Routing Explained (And Why It Breaks in Production)

 

Introduction

React routing often works perfectly during development — but suddenly breaks in production. Pages show a blank screen, return 404 errors, or fail when users refresh the browser.

If you’ve ever asked:

“Why does my React routing work locally but not after deployment?”

This article will give you a clear, practical explanation.

We’ll cover:

• How React routing actually works

• Why it breaks in production

• The most common mistakes

• How to fix routing issues correctly

---

How React Routing Works

React applications use client-side routing, most commonly with React Router.

Instead of the server handling routes like:

/about
/contact
/products

React:

• Loads one HTML file (index.html)

• Uses JavaScript to switch views

• Updates the URL without reloading the page

This is fast and smooth — but it creates problems if the server is not configured properly.

---

Why Routing Works in Development

During development:

• You usually run npm run dev or npm start

• A development server (Vite, CRA, etc.) is running

• The dev server automatically redirects all routes to index.html

So when you refresh /about, everything still works.

👉 This safety net disappears in production.

---

Why React Routing Breaks in Production

In production, your app is served by:

• Nginx

• Apache

• Cloud hosting

• Static file servers

These servers do not know about React routes.

When a user refreshes:

https://example.com/about

The server thinks:

“There is no /about file or folder”

So it returns:

• 404 error

• Blank page

• Default server page

---

The Core Problem (One Sentence)

The server does not know it should serve index.html for React routes.

---

Most Common React Routing Mistakes

1. No Fallback to index.html

This is the number one cause of broken routing.

When the server cannot find a route, it should always return:

index.html

Without this fallback, routing breaks on refresh.

---

2. Using BrowserRouter Without Server Support

BrowserRouter relies on clean URLs:

/about
/profile
/settings

This requires server configuration.

If the server is not set up correctly, routing fails.

---

3. Incorrect Base Path

If your app is deployed in a subdirectory:

https://example.com/app/

React may still assume it’s running at /.

This causes:

• Blank pages

• Assets not loading

• Routes breaking

---

4. Missing Build Configuration

Developers sometimes:

• Upload the wrong folder

• Serve source files instead of build files

• Point the server to the wrong root directory

React only works in production using the build output.

---

How to Fix React Routing in Production

✅ Fix for Nginx

Add this inside your server block:

location / {
  try_files $uri /index.html;
}

This tells Nginx:

“If the file doesn’t exist, always serve index.html.”

---

✅ Fix for Apache

Create or update .htaccess:

RewriteEngine On
RewriteBase /
RewriteRule ^index\.html$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.html [L]

---

✅ Fix for Vite (Base Path)

If your app is not at root:

export default defineConfig({
  base: "/app/"
});

---

✅ Fix for Create React App

Add to package.json:

"homepage": "/app/"

Then rebuild the app.

---

Alternative: HashRouter (When You Can’t Control the Server)

If you cannot configure the server, use HashRouter.

URLs will look like:

/#/about
/#/profile

Pros

• No server configuration needed

• Works everywhere

Cons

• Less clean URLs

• Not ideal for SEO

Use this only if server configuration is impossible.

---

How to Debug Routing Issues

When routing breaks:

1. Refresh a non-homepage route

2. Open browser DevTools

3. Check:

   • Network errors

   • 404 responses

4. Confirm server fallback

5. Verify build folder is served

Most routing issues can be found in minutes with this process.

---

Best Practices for React Routing

• Use BrowserRouter with proper server config

• Always test refreshing routes

• Test production build locally

• Keep routing simple

• Avoid deploying without fallback rules

Routing bugs often appear only after deployment — test early.

---

Why This Issue Is So Common

React makes routing feel easy — but hides the server dependency.

Many tutorials:

• Skip production setup

• Focus only on development

• Assume hosting “just works”

In reality, routing is a collaboration between React and the server.

---

Conclusion

React routing doesn’t break randomly. It breaks because the server is not prepared to handle client-side routes.

Once you understand:

• How routing works

• What the server expects

• How to configure fallback rules

You can fix routing issues permanently and deploy React apps with confidence.