react_on_rails 16.7.0.rc.3 → 17.0.0.rc.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a330ac2b76a6a565ea1f64291f54d2ff5a90b39e33bb7c1929f3caa11ed8358e
-  data.tar.gz: 4d06374dfcb3c2004138c3386ed326634b03c91a27e96c4d442b0bcd5a9c39c9
+  metadata.gz: 0feb399078c3e60a35b5e36bc257cc2711bf793fd04dab39c3ccfcfdd8448cd8
+  data.tar.gz: 3848ca13d934d2fda5ca63f8b7660aaac360ac3daec07d7a15433a647d058c44
 SHA512:
-  metadata.gz: 55392f01cd6ccad3792eac088c3f59d354131e159d22bc15dc086b17abc75ca248da294269d3e73ee25cea846af246e0d59ab2b93558ab0cf9bd9558e3ef52bf
-  data.tar.gz: c8fed4f8f74704860bff9a4784906ebcf5bab48cf7a50d9e7240a750d71c4d87dd228c55b3f0bad80edcc0c06565a20f606f8a2f1938ab8b3fa0108c52241bbf
+  metadata.gz: 3d2a9e86976672ce1b5ae6b869a9d777bb652b35423cb7b361614db8ccdb710423ad8434115f460ffd7522336a9eb8eec74382bd793f4cd537dfe2d12b69df46
+  data.tar.gz: b75324ae9ad146861baebd20716ef293c28509734afbf206da63275db4d29c6a24115a9e2b834781d275a1a586fd9215cdd208c1e93a1101a47d275436cbfda1

data/.rubocop.yml

@@ -11,6 +11,7 @@ AllCops:
 
   Exclude:
     - 'spec/dummy/bin/*'
+    - 'spike/**/*'  # Exploratory spike code outside lib/ — not part of the production surface
 
 Naming/FileName:
   Exclude:

data/Gemfile.development_dependencies

@@ -2,18 +2,22 @@
 
 eval_gemfile File.expand_path("../Gemfile.shared_dev_dependencies", __dir__)
 
-gem "shakapacker", "9.6.1"
+gem "shakapacker", "10.1.0"
 gem "bootsnap", require: false
 gem "rails", "~> 7.1.0"
 
-gem "sqlite3", "~> 1.6"
+gem "sqlite3", "~> 2.0"
 gem "sass-rails", "~> 6.0"
 gem "uglifier"
 gem "jquery-rails"
 gem "puma", "~> 6.0"
 
 # Turbolinks makes following links in your web application faster. Read more: https://github.com/rails/turbolinks
-gem "turbolinks" if ENV["DISABLE_TURBOLINKS"].nil? || ENV["DISABLE_TURBOLINKS"].strip.empty?
+# Declared unconditionally so the gemset always matches Gemfile.lock. DISABLE_TURBOLINKS
+# toggles Turbolinks at the application layer (the require_asset in
+# spec/dummy/app/assets/javascripts/application_non_webpack.js.erb), not gem inclusion.
+# A conditional declaration broke `bundle install --frozen` in CI (see AGENTS.md).
+gem "turbolinks"
 
 # Build JSON APIs with ease. Read more: https://github.com/rails/jbuilder
 gem "jbuilder"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    react_on_rails (16.7.0.rc.3)
+    react_on_rails (17.0.0.rc.1)
       addressable
       connection_pool
       execjs (~> 2.5)
@@ -237,7 +237,7 @@ GEM
       nio4r (~> 2.0)
     racc (1.8.1)
     rack (3.2.5)
-    rack-proxy (0.7.7)
+    rack-proxy (0.8.2)
       rack
     rack-session (2.1.1)
       base64 (>= 0.1.0)
@@ -360,7 +360,7 @@ GEM
       rubyzip (>= 1.2.2, < 3.0)
       websocket (~> 1.0)
     semantic_range (3.1.1)
-    shakapacker (9.6.1)
+    shakapacker (10.1.0)
       activesupport (>= 5.2)
       package_json
       rack-proxy (>= 0.6.1)
@@ -379,10 +379,10 @@ GEM
       actionpack (>= 5.2)
       activesupport (>= 5.2)
       sprockets (>= 3.0.0)
