shakapacker 10.1.0 → 10.2.0

data/lib/shakapacker/helper.rb

@@ -112,7 +112,7 @@ module Shakapacker::Helper
   def javascript_pack_tag(*names, defer: true, async: false, early_hints: nil, **options)
     if @javascript_pack_tag_loaded
       raise "To prevent duplicated chunks on the page, you should call javascript_pack_tag only once on the page. " \
-      "Please refer to https://github.com/shakacode/shakapacker/blob/main/README.md#view-helpers-javascript_pack_tag-and-stylesheet_pack_tag for the usage guide"
+      "Please refer to https://github.com/shakacode/shakapacker/blob/main/docs/api-reference.md#view-helpers-javascript_pack_tag-and-stylesheet_pack_tag for the usage guide"
     end
 
     # Collect all packs (queue + direct args)
@@ -330,7 +330,7 @@ module Shakapacker::Helper
   def append_stylesheet_pack_tag(*names)
     if @stylesheet_pack_tag_loaded
       raise "You can only call append_stylesheet_pack_tag before stylesheet_pack_tag helper. " \
-      "Please refer to https://github.com/shakacode/shakapacker/blob/main/README.md#view-helper-append_javascript_pack_tag-prepend_javascript_pack_tag-and-append_stylesheet_pack_tag for the usage guide"
+      "Please refer to https://github.com/shakacode/shakapacker/blob/main/docs/api-reference.md#view-helper-append_javascript_pack_tag-prepend_javascript_pack_tag-and-append_stylesheet_pack_tag for the usage guide"
     end
 
     @stylesheet_pack_tag_queue ||= []
@@ -357,7 +357,7 @@ module Shakapacker::Helper
     def update_javascript_pack_tag_queue(defer:, async:)
       if @javascript_pack_tag_loaded
         raise "You can only call #{caller_locations(1..1).first.base_label} before javascript_pack_tag helper. " \
-        "Please refer to https://github.com/shakacode/shakapacker/blob/main/README.md#view-helper-append_javascript_pack_tag-prepend_javascript_pack_tag-and-append_stylesheet_pack_tag for the usage guide"
+        "Please refer to https://github.com/shakacode/shakapacker/blob/main/docs/api-reference.md#view-helper-append_javascript_pack_tag-prepend_javascript_pack_tag-and-append_stylesheet_pack_tag for the usage guide"
       end
 
       # When both async and defer are specified, async takes precedence per HTML5 spec

data/lib/shakapacker/install/env.rb

@@ -2,6 +2,7 @@ module Shakapacker
   module Install
     module Env
       TRUTHY_VALUES = %w[true 1 yes].freeze
+      VALID_BUNDLERS = %w[webpack rspack].freeze
 
       module_function
 
@@ -28,6 +29,55 @@ module Shakapacker
 
         !config_preexisting
       end
