Why Does My React App Break When I Refresh the Page on Vercel?

So you finally deploy your React app to Vercel. It works. You click around, everything's fine. Then you go to another page, hit refresh and…

Boom. 404 Page Not Found.

You’re confused. It worked a second ago. You didn’t touch anything. What’s going on?

Let’s talk about why this happens (in plain English), and how to fix it in 2 minutes.

---

What’s Actually Going On?

Your React app is probably using something called React Router. It helps your app change pages without reloading the whole site.

So when you click a link to /about or /profile, React quietly swaps out the content on the screen, without asking the server for a new page. It’s fast and smooth.

But the moment you hit refresh on that /about page?

Vercel (the platform hosting your site) says:

“Hmm, /about? I don’t have a file or folder called that... 404 it is.”

That’s the issue.

---

The Fix (Don’t Worry, It’s Easy)

You just need to tell Vercel:

“Hey, no matter what page someone visits, always show the main React app. Let the app handle the rest.”

You do that by adding a tiny config file to your project. Here’s how:

Step-by-Step:

1. In your project folder (same place where package.json is), create a file called vercel.json

2. Inside it, paste this:

{
  "rewrites": [
    { "source": "/(.*)", "destination": "/" }
  ]
}

3. Save it. Push your changes to GitHub (or whatever you’re using).

4. Redeploy your project on Vercel.

Done. Go back to your site. Click to another page, refresh, it works. ✨

---

A Backup Option (Not the Best, But It Works)

If you don’t want to mess with that file, there’s a quick fix.

In your code, change this:

import { BrowserRouter } from "react-router-dom";

To this:

import { HashRouter } from "react-router-dom";

This will change your URLs from /about to /#/about. Refreshing will work, but it doesn’t look as clean, and search engines don’t love it.

Use this only if you're in a rush.

---

Final Thoughts

You didn’t do anything wrong. This little issue trips up a lot of developers. Even experienced ones. It’s just one of those “React meets real-world hosting” things.

Now you know how to fix it. And if someone else runs into this error, guess who’s going to look smart? You. 😎

If you found this helpful, share it with someone who’s been fighting that 404 screen. And if there’s another React problem bugging you, let me know, I might write about that next.