Fix SSR runtime failures for React Server Components

.github/workflows/rspec_test.yml

@@ -33,6 +33,7 @@ jobs:
       DRIVER: selenium_chrome
       CHROME_BIN: /usr/bin/google-chrome
       USE_COVERALLS: true
+      RENDERER_PASSWORD: devPassword
 
     steps:
       - name: Install Chrome
@@ -82,6 +83,20 @@ jobs:
       - name: Build shakapacker chunks
         run: NODE_ENV=development bundle exec bin/shakapacker
 
+      - name: Start Node renderer for SSR
+        run: |
+          node react-on-rails-pro-node-renderer.js &
+          echo "Waiting for Node renderer on port 3800..."
+          for i in $(seq 1 30); do
+            if nc -z localhost 3800 2>/dev/null; then
+              echo "Node renderer is ready"
+              exit 0
+            fi
+            sleep 1
+          done
+          echo "Node renderer failed to start within 30 seconds"
+          exit 1
+
       - name: Run rspec with xvfb
         uses: coactions/setup-xvfb@v1
         with:

.gitignore

@@ -57,6 +57,9 @@ client/app/bundles/comments/rescript/**/*.bs.js
 # Using React on Rails default directory
 /ssr-generated/
 
+# Node renderer bundle cache
+.node-renderer-bundles/
+
 # Generated React on Rails packs
 **/generated/**
 

CLAUDE.md

@@ -16,6 +16,76 @@ bundle exec rubocop
 bundle exec rubocop -a
 ```
 
+## Architecture: Three Bundle System
+
+This project builds **three separate Rspack bundles** via Shakapacker:
+
+| Bundle | Config | Output | Runtime |
+|--------|--------|--------|---------|
+| **Client** | `clientWebpackConfig.js` | `public/packs/` | Browser |
+| **Server (SSR)** | `serverWebpackConfig.js` | `ssr-generated/` | Node renderer VM sandbox |
+| **RSC** | `rscWebpackConfig.js` | RSC output dir | Node renderer (full Node.js) |
+
+### Key constraints
+
+- The **server bundle runs in a VM sandbox** (`vm.createContext()`), NOT full Node.js. It lacks `require`, `MessageChannel`, `TextEncoder`, and other Node/browser globals.
+- Use `resolve.fallback: false` (NOT `externals`) for Node builtins in the server bundle — the VM has no `require()`, so externalized `require('path')` calls will crash.
+- The **RSC bundle** targets Node.js directly with the `react-server` condition, so Node builtins work normally there.
+- A `BannerPlugin` injects a `MessageChannel` polyfill into the server bundle because `react-dom/server.browser` needs it at module load time.
+
+### Build commands
+
+```bash
+# Build only the server bundle
+SERVER_BUNDLE_ONLY=yes bin/shakapacker
+
+# Build only the RSC bundle
+RSC_BUNDLE_ONLY=true bin/shakapacker
+
+# Watch modes (used by Procfile.dev)
+SERVER_BUNDLE_ONLY=yes bin/shakapacker --watch
+RSC_BUNDLE_ONLY=true bin/shakapacker --watch
+```
+
+## Node Renderer
+
+React on Rails Pro's NodeRenderer must be running for SSR and RSC payload generation.
+
+- **Port**: 3800 (configured in `config/initializers/react_on_rails_pro.rb`)
+- **Launcher**: `node react-on-rails-pro-node-renderer.js`
+- **Auth**: Requires `RENDERER_PASSWORD` env var (defaults to `local-dev-renderer-password` in dev/test, required with no fallback in production)
+- **Started automatically** by `bin/dev` / `Procfile.dev`
+
+### Testing requirement
+
+**The Node renderer must be running before `bundle exec rspec`.** Tests will fail with `Net::ReadTimeout` if it is not running. CI starts it as a background process and waits up to 30 seconds for TCP readiness on port 3800.
+
+### Enabled environments
+
+The renderer is enabled when `Rails.env.local?` (development + test) or `REACT_USE_NODE_RENDERER=true`. Production requires explicit env var configuration.
+
+## RSC Component Classification
+
+React on Rails Pro auto-classifies components based on the `'use client'` directive:
+
+- **With `'use client'`** → registered via `ReactOnRails.register()` (traditional SSR/client component)
+- **Without `'use client'`** → registered via `registerServerComponent()` (React Server Component)
+
+### Common gotcha: `.server.jsx` files
+
+In this codebase, `.server.jsx` does NOT mean "React Server Component" — it means traditional **server-side rendering** (e.g., `StaticRouter`). If a `.server.jsx` file uses client APIs like `ReactOnRails.getStore()` or React hooks, it **needs** the `'use client'` directive to prevent RSC misclassification. The naming predates RSC and refers to the Rails SSR render path.
+
+### Key files
+
+| File | Purpose |
+|------|---------|
+| `config/webpack/rscWebpackConfig.js` | RSC bundle configuration |
+| `config/webpack/rspackRscPlugin.js` | Detects `'use client'` directives, emits React Flight manifests |
+| `client/app/packs/rsc-bundle.js` | RSC entry point |
+| `client/app/packs/rsc-client-components.js` | Client component registration for RSC |
+| `config/initializers/react_on_rails_pro.rb` | Node renderer + RSC configuration |
+| `react-on-rails-pro-node-renderer.js` | Node renderer launcher |
+
 ## Conductor Compatibility (Version Managers)
 
 ### Problem

Gemfile

@@ -5,7 +5,7 @@ git_source(:github) { |repo| "https://github.com/#{repo}.git" }
 
 ruby "3.4.6"
 
-gem "react_on_rails", "16.6.0.rc.0"
+gem "react_on_rails_pro", "16.6.0.rc.0"
 gem "shakapacker", "10.0.0.rc.0"
 
 # Bundle edge Rails instead: gem "rails", github: "rails/rails"