Vite SPA on Vercel: fix 404 when refreshing a nested route

Recognize the deep-link failure

Opening the root URL works. Navigating inside your React Router or Vue Router app works too. But pasting /dashboard into a fresh browser tab or refreshing it returns a Vercel 404. Client-side navigation never asked the server for that path; a full refresh does.

Check the deployment output first. A typical Vite SPA has a dist/index.html file but no dist/dashboard/index.html. That is expected for a client-routed SPA, not a missing build artifact.

Add the SPA fallback

For a Vite single-page app, the Vercel Vite documentation recommends rewriting unmatched navigation paths to index.html. Place vercel.json in the Vercel project's configured root directory, alongside package.json. This applies to SPA output; it is not a universal fix for server-rendered apps.

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

Do not break your API or a multipage app

A catch-all rewrite can swallow routes you intended to serve from a backend or separate HTML entry point. Confirm whether your app really is a client-only SPA. If you have /api handlers, server rendering, or multiple HTML documents, use narrower routing rules or the framework's own integration instead.

When cleanUrls is enabled, Vercel's documented Vite rewrite uses / as the destination rather than /index.html. Keep that setting in mind before copying a rule from a different project.

Verify the fix

Deploy the commit, open a nested URL in a new incognito tab, reload it, and check that the browser gets your app shell. Also request a nonexistent asset under /assets/ and verify you are not silently returning HTML where JavaScript was expected.

Reference: Vercel documentation, Vite on Vercel, Using Vite to make SPAs. DeployDoctor's repository scan can help identify other build and routing configuration risks.