Skip to content
Source
Sign inSign up
TanStack/router

docs(start): document Cloudflare Pages deployment for SPA mode #8829

Openjainamm-gala(GitHub profile, opens in a new tab)wants to merge 1 commit intomain fromrefs/pull/8829/headopened

🎯 Changes

Closes #5619, which was kept open as a docs task.

  • hosting.md: new "Cloudflare Pages (SPA mode)" section. Pages serves the root index.html for unmatched paths when there is no top-level 404.html, so the shell goes to outputPath: '/index.html' and no _redirects rule is needed. Also notes why a catch-all /* /_shell.html 200 breaks on Pages (rules apply even when an asset matches).
  • spa-mode.md: a note under the redirects example linking to that section.

Checked with a minimal Start app (@tanstack/react-start 1.169.4): the default build emits _shell.html and no root index.html. With outputPath: '/index.html' it emits dist/client/index.html (the shell) and no 404.html.

Drafted with AI assistance. I checked the build output and reviewed every change.

✅ Checklist

  • I have followed the steps in the Contributing guide.
  • I have tested code changes locally with the relevant test commands, or tests do not apply to this pull request.
  • I fully understand the code in this pull request, including any code generated with AI assistance.

🚀 Release Impact

  • This change affects published code, and I have generated a changeset.
  • This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

  • Documentation
    • Added a Cloudflare Pages deployment guide for SPA-mode apps, including build settings and hosting considerations.
    • Updated the SPA mode guide with Cloudflare Pages fallback guidance and a link to the new deployment guide.
    1. ⚠️ No Changeset found

      Latest commit: 35d6d61185290709c72ecab1e7c10d0bf1ea2139

      Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

      This PR includes no changesets

      When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

      Click here to learn what changesets are, and how to add one.

      Click here if you're a maintainer who wants to add a changeset to this PR

    2. Review in Change Stack →

      No actionable comments were generated in the recent review.

      Recent review info
      Run configuration
      Commits

      Reviewing files that changed from the base of the PR and between da2adec76dbe6c0da6d6a0d5640f7b9388217f45 and 35d6d61185290709c72ecab1e7c10d0bf1ea2139.

      Files selected for processing: 2
      • docs/start/framework/react/guide/hosting.md
      • docs/start/framework/react/guide/spa-mode.md

      Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

      Walkthrough

      The documentation adds Cloudflare Pages instructions for SPA-mode deployments. It describes the shell output path, build settings, and fallback behavior, and links the SPA mode guide to the hosting instructions.

      Changes: Cloudflare Pages SPA hosting

      Layer / File(s)Summary
      Document Cloudflare Pages SPA deployment
      docs/start/framework/react/guide/hosting.md, docs/start/framework/react/guide/spa-mode.md
      The hosting guide documents configuring the SPA shell as /index.html, building to dist/client, and avoiding catch-all _redirects rules and top-level 404.html files. The SPA mode guide notes Pages' built-in fallback and links to the hosting guide.
      Priority: Normal

      Estimated code review effort: 1 (Trivial) | ~5 minutes

      Change: Other · Severity of issue fixed: Medium

      Suggested labels: documentation

      Suggested reviewers: schiller-manuel

      Merge Risk: Minimal · up to 35d6d

      This change adds Cloudflare Pages SPA deployment guidance and a link to it from the SPA mode guide. The documented configuration emits the root index.html as intended, and no merge-blocking issue remains.

      Pre-merge checks: Passed 4 · Failed 1
      Failed Failed checks: 1 warning
      Check nameStatusExplanationResolution
      Linked Issues checkWarningIssue [#5619] expects the SPA shell to load at the site root for local and Cloudflare Pages builds. The PR documents a Cloudflare Pages setup with outputPath: '/index.html', the Pages build settings…Address the local-build behavior required by [#5619], or document a verified local configuration and its expected build and preview behavior. Add focused automated coverage if the implementation changes.
      Passed Passed checks: 4 passed
      Check nameStatusExplanation
      Title checkPassedThe title clearly and concisely describes the main documentation change: adding Cloudflare Pages deployment guidance for SPA mode.
      Description checkPassedThe description explains the changes and motivation, completes all checklist items, discloses AI assistance, and correctly identifies the change as documentation-only with no release impact.
      Out of Scope Changes checkPassedThe changes are limited to hosting.md and spa-mode.md. The new Cloudflare Pages section and the link from the redirects example directly support [#5619]. The redirect and 404.html notes explain …
      Docstring CoveragePassedNo eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…
      Full details: Out of Scope Changes check

      Explanation

      The changes are limited to hosting.md and spa-mode.md. The new Cloudflare Pages section and the link from the redirects example directly support [#5619]. The redirect and 404.html notes explain the documented deployment behavior. No unrelated source or release changes are present.

      Full details: Docstring Coverage

      Explanation

      No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 0 functions across 0 files. (2 skipped: 2 unsupported.)

      Full details: Linked Issues check

      Explanation

      Issue [#5619] expects the SPA shell to load at the site root for local and Cloudflare Pages builds. The PR documents a Cloudflare Pages setup with outputPath: '/index.html', the Pages build settings, and no catch-all _redirects rule. It does not change implementation or document a solution for the reported local-build behavior. The supplied summary also identifies no automated tests, which is reasonable for documentation changes but does not resolve the unmet local requirement.

      Resolution

      Address the local-build behavior required by [#5619], or document a verified local configuration and its expected build and preview behavior. Add focused automated coverage if the implementation changes.

      Finishing Touches
      🧪 Generate unit tests (beta)
      • Create a new PR
      • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

      Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

      ❤️ Share
      Comment `@coderabbitai help` to get the list of available commands.

Sign in to join this conversation.