docs: add "RoR Pro vs TanStack Start" architecture comparison

[justin808]

What

Adds docs/pro/react-server-components/tanstack-start-comparison.md — a dedicated architecture comparison of React on Rails Pro and TanStack Start, paralleling the merged RSC vs. Next.js doc (#4158).

It sits next to the Next.js comparison in the RSC docs section but takes a different axis: the Next.js doc compares two RSC implementations, whereas TanStack Start is client-first rather than RSC-first — so this doc compares two ways to own the full stack.

Companion to the decision-guide section in #4242 (that's the short "which do I pick" entry; this is the deep architecture explainer it can point to).

Framing (calibrated to mid-2026)

• Splits the TanStack suite. Query/Router/Table are complementary and run on top of Rails; only Start (the framework) substitutes — and specifically for the server tier.
• Grounded in Start's current shape. SSR-first (server-rendered by default; selective per-route SSR); ships no ORM/database ("bring your own backend"; Drizzle common). Rails is that backend, batteries included.
• RSC = the colocation answer, described as Pro-supported (Node renderer), not "experimental."
• Honest about RoR's costs. Two languages; untyped JSON boundary (closed via generated types — flagged as roadmap); extra dev processes vs. Start's single Vite command.
• Fair to Start. Explicitly concedes greenfield / no-Rails / one-language / velocity-first.
• Mirrors the exemplar's neutral tone ("neither is better") and "as of 2026" accuracy hedges.

Gates

• npx prettier@3.6.2 --write ✓
• node script/generate-llms-full.mjs ✓ (llms-full.txt + llms-full-pro.txt regenerated)
• script/check-docs-sidebar ✓ (registered in docs/sidebars.ts next to nextjs-comparison)
• lychee ✓ 8/8 OK, 0 errors (only external link is the starter repo; TanStack Start is described conceptually with no external link, matching the Next.js doc's precedent)

Note

Independent of #4242 (different files), so they can merge in any order.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added a new guide comparing React on Rails Pro and TanStack Start for teams evaluating full-stack React approaches.
  • Includes a side-by-side look at architecture, rendering behavior, type safety, developer workflow, and decision guidance.
• Chores
  • Updated the documentation navigation and machine-readable docs list so the new page appears in the React Server Components section.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: cdc1c01a-ba57-4186-8396-d14e0b23ca3a

📥 Commits

Reviewing files that changed from the base of the PR and between 3ed9434 and 25b37b3.

📒 Files selected for processing (3)

• docs/pro/react-server-components/tanstack-start-comparison.md
• docs/sidebars.ts
• llms-full-pro.txt

✅ Files skipped from review due to trivial changes (2)

• docs/sidebars.ts
• llms-full-pro.txt

---

Walkthrough

Adds a new documentation page comparing React on Rails Pro and TanStack Start, covering architecture, server logic, rendering, type safety, and decision guidance. The page is registered in the Docusaurus sidebar and inserted into the Pro full-text documentation stream (llms-full-pro.txt).

Changes

TanStack Start comparison doc

Layer / File(s)	Summary
TanStack Start comparison page, sidebar, and indexing docs/pro/react-server-components/tanstack-start-comparison.md, docs/sidebars.ts, llms-full-pro.txt	New page added covering the two-layer TanStack framing (client libraries vs Start framework), server logic colocation, rendering/first-paint differences, type safety, a capabilities comparison table, DX comparison, and decision guidance. Registered in the React Server Components sidebar item list and inserted as a PAGE: block in the Pro full-text documentation stream.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• shakacode/react_on_rails#4158: Adds a similar "React on Rails Pro vs Next.js" architectural comparison page with the same sidebar and Pro full-text indexing integration points.

Suggested labels

documentation

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding an architecture comparison doc between React on Rails Pro and TanStack Start.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch jg/tanstack-start-comparison-doc

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR adds a TanStack Start comparison page to the React on Rails Pro docs. The main changes are:

• New architecture comparison for React on Rails Pro and TanStack Start.
• Sidebar registration beside the existing RSC comparison docs.
• Regenerated llms-full-pro.txt and llms-full.txt documentation bundles.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
docs/pro/react-server-components/tanstack-start-comparison.md	Adds the new comparison page; its relative links and frontmatter follow nearby RSC docs patterns.
docs/sidebars.ts	Registers the new page with a sidebar id that matches the file path.
llms-full-pro.txt	Regenerates the Pro LLM docs bundle with the new comparison page and related docs text.
llms-full.txt	Regenerates the full LLM docs bundle with updated RSC and Rspack troubleshooting content.

_{Reviews (1): Last reviewed commit: "docs: add "RoR Pro vs TanStack Start" ar..." | Re-trigger Greptile}

[claude]

Review: docs: add RoR Pro vs TanStack Start architecture comparison

This PR adds a well-structured architecture comparison doc paralleling the existing Next.js comparison. The framing (libraries vs. framework, batteries-included Rails vs. assemble-your-own backend) is accurate and the neutral tone is maintained. Four issues worth addressing before merge, ranked by severity.

1. Missing Pro Feature callout (structural)
Every other doc in docs/pro/react-server-components/ (including the parallel nextjs-comparison.md) opens immediately after the title with a > **Pro Feature** blockquote linking to react-on-rails-pro.md and the upgrade/licensing page. This page jumps straight to the [!NOTE] admonition without it. Readers who land here from a search will not know the RSC capabilities described require a Pro license until they dig into the body text.

2. Dev experience paragraph is near-verbatim copy of nextjs-comparison.md lines 219-223
The RoR Pro dev-experience prose ("orchestrates several processes — Rails, client dev-server HMR, bundle watchers, node renderer, bin/dev + Procfile, Rspack closes the compile gap") is essentially copy-pasted from the Next.js comparison with minor word-order changes. When the dev-experience story changes, both docs will need to be updated and will drift independently.

3. "When you should choose TanStack Start" section diverges from the exemplar altitude
nextjs-comparison.md has no "When you should choose Next.js" section — it defers all selection guidance to the Decision Guide. This doc adds an affirmative product-selection section before the "Which should you choose?" deferral, which risks putting selection guidance in two places that can contradict the Decision Guide (which #4242 is already expanding).

4. "Router + Vite + server functions" / "Vite-driven" is imprecise (plausible, hedged by accuracy note)
TanStack Start runs on Vinxi (which orchestrates Nitro + Vite), not Vite directly. Listing Vite as a co-equal component alongside Router and server functions in the capability table mislabels the framework layering, though the doc itself hedges that TanStack names are "illustrative and not stable API."

[justin808]

Thanks — addressed in 3ed9434:

• SSR default: corrected to SSR-first (server-rendered by default; selective per-route SSR) across the "two ways to get a server" bullet, the "Rendering and first paint" section, the capability table, and the summary. Verified against TanStack's Selective SSR docs (ssr defaults to true).
• OSS vs. Pro callout (L8): added a note at the top — the TanStack client libraries (Query/Router/Table) work with open-source React on Rails; RSC and TanStack Router SSR require Pro. (The parallel Next.js doc is RSC-only, hence its single Pro callout; this page spans both, so the note is scoped accordingly.)
• "Vinxi, not Vite" (L36): TanStack Start migrated off Vinxi to Vite + Nitro + h3 in v1.121.0 (the "devinxi" change), so "Vite" is current — I kept it and added "Nitro" for precision rather than reverting to Vinxi / vinxi dev.
• DX paragraph parallels nextjs-comparison (L151): intentional. This doc is the TanStack-Start sibling of the Next.js RSC comparison, and the "price of bolting onto Rails" is the same in both; the parallel phrasing aids cross-reading.
• "When you should choose TanStack Start" section (L158): keeping it. The greenfield / no-Rails / one-language concession is a deliberate part of this doc's neutral stance; I'd rather state it inline than defer every word of selection guidance to the Decision Guide.

Resolving these threads.

[claude]

Review: docs — RoR Pro vs TanStack Start architecture comparison

Well-structured doc with clear framing and honest concessions to TanStack Start. All 8 internal cross-reference links are valid, sidebar placement is logical (grouped next to nextjs-comparison), and the Rails/RoR Pro side of the capabilities matrix is accurate. A few items to resolve before merge:

🔴 PR description contradicts document body on SSR defaults

The PR framing section explicitly says TanStack Start is "Client-first (SSR opt-in per route)", but the document body states it is "SSR-first: routes are server-rendered by default" — in the "Two ways to get a server" section (lines 53–55), the Rendering section (line 101), and the Summary. These are factually opposite. See inline comment on line 53.

Whether TanStack Start's default changed at stable 1.x needs confirming against the official release notes. Either the PR description or the three body locations needs updating to agree.

🟡 ssr: false / 'data-only' option names may be illustrative, not real API keys

The accuracy note correctly disclaims that TanStack names here are "illustrative of an idea, not a stable API" — but the option names appear in the body without that caveat attached to them. A reader building a Start project could try to use them as literal config values. Consider a parenthetical like "(exact API may differ — check TanStack Start docs)" at first use.

🟡 "Vite/Nitro" elides the Vinxi layer

Through mid-2025, Start was built on Vinxi, which wraps Vite and Nitro — not Vite + Nitro directly. If Vinxi was retired at 1.x, the description is accurate. See inline comment on line 41. Easy to confirm from the TanStack Start 1.0 changelog.

🟢 Rspack code snippet is technically correct

config.assets_bundler === 'rspack' and clientWebpackConfig.lazyCompilation = false are both confirmed against generator templates and the doctor checker. One minor note: the snippet omits the const { config } = require('shakapacker'); import that puts config in scope. Adding that line to the source doc (rsc-troubleshooting.md) would help readers applying this to a customised file.

🟢 Plugin name update in llms-full-pro.txt is correct

Changing RSCWebpackPlugin → "the RSC bundler plugin" is accurate; the generator uses RSCRspackPlugin for Rspack projects so the generic phrasing covers both.

🟢 docs/oss/api-reference/generator-details.md still references only the webpack plugin/path

That source doc wasn't updated in this PR. Not a blocker here — fine as a follow-up.

[claude]

Review: docs: add RoR Pro vs TanStack Start architecture comparison

This PR adds a well-structured architecture comparison for React on Rails Pro vs TanStack Start, with appropriate caveats, a balanced capabilities matrix, and correct sidebar/llms-full regeneration. All internal file links resolve. The tone is fair and mirrors the nextjs-comparison doc.

Four issues found — two confirmed, two plausible:

---

CONFIRMED — Link text promises content that does not exist (line 169)

The link text reads: Decision Guide: React on Rails vs. TanStack Start and other alternatives. The target file (docs/oss/getting-started/comparing-react-on-rails-to-alternatives.md) compares React on Rails against Hotwire, Inertia, Next.js, react-rails, and Vite. TanStack Start does not appear in it at all (only one mention of TanStack Router in a performance note). A reader clicking through finds no TanStack Start comparison content. Either the link text needs to match what the page actually covers, or TanStack Start content needs to be added to that doc first.

---

CONFIRMED — Prose implies SSR requires Pro; contradicts the capabilities table on the same page (line 107)

The Rendering and first paint section reads: React on Rails server-renders React from Rails (via the Node renderer in Pro). The parenthetical implies SSR itself requires Pro. But open-source React on Rails has had SSR via ExecJS (mini_racer) since the beginning. The capabilities table on the same page correctly states Server-rendered (Rails); streaming SSR + RSC in Pro — correctly separating basic OSS SSR from Pro-exclusive streaming SSR and RSC. The prose and table contradict each other on whether OSS SSR exists at all.

Suggested fix: React on Rails server-renders React from Rails (via ExecJS in OSS, or the faster Node renderer in Pro), and React on Rails Pro adds streaming SSR and RSC…

---

PLAUSIBLE — Starter repo link may be misread as a TanStack Start demo (line 171)

The bullet under Which should you choose? correctly describes the starter as using TanStack Query, Router, and Table on a Rails backend. But on a page titled TanStack Start comparison, a skimming reader may infer it demonstrates TanStack Start + Rails integration — it actually shows TanStack client libraries on Rails as an alternative to Start. A short parenthetical such as (uses TanStack client libraries, not TanStack Start) would remove the ambiguity.

---

PLAUSIBLE — Vite/Nitro understates Vinxi (line 41)

The capabilities table describes TanStack Start as TanStack Router + Vite/Nitro + server functions. In practice, Vite is the bundler/dev-server and Nitro is the deployment adapter — both wired together by Vinxi, the user-facing layer. Listing them as Vite/Nitro implies two interchangeable alternatives and may invite credibility questions from TanStack Start users. TanStack Router + Vinxi (Vite + Nitro) + server functions is more precise.

[claude]

Review: docs/pro/react-server-components/tanstack-start-comparison.md

Well-structured doc with an honest framing. All 8 internal links resolve correctly, the sidebar position is right (between `nextjs-comparison` and `glossary`), and the cross-file consistency with the Next.js comparison doc is clean. Four issues need attention before merge, plus a few fairness gaps worth considering.

---

Factual issues

1. Nitro vs. Vinxi (line 41) — The TanStack Start table row says "TanStack Router + Vite + Nitro + server functions." TanStack Start is built on Vinxi (the Naman Goel project that wraps Vite and uses Nitro as its server engine internally). Nitro is an internal dependency of Vinxi — not the layer TanStack Start surfaces in its own API or docs. A reader checking `package.json` or the TanStack Start docs would see `vinxi`, not `nitro`. Should read: "TanStack Router + Vite + Vinxi + server functions."

2. TanStack Start 1.x release date (line 26) — The accuracy note says it "reached a stable 1.x release earlier in the year" — in the context of "as of 2026", this implies a 2026 release. TanStack Start v1.0 shipped in 2024. The phrase should say something like "(stable since 2024)" rather than implying 2026.

3. `ssr: 'data-only'` as a code literal (lines 49, 104) — The string `'data-only'` appears twice as if it's an actual TanStack Start route config value. `ssr: false` is a real option; `ssr: 'data-only'` hasn't been verified against the TanStack Start 1.x API and may be an invented shorthand or conflation with another framework. If it's not a literal API value, it should be written in prose ("data-only mode") rather than as a backtick code literal.

4. Starter repo link (line 177) — `https://github.com/shakacode/react-on-rails-starter-tanstack\` should be confirmed to be a live, publicly accessible repo before the doc goes live. A 404 on the only external link in the doc would undermine the credibility of the whole page.

---

Fairness / completeness gaps

These don't block merge but are worth considering given the doc's stated goal of "neutral architectural comparison":

• Edge deployment: Start's support for Cloudflare Workers, Deno Deploy, Vercel Edge, Lambda@Edge, etc. is a first-class feature (via Vinxi/Nitro's adapters) and a genuine material architectural advantage for latency-sensitive apps. It currently appears only as "(or Edge)" in the hosting-model table row — one parenthetical against several paragraphs of Start disadvantages.

• TanStack Form: The library table lists Query, Router, and Table as "shared ground" but omits TanStack Form, which has a specific server-function integration in Start (end-to-end typed form submission with server validation, no codegen). Its absence makes the "shared libraries" framing look skewed.

• "When you should choose Start" scope: The section currently narrows the case to "greenfield, one language, small team, raw velocity." There are other legitimate Start use cases (edge-latency requirements, type-safety-first teams, apps with no pre-existing backend) that a genuinely balanced doc should enumerate.

• RSC "no `/api` round-trip" contrast: The summary says RSC "removes the extra `/api` round-trip" — but TanStack Start server functions also remove the need for a separate `/api` endpoint. The implied contrast is between RSC-on-Rails and a Rails JSON API, not between RSC and server functions. The earlier "Where your server logic lives" section handles this more accurately; the summary's phrasing could be tightened to avoid the misleading implication.

[justin808]

Re-review dispositions (head 25b37b396; all required checks green, mergeStateStatus: CLEAN). Resolving:

Addressed:

• PR description "client-first" (L55): the description's framing line is updated to SSR-first to match the doc.
• Decision Guide link (L169): docs: add "React on Rails vs TanStack Start" to the decision guide #4242 merged to main, so the linked Decision Guide now has its own "React on Rails vs TanStack Start" section — the link text is accurate.
• Starter repo link (L177): verified public + reachable (lychee 9/9 OK, 0 errors).
• (via the Node renderer in Pro) implied SSR = Pro (earlier head): fixed — now "in open-source via ExecJS, or via the Node renderer in Pro," matching the capability table.

Declined with rationale:

• "It's Vinxi, not Vite/Nitro" (L41 + earlier, ×several): stale. TanStack Start removed Vinxi in v1.121.0 ("devinxi"); the 1.x stack is Vite + Nitro + h3, configured directly via vite.config.ts + the tanstackStart plugin (app.config.ts / Vinxi is the pre-1.121 setup). Keeping "Vite + Nitro."
• ssr: 'data-only' may not be a real API value (L49/L104): it is — 'data-only' is a documented Selective SSR option (loaders run on the server, component renders on the client) alongside ssr: true | false.
• v1.0 timing (L25): the "stable 1.x as of 2026" note sits within the page's explicit "as of 2026 / illustrative, not a stable API" hedge, which points readers to current TanStack docs. Leaving the hedge to carry it rather than pin an exact date.
• Starter placement / "not Start" qualifier (L171): the text already reads "using TanStack Query, Router, and Table," naming the libraries; the whole doc's framing makes the libraries-vs-Start split explicit.
• RSC /api round-trip framing (L181): summary altitude; the body already states both stacks avoid the separate endpoint (Start via server functions, RoR via RSC / server rendering). No change.

Beta phase (main), development mode; docs-only, required checks green, lychee 0 errors. Enqueuing.