shakapacker 9.0.0 → 9.2.0

data/lib/shakapacker/bundler_switcher.rb

@@ -0,0 +1,329 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+
+module Shakapacker
+  # Provides functionality to switch between webpack and rspack bundlers
+  class BundlerSwitcher
+    SHAKAPACKER_CONFIG = "config/shakapacker.yml"
+    CUSTOM_DEPS_CONFIG = ".shakapacker-switch-bundler-dependencies.yml"
+
+    # Default dependencies for each bundler (package names only, no versions)
+    DEFAULT_RSPACK_DEPS = {
+      dev: %w[@rspack/cli @rspack/plugin-react-refresh],
+      prod: %w[@rspack/core rspack-manifest-plugin]
+    }.freeze
+
+    DEFAULT_WEBPACK_DEPS = {
+      dev: %w[webpack webpack-cli webpack-dev-server @pmmmwh/react-refresh-webpack-plugin @swc/core swc-loader],
+      prod: %w[webpack-assets-manifest webpack-merge]
+    }.freeze
+
+    attr_reader :root_path
+
+    def initialize(root_path = nil)
+      @root_path = root_path || (defined?(Rails) ? Rails.root : Pathname.new(Dir.pwd))
+    end
+
+    def current_bundler
+      config = load_yaml_config(config_path)
+      config.dig("default", "assets_bundler") || "webpack"
+    end
+
+    def switch_to(bundler, install_deps: false, no_uninstall: false)
+      unless %w[webpack rspack].include?(bundler)
+        raise ArgumentError, "Invalid bundler: #{bundler}. Must be 'webpack' or 'rspack'"
+      end
+
+      current = current_bundler
+      if current == bundler && !install_deps
+        puts "✅ Already using #{bundler}"
+        return
+      end
+
+      if current == bundler && install_deps
+        puts "✅ Already using #{bundler} - reinstalling dependencies as requested"
+        manage_dependencies(bundler, install_deps, switching: false, no_uninstall: no_uninstall)
+        return
+      end
+
+      update_config(bundler)
+
+      puts "✅ Switched from #{current} to #{bundler}"
+      puts ""
+      puts "📝 Configuration updated in #{SHAKAPACKER_CONFIG}"
+
+      manage_dependencies(bundler, install_deps, no_uninstall: no_uninstall)
+
+      puts ""
+      puts "🎯 Next steps:"
+      puts "   1. Restart your dev server: bin/dev"
+      puts "   2. Verify build works: bin/shakapacker"
+      puts ""
+      puts "💡 Tip: Both webpack and rspack can coexist in package.json during migration"
+      puts "        Use --install-deps to automatically manage dependencies, or manage manually"
+      puts "        Use --no-uninstall to skip removing old bundler packages (faster switching)"
+    end
+
+    def init_config
+      if File.exist?(custom_config_path)
+        puts "⚠️  #{CUSTOM_DEPS_CONFIG} already exists"
+        return
+      end
+
+      config = {
+        "rspack" => {
+          "devDependencies" => DEFAULT_RSPACK_DEPS[:dev],
+          "dependencies" => DEFAULT_RSPACK_DEPS[:prod]
+        },
+        "webpack" => {
+          "devDependencies" => DEFAULT_WEBPACK_DEPS[:dev],
+          "dependencies" => DEFAULT_WEBPACK_DEPS[:prod]
+        }
+      }
+
+      File.write(custom_config_path, YAML.dump(config))
+      puts "✅ Created #{CUSTOM_DEPS_CONFIG}"
+      puts ""
+      puts "You can now customize the dependencies for each bundler in this file."
+      puts "The script will automatically use these custom dependencies when switching bundlers."
+    end
+
+    def show_usage
+      current = current_bundler
+      puts "Current bundler: #{current}"
+      puts ""
+      puts "Usage:"
+      puts "  rails shakapacker:switch_bundler [webpack|rspack] [OPTIONS]"
+      puts "  rake shakapacker:switch_bundler [webpack|rspack] -- [OPTIONS]"
+      puts ""
+      puts "Options:"
+      puts "  --install-deps    Automatically install/uninstall dependencies"
+      puts "  --no-uninstall    Skip uninstalling old bundler packages (faster, keeps both bundlers)"
+      puts "  --init-config     Create #{CUSTOM_DEPS_CONFIG} with default dependencies"
+      puts "  --help, -h        Show this help message"
+      puts ""
+      puts "Examples:"
+      puts "  # Using rails command"
+      puts "  rails shakapacker:switch_bundler rspack --install-deps"
+      puts "  rails shakapacker:switch_bundler webpack --install-deps --no-uninstall"
+      puts "  rails shakapacker:switch_bundler --init-config"
+      puts ""
+      puts "  # Using rake command (note the -- separator)"
+      puts "  rake shakapacker:switch_bundler rspack -- --install-deps"
+      puts "  rake shakapacker:switch_bundler webpack -- --install-deps --no-uninstall"
+      puts "  rake shakapacker:switch_bundler -- --init-config"
+    end
+
+    private
+
+      def config_path
+        root_path.join(SHAKAPACKER_CONFIG)
+      end
+
+      def custom_config_path
+        root_path.join(CUSTOM_DEPS_CONFIG)
+      end
+
+      def load_dependencies
+        if File.exist?(custom_config_path)
+          puts "📝 Using custom dependencies from #{CUSTOM_DEPS_CONFIG}"
+          begin
+            custom = load_yaml_config(custom_config_path)
+          rescue Psych::SyntaxError => e
+            puts "❌ Error parsing #{CUSTOM_DEPS_CONFIG}: #{e.message}"
+            puts "   Please fix the YAML syntax or delete the file to use defaults"
+            raise
+          end
+          rspack_deps = {
+            dev: custom.dig("rspack", "devDependencies") || DEFAULT_RSPACK_DEPS[:dev],
+            prod: custom.dig("rspack", "dependencies") || DEFAULT_RSPACK_DEPS[:prod]
+          }
+          webpack_deps = {
+            dev: custom.dig("webpack", "devDependencies") || DEFAULT_WEBPACK_DEPS[:dev],
+            prod: custom.dig("webpack", "dependencies") || DEFAULT_WEBPACK_DEPS[:prod]
+          }
+          [rspack_deps, webpack_deps]
+        else
+          [DEFAULT_RSPACK_DEPS, DEFAULT_WEBPACK_DEPS]
+        end
+      end
+
+      def update_config(bundler)
+        content = File.read(config_path)
+
+        # Replace assets_bundler value (handles spaces, tabs, and various quote styles)
+        # Only matches uncommented lines
+        content.gsub!(/^([ \t]*assets_bundler:[ \t]*['"]?)(webpack|rspack)(['"]?)/, "\\1#{bundler}\\3")
+
+        # Update javascript_transpiler recommendation for rspack
+        # Only update if not already set to swc and only on uncommented lines
+        if bundler == "rspack" && content !~ /^[ \t]*javascript_transpiler:[ \t]*['"]?swc['"]?/
+          content.gsub!(/^([ \t]*javascript_transpiler:[ \t]*['"]?)\w+(['"]?)/, "\\1swc\\2")
+        end
+
+        File.write(config_path, content)
+      end
+
+      def manage_dependencies(bundler, install_deps, switching: true, no_uninstall: false)
+        rspack_deps, webpack_deps = load_dependencies
+        deps_to_install = bundler == "rspack" ? rspack_deps : webpack_deps
+        deps_to_remove = bundler == "rspack" ? webpack_deps : rspack_deps
+
+        if install_deps
+          puts ""
+          puts "📦 Managing dependencies..."
+          puts ""
+
+          # Show what will be removed (only when switching and not no_uninstall)
+          if switching && !no_uninstall && (!deps_to_remove[:dev].empty? || !deps_to_remove[:prod].empty?)
+            puts "   🗑️  Removing:"
+            deps_to_remove[:dev].each { |dep| puts "      - #{dep} (dev)" }
+            deps_to_remove[:prod].each { |dep| puts "      - #{dep} (prod)" }
+            puts ""
+          elsif switching && no_uninstall
+            puts "   ⏭️  Skipping uninstall (--no-uninstall)"
+            puts ""
+          end
+
+          # Show what will be installed
+          if !deps_to_install[:dev].empty? || !deps_to_install[:prod].empty?
+            puts "   📦 Installing:"
+            deps_to_install[:dev].each { |dep| puts "      - #{dep} (dev)" }
+            deps_to_install[:prod].each { |dep| puts "      - #{dep} (prod)" }
+            puts ""
+          end
+
+          # Remove old bundler dependencies (only when switching and not no_uninstall)
+          if switching && !no_uninstall
+            remove_dependencies(deps_to_remove)
+          end
+
+          # Install new bundler dependencies
+          install_dependencies(deps_to_install)
+
+          puts "   ✅ Dependencies updated"
+        else
+          print_manual_dependency_instructions(bundler, deps_to_install, deps_to_remove)
+        end
+      end
+
+      def remove_dependencies(deps)
+        package_json = get_package_json
+
+        unless deps[:dev].empty?
+          unless package_json.manager.remove(deps[:dev])
+            puts "   ⚠️  Warning: Failed to uninstall some dev dependencies"
+          end
+        end
+
+        unless deps[:prod].empty?
+          unless package_json.manager.remove(deps[:prod])
+            puts "   ⚠️  Warning: Failed to uninstall some prod dependencies"
+          end
+        end
+      end
+
+      def install_dependencies(deps)
+        package_json = get_package_json
+
+        unless deps[:dev].empty?
+          unless package_json.manager.add(deps[:dev], type: :dev)
+            puts "❌ Failed to install dev dependencies"
+            raise "Failed to install dev dependencies"
+          end
+        end
+
+        unless deps[:prod].empty?
+          unless package_json.manager.add(deps[:prod], type: :production)
+            puts "❌ Failed to install prod dependencies"
+            raise "Failed to install prod dependencies"
+          end
+        end
+
+        # Run a full install to ensure optional dependencies (like native bindings) are properly resolved
+        # This is especially important for packages like @rspack/core that use platform-specific native modules
+        unless package_json.manager.install
+          puts "❌ Failed to run full install to resolve optional dependencies"
+          raise "Failed to run full install"
+        end
+      end
+
+      def get_package_json
+        require "package_json"
+        PackageJson.read(root_path)
+      end
+
+      def print_manual_dependency_instructions(bundler, deps_to_install, deps_to_remove)
+        puts ""
+        puts "⚠️  Dependencies not automatically installed (use --install-deps to auto-install)"
+        puts ""
+
+        package_manager = detect_package_manager
+        target_name = bundler == "rspack" ? "rspack" : "webpack"
+        old_name = bundler == "rspack" ? "webpack" : "rspack"
+
+        puts "📦 To install #{target_name} dependencies, run:"
+        print_install_commands(package_manager, deps_to_install)
+        puts ""
+        puts "🗑️  To remove #{old_name} dependencies, run:"
+        print_uninstall_commands(package_manager, deps_to_remove)
+      end
+
+      def detect_package_manager
+        get_package_json.manager.binary
+      rescue StandardError
+        "npm" # Fallback to npm if detection fails
+      end
+
+      def print_install_commands(package_manager, deps)
+        case package_manager
+        when "yarn"
+          puts "   yarn add --dev #{deps[:dev].join(' ')}" unless deps[:dev].empty?
+          puts "   yarn add #{deps[:prod].join(' ')}" unless deps[:prod].empty?
+        when "pnpm"
+          puts "   pnpm add -D #{deps[:dev].join(' ')}" unless deps[:dev].empty?
+          puts "   pnpm add #{deps[:prod].join(' ')}" unless deps[:prod].empty?
+        when "bun"
+          puts "   bun add --dev #{deps[:dev].join(' ')}" unless deps[:dev].empty?
+          puts "   bun add #{deps[:prod].join(' ')}" unless deps[:prod].empty?
+        else # npm
+          puts "   npm install --save-dev #{deps[:dev].join(' ')}" unless deps[:dev].empty?
+          puts "   npm install --save #{deps[:prod].join(' ')}" unless deps[:prod].empty?
+        end
+      end
+
+      def print_uninstall_commands(package_manager, deps)
+        case package_manager
+        when "yarn"
+          puts "   yarn remove #{deps[:dev].join(' ')}" unless deps[:dev].empty?
+          puts "   yarn remove #{deps[:prod].join(' ')}" unless deps[:prod].empty?
+        when "pnpm"
+          puts "   pnpm remove #{deps[:dev].join(' ')}" unless deps[:dev].empty?
+          puts "   pnpm remove #{deps[:prod].join(' ')}" unless deps[:prod].empty?
+        when "bun"
+          puts "   bun remove #{deps[:dev].join(' ')}" unless deps[:dev].empty?
+          puts "   bun remove #{deps[:prod].join(' ')}" unless deps[:prod].empty?
+        else # npm
+          puts "   npm uninstall #{deps[:dev].join(' ')}" unless deps[:dev].empty?
+          puts "   npm uninstall #{deps[:prod].join(' ')}" unless deps[:prod].empty?
+        end
+      end
+
+      # Load YAML config file with Ruby version compatibility
+      # Ruby 3.1+ supports aliases: keyword, older versions need YAML.safe_load
+      def load_yaml_config(path)
+        if YAML.respond_to?(:unsafe_load_file)
+          # Ruby 3.1+: Use unsafe_load_file to support aliases/anchors
+          YAML.unsafe_load_file(path)
+        else
+          # Ruby 2.7-3.0: Use safe_load with aliases enabled
+          YAML.safe_load(File.read(path), permitted_classes: [], permitted_symbols: [], aliases: true)
+        end
+      rescue ArgumentError
+        # Ruby 2.7 doesn't support aliases keyword - fall back to YAML.load
+        YAML.load(File.read(path)) # rubocop:disable Security/YAMLLoad
+      end
+  end
+end

data/lib/shakapacker/configuration.rb

@@ -255,7 +255,21 @@ class Shakapacker::Configuration
       rescue ArgumentError
         YAML.load_file(config_path.to_s)
       end
-      symbolized_config = config[env].deep_symbolize_keys
+
+      # Try to find environment-specific configuration with fallback
+      # Fallback order: requested env → production
+      if config[env]
+        env_config = config[env]
+      elsif config["production"]
+        log_fallback(env, "production")
+        env_config = config["production"]
+      else
+        # No suitable configuration found - rely on bundled defaults
+        log_fallback(env, "none (will use bundled defaults)")
+        env_config = nil
+      end
+
+      symbolized_config = env_config&.deep_symbolize_keys || {}
 
       return symbolized_config
     rescue Errno::ENOENT => e
@@ -280,7 +294,10 @@ class Shakapacker::Configuration
         rescue ArgumentError
           YAML.load_file(path)
         end
-        HashWithIndifferentAccess.new(config[env] || config[Shakapacker::DEFAULT_ENV])
+        # Load defaults from bundled shakapacker.yml (always has all environments)
+        # Note: This differs from load() which reads user's config and may be missing environments
+        # Fallback to production ensures staging and other custom envs get production-like defaults
+        HashWithIndifferentAccess.new(config[env] || config["production"])
       end
     end
 
@@ -289,4 +306,13 @@ class Shakapacker::Configuration
 
       path
     end
+
+    def log_fallback(requested_env, fallback_env)
+      return unless Shakapacker.logger
+
+      Shakapacker.logger.info(
+        "Shakapacker environment '#{requested_env}' not found in #{config_path}, " \
+        "falling back to '#{fallback_env}'"
+      )
+    end
 end

data/lib/shakapacker/doctor.rb

@@ -65,12 +65,12 @@ module Shakapacker
 
       def check_entry_points
         # Check for invalid configuration first
-        if config.data[:source_entry_path] == "/" && config.nested_entries?
+        if config.fetch(:source_entry_path) == "/" && config.nested_entries?
           @issues << "Invalid configuration: cannot use '/' as source_entry_path with nested_entries: true"
           return  # Don't try to check files when config is invalid
         end
 
-        source_entry_path = config.source_path.join(config.data[:source_entry_path] || "packs")
+        source_entry_path = config.source_path.join(config.fetch(:source_entry_path) || "packs")
 
         unless source_entry_path.exist?
           @issues << "Source entry path #{source_entry_path} does not exist"
@@ -173,7 +173,8 @@ module Shakapacker
       end
 
       def check_sri_dependencies
-        return unless config.data.dig(:integrity, :enabled)
+        integrity_config = config.integrity
+        return unless integrity_config&.dig(:enabled)
 
         bundler = config.assets_bundler
         if bundler == "webpack"
@@ -183,7 +184,7 @@ module Shakapacker
         end
 
         # Validate hash functions
-        hash_functions = config.data.dig(:integrity, :hash_functions) || ["sha384"]
+        hash_functions = integrity_config.dig(:hash_functions) || ["sha384"]
         invalid_functions = hash_functions - ["sha256", "sha384", "sha512"]
         unless invalid_functions.empty?
           @issues << "Invalid SRI hash functions: #{invalid_functions.join(', ')}"
@@ -326,6 +327,11 @@ module Shakapacker
         unless binstub_path.exist?
           @warnings << "Shakapacker binstub not found at bin/shakapacker. Run 'rails shakapacker:binstubs' to create it."
         end
+
+        export_config_binstub = root_path.join("bin/export-bundler-config")
+        unless export_config_binstub.exist?
+          @warnings << "Config export binstub not found at bin/export-bundler-config. Run 'rails shakapacker:binstubs' to create it."
+        end
       end
 
       def check_javascript_transpiler_dependencies
@@ -453,7 +459,51 @@ module Shakapacker
 
         if swc_config_path.exist?
           @info << "SWC configuration: Using config/swc.config.js (recommended). This config is merged with Shakapacker's defaults."
+          check_swc_config_settings(swc_config_path)
+        end
+      end
+
+      def check_swc_config_settings(config_path)
+        config_content = File.read(config_path, encoding: "UTF-8")
+
+        # Check for loose: true (deprecated default)
+        if config_content.match?(/loose\s*:\s*true/)
+          @warnings << "SWC configuration: 'loose: true' detected in config/swc.config.js. " \
+                      "This can cause silent failures with Stimulus controllers and incorrect spread operator behavior. " \
+                      "Consider removing this setting to use Shakapacker's default 'loose: false' (spec-compliant). " \
+                      "See: https://github.com/shakacode/shakapacker/blob/main/docs/using_swc_loader.md#using-swc-with-stimulus"
         end
+
+        # Check for missing keepClassNames with Stimulus
+        if stimulus_likely_used? && !config_content.match?(/keepClassNames\s*:\s*true/)
+          @warnings << "SWC configuration: Stimulus appears to be in use, but 'keepClassNames: true' is not set in config/swc.config.js. " \
+                      "Without this setting, Stimulus controllers will fail silently. " \
+                      "Add 'keepClassNames: true' to jsc config. " \
+                      "See: https://github.com/shakacode/shakapacker/blob/main/docs/using_swc_loader.md#using-swc-with-stimulus"
+        elsif config_content.match?(/keepClassNames\s*:\s*true/)
+          @info << "SWC configuration: 'keepClassNames: true' is set (good for Stimulus compatibility)"
+        end
+
+        # Check for jsc.target and env conflict
+        # Use word boundary to avoid false positives with transform.target or other nested properties
+        if config_content.match?(/jsc\s*:\s*\{[^}]*\btarget\s*:/) && config_content.match?(/env\s*:\s*\{/)
+          @issues << "SWC configuration: Both 'jsc.target' and 'env' are configured. These cannot be used together. " \
+                     "Remove 'jsc.target' and use only 'env' (Shakapacker sets this automatically). " \
+                     "See: https://github.com/shakacode/shakapacker/blob/main/docs/using_swc_loader.md#using-swc-with-stimulus"
+        end
+      rescue => e
+        # Don't fail doctor if SWC config check has issues
+        @warnings << "Unable to validate SWC configuration: #{e.message}"
+      end
+
+      def stimulus_likely_used?
+        return false unless package_json_exists?
+
+        package_json = read_package_json
+        dependencies = (package_json["dependencies"] || {}).merge(package_json["devDependencies"] || {})
+
+        # Check for @hotwired/stimulus or stimulus package
+        dependencies.key?("@hotwired/stimulus") || dependencies.key?("stimulus")
       end
 
       def check_css_dependencies
@@ -785,6 +835,11 @@ module Shakapacker
             if binstub_path.exist?
               puts "✓ Shakapacker binstub found"
             end
+
+            export_config_binstub = doctor.root_path.join("bin/export-bundler-config")
+            if export_config_binstub.exist?
+              puts "✓ Config export binstub found"
+            end
           end
 
           def print_info_messages
@@ -828,6 +883,12 @@ module Shakapacker
             package_manager = doctor.send(:package_manager)
             puts "To fix missing dependencies, run:"
             puts "  #{package_manager_install_command(package_manager)}"
+            puts ""
+            puts "For debugging configuration issues, export your webpack/rspack config:"
+            puts "  bin/export-bundler-config --doctor"
+            puts "  (Exports annotated YAML configs for dev and production - best for troubleshooting)"
+            puts ""
+            puts "  See 'bin/export-bundler-config --help' for more options"
           end
 
           def package_manager_install_command(manager)

data/lib/shakapacker/rspack_runner.rb

@@ -6,7 +6,7 @@ module Shakapacker
   class RspackRunner < Shakapacker::Runner
     def self.run(argv)
       $stdout.sync = true
-      ENV["NODE_ENV"] ||= (ENV["RAILS_ENV"] == "production") ? "production" : "development"
+      Shakapacker.ensure_node_env!
       new(argv).run
     end
 

data/lib/shakapacker/runner.rb

@@ -24,7 +24,7 @@ module Shakapacker
     ].freeze
     def self.run(argv)
       $stdout.sync = true
-      ENV["NODE_ENV"] ||= (ENV["RAILS_ENV"] == "production") ? "production" : "development"
+      Shakapacker.ensure_node_env!
 
       # Create a single runner instance to avoid loading configuration twice.
       # We extend it with the appropriate build command based on the bundler type.

data/lib/shakapacker/swc_migrator.rb

@@ -51,11 +51,19 @@ module Shakapacker
       // This file is merged with Shakapacker's default SWC configuration
       // See: https://swc.rs/docs/configuration/compilation
 
+      const { env } = require('shakapacker');
+
       module.exports = {
-        jsc: {
-          transform: {
-            react: {
-              runtime: "automatic"
+        options: {
+          jsc: {
+            // CRITICAL for Stimulus compatibility: Prevents SWC from mangling class names
+            // which breaks Stimulus's class-based controller discovery mechanism
+            keepClassNames: true,
+            transform: {
+              react: {
+                runtime: "automatic",
+                refresh: env.isDevelopment && env.runningWebpackDevServer
+              }
             }
           }
         }
@@ -222,8 +230,8 @@ module Shakapacker
             settings.delete("babel")
           end
 
-          settings["swc"] = true
-          logger.info "  - Enabled SWC for #{env} environment"
+          settings["javascript_transpiler"] = "swc"
+          logger.info "  - Set javascript_transpiler to 'swc' for #{env} environment"
         end
 
         File.write(config_path, config.to_yaml)

data/lib/shakapacker/version.rb

@@ -1,4 +1,4 @@
 module Shakapacker
   # Change the version in package.json too, please!
-  VERSION = "9.0.0".freeze
+  VERSION = "9.2.0".freeze
 end

data/lib/shakapacker/webpack_runner.rb

@@ -6,7 +6,7 @@ module Shakapacker
   class WebpackRunner < Shakapacker::Runner
     def self.run(argv)
       $stdout.sync = true
-      ENV["NODE_ENV"] ||= (ENV["RAILS_ENV"] == "production") ? "production" : "development"
+      Shakapacker.ensure_node_env!
       new(argv).run
     end
 

data/lib/shakapacker.rb

@@ -7,6 +7,9 @@ module Shakapacker
   extend self
 
   DEFAULT_ENV = "development".freeze
+  # Environments that use their RAILS_ENV value for NODE_ENV
+  # All other environments (production, staging, etc.) use "production" for webpack optimizations
+  DEV_TEST_ENVS = %w[development test].freeze
 
   def instance=(instance)
     @instance = instance
@@ -24,6 +27,13 @@ module Shakapacker
     ENV["NODE_ENV"] = original
   end
 
+  # Set NODE_ENV based on RAILS_ENV if not already set
+  # - development/test environments use their RAILS_ENV value
+  # - all other environments (production, staging, etc.) use "production" for webpack optimizations
+  def ensure_node_env!
+    ENV["NODE_ENV"] ||= DEV_TEST_ENVS.include?(ENV["RAILS_ENV"]) ? ENV["RAILS_ENV"] : "production"
+  end
+
   def ensure_log_goes_to_stdout
     old_logger = Shakapacker.logger
     Shakapacker.logger = Logger.new(STDOUT)

data/lib/tasks/shakapacker/export_bundler_config.rake

@@ -0,0 +1,72 @@
+namespace :shakapacker do
+  desc <<~DESC
+    Export webpack or rspack configuration for debugging and analysis
+
+    Exports your resolved webpack/rspack configuration in human-readable formats.
+    Use this to debug configuration issues, compare environments, or analyze
+    client vs server bundle differences.
+
+    Usage:
+      rails shakapacker:export_bundler_config [OPTIONS]
+      rake shakapacker:export_bundler_config -- [OPTIONS]
+
+    Quick Start (Recommended):
+      rails shakapacker:export_bundler_config --doctor
+
+    This exports all configs (dev + prod, client + server) to shakapacker-config-exports/
+    directory in annotated YAML format - perfect for troubleshooting.
+
+    Common Options:
+      --doctor              Export everything for troubleshooting (recommended)
+      --save                Save current environment configs to files
+      --save-dir=<dir>      Custom output directory (requires --save)
+      --env=development|production|test    Specify environment
+      --client-only         Export only client config
+      --server-only         Export only server config
+      --format=yaml|json|inspect           Output format
+      --help, -h            Show detailed help
+
+    Examples:
+      # Export all configs for troubleshooting
+      rails shakapacker:export_bundler_config --doctor
+
+      # Save production client config
+      rails shakapacker:export_bundler_config --save --env=production --client-only
+
+      # View development config in terminal
+      rails shakapacker:export_bundler_config
+
+      # Show detailed help
+      rails shakapacker:export_bundler_config --help
+
+    Note: When using 'rake', you must use '--' to separate rake options from task arguments.
+          Example: rake shakapacker:export_bundler_config -- --doctor
+
+    The task automatically falls back to the gem version if bin/export-bundler-config
+    binstub is not installed. To install all binstubs, run: rails shakapacker:binstubs
+  DESC
+  task :export_bundler_config do
+    # Try to use the binstub if it exists, otherwise use the gem's version
+    bin_path = Rails.root.join("bin/export-bundler-config")
+
+    unless File.exist?(bin_path)
+      # Binstub not installed, use the gem's version directly
+      gem_bin_path = File.expand_path("../../install/bin/export-bundler-config", __dir__)
+
+      $stderr.puts "Note: bin/export-bundler-config binstub not found."
+      $stderr.puts "Using gem version directly. To install the binstub, run: rake shakapacker:binstubs"
+      $stderr.puts ""
+
+      Dir.chdir(Rails.root) do
+        exec("node", gem_bin_path, *ARGV[1..])
+      end
+    else
+      # Pass through command-line arguments after the task name
+      # Use exec to replace the rake process with the export script
+      # This ensures proper exit codes and signal handling
+      Dir.chdir(Rails.root) do
+        exec(bin_path.to_s, *ARGV[1..])
+      end
+    end
+  end
+end