-    sqlite3 (1.7.3)
+    sqlite3 (2.9.4)
       mini_portile2 (~> 2.8.0)
-    sqlite3 (1.7.3-arm64-darwin)
-    sqlite3 (1.7.3-x86_64-linux)
+    sqlite3 (2.9.4-arm64-darwin)
+    sqlite3 (2.9.4-x86_64-linux-gnu)
     steep (1.9.4)
       activesupport (>= 5.1)
       concurrent-ruby (>= 1.1.10)
@@ -475,11 +475,11 @@ DEPENDENCIES
   sass-rails (~> 6.0)
   sdoc
   selenium-webdriver (= 4.9.0)
-  shakapacker (= 9.6.1)
+  shakapacker (= 10.1.0)
   simplecov (~> 0.16.1)
   spring (~> 4.0)
   sprockets (~> 4.0)
-  sqlite3 (~> 1.6)
+  sqlite3 (~> 2.0)
   steep
   turbo-rails
   turbolinks
@@ -487,4 +487,4 @@ DEPENDENCIES
   webdrivers (= 5.3.0)
 
 BUNDLED WITH
-   2.5.9
+  4.0.10

data/lib/generators/react_on_rails/base_generator.rb

@@ -6,11 +6,13 @@ require "erb"
 require_relative "generator_messages"
 require_relative "generator_helper"
 require_relative "js_dependency_manager"
+require_relative "shakapacker_precompile_hook_helper"
 module ReactOnRails
   module Generators
     class BaseGenerator < Rails::Generators::Base
       include GeneratorHelper
       include JsDependencyManager
+      include ShakapackerPrecompileHookHelper
 
       Rails::Generators.hide_namespace(namespace)
       source_root(File.expand_path("templates", __dir__))
@@ -22,11 +24,22 @@ module ReactOnRails
                    desc: "Install Redux package and Redux version of Hello World Example",
                    aliases: "-R"
 
-      # --rspack
+      # --rspack / --no-rspack (Rspack is the default on fresh installs; --no-rspack selects Webpack)
+      # IMPORTANT: do NOT add a `default:` here. The absence of a default is load-bearing — Thor
+      # only includes :rspack in the options hash when the flag is explicitly passed, which is how
+      # GeneratorHelper#using_rspack? tells an explicit choice from "no flag given" (the latter
+      # falls back to rspack_bundler_default). Adding `default: false` would make
+      # options.key?(:rspack) always true and silently break the fresh-install Rspack default.
+      # (Thor's omit-when-no-default behavior verified against Thor 1.5.0; see Gemfile.lock.)
       class_option :rspack,
                    type: :boolean,
-                   default: false,
-                   desc: "Use Rspack instead of Webpack as the bundler"
+                   desc: "Use Rspack (default) as the bundler; pass --no-rspack to use Webpack"
+
+      # --webpack: friendly alias for --no-rspack (reconciled in GeneratorHelper#explicit_bundler_choice).
+      # No `default:` here either — same load-bearing reason as --rspack above.
+      class_option :webpack,
+                   type: :boolean,
+                   desc: "Use Webpack as the bundler (alias for --no-rspack; --no-webpack is equivalent to --rspack)"
 
       # --pro
       class_option :pro,
@@ -313,6 +326,18 @@ module ReactOnRails
 
       private
 
+      # Fresh-install context: default to Rspack (when Shakapacker supports it) unless the
+      # app already declares a bundler. See GeneratorHelper#fresh_install_rspack_default.
+      # NOTE: InstallGenerator#rspack_bundler_default is an intentional twin of this override
+      # (both generators are independently CLI-invocable); keep the two in sync.
+      def rspack_bundler_default
+        fresh_install_rspack_default
+      end
+
+      def generated_build_test_command
+        shakapacker_build_command(env: "RAILS_ENV=test NODE_ENV=test", environment: "test")
+      end
+
       def generate_new_app_home_page?
         options.new_app? && new_app_root_route_added?
       end

data/lib/generators/react_on_rails/generator_helper.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "shakapacker_precompile_hook_helper"
 
+# rubocop:disable Metrics/ModuleLength
 module GeneratorHelper
