Switch SSR to the Pro Node renderer on webpack

Second of three stacked sub-PRs in the Pro RSC migration. Routes all
server rendering through the Pro Node renderer (port 3800) instead of
ExecJS, and flips the asset bundler from rspack to webpack — scoped
reversal of #702, needed because rspack 2.0.0-beta.7's webpack
compatibility layer doesn't cover the APIs upstream RSCWebpackPlugin
requires. We flip back to rspack once shakacode/react_on_rails_rsc#29
ships a native rspack RSC plugin.

The bundler flip and NodeRenderer wiring ship atomically: the server
bundle produced by the Pro webpack transforms (target: 'node' +
libraryTarget: 'commonjs2') is not evaluable by ExecJS, so the
initializer pointing server_renderer at the NodeRenderer must land at
the same time.

Key changes:

- config/shakapacker.yml: assets_bundler: rspack → webpack
- config/webpack/bundlerUtils.js: return @rspack/core or webpack based
  on the shakapacker setting (was rspack-only and threw otherwise);
  spec updated in parallel
- config/webpack/serverWebpackConfig.js: Pro transforms per the :pro
  generator's update_webpack_config_for_pro and the marketplace/dummy
  references — target: 'node' + node: false, libraryTarget:
  'commonjs2', extractLoader helper, babelLoader.options.caller =
  { ssr: true }, destructured module.exports so Sub-PR 3's
  rscWebpackConfig.js can derive from serverWebpackConfig(true).
  RSCWebpackPlugin({ isServer: true }) when !rscBundle emits the
  server manifest; inert until Sub-PR 3 activates RSC support
- config/initializers/react_on_rails_pro.rb: NodeRenderer-only config
  (no RSC fields — those move in Sub-PR 3)
- renderer/node-renderer.js: launcher with strict integer env parsing,
  CI worker cap, and additionalContext: { URL, AbortController } so
  react-router-dom's NavLink.encodeLocation does not throw
  "ReferenceError: URL is not defined" at SSR time
- Procfile.dev: renderer: NODE_ENV=development node renderer/node-renderer.js
- package.json: react-on-rails-pro-node-renderer 16.6.0 and
  react-on-rails-rsc ^19.0.4 (Pro peer dep; required for the
  RSCWebpackPlugin import)
- .gitignore: /renderer/.node-renderer-bundles/
- .env.example: REACT_ON_RAILS_PRO_LICENSE, RENDERER_PASSWORD, and
  REACT_RENDERER_URL with dev vs prod guidance
- .github/workflows/rspec_test.yml: start the Node renderer before
  rspec with PID liveness and port-ready checks plus log capture on
  failure

Verified locally: webpack build compiles cleanly. `bin/rails s` on
3000 with `node renderer/node-renderer.js` on 3800 renders GET /
at HTTP 200; Rails log shows "Node Renderer responded" and the
renderer log emits "[SERVER] RENDERED Footer to dom node with id:
..." — confirming SSR went through the Pro path rather than falling
back to ExecJS.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ihabadham

.env.example

@@ -0,0 +1,18 @@
+# React on Rails Pro license — required in production.
+# Issue a license at https://pro.reactonrails.com/ and paste the JWT token below.
+# Not required in development or test (the Pro engine logs an info notice and
+# continues). Don't commit the real token — copy this file to `.env`, which is
+# gitignored.
+REACT_ON_RAILS_PRO_LICENSE=
+
+# Shared secret between the Rails app and the Node renderer. Must match
+# config.renderer_password in config/initializers/react_on_rails_pro.rb.
+# In production, set this to a strong random value via your secret store.
+# In development, both the renderer and the initializer default to
+# `local-dev-renderer-password` so `bin/dev` works without any setup.
+RENDERER_PASSWORD=
+
+# Node renderer HTTP endpoint. Defaults to http://localhost:3800 in
+# development (where Procfile.dev runs `node renderer/node-renderer.js`).
+# Override in production to point at the deployed renderer host.
+# REACT_RENDERER_URL=http://localhost:3800

.github/workflows/rspec_test.yml

@@ -82,6 +82,27 @@ jobs:
       - name: Build shakapacker chunks
         run: NODE_ENV=development bundle exec bin/shakapacker
 
+      - name: Start Node renderer for SSR
+        run: |
+          node renderer/node-renderer.js > /tmp/node-renderer.log 2>&1 &
+          RENDERER_PID=$!
+          echo "Waiting for Node renderer (PID $RENDERER_PID) on port 3800..."
+          for i in $(seq 1 30); do
+            if ! kill -0 $RENDERER_PID 2>/dev/null; then
+              echo "Node renderer process exited unexpectedly. Log output:"
+              cat /tmp/node-renderer.log
+              exit 1
+            fi
+            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. Log output:"
+          cat /tmp/node-renderer.log
+          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/
 
