Hosting details for Cloudflare Workers doesn't work for single-page app on Cloudflare Pages

[westhouseit]

Which 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

1. Configuring SPA mode
2. Basic Redirects Example
3. 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:
/routes/$id.tsx

[westhouseit]

Currently the solution I'm using is:

Edit vite.config.ts

    tanstackStart({
      spa: {
        enabled: true,
        prerender: {
          outputPath: '/',
          crawlLinks: true,
          retryCount: 3,
        },
      },
    }),

And in Cloudflare set your build configuration to:

Build command: npm run build
Build output: dist/client
Root directory:
Build comments: Enabled

Since this is my first site with Start it's possible I missed something important

[schiller-manuel]

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?

[westhouseit]

@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 ;-)

[westhouseit]

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

[schiller-manuel]

ok so this is then a documentation topic

[westhouseit]

Understood. There's a possible bug linked to this with local build+serve but I'll need to have a clean example to confirm.

[westhouseit]

Above is unreliable, best to explicitly set index.html

tanstackStart({
  spa: {
    enabled: true,
    prerender: {
      outputPath: '/index.html',
      crawlLinks: true,
      retryCount: 3,
    },
  },
}),