react_on_rails 16.6.0 → 16.7.0.rc.0

data/lib/generators/react_on_rails/pro_setup.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "generator_messages"
+require "react_on_rails/pro_migration"
 
 module ReactOnRails
   module Generators
@@ -33,7 +34,7 @@ module ReactOnRails
       #
       # Creates:
       # - config/initializers/react_on_rails_pro.rb
-      # - client/node-renderer.js
+      # - renderer/node-renderer.js
       # - Procfile.dev entry for node-renderer
       #
       # @note NPM dependencies are handled separately by JsDependencyManager
@@ -43,8 +44,8 @@ module ReactOnRails
         say set_color("=" * 80, :cyan)
 
         create_pro_initializer
-        create_node_renderer
-        add_pro_to_procfile
+        legacy_renderer_detected = create_node_renderer
+        add_pro_to_procfile unless legacy_renderer_detected
         update_webpack_config_for_pro
 
         say set_color("=" * 80, :cyan)
@@ -52,22 +53,26 @@ module ReactOnRails
         say set_color("=" * 80, :cyan)
       end
 
-      # Check if Pro gem is missing. Attempts auto-install via bundle add.
+      # Check if the Pro gem is missing. When the base react_on_rails gem is in
+      # the Gemfile, installation is deferred to the later Gemfile swap (which
+      # preserves the user's version pin); otherwise auto-install via `bundle
+      # add` is attempted.
       # @param force [Boolean] When true, always checks (default: only if use_pro?).
-      # @return [Boolean] true if Pro gem is missing and could not be installed
+      # @return [Boolean] true only if the Pro gem is missing and could not be
+      #   installed; false if it is present, was auto-installed, or the install
+      #   is deferred to the Gemfile swap.
       def missing_pro_gem?(force: false)
         return false unless force || use_pro?
         return false if pro_gem_installed?
+        return false if defer_pro_gem_install_to_gemfile_swap
         return false if attempt_pro_gem_auto_install
 
-        context_line = pro_gem_requirement_context_line
-        prerelease_note = rsc_pro_prerelease_note
+        optional_prerelease_line = prerelease_note.empty? ? "" : "\n#{prerelease_note}"
 
         GeneratorMessages.add_error(<<~MSG.strip)
           🚫 Failed to auto-install #{PRO_GEM_NAME} gem.
 
-          #{context_line}
-          #{prerelease_note}
+          #{pro_gem_requirement_context_line}#{optional_prerelease_line}
 
           Please add manually to your Gemfile:
             gem '#{PRO_GEM_NAME}', '#{pro_gem_version_requirement}'
@@ -94,20 +99,16 @@ module ReactOnRails
       end
 
       def pro_requirement_flag
-        return "--rsc-pro" if use_rsc_pro_mode?
         return "--rsc" if options[:rsc]
 
         "--pro"
       end
 
-      def rsc_pro_prerelease_note
-        return "" unless use_rsc_pro_mode?
-        return "" unless Gem::Version.new(ReactOnRails::VERSION).prerelease?
+      def prerelease_note
+        return "" unless prerelease_ror_version?
 
         "Note: #{PRO_GEM_NAME} #{ReactOnRails::VERSION} may not be published yet. " \
           "If you are testing from source, use a local Gemfile `path:` option."
-      rescue ArgumentError
-        ""
       end
 
       # Attempt to auto-install the Pro gem via bundle add.
@@ -210,23 +211,65 @@ module ReactOnRails
         say "✅ Created #{initializer_path}", :green
       end
 
+      # Matches active (uncommented) Procfile.dev node-renderer lines, tolerating
+      # an optional `./` prefix that a user may have added by hand
+      # (e.g. `node ./renderer/node-renderer.js`).
+      NEW_RENDERER_COMMAND_REGEX = %r{^[ \t]*node-renderer:[^\n]*\bnode\s+\.?/?renderer/node-renderer\.js\b}
+      LEGACY_RENDERER_COMMAND_REGEX = %r{^[ \t]*node-renderer:[^\n]*\bnode\s+\.?/?client/node-renderer\.js\b}
+
+      # Creates renderer/node-renderer.js unless either the new path or the legacy
+      # client/node-renderer.js already exists.
+      #
+      # @return [Boolean] true when a legacy client/node-renderer.js was detected
+      #   (caller should skip add_pro_to_procfile to avoid pointing Procfile.dev
+      #   at a file that wasn't created); false otherwise.
       def create_node_renderer
