Gate TanStack starter on React on Rails 17 rc7 (#185)

* Gate TanStack starter on React on Rails 17 rc7

* Refresh RSC showcase visual snapshot

* Use neutral RSC prefetch completion copy

* Prepare assets for Playwright smoke

* Assert RSC prefetch response

Author: justin808

AGENTS.md

@@ -27,9 +27,10 @@ code first and then update the docs or this file in the same change.
   shell and Pro RSC payload endpoint; a bare TanStack Router loader selects the
   server component and props, and the exported React on Rails Pro `RSCRoute`
   helper fetches/composes the RSC payload with client islands on the local
-  Rspack default.
+  Rspack default. The route also includes a provider-backed RSC prefetch action
+  through `prefetchServerComponent`.
 - `/hello_server` demonstrates streaming RSC. Rspack client-reference manifests
-  are available with `react-on-rails-rsc@19.0.5-rc.7`; the remaining strict
+  are available with `react-on-rails-rsc@19.2.1-rc.0`; the remaining strict
   production CSP hydration limitation is documented in
   `docs/11-rsc-csp-nonce-spike.md`.
 - The root path `/` is a public Rails landing page (`home#index`). It leads with
@@ -225,6 +226,9 @@ Rules:
   fetching/rendering. Do not recreate the Pro length-prefixed stream parser,
   import `react-on-rails-rsc/client.browser` directly from app code, or replace
   the payload with a bespoke JSON protocol when the goal is to demonstrate RSC.
+- Use `react-on-rails-pro/prefetchServerComponent` when exercising provider
+  cache prefetching for this route; keep it pointed at the same component name
+  and props selected by the route loader.
 - Keep `app/views/react_on_rails_pro/rsc_payload.text.erb` trim-safe. A trailing
   newline after the helper output creates a blank line between length-prefixed
   RSC chunks, which the current Pro client parser treats as malformed. Track
@@ -275,7 +279,7 @@ Rules:
 - Production-assets mode must run with optimized assets and the React on Rails
   Pro Node renderer.
 - Treat interactive RSC client-reference manifest generation on Rspack as
-  expected behavior with `react-on-rails-rsc@19.0.5-rc.7` or newer. Keep
+  expected behavior with `react-on-rails-rsc@19.2.1-rc.0` or newer. Keep
   `pnpm run repro:rspack-rsc` available as the small regression check.
 - When validating unreleased `react_on_rails` or `react_on_rails_rsc` branches,
   follow `docs/12-upstream-branch-testing.md`. Do not leave local path or git

Gemfile

@@ -65,9 +65,9 @@ group :test do
   gem "selenium-webdriver"
 end
 
-gem "react_on_rails", "17.0.0.rc.6"
+gem "react_on_rails", "17.0.0.rc.7"
 
-gem "react_on_rails_pro", "17.0.0.rc.6"
+gem "react_on_rails_pro", "17.0.0.rc.7"
 
 gem "shakapacker", "10.2.0"
 

Gemfile.lock

@@ -330,22 +330,21 @@ GEM
       prism (>= 1.6.0)
       rbs (>= 4.0.0)
       tsort
-    react_on_rails (17.0.0.rc.6)
+    react_on_rails (17.0.0.rc.7)
       addressable
       connection_pool
       execjs (~> 2.5)
       rails (>= 5.2)
       rainbow (~> 3.0)
       shakapacker (>= 6.0)
-    react_on_rails_pro (17.0.0.rc.6)
-      addressable
+    react_on_rails_pro (17.0.0.rc.7)
       async (>= 2.29)
       async-http (~> 0.95)
       execjs (~> 2.9)
       io-endpoint (~> 0.17.0)
       jwt (>= 2.5, < 4)
-      rainbow
-      react_on_rails (= 17.0.0.rc.6)
+      nokogiri (>= 1.12, < 2)
+      react_on_rails (= 17.0.0.rc.7)
     regexp_parser (2.12.0)
     reline (0.6.3)
       io-console (~> 0.5)
@@ -492,8 +491,8 @@ DEPENDENCIES
   puma (>= 5.0)
   rack-attack (~> 6.8)
   rails (~> 8.1.3)
-  react_on_rails (= 17.0.0.rc.6)
-  react_on_rails_pro (= 17.0.0.rc.6)
+  react_on_rails (= 17.0.0.rc.7)
+  react_on_rails_pro (= 17.0.0.rc.7)
   rspec-rails (~> 8.0)
   rubocop-rails-omakase
   selenium-webdriver

README.md

@@ -50,7 +50,8 @@ Each route demonstrates a deliberate rendering choice, not a fallback:
   Flight stream, and composes that server-streamed tree beside ordinary client
   React. It now includes an in-app status panel that separates the working RSC
   payload route from the lower-level streaming client-island limitation. It runs
-  on the default Rspack bundler with `react-on-rails-rsc@19.0.5-rc.7`.
+  on the default Rspack bundler with `react-on-rails-rsc@19.2.1-rc.0` and
+  exercises the provider-backed RSC prefetch path.
 - **`/hello_server`** demonstrates streaming React Server Components. The demo
   keeps an interactive `LikeButton` client island inside a server-rendered
   tree, but labels that island as the separate client-reference edge case. On
@@ -77,20 +78,21 @@ Rspack is the default Shakapacker bundler for local development and the
 deployed image. Use `config/shakapacker.yml`, `config/rspack/`, and the
 `.controlplane/Dockerfile` build ARG as the source of truth for the default
 path. The Rspack RSC plugin in
-`react-on-rails-rsc@19.0.5-rc.7` emits the client/server manifests the Pro RSC
+`react-on-rails-rsc@19.2.1-rc.0` emits the client/server manifests the Pro RSC
 client-reference path needs. Webpack remains an opt-in bridge/comparison path
 via `SHAKAPACKER_ASSETS_BUNDLER=webpack`.
 
 | Component | Version |
 | --- | --- |
-| React on Rails / Pro | `17.0.0.rc.3` |
-| Shakapacker / Shakapacker Rspack | `10.1.0` |
-| React | `19.0.6` |
+| React on Rails / Pro | `17.0.0.rc.7` / `17.0.0-rc.7` |
+| React on Rails RSC | `19.2.1-rc.0` |
+| Shakapacker / Shakapacker Rspack | `10.2.0` |
+| React | `19.2.7` |
 | Rails | `8.1.x` |
 | Language / tooling | TypeScript, pnpm |
 
-Shakapacker stays on `10.1.0` for this release because public `11.1.0`
-artifacts are not yet visible in the registries consumed by the starter.
+Shakapacker stays on `10.2.0` for this release; the React on Rails 17 RC7
+upgrade did not require a coupled Shakapacker bump.
 
 ## Setup
 

SPIKE.md

@@ -15,7 +15,7 @@ The remaining limitation is separate from the bundler: `/hello_server`'s client
 island still waits on the upstream React on Rails Pro streaming CSP nonce fix in
 strict production CSP mode. See `docs/11-rsc-csp-nonce-spike.md`.
 
-The app was bootstrapped with `create-react-on-rails-app --rsc --rspack --package-manager pnpm` and the current release stack targets React on Rails Pro `17.0.0-rc.3` with Shakapacker `10.1.0`. Shakapacker stays on `10.1.0` because public `11.1.0` artifacts are not visible in the registries consumed by the starter. The Rails/Rspack/React on Rails Pro setup passes `react_on_rails:doctor` with the expected warning that both Rspack and Webpack configs are present.
+The app was bootstrapped with `create-react-on-rails-app --rsc --rspack --package-manager pnpm` and the current release stack targets React on Rails Pro `17.0.0-rc.7`, React on Rails RSC `19.2.1-rc.0`, and Shakapacker `10.2.0`. Shakapacker stays on `10.2.0` because the React on Rails 17 RC7 upgrade did not require a coupled Shakapacker bump. The Rails/Rspack/React on Rails Pro setup passes `react_on_rails:doctor` with the expected warning that both Rspack and Webpack configs are present.
 
 ## Validation Goals
 
@@ -27,8 +27,9 @@ The app was bootstrapped with `create-react-on-rails-app --rsc --rspack --packag
 ## What Worked
 
 - Rails 8.1 app scaffolded with PostgreSQL and SolidQueue.
-- React on Rails and React on Rails Pro release stack: `17.0.0.rc.3`.
-- Shakapacker launch stack: `10.1.0`.
+- React on Rails and React on Rails Pro release stack: `17.0.0.rc.7`.
+- React on Rails RSC stack: `19.2.1-rc.0`.
+- Shakapacker launch stack: `10.2.0`.
 - Rspack builds complete successfully and emit the RSC client-reference
   manifests with `react-on-rails-rsc@19.0.5-rc.2`.
 - The `/dashboard` TanStack Router, Query, and Table surface prerenders through React on Rails Pro's Node renderer and hydrates under the Rails shell.
@@ -45,10 +46,10 @@ manifests present.
 Current stance:
 
 - Keep Rspack as the bundler.
-- Keep the React on Rails Pro `17.0.0-rc.3` and Shakapacker `10.1.0` release stack.
+- Keep the React on Rails Pro `17.0.0-rc.7`, React on Rails RSC `19.2.1-rc.0`, and Shakapacker `10.2.0` release stack.
 - Keep the Rspack/RSC client boundary repro in `pnpm run repro:rspack-rsc`.
 - Keep direct Rspack packages aligned with the Shakapacker Rspack 2 adapter: `@rspack/core` / `@rspack/cli` `2.0.4` and `@rspack/dev-server` `2.0.1`.
-- Keep `react-on-rails-rsc` on `19.0.5-rc.7` or newer when requiring Rspack RSC
+- Keep `react-on-rails-rsc` on `19.2.1-rc.0` or newer when requiring Rspack RSC
   client-reference manifests.
 
 Impact:

app/javascript/src/RscShowcase/ror_components/RscShowcaseApp.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import React, { Suspense, useMemo, useState } from 'react';
+import React, { Suspense, useCallback, useMemo, useRef, useState } from 'react';
 import {
   Outlet,
   RouterProvider,
@@ -12,6 +12,7 @@ import {
 } from '@tanstack/react-router';
 import { CheckCircle2, ExternalLink, RefreshCw, Route, Server, ShieldCheck, TriangleAlert } from 'lucide-react';
 import RSCRoute from 'react-on-rails-pro/RSCRoute';
+import { prefetchServerComponent } from 'react-on-rails-pro/prefetchServerComponent';
 import wrapServerComponentRenderer from 'react-on-rails-pro/wrapServerComponentRenderer/client';
 import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
 import { Badge } from '@/components/ui/badge';
@@ -83,6 +84,55 @@ function PayloadRenderer({ routeData }: { routeData: RscRouteData }) {
   );
 }
 
+type PrefetchStatus = 'idle' | 'loading' | 'ready' | 'error';
+
+function PayloadPrefetchButton({ routeData }: { routeData: RscRouteData | null }) {
+  const [status, setStatus] = useState<PrefetchStatus>('idle');
+  const inFlightRef = useRef<Promise<void> | null>(null);
+
+  const prefetchPayload = useCallback(() => {
+    if (!routeData) return Promise.resolve();
+    if (inFlightRef.current) return inFlightRef.current;
+
+    setStatus('loading');
+    const request = prefetchServerComponent(routeData.componentName, routeData.componentProps, {
+      skipIfEmbedded: false,
+    })
+      .then(() => {
+        setStatus('ready');
+      })
+      .catch(() => {
+        setStatus('error');
+      })
+      .finally(() => {
+        inFlightRef.current = null;
+      });
+
+    inFlightRef.current = request;
+    return request;
+  }, [routeData]);
+
+  const label = {
+    idle: 'Prefetch payload',
+    loading: 'Prefetching payload',
+    ready: 'Prefetch completed',
+    error: 'Prefetch failed',
+  }[status];
+
+  return (
+    <Button
+      type="button"
+      variant={status === 'error' ? 'destructive' : 'outline'}
+      className="mt-1"
+      disabled={!routeData || status === 'loading'}
+      onClick={() => void prefetchPayload()}
+    >
+      {status === 'loading' ? <RefreshCw className="size-4 animate-spin" aria-hidden="true" /> : null}
+      {label}
+    </Button>
+  );
+}
+
 function ClientSignalPanel({ className }: { className?: string }) {
   const [pulses, setPulses] = useState(0);
 
@@ -280,6 +330,7 @@ function ShowcasePage({ appProps, routeData }: { appProps: RscShowcaseAppProps;
               <RefreshCw className="size-4" aria-hidden="true" />
               Refetch payload
             </Button>
+            <PayloadPrefetchButton key={routeData?.requestPath ?? 'unavailable'} routeData={routeData} />
           </CardContent>
         </Card>
       </header>

docs/01-architecture.md

@@ -1,8 +1,8 @@
 # Architecture
 
-This starter begins from `create-react-on-rails-app --rsc --rspack` and currently targets the React on Rails Pro `17.0.0-rc.3` RC stack with Shakapacker `10.1.0`.
+This starter begins from `create-react-on-rails-app --rsc --rspack` and currently targets the React on Rails Pro `17.0.0-rc.7` RC stack with React on Rails RSC `19.2.1-rc.0` and Shakapacker `10.2.0`.
 
-Shakapacker remains on `10.1.0` because public `11.1.0` artifacts are not visible in the registries this starter consumes. Rspack is the checked-in local and deploy default. `react-on-rails-rsc@19.0.5-rc.7` provides the Rspack RSC manifest support this starter needs, while Webpack remains an opt-in bridge/comparison path.
+Shakapacker remains on `10.2.0` because the React on Rails 17 RC7 upgrade did not require a coupled Shakapacker bump. Rspack is the checked-in local and deploy default. `react-on-rails-rsc@19.2.1-rc.0` provides the Rspack RSC manifest support this starter needs, while Webpack remains an opt-in bridge/comparison path.
 
 ## Related React On Rails Docs
 
@@ -104,7 +104,7 @@ Vite, file-based routing, Hotwire, or Stimulus.
 Rspack is the active bundler in `config/shakapacker.yml`. Development disables client lazy compilation at the config top level and at `experiments.lazyCompilation`, uses live reload by default for this RC stack, and gates TanStack devtools behind `localStorage["tanstack-devtools"] = "1"` to avoid dev-server overlay requests from optional chunks. Explicit HMR mode enables React Fast Refresh through Shakapacker's Rspack wiring, while static and production-assets dev modes remain free of Rspack dev-server clients.
 
 The public React Server Components path is green on the local Rspack default
-with `react-on-rails-rsc@19.0.5-rc.7`. The Rspack client, server, and
+with `react-on-rails-rsc@19.2.1-rc.0`. The Rspack client, server, and
 server-only RSC bundles compile and emit the React client/server manifests
 expected by the React on Rails RSC client-reference path. The Webpack bridge
 remains documented in [RSC Webpack Bundler Spike](09-rsc-webpack-bundler-spike.md)

docs/02-vs-inertia.md

@@ -149,7 +149,7 @@ renderer such as React on Rails Pro. That is an architectural inference, not a
 claim about Inertia's roadmap.
 
 The Rspack status is also intentionally conservative. Rspack remains the local
-and deploy default, and `react-on-rails-rsc@19.0.5-rc.7` emits the RSC
+and deploy default, and `react-on-rails-rsc@19.2.1-rc.0` emits the RSC
 client-reference manifests required by React on Rails Pro. The status is tracked
 in [SPIKE.md](../SPIKE.md) and [Tested Modes](06-tested-modes.md). The Webpack
 bridge remains an opt-in comparison path.

docs/06-tested-modes.md

@@ -1,9 +1,10 @@
 # Tested Modes
 
 This starter keeps the TanStack dashboard on Rspack and the launch RC stack:
-React on Rails Pro `17.0.0-rc.3` with Shakapacker `10.1.0`.
-Shakapacker is intentionally not documented as `11.1.0` because public
-`11.1.0` artifacts are not visible in the registries consumed by the starter.
+React on Rails Pro `17.0.0-rc.7`, React on Rails RSC `19.2.1-rc.0`, and
+Shakapacker `10.2.0`.
+Shakapacker remains on `10.2.0` because the React on Rails 17 RC7 upgrade did
+not require a coupled Shakapacker bump.
 Rspack is the default local and deploy bundler in the checked-in matrix.
 Webpack has explicit opt-in bridge/comparison smokes below.
 
@@ -61,7 +62,7 @@ build, rendering, or routing behavior.
 | HMR dev | `bin/test hmr` or `SHAKAPACKER_DEV_SERVER_HMR=true bin/dev --no-open-browser --route=dashboard` | CI | Boots the same default dev stack with `hmr: true`, `live_reload: false`, and React Fast Refresh enabled by Shakapacker's Rspack integration, then verifies the authenticated TanStack routes hydrate, navigate, and observe a browser-open source edit. This smoke does not assert state-preserving React Fast Refresh updates. |
 | Webpack HMR bridge | `bin/test webpack-hmr` or `SHAKAPACKER_ASSETS_BUNDLER=webpack node script/dev-mode-smoke.mjs hmr` | Webpack bridge sentinel | Boots Rails, Webpack dev-server, SolidQueue, the Node renderer, and the server/RSC bundle watchers with HMR enabled, then verifies the authenticated TanStack routes hydrate, navigate, and observe a browser-open source edit. This keeps the optional Webpack path covered without changing the Rspack default. |
 | Webpack HMR RSC bridge | `bin/test webpack-hmr-rsc` or `SHAKAPACKER_ASSETS_BUNDLER=webpack REQUIRE_RSC_MANIFESTS=true node script/dev-mode-smoke.mjs hmr hello-server` | Webpack RSC/HMR sentinel | Boots the Webpack HMR stack against `/hello_server`, waits for both RSC client-reference manifests, and fails if the route falls back before rendering the RSC page. This verifies the optional Webpack dev-server writes the client manifest where React on Rails Pro can consume it while still excluding hot-update artifacts from disk. |
-| Rspack/RSC client boundary repro | `bin/test rsc-repro` or `pnpm run repro:rspack-rsc` | CI status, upstream repro | Builds Rspack bundles, verifies the generated `HelloServer` RSC example still contains a `'use client'` boundary, and confirms both RSC client-reference manifests are emitted with `react-on-rails-rsc@19.0.5-rc.7`. Use `REQUIRE_RSC_MANIFESTS=true` when this focused check must fail hard on a manifest regression. |
+| Rspack/RSC client boundary repro | `bin/test rsc-repro` or `pnpm run repro:rspack-rsc` | CI status, upstream repro | Builds Rspack bundles, verifies the generated `HelloServer` RSC example still contains a `'use client'` boundary, and confirms both RSC client-reference manifests are emitted with `react-on-rails-rsc@19.2.1-rc.0`. Use `REQUIRE_RSC_MANIFESTS=true` when this focused check must fail hard on a manifest regression. |
 | `/hello_server` RSC route smoke | `bin/test hello-server-rsc` or `pnpm run test:hello-server-rsc` | RSC route sentinel | Boots the static-assets dev stack against `/hello_server` and verifies the route renders the demo shell with the RSC manifests available. Use `REQUIRE_RSC_MANIFESTS=true` when intentionally requiring interactive RSC client-reference manifests. |
 | Production precompile | `bin/test production-precompile` or `RAILS_ENV=production SECRET_KEY_BASE_DUMMY=1 REACT_ON_RAILS_STARTER_TANSTACK_DATABASE_PASSWORD=dummy bin/rails assets:precompile` | Release-impacting checks | Confirms production Rspack client, server, and RSC bundles compile. The expected Pro license warning is non-fatal. |
 | Production boot smoke | `bin/test production-boot` or `node script/production-boot-smoke.mjs` | CI, release-impacting checks | Precompiles production assets with dummy secrets, prepares production-mode databases, starts `client/node-renderer.js` from compiled output, boots Rails in `RAILS_ENV=production`, checks `/up`, signs in as `demo@example.com / password`, and checks `/projects?status=active&sort=name&dir=asc` with `X-Forwarded-Proto: https`. |
@@ -115,5 +116,5 @@ build, rendering, or routing behavior.
   with `experiments.lazyCompilation = false` kept explicit for compatibility.
   Otherwise dynamic TanStack devtools imports can route through Rspack
   lazy-trigger URLs that return 404s in development.
-- Historical Rspack/RSC manifest tracking lives in [shakacode/react_on_rails#1828](https://github.com/shakacode/react_on_rails/issues/1828). The starter requires `react-on-rails-rsc@19.0.5-rc.7` or newer for the Rspack manifest path.
+- Historical Rspack/RSC manifest tracking lives in [shakacode/react_on_rails#1828](https://github.com/shakacode/react_on_rails/issues/1828). The starter requires `react-on-rails-rsc@19.2.1-rc.0` or newer for the Rspack manifest path.
 - The React on Rails Pro TanStack Router private-store compatibility issue is tracked in [shakacode/react_on_rails#3375](https://github.com/shakacode/react_on_rails/issues/3375).

docs/08-why-rsc-on-rails.md

@@ -226,7 +226,7 @@ inside one Rails app.
 ## Limitations And Current State
 
 This starter intentionally keeps Rspack as the local and deploy default.
-`react-on-rails-rsc@19.0.5-rc.7` provides the Rspack plugin path that emits the
+`react-on-rails-rsc@19.2.1-rc.0` provides the Rspack plugin path that emits the
 RSC client-reference manifests required by React on Rails Pro. That status is
 tracked in [SPIKE.md](../SPIKE.md), and the small reproduction remains available
 through `pnpm run repro:rspack-rsc`.