+
+      # Keep bundled runtime defaults backward compatible while allowing the
+      # installer to write an explicit new-project bundler choice. Takes the same
+      # inputs as update_transpiler_config? for consistency, but is deliberately
+      # more conservative: switching an existing app's bundler is impactful, so we
+      # only rewrite a config the installer owns (a fresh install, or an explicit
+      # FORCE overwrite) and never a pre-existing one (interactive or SKIP mode).
+      def update_assets_bundler_config?(assets_bundler_to_install:, conflict_option:, config_preexisting:)
+        # The bundled shakapacker.yml already ships assets_bundler: "webpack", so
+        # rewriting it to "webpack" would be a no-op. This relies on that shipped default.
+        return false if assets_bundler_to_install == "webpack"
+        return true if conflict_option[:force]
+
+        !config_preexisting
+      end
+
+      # Resolve which bundler the installer should set up. Precedence: an explicit
+      # SHAKAPACKER_ASSETS_BUNDLER env var (or task argument, which sets that env var)
+      # always wins; otherwise a FORCE overwrite installs the new-project default;
+      # otherwise an existing app keeps its current bundler (when it is a recognized
+      # value) so a re-install never silently switches it; brand-new installs fall
+      # back to rspack. Returning the env var verbatim lets the caller's strict
+      # VALID_BUNDLERS check still reject a misspelled value.
+      def resolve_assets_bundler(env_value:, existing_bundler:, force:)
+        return env_value if env_value
+        return "rspack" if force
+        return existing_bundler if VALID_BUNDLERS.include?(existing_bundler)
+
+        "rspack"
+      end
+
+      # Apply an optional `shakapacker:install[bundler]` task argument. A
+      # recognized bundler (webpack or rspack) is written to
+      # SHAKAPACKER_ASSETS_BUNDLER so the install template picks it up,
+      # overriding any value already set in that env var (the explicit argument
+      # wins). An unrecognized value returns an error message (and leaves the
+      # env var unset) so the caller can abort, mirroring the template's strict
+      # validation of SHAKAPACKER_ASSETS_BUNDLER. Returns nil when the argument
+      # is valid or absent.
+      def apply_bundler_arg(bundler_arg)
+        return nil if bundler_arg.nil? || bundler_arg.empty?
+
+        if VALID_BUNDLERS.include?(bundler_arg)
+          ENV["SHAKAPACKER_ASSETS_BUNDLER"] = bundler_arg
+          nil
+        else
+          "Unknown bundler '#{bundler_arg}'. Valid values: #{VALID_BUNDLERS.join(", ")}."
+        end
+      end
     end
   end
 end

data/lib/shakapacker/instance.rb

@@ -81,7 +81,7 @@ class Shakapacker::Instance
   # @return [Shakapacker::CompilerStrategy] the compiler strategy
   # @api private
   def strategy
-    @strategy ||= Shakapacker::CompilerStrategy.from_config
+    @strategy ||= Shakapacker::CompilerStrategy.from_config(self)
   end
 
   # Returns the compiler for this instance

data/lib/shakapacker/mtime_strategy.rb

@@ -19,7 +19,7 @@ module Shakapacker
       end
 
       def latest_modified_timestamp
-        if Rails.env.development?
+        if env.development?
           warn <<~MSG.strip
           Shakapacker::Compiler - Slow setup for development
 

data/lib/shakapacker/runner.rb

@@ -26,6 +26,23 @@ module Shakapacker
       "i"
     ].freeze
 
+    SHAKAPACKER_NODE_FLAGS = Configuration::SHAKAPACKER_NODE_FLAGS
+    private_constant :SHAKAPACKER_NODE_FLAGS
+
+    RSPACK_RUNNER_EXTENSION = Module.new do
+      def build_cmd
+        package_json.manager.native_exec_command("rspack")
+      end
+    end
+    private_constant :RSPACK_RUNNER_EXTENSION
+
+    WEBPACK_RUNNER_EXTENSION = Module.new do
+      def build_cmd
+        package_json.manager.native_exec_command("webpack")
+      end
+    end
+    private_constant :WEBPACK_RUNNER_EXTENSION
+
     def self.json_output?(argv)
       argv.include?("--json") || argv.include?("-j")
     end
@@ -34,31 +51,39 @@ module Shakapacker
       json_output?(argv) ? $stderr : $stdout
     end
 
+    def self.split_passthrough_argv(argv)
+      separator_index = argv.index("--")
+      return [argv.dup, []] unless separator_index
+
+      [argv[0...separator_index], argv[(separator_index + 1)..]]
+    end
+
     def self.run(argv)
       $stdout.sync = true
+      runner_argv, passthrough_argv = split_passthrough_argv(argv)
 
       # Show Shakapacker help and exit (don't call bundler)
       # Support --help, -h, and --help=verbose formats
-      help_verbose = argv.any? { |arg| arg == "--help=verbose" }
-      if argv.include?("--help") || argv.include?("-h") || help_verbose
+      help_verbose = runner_argv.any? { |arg| arg == "--help=verbose" }
+      if runner_argv.include?("--help") || runner_argv.include?("-h") || help_verbose
         print_help(verbose: help_verbose)
         exit(0)