-        node_renderer_path = "client/node-renderer.js"
+        node_renderer_path = "renderer/node-renderer.js"
+        legacy_node_renderer_path = "client/node-renderer.js"
 
         if File.exist?(File.join(destination_root, node_renderer_path))
           say "ℹ️  #{node_renderer_path} already exists, skipping", :yellow
-          return
+          return false
+        end
+
+        if File.exist?(File.join(destination_root, legacy_node_renderer_path))
+          say "ℹ️  #{legacy_node_renderer_path} detected, keeping existing renderer; " \
+              "to migrate, move it to #{node_renderer_path} and update any references " \
+              "(e.g. Procfile.dev, Procfile.prod, Docker CMD / command):", :yellow
+          say "      node-renderer: RENDERER_LOG_LEVEL=debug RENDERER_PORT=${RENDERER_PORT:-3800} " \
+              "node #{node_renderer_path}", :yellow
+          warn_on_stale_legacy_procfile_entry
+          return true
         end
 
         say "📝 Creating Node Renderer bootstrap...", :yellow
 
-        # Ensure client directory exists
-        FileUtils.mkdir_p(File.join(destination_root, "client"))
+        empty_directory("renderer")
 
-        template_path = "templates/pro/base/client/node-renderer.js"
+        template_path = "templates/pro/base/renderer/node-renderer.js"
         copy_file(template_path, node_renderer_path)
 
         say "✅ Created #{node_renderer_path}", :green
+        false
+      end
+
+      # When a legacy client/node-renderer.js is detected, add_pro_to_procfile is
+      # skipped, so surface a pointed warning if Procfile.dev still launches the
+      # legacy entry. This nudges the user to update the exact line they need to
+      # touch rather than leaving them to diff the generic migration hint against
+      # their Procfile themselves.
+      def warn_on_stale_legacy_procfile_entry
+        procfile_path = File.join(destination_root, "Procfile.dev")
+        return unless File.exist?(procfile_path)
+
+        procfile_content = File.read(procfile_path)
+        return unless procfile_content.match?(LEGACY_RENDERER_COMMAND_REGEX)
+
+        GeneratorMessages.add_warning(<<~MSG.strip)
+          ⚠️  Procfile.dev still launches the legacy client/node-renderer.js.
+          After migrating the renderer file, update that line to:
+            node-renderer: RENDERER_LOG_LEVEL=debug RENDERER_PORT=${RENDERER_PORT:-3800} node renderer/node-renderer.js
+        MSG
       end
 
       def add_pro_to_procfile
@@ -237,22 +280,32 @@ module ReactOnRails
             ⚠️  Procfile.dev not found. Skipping Node Renderer process addition.
 
             You'll need to add the Node Renderer to your process manager manually:
-              node-renderer: RENDERER_LOG_LEVEL=debug RENDERER_PORT=3800 node client/node-renderer.js
+              node-renderer: RENDERER_LOG_LEVEL=debug RENDERER_PORT=${RENDERER_PORT:-3800} node renderer/node-renderer.js
           MSG
           return
         end
 
-        if File.read(procfile_path).include?("node-renderer:")
+        procfile_content = File.read(procfile_path)
+
+        if procfile_content.match?(NEW_RENDERER_COMMAND_REGEX)
           say "ℹ️  Node Renderer already in Procfile.dev, skipping", :yellow
           return
         end
 
+        if procfile_content.match?(/^[ \t]*node-renderer:/)
+          say "⚠️  Procfile.dev has a node-renderer: entry that doesn't reference " \
+              "renderer/node-renderer.js. Update it manually to:", :yellow
+          say "      node-renderer: RENDERER_LOG_LEVEL=debug RENDERER_PORT=${RENDERER_PORT:-3800} " \
+              "node renderer/node-renderer.js", :yellow
+          return
+        end
+
         say "📝 Adding Node Renderer to Procfile.dev...", :yellow
 
         node_renderer_line = <<~PROCFILE
 
           # React on Rails Pro - Node Renderer for SSR
-          node-renderer: RENDERER_LOG_LEVEL=debug RENDERER_PORT=3800 node client/node-renderer.js
+          node-renderer: RENDERER_LOG_LEVEL=debug RENDERER_PORT=${RENDERER_PORT:-3800} node renderer/node-renderer.js
         PROCFILE
 
         append_to_file("Procfile.dev", node_renderer_line)
