Tracking: docs & demos to make React on Rails Pro a legit Next.js / TanStack Start alternative (and easy Inertia / vite-rails migration)

Goal: make React on Rails Pro a legit alternative to Next.js and TanStack Start, and a compelling migration target from Inertia Rails and plain vite-rails — via docs and demos. This is the marketing/education/proof track that complements the engineering roadmap in shakacode/react_on_rails#3864.

Provenance: produced from an AI research pass (2026-07-02): first-hand audit of reactonrails.com (full sitemap + every load-bearing page) and shakapacker.com, plus a 100+-agent comparison sweep of the Next.js, TanStack Start, Inertia Rails, and vite_ruby docs/demo ecosystems, with each factual claim adversarially verified by 3 independent agents against the live sites. Priorities are suggestions for maintainer triage.

Premise: the problem is proof, not coverage

The docs foundation is already competitive — npx create-react-on-rails-app, a 15-minute quick start, ~150 doc pages, migration guides for Next.js/Inertia/vite-rails, honest comparison pages, 7 demos all with live URL + source, /prompts, and llms.txt. What competitors win on is artifacts that create conviction: Next.js has its 16-chapter Learn course (financial-dashboard app teaching RSC, streaming, and Server Actions mutations); TanStack has end-to-end types and a starter gallery; Inertia has starter kits with auth + SSR + Kamal deploy included.

Verified gaps

1. No Learn-course equivalent. The 7-part RSC tutorial is reference-shaped, not project-shaped.
2. Benchmarks are self-admittedly "directional" — small samples, conflated variables (RSC + Pro renderer + SSR measured together), un-preserved environments.
3. The Inertia migration guide is a self-described v1 — it promises the step-by-step playbook (forms, shared state, SSR cutover, removing Inertia) and worked example app "as follow-ups."
4. The mutations story is never shown in code. Comparison pages say "Rails controllers own mutations" but never show what replaces a Server Action / TanStack server function.
5. Type safety across the Rails↔React boundary is an admitted roadmap item — TanStack Start's strongest objection.
6. Discoverability: the /docs index surfaces only "Migrate from react-rails"; the Inertia and vite-rails migration guides are invisible from it.
7. The vite-rails guide answers "how" but not "why/when/how long" — no effort estimates or cost-benefit case for teams content with Vite.
8. No one-click deploys on any demo repo (vs the ubiquitous Vercel button).
9. shakapacker.com has zero examples/demos (/examples is a thin resources hub) and no llms.txt.
10. Case studies buried — Popmenu (−73% response time) lives under RSC docs; HiChee and Academia.edu aren't told as stories.

Plan

P0 — quick wins (days each)

• #141 — Surface migration guides on the /docs index + homepage tiles (gap 6) — done via #144 (homepage tiles + sidebar Migration Guides category, 2026-07-04)
• shakacode/react_on_rails#4445 — "Mutations without Server Actions" recipe page (gap 4) — done via shakacode/react_on_rails#4463 (mutations.md: same mutation in three stacks, linked from both comparison pages, 2026-07-03); useRailsForm itself shipped via shakacode/react_on_rails#3942
• #142 — Deploy buttons (Render/Railway/Fly) on all 7 demo repos + "deploy a demo in 5 minutes" docs page (gap 8)
• shakacode/react_on_rails#4446 — Effort estimates + decision rubrics in the Inertia and vite-rails migration guides (gaps 3, 7) — done via shakacode/react_on_rails#4462 (sizing tables + worked examples in both guides, 2026-07-03)
• shakacode/shakapacker.com#35 — shakapacker.com: llms.txt + real examples page with starter repos (gap 9; transferred from shakacode/shakapacker#1198 — the site repo owns this work)

P0.5 — docs-quality instrumentation (added 2026-07-09)

The docs corpus (176 pages, ~308k words) changes fast enough that one-shot audits rot within weeks. These two items make quality measurable and self-maintaining:

