✨ Add --rails-env option for configurable asset precompilation environment

## New Feature
- Add `--rails-env` option to `bin/dev prod` for custom Rails environment during assets:precompile
- Default: NODE_ENV=production, RAILS_ENV=development (avoids credentials complexity)
- Option: `--rails-env=production` for full production Rails environment
- Clear documentation that option only affects assets:precompile, not server processes

## Enhanced Documentation
- Comprehensive help text with examples and environment explanations
- Clear runtime messaging about environment configuration
- Separation of asset precompilation vs server process environments
- Guidance on when to use each option

## Usage Examples
```bash
bin/dev prod                          # Default: production webpack, development Rails
bin/dev prod --rails-env=production   # Full production environment
bin/dev prod --route=dashboard        # Custom route in URLs
```

## Benefits
- ✅ Production webpack optimizations without production Rails complexity by default
- ✅ Option for full production environment when needed (testing credentials, etc.)
- ✅ Clear documentation prevents confusion about scope
- ✅ Better error handling with environment-specific guidance

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

Co-Authored-By: Claude <[email protected]>

Author: justin808

lib/react_on_rails/dev/server_manager.rb

@@ -8,10 +8,10 @@ module ReactOnRails
   module Dev
     class ServerManager
       class << self
-        def start(mode = :development, procfile = nil, verbose: false, route: nil)
+        def start(mode = :development, procfile = nil, verbose: false, route: nil, rails_env: nil)
           case mode
           when :production_like
-            run_production_like(_verbose: verbose, route: route)
+            run_production_like(_verbose: verbose, route: route, rails_env: rails_env)
           when :static
             procfile ||= "Procfile.dev-static-assets"
             run_static_development(procfile, verbose: verbose, route: route)
@@ -119,7 +119,7 @@ def show_help
         def run_from_command_line(args = ARGV)
           require "optparse"
 
-          options = { route: nil }
+          options = { route: nil, rails_env: nil }
 
           OptionParser.new do |opts|
             opts.banner = "Usage: dev [command] [options]"
@@ -128,6 +128,10 @@ def run_from_command_line(args = ARGV)
               options[:route] = route
             end
 
+            opts.on("--rails-env ENV", "Override RAILS_ENV for assets:precompile step only (prod mode only)") do |env|
+              options[:rails_env] = env
+            end
+
             opts.on("-h", "--help", "Prints this help") do
               show_help
               exit
@@ -140,7 +144,7 @@ def run_from_command_line(args = ARGV)
           # Main execution
           case command
           when "production-assets", "prod"
-            start(:production_like, nil, verbose: false, route: options[:route])
+            start(:production_like, nil, verbose: false, route: options[:route], rails_env: options[:rails_env])
           when "static"
             start(:static, "Procfile.dev-static-assets", verbose: false, route: options[:route])
           when "kill"
@@ -182,12 +186,21 @@ def help_commands
         end
         # rubocop:enable Metrics/AbcSize
 
+        # rubocop:disable Metrics/AbcSize
         def help_options
           <<~OPTIONS
             #{Rainbow('⚙️  OPTIONS:').cyan.bold}
-              #{Rainbow('--verbose, -v').green.bold}       #{Rainbow('Enable verbose output for pack generation').white}
+              #{Rainbow('--route ROUTE').green.bold}        #{Rainbow('Specify route to display in URLs (default: root)').white}
+              #{Rainbow('--rails-env ENV').green.bold}      #{Rainbow('Override RAILS_ENV for assets:precompile step only (prod mode only)').white}
+              #{Rainbow('--verbose, -v').green.bold}        #{Rainbow('Enable verbose output for pack generation').white}
+
+            #{Rainbow('📝 EXAMPLES:').cyan.bold}
+              #{Rainbow('bin/dev prod').green.bold}                    #{Rainbow('# NODE_ENV=production, RAILS_ENV=development').white}
+              #{Rainbow('bin/dev prod --rails-env=production').green.bold}  #{Rainbow('# NODE_ENV=production, RAILS_ENV=production').white}
+              #{Rainbow('bin/dev prod --route=dashboard').green.bold}       #{Rainbow('# Custom route in URLs').white}
           OPTIONS
         end
+        # rubocop:enable Metrics/AbcSize
 
         def help_customization
           <<~CUSTOMIZATION
