react_on_rails 16.1.2 → 16.2.0

data/lib/react_on_rails/doctor.rb

@@ -154,6 +154,7 @@ module ReactOnRails
     def check_configuration_details
       check_shakapacker_configuration_details
       check_react_on_rails_configuration_details
+      check_server_bundle_prerender_consistency
     end
 
     def check_bin_dev_launcher
@@ -166,6 +167,7 @@ module ReactOnRails
 
     def check_testing_setup
       check_rspec_helper_setup
+      check_build_test_configuration
     end
 
     def check_development
@@ -173,6 +175,7 @@ module ReactOnRails
       check_procfile_dev
       check_bin_dev_script
       check_gitignore
+      check_async_usage
     end
 
     def check_javascript_bundles
@@ -465,7 +468,6 @@ module ReactOnRails
       check_npm_wildcards
     end
 
-    # rubocop:disable Metrics/CyclomaticComplexity
     def check_gem_wildcards
       gemfile_path = ENV["BUNDLE_GEMFILE"] || "Gemfile"
       return unless File.exist?(gemfile_path)
@@ -487,9 +489,7 @@ module ReactOnRails
         # Ignore errors reading Gemfile
       end
     end
-    # rubocop:enable Metrics/CyclomaticComplexity
 
-    # rubocop:disable Metrics/CyclomaticComplexity
     def check_npm_wildcards
       return unless File.exist?("package.json")
 
@@ -511,7 +511,6 @@ module ReactOnRails
         # Ignore other errors
       end
     end
