Skip to content
Source
Sign inSign up
TanStack/router

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

Send to my agent
Openwesthouseit(GitHub profile, opens in a new tab) opened this issue 8 comments

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:


  1. 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

  2. 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?

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

  4. 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

  5. ok so this is then a documentation topic

  6. schiller-manuel(GitHub profile, opens in a new tab) added labelsdocumentation

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

  8. Above is unreliable, best to explicitly set index.html

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

  9. I verified the corrected outputPath: 'index.html' configuration against current main. The production SPA build emits dist/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.

Sign in to join this conversation.