Add validation and error messaging for hardcoded server bundle paths

Addresses review feedback to provide clear error messages when using
hardcoded paths with older Shakapacker versions.

Changes:
- Add runtime validation in serverWebpackConfig.js template for Shakapacker < 9.0
- Display helpful warning with configuration instructions if path doesn't exist
- Extract hardcoded "ssr-generated" to DEFAULT_SERVER_BUNDLE_OUTPUT_PATH constant
- Improve logging: use debug level for auto-detection (not user-initiated)
- Add documentation about absolute paths in normalize_to_relative_path

The validation helps users quickly identify configuration mismatches and
provides actionable guidance to fix them using rails react_on_rails:doctor.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: justin808

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

@@ -45,31 +45,39 @@ const configureServer = () => {
   serverWebpackConfig.plugins.unshift(new bundler.optimize.LimitChunkCountPlugin({ maxChunks: 1 }));
 
   // Custom output for the server-bundle
-  //<% if shakapacker_version_9_or_higher? %>
+<% 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.
-  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: config.privateOutputPath,
-    // No publicPath needed since server bundles are not served via web
-    // https://webpack.js.org/configuration/output/#outputglobalobject
-  };<% else %>
+<% 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.
+<% 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: <%= shakapacker_version_9_or_higher? ? 'config.privateOutputPath' : "require('path').resolve(__dirname, '../../ssr-generated')" %>,
     // No publicPath needed since server bundles are not served via web
     // https://webpack.js.org/configuration/output/#outputglobalobject
-  };<% end %>
+  };
+
+<% unless shakapacker_version_9_or_higher? -%>
+  // Validate hardcoded output path exists or can be created
+  // For Shakapacker < 9.0, we use a hardcoded path. To sync 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');
+  const serverBundlePath = serverWebpackConfig.output.path;
+  if (!fs.existsSync(serverBundlePath)) {
+    console.warn(`⚠️  Server bundle output directory does not exist: ${serverBundlePath}`);
+    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(

lib/react_on_rails/configuration.rb

@@ -10,6 +10,7 @@ def self.configure
 
   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 +47,7 @@ def self.configuration
       # 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
@@ -263,7 +264,7 @@ def validate_enforce_private_server_bundles
     # rubocop:disable Metrics/CyclomaticComplexity
     def auto_detect_server_bundle_path_from_shakapacker
       # Skip if user explicitly set server_bundle_output_path to something other than default
-      return if server_bundle_output_path != "ssr-generated"
+      return if server_bundle_output_path != ReactOnRails::DEFAULT_SERVER_BUNDLE_OUTPUT_PATH
 
       # Skip if Shakapacker is not available
       return unless defined?(::Shakapacker)
@@ -279,8 +280,8 @@ def auto_detect_server_bundle_path_from_shakapacker
         relative_path = ReactOnRails::Utils.normalize_to_relative_path(private_path)
         self.server_bundle_output_path = relative_path
 
-        Rails.logger&.info("ReactOnRails: Auto-detected server_bundle_output_path from " \
-                           "shakapacker.yml private_output_path: '#{relative_path}'")
+        Rails.logger&.debug("ReactOnRails: Auto-detected server_bundle_output_path from " \
+                            "shakapacker.yml 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 " \

lib/react_on_rails/doctor.rb

@@ -681,7 +681,8 @@ def analyze_server_rendering_config(content)
 
       # Server bundle output path
       server_bundle_path_match = content.match(/config\.server_bundle_output_path\s*=\s*["']([^"']+)["']/)
-      rails_bundle_path = server_bundle_path_match ? server_bundle_path_match[1] : "ssr-generated"
+      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

lib/react_on_rails/utils.rb

@@ -446,12 +446,16 @@ def self.package_manager_remove_command(package_name)
     # Converts an absolute path (String or Pathname) to a path relative to Rails.root.
     # If the path is already relative or doesn't contain Rails.root, returns it as-is.
     #
+    # Note: Absolute paths that don't start with Rails.root are intentionally passed through
+    # unchanged. This allows for explicit absolute paths to directories outside the Rails app.
+    #
     # @param path [String, Pathname] The path to normalize
     # @return [String] The relative path as a string
     #
     # @example
     #   normalize_to_relative_path("/app/ssr-generated") # => "ssr-generated"
     #   normalize_to_relative_path("ssr-generated")      # => "ssr-generated"
+    #   normalize_to_relative_path("/other/path/bundles") # => "/other/path/bundles" (unchanged)
     def self.normalize_to_relative_path(path)
       return nil if path.nil?