@@ -225,17 +238,19 @@ def help_mode_details
 
             #{Rainbow('🏭 Production-assets mode').cyan.bold} - #{Rainbow('Procfile.dev-prod-assets').green}:
             #{Rainbow('•').yellow} #{Rainbow('React on Rails pack generation before Procfile start').white}
-            #{Rainbow('•').yellow} #{Rainbow('Asset precompilation with production optimizations').white}
-            #{Rainbow('•').yellow} #{Rainbow('Optimized, minified bundles').white}
-            #{Rainbow('•').yellow} #{Rainbow('Extracted CSS files (no FOUC)').white}
+            #{Rainbow('•').yellow} #{Rainbow('Asset precompilation with NODE_ENV=production (webpack optimizations)').white}
+            #{Rainbow('•').yellow} #{Rainbow('RAILS_ENV=development by default for assets:precompile (avoids credentials)').white}
+            #{Rainbow('•').yellow} #{Rainbow('Use --rails-env=production for assets:precompile only (not server processes)').white}
+            #{Rainbow('•').yellow} #{Rainbow('Server processes controlled by Procfile.dev-prod-assets environment').white}
+            #{Rainbow('•').yellow} #{Rainbow('Optimized, minified bundles with CSS extraction').white}
             #{Rainbow('•').yellow} #{Rainbow('No HMR (static assets)').white}
-            #{Rainbow('•').yellow} #{Rainbow('Slower recompilation').white}
             #{Rainbow('•').yellow} #{Rainbow('Access at:').white} #{Rainbow('http://localhost:3001/<route>').cyan.underline}
           MODES
         end
         # rubocop:enable Metrics/AbcSize
 
-        def run_production_like(_verbose: false, route: nil)
+        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+        def run_production_like(_verbose: false, route: nil, rails_env: nil)
           procfile = "Procfile.dev-prod-assets"
 
           print_procfile_info(procfile, route: route)
@@ -252,12 +267,33 @@ def run_production_like(_verbose: false, route: nil)
             route: route
           )
 
-          # Precompile assets in production mode (includes pack generation automatically)
-          puts "🔨 Precompiling assets..."
+          # Precompile assets with production webpack optimizations (includes pack generation automatically)
+          env_vars = ["NODE_ENV=production"]
+          env_vars << "RAILS_ENV=#{rails_env}" if rails_env
+          command = "#{env_vars.join(' ')} bundle exec rails assets:precompile"
+
+          puts "🔨 Precompiling assets with production webpack optimizations..."
+          puts ""
+
+          puts Rainbow("ℹ️  Asset Precompilation Environment:").blue
+          puts "   • NODE_ENV=production → Webpack optimizations (minification, compression)"
+          if rails_env
+            puts "   • RAILS_ENV=#{rails_env} → Custom Rails environment for assets:precompile only"
+            puts "   • Note: RAILS_ENV=production requires credentials, database setup, etc."
+            puts "   • Server processes will use environment from Procfile.dev-prod-assets"
+          else
+            puts "   • RAILS_ENV=development → Simpler Rails setup (no credentials needed)"
+            puts "   • Use --rails-env=production for assets:precompile step only"
+            puts "   • Server processes will use environment from Procfile.dev-prod-assets"
+            puts "   • Gets production webpack bundles without production Rails complexity"
+          end
+          puts ""
+          puts "#{Rainbow('💻 Running:').blue} #{command}"
+          puts ""
 
           # Capture both stdout and stderr
           require "open3"
-          stdout, stderr, status = Open3.capture3("RAILS_ENV=production NODE_ENV=production bundle exec rails assets:precompile")
+          stdout, stderr, status = Open3.capture3(command)
 
           if status.success?
             puts "✅ Assets precompiled successfully"
@@ -267,51 +303,69 @@ def run_production_like(_verbose: false, route: nil)
             puts "❌ Asset precompilation failed"
             puts ""
 
-            # Display the actual error output
-            unless stderr.empty?
-              puts "#{Rainbow('🚨 Error Output:').red.bold}"
-              puts stderr
-              puts ""
-            end
+            # Combine and display all output
+            all_output = []
+            all_output << stdout unless stdout.empty?
+            all_output << stderr unless stderr.empty?
 