@@ -486,14 +539,37 @@ module ReactOnRails
         "bundle add #{PRO_GEM_NAME} --version='#{pro_gem_version_requirement}' --strict"
       end
 
+      def defer_pro_gem_install_to_gemfile_swap
+        return false unless base_react_on_rails_gem_in_gemfile?
+
+        mark_pro_gem_installed!
+        true
+      end
+
+      def base_react_on_rails_gem_in_gemfile?
+        gemfile_path = File.join(destination_root, "Gemfile")
+        return false unless File.exist?(gemfile_path)
+
+        ReactOnRails::ProMigration.base_gem_entry?(File.read(gemfile_path))
+      rescue SystemCallError, IOError
+        false
+      end
+
       def pro_gem_version_requirement
-        # RSC Pro uses exact pinning so the Pro gem version always matches the
-        # paired RSC package version generated in the same run.
-        return ReactOnRails::VERSION if use_rsc_pro_mode?
+        # Prerelease gem versions need an exact pin: Bundler's pessimistic operator
+        # (~>) does not match prerelease versions, so a stable range would fail to
+        # install during prerelease cycles.
+        return ReactOnRails::VERSION if prerelease_ror_version?
 
         "~> #{recommended_pro_gem_version}"
       end
 
+      def prerelease_ror_version?
+        Gem::Version.new(ReactOnRails::VERSION).prerelease?
+      rescue ArgumentError
+        false
+      end
+
       # Keep manual fallback pinned to the latest stable release (drop pre-release suffixes like .rc.N).
       # react_on_rails_pro follows the same version number as react_on_rails by policy.
       # Both gems are released in lockstep; if this ever changes, replace with a dedicated constant.

data/lib/generators/react_on_rails/react_with_redux_generator.rb

@@ -104,7 +104,7 @@ module ReactOnRails
         # Fallback to package manager detection if GeneratorHelper fails
         return if success
 
-        package_manager = GeneratorMessages.detect_package_manager
+        package_manager = GeneratorMessages.detect_package_manager(app_root: destination_root)
         return unless package_manager
 
         install_packages_with_fallback(regular_packages, dev: false, package_manager: package_manager)
@@ -116,7 +116,8 @@ module ReactOnRails
         # Append Redux-specific post-install instructions
         GeneratorMessages.add_info(
           GeneratorMessages.helpful_message_after_installation(component_name: "HelloWorldApp", route: "hello_world",
-                                                               pro: Gem.loaded_specs.key?("react_on_rails_pro"))
+                                                               pro: Gem.loaded_specs.key?("react_on_rails_pro"),
+                                                               app_root: destination_root)
         )
       end
 

data/lib/generators/react_on_rails/templates/base/base/.env.example

@@ -7,12 +7,37 @@
 # Shakapacker reads SHAKAPACKER_DEV_SERVER_PORT on both the Ruby (proxy) and
 # JS (webpack-dev-server) sides, so no shakapacker.yml changes are needed.
 #
+# === Coding Agent / CI Integration ===
+# Set REACT_ON_RAILS_BASE_PORT to derive all ports from a single value.
+# This works with any tool (Conductor.build, Codex, Quad Code, etc.).
+# Ports are assigned as: Rails = base+0, webpack = base+1, renderer = base+2.
+# When set, no manual port configuration is needed.
+#
+# Conductor.build sets CONDUCTOR_PORT automatically, which is recognized
+# as a fallback when REACT_ON_RAILS_BASE_PORT is not set.
+#
+# === Manual Worktree Setup ===
 # Example for a second worktree:
 #   PORT=3001
 #   SHAKAPACKER_DEV_SERVER_PORT=3036
+#   RENDERER_PORT=3801                        # React on Rails Pro only
+#   REACT_RENDERER_URL=http://localhost:3801   # Must match RENDERER_PORT
+
+# Base port for coding agent tools (derives all other ports automatically)
+# REACT_ON_RAILS_BASE_PORT=
 
 # Rails server port (default: 3000 for Procfile.dev / 3001 for Procfile.dev-prod-assets)
 # PORT=3000
 
 # Webpack dev server port (default: 3035, used by shakapacker)
 # SHAKAPACKER_DEV_SERVER_PORT=3035