+  include ReactOnRails::Generators::ShakapackerPrecompileHookHelper
+
   def package_json
     # Lazy load package_json gem only when actually needed for dependency management
 
@@ -128,11 +132,57 @@ module GeneratorHelper
   def using_rspack?
     return @using_rspack if defined?(@using_rspack)
 
-    # options.key?(:rspack) is true when the generator declares --rspack (e.g. InstallGenerator),
-    # false when it does not (e.g. RscGenerator, ProGenerator). Using .key? rather than .nil?
-    # check on the value makes the intent explicit and avoids relying on Thor returning nil for
-    # undeclared options.
-    @using_rspack = options.key?(:rspack) ? options[:rspack] : rspack_configured_in_project?
+    # An explicit bundler flag always wins. When none was passed (or the generator doesn't
+    # declare the flags, e.g. RscGenerator/ProGenerator), fall back to the bundler default,
+    # which each generator defines for its own context.
+    explicit = explicit_bundler_choice
+    @using_rspack = explicit.nil? ? rspack_bundler_default : explicit
+  end
+
+  # Resolve the explicit bundler flags into a single choice.
+  #
+  # --rspack selects Rspack; --no-rspack and --webpack select Webpack (--webpack is a friendly
+  # alias for --no-rspack, and the auto-generated --no-webpack mirrors --rspack). Returns true
+  # for Rspack, false for Webpack, or nil when no bundler flag was passed (so the caller falls
+  # back to rspack_bundler_default).
+  #
+  # IMPORTANT: this relies on Thor NOT including a nil-defaulted option in the hash when the flag
+  # is absent — options.key?(:rspack)/(:webpack) is true only when the user passed that flag.
+  # Re-adding `default:` to either class_option would make the key always present and break both
+  # the "no flag given" fallback and the conflict detection here.
+  # (Thor's omit-when-no-default behavior verified against Thor 1.5.0; see Gemfile.lock.)
+  #
+  # Passing contradictory flags (e.g. --rspack --webpack) raises a Thor::Error.
+  def explicit_bundler_choice
+    choices = []
+    choices << options[:rspack] if options.key?(:rspack)
+    # --webpack means "use Webpack" (rspack = false); --no-webpack means "use Rspack".
+    # Name the inverted webpack flag so the rspack-boolean intent reads directly.
+    rspack_via_webpack_flag = !options[:webpack]
+    choices << rspack_via_webpack_flag if options.key?(:webpack)
+    return nil if choices.empty?
+
+    if choices.uniq.length > 1
+      raise Thor::Error,
+            "Conflicting bundler flags: pass either Rspack (--rspack) or Webpack " \
+            "(--webpack / --no-rspack), not both."
+    end
+
+    choices.first
+  end
+
+  # True when the user passed any explicit bundler flag
+  # (--rspack/--no-rspack/--webpack/--no-webpack).
+  def bundler_flag_given?
+    options.key?(:rspack) || options.key?(:webpack)
+  end
+
+  # Bundler to use when no explicit bundler flag was passed.
+  # Default (standalone generators like RscGenerator/ProGenerator): respect the existing
+  # project's shakapacker.yml and never impose a bundler. InstallGenerator/BaseGenerator
+  # override this to default fresh installs to Rspack.
+  def rspack_bundler_default
+    rspack_configured_in_project?
   end
 
   # Remap a config path from config/webpack/ to config/rspack/ when using rspack.
@@ -291,25 +341,6 @@ module GeneratorHelper
     shakapacker_version_9_3_or_higher?
   end
 
-  def parse_shakapacker_yml(path)
-    require "yaml"
-    # Use safe_load_file for security (defense-in-depth, even though this is user's own config)
-    # permitted_classes: [Symbol] allows symbol keys which shakapacker.yml may use
-    # aliases: true allows YAML anchors (&default, *default) commonly used in Rails configs
-    YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: true)
-  rescue ArgumentError
-    # Older Psych versions don't support all parameters - try without aliases
-    begin
-      YAML.safe_load_file(path, permitted_classes: [Symbol])
-    rescue ArgumentError
-      # Very old Psych - fall back to safe_load with File.read
-      YAML.safe_load(File.read(path), permitted_classes: [Symbol]) # rubocop:disable Style/YAMLFileRead
-    end
-  rescue StandardError
-    # If we can't parse the file, return empty config
-    {}
-  end
-
   # Check if Shakapacker 9.3.0 or higher is available
   # This version made SWC the default JavaScript transpiler
   def shakapacker_version_9_3_or_higher?
