React on Rails Starter TanStack

Flagship React on Rails + TanStack starter. It uses the RC releases of React on Rails Pro and Shakapacker with Rspack:

• react_on_rails / react_on_rails_pro 16.7.0.rc.1
• react-on-rails-pro / react-on-rails-pro-node-renderer 16.7.0-rc.1
• shakapacker / shakapacker-rspack 10.1.0-rc.2
• Rails 8.1, React 19, TypeScript, pnpm, Rspack, React Server Components

Quick Start

git clone git@github.com:shakacode/react-on-rails-starter-tanstack.git
cd react-on-rails-starter-tanstack
bin/setup
bin/dev
open http://localhost:3000

Run bin/doctor first when setup fails; it checks Ruby, Node, pnpm, Bun, and Postgres with actionable fix messages. The seed user is demo@example.com / password.

Development

bundle exec rspec
pnpm run test:router-shim
pnpm test:playwright
pnpm run test:dev-modes
pnpm run test:hmr
bin/test

bin/dev starts Rails, Rspack, SolidQueue, the Pro Node renderer, and the RSC bundle watcher through Procfile.dev. This starter keeps Rspack development on live reload by default; run SHAKAPACKER_DEV_SERVER_HMR=true bin/dev --no-open-browser --route=dashboard or pnpm run test:hmr when you want to test HMR-specific behavior.

Use these alternate modes to smoke-test non-HMR paths:

bin/dev static --no-open-browser --route=dashboard
bin/dev prod --no-open-browser --route=dashboard

Both modes start the Node renderer because the authenticated TanStack dashboard is server-rendered by React on Rails Pro.

The authenticated /dashboard route is the TanStack surface:

• TanStack Router runs under a Rails-owned HTML shell and is prerendered by React on Rails Pro's Node renderer.
• TanStack Query loads independent metric cards and Rails JSON API data with CSRF-aware helpers.
• TanStack Table drives the projects list with server-backed filter, sort, pagination, and URL state.
• Project index/create/show/edit and nested settings routes stay inside the client-side dashboard experience, including direct full-page loads to /projects....
• Classic Rails CRUD remains available at /classic/projects to demonstrate hybrid Rails UI coexistence.

TanStack Router and Query devtools are bundled but disabled by default in development. Enable them only when needed:

localStorage.setItem("tanstack-devtools", "1")

Current Status

This repo is the public template seed. Phase 2 adds Rails 8 authentication, signup, email verification, resend throttles, development mail previews, and a verified-email dashboard gate. Phase 3 adds Projects CRUD, scoped authorization, JSON API endpoints, metrics, factories, and demo seeds.

Phase 4 implements the TanStack Router/Query/Table authenticated surface described in shakacode/react_on_rails#3364.

See SPIKE.md for the current AMBER RSC/Rspack compatibility note: Rspack builds are green, but interactive RSC client-reference plugin support is blocked upstream.

Docs

• Architecture
• React on Rails + TanStack vs Inertia
• Customizing
• Deploying
• Troubleshooting
• Tested Modes
• Control Plane Handoff
• Upgrading

License

MIT