Your home page opens and clicking through the app works, but refreshing a page such as /profile returns a Vercel 404. For a Vite app deployed as a static single-page application, check how the host serves that page URL. Vercel documents that deep linking needs a rewrite for this deployment type. Vercel Vite guide
Start by confirming the build type and output directory. Then route the app's page URLs to its HTML entry point. A fallback cannot repair a failed build, a missing JavaScript file or a server deployment configured as static hosting.
Confirm this is a static SPA
Read package.json, the build script and the Vite configuration in your own project. Continue only when the output you intend to deploy is a static client app with an HTML entry point and browser assets.
Do not apply this recipe to Next.js or TanStack Start server deployments. A dependency on Vite alone is not enough to choose static hosting: Vite's deployment guide explicitly separates static builds from server-side rendering. If the build produces server code, use that framework's deployment instructions instead. Vite static deployment
For the static setup described by Vite, the build script runs vite build. If that is your project's script, run:
npm run buildUse the equivalent script for your project's package manager. Inspect the generated files after a successful build. Vite defaults to dist, but build.outDir can change that. Verify that the actual output contains index.html and the assets it references. Vite static deployment
If publishing fails before any page is served, start with the Lovable deployment guide for a Lovable project. If a Bolt preview works but the built app lacks its configuration, use the Bolt deployment guide. This guide addresses requests for pages after a static build exists.
Check your route for free
Use your browser's Network panel on a site you own. This is our diagnosis checklist, based on the static-serving test below:
- Open the deployed home page. Navigate within the app to a known page, such as
/profile. - Clear the Network list and refresh that page. Inspect the document request, its status and its response body.
- Open that same page URL directly in a new tab. Check the document request again.
- Inspect the JavaScript and CSS requests too. Confirm they return the intended assets rather than the app's HTML.
| Observation | Next check |
|---|---|
| Home page works; the direct page document returns a host 404 | Check the output directory and page rewrite below. |
| The document returns the app's HTML, but the app shows its own not-found screen | Check whether the client router defines that URL. Serving the HTML is only the first checkpoint. |
| The HTML loads, but a script or stylesheet is missing | Compare its requested URL with the built files. Do not add that asset path to the HTML fallback. |
| A read-only API request returns the SPA's HTML | Check for a rewrite that also matches API paths. The page fallback must not replace the API response. |
| The browser cannot establish a secure connection on your custom domain | Take the domain/TLS branch below before changing page routing. |
You can also preview the built files locally using your project's vite preview script. That checks the local build, not Vercel's routing configuration; Vite says preview is not a production server. Vite static deployment
Match the output directory to the rewrite destination
Vercel serves the contents of the configured Output Directory. Check that this is the directory your build actually creates. A per-deployment outputDirectory in vercel.json overrides the dashboard setting. Vercel build configuration, project configuration
Keep these paths separate:
| Setting or file | Example |
|---|---|
| Build output directory | dist |
| HTML file on disk after building | dist/index.html |
Rewrite destination inside the deployed site, with default cleanUrls | /index.html |
If your build output is dist/public, check for dist/public/index.html locally and configure that output directory. The deployed destination is still /index.html, not /dist/public/index.html, when that directory's contents form the site root. This follows Vercel's output-directory rule and its site-root rewrite examples. Build configuration, rewrite examples
Check cleanUrls before copying a destination. Its default is false. When it is true, Vercel's Vite guide says to use / instead of /index.html for this SPA fallback. Do not change URL behavior merely to fit a copied snippet. Vercel Vite guide, cleanUrls
Add a rewrite for the app's page routes
A rewrite serves another destination while keeping the requested URL in the browser. Vercel places these rules in the project's root vercel.json. Vercel rewrites
The following is a scoped example for a static app whose client pages include /profile and /novels/:id. It assumes the HTML entry point is /index.html and cleanUrls is false or absent:
{
"$schema": "https://openapi.vercel.sh/vercel.json",
"rewrites": [
{ "source": "/profile", "destination": "/index.html" },
{ "source": "/novels/:id", "destination": "/index.html" }
]
}Replace these example page patterns with routes your client router actually owns. Merge the rules into your existing configuration after checking its other routing rules; do not replace the whole file. If you use cleanUrls: true, change both destinations to /. Parameterized source paths and same-application destinations follow Vercel's rewrite syntax.
Vercel also documents a catch-all SPA example. Before adopting one, inventory your API, static-asset and other non-page paths. The scoped example above does not match /api/... or /assets/.... Keep those namespaces outside the page fallback. Vercel documents filesystem precedence over rewrites, but a missing resource is still a negative case you should test. Vercel configuration reference
This is a routing change, not access control. Do not treat an HTML response at a private page URL as proof that authentication or data permissions work.
What changed in our local test
We served a synthetic HTML shell and a JavaScript asset from a local static server. We then enabled a fallback only for /profile and /novels/<one path segment>, without changing the files.
| Request | Files only | Scoped fallback |
|---|---|---|
/ | 200, HTML shell | 200, HTML shell |
/profile | 404 | 200, HTML shell |
/novels/1 | 404 | 200, HTML shell |
/assets/app.js | 200, JavaScript | 200, JavaScript |
/assets/missing.js | 404 | 404 |
/api/missing | 404 | 404 |
/not-a-page | 404 | 404 |
This demonstrates the static-serving distinction: an explicit page fallback can return the entry HTML while leaving unrelated missing resources as errors.
It was a synthetic HTTP test, not a Vite or React build, a browser-rendering test or a Vercel deployment. We did not test Vercel's routing engine, cleanUrls, a real API or authentication.
Verify the deployed change
When you deploy your configuration change, repeat the Network checklist on that exact deployment URL. Check the home page, a direct page URL and a refresh. Confirm the expected page renders, not just that its document returns 200.
Check an existing asset and a deliberately nonexistent asset under your own asset namespace. Confirm the missing asset does not return the SPA shell. If your project has an API, use a known read-only endpoint and inspect its expected status, content type and body. Check an unknown API path too; its error must not become the SPA's HTML.
If a page still returns a host 404, compare the deployed revision, project root, build output, rewrite source and destination. If the HTML arrives but the screen is wrong, inspect the client route and failed assets before widening the rewrite. These are verification checkpoints derived from the local test, not a claim that a fallback fixes every 404.
If your custom domain cannot connect
For a custom domain you own, the free custom-domain SSL checker checks DNS and the certificates presented by the domain and its www counterpart. It does not check page rewrites, JavaScript, APIs or authentication. Behind Cloudflare's proxy, it can only see Cloudflare's certificate. Use it for a domain or TLS failure, not to validate this routing fix. Checker scope
Still stuck on hosting?
Bring the failing URL, build command and Network observations, with secrets removed, to the Production Readiness Audit.
How we checked this
We checked Vercel's Vite, rewrite, project-configuration and build documentation, plus Vite's static-deployment guide, on 1 November 2026. The Vercel configuration advice is vendor-documented. We reproduced the file-only versus scoped-fallback response difference locally on the same date using synthetic static files.
No Vercel deployment or client incident was tested. The local test does not validate React rendering, authentication, real API behavior or Vercel's cleanUrls handling.
Sources
All sources read on 1 November 2026.
- Vite on Vercel, Vercel. Updated 26 August 2026.
- Rewrites on Vercel, Vercel. Updated 11 August 2026.
- vercel.json configuration, Vercel. Updated 14 August 2026.
- Configuring a build, Vercel. Publication date not established.
- Deploying a static site, Vite. Publication date not established.
- Custom-domain SSL checker, Enviera. Publication date not established.
- Prototype to production, Enviera. Publication date not established.