Reduce Rspack RSC dev-server manifest footgun (#4234)

## Summary

Follow-up to #4227 / #4226. The original fix disabled Rspack lazy
compilation for generated RSC apps, but the behavior was still easy for
existing apps to miss and one helper still assumed the RSC config lived
under `config/webpack`.

This PR:

- disables Rspack lazy compilation in generated dev-server config when
an RSC config is present
- makes RSC client-reference discovery check the sibling
`rscWebpackConfig.js` in the active config directory
- adds `react_on_rails:doctor:rsc` diagnostics for existing Rspack RSC
apps whose dev config does not disable lazy compilation
- documents the empty React Client Manifest / `lazy-compilation-proxy` /
`POST /_rspack/lazy/trigger` 404 troubleshooting path
- adds the #4234 changelog entry under Unreleased / Fixed

## Validation

- `cd react_on_rails && bundle exec rspec
spec/react_on_rails/generators/install_generator_spec.rb -e 'disables
Rspack lazy compilation while serving RSC apps' -e 'checks RSC discovery
support in the generated Rspack config directory'`
- `cd react_on_rails && bundle exec rspec
spec/react_on_rails/generators/rsc_generator_spec.rb -e 'when Pro is
installed on an existing rspack project'`
- `cd react_on_rails && bundle exec rspec
spec/react_on_rails/generators/rsc_generator_spec.rb -e 'when an
existing client RSC webpack config already references the scoped
helper'`
- `cd react_on_rails && bundle exec rspec
spec/lib/react_on_rails/doctor_spec.rb -e
'check_rsc_rspack_lazy_compilation' -e 'warns when the Rspack RSC config
supports manifest discovery and the manifest is missing'`
- `bundle exec rubocop react_on_rails/lib/react_on_rails/doctor.rb
react_on_rails/lib/generators/react_on_rails/rsc_setup/client_references.rb
react_on_rails/spec/lib/react_on_rails/doctor_spec.rb
react_on_rails/spec/react_on_rails/generators/install_generator_spec.rb
react_on_rails/spec/react_on_rails/generators/rsc_generator_spec.rb`
- `pnpm start format.listDifferent`
- `git diff --check origin/main...HEAD`
- `script/ci-changes-detector origin/main`
- `/Users/justin/.agents/skills/autoreview/scripts/autoreview --mode
local` clean before push
- pre-push hook: branch RuboCop plus online Markdown link check passed


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **Bug Fixes**
- Improved RSC dev-server diagnostics for Rspack, with warnings when
client lazy compilation isn’t disabled and it may cause an empty React
Client Manifest.
- Updated diagnostics to verify client-reference discovery using the
correct RSC config location.
- Refined RSC + Rspack setup guidance to ensure the Rspack development
config disables client lazy compilation when RSC is present.

- **Documentation**
- Clarified supported locations for RSC bundler configuration for both
webpack and Rspack.
- Expanded RSC troubleshooting with Rspack-specific “empty client
manifest” symptoms and remediation.

- **Tests**
- Updated generator and doctor specs for the revised Rspack/RSC behavior
and diagnostics.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: justin808

CHANGELOG.md

@@ -48,6 +48,18 @@ After a release, run `/update-changelog` in Claude Code to analyze commits, writ
 
 #### Fixed
 
+- **[Pro]** **Rspack RSC dev-server setup is easier to diagnose and customize**:
+  Generated RSC helper code now verifies client-reference discovery support
+  through the sibling `rscWebpackConfig.js` file instead of assuming
+  `config/webpack`, so Rspack apps keep using `config/rspack/rscWebpackConfig.js`.
+  The RSC doctor also warns existing Rspack apps when normal `bin/dev` can leave
+  the React Client Manifest empty because `lazyCompilation` is still enabled,
+  and the troubleshooting guide documents the `lazy-compilation-proxy` /
+  `POST /_rspack/lazy/trigger` 404 symptom path. Follow-up to
+  [PR 4227](https://github.com/shakacode/react_on_rails/pull/4227).
+  [PR 4234](https://github.com/shakacode/react_on_rails/pull/4234) by
+  [justin808](https://github.com/justin808).
+
 - **Precompile hook UTF-8 hardening now handles conflicting `RUBYOPT` encoding flags**:
   The shared Shakapacker precompile hook strips pre-existing Ruby encoding flags such as
   `-EUS-ASCII`, `--encoding=US-ASCII`, `--external-encoding=US-ASCII`, and

docs/oss/api-reference/generator-details.md

@@ -286,7 +286,7 @@ RSC builds on React on Rails Pro's Node rendering infrastructure. The generator
 
 In addition to all Pro files:
 
-- `config/webpack/rscWebpackConfig.js` - RSC-specific webpack configuration
+- `config/webpack/rscWebpackConfig.js` or `config/rspack/rscWebpackConfig.js` - RSC-specific bundler configuration
 - `app/javascript/src/HelloServer/` - Example RSC component (replaces HelloWorld)
 - `app/controllers/hello_server_controller.rb` - Controller with streaming support
 - `app/views/hello_server/index.html.erb` - View using `stream_react_component`

docs/oss/migrating/rsc-troubleshooting.md

@@ -20,6 +20,7 @@ When something goes wrong during RSC migration, start here. This table maps symp
 | `ReferenceError: fetch is not defined` (or `Headers`, `Request`, `Response`, `AbortController`, `AbortSignal`) | Node renderer VM context missing fetch globals                                               | [Node Renderer VM Context](#node-renderer-vm-context----missing-globals)                      |
 | `ReferenceError: require is not defined`                                                                       | Server bundle or RSC bundle uses `externals` for Node builtins instead of `resolve.fallback` | [Handling Node Builtins](#handling-node-builtins----externals-vs-resolvefallback)             |
 | `ReferenceError: MessageChannel is not defined`                                                                | `react-dom/server.browser` needs `MessageChannel` at load time in VM sandbox                 | [MessageChannel Not Defined](#messagechannel-not-defined)                                     |
+| RSC says a module is missing from the React Client Manifest and the manifest is empty in Rspack `bin/dev`      | Rspack lazy compilation deferred RSC client references before the server renderer read them  | [Empty Client Manifest with Rspack Dev Server](#empty-client-manifest-with-rspack-dev-server) |
 | SSR hangs or times out on large pages                                                                          | Stream backpressure deadlock                                                                 | [Stream Backpressure Deadlock](#stream-backpressure-deadlock)                                 |
 | Rails boot error about version mismatch                                                                        | Gem and npm package at different versions                                                    | [Gem and npm Package Version Mismatch](#gem-and-npm-package-version-mismatch)                 |
 | 422 Unprocessable Entity on form submission                                                                    | Missing CSRF token in fetch request                                                          | [Mutations](rsc-data-fetching.md#mutations-rails-controllers-not-server-actions)              |
@@ -774,6 +775,54 @@ class Api::UsersController < ApplicationController
 end
 ```
 
+## Empty Client Manifest with Rspack Dev Server
+
+In RSC apps that use Rspack, normal `bin/dev` dev-server mode must compile RSC client references before the server renderer reads the React Client Manifest. If Rspack lazy compilation is still enabled, the first server render can see an empty manifest and fail with an error like:
+
+```text
+Could not find the module ".../LikeButton.jsx#default" in the React Client Manifest.
+```
+
+Common signs:
+
+- `react-client-manifest.json` contains `"filePathToModuleMetadata": {}`
+- the generated Rspack client bundle mentions `lazy-compilation-proxy`
+- the browser sends `POST /_rspack/lazy/trigger` and Rails returns `404`
+- `bin/dev static` works, but normal `bin/dev` fails
+
+Run the RSC doctor first:
+
+```bash
+bundle exec rails react_on_rails:doctor:rsc
+```
+
+For existing generated apps, update `config/rspack/development.js` so the Rspack dev-server branch disables lazy compilation when an RSC config is present:
+
+```js
+const developmentEnvOnly = (clientWebpackConfig, _serverWebpackConfig, rscWebpackConfig) => {
+  if (process.env.WEBPACK_SERVE) {
+    if (config.assets_bundler === 'rspack') {
+      const { ReactRefreshRspackPlugin } = require('@rspack/plugin-react-refresh');
+      clientWebpackConfig.plugins.push(new ReactRefreshRspackPlugin());
+
+      if (rscWebpackConfig) {
+        clientWebpackConfig.lazyCompilation = false;
+      }
+    }
+  }
+};
+```
+
+Also verify that `config/rspack/ServerClientOrBoth.js` passes the RSC config as the third argument to the environment-specific config hook:
+
+```js
+envSpecific(clientConfig, serverConfig, rscConfig);
+```
+
+If it only passes `clientConfig` and `serverConfig`, rerun the RSC generator to refresh both `ServerClientOrBoth.js` and `development.js`.
+
+Fresh generator output includes this guard. If your config has been heavily customized, keep the important behavior: RSC + Rspack + dev-server mode should set `clientWebpackConfig.lazyCompilation = false`.
+
 ## Bundle Analysis Tools
 
 | Tool                                                                                                                          | Purpose                                                          |
@@ -810,6 +859,7 @@ end
 | `ReferenceError: require is not defined`                                                                                     | Server or RSC bundle webpack config uses `externals` for Node builtins, generating `require()` calls that fail in VM sandbox                                                                       | Use `resolve.fallback: { path: false, fs: false }` instead of `externals`. See [Handling Node Builtins](#handling-node-builtins----externals-vs-resolvefallback)                                                                                                       |
 | `ReferenceError: MessageChannel is not defined`                                                                              | `react-dom/server.browser` instantiates `MessageChannel` at module load time; VM sandbox lacks this global                                                                                         | Inject a `BannerPlugin` polyfill in the server webpack config. See [MessageChannel Not Defined](#messagechannel-not-defined)                                                                                                                                           |
 | `"global object mismatch"`                                                                                                   | `react-on-rails` and `react-on-rails-pro` resolved from different sources (e.g., npm vs yalc)                                                                                                      | Force consistent resolution with `pnpm.overrides` or `yarn.resolutions`. See [Version Mismatch](#version-mismatch----global-object-mismatch)                                                                                                                           |
+| Missing module in React Client Manifest with empty `filePathToModuleMetadata` in Rspack `bin/dev`                            | Rspack lazy compilation deferred RSC client references before manifest generation                                                                                                                  | Disable Rspack lazy compilation for RSC dev-server mode. See [Empty Client Manifest with Rspack Dev Server](#empty-client-manifest-with-rspack-dev-server)                                                                                                             |
 | SSR hangs indefinitely / request timeout on large RSC payloads                                                               | Stream backpressure deadlock when RSC payload exceeds 16 KB                                                                                                                                        | Update to latest React on Rails Pro. See [Stream Backpressure Deadlock](#stream-backpressure-deadlock)                                                                                                                                                                 |
 | `"The 'react-on-rails' package version does not match the gem version"`                                                      | Gem and npm package installed at different versions                                                                                                                                                | Install the npm package version matching your gem. See [Gem and npm Package Version Mismatch](#gem-and-npm-package-version-mismatch)                                                                                                                                   |
 | `"The 'react-on-rails' package version is not an exact version"`                                                             | Using semver ranges (`^`, `~`, `*`) instead of an exact version in package.json                                                                                                                    | Pin to the exact version without range operators. See [Gem and npm Package Version Mismatch](#gem-and-npm-package-version-mismatch)                                                                                                                                    |

docs/pro/installation.md

@@ -91,7 +91,7 @@ bundle exec rails generate react_on_rails:install --rsc
 bundle exec rails generate react_on_rails:rsc
 ```
 
-The RSC generator creates `rscWebpackConfig.js`, adds `RSCWebpackPlugin` to both server and client webpack configs, configures `RSC_BUNDLE_ONLY` handling in `ServerClientOrBoth.js`, and sets up the RSC bundle watcher process. See [React Server Components](./react-server-components/tutorial.md) for more information.
+The RSC generator creates `rscWebpackConfig.js` in the active bundler config directory (`config/webpack/` or `config/rspack/`), adds the RSC bundler plugin to both server and client configs, configures `RSC_BUNDLE_ONLY` handling in `ServerClientOrBoth.js`, and sets up the RSC bundle watcher process. See [React Server Components](./react-server-components/tutorial.md) for more information.
 
 ---
 

react_on_rails/lib/generators/react_on_rails/rsc/USAGE

@@ -6,16 +6,16 @@ Example:
     rails generate react_on_rails:rsc --typescript
 
     This will add:
-    - RSC webpack configuration (config/webpack/rscWebpackConfig.js)
+    - RSC bundler configuration (config/webpack/rscWebpackConfig.js or config/rspack/rscWebpackConfig.js)
     - HelloServer example component
     - HelloServerController and view
     - RSC routes (rsc_payload_route, hello_server)
     - RSC bundle watcher to Procfile.dev
 
 Modifies:
-    - config/webpack/serverWebpackConfig.js (adds RSCWebpackPlugin, rscBundle param)
-    - config/webpack/clientWebpackConfig.js (adds RSCWebpackPlugin)
-    - config/webpack/ServerClientOrBoth.js (adds rscWebpackConfig, RSC_BUNDLE_ONLY)
+    - config/webpack/serverWebpackConfig.js or config/rspack/serverWebpackConfig.js (adds RSC plugin, rscBundle param)
+    - config/webpack/clientWebpackConfig.js or config/rspack/clientWebpackConfig.js (adds RSC plugin)
+    - config/webpack/ServerClientOrBoth.js or config/rspack/ServerClientOrBoth.js (adds rscWebpackConfig, RSC_BUNDLE_ONLY)
     - config/initializers/react_on_rails_pro.rb (adds RSC config block)
     - package.json (adds react-on-rails-rsc)
 

react_on_rails/lib/generators/react_on_rails/rsc_setup/client_references.rb

@@ -156,7 +156,7 @@ def rsc_client_references_js
               };
 
               const rscConfigSupportsDiscovery = () => {
-                const rscWebpackConfig = resolve('config/webpack/rscWebpackConfig.js');
+                const rscWebpackConfig = resolve(__dirname, 'rscWebpackConfig.js');
                 const precompileHook = resolve('bin/shakapacker-precompile-hook');
 
                 return (

react_on_rails/lib/generators/react_on_rails/templates/base/base/config/webpack/development.js.tt

@@ -1,12 +1,10 @@
 <%= add_documentation_reference(config[:message], "// https://github.com/shakacode/react-on-rails-demo-ssr-hmr/blob/master/config/webpack/development.js") %>
 
 const { devServer, inliningCss, config } = require('shakapacker');
-const { existsSync } = require('fs');
-const { resolve } = require('path');
 
 const serverClientOrBoth = require('./ServerClientOrBoth');
 
-const developmentEnvOnly = (clientWebpackConfig, _serverWebpackConfig) => {
+const developmentEnvOnly = (clientWebpackConfig, _serverWebpackConfig, rscWebpackConfig) => {
   // React Refresh (Fast Refresh) setup - only when dev server is running (HMR mode)
   if (process.env.WEBPACK_SERVE) {
     // eslint-disable-next-line global-require
@@ -15,7 +13,7 @@ const developmentEnvOnly = (clientWebpackConfig, _serverWebpackConfig) => {
       const { ReactRefreshRspackPlugin } = require('@rspack/plugin-react-refresh');
       clientWebpackConfig.plugins.push(new ReactRefreshRspackPlugin());
 
-      if (existsSync(resolve(__dirname, 'rscWebpackConfig.js'))) {
+      if (rscWebpackConfig) {
         // RSC client references must be compiled before the server render reads the client manifest.
         clientWebpackConfig.lazyCompilation = false;
       }

react_on_rails/lib/react_on_rails/doctor.rb

@@ -3521,6 +3521,11 @@ def base_package_reference?(content)
     # Keep in sync with RSC_CLIENT_MANIFEST_GUIDANCE in
     # packages/react-on-rails-pro/src/handleErrorRSC.ts.
     RSC_CLIENT_MANIFEST_CLEANUP_PATHS = %w[public/packs public/packs-test ssr-generated .node-renderer-bundles].freeze
+    RSC_RSPACK_CONFIG_FILENAME = "rscWebpackConfig.js"
+    RSC_RSPACK_DEVELOPMENT_CONFIG_FILENAME = "development.js"
+    RSC_RSPACK_CLIENT_LAZY_COMPILATION_DISABLED_PATTERN = /
+      ^\s*clientWebpackConfig\.lazyCompilation\s*=\s*false\b
+    /x
 
     def check_rsc_setup
       unless ReactOnRails::Utils.react_on_rails_pro?
@@ -3543,6 +3548,7 @@ def check_rsc_setup
       check_rsc_renderer_mode(pro_config)
       check_rsc_payload_route
       check_rsc_bundler_config
+      check_rsc_rspack_lazy_compilation
       check_rsc_react_version
       check_rsc_procfile_watcher
       check_rsc_client_manifest
@@ -3615,6 +3621,49 @@ def check_rsc_bundler_config
       end
     end
 
+    def check_rsc_rspack_lazy_compilation
+      return unless active_assets_bundler == "rspack"
+
+      config_directory = rsc_rspack_config_directory
+      return unless config_directory
+
+      rsc_config_path = File.join(config_directory, RSC_RSPACK_CONFIG_FILENAME)
+      return unless File.exist?(rsc_config_path)
+
+      development_config_path = File.join(config_directory, RSC_RSPACK_DEVELOPMENT_CONFIG_FILENAME)
+      unless File.exist?(development_config_path)
+        checker.add_warning("⚠️  RSC Rspack development config not found: #{development_config_path}")
+        checker.add_info("  💡 Cannot verify that Rspack lazyCompilation is disabled for RSC dev-server mode")
+        return
+      end
+
+      development_config = File.read(development_config_path)
+      if development_config.match?(RSC_RSPACK_CLIENT_LAZY_COMPILATION_DISABLED_PATTERN)
+        checker.add_success("✅ Rspack lazy compilation appears disabled for RSC dev-server")
+      else
+        checker.add_warning(<<~MSG.strip)
+          ⚠️  Rspack lazyCompilation can leave the RSC client manifest empty in normal bin/dev mode.
+
+          #{development_config_path} does not appear to disable lazyCompilation while the dev server is running.
+        MSG
+        checker.add_info("  💡 Add this inside the Rspack WEBPACK_SERVE branch:")
+        checker.add_info("     clientWebpackConfig.lazyCompilation = false;")
+        checker.add_info(
+          "  💡 See docs/oss/migrating/rsc-troubleshooting.md#empty-client-manifest-with-rspack-dev-server"
+        )
+      end
+    rescue StandardError => e
+      checker.add_warning("⚠️  Could not inspect RSC Rspack lazyCompilation config: #{e.message}")
+    end
+
+    def rsc_rspack_config_directory
+      explicit_config_path = shakapacker_assets_bundler_config_path
+      return bundler_config_directory(explicit_config_path) if explicit_config_path && File.file?(explicit_config_path)
+
+      default_config_path = ConfigPathResolver::RSPACK_DEFAULT_CONFIG_CANDIDATES.find { |path| File.file?(path) }
+      bundler_config_directory(default_config_path)
+    end
+
     def check_rsc_react_version
       react_version = detect_react_version_from_deps
       unless react_version