---
# System prepended metadata

title: Fixing Vercel’s 404 Issue for React SPAs

---

# Fixing Vercel’s 404 Issue for React SPAs

While deploying my Gitprofile explorer Application (built with React and Vite for the ALX Front-End ReactJS program) to Vercel, I hit a snag: my custom 404 page worked locally but showed Vercel’s default "404: NOT_FOUND" page on the live site for unknown routes (e.g., /random-page). 
![vercel-routingerrorpage](https://hackmd.io/_uploads/B18gaY_uxl.png)

Here’s how I fixed it and ensured proper SPA routing.


## The Problem

My app, hosted in the github-user-search directory of my [alx-fe-reactjs](https://github.com/NueloSE/alx-fe-reactjs/tree/main/github-user-search) GitHub repo, uses React Router to display a custom NotFound component for unknown routes. 

Locally, navigating to http://localhost:5173/invalid showed my “Page Not Found” message, but on Vercel, it didn’t. This happened because Vercel serves static files directly and doesn’t automatically route unknown paths to index.html for client-side routing.

## The Fix

### **Step 1**: Verify the 404 Component

I confirmed my NotFound component was set up correctly in App.jsx using React Router:
```jsx
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import Search from './components/Search';
import NotFound from './components/NotFound';

function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Search />} />
        <Route path="*" element={<NotFound />} />
      </Routes>
    </BrowserRouter>
  );
}

export default App;
```

The NotFound component (components/NotFound.jsx):

```jsx
function NotFound() {
  return (
    <div className="flex flex-col items-center justify-center h-screen text-center">
      <h1 className="text-3xl font-bold text-gray-800">404 - Page Not Found</h1>
      <a href="/" className="mt-4 text-blue-500 hover:underline">Back to Home</a>
    </div>
  );
}

export default NotFound;
```

I tested the production build locally with `npm run build` and `npm run preview`, confirming the 404 page worked at http://localhost:4173/random-page.

### **Step 2**: Add vercel.json

To make Vercel route all requests to index.html for React Router to handle, I added a vercel.json file in the github-user-search directory:
```json
{
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/index.html"
    }
  ],
  "buildCommand": "npm run build",
  "outputDirectory": "dist"
}
```
This rewrites all routes to index.html, letting React Router render the NotFound component for unmatched paths. I committed and pushed the changes:

```bash
git add vercel.json
git commit -m "Add vercel.json for SPA routing"
git push origin main
```

### **Step 3**: Check Vercel Settings

In the Vercel dashboard, I verified:





- Framework Preset: Set to “Vite” under project settings.



- Build Settings: “Build Command” as npm run build, “Output Directory” as dist.



- Root Directory: Set to github-user-search (since my app is in a subdirectory).

### **Step 4**: Redeploy and Test

I pushed the changes to GitHub, triggering a Vercel redeployment. 

On the live site, navigating to /random-page now showed my custom 404 page. I also ensured environment variables (e.g., VITE_APP_GITHUB_API_KEY) were set in Vercel’s dashboard.

## Key Takeaways





- SPA Routing Needs Rewrites: Use vercel.json to redirect all routes to index.html for SPAs.



- Test Production Builds: Run npm run preview to catch issues locally.



- Check Vercel Config: Ensure correct framework and directory settings.

This fix was a great lesson in debugging deployment issues. If you hit similar problems, try these steps or share your experience in the comments! Connect with me on LinkedIn to discuss web dev challenges.

## Resources

- Vercel Docs: Project Configuration

- React Router Docs

- Vite Docs


<hr/>

Published on HackMD during my ALX Front-End ReactJS journey.