-      elsif argv.include?("--version") || argv.include?("-v")
+      elsif runner_argv.include?("--version") || runner_argv.include?("-v")
         print_version
         exit(0)
-      elsif argv.include?("--init")
+      elsif runner_argv.include?("--init")
         init_config_file
         exit(0)
-      elsif argv.include?("--list-builds")
+      elsif runner_argv.include?("--list-builds")
         list_builds
         exit(0)
       end
 
       # Check for --bundler flag
       bundler_override = nil
-      bundler_index = argv.index("--bundler")
+      bundler_index = runner_argv.index("--bundler")
       if bundler_index
-        bundler_value = argv[bundler_index + 1]
+        bundler_value = runner_argv[bundler_index + 1]
         unless bundler_value && %w[webpack rspack].include?(bundler_value)
           $stderr.puts "[Shakapacker] Error: --bundler requires 'webpack' or 'rspack'"
           $stderr.puts "Usage: bin/shakapacker --bundler <webpack|rspack>"
@@ -68,9 +93,9 @@ module Shakapacker
       end
 
       # Check for --build flag
-      build_index = argv.index("--build")
+      build_index = runner_argv.index("--build")
       if build_index
-        build_name = argv[build_index + 1]
+        build_name = runner_argv[build_index + 1]
 
         unless build_name
           $stderr.puts "[Shakapacker] Error: --build requires a build name"
@@ -93,7 +118,7 @@ module Shakapacker
           build_config = loader.resolve_build_config(build_name, **resolve_opts)
 
           # Remove --build and build name from argv
-          remaining_argv = argv.dup
+          remaining_argv = runner_argv.dup
           remaining_argv.delete_at(build_index + 1)
           remaining_argv.delete_at(build_index)
 
@@ -108,17 +133,18 @@ module Shakapacker
 
           # If this build uses dev server, delegate to DevServerRunner
           if loader.uses_dev_server?(build_config)
-            log = log_output_for(argv)
+            # Include passthrough --json so Shakapacker logs stay off stdout when bundler JSON is requested.
+            log = log_output_for(runner_argv + passthrough_argv)
             log.puts "[Shakapacker] Build '#{build_name}' requires dev server"
             log.puts "[Shakapacker] Running: bin/shakapacker-dev-server --build #{build_name}"
             log.puts ""
             require_relative "dev_server_runner"
-            DevServerRunner.run_with_build_config(remaining_argv, build_config)
+            DevServerRunner.run_with_build_config(remaining_argv, build_config, passthrough_argv)
             return
           end
 
           # Otherwise run with this build config
-          run_with_build_config(remaining_argv, build_config)
+          run_with_build_config(remaining_argv, build_config, passthrough_argv)
           return
         rescue ArgumentError => e
           $stderr.puts "[Shakapacker] #{e.message}"
@@ -129,7 +155,7 @@ module Shakapacker
       Shakapacker.ensure_node_env!
 
       # Remove --bundler flag from argv if present (not using --build)
-      remaining_argv = argv.dup
+      remaining_argv = runner_argv.dup
       if bundler_index
         bundler_idx = remaining_argv.index("--bundler")
         if bundler_idx
@@ -144,39 +170,26 @@ module Shakapacker
 
       # Create a single runner instance to avoid loading configuration twice.
       # We extend it with the appropriate build command based on the bundler type.
-      runner = new(remaining_argv, nil, bundler_override)
+      runner = new(remaining_argv, nil, bundler_override, passthrough_argv)
 
       # Determine which bundler to use (override takes precedence)
       use_rspack = bundler_override ? (bundler_override == "rspack") : runner.config.rspack?
 
       if use_rspack
         require_relative "rspack_runner"