@@ -330,10 +361,34 @@ module GeneratorHelper
   # `assets_bundler` inside the `default: &default` block, and our generator writes
   # it there too via configure_rspack_in_shakapacker.
   def rspack_configured_in_project?
+    shakapacker_assets_bundler_value == "rspack"
+  end
+
+  # Fresh-install bundler default used by InstallGenerator/BaseGenerator: prefer Rspack
+  # when Shakapacker supports it (Rspack landed in Shakapacker 9.0), but never override an
+  # existing app's explicit assets_bundler choice. On a brand-new install where Shakapacker
+  # isn't loaded yet, shakapacker_version_9_or_higher? optimistically returns true.
+  def fresh_install_rspack_default
+    return rspack_configured_in_project? if project_declares_assets_bundler?
+
+    shakapacker_version_9_or_higher?
+  end
+
+  # True when config/shakapacker.yml exists and its default: section declares an
+  # assets_bundler (i.e., the project has already made an explicit bundler choice).
+  def project_declares_assets_bundler?
+    !shakapacker_assets_bundler_value.nil?
+  end
+
+  # Single source for the config/shakapacker.yml default-section read shared by
+  # rspack_configured_in_project? and project_declares_assets_bundler?. Returns the
+  # assets_bundler value (e.g. "rspack"), or nil when the file is absent or the key is unset.
+  # Only the default: section is inspected (see rspack_configured_in_project? for the rationale).
+  def shakapacker_assets_bundler_value
     shakapacker_yml_path = File.join(destination_root, "config/shakapacker.yml")
-    return false unless File.exist?(shakapacker_yml_path)
+    return nil unless File.exist?(shakapacker_yml_path)
 
-    config = parse_shakapacker_yml(shakapacker_yml_path)
-    config.dig("default", "assets_bundler") == "rspack"
+    parse_shakapacker_yml(shakapacker_yml_path).dig("default", "assets_bundler")
   end
 end
+# rubocop:enable Metrics/ModuleLength

data/lib/generators/react_on_rails/generator_messages/ci_section.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
 require "rainbow"
+require_relative "../shakapacker_precompile_hook_helper"
 
 module GeneratorMessages
   module CiSection
+    include ReactOnRails::Generators::ShakapackerPrecompileHookHelper
+
     private
 
     def build_ci_section(app_root: Dir.pwd, ci_workflow_generated: false)
@@ -25,6 +28,11 @@ module GeneratorMessages
                         else
                           ""
                         end
+      manual_build_command = shakapacker_build_command(
+        env: "RAILS_ENV=test NODE_ENV=test",
+        app_root: app_root,
+        environment: "test"
+      )
 
       <<~CI
 
@@ -35,7 +43,7 @@ module GeneratorMessages
         #{ci_status}
 
         To build bundles manually before tests:
-        #{Rainbow('RAILS_ENV=test NODE_ENV=test bin/shakapacker').cyan}#{build_test_hint}
+        #{Rainbow(manual_build_command).cyan}#{build_test_hint}
       CI
     end
   end

data/lib/generators/react_on_rails/install_generator.rb

@@ -9,6 +9,7 @@ require_relative "generator_messages"
 require_relative "js_dependency_manager"
 require_relative "pro_setup"
 require_relative "rsc_setup"
+require_relative "shakapacker_precompile_hook_helper"
 # Load-path require: git_utils lives under react_on_rails/lib, not relative to this generator directory.
 require "react_on_rails/git_utils"
 
@@ -23,6 +24,7 @@ module ReactOnRails
       include JsDependencyManager
       include ProSetup
       include RscSetup
+      include ShakapackerPrecompileHookHelper
 
       # fetch USAGE file for details generator description
       source_root(File.expand_path(__dir__))
@@ -41,11 +43,22 @@ module ReactOnRails
                    desc: "Generate TypeScript files and install TypeScript dependencies. Default: false",
                    aliases: "-T"
 