-    # rubocop:enable Metrics/CyclomaticComplexity
 
     def check_key_configuration_files
       files_to_check = {
@@ -535,7 +534,6 @@ module ReactOnRails
       check_server_rendering_engine
     end
 
-    # rubocop:disable Metrics/CyclomaticComplexity
     def check_layout_files
       layout_files = Dir.glob("app/views/layouts/**/*.erb")
       return if layout_files.empty?
@@ -562,7 +560,6 @@ module ReactOnRails
         end
       end
     end
-    # rubocop:enable Metrics/CyclomaticComplexity
 
     # rubocop:disable Metrics/CyclomaticComplexity
     def check_server_rendering_engine
@@ -600,7 +597,6 @@ module ReactOnRails
     end
     # rubocop:enable Metrics/CyclomaticComplexity
 
-    # rubocop:disable Metrics/CyclomaticComplexity
     def check_shakapacker_configuration_details
       return unless File.exist?("config/shakapacker.yml")
 
@@ -629,7 +625,6 @@ module ReactOnRails
         checker.add_warning("  ⚠️  Could not run 'rake shakapacker:info': #{e.message}")
       end
     end
-    # rubocop:enable Metrics/CyclomaticComplexity
 
     def check_react_on_rails_configuration_details
       check_react_on_rails_initializer
@@ -664,6 +659,7 @@ module ReactOnRails
       end
     end
 
+    # rubocop:disable Metrics/CyclomaticComplexity
     def analyze_server_rendering_config(content)
       checker.add_info("\n🖥️  Server Rendering:")
 
@@ -675,6 +671,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
@@ -699,9 +708,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:")
 
@@ -732,10 +741,12 @@ module ReactOnRails
       auto_load_match = content.match(/config\.auto_load_bundle\s*=\s*([^\s\n,]+)/)
       checker.add_info("  auto_load_bundle: #{auto_load_match[1]}") if auto_load_match
 
-      # Immediate hydration (Pro feature)
+      # Deprecated immediate_hydration setting
       immediate_hydration_match = content.match(/config\.immediate_hydration\s*=\s*([^\s\n,]+)/)
       if immediate_hydration_match
-        checker.add_info("  immediate_hydration: #{immediate_hydration_match[1]} (React on Rails Pro)")
+        checker.add_warning("  ⚠️  immediate_hydration: #{immediate_hydration_match[1]} (DEPRECATED)")
+        checker.add_info("    💡 This setting is no longer used. Immediate hydration is now automatic for Pro users.")
+        checker.add_info("    💡 Remove this line from your config/initializers/react_on_rails.rb file.")
       end
 
       # Component registry timeout
@@ -1108,6 +1119,124 @@ module ReactOnRails
       end
     end
 
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    def check_server_bundle_prerender_consistency
+      config_path = "config/initializers/react_on_rails.rb"
+      return unless File.exist?(config_path)
+
+      checker.add_info("\n🔍 Server Rendering Consistency:")
+
+      begin
+        content = File.read(config_path)
+
+        # Check for server bundle configuration
+        server_bundle_match = content.match(/config\.server_bundle_js_file\s*=\s*["']([^"']+)["']/)
+        server_bundle_set = server_bundle_match && server_bundle_match[1].present?
+
+        # Check for global prerender setting
+        prerender_match = content.match(/config\.prerender\s*=\s*(true)/)
+        prerender_set = prerender_match
+
+        # Check if prerender is used in views
+        uses_prerender = uses_prerender_in_views?
+
+        # Analyze the configuration
+        if (prerender_set || uses_prerender) && !server_bundle_set
+          checker.add_warning("  ⚠️  Server rendering is enabled but server_bundle_js_file is not configured")
+          checker.add_info("  💡 Set config.server_bundle_js_file = 'server-bundle.js' to enable SSR")
+          checker.add_info("  💡 See: https://www.shakacode.com/react-on-rails/docs/guides/server-rendering")
+        elsif server_bundle_set && !prerender_set && !uses_prerender
+          checker.add_info("  ℹ️  server_bundle_js_file is configured but prerender doesn't appear to be used")
+          checker.add_info("  💡 Either use prerender: true in react_component calls or remove server_bundle_js_file")
+        else
+          checker.add_success("  ✅ Server rendering configuration is consistent")
+        end
+      rescue StandardError => e
+        checker.add_warning("  ⚠️  Could not analyze server rendering configuration: #{e.message}")
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+    def uses_prerender_in_views?
+      # Check view files for prerender: true
+      view_files = Dir.glob("app/views/**/*.{erb,haml,slim}")
+      view_files.any? do |file|
+        next unless File.exist?(file)
+
+        File.read(file).match?(/prerender:\s*true/)
+      end
+    rescue StandardError
+      false
+    end
+
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength
+    def check_build_test_configuration
+      config_path = "config/initializers/react_on_rails.rb"
+      shakapacker_yml = "config/shakapacker.yml"
+
+      return unless File.exist?(config_path)
+
+      checker.add_info("\n🧪 Test Asset Compilation:")
+
+      begin
+        config_content = File.read(config_path)
+        has_build_test_command = config_content.match(/^\s*config\.build_test_command\s*=\s*["']([^"']+)["']/)
+        uses_test_helper = uses_react_on_rails_test_helper?
+
+        if File.exist?(shakapacker_yml)
+          shakapacker_content = File.read(shakapacker_yml)
+          # Match test section and look for compile: true
+          has_compile_true = shakapacker_content.match(/^test:.*?^\s+compile:\s*true/m)
+
+          if has_build_test_command && has_compile_true
+            checker.add_warning("  ⚠️  Both build_test_command and shakapacker compile: true are configured")
+            checker.add_info("  💡 These are mutually exclusive - use only one approach")
+            checker.add_info("  💡 Recommended: Use compile: true in shakapacker.yml (simpler)")
+            checker.add_info("  💡 Alternative: Use build_test_command with ReactOnRails::TestHelper (explicit control)")
+            checker.add_info("  📖 See: https://github.com/shakacode/react_on_rails/blob/master/docs/guides/testing-configuration.md")
+          elsif has_build_test_command && !uses_test_helper
+            checker.add_warning("  ⚠️  build_test_command is set but ReactOnRails::TestHelper is not configured")
+            checker.add_info("  💡 Add to spec/rails_helper.rb:")
+            checker.add_info("      ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)")
+            checker.add_info("  💡 Or remove build_test_command and use compile: true in shakapacker.yml")
+          elsif !has_build_test_command && uses_test_helper
+            checker.add_error("  🚫 ReactOnRails::TestHelper is configured but build_test_command is not set")
+            checker.add_info("  💡 Add to config/initializers/react_on_rails.rb:")
+            checker.add_info("      config.build_test_command = 'RAILS_ENV=test bin/shakapacker'")
+            checker.add_info("  💡 Or remove TestHelper and use compile: true in shakapacker.yml")
+          elsif !has_build_test_command && !has_compile_true && !uses_test_helper
+            checker.add_warning("  ⚠️  No test asset compilation configured")
+            checker.add_info("  💡 Recommended: Add to shakapacker.yml test section:")
+            checker.add_info("      compile: true")
+            checker.add_info("  📖 See: https://github.com/shakacode/react_on_rails/blob/master/docs/guides/testing-configuration.md")
+          elsif has_compile_true
+            checker.add_success("  ✅ Test assets configured via Shakapacker auto-compilation")
+            checker.add_info("      (compile: true in shakapacker.yml)")
+          elsif has_build_test_command && uses_test_helper
+            checker.add_success("  ✅ Test assets configured via React on Rails test helper")
+            checker.add_info("      (build_test_command + ReactOnRails::TestHelper)")
+          end
+        else
+          checker.add_warning("  ⚠️  config/shakapacker.yml not found")
+        end
+      rescue StandardError => e
+        checker.add_warning("  ⚠️  Could not analyze test configuration: #{e.message}")
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength
+
+    def uses_react_on_rails_test_helper?
+      spec_helpers = ["spec/rails_helper.rb", "spec/spec_helper.rb", "test/test_helper.rb"]
+      spec_helpers.any? do |helper|
+        next unless File.exist?(helper)
+
+        content = File.read(helper)
+        content.include?("configure_rspec_to_compile_assets") || content.include?("ensure_assets_compiled")
+      end
+    rescue StandardError
+      false
+    end
+
     def relativize_path(absolute_path)
       return absolute_path unless absolute_path.is_a?(String)
 
@@ -1144,6 +1273,206 @@ module ReactOnRails
         checker.add_info("  #{label}: <error reading value: #{e.message}>")
       end
     end
+
+    # Comment patterns used for filtering out commented async usage
+    ERB_COMMENT_PATTERN = /<%\s*#.*javascript_pack_tag/
+    HAML_COMMENT_PATTERN = /^\s*-#.*javascript_pack_tag/
+    SLIM_COMMENT_PATTERN = %r{^\s*/.*javascript_pack_tag}
+    HTML_COMMENT_PATTERN = /<!--.*javascript_pack_tag/
+
+    def check_async_usage
+      # When Pro is installed, async is fully supported and is the default behavior
+      # No need to check for async usage in this case
+      return if ReactOnRails::Utils.react_on_rails_pro?
+
+      async_issues = []
+
+      # Check 1: javascript_pack_tag with :async in view files
+      view_files_with_async = scan_view_files_for_async_pack_tag
+      unless view_files_with_async.empty?
+        async_issues << "javascript_pack_tag with :async found in view files:"
+        view_files_with_async.each do |file|
+          async_issues << "  • #{file}"
+        end
+      end
+
+      # Check 2: generated_component_packs_loading_strategy = :async
+      if config_has_async_loading_strategy?
+        async_issues << "config.generated_component_packs_loading_strategy = :async in initializer"
+      end
+
+      return if async_issues.empty?
+
+      # Report errors if async usage is found without Pro
+      checker.add_error("🚫 :async usage detected without React on Rails Pro")
+      async_issues.each { |issue| checker.add_error("  #{issue}") }
+      checker.add_info("  💡 :async can cause race conditions. Options:")
+      checker.add_info("    1. Upgrade to React on Rails Pro (recommended for :async support)")
+      checker.add_info("    2. Change to :defer or :sync loading strategy")
+      checker.add_info("  📖 https://www.shakacode.com/react-on-rails/docs/guides/configuration/")
+    end
+
+    def scan_view_files_for_async_pack_tag
+      view_patterns = ["app/views/**/*.erb", "app/views/**/*.haml", "app/views/**/*.slim"]
+      files_with_async = view_patterns.flat_map { |pattern| scan_pattern_for_async(pattern) }
+      files_with_async.compact
+    rescue Errno::ENOENT, Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError => e
+      # Log the error if Rails logger is available
+      log_debug("Error scanning view files for async: #{e.message}")
+      []
+    end
+
+    def scan_pattern_for_async(pattern)
+      Dir.glob(pattern).filter_map do |file|
+        next unless File.exist?(file)
+
+        content = File.read(file)
+        next if content_has_only_commented_async?(content)
+        next unless file_has_async_pack_tag?(content)
+
+        relativize_path(file)
+      end
+    end
+
+    def file_has_async_pack_tag?(content)
+      # Match javascript_pack_tag with :async symbol or async: true hash syntax
+      # Examples that should match:
+      #   - javascript_pack_tag "app", :async
+      #   - javascript_pack_tag "app", async: true
+      #   - javascript_pack_tag "app", :async, other_option: value
+      # Examples that should NOT match:
+      #   - javascript_pack_tag "app", defer: "async" (async is a string value, not the option)
+      #   - javascript_pack_tag "app", :defer
+      # Note: Theoretical edge case `data: { async: true }` would match but is extremely unlikely
+      # in real code and represents a harmless false positive (showing a warning when not needed)
+      # Use word boundary \b to ensure :async is not part of a longer symbol like :async_mode
+      # [^<]* allows matching across newlines within ERB tags but stops at closing ERB tag
+      content.match?(/javascript_pack_tag[^<]*(?::async\b|async:\s*true)/)
+    end
+
+    def content_has_only_commented_async?(content)
+      # Check if all occurrences of javascript_pack_tag with :async are in comments
+      # Returns true if ONLY commented async usage exists (no active async usage)
+
+      # First check if there's any javascript_pack_tag with :async in the full content
+      return true unless file_has_async_pack_tag?(content)
+
+      # Strategy: Remove all commented lines, then check if any :async remains
+      # This handles both single-line and multi-line tags correctly
+      uncommented_lines = content.each_line.reject do |line|
+        line.match?(ERB_COMMENT_PATTERN) ||
+          line.match?(HAML_COMMENT_PATTERN) ||
+          line.match?(SLIM_COMMENT_PATTERN) ||
+          line.match?(HTML_COMMENT_PATTERN)
+      end
+
+      uncommented_content = uncommented_lines.join
+      # If no async found in uncommented content, all async usage was commented
+      !file_has_async_pack_tag?(uncommented_content)
+    end
+
+    def config_has_async_loading_strategy?
+      config_path = "config/initializers/react_on_rails.rb"
+      return false unless File.exist?(config_path)
+
+      content = File.read(config_path)
+      # Check if generated_component_packs_loading_strategy is set to :async
+      # Filter out commented lines (lines starting with # after optional whitespace)
+      content.each_line.any? do |line|
+        # Skip lines that start with # (after optional whitespace)
+        next if line.match?(/^\s*#/)
+
+        # Match: config.generated_component_packs_loading_strategy = :async
+        # Use word boundary \b to ensure :async is the complete symbol, not part of :async_mode etc.
+        line.match?(/config\.generated_component_packs_loading_strategy\s*=\s*:async\b/)
+      end
+    rescue Errno::ENOENT, Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError => e
+      # Log the error if Rails logger is available
+      log_debug("Error checking async loading strategy: #{e.message}")
+      false
+    end
+
+    def log_debug(message)
+      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}
+
+        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
 end

data/lib/react_on_rails/engine.rb

@@ -4,8 +4,82 @@ require "rails/railtie"
 
 module ReactOnRails
   class Engine < ::Rails::Engine
+    # Validate package versions and compatibility on Rails startup
+    # This ensures the application fails fast if versions don't match or packages are misconfigured
+    # Skip validation during installation tasks (e.g., shakapacker:install) or generator runtime
+    initializer "react_on_rails.validate_version_and_package_compatibility" do
+      config.after_initialize do
+        next if Engine.skip_version_validation?
+
+        Rails.logger.info "[React on Rails] Validating package version and compatibility..."
+        VersionChecker.build.validate_version_and_package_compatibility!
+        Rails.logger.info "[React on Rails] Package validation successful"
+      end
+    end
+
+    # Determine if version validation should be skipped
+    #
+    # This method checks multiple conditions to determine if package version validation
+    # should be skipped. Validation is skipped during setup scenarios where the npm
+    # package isn't installed yet (e.g., during generator execution).
+    #
+    # @return [Boolean] true if validation should be skipped
+    #
+    # @note Thread Safety: ENV variables are process-global. In practice, Rails generators
+    #   run in a single process, so concurrent execution is not a concern. If running
+    #   generators concurrently (e.g., in parallel tests), ensure tests run in separate
+    #   processes to avoid ENV variable conflicts.
+    #
+    # @example Testing with parallel processes
+    #   # In RSpec configuration:
+    #   config.before(:each) do |example|
+    #     ENV.delete("REACT_ON_RAILS_SKIP_VALIDATION")
+    #   end
+    #
+    # @note Manual ENV Setting: While this ENV variable is designed to be set by generators,
+    #   users can manually set it (e.g., `REACT_ON_RAILS_SKIP_VALIDATION=true rails server`)
+    #   to bypass validation. This should only be done temporarily during debugging or
+    #   setup scenarios. The validation helps catch version mismatches early, so bypassing
+    #   it in production is not recommended.
+    def self.skip_version_validation?
+      # Skip if explicitly disabled via environment variable (set by generators)
+      # Using ENV variable instead of ARGV because Rails can modify/clear ARGV during
+      # initialization, making ARGV unreliable for detecting generator context. The ENV
+      # variable persists through the entire Rails initialization process.
+      if ENV["REACT_ON_RAILS_SKIP_VALIDATION"] == "true"
+        Rails.logger.debug "[React on Rails] Skipping validation - disabled via environment variable"
+        return true
+      end
+
+      # Check package.json first as it's cheaper and handles more cases
+      if package_json_missing?
+        Rails.logger.debug "[React on Rails] Skipping validation - package.json not found"
+        return true
+      end
+
+      # Skip during generator runtime since packages are installed during execution
+      # This is a fallback check in case ENV wasn't set, though ENV is the primary mechanism
+      if running_generator?
+        Rails.logger.debug "[React on Rails] Skipping validation during generator runtime"
+        return true
+      end
+
+      false
+    end
+
+    # Check if we're running a Rails generator
+    # @return [Boolean] true if running a generator
+    def self.running_generator?
+      !ARGV.empty? && ARGV.first&.in?(%w[generate g])
+    end
+
+    # Check if package.json doesn't exist yet
+    # @return [Boolean] true if package.json is missing
+    def self.package_json_missing?
+      !File.exist?(VersionChecker::NodePackageVersion.package_json_path)
+    end
+
     config.to_prepare do
-      VersionChecker.build.log_if_gem_and_node_package_versions_differ
       ReactOnRails::ServerRenderingPool.reset_pool
     end
 

data/lib/react_on_rails/git_utils.rb

@@ -5,7 +5,9 @@ require "English"
 module ReactOnRails
   module GitUtils
     def self.uncommitted_changes?(message_handler, git_installed: true)
-      return false if ENV["COVERAGE"] == "true"
+      # Skip check in CI environments - CI often makes temporary modifications
+      # (e.g., script/convert for minimum version testing) before running generators
+      return false if ENV["CI"] == "true" || ENV["COVERAGE"] == "true"
 
       status = `git status --porcelain`
       return false if git_installed && status&.empty?