-        # Extend the runner instance with rspack-specific methods
-        # This avoids creating a new RspackRunner which would reload the configuration
-        runner.extend(Module.new do
-          def build_cmd
-            package_json.manager.native_exec_command("rspack")
-          end
-
-          def assets_bundler_commands
-            BASE_COMMANDS + %w[build watch]
-          end
-        end)
+        # Extend the runner instance to avoid creating a new RspackRunner and reloading configuration.
+        runner.extend(RSPACK_RUNNER_EXTENSION)
         runner.run
       else
         require_relative "webpack_runner"
         # Extend the runner instance with webpack-specific methods
         # This avoids creating a new WebpackRunner which would reload the configuration
-        runner.extend(Module.new do
-          def build_cmd
-            package_json.manager.native_exec_command("webpack")
-          end
-        end)
+        runner.extend(WEBPACK_RUNNER_EXTENSION)
         runner.run
       end
     end
 
-    def self.run_with_build_config(argv, build_config)
+    def self.run_with_build_config(argv, build_config, passthrough_argv = [])
       $stdout.sync = true
       Shakapacker.ensure_node_env!
 
@@ -189,7 +202,8 @@ module Shakapacker
       # This ensures the bundler override (from --bundler or build config) is respected
       ENV["SHAKAPACKER_ASSETS_BUNDLER"] = build_config[:bundler]
 
-      log = log_output_for(argv)
+      # Include passthrough --json so Shakapacker logs stay off stdout when bundler JSON is requested.
+      log = log_output_for(argv + passthrough_argv)
       log.puts "[Shakapacker] Running build: #{build_config[:name]}"
       log.puts "[Shakapacker] Description: #{build_config[:description]}" if build_config[:description]
       log.puts "[Shakapacker] Bundler: #{build_config[:bundler]}"
@@ -197,37 +211,31 @@ module Shakapacker
 
       # Create runner with modified argv and bundler from build_config
       # The build_config[:bundler] already has any CLI --bundler override applied
-      runner = new(argv, build_config, build_config[:bundler])
+      runner = new(argv, build_config, build_config[:bundler], passthrough_argv)
 
       # Use bundler from build_config (which includes CLI override)
       if build_config[:bundler] == "rspack"
         require_relative "rspack_runner"
-        runner.extend(Module.new do
-          def build_cmd
-            package_json.manager.native_exec_command("rspack")
-          end
-
-          def assets_bundler_commands
-            BASE_COMMANDS + %w[build watch]
-          end
-        end)
+        runner.extend(RSPACK_RUNNER_EXTENSION)
         runner.run
       else
         require_relative "webpack_runner"
-        runner.extend(Module.new do
-          def build_cmd
-            package_json.manager.native_exec_command("webpack")
-          end
-        end)
+        runner.extend(WEBPACK_RUNNER_EXTENSION)
         runner.run
       end
     end
 
-    def initialize(argv, build_config = nil, bundler_override = nil)
-      @argv = argv
+    def initialize(argv, build_config = nil, bundler_override = nil, passthrough_argv = nil)
+      @argv, @passthrough_argv =
+        unless passthrough_argv.nil?
+          [argv, passthrough_argv]
+        else
+          self.class.split_passthrough_argv(argv)
+        end
       @build_config = build_config
       @bundler_override = bundler_override
-      @json_output = self.class.json_output?(argv)
+      # Bundler --json writes machine-readable output to stdout; route Shakapacker logs to stderr too.
+      @json_output = self.class.json_output?(bundler_argv)
 
       @app_path           = File.expand_path(".", Dir.pwd)
       @shakapacker_config = ENV["SHAKAPACKER_CONFIG"] || File.join(@app_path, "config/shakapacker.yml")
@@ -260,6 +268,9 @@ module Shakapacker
       cmd = build_cmd
       log_output.puts "[Shakapacker] Base command: #{cmd.join(" ")}"
 
+      detect_shakapacker_flags_in_passthrough!
+
+      # Shakapacker-owned Node flags must appear before --; passthrough args belong to the bundler.
       if @argv.delete("--debug-shakapacker")
         log_output.puts "[Shakapacker] Debug mode enabled (--debug-shakapacker)"
         env["NODE_OPTIONS"] = "#{env["NODE_OPTIONS"]} --inspect-brk"
