🚀 How to Deploy a React App/Website on Vercel (Fix "Page Not Found" Error)

If you’re deploying your React app on Vercel and getting a frustrating "Page Not Found" error on refresh or navigating to routes like /about or /dashboard, you’re not alone.

This guide will walk you through how to correctly deploy a React app to Vercel — and fix the routing issue that plagues many single-page applications (SPAs) by adding a vercel.json file.

---

✅ Step 1: Build Your React App

First, make sure your app is ready to be deployed.

If you used Vite:

cmd
1npm run build

This creates a build/ folder with static assets.

---

✅ Step 2: Push Your Code to GitHub

1. Create a GitHub repository.
2. Push your React code to GitHub.

git
1git init
2git remote add origin https://github.com/your-username/your-repo.git
3git add .
4git commit -m "Initial commit"
5git push -u origin main
6

---

✅ Step 3: Create a Vercel Account and Import Project

1. Go to vercel.com.
2. Sign up with GitHub and import your project.
3. When asked for a framework, choose Other (not React) if it's a pure static React app (like CRA). Otherwise, if you're using Next.js or Remix, choose that.

Vercel automatically detects the build command and output folder (build).

---

❗ Common Issue: "404 Page Not Found" on Route Refresh

After deployment, when you go to:

url
1yourdomain.vercel.app/about

You might see a 404 Page Not Found.

🧠 Why?

React apps (built with Vite or similar) are Single Page Applications (SPA). They rely on client-side routing. But Vercel is a static hosting provider. So if you access /about directly, Vercel looks for a static file about/index.html, which doesn’t exist — hence the 404.

---

🛠️ Solution: Add vercel.json

You need to rewrite all routes to index.html so React can handle them.

👉 Create a file named vercel.json in the root of your project:

js
1{
2  "rewrites": [
3    { "source": "/(.*)", "destination": "/index.html" }
4  ]
5}
6

This tells Vercel:

"No matter what the route is, serve index.html and let React Router take care of the rest."

---

✅ Step 4: Re-deploy Your App

Once you add vercel.json, push your changes to GitHub:

git
1git add vercel.json
2git commit -m "Fix Vercel routing with vercel.json"
3git push
4

Vercel will automatically re-deploy the latest commit. Now test your app at:

url
1your-app.vercel.app
2

Try refreshing on /about or /dashboard — it should work!

---

🧪 Bonus: Custom Domains & HTTPS

• You can add a custom domain in the Vercel dashboard.
• Vercel gives you free HTTPS with automatic renewals.

---

📦 Full Folder Structure (Example)

md
1my-app/
2├── public/
3├── src/
4├── vercel.json ✅
5├── package.json
6└── ...
7

---

✅ Recap

---

🧠 Pro Tip

If you're using React Router v6, make sure you also use:

js
1<BrowserRouter basename="/" />
2

And make sure your routes don’t rely on server-side logic.

---

💬 Final Words

Vercel is incredibly fast and developer-friendly, but React SPAs require a small tweak (vercel.json) to work properly. Now you know how to fix it!