-      # --rspack
+      # --rspack / --no-rspack (Rspack is the default on fresh installs; --no-rspack selects Webpack)
+      # IMPORTANT: do NOT add a `default:` here. The absence of a default is load-bearing — Thor
+      # only includes :rspack in the options hash when the flag is explicitly passed, which is how
+      # GeneratorHelper#using_rspack? tells an explicit choice from "no flag given" (the latter
+      # falls back to rspack_bundler_default). Adding `default: false` would make
+      # options.key?(:rspack) always true and silently break the fresh-install Rspack default.
+      # (Thor's omit-when-no-default behavior verified against Thor 1.5.0; see Gemfile.lock.)
       class_option :rspack,
                    type: :boolean,
-                   default: false,
-                   desc: "Use Rspack instead of Webpack as the bundler. Default: false"
+                   desc: "Use Rspack (default) as the bundler; pass --no-rspack to use Webpack"
+
+      # --webpack: friendly alias for --no-rspack (reconciled in GeneratorHelper#explicit_bundler_choice).
+      # No `default:` here either — same load-bearing reason as --rspack above.
+      class_option :webpack,
+                   type: :boolean,
+                   desc: "Use Webpack as the bundler (alias for --no-rspack; --no-webpack is equivalent to --rspack)"
 
       # --ignore-warnings
       class_option :ignore_warnings,
@@ -87,7 +100,6 @@ module ReactOnRails
 
       # Removed: --skip-shakapacker-install (Shakapacker is now a required dependency)
 
-      SHAKAPACKER_YML_PATH = "config/shakapacker.yml"
       HELLO_WORLD_ROUTE = "hello_world"
       HELLO_SERVER_ROUTE = "hello_server"
       # Matches the stock `bin/dev` written by Rails 8.x. Rails 7.1 commonly
@@ -196,6 +208,14 @@ module ReactOnRails
 
       private
 
+      # Fresh-install context: default to Rspack (when Shakapacker supports it) unless the
+      # app already declares a bundler. See GeneratorHelper#fresh_install_rspack_default.
+      # NOTE: BaseGenerator#rspack_bundler_default is an intentional twin of this override
+      # (both generators are independently CLI-invocable); keep the two in sync.
+      def rspack_bundler_default
+        fresh_install_rspack_default
+      end
+
       def invoke_generators
         ensure_shakapacker_installed
         if options.typescript?
@@ -206,7 +226,7 @@ module ReactOnRails
         # `invoke` instantiates child generators with a fresh options hash, so
         # --pretend/--force/--skip must be forwarded explicitly at each boundary.
         invoke "react_on_rails:base", [],
-               { typescript: options.typescript?, redux: options.redux?, rspack: options.rspack?,
+               { typescript: options.typescript?, redux: options.redux?, rspack: using_rspack?,
                  pro: use_pro?, rsc: use_rsc?, new_app: options.new_app?,
                  shakapacker_just_installed: shakapacker_just_installed?,
                  force: options[:force], skip: options[:skip], pretend: options[:pretend] }
@@ -296,18 +316,19 @@ module ReactOnRails
                  { package_manager: package_manager, has_lockfile: has_lockfile,
                    pnpm_version_declared: pnpm_version_declared,
                    pnpm_fallback_version: CI_PNPM_FALLBACK_VERSION,
-                   has_active_record: has_active_record, has_rspec: has_rspec })
+                   has_active_record: has_active_record, has_rspec: has_rspec,
+                   precompile_hook_command: shakapacker_precompile_hook_command(environment: "test") })
         @ci_workflow_generated = true
       end
 
-      # NODE_ENV=production ensures Shakapacker emits a minified production bundle;
-      # without it the default is "development" which produces an unminified dev bundle
-      # and is almost never what `npm run build` is expected to do.
-      DEFAULT_PACKAGE_JSON_SCRIPTS = {
-        "build" => "NODE_ENV=production bin/shakapacker",
-        "build:test" => "RAILS_ENV=test NODE_ENV=test bin/shakapacker"
-      }.freeze
-      private_constant :DEFAULT_PACKAGE_JSON_SCRIPTS
+      # RAILS_ENV=production runs the hook with production Rails config, while
+      # NODE_ENV=production makes Shakapacker emit a minified production bundle.
+      def default_package_json_scripts
+        {
+          "build" => shakapacker_build_command(env: "RAILS_ENV=production NODE_ENV=production"),
+          "build:test" => shakapacker_build_command(env: "RAILS_ENV=test NODE_ENV=test", environment: "test")
+        }
+      end
 
       def add_package_json_scripts
         return if options[:pretend]