@@ -276,18 +287,19 @@ module Shakapacker
       end
 
       # Commands are not compatible with --config option.
-      if (@argv & assets_bundler_commands).empty?
+      incompatible_args = config_incompatible_args
+      if incompatible_args.empty?
         log_output.puts "[Shakapacker] Adding config file: #{@webpack_config}"
         cmd += ["--config", @webpack_config]
       else
-        log_output.puts "[Shakapacker] Skipping config file (running assets bundler command: #{(@argv & assets_bundler_commands).join(", ")})"
+        log_output.puts "[Shakapacker] Skipping config file (running assets bundler command: #{incompatible_args.join(", ")})"
       end
 
-      cmd += @argv
+      cmd += bundler_argv
       log_output.puts "[Shakapacker] Final command: #{cmd.join(" ")}"
       log_output.puts "[Shakapacker] Working directory: #{@app_path}"
 
-      watch_mode = @argv.include?("--watch") || @argv.include?("-w")
+      watch_mode = bundler_argv.include?("--watch") || bundler_argv.include?("-w")
       start_time = Time.now unless watch_mode
 
       Dir.chdir(@app_path) do
@@ -319,10 +331,33 @@ module Shakapacker
 
     protected
 
+      def bundler_argv
+        @argv + @passthrough_argv
+      end
+
       def assets_bundler_commands
         BASE_COMMANDS
       end
 
+      def config_incompatible_args
+        bundler_argv & assets_bundler_commands
+      end
+
+      def detect_shakapacker_flags_in_passthrough!(flags = SHAKAPACKER_NODE_FLAGS)
+        misplaced_flags = @passthrough_argv & flags
+        return if misplaced_flags.empty?
+
+        log_output.puts(
+          "The following Shakapacker-specific options must appear before --: #{misplaced_flags.join(' ')}."
+        )
+        exit_after_shakapacker_flag_error(1)
+      end
+
+      def exit_after_shakapacker_flag_error(status)
+        log_output.flush
+        exit(status)
+      end
+
       def print_config_not_found_error(bundler_type, config_path, config_dir)
         $stderr.puts "[Shakapacker] ERROR: #{bundler_type} config #{config_path} not found."
         $stderr.puts ""
@@ -354,6 +389,9 @@ module Shakapacker
           --bundler <webpack|rspack>
                                     Override bundler (defaults to shakapacker.yml)
 
+          Put Shakapacker-specific options before --. Arguments after -- are
+          passed directly to the selected bundler.
+
         Build configurations (config/shakapacker-builds.yml):
           --init                    Create config/shakapacker-builds.yml
           --list-builds             List available builds

data/lib/shakapacker/utils/misc.rb

@@ -2,12 +2,18 @@
 
 require "English"
 require "rake/file_utils"
+require "shellwords"
 
 module Shakapacker
   module Utils
     class Misc
       extend FileUtils
 
+      NODE_BINSTUB_EXECUTABLES = %w[node nodejs].freeze
+      ENV_FLAGS_WITH_ARGUMENTS = %w[-u --unset -C --chdir -P --path -a --argv0].freeze
+      private_constant :NODE_BINSTUB_EXECUTABLES
+      private_constant :ENV_FLAGS_WITH_ARGUMENTS
+
       def self.uncommitted_changes?(message_handler)
         return false if ENV["COVERAGE"] == "true"
 
