Pin Pro react-on-rails-rsc peer to an explicit ^19.0.5 range (#4082)

justin808 · claude · web-flow · commit adb5067483db · 2026-06-17T17:18:02.000-10:00
## Why `packages/react-on-rails-pro/package.json` declared the optional peer `"react-on-rails-rsc": "*"`. The wildcard accepts **any** version — including pre-`19.0.5` builds that lack the RSC CSS FOUC fix, and a future major (`20.x`) — and, because semver `*` never matches prereleases, RC rollouts already require explicit overrides. So `*` provided no convenience while admitting known-bad floors. This replaces `"*"` with an explicit `^19.0.5` (= `>=19.0.5 <20.0.0`): - **Floor `19.0.5`** — the RSC CSS FOUC fix requirement (the stable pin landed in #3634), so pre-FOUC builds are excluded. - **Ceiling `<20.0.0`** — a new `react-on-rails-rsc` major is a deliberate, reviewed bump rather than silently accepted. - Within the `19.x` line (`19.0.x`, `19.2.x`, …), the **actual per-version compatibility gate is the Pro node-renderer runtime version check** (`rscPeerSupport.ts`, which tiers rsc `19.0.x`↔react `19.0.4+` and rsc `19.2.x`↔react `19.2.7+`), not this advisory optional peer range. `^19.0.5` intentionally admits the supported `19.2.x` line so the React 19.2 path isn't blocked by a peer warning. ## No regression to the React 19.2 soak The in-repo Pro/RSC dummy resolves `react-on-rails-rsc@19.2.0-rc.1` (a prerelease) via a direct dependency + pnpm override. Both `"*"` and `^19.0.5` exclude prereleases by semver, so resolution is unchanged: `pnpm install` produces **zero** `react-on-rails-rsc` peer warnings before and after, and `pnpm-lock.yaml` is byte-identical (md5 unchanged). ## Changes - `packages/react-on-rails-pro/package.json`: peer `react-on-rails-rsc` `"*"` → `"^19.0.5"` (stays `optional`; devDependency untouched). - `docs/pro/react-server-components/upgrading-existing-pro-app.md`: note documenting the floor/ceiling meaning and that the runtime version check is the real per-version gate. `llms-full-pro.txt` regenerated to match. - `CHANGELOG.md`: `[Unreleased]` entry. ## Validation (local, all green) - `pnpm run type-check`, `pnpm run lint`, `prettier --check`, `script/check-docs-sidebar`: clean. - Lockfile unchanged; no new peer warnings vs the `"*"` baseline. ## Notes - Builds on #3634 (stable `19.0.5` pin). Will be rebased onto merged #3634 (which flips the install docs from `19.0.5-rc.7` to stable `19.0.5`, so the doc install version matches this `^19.0.5` floor). Fixes #3965  --- > [!NOTE] > **Low Risk** > Metadata and documentation only; optional peer range is advisory and does not change runtime RSC rendering logic. > > **Overview** > Replaces the Pro package’s optional `react-on-rails-rsc` peer dependency from `"*"` with **`^19.0.5`** (`>= 19.0.5 < 20.0.0`), so npm/pnpm installs are advised against pre-FOUC `19.x` builds and against an unreviewed `20.x` major while still allowing supported `19.1+` / `19.2.x` within the line. > > RSC upgrade docs (and regenerated `llms-full-pro.txt`) now separate the **generator’s exact `19.0.5` app pin** from this **broader Pro peer range**, and note that **`rscPeerSupport.ts` runtime checks** remain the real per-version gate. **`CHANGELOG.md`** records the change under `[Unreleased]`. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 09a5c25. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>   ## Summary by CodeRabbit * **Changed** * Updated the Pro package’s optional React Server Components peer dependency from `"*"` to `^19.0.5` (advisory `>= 19.0.5 < 20.0.0`). * **Documentation** * Clarified the reason and expected behavior of the new peer range, including the `19.0.5` minimum, the ceiling before `20.0.0`, and that actual per-Version compatibility is verified through runtime checks rather than the peer range alone.  --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -36,6 +36,7 @@ After a release, run `/update-changelog` in Claude Code to analyze commits, writ
 
 - **[Pro]** **Pinned `react-on-rails-rsc` to the stable `19.0.5` release**: The generator default, the root and Pro package manifests, the lockfile, and the Pro RSC install docs now pin the stable `react-on-rails-rsc@19.0.5` (previously the `19.0.5-rc.7` prerelease). The native RSC CSS FOUC fix requires `react-on-rails-rsc >= 19.0.5`. Closes [Issue 3634](https://github.com/shakacode/react_on_rails/issues/3634). [PR 4080](https://github.com/shakacode/react_on_rails/pull/4080) by [justin808](https://github.com/justin808).
 - **[Pro]** **RSC peer-compatibility warn-tier floor raised to stable `19.0.5`**: The Pro node renderer's `recommendedMin` for `react-on-rails-rsc` is now the published stable `19.0.5` (previously the dormant `19.0.2`). Anyone still on an older 19.x build (`19.0.2`–`19.0.4`) now gets a loud startup warning that they are missing the coordinated RSC fixes shipped in `19.0.5` (FOUC stylesheet preloading, async manifest signatures); `19.0.5`+ no longer warns. Refs [Issue 3632](https://github.com/shakacode/react_on_rails/issues/3632). [PR 4078](https://github.com/shakacode/react_on_rails/pull/4078) by [justin808](https://github.com/justin808).
+- **[Pro]** **RSC peer wildcard replaced with an explicit range**: The Pro npm package's optional `react-on-rails-rsc` peer dependency is now `^19.0.5` (`>= 19.0.5 < 20.0.0`) instead of `"*"`, so installs are floored at the RSC CSS FOUC fix release `19.0.5` and capped below the next major `20.0.0`, rather than `"*"` accepting any version including pre-FOUC builds and an unknown future major. Within the `19.x` line, per-version compatibility is enforced by the Pro node renderer's runtime version check (`rscPeerSupport.ts`), not by this advisory peer range. Fixes [Issue 3965](https://github.com/shakacode/react_on_rails/issues/3965). [PR 4082](https://github.com/shakacode/react_on_rails/pull/4082) by [justin808](https://github.com/justin808).
 
 ### [17.0.0.rc.5] - 2026-06-16
 
diff --git a/docs/pro/react-server-components/upgrading-existing-pro-app.md b/docs/pro/react-server-components/upgrading-existing-pro-app.md
@@ -36,6 +36,11 @@ pnpm add react@~19.0.4 react-dom@~19.0.4 react-on-rails-rsc@19.0.5
 > [!NOTE]
 > The generator pins `react-on-rails-rsc` to exactly `19.0.5` (no `^` or `~`). Because the RSC bundler APIs are version-coupled, record `react-on-rails-rsc` as exactly `19.0.5` in `package.json` rather than the default caret range so a later `19.1.x`/`19.2.x` is not picked up; `react` and `react-dom` stay on `~19.0.4`. This is separate from the Pro package peer metadata tracked in [issue #3609](https://github.com/shakacode/react_on_rails/issues/3609): metadata can allow RSC packages broadly enough for `npm ls`, while the generator still installs the tested exact RSC package pin.
 
+That exact pin is what goes in your app's `package.json`. Separately, the Pro package itself declares an optional peer range, which is broader on purpose:
+
+> [!NOTE]
+> The Pro package's optional `react-on-rails-rsc` peer range is `^19.0.5` (i.e. `>= 19.0.5 < 20.0.0`, see [issue #3965](https://github.com/shakacode/react_on_rails/issues/3965)). This is an advisory range: it sets the **floor** at `19.0.5` (the RSC CSS FOUC fix) and a **ceiling** below the next major `20.0.0` (a new `react-on-rails-rsc` major is a deliberate, reviewed bump). Within the `19.x` line it admits any `>= 19.0.5` release, including `19.1.x` and `19.2.x`; per-version compatibility is enforced not by this range but by the Pro node renderer's runtime version check (`rscPeerSupport.ts`), which tiers `react-on-rails-rsc` `19.0.x` against React `19.0.4+` and `19.2.x` against React `19.2.7+`. Compared to the old `"*"`, this range simply excludes pre-`19.0.5` builds (which lack the FOUC fix) and the unknown next major.
+
 ## Pre-Migration: Audit Components for Client API Usage
 
 Before running the generator, audit your existing components to identify which ones use client-side APIs. When RSC is enabled, any component **without** `'use client'` is automatically classified as a React Server Component. Components that use client APIs will break if misclassified.
diff --git a/llms-full-pro.txt b/llms-full-pro.txt
@@ -7953,6 +7953,11 @@ pnpm add react@~19.0.4 react-dom@~19.0.4 react-on-rails-rsc@19.0.5
 > [!NOTE]
 > The generator pins `react-on-rails-rsc` to exactly `19.0.5` (no `^` or `~`). Because the RSC bundler APIs are version-coupled, record `react-on-rails-rsc` as exactly `19.0.5` in `package.json` rather than the default caret range so a later `19.1.x`/`19.2.x` is not picked up; `react` and `react-dom` stay on `~19.0.4`. This is separate from the Pro package peer metadata tracked in [issue #3609](https://github.com/shakacode/react_on_rails/issues/3609): metadata can allow RSC packages broadly enough for `npm ls`, while the generator still installs the tested exact RSC package pin.
 
+That exact pin is what goes in your app's `package.json`. Separately, the Pro package itself declares an optional peer range, which is broader on purpose:
+
+> [!NOTE]
+> The Pro package's optional `react-on-rails-rsc` peer range is `^19.0.5` (i.e. `>= 19.0.5 < 20.0.0`, see [issue #3965](https://github.com/shakacode/react_on_rails/issues/3965)). This is an advisory range: it sets the **floor** at `19.0.5` (the RSC CSS FOUC fix) and a **ceiling** below the next major `20.0.0` (a new `react-on-rails-rsc` major is a deliberate, reviewed bump). Within the `19.x` line it admits any `>= 19.0.5` release, including `19.1.x` and `19.2.x`; per-version compatibility is enforced not by this range but by the Pro node renderer's runtime version check (`rscPeerSupport.ts`), which tiers `react-on-rails-rsc` `19.0.x` against React `19.0.4+` and `19.2.x` against React `19.2.7+`. Compared to the old `"*"`, this range simply excludes pre-`19.0.5` builds (which lack the FOUC fix) and the unknown next major.
+
 ## Pre-Migration: Audit Components for Client API Usage
 
 Before running the generator, audit your existing components to identify which ones use client-side APIs. When RSC is enabled, any component **without** `'use client'` is automatically classified as a React Server Component. Components that use client APIs will break if misclassified.
diff --git a/packages/react-on-rails-pro/package.json b/packages/react-on-rails-pro/package.json
@@ -87,7 +87,7 @@
   "peerDependencies": {
     "react": ">= 16",
     "react-dom": ">= 16",
-    "react-on-rails-rsc": "*",
+    "react-on-rails-rsc": "^19.0.5",
     "@tanstack/react-router": ">=1.139.0 <2.0.0",
     "ioredis": ">= 5"
   },