@@ -317,7 +338,7 @@ module ReactOnRails
 
         original_text = File.read(package_json_path)
         existing_scripts = JSON.parse(original_text)["scripts"] || {}
-        scripts_to_add = DEFAULT_PACKAGE_JSON_SCRIPTS.reject { |key, _| existing_scripts.key?(key) }
+        scripts_to_add = default_package_json_scripts.reject { |key, _| existing_scripts.key?(key) }
 
         if scripts_to_add.empty?
           say_status :skip, "build scripts already present in package.json", :yellow
@@ -690,7 +711,10 @@ module ReactOnRails
         flags = []
         flags << "--redux" if options.redux?
         flags << "--typescript" if options.typescript?
-        flags << "--rspack" if options.rspack?
+        # Echo the resolved bundler choice (normalized to --rspack/--no-rspack, so a --webpack
+        # alias re-runs as --no-rspack) only when the user passed one explicitly. An unset choice
+        # re-resolves to the fresh-install default on re-run, so we don't pin it here.
+        flags << (using_rspack? ? "--rspack" : "--no-rspack") if bundler_flag_given?
 
         if options.rsc?
           flags << "--rsc"
@@ -838,11 +862,14 @@ module ReactOnRails
 
         seed_package_manager_in_package_json_from_lockfile!
 
-        # Then run the shakapacker installer
-        # Use options.rspack? directly (not using_rspack?): shakapacker.yml doesn't exist yet at this
-        # point, so using_rspack? would fall back to rspack_configured_in_project? which returns false,
-        # causing Shakapacker to install webpack configs into config/webpack/ instead of rspack.
-        shakapacker_install_env = options.rspack? ? { "SHAKAPACKER_ASSETS_BUNDLER" => "rspack" } : {}
+        # Then run the shakapacker installer.
+        # Resolve the bundler via using_rspack?. shakapacker.yml doesn't exist yet at this point,
+        # so the fresh-install default applies: an unset --rspack flag resolves to Rspack when
+        # Shakapacker supports it (shakapacker_version_9_or_higher? is optimistically true on a
+        # brand-new install where Shakapacker isn't loaded yet). An explicit --no-rspack still
+        # selects Webpack. using_rspack? memoizes, so the rest of the run (e.g.
+        # configure_rspack_in_shakapacker) stays consistent with this decision.
+        shakapacker_install_env = using_rspack? ? { "SHAKAPACKER_ASSETS_BUNDLER" => "rspack" } : {}
         success = Bundler.with_unbundled_env do
           system(shakapacker_install_env, "bundle exec rails shakapacker:install")
         end

data/lib/generators/react_on_rails/js_dependency_manager.rb

@@ -578,12 +578,19 @@ module ReactOnRails
         end
 
         File.write("package.json", "#{JSON.pretty_generate(content)}\n")
+        GeneratorMessages.add_warning(package_json_pin_fallback_warning(versioned_packages))
         true
       rescue StandardError => e
         GeneratorMessages.add_warning("⚠️  Could not write dependency pins to package.json: #{e.message}")
         false
       end
 
+      def package_json_pin_fallback_warning(versioned_packages)
+        pinned_list = versioned_packages.map { |name, version| "#{name}@#{version}" }.join(", ")
+        "⚠️  Package manager install failed. Wrote the following version pins to package.json " \
+          "so you can rerun your package manager manually: #{pinned_list}"
+      end
+
       def fallback_package_manager
         package_manager = GeneratorMessages.detect_package_manager(app_root: destination_root)
         return package_manager if GeneratorMessages.supported_package_manager?(package_manager)

data/lib/generators/react_on_rails/pro_setup.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "securerandom"
 require_relative "generator_messages"
 require "react_on_rails/node_renderer_procfile"
 require "react_on_rails/pro_migration"
