Hosting details for Cloudflare Workers doesn't work for single-page app on Cloudflare Pages #5619
Send to my agentWhich project does this relate to?#
Start
Describe the bug#
SPA (single-page app) mode isn't able to the shell properly locally or on Cloudflare Pages. This is because Pages expects the shell at /index.html and doesn't appear to accept a redirect.
Your Example Website or App#
tbc
Steps to Reproduce the Bug or Issue#
As per directions in docs for SPA mode
- Configuring SPA mode
- Basic Redirects Example
- Shell Mask Path
Expected behavior#
SPA shell is transparently loaded when accessing the site root on a local or Cloudflare Pages build.
Screenshots or Videos#
No response
Platform#
- Start Version: 1.133.27
- OS: N/A, though I use Ubuntu 24.04 for dev env
- Browser: N/A
- Bundler: vite
- Bundler Version: 7.1.12
Additional context#
It's possible that using a dynamic routing for the root path is causing or aggravating the issue. For example:
if you need an index.html instead of _shell.html you can configure the outputpath to index.html, see
https://tanstack.com/start/latest/docs/framework/react/guide/spa-mode#prerendering-options
does this solve your issue?
@schiller-manuel, thanks, yes, that's what I've gone with. See above, it looks like I was copying that part over from Discord while you were replying ;-)
Still, I think there's a few more things to flesh out that can then be used to the update the docs page here: https://tanstack.com/start/latest/docs/framework/react/guide/hosting
ok so this is then a documentation topic
schiller-manuel(GitHub profile, opens in a new tab) added labelsdocumentation
Understood. There's a possible bug linked to this with local build+serve but I'll need to have a clean example to confirm.
Above is unreliable, best to explicitly set index.html
tanstackStart({ spa: { enabled: true, prerender: { outputPath: '/index.html', crawlLinks: true, retryCount: 3, }, }, }),
I verified the corrected
outputPath: 'index.html'configuration against current main. The production SPA build emitsdist/client/index.html, and the existing Chromium coverage passes against the static output.The Cloudflare Pages-specific setup still isn't documented: the SPA guide only discusses generic output paths, while the hosting guide covers Cloudflare Workers.
Keeping this open as a documentation task. The separate direct deep-route hydration issue is tracked in #6455.
jainamm-gala(GitHub profile, opens in a new tab) linked this to #8829
Sign in to join this conversation.
Currently the solution I'm using is:
Edit vite.config.ts
And in Cloudflare set your build configuration to:
Since this is my first site with Start it's possible I missed something important