Introduction

Deploying a Vite app to Vercel is a common choice due to Vercel's excellent hosting capabilities and seamless integration with frontend frameworks. However, a common issue developers face after deployment is the inability to refresh pages without encountering a 404: NOT_FOUND error. This article will guide you through understanding and resolving this issue to ensure a smooth user experience.

Understanding the Problem

Vite is a modern build tool that provides a fast development experience for frontend applications, while Vercel is a popular platform for deploying these applications. When you deploy a single-page application (SPA) like a Vite app to Vercel, refreshing pages can sometimes result in a 404: NOT_FOUND error. This happens because Vercel, by default, treats each URL path as a request for a specific file on the server, which doesn't exist for dynamic routes in SPAs.

Diagnosing the Issue

To diagnose this issue, let's first understand how it manifests. You deploy your Vite app to Vercel, and everything works fine until you try to refresh a page or navigate directly to a URL other than the root. The error message you see is:

404: NOT_FOUND
Code: NOT_FOUND
ID: cpt1::7dgwq-1716569196579-fc8b22c17e3e

This error indicates that Vercel cannot find the requested page because it is treating the request as if it should correspond to a physical file on the server. Since SPAs manage routing on the client side, the server needs to redirect all navigation requests to the entry point of the application (usually index.html).

Solution Adding `vercel.json`

To fix this, we need to create a vercel.json configuration file that instructs Vercel to handle routing properly for our SPA. The file will contain a rewrite rule that directs all incoming requests to the root of our application.

Explanation of `vercel.json`

The vercel.json file is a configuration file that allows you to customize the behavior of your Vercel deployment. By adding rewrite rules, you can manage how URLs are handled, ensuring that all paths are redirected to your SPA's entry point.

Detailed Walkthrough

Step 1: Creating the `vercel.json` File

First, create a vercel.json file in the root directory of your project. This file will contain the necessary rewrite rules.

Step 2: Adding the Rewrite Rule

Open the vercel.json file and add the following content:

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

This rule tells Vercel to redirect all requests (denoted by /(.*)) to the root of the application (/).

Step 3: Deploying the Changes to Vercel

Commit your changes to your version control system (e.g., Git) and push them to your repository. Vercel will automatically detect the changes and redeploy your application.

Step 4: Testing the Solution

After the deployment is complete, navigate to your application and try refreshing various pages. You should no longer encounter the 404: NOT_FOUND error, and the app should handle routing correctly.

Conclusion

By adding a simple rewrite rule in the vercel.json file, you can resolve the 404: NOT_FOUND error that occurs when refreshing pages in a Vite app deployed to Vercel. This ensures that your SPA handles routing correctly, providing a seamless experience for users. Proper routing is crucial for SPAs, and understanding how to configure it on different platforms is an essential skill for modern web developers.

By following this guide, you've ensured that your Vite app runs smoothly on Vercel, allowing users to navigate and refresh pages without any issues. Always remember to check platform-specific documentation and best practices when deploying your applications to avoid common pitfalls like this one.