Fixing 404 Errors in Vercel Deployments

Introduction

Deploying web applications can sometimes present unexpected challenges, especially when working with modern hosting platforms like Vercel. One common issue developers face is encountering a 404 error when refreshing pages in a single-page application (SPA). This article aims to address this problem by exploring why it occurs and providing a straightforward solution to ensure seamless navigation in your Vercel-deployed applications.

Hi there! It’s been a while since I last published anything. I've been reminding myself of the importance of documenting the challenges I encounter while building websites and expanding my knowledge in the field. Finally, I’m back.

My Experience

Have you ever deployed a project to Vercel where navigating between pages works flawlessly, but refreshing the page results in a 404 error? Well, I experienced the exact same thing!

Why This Happens

The issue arises because, in a single-page application (SPA) hosted on platforms like Vercel, refreshing a page prompts the server to search for a physical file that matches the URL. Since SPAs deliver all content from a single index.html file, the absence of a corresponding file leads the server to return a 404 error.

For example:

Your SPA serves index.html for all routes.
Navigating to /about from your SPA works because the JavaScript router handles it.
Refreshing /about makes the server look for /about/index.html or /about in the file system, which doesn't exist.

The Solution

I’ll dive right in and tell you why the error occurs. You need to configure a fallback to serve the index.html file for all routes so the SPA can handle the routing. Follow these steps:

Create or Update vercel.json File: Add a rewrites configuration to ensure all requests are redirected to index.html.

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

Deploy Changes: Save the file in your project's root directory and redeploy your application to Vercel.

Why This Works

The rewrites rule ensures that any path requested on your domain is rewritten to serve index.html. Once index.html is loaded, your JavaScript router (like React Router or Vue Router) can handle the actual routing logic.

After implementing this, refreshing or directly visiting any route in your SPA will work as expected.

Conclusion

In conclusion, encountering a 404 error when refreshing pages in a Vercel-deployed single-page application can be frustrating, but it's a common issue with a straightforward solution. By configuring a fallback in the vercel.json file to serve the index.html for all routes, you ensure that your JavaScript router can manage the routing seamlessly. This approach not only resolves the error but also enhances the user experience by maintaining smooth navigation throughout your application. Remember, documenting these challenges and solutions not only aids your development process but also helps others facing similar issues. I’ll catch you in the next one!

Solution for 404 Not Found Error in Vercel Deployments

Table of contents