+# Pro Node renderer bundle cache
+/renderer/.node-renderer-bundles/
+
 # Generated React on Rails packs
 **/generated/**
 

Procfile.dev

@@ -10,5 +10,7 @@ rescript: yarn res:watch
 rails: bundle exec thrust bin/rails server -p 3000
 # Client Rspack dev server with HMR
 wp-client: RAILS_ENV=development NODE_ENV=development bin/shakapacker-dev-server
-# Server Rspack watcher for SSR bundle
+# Server webpack watcher for SSR bundle
 wp-server: SERVER_BUNDLE_ONLY=yes bin/shakapacker --watch
+# Pro Node renderer — executes the server bundle for SSR (port 3800)
+renderer: NODE_ENV=development node renderer/node-renderer.js

client/__tests__/webpack/bundlerUtils.spec.js

@@ -1,7 +1,9 @@
 /* eslint-disable max-classes-per-file */
 /* eslint-disable global-require */
 /**
- * Unit tests for bundlerUtils.js in Rspack-only mode.
+ * Unit tests for bundlerUtils.js. The utility returns the active bundler
+ * module based on shakapacker.yml's `assets_bundler` setting; it supports
+ * both webpack and rspack.
  */
 
 jest.mock('@rspack/core', () => ({
@@ -10,12 +12,18 @@ jest.mock('@rspack/core', () => ({
   optimize: { LimitChunkCountPlugin: class MockRspackLimitChunkCount {} },
 }));
 
+jest.mock('webpack', () => ({
+  ProvidePlugin: class MockWebpackProvidePlugin {},
+  DefinePlugin: class MockWebpackDefinePlugin {},
+  optimize: { LimitChunkCountPlugin: class MockWebpackLimitChunkCount {} },
+}));
+
 describe('bundlerUtils', () => {
   let mockConfig;
 
   beforeEach(() => {
     jest.resetModules();
-    mockConfig = { assets_bundler: 'rspack' };
+    mockConfig = { assets_bundler: 'webpack' };
   });
 
   afterEach(() => {
@@ -35,32 +43,30 @@ describe('bundlerUtils', () => {
       expect(bundler.CssExtractRspackPlugin.name).toBe('MockCssExtractRspackPlugin');
     });
 
-    it('throws when assets_bundler is webpack', () => {
+    it('returns webpack when assets_bundler is webpack', () => {
       mockConfig.assets_bundler = 'webpack';
       jest.doMock('shakapacker', () => ({ config: mockConfig }));
       const utils = require('../../../config/webpack/bundlerUtils');
 
-      expect(() => utils.getBundler()).toThrow('configured for Rspack only');
+      const bundler = utils.getBundler();
+
+      expect(bundler).toBeDefined();
+      expect(bundler.DefinePlugin).toBeDefined();
+      expect(bundler.DefinePlugin.name).toBe('MockWebpackDefinePlugin');
     });
 
-    it('throws when assets_bundler is undefined', () => {
+    it('returns webpack when assets_bundler is undefined', () => {
       mockConfig.assets_bundler = undefined;
       jest.doMock('shakapacker', () => ({ config: mockConfig }));
       const utils = require('../../../config/webpack/bundlerUtils');
 
-      expect(() => utils.getBundler()).toThrow('configured for Rspack only');
-    });
-
-    it('throws when assets_bundler is invalid', () => {
-      mockConfig.assets_bundler = 'invalid-bundler';
-      jest.doMock('shakapacker', () => ({ config: mockConfig }));
-      const utils = require('../../../config/webpack/bundlerUtils');
+      const bundler = utils.getBundler();
 
-      expect(() => utils.getBundler()).toThrow('configured for Rspack only');
+      expect(bundler.DefinePlugin).toBeDefined();
     });
 
     it('returns cached bundler on subsequent calls', () => {
-      mockConfig.assets_bundler = 'rspack';
+      mockConfig.assets_bundler = 'webpack';
       jest.doMock('shakapacker', () => ({ config: mockConfig }));
       const utils = require('../../../config/webpack/bundlerUtils');
 
@@ -106,7 +112,7 @@ describe('bundlerUtils', () => {
       jest.doMock('shakapacker', () => ({ config: mockConfig }));
       const utils = require('../../../config/webpack/bundlerUtils');
 
-      expect(() => utils.getCssExtractPlugin()).toThrow('configured for Rspack only');
+      expect(() => utils.getCssExtractPlugin()).toThrow('only available when assets_bundler is rspack');
     });
   });
 });

config/initializers/react_on_rails_pro.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# See https://reactonrails.com/docs/configuration/configuration-pro
+# Production license: set REACT_ON_RAILS_PRO_LICENSE to the JWT token from
+# https://pro.reactonrails.com/. Development and test environments don't
+# require a license — the Pro engine logs an info-level notice only.
+ReactOnRailsPro.configure do |config|
+  # Route all server rendering through the Pro Node renderer (port 3800).
+  # Falling back to ExecJS is disabled so any renderer issue surfaces loudly
+  # instead of silently degrading.
+  config.server_renderer = "NodeRenderer"
+  config.renderer_use_fallback_exec_js = false
+
+  # Renderer HTTP endpoint. The Node renderer listens on localhost:3800 in
+  # development; override REACT_RENDERER_URL in production to point at the
+  # deployed renderer host.
+  config.renderer_url = ENV.fetch("REACT_RENDERER_URL", "http://localhost:3800")
+
+  # Shared secret for renderer authentication. Must match renderer/node-renderer.js.
+  # In production, set RENDERER_PASSWORD to a strong value via your secret store.
+  # The shared dev default keeps the launcher and initializer in sync locally
+  # so `bin/dev` just works.
+  config.renderer_password = ENV.fetch("RENDERER_PASSWORD", "local-dev-renderer-password")
+end

config/shakapacker.yml

@@ -9,7 +9,13 @@ default: &default
   webpack_compile_output: true
   nested_entries: true
   javascript_transpiler: swc
-  assets_bundler: rspack
+  # Tactical: running on webpack during the Pro RSC migration. The project will
+  # flip back to rspack once react_on_rails_rsc ships a native rspack RSC plugin
+  # (tracked at shakacode/react_on_rails_rsc#29). The rspack 2.0.0-beta.7 webpack
+  # compatibility layer doesn't cover the APIs the upstream webpack RSC plugin
+  # requires (contextModuleFactory.resolveDependencies, ModuleDependency), so the
+  # upstream RSCWebpackPlugin can't run on rspack yet.
+  assets_bundler: webpack
 
   # Additional paths webpack should lookup modules
   # ['app/assets', 'engine/foo/app/assets']

config/webpack/bundlerUtils.js

@@ -1,38 +1,24 @@
 /**
- * Bundler utilities for Rspack-only configuration.
- *
- * This repository standardizes on Rspack with Shakapacker.
+ * Bundler utilities. Returns the active bundler module based on shakapacker.yml's
+ * `assets_bundler` setting. Supports both webpack and rspack so this project can
+ * switch between them without touching every config file.
  */
 
 const { config } = require('shakapacker');
 
-// Cache for bundler module
 let _cachedBundler = null;
 
-const ensureRspack = () => {
-  if (config.assets_bundler !== 'rspack') {
-    throw new Error(
-      `Invalid assets_bundler: "${config.assets_bundler}". ` +
-        'This project is configured for Rspack only. ' +
-        'Set assets_bundler: rspack in config/shakapacker.yml',
-    );
-  }
-};
-
 /**
- * Gets the Rspack module for the current build.
+ * Gets the bundler module for the current build.
  *
- * @returns {Object} @rspack/core module
- * @throws {Error} If assets_bundler is not 'rspack'
+ * @returns {Object} webpack or @rspack/core module
  */
 const getBundler = () => {
-  ensureRspack();
-
   if (_cachedBundler) {
     return _cachedBundler;
   }
 
-  _cachedBundler = require('@rspack/core');
+  _cachedBundler = config.assets_bundler === 'rspack' ? require('@rspack/core') : require('webpack');
 
   return _cachedBundler;
 };
@@ -45,11 +31,21 @@ const getBundler = () => {
 const isRspack = () => config.assets_bundler === 'rspack';
 
 /**
- * Gets the CSS extraction plugin for Rspack.
+ * Gets the CSS extraction plugin. Only meaningful on rspack — webpack projects
+ * use mini-css-extract-plugin directly via shakapacker's generated config.
  *
  * @returns {Object} CssExtractRspackPlugin
+ * @throws {Error} If assets_bundler is not rspack
  */
-const getCssExtractPlugin = () => getBundler().CssExtractRspackPlugin;
+const getCssExtractPlugin = () => {
+  if (!isRspack()) {
+    throw new Error(
+      'getCssExtractPlugin() is only available when assets_bundler is rspack. ' +
+        "On webpack, rely on shakapacker's generated MiniCssExtractPlugin configuration.",
+    );
+  }
+  return getBundler().CssExtractRspackPlugin;
+};
 
 module.exports = {
   getBundler,