@@ -31,6 +37,38 @@ module Shakapacker
       def self.sh_in_dir(dir, *shell_commands)
         shell_commands.flatten.each { |shell_command| sh %(cd '#{dir}' && #{shell_command.strip}) }
       end
+
+      def self.js_binstub_executable(path)
+        return nil unless File.file?(path)
+
+        shebang = File.open(path, "rb") { |f| f.gets }.to_s.chomp
+        return nil unless shebang.start_with?("#!")
+
+        shebang_tokens = begin
+          Shellwords.split(shebang.delete_prefix("#!"))
+        rescue ArgumentError
+          return nil
+        end
+        executable = shebang_tokens.first.to_s
+
+        if File.basename(executable) == "env"
+          shebang_tokens = shebang_tokens.drop(1)
+          while (env_token = shebang_tokens.first)
+            if env_token.start_with?("-")
+              env_flag = shebang_tokens.shift
+              shebang_tokens.shift if ENV_FLAGS_WITH_ARGUMENTS.include?(env_flag)
+            elsif env_token.match?(/\A[A-Za-z_][A-Za-z0-9_]*=/)
+              shebang_tokens.shift
+            else
+              break
+            end
+          end
+          executable = shebang_tokens.first.to_s
+        end
+
+        # Preserve direct interpreter paths so stale absolute Node shebangs fail with actionable binstub guidance.
+        NODE_BINSTUB_EXECUTABLES.include?(File.basename(executable)) ? executable : nil
+      end
     end
   end
 end

data/lib/shakapacker/version.rb

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

data/lib/shakapacker/version_checker.rb

@@ -1,4 +1,6 @@
 # frozen_string_literal: true
+require "yaml"
+
 require_relative "version"
 
 module Shakapacker
@@ -224,13 +226,19 @@ module Shakapacker
 
           def from_pnpm_lock
             require "yaml"
+            require "date"
+
+            # pnpm >= 10.16 writes a `time:` section; permit Time/Date so Psych 4+ doesn't raise DisallowedClass.
+            content = safe_load_pnpm_lock(File.read(@pnpm_lock))
 
-            content = YAML.load_file(@pnpm_lock)
+            packages = content.is_a?(Hash) ? (content["packages"] || {}) : {}
 
-            content.fetch("packages", {}).each do |key, value|
+            packages.each do |key, value|
               # git-based constraints will include a "version" key with their pseudo semantic version
-              return value["version"] if key.start_with?("shakapacker") && value.key?("version")
-              return value["version"] if value["name"] == "shakapacker"
+              if value.is_a?(Hash)
+                return value["version"] if key.start_with?("shakapacker") && value.key?("version")
+                return value["version"] if value["name"] == "shakapacker"
+              end
 
               # v9+ uses the same key format just without the leading slash, so we just add one in
               key = "/#{key}" unless key.start_with?("/")
@@ -248,6 +256,10 @@ module Shakapacker
 
             nil
           end
+
+          def safe_load_pnpm_lock(lockfile)
+            YAML.safe_load(lockfile, permitted_classes: [Time, Date])
+          end
       end
   end
 end

data/lib/tasks/shakapacker/export_bundler_config.rake

@@ -1,21 +1,6 @@
-namespace :shakapacker do
-  def shakapacker_config_binstub_command(bin_path)
-    # Read in binary mode so Windows CRLF line endings do not leak \r into the shebang.
-    shebang = File.open(bin_path, "rb", &:gets).to_s
-    command = shebang.delete_prefix("#!").strip.split(/\s+/)
-    executable = File.basename(command.first.to_s)
-
-    if executable == "env"
-      executable = File.basename(command.drop(1).find { |part| !part.start_with?("-") }.to_s)
-    end
-
-    # Legacy JS binstubs are dispatched via PATH lookup; Kernel#exec resolves
-    # "node" through the shell's PATH. The Ruby binstubs perform their own
-    # explicit lookup via shakapacker_find_executable, which matters more on
-    # Windows where PATHEXT is involved.
-    executable == "node" ? ["node", bin_path.to_s] : [RbConfig.ruby, bin_path.to_s]
-  end
+require "shakapacker/utils/misc"
 
+namespace :shakapacker do
   desc <<~DESC
     Export webpack or rspack configuration for debugging and analysis
 
@@ -62,7 +47,7 @@ namespace :shakapacker do
     # Try to use the binstub if it exists, otherwise use the gem's version
     bin_path = Rails.root.join("bin/shakapacker-config")
 
-    unless File.exist?(bin_path)
+    unless File.file?(bin_path)
       # Binstub not installed, use the gem's version directly
       gem_bin_path = File.expand_path("../../install/bin/shakapacker-config", __dir__)
 
@@ -75,10 +60,34 @@ namespace :shakapacker do
       end
     else
       # Pass through command-line arguments after the task name.
-      # Ruby binstubs run under the same Ruby as Rake; legacy JavaScript
-      # binstubs from upgraded apps still need Node until users refresh them.
+      #
+      # Modern Ruby binstubs (the current default) are invoked with
+      # RbConfig.ruby so they run under the same Ruby as Rake — this avoids
+      # version-manager/shebang mismatches and works on Windows.
+      #
+      # Legacy JavaScript binstubs left over from earlier Shakapacker
+      # versions (`#!/usr/bin/env node`) are invoked through Node until
+      # users refresh them with `rake shakapacker:binstubs`.
+      js_binstub_executable = Shakapacker::Utils::Misc.js_binstub_executable(bin_path)
+
       Dir.chdir(Rails.root) do
-        Kernel.exec(*shakapacker_config_binstub_command(bin_path), *ARGV[1..])
+        if js_binstub_executable
+          $stderr.puts "Note: bin/shakapacker-config is a legacy JavaScript binstub."
+          $stderr.puts "Run `bundle exec rake shakapacker:binstubs` to upgrade to the Ruby binstub."
+          $stderr.puts ""
+          begin
+            Kernel.exec(js_binstub_executable, bin_path.to_s, *ARGV[1..])
+          rescue Errno::ENOENT, Errno::EACCES
+            abort "Error: could not execute '#{js_binstub_executable}' because it was not found or is not executable.\n" \
+                  "Run `bundle exec rake shakapacker:binstubs` to upgrade to the Ruby binstub."
+          end
+        else
+          begin
+            Kernel.exec(RbConfig.ruby, bin_path.to_s, *ARGV[1..])
+          rescue Errno::ENOENT, Errno::EACCES
+            abort "Error: Ruby interpreter '#{RbConfig.ruby}' was not found or is not executable."
+          end
+        end
       end
     end
   end

data/lib/tasks/shakapacker/install.rake

@@ -1,13 +1,15 @@
+require "shakapacker/install/env"
+
 install_template_path = File.expand_path("../../install/template.rb", __dir__).freeze
 bin_path = ENV["BUNDLE_BIN"] || Rails.root.join("bin")
 
 namespace :shakapacker do
-  desc "Install Shakapacker in this application (use SHAKAPACKER_ASSETS_BUNDLER=rspack for Rspack, --typescript for TypeScript)"
+  desc "Install Shakapacker in this application (defaults to Rspack; pass webpack or SHAKAPACKER_ASSETS_BUNDLER=webpack for Webpack)"
   task :install, [:bundler, :typescript] => [:check_node] do |task, args|
     Shakapacker::Configuration.installing = true
 
-    if args[:bundler] == "rspack" || ENV["SHAKAPACKER_ASSETS_BUNDLER"] == "rspack"
-      ENV["SHAKAPACKER_ASSETS_BUNDLER"] = "rspack"
+    if (bundler_error = Shakapacker::Install::Env.apply_bundler_arg(args[:bundler]))
+      abort bundler_error
     end
 
     # Set typescript flag if passed as argument

data/lib/tasks/shakapacker.rake

@@ -1,6 +1,6 @@
 tasks = {
   "shakapacker:info"                    => "Provides information on Shakapacker's environment",
-  "shakapacker:install"                 => "Installs and setup webpack",
+  "shakapacker:install"                 => "Installs and sets up Shakapacker",
   "shakapacker:compile"                 => "Compiles webpack bundles based on environment",
   "shakapacker:clean"                   => "Remove old compiled bundles",
   "shakapacker:clobber"                 => "Removes the webpack compiled output directory",