+
+# Node renderer port (React on Rails Pro only, default: 3800)
+# RENDERER_PORT=3800
+
+# Node renderer URL (React on Rails Pro only, must match RENDERER_PORT).
+# If you set only RENDERER_PORT, bin/dev auto-derives
+# REACT_RENDERER_URL=http://localhost:RENDERER_PORT. For a remote or
+# non-localhost renderer (Docker service name, remote host), set
+# REACT_RENDERER_URL explicitly so it is not replaced with the localhost default.
+# REACT_RENDERER_URL=http://localhost:3800

data/lib/generators/react_on_rails/templates/base/base/.github/workflows/ci.yml.tt

@@ -0,0 +1,86 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          # ruby-version: "3.3"  # Uncomment and set if you don't have a .ruby-version file
+          bundler-cache: true
+
+<%- if config[:package_manager] == 'pnpm' -%>
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+<%- unless config[:pnpm_version_declared] -%>
+        with:
+          # ⚠️ Verify this matches the pnpm major that wrote your pnpm-lock.yaml —
+          # major mismatches can silently change dependency resolution. To manage
+          # the version via Corepack instead, add `"packageManager": "pnpm@<exact-version>"`
+          # to package.json and remove this `with:` block. Range/tag specs (e.g. `pnpm@^10`,
+          # `pnpm@latest`) are non-reproducible and some Corepack versions reject them.
+          version: "<%= config[:pnpm_fallback_version] %>"
+<%- end -%>
+<%- end -%>
+<%- if config[:package_manager] == 'bun' -%>
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@v2
+
+<%- end -%>
+<%- if config[:package_manager] == 'yarn' -%>
+      - name: Enable Corepack
+        # Must run before actions/setup-node so its `cache: "yarn"` step
+        # can resolve Yarn Berry's cache directory correctly.
+        run: corepack enable
+
+<%- end -%>
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          # "lts/*" tracks the current Node LTS; consider pinning (e.g. "22") for reproducible builds.
+          node-version: "lts/*"
+<%- if config[:has_lockfile] && %w[yarn pnpm npm].include?(config[:package_manager]) -%>
+          cache: "<%= config[:package_manager] %>"
+<%- end -%>
+
+      - name: Install JS dependencies
+<%- if !config[:has_lockfile] && config[:package_manager] == 'yarn' -%>
+        # Yarn Berry defaults to immutable installs; allow lockfile creation on first CI run.
+        run: yarn install --no-immutable
+<%- elsif !config[:has_lockfile] && config[:package_manager] == 'pnpm' -%>
+        # pnpm defaults to frozen-lockfile in CI; allow lockfile creation on first CI run.
+        run: pnpm install --no-frozen-lockfile
+<%- else -%>
+        run: <%= config[:package_manager] %> install
+<%- end -%>
+
+<%- if config[:has_active_record] -%>
+      - name: Set up database
+        # If using PostgreSQL or MySQL, add a services block above.
+        # See https://docs.github.com/en/actions/using-containerized-services
+        run: bin/rails db:prepare
+        env:
+          RAILS_ENV: test
+
+<%- end -%>
+      - name: Build JavaScript bundles
+        # Shakapacker default. ViteRuby users: replace with `bin/vite build --mode test`.
+        run: bin/shakapacker
+        env:
+          RAILS_ENV: test
+          NODE_ENV: test
+
+      - name: Run tests
+        run: <%= config[:has_rspec] ? "bundle exec rspec" : "bin/rails test" %>
+        env:
+          RAILS_ENV: test

data/lib/generators/react_on_rails/templates/base/base/Procfile.dev

@@ -1,9 +1,10 @@
 # Procfile for development
 # You can run these commands in separate shells
 #
-# To run multiple worktrees simultaneously, set different ports in each worktree's .env:
-#   PORT=3001
-#   SHAKAPACKER_DEV_SERVER_PORT=3036
+# PORT, SHAKAPACKER_DEV_SERVER_PORT, and renderer ports are set automatically by
+# bin/dev when REACT_ON_RAILS_BASE_PORT (or CONDUCTOR_PORT) is present, so
+# concurrent worktrees get distinct ports without manual .env edits.
+# For manual worktree setup (no base-port tool), see .env.example.
 rails: bundle exec rails s -p ${PORT:-3000}
 dev-server: bin/shakapacker-dev-server
 server-bundle: SERVER_BUNDLE_ONLY=true bin/shakapacker-watch --watch

data/lib/generators/react_on_rails/templates/base/base/babel.config.js.tt

