react_on_rails 16.2.0.beta.10 → 16.2.0.beta.12

data/bin/ci-run-failed-specs

@@ -139,10 +139,12 @@ echo ""
 
 # Determine the working directory (check if we need to be in spec/dummy)
 WORKING_DIR="."
-if [ ${#UNIQUE_SPECS[@]} -gt 0 ] && ([[ "${UNIQUE_SPECS[0]}" == *"spec/system"* ]] || [[ "${UNIQUE_SPECS[0]}" == *"spec/helpers"* ]]); then
-  if [ -d "spec/dummy" ]; then
-    WORKING_DIR="spec/dummy"
-    echo -e "${BLUE}Running from spec/dummy directory${NC}"
+if [ ${#UNIQUE_SPECS[@]} -gt 0 ]; then
+  if [[ "${UNIQUE_SPECS[0]}" == *"spec/system"* ]] || [[ "${UNIQUE_SPECS[0]}" == *"spec/helpers"* ]]; then
+    if [ -d "spec/dummy" ]; then
+      WORKING_DIR="spec/dummy"
+      echo -e "${BLUE}Running from spec/dummy directory${NC}"
+    fi
   fi
 fi
 

data/bin/ci-switch-config

@@ -255,9 +255,10 @@ EOF
   set_node_version "20.18.1" "$VERSION_MANAGER"
 
   # Run conversion script
-  # NOTE: This uses whatever 'ruby' is in PATH after version manager updates above.
-  # The version manager may not have reloaded yet, so ensure your current Ruby is
-  # compatible with script/convert (Ruby 2.6+ should work).
+  # NOTE: This executes 'ruby' before the version manager reloads in your current shell.
+  # The script/convert file requires Ruby 2.6+ and uses basic file I/O operations.
+  # Most modern Ruby versions (2.6+) are compatible. The version manager changes above
+  # only take effect after shell reload, so this uses your current Ruby installation.
   print_header "Running script/convert to downgrade dependencies"
   cd "$PROJECT_ROOT"
   ruby script/convert

data/lib/generators/react_on_rails/base_generator.rb

@@ -101,7 +101,8 @@ module ReactOnRails
         puts "Adding Shakapacker #{ReactOnRails::PackerUtils.shakapacker_version} config"
         base_path = "base/base/"
         config = "config/shakapacker.yml"
-        copy_file("#{base_path}#{config}", config)
+        # Use template to enable version-aware configuration
+        template("#{base_path}#{config}.tt", config)
         configure_rspack_in_shakapacker if options.rspack?
       end
 

data/lib/generators/react_on_rails/generator_helper.rb

@@ -95,4 +95,33 @@ module GeneratorHelper
   def component_extension(options)
     options.typescript? ? "tsx" : "jsx"
   end
+
+  # Check if Shakapacker 9.0 or higher is available
+  # Returns true if Shakapacker >= 9.0, false otherwise
+  #
+  # This method is used during code generation to determine which configuration
+  # patterns to use in generated files (e.g., config.privateOutputPath vs hardcoded paths).
+  #
+  # @return [Boolean] true if Shakapacker 9.0+ is available or likely to be installed
+  #
+  # @note Default behavior: Returns true when Shakapacker is not yet installed
+  #   Rationale: During fresh installations, we optimistically assume users will install
+  #   the latest Shakapacker version. This ensures new projects get best-practice configs.
+  #   If users later install an older version, the generated webpack config includes
+  #   fallback logic (e.g., `config.privateOutputPath || hardcodedPath`) that prevents
+  #   breakage, and validation warnings guide them to fix any misconfigurations.
+  def shakapacker_version_9_or_higher?
+    return @shakapacker_version_9_or_higher if defined?(@shakapacker_version_9_or_higher)
+
+    @shakapacker_version_9_or_higher = begin
+      # If Shakapacker is not available yet (fresh install), default to true
+      # since we're likely installing the latest version
+      return true unless defined?(ReactOnRails::PackerUtils)
+
+      ReactOnRails::PackerUtils.shakapacker_version_requirement_met?("9.0.0")
+    rescue StandardError
+      # If we can't determine version, assume latest
+      true
+    end
+  end
 end

data/lib/generators/react_on_rails/js_dependency_manager.rb

@@ -123,14 +123,36 @@ module ReactOnRails
       end
 
       def add_react_on_rails_package
-        # Use exact version match between gem and npm package for stable releases
-        # For pre-release versions (e.g., 16.1.0-rc.1), use latest to avoid installing
-        # a version that may not exist in the npm registry
-        major_minor_patch_only = /\A\d+\.\d+\.\d+\z/
-        react_on_rails_pkg = if ReactOnRails::VERSION.match?(major_minor_patch_only)
-                               "react-on-rails@#{ReactOnRails::VERSION}"
+        # Use exact version match between gem and npm package for all versions including pre-releases
+        # Ruby gem versions use dots (16.2.0.beta.10) but npm requires hyphens (16.2.0-beta.10)
+        # This method converts between the two formats.
+        #
+        # The regex matches:
+        # - Stable: 16.2.0
+        # - Beta (Ruby): 16.2.0.beta.10 or (npm): 16.2.0-beta.10
+        # - RC (Ruby): 16.1.0.rc.1 or (npm): 16.1.0-rc.1
+        # - Alpha (Ruby): 16.0.0.alpha.5 or (npm): 16.0.0-alpha.5
+        # This ensures beta/rc versions use the exact version instead of "latest" which would
+        # install the latest stable release and cause version mismatches.
+
+        # Accept both dot and hyphen separators for pre-release versions
+        version_with_optional_prerelease = /\A(\d+\.\d+\.\d+)([-.]([a-zA-Z0-9.]+))?\z/
+
+        react_on_rails_pkg = if (match = ReactOnRails::VERSION.match(version_with_optional_prerelease))
+                               base_version = match[1]
+                               prerelease = match[3]
+
+                               # Convert Ruby gem format (dot) to npm semver format (hyphen)
+                               npm_version = if prerelease
+                                               "#{base_version}-#{prerelease}"
+                                             else
+                                               base_version
+                                             end
+
+                               "react-on-rails@#{npm_version}"
                              else
-                               puts "Adding the latest react-on-rails NPM module. " \
+                               puts "WARNING: Unrecognized version format #{ReactOnRails::VERSION}. " \
+                                    "Adding the latest react-on-rails NPM module. " \
                                     "Double check this is correct in package.json"
                                "react-on-rails"
                              end

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

@@ -12,6 +12,25 @@ ReactOnRails.configure do |config|
   # Set to "" if you're not using server rendering
   config.server_bundle_js_file = "server-bundle.js"
 
+  # ⚠️ RECOMMENDED: Use Shakapacker 9.0+ private_output_path instead
+  #
+  # If using Shakapacker 9.0+, add to config/shakapacker.yml:
+  #   private_output_path: ssr-generated
+  #
+  # React on Rails will auto-detect this value, eliminating the need to set it here.
+  # This keeps your webpack and Rails configs in sync automatically.
+  #
+  # For older Shakapacker versions or custom setups, manually configure:
+  # config.server_bundle_output_path = "ssr-generated"
+  #
+  # The path is relative to Rails.root and should point to a private directory
+  # (outside of public/) for security. Run 'rails react_on_rails:doctor' to verify.
+
+  # Enforce that server bundles are only loaded from private (non-public) directories.
+  # When true, server bundles will only be loaded from the configured server_bundle_output_path.
+  # This is recommended for production to prevent server-side code from being exposed.
+  config.enforce_private_server_bundles = true
+
   ################################################################################
   # Test Configuration (Optional)
   ################################################################################

data/lib/generators/react_on_rails/templates/base/base/config/{shakapacker.yml → shakapacker.yml.tt}

@@ -29,6 +29,15 @@ default: &default
   # Location for manifest.json, defaults to {public_output_path}/manifest.json if unset
   # manifest_path: public/packs/manifest.json
 
+  # Location for private server-side bundles (e.g., for SSR)
+  # These bundles are not served publicly, unlike public_output_path
+  # Shakapacker 9.0+ feature - automatically detected by React on Rails
+<% if shakapacker_version_9_or_higher? -%>
+  private_output_path: ssr-generated
+<% else -%>
+  # private_output_path: ssr-generated  # Uncomment to enable (requires Shakapacker 9.0+)
+<% end -%>
+
   # Additional paths webpack should look up modules
   # ['app/assets', 'engine/foo/app/assets']
   additional_paths: []

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

@@ -44,19 +44,53 @@ const configureServer = () => {
   };
   serverWebpackConfig.plugins.unshift(new bundler.optimize.LimitChunkCountPlugin({ maxChunks: 1 }));
 
-  // Custom output for the server-bundle that matches the config in
-  // config/initializers/react_on_rails.rb
-  // Server bundles are output to a private directory (not public) for security
+  // Custom output for the server-bundle
+<% if shakapacker_version_9_or_higher? -%>
+  // Using Shakapacker 9.0+ privateOutputPath for automatic sync with shakapacker.yml
+  // This eliminates manual path configuration and keeps configs in sync.
+  // Falls back to hardcoded path if private_output_path is not configured.
+  const serverBundleOutputPath = config.privateOutputPath ||
+    require('path').resolve(__dirname, '../../ssr-generated');
+<% else -%>
+  // Using hardcoded path (Shakapacker < 9.0)
+  // For Shakapacker 9.0+, consider using config.privateOutputPath instead
+  // to automatically sync with shakapacker.yml private_output_path.
+  const serverBundleOutputPath = require('path').resolve(__dirname, '../../ssr-generated');
+<% end -%>
+
   serverWebpackConfig.output = {
     filename: 'server-bundle.js',
     globalObject: 'this',
     // If using the React on Rails Pro node server renderer, uncomment the next line
     // libraryTarget: 'commonjs2',
-    path: require('path').resolve(__dirname, '../../ssr-generated'),
+    path: serverBundleOutputPath,
     // No publicPath needed since server bundles are not served via web
     // https://webpack.js.org/configuration/output/#outputglobalobject
   };
 
+  // Validate server bundle output path configuration
+<% if shakapacker_version_9_or_higher? -%>
+  // For Shakapacker 9.0+, verify privateOutputPath is configured in shakapacker.yml
+  if (!config.privateOutputPath) {
+    console.warn('⚠️  Shakapacker 9.0+ detected but private_output_path not configured in shakapacker.yml');
+    console.warn('   Add to config/shakapacker.yml:');
+    console.warn('     private_output_path: ssr-generated');
+    console.warn('   Run: rails react_on_rails:doctor to validate your configuration');
+  }
+<% else -%>
+  // For Shakapacker < 9.0, verify hardcoded path syncs with Rails config
+  // 1. Ensure config/initializers/react_on_rails.rb has: config.server_bundle_output_path = "ssr-generated"
+  // 2. Run: rails react_on_rails:doctor to verify configuration
+  const fs = require('fs');
+  if (!fs.existsSync(serverBundleOutputPath)) {
+    console.warn(`⚠️  Server bundle output directory does not exist: ${serverBundleOutputPath}`);
+    console.warn('   It will be created during build, but ensure React on Rails is configured:');
+    console.warn('   config.server_bundle_output_path = "ssr-generated" in config/initializers/react_on_rails.rb');
+    console.warn('   Run: rails react_on_rails:doctor to validate your configuration');
+  }
+<% end -%>
+
+
   // Don't hash the server bundle b/c would conflict with the client manifest
   // And no need for the MiniCssExtractPlugin
   serverWebpackConfig.plugins = serverWebpackConfig.plugins.filter(

data/lib/react_on_rails/configuration.rb

@@ -1,5 +1,23 @@
 # frozen_string_literal: true
 
+require "active_support/core_ext/enumerable"
+require "active_support/core_ext/object/blank"
+
+# Polyfill for compact_blank (added in Rails 6.1) to support Rails 5.2-6.0
+unless [].respond_to?(:compact_blank)
+  module Enumerable
+    def compact_blank
+      reject(&:blank?)
+    end
+  end
+
+  class Array
+    def compact_blank
+      reject(&:blank?)
+    end
+  end
+end
+
 # rubocop:disable Metrics/ClassLength
 
 module ReactOnRails
@@ -10,6 +28,7 @@ module ReactOnRails
 
   DEFAULT_GENERATED_ASSETS_DIR = File.join(%w[public webpack], Rails.env).freeze
   DEFAULT_COMPONENT_REGISTRY_TIMEOUT = 5000
+  DEFAULT_SERVER_BUNDLE_OUTPUT_PATH = "ssr-generated"
 
   def self.configuration
     @configuration ||= Configuration.new(
@@ -46,7 +65,7 @@ module ReactOnRails
       # Set to 0 to disable the timeout and wait indefinitely for component registration.
       component_registry_timeout: DEFAULT_COMPONENT_REGISTRY_TIMEOUT,
       generated_component_packs_loading_strategy: nil,
-      server_bundle_output_path: "ssr-generated",
+      server_bundle_output_path: DEFAULT_SERVER_BUNDLE_OUTPUT_PATH,
       enforce_private_server_bundles: false
     )
   end
@@ -184,6 +203,7 @@ module ReactOnRails
       check_component_registry_timeout
       validate_generated_component_packs_loading_strategy
       validate_enforce_private_server_bundles
+      auto_detect_server_bundle_path_from_shakapacker
     end
 
     private
@@ -257,6 +277,57 @@ module ReactOnRails
                                  "the public directory. Please set it to a directory outside of public."
     end
 
+    # Auto-detect server_bundle_output_path from Shakapacker 9.0+ private_output_path
+    # Checks if user explicitly set a value and warns them to use auto-detection instead
+    def auto_detect_server_bundle_path_from_shakapacker
+      # Skip if Shakapacker is not available
+      return unless defined?(::Shakapacker)
+
+      # Check if Shakapacker config has private_output_path method (9.0+)
+      return unless ::Shakapacker.config.respond_to?(:private_output_path)
+
+      # Get the private_output_path from Shakapacker
+      private_path = ::Shakapacker.config.private_output_path
+      return unless private_path
+
+      relative_path = ReactOnRails::Utils.normalize_to_relative_path(private_path)
+
+      # Check if user explicitly configured server_bundle_output_path
+      if server_bundle_output_path != ReactOnRails::DEFAULT_SERVER_BUNDLE_OUTPUT_PATH
+        warn_about_explicit_configuration(relative_path)
+        return
+      end
+
+      apply_shakapacker_private_output_path(relative_path)
+    rescue StandardError => e
+      # Fail gracefully - if auto-detection fails, keep the default
+      Rails.logger&.debug("ReactOnRails: Could not auto-detect server bundle path from " \
+                          "Shakapacker: #{e.message}")
+    end
+
+    def warn_about_explicit_configuration(shakapacker_path)
+      # Normalize both paths for comparison
+      normalized_config = server_bundle_output_path.to_s.chomp("/")
+      normalized_shakapacker = shakapacker_path.to_s.chomp("/")
+
+      # Only warn if there's a mismatch
+      return if normalized_config == normalized_shakapacker
+
+      Rails.logger&.warn(
+        "ReactOnRails: server_bundle_output_path is explicitly set to '#{server_bundle_output_path}' " \
+        "but shakapacker.yml private_output_path is '#{shakapacker_path}'. " \
+        "Consider removing server_bundle_output_path from your React on Rails initializer " \
+        "to use the auto-detected value from shakapacker.yml."
+      )
+    end
+
+    def apply_shakapacker_private_output_path(relative_path)
+      self.server_bundle_output_path = relative_path
+
+      Rails.logger&.debug("ReactOnRails: Auto-detected server_bundle_output_path from " \
+                          "shakapacker.yml private_output_path: '#{relative_path}'")
+    end
+
     def check_minimum_shakapacker_version
       ReactOnRails::PackerUtils.raise_shakapacker_version_incompatible_for_basic_pack_generation unless
         ReactOnRails::PackerUtils.supports_basic_pack_generation?
@@ -358,15 +429,23 @@ module ReactOnRails
     end
 
     def ensure_webpack_generated_files_exists
-      return unless webpack_generated_files.empty?
-
-      self.webpack_generated_files = [
-        "manifest.json",
-        server_bundle_js_file,
-        rsc_bundle_js_file,
-        react_client_manifest_file,
-        react_server_client_manifest_file
-      ].compact_blank
+      all_required_files = ["manifest.json", server_bundle_js_file]
+
+      if ReactOnRails::Utils.react_on_rails_pro?
+        pro_config = ReactOnRailsPro.configuration
+        all_required_files << pro_config.rsc_bundle_js_file
+        all_required_files << pro_config.react_client_manifest_file
+        all_required_files << pro_config.react_server_client_manifest_file
+      end
+
+      all_required_files = all_required_files.compact_blank
+
+      if webpack_generated_files.empty?
+        self.webpack_generated_files = all_required_files
+      else
+        missing_files = all_required_files.reject { |file| webpack_generated_files.include?(file) }
+        self.webpack_generated_files += missing_files if missing_files.any?
+      end
     end
 
     def configure_skip_display_none_deprecation

data/lib/react_on_rails/dev/pack_generator.rb

@@ -2,6 +2,7 @@
 
 require "English"
 require "stringio"
+require_relative "../packer_utils"
 
 module ReactOnRails
   module Dev
@@ -37,29 +38,40 @@ module ReactOnRails
 
           if verbose
             puts "📦 Generating React on Rails packs..."
-            success = run_pack_generation
+            success = run_pack_generation(silent: false, verbose: true)
           else
             print "📦 Generating packs... "
-            success = run_pack_generation(silent: true)
+            success = run_pack_generation(silent: true, verbose: false)
             puts success ? "✅" : "❌"
           end
 
           return if success
 
           puts "❌ Pack generation failed"
+          unless verbose
+            puts ""
+            puts "💡 Run with #{Rainbow('--verbose').cyan.bold} flag for detailed output:"
+            puts "   #{Rainbow('bin/dev --verbose').green.bold}"
+          end
           exit 1
         end
 
         private
 
-        def run_pack_generation(silent: false)
+        def run_pack_generation(silent: false, verbose: false)
+          # Set environment variable for child processes to respect verbose mode
+          ENV["REACT_ON_RAILS_VERBOSE"] = verbose ? "true" : "false"
+
           # If we're already inside a Bundler context AND Rails is available (e.g., called from bin/dev),
           # we can directly require and run the task. Otherwise, use bundle exec.
           if should_run_directly?
             run_rake_task_directly(silent: silent)
           else
-            run_via_bundle_exec(silent: silent)
+            run_via_bundle_exec(silent: silent, verbose: verbose)
           end
+        ensure
+          # Clean up environment variable
+          ENV.delete("REACT_ON_RAILS_VERBOSE")
         end
 
         def should_run_directly?
@@ -139,14 +151,40 @@ module ReactOnRails
           # rubocop:enable Style/StderrPuts, Style/GlobalStdStream
         end
 
-        def run_via_bundle_exec(silent: false)
-          if silent
-            system(
-              "bundle", "exec", "rake", "react_on_rails:generate_packs",
-              out: File::NULL, err: File::NULL
-            )
+        def run_via_bundle_exec(silent: false, verbose: false)
+          # Environment variable is already set in run_pack_generation, but we make it explicit here
+          # for clarity and to ensure it's passed to the subprocess
+          env = { "REACT_ON_RAILS_VERBOSE" => verbose ? "true" : "false" }
+
+          # Need to unbundle to prevent Bundler from intercepting our bundle exec call
+          # when already running inside a Bundler context (e.g., from bin/dev)
+          with_unbundled_context do
+            if silent
+              system(
+                env,
+                "bundle", "exec", "rake", "react_on_rails:generate_packs",
+                out: File::NULL, err: File::NULL
+              )
+            else
+              system(env, "bundle", "exec", "rake", "react_on_rails:generate_packs")
+            end
+          end
+        end
+
+        # DRY helper method for Bundler context switching with API compatibility
+        # Supports both new (with_unbundled_env) and legacy (with_clean_env) Bundler APIs
+        def with_unbundled_context(&block)
+          if defined?(Bundler)
+            if Bundler.respond_to?(:with_unbundled_env)
+              Bundler.with_unbundled_env(&block)
+            elsif Bundler.respond_to?(:with_clean_env)
+              Bundler.with_clean_env(&block)
+            else
+              # Fallback if neither method is available (very old Bundler versions)
+              yield
+            end
           else
-            system("bundle", "exec", "rake", "react_on_rails:generate_packs")
+            yield
           end
         end
       end

data/lib/react_on_rails/dev/server_manager.rb

@@ -3,6 +3,7 @@
 require "English"
 require "open3"
 require "rainbow"
+require_relative "../packer_utils"
 
 module ReactOnRails
   module Dev

data/lib/react_on_rails/doctor.rb

@@ -667,6 +667,7 @@ module ReactOnRails
       end
     end
 
+    # rubocop:disable Metrics/CyclomaticComplexity
     def analyze_server_rendering_config(content)
       checker.add_info("\n🖥️  Server Rendering:")
 
@@ -678,6 +679,19 @@ module ReactOnRails
         checker.add_info("  server_bundle_js_file: server-bundle.js (default)")
       end
 
+      # Server bundle output path
+      server_bundle_path_match = content.match(/config\.server_bundle_output_path\s*=\s*["']([^"']+)["']/)
+      default_path = ReactOnRails::DEFAULT_SERVER_BUNDLE_OUTPUT_PATH
+      rails_bundle_path = server_bundle_path_match ? server_bundle_path_match[1] : default_path
+      checker.add_info("  server_bundle_output_path: #{rails_bundle_path}")
+
+      # Enforce private server bundles
+      enforce_private_match = content.match(/config\.enforce_private_server_bundles\s*=\s*([^\s\n,]+)/)
+      checker.add_info("  enforce_private_server_bundles: #{enforce_private_match[1]}") if enforce_private_match
+
+      # Check Shakapacker integration and provide recommendations
+      check_shakapacker_private_output_path(rails_bundle_path)
+
       # RSC bundle file (Pro feature)
       rsc_bundle_match = content.match(/config\.rsc_bundle_js_file\s*=\s*["']([^"']+)["']/)
       if rsc_bundle_match
@@ -702,9 +716,9 @@ module ReactOnRails
 
       checker.add_info("  raise_on_prerender_error: #{raise_on_error_match[1]}")
     end
-    # rubocop:enable Metrics/AbcSize
+    # rubocop:enable Metrics/CyclomaticComplexity
 
-    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/CyclomaticComplexity
     def analyze_performance_config(content)
       checker.add_info("\n⚡ Performance & Loading:")
 
@@ -1387,9 +1401,85 @@ module ReactOnRails
     end
 
     def log_debug(message)
-      return unless defined?(Rails.logger) && Rails.logger
+      Rails.logger&.debug(message)
+    end
+
+    # Check Shakapacker private_output_path integration and provide recommendations
+    def check_shakapacker_private_output_path(rails_bundle_path)
+      return report_no_shakapacker unless defined?(::Shakapacker)
+      return report_upgrade_shakapacker unless ::Shakapacker.config.respond_to?(:private_output_path)
+
+      check_shakapacker_9_private_output_path(rails_bundle_path)
+    rescue StandardError => e
+      checker.add_info("\n  ℹ️  Could not check Shakapacker config: #{e.message}")
+    end
+
+    def report_no_shakapacker
+      checker.add_info("\n  ℹ️  Shakapacker not detected - using manual configuration")
+    end
+
+    def report_upgrade_shakapacker
+      checker.add_info(<<~MSG.strip)
+        \n  💡 Recommendation: Upgrade to Shakapacker 9.0+
+
+        Shakapacker 9.0+ adds 'private_output_path' in shakapacker.yml for server bundles.
+        This eliminates the need to configure server_bundle_output_path separately.
+
+        Benefits:
+        - Single source of truth in shakapacker.yml
+        - Automatic detection by React on Rails
+        - No configuration duplication
+      MSG
+    end
+
+    def check_shakapacker_9_private_output_path(rails_bundle_path)
+      private_path = ::Shakapacker.config.private_output_path
+
+      if private_path
+        report_shakapacker_path_status(private_path, rails_bundle_path)
+      else
+        report_configure_private_output_path(rails_bundle_path)
+      end
+    end
+
+    def report_shakapacker_path_status(private_path, rails_bundle_path)
+      relative_path = ReactOnRails::Utils.normalize_to_relative_path(private_path)
+      # Normalize both paths for comparison (remove trailing slashes)
+      normalized_relative = relative_path.to_s.chomp("/")
+      normalized_rails = rails_bundle_path.to_s.chomp("/")
+
+      if normalized_relative == normalized_rails
+        checker.add_success("\n  ✅ Using Shakapacker 9.0+ private_output_path: '#{relative_path}'")
+        checker.add_info("     Auto-detected from shakapacker.yml - no manual config needed")
+      else
+        report_configuration_mismatch(relative_path, rails_bundle_path)
+      end
+    end
+
+    def report_configuration_mismatch(relative_path, rails_bundle_path)
+      checker.add_warning(<<~MSG.strip)
+        \n  ⚠️  Configuration mismatch detected!
+
+        Shakapacker private_output_path: '#{relative_path}'
+        React on Rails server_bundle_output_path: '#{rails_bundle_path}'
+
+        Recommendation: Remove server_bundle_output_path from your React on Rails
+        initializer and let it auto-detect from shakapacker.yml private_output_path.
+      MSG
+    end
+
+    def report_configure_private_output_path(rails_bundle_path)
+      checker.add_info(<<~MSG.strip)
+        \n  💡 Recommendation: Configure private_output_path in shakapacker.yml
+
+        Add to config/shakapacker.yml:
+          private_output_path: #{rails_bundle_path}
 
-      Rails.logger.debug(message)
+        This will:
+        - Keep webpack and Rails configs in sync automatically
+        - Enable auto-detection by React on Rails
+        - Serve as single source of truth for server bundle location
+      MSG
     end
   end
   # rubocop:enable Metrics/ClassLength