SPA Deployment on Vercel: Troubleshooting 404 Errors

Recently I decided to deploy my portfolio on Vercel, the deployment was smooth and the website was live within minutes. However, there was a catch, whenever I try to refresh the the page on the portfolio other than the homepage it shows a 404 error. It was a worst nightmare as it was not just an inconvenience but a critical problem, as it hindered navigation and user experience. Here's how I diagnosed and fixed it:

The Deployment Process

Deploying my portfolio on Vercel was straightforward:

1. I initialised my project with npm create vite@latest.

2. The application was developed with React Router for client-side routing.

3. After thorough testing locally, I pushed the code to GitHub.

4. I connected my GitHub repository to Vercel, and within minutes, my site was live at https://www.sumitmazumdar.in

Everything seemed perfect until I tried refreshing a page other than the homepage.

So, why did this occur and how to fix it ?

The issue arises because SPAs handle routing on the client side. When a URL is entered directly or a page is refreshed, the request is sent to the server, which tries to handle it as a traditional request for a specific resource. Since the server doesn’t have routes matching the client-side ones, it returns a 404 error.

The solution involves configuring the server to always serve the index.html file for all routes, allowing the client-side application to handle routing. Here’s how I resolved it:

1. Adding a vercel.json File:

I created a vercel.json file at the root of my project with the following configuration:

{
  "routes": [
    {
      "src": "/(.*)",
      "dest": "/index.html"
    }
  ]
}

This configuration tells Vercel to serve index.html for any route.

2. After adding the vercel.json file, I pushed the changes to GitHub, and Vercel automatically redeployed the site .

3. Once the deployment was complete, I tested refreshing various pages and directly accessing URLs. The 404 errors were gone, and the application handled routing correctly.

Through this incident, I learned about the importance of configuring deployment environments for SPAs. Here are some resources that helped me understand and fix the issue: