react_on_rails_pro 16.6.0 → 16.7.0.rc.0

data/lib/react_on_rails_pro/configuration.rb

@@ -21,6 +21,7 @@ module ReactOnRailsPro
       dependency_globs: Configuration::DEFAULT_DEPENDENCY_GLOBS,
       excluded_dependency_globs: Configuration::DEFAULT_EXCLUDED_DEPENDENCY_GLOBS,
       remote_bundle_cache_adapter: Configuration::DEFAULT_REMOTE_BUNDLE_CACHE_ADAPTER,
+      rolling_deploy_adapter: Configuration::DEFAULT_ROLLING_DEPLOY_ADAPTER,
       ssr_timeout: Configuration::DEFAULT_SSR_TIMEOUT,
       ssr_pre_hook_js: nil,
       assets_to_copy: nil,
@@ -52,6 +53,7 @@ module ReactOnRailsPro
     DEFAULT_DEPENDENCY_GLOBS = [].freeze
     DEFAULT_EXCLUDED_DEPENDENCY_GLOBS = [].freeze
     DEFAULT_REMOTE_BUNDLE_CACHE_ADAPTER = nil
+    DEFAULT_ROLLING_DEPLOY_ADAPTER = nil
     DEFAULT_RENDERER_REQUEST_RETRY_LIMIT = 5
     DEFAULT_THROW_JS_ERRORS = true
     DEFAULT_RENDERING_RETURNS_PROMISES = false
@@ -63,12 +65,16 @@ module ReactOnRailsPro
     DEFAULT_REACT_CLIENT_MANIFEST_FILE = "react-client-manifest.json"
     DEFAULT_REACT_SERVER_CLIENT_MANIFEST_FILE = "react-server-client-manifest.json"
     DEFAULT_CONCURRENT_COMPONENT_STREAMING_BUFFER_SIZE = 64
+    ROLLING_DEPLOY_UPLOAD_POSITIONAL_PARAMS = %i[req opt rest].freeze
+    ROLLING_DEPLOY_UPLOAD_KEYWORD_PARAMS = %i[key keyreq].freeze
+    ROLLING_DEPLOY_UPLOAD_ALL_KEYWORD_PARAMS = %i[keyrest].freeze
+    ROLLING_DEPLOY_UPLOAD_REQUIRED_KEYWORDS = %i[bundle assets].freeze
 
     attr_accessor :renderer_url, :renderer_password, :tracing,
                   :server_renderer, :renderer_use_fallback_exec_js, :prerender_caching,
                   :renderer_http_pool_size, :renderer_http_pool_timeout, :renderer_http_pool_warn_timeout,
                   :dependency_globs, :excluded_dependency_globs, :rendering_returns_promises,
-                  :remote_bundle_cache_adapter, :ssr_pre_hook_js, :assets_to_copy,
+                  :remote_bundle_cache_adapter, :rolling_deploy_adapter, :ssr_pre_hook_js, :assets_to_copy,
                   :renderer_request_retry_limit, :throw_js_errors, :ssr_timeout,
                   :profile_server_rendering_js_code, :raise_non_shell_server_rendering_errors, :enable_rsc_support,
                   :rsc_payload_generation_url_path, :rsc_bundle_js_file, :react_client_manifest_file,
@@ -116,7 +122,8 @@ module ReactOnRailsPro
                    renderer_http_pool_warn_timeout: nil, renderer_http_keep_alive_timeout: nil,
                    tracing: nil,
                    dependency_globs: nil, excluded_dependency_globs: nil, rendering_returns_promises: nil,
-                   remote_bundle_cache_adapter: nil, ssr_pre_hook_js: nil, assets_to_copy: nil,
+                   remote_bundle_cache_adapter: nil, rolling_deploy_adapter: nil,
+                   ssr_pre_hook_js: nil, assets_to_copy: nil,
                    renderer_request_retry_limit: nil, throw_js_errors: nil, ssr_timeout: nil,
                    profile_server_rendering_js_code: nil, raise_non_shell_server_rendering_errors: nil,
                    enable_rsc_support: nil, rsc_payload_generation_url_path: nil,
@@ -137,6 +144,7 @@ module ReactOnRailsPro
       self.dependency_globs = dependency_globs
       self.excluded_dependency_globs = excluded_dependency_globs
       self.remote_bundle_cache_adapter = remote_bundle_cache_adapter
+      self.rolling_deploy_adapter = rolling_deploy_adapter
       self.ssr_pre_hook_js = ssr_pre_hook_js
       self.assets_to_copy = assets_to_copy
       self.renderer_request_retry_limit = renderer_request_retry_limit
@@ -156,7 +164,9 @@ module ReactOnRailsPro
       configure_default_url_if_not_provided
       validate_url
       validate_remote_bundle_cache_adapter
+      validate_rolling_deploy_adapter
       setup_renderer_password
+      validate_renderer_password_for_production
       setup_assets_to_copy
       setup_execjs_profiler_if_needed
       check_react_on_rails_support_for_rsc
@@ -249,6 +259,94 @@ module ReactOnRailsPro
       end
     end
 
+    def validate_rolling_deploy_adapter
+      return if rolling_deploy_adapter.nil?
+
+      unless rolling_deploy_adapter.is_a?(Module)
+        raise ReactOnRailsPro::Error, "config.rolling_deploy_adapter must be a module or class"
+      end
+
+      %i[previous_bundle_hashes fetch upload].each do |method_name|
+        next if rolling_deploy_adapter.respond_to?(method_name)
+
+        raise ReactOnRailsPro::Error,
+              "config.rolling_deploy_adapter must define class method ##{method_name}. " \
+              "See docs/pro/rolling-deploy-adapters.md for the full protocol and reference implementations."
+      end
+
+      validate_rolling_deploy_upload_signature
+    end
+
+    def validate_rolling_deploy_upload_signature
+      params = rolling_deploy_adapter.method(:upload).parameters
+      return if rolling_deploy_upload_signature_valid?(params)
+
+      raise ReactOnRailsPro::Error,
+            "config.rolling_deploy_adapter#upload must accept signature " \
+            "upload(bundle_hash, bundle:, assets:) or an options-hash equivalent (e.g. " \
+            "upload(bundle_hash, **opts) / upload(*args) where opts/args[1] yield :bundle and :assets). " \
+            "See docs/pro/rolling-deploy-adapters.md."
+    end
+
+    # Best-effort signature check — covers the common explicit, splat, and
+    # options-hash shapes adapter authors actually write. Edge cases (e.g.
+    # `upload(hash, *args, bundle:)` mixing splat with explicit keywords) may
+    # pass this check and still fail at call time; the runtime ArgumentError
+    # in that case is clear enough that we accept the gap rather than encode
+    # every Ruby parameter combination here.
+    def rolling_deploy_upload_signature_valid?(params)
+      accepts_bundle_hash_argument?(params) &&
+        (accepts_upload_keyword_arguments?(params) || accepts_upload_options_hash?(params))
+    end
+
+    def accepts_bundle_hash_argument?(params)
+      required_positionals = params.count { |type, _name| type == :req }
+      return false if required_positionals > 1
+
+      params.any? { |type, _name| ROLLING_DEPLOY_UPLOAD_POSITIONAL_PARAMS.include?(type) }
+    end
+
+    def accepts_upload_keyword_arguments?(params)
+      return false if extra_required_upload_keywords(params).any?
+
+      accepts_all_upload_keywords?(params) || accepts_required_upload_keywords?(params)
+    end
+
+    def extra_required_upload_keywords(params)
+      required_keywords = params.select { |type, _name| type == :keyreq }.map(&:last)
+      required_keywords - ROLLING_DEPLOY_UPLOAD_REQUIRED_KEYWORDS
+    end
+
+    def accepts_all_upload_keywords?(params)
+      params.any? { |type, _name| ROLLING_DEPLOY_UPLOAD_ALL_KEYWORD_PARAMS.include?(type) }
+    end
+
+    def accepts_required_upload_keywords?(params)
+      ROLLING_DEPLOY_UPLOAD_REQUIRED_KEYWORDS.all? do |keyword|
+        params.any? { |type, name| ROLLING_DEPLOY_UPLOAD_KEYWORD_PARAMS.include?(type) && name == keyword }
+      end
+    end
+
+    def accepts_upload_options_hash?(params)
+      # Ruby 3 only converts keywords to an options hash when the callee has no
+      # explicit keyword parameters. `upload(hash, options = {}, region:)` still
+      # rejects the `bundle:` / `assets:` call shape used by assets precompile.
+      # `**nil` (the `:nokey` parameter kind) explicitly forbids keywords too,
+      # so reject it for the same reason.
+      return false if uses_explicit_upload_keywords?(params)
+      return true if params.any? { |type, _name| type == :rest }
+
+      required_positionals = params.count { |type, _name| type == :req }
+      optional_positionals = params.count { |type, _name| type == :opt }
+      required_positionals == 1 && optional_positionals.positive?
+    end
+
+    def uses_explicit_upload_keywords?(params)
+      params.any? do |type, _name|
+        type == :nokey || ROLLING_DEPLOY_UPLOAD_KEYWORD_PARAMS.include?(type)
+      end
+    end
+
     def setup_renderer_password
       # Explicit passwords, including values loaded from ENV in the initializer, skip URL extraction.
       # Blank values (nil or "") fall through so URL extraction and ENV fallback still apply.
@@ -260,8 +358,6 @@ module ReactOnRailsPro
       # Mirror Node-side defaults: if Rails config and URL are both missing a password,
       # use RENDERER_PASSWORD from env.
       self.renderer_password = ENV.fetch("RENDERER_PASSWORD", nil) if renderer_password.blank?
-
-      validate_renderer_password_for_production
     end
 
     def validate_renderer_password_for_production
@@ -270,12 +366,14 @@ module ReactOnRailsPro
       return if renderer_password.present?
       return unless node_renderer?
 
-      # Fail closed: only skip validation when RAILS_ENV is explicitly set to development or test.
-      # Rails.env defaults to "development" when RAILS_ENV is unset, which would silently skip
-      # validation in misconfigured environments. Checking ENV["RAILS_ENV"] directly matches the
-      # Node-side behavior where an unset environment is treated as production-like.
-      rails_env = ENV["RAILS_ENV"]&.downcase
-      return if rails_env.present? && %w[development test].include?(rails_env)
+      # Fail closed: only skip validation when every present runtime env is explicitly
+      # development or test. This mirrors the Node-side runtimeEnvsAllowDevelopmentDefaults()
+      # which checks both NODE_ENV and RAILS_ENV. Checking NODE_ENV here surfaces
+      # misconfigurations (e.g. NODE_ENV=production + RAILS_ENV=development) at Rails boot
+      # time rather than waiting for the Node renderer to reject the request.
+      runtime_envs = [ENV.fetch("RAILS_ENV", nil), ENV.fetch("NODE_ENV", nil)].compact_blank.map(&:downcase)
+      allowed_envs = %w[development test].freeze
+      return if runtime_envs.any? && runtime_envs.all? { |e| allowed_envs.include?(e) }
 
       raise ReactOnRailsPro::Error, <<~MSG
         RENDERER_PASSWORD must be set in production-like environments (staging, production, etc.)
@@ -304,13 +402,12 @@ module ReactOnRailsPro
 
         If Rails and the Node Renderer disagree about startup behavior, verify both RAILS_ENV and NODE_ENV.
 
-        Environment matrix:
-          development    — password optional (no authentication)
-          test           — password optional (no authentication)
-          (RAILS_ENV unset) — treated as production-like; RENDERER_PASSWORD required
-          staging        — RENDERER_PASSWORD required
-          production     — RENDERER_PASSWORD required
-          (any other)    — RENDERER_PASSWORD required
+        Environment matrix (both RAILS_ENV and NODE_ENV are checked):
+          development/test — password optional when every set env is development or test
+          (both unset)     — treated as production-like; RENDERER_PASSWORD required
+          staging          — RENDERER_PASSWORD required
+          production       — RENDERER_PASSWORD required
+          (mixed envs)     — RENDERER_PASSWORD required (e.g. NODE_ENV=production + RAILS_ENV=development)
       MSG
     end
   end

data/lib/react_on_rails_pro/engine.rb

@@ -24,6 +24,16 @@ module ReactOnRailsPro
       config.after_initialize { ReactOnRailsPro::Engine.log_problematic_compression_middleware_warnings }
     end
 
+    # Override the default rendering strategy with Pro's NodeStrategy and JsCodeBuilder.
+    # Runs after core's initializer since Pro engine loads after core.
+    # Not yet wired into the main rendering path — currently additive only (see issue #2905).
+    initializer "react_on_rails_pro.set_rendering_strategy" do
+      config.after_initialize do
+        ReactOnRails.rendering_strategy = ReactOnRailsPro::RenderingStrategy::NodeStrategy.new
+        ReactOnRails.js_code_builder = ReactOnRailsPro::JsCodeBuilder.new
+      end
+    end
+
     class << self
       def log_license_status
         status = ReactOnRailsPro::LicenseValidator.license_status

data/lib/react_on_rails_pro/httpx_stream_bidi_patch.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "httpx"
+
+#
+# Temporary patch for HTTPX stream_bidi plugin retry bug
+#
+# Issue: https://github.com/HoneyryderChuck/httpx/issues/124
+#
+# Problem: When a streaming request fails and is retried, the @headers_sent
+# flag is not reset. This causes the :body callback to fire prematurely on
+# retry, leading to re-entrant handle() calls that crash with:
+#   HTTP2::Error::InternalError
+#
+# This patch resets @headers_sent when transitioning back to :idle state.
+#
+# Can be removed once fixed upstream in httpx gem.
+#
+
+HTTPX::Plugins.load_plugin(:stream_bidi)
+
+if defined?(HTTPX::Plugins::StreamBidi)
+  module HTTPX
+    module Plugins
+      module StreamBidi
+        module RequestMethodsRetryFix
+          def transition(nextstate)
+            @headers_sent = false if nextstate == :idle
+
+            return super unless @options.stream
+
+            callbacks(:body).clear if nextstate == :idle
+
+            super
+          end
+        end
+
+        RequestMethods.prepend(RequestMethodsRetryFix)
+      end
+    end
+  end
+end

data/lib/react_on_rails_pro/js_code_builder.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module ReactOnRailsPro
+  # Pro JS code builder that extends the base JsCodeBuilder with RSC support,
+  # pre-hooks, and Node renderer-specific options.
+  #
+  # Part of the strategy pattern refactoring (see issue #2905).
+  # Currently additive — not yet wired into the main rendering path.
+  class JsCodeBuilder < ReactOnRails::JsCodeBuilder
+    protected
+
+    def build_sections(render_request)
+      [
+        rails_context_section(render_request),
+        rsc_params_section(render_request),
+        rsc_payload_function_section(render_request),
+        pre_hook_section(render_request),
+        store_initialization_section(render_request),
+        props_section(render_request),
+        render_call_section(render_request)
+      ]
+    end
+
+    def rsc_params_section(render_request)
+      return nil unless rsc_streaming?(render_request)
+
+      config = ReactOnRailsPro.configuration
+      react_client_manifest_file = config.react_client_manifest_file
+      react_server_client_manifest_file = config.react_server_client_manifest_file
+
+      <<~JS.chomp
+        railsContext.reactClientManifestFileName = #{react_client_manifest_file.to_json};
+        railsContext.reactServerClientManifestFileName = #{react_server_client_manifest_file.to_json};
+      JS
+    end
+
+    def rsc_payload_function_section(render_request)
+      return nil unless rsc_streaming?(render_request)
+
+      if render_request.rsc_payload_streaming?
+        <<~JS.chomp
+          if (typeof generateRSCPayload !== 'function') {
+            globalThis.generateRSCPayload = function generateRSCPayload() {
+              throw new Error('The rendering request is already running on the RSC bundle. Please ensure that generateRSCPayload is only called from any React Server Component.')
+            }
+          }
+        JS
+      else
+        <<~JS.chomp
+          railsContext.serverSideRSCPayloadParameters = {
+            renderingRequest,
+            rscBundleHash: #{ReactOnRailsPro::Utils.rsc_bundle_hash.to_json},
+          }
+          if (typeof generateRSCPayload !== 'function') {
+            globalThis.generateRSCPayload = function generateRSCPayload(componentName, props, railsContext) {
+              const { renderingRequest, rscBundleHash } = railsContext.serverSideRSCPayloadParameters;
+              const propsString = JSON.stringify(props);
+              const newRenderingRequest = renderingRequest.replace(
+                /\\(\\s*\\)\\s*$/,
+                function() { return `(${JSON.stringify(componentName)}, ${propsString})`; }
+              );
+              return runOnOtherBundle(rscBundleHash, newRenderingRequest);
+            }
+          }
+        JS
+      end
+    end
+
+    def pre_hook_section(_render_request)
+      pre_hook = ReactOnRailsPro.configuration.ssr_pre_hook_js
+      pre_hook.presence
+    end
+
+    # == JS variable contract (see base class build_sections for details)
+    # These three methods are coupled by JS variable names:
+    # - wrap_in_iife introduces `componentName` and `props` as IIFE default parameters
+    # - props_section declares `usedProps` (falls back to render_request.props_string
+    #   when `props` IIFE param is undefined, i.e. normal invocation)
+    # - render_call_section references both `componentName` and `usedProps`
+    # Overriding any one without the others will produce broken JavaScript.
+    def props_section(render_request)
+      "var usedProps = typeof props === 'undefined' ? #{render_request.props_string} : props;"
+    end
+
+    def render_call_section(render_request)
+      render_function_js_expr = resolve_render_function_js_expr(render_request)
+
+      <<~JS.chomp
+        return ReactOnRails[#{render_function_js_expr}]({
+          name: componentName,
+          domNodeId: #{render_request.dom_id.to_json},
+          props: usedProps,
+          trace: #{render_request.render_options.trace},
+          railsContext: railsContext,
+          throwJsErrors: #{ReactOnRailsPro.configuration.throw_js_errors},
+          renderingReturnsPromises: #{ReactOnRailsPro.configuration.rendering_returns_promises},
+        });
+      JS
+    end
+
+    def wrap_in_iife(body, render_request)
+      "(function(componentName = #{render_request.component_name.to_json}, props = undefined) {\n#{body}\n})()"
+    end
+
+    private
+
+    def rsc_streaming?(render_request)
+      ReactOnRailsPro.configuration.enable_rsc_support && render_request.streaming?
+    end
+
+    # Returns a JavaScript expression for the render function name.
+    # For RSC streaming, this is a ternary expression (not a simple string literal).
+    def resolve_render_function_js_expr(render_request)
+      if rsc_streaming?(render_request)
+        "ReactOnRails.isRSCBundle ? 'serverRenderRSCReactComponent' : 'streamServerRenderedReactComponent'"
+      else
+        "'serverRenderReactComponent'"
+      end
+    end
+  end
+end

data/lib/react_on_rails_pro/pre_seed_renderer_cache.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "react_on_rails_pro/renderer_cache_helpers"
+require "react_on_rails_pro/renderer_cache_path"
+require "react_on_rails_pro/rolling_deploy_cache_stager"
+
+module ReactOnRailsPro
+  # Stages the Node Renderer bundle cache in the renderer's expected directory
+  # structure (`<cache>/<bundleHash>/<bundleHash>.js`), including any configured
+  # assets_to_copy and, when RSC support is enabled, the RSC bundle and manifests.
+  #
+  # Supports two modes:
+  #
+  # * `:copy` - copies bundle and assets. Designed for Docker image
+  #   builds where the cache must be baked into an immutable artifact.
+  # * `:symlink` - creates relative symlinks. For same-filesystem workflows
+  #   (local dev, CI, Heroku-style same-dyno deploys, bundle-caching restores).
+  #
+  # Both modes produce the same on-disk cache layout, matching the renderer's
+  # runtime contract. The 410->retry cold-start round-trip on first SSR request
+  # is eliminated when the pre-seeded bundle is present at renderer startup.
+  class PreSeedRendererCache
+    VALID_MODES = %i[copy symlink].freeze
+
+    # `mode:` is required (no default) because the two modes have fundamentally
+    # different semantics — `:copy` bakes immutable artifacts for Docker/image
+    # builds; `:symlink` links live files on a shared filesystem. Forcing callers
+    # to be explicit prevents the footgun where an implicit default would mismatch
+    # the deploy context (e.g., copy-mode raises about RENDERER_SERVER_BUNDLE_CACHE_PATH
+    # in a dev shell). The rake task and AssetsPrecompile auto-invocation both pass
+    # `mode:` explicitly with their own context-appropriate defaults.
+    def self.call(mode:)
+      unless VALID_MODES.include?(mode)
+        raise ArgumentError, "mode must be one of #{VALID_MODES.inspect}, got #{mode.inspect}"
+      end
+
+      cache_dir = resolve_cache_dir(mode)
+      puts "[ReactOnRailsPro] Staging renderer cache (mode: #{mode}) in: #{cache_dir}"
+      pool = ReactOnRailsPro::ServerRenderingPool::NodeRenderingPool
+
+      assets, rsc_required_paths = RendererCacheHelpers.collect_assets_with_required_paths
+
+      current_hashes = []
+      # Block-level `rescue` (Ruby 2.5+): equivalent to wrapping the block body in
+      # begin/rescue/end. RuboCop's Style/RedundantBegin enforces this form, so
+      # callers reading the loop should treat the rescue clause below as the
+      # iteration body's exception handler — not the surrounding method's.
+      RendererCacheHelpers.bundle_sources(pool, action_description(mode)).each do |src_bundle_path, bundle_hash|
+        bundle_dir = File.join(cache_dir, bundle_hash.to_s)
+        stage_bundle(src_bundle_path, bundle_dir, bundle_hash, mode)
+        # The Node Renderer serves manifests from whichever bundle dir it loaded,
+        # so both server and RSC dirs need the manifests present.
+        stage_assets(assets, bundle_dir, rsc_required_paths, mode)
+        current_hashes << bundle_hash.to_s
+      rescue StandardError => e
+        # Fail-fast: re-raise on the first bundle failure so the deploy sees a non-zero exit and
+        # aborts before downstream steps assume the cache is complete. Earlier bundles that
+        # already staged successfully (e.g. server bundle when RSC fails) remain on disk for
+        # diagnosis or for a re-run, but the renderer should not be expected to start from a
+        # partially-staged cache — operators must rebuild the cache or roll back.
+        warn "[ReactOnRailsPro] Renderer cache staging failed for bundle #{bundle_hash}; " \
+             "cache may be partially staged: #{e.message}"
+        raise
+      end
+
+      # Optionally seed previous deploys' bundle hashes for rolling-deploy safety.
+      # No-op when neither config.rolling_deploy_adapter nor PREVIOUS_BUNDLE_HASHES is set.
+      RollingDeployCacheStager.call(cache_dir: cache_dir, current_hashes: current_hashes, mode: mode)
+    end
+
+    # Validates the cache-dir env var (raises in production-like copy mode when
+    # unset) before resolving. See enforce_cache_dir_env_var! for the rationale.
+    def self.resolve_cache_dir(mode)
+      enforce_cache_dir_env_var!(mode)
+      ReactOnRailsPro::RendererCachePath.resolve
+    end
+    private_class_method :resolve_cache_dir
+
+    # In copy mode (Docker image builds), silent fallback to Rails.root/.node-renderer-bundles
+    # is a footgun: the renderer process may run from a different cwd and resolve its default
+    # cache directory to a different path (e.g., /tmp/react-on-rails-pro-node-renderer-bundles),
+    # causing pre-seeded bundles to land somewhere the renderer never reads. Require an
+    # explicit env var in non-dev/test environments.
+    def self.enforce_cache_dir_env_var!(mode)
+      return unless mode == :copy
+      return if Rails.env.development? || Rails.env.test?
+
+      # Only development and test are exempt; custom environments (ci, staging,
+      # review, etc.) must set the env var explicitly because their default cache
+      # path can differ from the Node renderer's default, causing silent
+      # mis-staging.
+      # RENDERER_BUNDLE_PATH remains accepted for compatibility, but new deploys
+      # should migrate to RENDERER_SERVER_BUNDLE_CACHE_PATH. Whitespace-only
+      # values intentionally pass this guard so RendererCachePath can raise the
+      # specific validation error instead of the missing-env guidance.
+      return if !ENV.fetch("RENDERER_SERVER_BUNDLE_CACHE_PATH", "").empty? ||
+                !ENV.fetch("RENDERER_BUNDLE_PATH", "").empty?
+
+      raise ReactOnRailsPro::Error, <<~MSG.strip
+        Pre-seeding the renderer cache in copy mode (#{Rails.env}) requires an explicit
+        cache directory. Set RENDERER_SERVER_BUNDLE_CACHE_PATH in your environment, e.g.
+        in your Dockerfile:
+
+          ENV RENDERER_SERVER_BUNDLE_CACHE_PATH=/app/.node-renderer-bundles
+
+        The Node Renderer's default cache directory resolution differs between the Ruby
+        and standalone Node environments, so relying on the default in production-like
+        deploys can cause pre-seeded bundles to land in a path the renderer never reads.
+
+        If you don't need an immutable artifact (e.g. in CI or same-filesystem deploys),
+        use mode: :symlink instead:
+
+          rake react_on_rails_pro:pre_seed_renderer_cache MODE=symlink
+      MSG
+    end
+    private_class_method :enforce_cache_dir_env_var!
+
+    def self.action_description(mode)
+      mode == :copy ? "pre-seeding" : "pre-staging"
+    end
+    private_class_method :action_description
+
+    def self.stage_bundle(src_path, bundle_dir, bundle_hash, mode)
+      dest_file = File.join(bundle_dir, "#{bundle_hash}.js")
+      log_prefix = mode == :copy ? "Pre-seeded renderer cache" : "Pre-staged renderer cache"
+      stage_file(src_path, dest_file, mode, log_prefix)
+    end
+    private_class_method :stage_bundle
+
+    def self.stage_file(src, dest, mode, log_prefix)
+      RendererCacheHelpers.stage_file(src, dest, mode, log_prefix: log_prefix)
+    end
+    private_class_method :stage_file
+
+    # RSC manifests are required when RSC is enabled; user-configured
+    # assets_to_copy are optional and only produce a warning.
+    def self.stage_assets(assets, bundle_dir, rsc_required_paths, mode)
+      action_desc = action_description(mode)
+      RendererCacheHelpers.each_stageable_asset(assets, rsc_required_paths, action_desc) do |expanded|
+        dest = File.join(bundle_dir, File.basename(expanded))
+        log_prefix = mode == :copy ? "Copied asset" : "Symlinked asset"
+        stage_file(expanded, dest, mode, log_prefix)
+      end
+    end
+    private_class_method :stage_assets
+  end
+end

data/lib/react_on_rails_pro/prepare_node_renderer_bundles.rb

@@ -1,40 +1,45 @@
 # frozen_string_literal: true
 
-require "pathname"
+require "react_on_rails_pro/pre_seed_renderer_cache"
 
 module ReactOnRailsPro
+  # DEPRECATED: use `ReactOnRailsPro::PreSeedRendererCache.call(mode: :symlink)` directly.
+  # Retained as a thin shim so existing callers (custom rake tasks, Procfile entries,
+  # deploy scripts) keep working during the deprecation cycle. Emits a warning once
+  # per process on first call.
   class PrepareNodeRenderBundles
-    extend FileUtils
-
-    def self.make_relative_symlink(source, destination)
-      FileUtils.rm_f(destination)
-      relative_source_path = Pathname.new(source).relative_path_from(Pathname.new(destination).dirname)
-      File.symlink(relative_source_path, destination)
-      puts "[ReactOnRailsPro] Symlinked #{relative_source_path} to #{destination}"
-    end
-
+    # Mutex guards the check-then-set on @deprecation_warned so concurrent callers
+    # (e.g. multiple Puma workers invoking the shim at boot) still see exactly one
+    # warning per process.
+    @deprecation_mutex = Mutex.new
+    @deprecation_warned = false
+
+    # The deprecated rake task emits its own warning and calls PreSeedRendererCache
+    # directly; it does not set this one-time guard. See assets.rake for that path.
     def self.call
-      # TODO: temporarily hardcoding tmp/bundles directory. renderer and rails should read from a Yaml file
-      src_bundle_path = ReactOnRails::Utils.server_bundle_js_file_path
-      renderer_bundle_file_name = ReactOnRailsPro::ServerRenderingPool::NodeRenderingPool.renderer_bundle_file_name
-      dest_path = ENV["RENDERER_BUNDLE_PATH"].presence || Rails.root.join(".node-renderer-bundles").to_s
-      bundle_dest_path = File.join(dest_path, renderer_bundle_file_name.to_s).to_s
-      puts "[ReactOnRailsPro] Symlinking assets to local node-renderer, path #{dest_path}"
-      mkdir_p(dest_path)
-
-      make_relative_symlink(src_bundle_path, bundle_dest_path)
-
-      return unless ReactOnRailsPro.configuration.assets_to_copy.present?
+      emit_deprecation_warning!
+      PreSeedRendererCache.call(mode: :symlink)
+    end
 
-      ReactOnRailsPro.configuration.assets_to_copy.each do |asset_path|
-        unless File.exist?(asset_path)
-          warn "Asset not found #{asset_path}"
-          next
-        end
+    def self.emit_deprecation_warning!
+      @deprecation_mutex.synchronize do
+        return if @deprecation_warned
 
-        destination_full_path = File.join(dest_path, asset_path.basename.to_s)
-        make_relative_symlink(asset_path, destination_full_path)
+        warn "[ReactOnRailsPro] ReactOnRailsPro::PrepareNodeRenderBundles is deprecated. " \
+             "Use ReactOnRailsPro::PreSeedRendererCache.call(mode: :symlink) instead. " \
+             "The rake task equivalent is 'rake react_on_rails_pro:pre_seed_renderer_cache MODE=symlink'."
+        @deprecation_warned = true
       end
     end
+    private_class_method :emit_deprecation_warning!
+
+    # :nodoc: Test helper - resets the one-time deprecation-warning guard so
+    # specs can exercise the warning path without leaking state between examples.
+    # Private so it can only be invoked from specs via `send`; prevents accidental
+    # reset from production code.
+    def self.reset_deprecation_warned!
+      @deprecation_mutex.synchronize { @deprecation_warned = false }
+    end
+    private_class_method :reset_deprecation_warned!
   end
 end