@@ -1,4 +1,4 @@
-<%= add_documentation_reference(config[:message], "// https://github.com/shakacode/react_on_rails_demo_ssr_hmr/blob/master/babel.config.js") %>
+<%= add_documentation_reference(config[:message], "// https://github.com/shakacode/react-on-rails-demo-ssr-hmr/blob/master/babel.config.js") %>
 
 module.exports = function (api) {
   const defaultConfigFunc = require('shakapacker/package/babel/preset.js')

data/lib/generators/react_on_rails/templates/base/base/bin/switch-bundler

@@ -15,8 +15,8 @@ class BundlerSwitcher
   }.freeze
 
   RSPACK_DEPS = {
-    dependencies: %w[@rspack/core@^1.0.0 rspack-manifest-plugin@^5.0.0],
-    dev_dependencies: %w[@rspack/cli@^1.0.0 @rspack/plugin-react-refresh@^1.0.0]
+    dependencies: %w[@rspack/core@^2.0.0-0 rspack-manifest-plugin@^5.0.0],
+    dev_dependencies: %w[@rspack/cli@^2.0.0-0 @rspack/plugin-react-refresh@^2.0.0]
   }.freeze
 
   def initialize(target_bundler)

data/lib/generators/react_on_rails/templates/base/base/config/webpack/ServerClientOrBoth.js.tt

@@ -1,4 +1,4 @@
-<%= add_documentation_reference(config[:message], "// https://github.com/shakacode/react_on_rails_demo_ssr_hmr/blob/master/config/webpack/ServerClientOrBoth.js") %>
+<%= add_documentation_reference(config[:message], "// https://github.com/shakacode/react-on-rails-demo-ssr-hmr/blob/master/config/webpack/ServerClientOrBoth.js") %>
 
 const clientWebpackConfig = require('./clientWebpackConfig');
 <% if use_pro? -%>

data/lib/generators/react_on_rails/templates/base/base/config/webpack/clientWebpackConfig.js.tt

@@ -1,4 +1,4 @@
-<%= add_documentation_reference(config[:message], "// https://github.com/shakacode/react_on_rails_demo_ssr_hmr/blob/master/config/webpack/clientWebpackConfig.js") %>
+<%= add_documentation_reference(config[:message], "// https://github.com/shakacode/react-on-rails-demo-ssr-hmr/blob/master/config/webpack/clientWebpackConfig.js") %>
 
 const commonWebpackConfig = require('./commonWebpackConfig');
 <% if use_rsc? -%>

data/lib/generators/react_on_rails/templates/base/base/config/webpack/commonWebpackConfig.js.tt

@@ -1,4 +1,4 @@
-<%= add_documentation_reference(config[:message], "// https://github.com/shakacode/react_on_rails_demo_ssr_hmr/blob/master/config/webpack/commonWebpackConfig.js") %>
+<%= add_documentation_reference(config[:message], "// https://github.com/shakacode/react-on-rails-demo-ssr-hmr/blob/master/config/webpack/commonWebpackConfig.js") %>
 
 // Common configuration applying to client and server configuration
 const { generateWebpackConfig, merge } = require('shakapacker');
@@ -14,4 +14,4 @@ const commonOptions = {
 // Copy the object using merge b/c the baseClientWebpackConfig and commonOptions are mutable globals
 const commonWebpackConfig = () => merge({}, baseClientWebpackConfig, commonOptions);
 
-module.exports = commonWebpackConfig;
+module.exports = commonWebpackConfig;

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

@@ -1,4 +1,4 @@
-<%= add_documentation_reference(config[:message], "// https://github.com/shakacode/react_on_rails_demo_ssr_hmr/blob/master/config/webpack/development.js") %>
+<%= 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');
 

data/lib/generators/react_on_rails/templates/base/base/config/webpack/production.js.tt

@@ -1,4 +1,4 @@
-<%= add_documentation_reference(config[:message], "// https://github.com/shakacode/react_on_rails_demo_ssr_hmr/blob/master/config/webpack/production.js") %>
+<%= add_documentation_reference(config[:message], "// https://github.com/shakacode/react-on-rails-demo-ssr-hmr/blob/master/config/webpack/production.js") %>
 
 const serverClientOrBoth = require('./ServerClientOrBoth');
 

data/lib/generators/react_on_rails/templates/base/base/config/webpack/serverWebpackConfig.js.tt

@@ -1,4 +1,4 @@
-<%= add_documentation_reference(config[:message], "// https://github.com/shakacode/react_on_rails_demo_ssr_hmr/blob/master/config/webpack/serverWebpackConfig.js") %>
+<%= add_documentation_reference(config[:message], "// https://github.com/shakacode/react-on-rails-demo-ssr-hmr/blob/master/config/webpack/serverWebpackConfig.js") %>
 
 const { merge, config } = require('shakapacker');
 const commonWebpackConfig = require('./commonWebpackConfig');
@@ -197,10 +197,11 @@ const configureServer = () => {
     }
   });
 