-            unless stdout.empty? && stdout.strip != stderr.strip
-              puts "#{Rainbow('📋 Command Output:').yellow.bold}"
-              puts stdout
+            unless all_output.empty?
+              puts Rainbow("📋 Full Command Output:").red.bold
+              puts Rainbow("─" * 60).red
+              all_output.each { |output| puts output }
+              puts Rainbow("─" * 60).red
               puts ""
             end
 
-            puts "#{Rainbow('💡 Common fixes:').yellow.bold}"
+            puts Rainbow("🛠️  To debug this issue:").yellow.bold
+            puts "#{Rainbow('1.').cyan} #{Rainbow('Run the command separately to see detailed output:').white}"
+            puts "   #{Rainbow(command).cyan}"
+            puts ""
+            puts "#{Rainbow('2.').cyan} #{Rainbow('Add --trace for full stack trace:').white}"
+            puts "   #{Rainbow("#{command} --trace").cyan}"
+            puts ""
+            puts "#{Rainbow('3.').cyan} #{Rainbow('Or try with development webpack (faster, less optimized):').white}"
+            puts "   #{Rainbow('NODE_ENV=development bundle exec rails assets:precompile').cyan}"
+            puts ""
+
+            puts Rainbow("💡 Common fixes:").yellow.bold
 
             # Provide specific guidance based on error content
             error_content = "#{stderr} #{stdout}".downcase
 
             if error_content.include?("secret_key_base")
-              puts "#{Rainbow('•').yellow} #{Rainbow('Missing secret_key_base:').white.bold} Run #{Rainbow('bin/rails credentials:edit').cyan}"
+              puts "#{Rainbow('•').yellow} #{Rainbow('Missing secret_key_base:').white.bold} " \
+                   "Run #{Rainbow('bin/rails credentials:edit').cyan}"
             end
 
-            if error_content.include?("database") || error_content.include?("relation") || error_content.include?("table")
-              puts "#{Rainbow('•').yellow} #{Rainbow('Database issues:').white.bold} Run #{Rainbow('bin/rails db:create db:migrate').cyan}"
+            if error_content.include?("database") || error_content.include?("relation") ||
+               error_content.include?("table")
+              puts "#{Rainbow('•').yellow} #{Rainbow('Database issues:').white.bold} " \
+                   "Run #{Rainbow('bin/rails db:create db:migrate').cyan}"
             end
 
             if error_content.include?("gem") || error_content.include?("bundle") || error_content.include?("load error")
-              puts "#{Rainbow('•').yellow} #{Rainbow('Missing dependencies:').white.bold} Run #{Rainbow('bundle install && npm install').cyan}"
+              puts "#{Rainbow('•').yellow} #{Rainbow('Missing dependencies:').white.bold} " \
+                   "Run #{Rainbow('bundle install && npm install').cyan}"
             end
 
-            if error_content.include?("webpack") || error_content.include?("module") || error_content.include?("compilation")
-              puts "#{Rainbow('•').yellow} #{Rainbow('Webpack compilation:').white.bold} Check JavaScript/webpack errors above"
+            if error_content.include?("webpack") || error_content.include?("module") ||
+               error_content.include?("compilation")
+              puts "#{Rainbow('•').yellow} #{Rainbow('Webpack compilation:').white.bold} " \
+                   "Check JavaScript/webpack errors above"
             end
 
             # Always show these general options
-            puts "#{Rainbow('•').yellow} #{Rainbow('General debugging:').white} Run with #{Rainbow('--trace').cyan} for full stack trace"
-            puts "#{Rainbow('•').yellow} #{Rainbow('Environment issues:').white} Check #{Rainbow('config/environments/production.rb').cyan}"
+            puts "#{Rainbow('•').yellow} #{Rainbow('Environment config:').white} " \
+                 "Check #{Rainbow('config/environments/production.rb').cyan}"
 
             puts ""
-            puts "#{Rainbow('ℹ️  Alternative for development:').blue}"
+            puts Rainbow("ℹ️  Alternative for development:").blue
             puts "   #{Rainbow('bin/dev static').green}  # Static assets without production optimizations"
             puts ""
             exit 1
           end
         end
+        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
         def run_static_development(procfile, verbose: false, route: nil)
           print_procfile_info(procfile, route: route)