@@ -46,16 +47,58 @@ module ReactOnRails
         say set_color("🚀 REACT ON RAILS PRO SETUP", :cyan, :bold)
         say set_color("=" * 80, :cyan)
 
-        create_pro_initializer
+        # The Rails initializer and Node renderer bootstrap must share the same
+        # password literal. Only mint a fresh random password when BOTH files will
+        # be created — otherwise nil so each template falls back to the env-only
+        # branch, avoiding a literal mismatch with any existing file.
+        # Always reassign so a stale value from a prior invocation on the same
+        # instance can't leak into a later partial-install run.
+        @generated_renderer_password = nil
+        if pro_initializer_will_be_created? && node_renderer_will_be_created?
+          @generated_renderer_password = SecureRandom.hex(32)
+        end
+
+        initializer_created = create_pro_initializer
         legacy_renderer_detected = create_node_renderer
         add_pro_to_procfiles unless legacy_renderer_detected
         update_webpack_config_for_pro
 
+        say_renderer_password_setup_summary(initializer_created)
+
         say set_color("=" * 80, :cyan)
         say "✅ React on Rails Pro setup complete!", :green
         say set_color("=" * 80, :cyan)
       end
 
+      def say_renderer_password_setup_summary(initializer_created)
+        if @generated_renderer_password
+          say ""
+          say set_color("🔐 A random renderer password was written into your config files.", :yellow, :bold)
+          say "   For production, set RENDERER_PASSWORD as an env var instead and"
+          say "   remove the literal value from version control."
+          say "   See: https://www.shakacode.com/react-on-rails/docs/pro/node-renderer/"
+          say ""
+        elsif initializer_created
+          # Initializer was newly created but the Node renderer file already exists;
+          # the new initializer falls back to ENV["RENDERER_PASSWORD"] only so it doesn't
+          # disagree with whatever literal the existing renderer file contains.
+          say ""
+          say set_color("⚠️  Existing Node renderer detected — Rails initializer uses " \
+                        "ENV[\"RENDERER_PASSWORD\"] only.", :yellow, :bold)
+          say "   Set RENDERER_PASSWORD in your environment to match the password in your existing renderer."
+          say ""
+        end
+      end
+
+      def pro_initializer_will_be_created?
+        !File.exist?(File.join(destination_root, "config/initializers/react_on_rails_pro.rb"))
+      end
+
+      def node_renderer_will_be_created?
+        !File.exist?(File.join(destination_root, "renderer/node-renderer.js")) &&
+          !File.exist?(File.join(destination_root, "client/node-renderer.js"))
+      end
+
       # 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
@@ -205,14 +248,18 @@ module ReactOnRails
 
         if File.exist?(File.join(destination_root, initializer_path))
           say "ℹ️  #{initializer_path} already exists, skipping", :yellow
-          return
+          return false
         end
 
         say "📝 Creating React on Rails Pro initializer...", :yellow
 
+        # @generated_renderer_password is set by setup_pro only when both this
+        # file and the Node renderer bootstrap will be created together; nil here
+        # means the template emits the env-only fallback (no literal password).
         template("templates/pro/base/config/initializers/react_on_rails_pro.rb.tt", initializer_path)
 
         say "✅ Created #{initializer_path}", :green
+        true
       end
 
       # Matches active (uncommented) Procfile.dev node-renderer lines that
@@ -267,6 +314,11 @@ module ReactOnRails
               "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_procfile_command('Procfile.dev')}", :yellow
+          say set_color(
+            "⚠️  Ensure the password in #{legacy_node_renderer_path} matches " \
+            "config/initializers/react_on_rails_pro.rb. Both must use the same RENDERER_PASSWORD.",
+            :yellow
+          )
           warn_on_stale_legacy_procfile_entry
           return true
         end
@@ -275,8 +327,8 @@ module ReactOnRails
 
         empty_directory("renderer")
 
-        template_path = "templates/pro/base/renderer/node-renderer.js"
-        copy_file(template_path, node_renderer_path)
+        template_path = "templates/pro/base/renderer/node-renderer.js.tt"
+        template(template_path, node_renderer_path)
 
         say "✅ Created #{node_renderer_path}", :green
         false