-  // eval works well for the SSR bundle because it's the fastest and shows
-  // lines in the server bundle which is good for debugging SSR
-  // The default of cheap-module-source-map is slow and provides poor info.
-  serverWebpackConfig.devtool = 'eval';
+  // Avoid the webpack eval devtool, which triggers a webpack 5.106+ regression
+  // with ESM default exports (ReferenceError: __WEBPACK_DEFAULT_EXPORT__ is not defined).
+  // In development, cheap-module-source-map provides original line numbers in SSR error traces.
+  // In production, devtool is disabled to avoid generating .map files.
+  serverWebpackConfig.devtool = process.env.NODE_ENV === 'production' ? false : 'cheap-module-source-map';
 
 <% if use_pro? -%>
   // React on Rails Pro uses Node renderer, so target must be 'node'

data/lib/generators/react_on_rails/templates/base/base/config/webpack/test.js.tt

@@ -1,4 +1,4 @@
-<%= add_documentation_reference(config[:message], "// https://github.com/shakacode/react_on_rails_demo_ssr_hmr/blob/master/config/webpack/test.js") %>
+<%= add_documentation_reference(config[:message], "// https://github.com/shakacode/react-on-rails-demo-ssr-hmr/blob/master/config/webpack/test.js") %>
 
 const serverClientOrBoth = require('./ServerClientOrBoth')
 

data/lib/generators/react_on_rails/templates/pro/base/config/initializers/react_on_rails_pro.rb.tt

@@ -6,7 +6,7 @@ ReactOnRailsPro.configure do |config|
   config.server_renderer = "NodeRenderer"
   config.renderer_url = ENV.fetch("REACT_RENDERER_URL", "http://localhost:3800")
 
-  # See value in client/node-renderer.js
+  # See value in renderer/node-renderer.js
   config.renderer_password = ENV.fetch("RENDERER_PASSWORD", "devPassword")
 
   config.ssr_timeout = 5

data/lib/generators/react_on_rails/templates/pro/base/{client → renderer}/node-renderer.js

@@ -6,6 +6,7 @@ const configuredWorkersCount =
   parseWorkersCount(env.RENDERER_WORKERS_COUNT) ?? parseWorkersCount(env.NODE_RENDERER_CONCURRENCY);
 
 const config = {
+  // Resolves to <project-root>/.node-renderer-bundles (one level up from renderer/).
   serverBundleCachePath: path.resolve(__dirname, '../.node-renderer-bundles'),
   port: Number(env.RENDERER_PORT) || 3800,
   logLevel: env.RENDERER_LOG_LEVEL || 'info',

data/lib/react_on_rails/config_path_resolver.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "set"
+
 module ReactOnRails
   module ConfigPathResolver
     # Keep JS before TS to match generator defaults and to prefer the
@@ -14,13 +16,108 @@ module ReactOnRails
     ].freeze
     ALL_DEFAULT_CONFIG_CANDIDATES = (WEBPACK_DEFAULT_CONFIG_CANDIDATES + RSPACK_DEFAULT_CONFIG_CANDIDATES).freeze
 
+    protected
+
+    # Protected so including classes and overrides can share the same warning
+    # de-dupe registry across resolver callers without exposing it as API.
+    def config_path_warning_registry
+      @config_path_warning_registry ||= {
+        package_roots: Set.new,
+        package_json_paths: Set.new
+      }
+    end
+
     private
 