• #147 — Docs inventory + scoring pipeline (npm run audit:inventory): per-page length/age/inbound-links/flags dataset, regenerated on demand; feeds an Importance × Quality triage
• #148 — Docs-as-evals harness: fresh agent sessions must complete 8 canonical tasks (install, first component, SSR, RSC, mutations, deploy, migrate) using only the docs; failures file issues naming the page and step

P1 — the big rocks (this quarter; these create conviction)

• "Learn React on Rails Pro" course — chaptered, project-shaped course building the same financial-dashboard app as Next.js Learn (public page, Devise auth, invoice CRUD, Postgres, streaming SSR, RSC, controller mutations). Chapter-for-chapter parity so evaluators compare identical apps and see where Rails conventions delete work. MVP: 12–16 chapters + repo with one git tag per chapter (gap 1)
• Reproducible benchmark harness — one app implemented in RoR Pro / Next.js / Inertia+SSR / vite-rails+SSR; scripted runs (pinned versions, documented hardware, warm/cold, p50/p95/p99, bundle sizes, CWVs); published methodology + "run it yourself" one-liner. Isolate the variables the current page conflates (ExecJS→Node renderer, SSR→streaming, no-RSC→RSC). Feeds a quantified ops-cost page (node-renderer memory/latency, hosting vs Vercel) (gap 2)
• Keep the Inertia guide's promise — worked migration repo: a real small Inertia app migrated to RoR Pro commit-by-commit (one PR per phase) using the documented coexistence setup, with an honest effort log and before/after Lighthouse/CWV; playbook doc derived from the commits (gap 3). Note: this item now also owns the step-by-step playbook — shakacode/react_on_rails#3899 closed after verifying coexistence only, and the Inertia guide's scope note still points readers at that closed issue for the playbook; re-point it here.

P2 — depth and reach

• End-to-end type-safety guide + tooling (Rails props → generated TS types; typelizer/ts_routes or an official generator) (gap 5)
• Top-level Case Studies page: Popmenu, HiChee, Academia.edu (Shakapacker/Rspack), with architecture notes (gap 10)
• Extend the Gumroad same-app comparison into the benchmark harness's public face: live CWV dashboard per variant
• "Which demo answers which question" matrix on /examples (curation over creation — demo inventory already beats every competitor except Next.js)
• AI-onboarding doubling-down: llms-full.txt, migration-specific prompts on /prompts, and make agent-driven create-react-on-rails-app the tested path (pairs with shakacode/react_on_rails#3868 / #3870)
• vite-rails worked example migration (smaller-scale version of the Inertia one)

Explicit non-goals

• More reference pages — coverage already leads everyone but Next.js.
• More standalone demos before the existing seven are wired into guides, courses, and deploy buttons.
• Chasing Next.js segment-level routing/prefetching claims in docs — the honest "it's still your Rails app" framing is working.

Success criteria

• An Inertia team can go from "considering" to "migrated first route" using only the playbook + worked repo, and can estimate total effort before starting.
• A Next.js dev can complete Learn-RoR-Pro having seen streaming, RSC, and mutations in Rails — in the same app they built in Next.js Learn.
• Every performance claim on the site links to a repo + methodology a skeptic can rerun.
• Every demo repo deploys in one click.
• "How do I mutate data without Server Actions?" is answered with code on one page.

Related

• shakacode/react_on_rails#3864 (engineering roadmap this complements)
• #132 (Pro-first copy alignment), #129 (flagship demo on examples — may already be done; examples page now lists it)

🤖 Generated with Claude Code

Start by reading the P0, P0.5, P1, and P2 plan items alongside the referenced reactonrails.com, react_on_rails, and shakapacker.com issues; this is a roadmap rather than a single entry point or file. Scope one listed deliverable before proceeding, and use the stated success criteria—migration guidance, reproducible claims, completed course material, or deployable demos—to define done.