-    def resolved_package_json_path
-      node_modules_location = ReactOnRails.configuration.node_modules_location.to_s
-      return "package.json" if node_modules_location.empty? || node_modules_location == Rails.root.to_s
+    def resolved_package_json_path(package_root = resolved_package_root)
+      resolved_package_path("package.json", package_root)
+    end
+
+    # Memoized per instance: configuration is set once at boot in production.
+    # Tests must build a fresh resolver after stubbing a different
+    # node_modules_location, since reconfiguration on a reused instance is
+    # ignored after the first call.
+    def resolved_package_root
+      @resolved_package_root ||= begin
+        node_modules_location = ReactOnRails.configuration.node_modules_location.to_s
+
+        resolved_location = Pathname.new(node_modules_location).cleanpath
+        # cleanpath normalizes redundant separators and ".." without resolving symlinks;
+        # realpath is intentionally skipped to avoid filesystem I/O on every call.
+        # Relative paths like "../client" remain valid diagnostics targets and are
+        # not constrained to stay within Rails.root.
+        if resolved_location == Pathname.new(".")
+          Rails.root.to_s
+        elsif resolved_location.absolute?
+          resolved_location.to_s
+        else
+          Rails.root.join(resolved_location).to_s
+        end
+      end
+    end
+
+    def resolved_package_path(filename, package_root = resolved_package_root)
+      File.join(package_root, filename)
+    end
+
+    def package_root_missing?(package_root)
+      !Dir.exist?(package_root)
+    end
+
+    def package_json_path_for(detection_target, package_root = resolved_package_root)
+      package_json_path = resolved_package_json_path(package_root)
+      return package_json_path if File.exist?(package_json_path)
+
+      if package_root_missing?(package_root)
+        warn_missing_package_root(package_root)
+      else
+        warn_missing_package_json(package_json_path, detection_target)
+      end
+      nil
+    end
+
+    # Including classes must provide #add_warning(message). Classes that route
+    # warnings into another object's message list can override
+    # #config_path_warning_registry to share de-dupe state with that sink.
+    # Overrides must return a Hash with :package_roots and :package_json_paths
+    # keys whose values respond to #add?, such as Set instances.
+    def warn_missing_package_root(package_root)
+      return unless warned_package_roots.add?(package_root)
+
+      add_config_path_warning(missing_package_root_warning(package_root))
+    end
+
+    def missing_package_root_warning(package_root)
+      "⚠️  node_modules_location points to #{package_root}, but that directory does not exist; " \
+        "all diagnostics that read from it are skipped. Check config/initializers/react_on_rails.rb."
+    end
+
+    def warn_missing_package_json(package_json_path, detection_target)
+      return unless warned_package_json_paths.add?(package_json_path)
+
+      add_config_path_warning(missing_package_json_warning(package_json_path, detection_target))
+    end
+
+    def missing_package_json_warning(package_json_path, detection_target)
+      "⚠️  #{package_json_path} not found; cannot detect #{detection_target}. " \
+        "Check config/initializers/react_on_rails.rb."
+    end
+
+    def warned_package_roots
+      config_path_warning_registry[:package_roots]
+    end
+
+    def warned_package_json_paths
+      config_path_warning_registry[:package_json_paths]
+    end
+
+    def add_warning(_message)
+      raise NotImplementedError,
+            "#{self.class} must implement #add_warning(message) to include ReactOnRails::ConfigPathResolver"
+    end
 
-      Rails.root.join(node_modules_location, "package.json").to_s
+    def add_config_path_warning(message)
+      add_warning(message)
     end
 
     def resolved_webpack_config_path

data/lib/react_on_rails/configuration.rb

@@ -26,6 +26,28 @@ module ReactOnRails
     configuration.setup_config_values
   end
 
+  # Rendering strategy configured at boot time by engine initializers.
+  # Replaces runtime react_on_rails_pro? checks (see issue #2905).
+  # Not yet wired into the main rendering path — currently additive only.
+  def self.rendering_strategy
+    @rendering_strategy ||= ReactOnRails::RenderingStrategy::ExecJsStrategy.new
+  end
+
+  def self.rendering_strategy=(strategy)
+    @rendering_strategy = strategy
+  end
+
+  # JS code builder configured at boot time by engine initializers.
+  # Used by RenderRequest#to_js to generate SSR JavaScript code.
+  # Not yet wired into the main rendering path — currently additive only.
+  def self.js_code_builder
+    @js_code_builder ||= ReactOnRails::JsCodeBuilder.new
+  end
+
+  def self.js_code_builder=(builder)
+    @js_code_builder = builder
+  end
+
   DEFAULT_GENERATED_ASSETS_DIR = File.join(%w[public webpack], Rails.env).freeze
   DEFAULT_COMPONENT_REGISTRY_TIMEOUT = 5000
   DEFAULT_SERVER_BUNDLE_OUTPUT_PATH = "ssr-generated"