Delegate watch binstub ownership to Shakapacker

Author: ihabadham

CHANGELOG.md

@@ -37,6 +37,14 @@ After a release, run `/update-changelog` in Claude Code to analyze commits, writ
 
 #### Fixed
 
+- **Stopped replacing Shakapacker-owned watch binstubs during installation**: React on Rails no longer ships
+  its own `bin/shakapacker-watch` template. Generated Procfiles use Shakapacker's optional watch binstub when
+  it is present and fall back to `bin/shakapacker --watch` for older supported Shakapacker installations.
+  Existing Shakapacker-provided or customized watch binstubs remain untouched, including under `--force`. Fixes
+  [Issue 4617](https://github.com/shakacode/react_on_rails/issues/4617).
+  [PR 4715](https://github.com/shakacode/react_on_rails/pull/4715) by
+  [ihabadham](https://github.com/ihabadham).
+
 - **Server rendering no longer crashes on or corrupts lone UTF-16 surrogates**: When the JavaScript
   renderer emits a string containing a lone surrogate (commonly from truncating text mid-emoji, e.g. an
   excerpt cut with `slice`/`substring`), `JSON.stringify` serializes it as a `\uXXXX` escape that Ruby's

react_on_rails/lib/generators/react_on_rails/base_generator.rb

@@ -251,9 +251,7 @@ def copy_base_files
         ensure_new_app_root_route_initialized
 
         base_path = "base/base/"
-        base_files = %w[Procfile.dev
-                        Procfile.dev-static-assets
-                        Procfile.dev-prod-assets
+        base_files = %w[Procfile.dev-prod-assets
                         .dev-services.yml.example
                         .env.example
                         bin/shakapacker-precompile-hook]
@@ -262,7 +260,9 @@ def copy_base_files
         # Exception: Redux still needs the HelloWorld controller even with RSC
         base_files << "app/controllers/hello_world_controller.rb" unless use_rsc? && !options.redux?
         base_files << "app/controllers/home_controller.rb" if generate_new_app_home_page?
-        base_templates = %w[config/initializers/react_on_rails.rb]
+        base_templates = %w[Procfile.dev
+                            Procfile.dev-static-assets
+                            config/initializers/react_on_rails.rb]
         base_files.each { |file| copy_file("#{base_path}#{file}", file) }
         copy_react_on_rails_default_layout(base_path)
         warn_existing_hello_world_tailwind_layout

react_on_rails/lib/generators/react_on_rails/generator_helper.rb

@@ -492,6 +492,16 @@ def detect_react_version
     nil
   end
 
+  # Prefer Shakapacker's optional watcher binstub when the application has it. Older
+  # supported Shakapacker installations can still run watch mode through the required
+  # bin/shakapacker binstub, so React on Rails does not need to vendor a fallback watcher.
+  def shakapacker_watch_command
+    watch_binstub = File.join(destination_root, "bin/shakapacker-watch")
+    executable = File.exist?(watch_binstub) ? "bin/shakapacker-watch" : "bin/shakapacker"
+
+    "#{executable} --watch"
+  end
+
   # Check if Shakapacker 9.0 or higher is available
   # Returns true if Shakapacker >= 9.0, false otherwise
   #

react_on_rails/lib/generators/react_on_rails/install_generator.rb

@@ -675,15 +675,10 @@ def add_bin_scripts
 
         # Copy bin scripts from templates
         template_bin_path = "#{__dir__}/templates/base/base/bin"
-        shakapacker_watch_path = File.join(destination_root, "bin/shakapacker-watch")
-        preserve_existing_shakapacker_watch = File.exist?(shakapacker_watch_path)
-        # Always exclude these scripts from the bulk copy. `dev` needs app-specific patches,
-        # while Shakapacker owns its watch binstub when it provides one.
-        directory_options = { exclude_pattern: %r{/(?:dev|shakapacker-watch)(?:\.tt)?\z} }
+        # Always exclude `dev` from the bulk copy; it is handled explicitly below
+        # so we can patch DEFAULT_ROUTE and AUTO_OPEN_BROWSER_ONCE after copying.
+        directory_options = { exclude_pattern: %r{/dev(?:\.tt)?\z} }
         directory template_bin_path, "bin", directory_options
-        unless preserve_existing_shakapacker_watch
-          copy_file("#{template_bin_path}/shakapacker-watch", "bin/shakapacker-watch")
-        end
 
         if preserve_existing_bin_dev?
           if use_rsc? && !options.redux? && !options.new_app?
@@ -706,10 +701,7 @@ def add_bin_scripts
 
         # Make these and only these files executable. Use destination_root so
         # chmod remains correct even if an earlier generator step changed Dir.pwd.
-        files_to_become_executable = bin_scripts_to_chmod(
-          template_bin_path,
-          preserve_existing_shakapacker_watch:
-        )
+        files_to_become_executable = bin_scripts_to_chmod(template_bin_path)
         File.chmod(0o755, *files_to_become_executable)
       end
 
@@ -774,10 +766,8 @@ def preserve_existing_bin_dev?
         !!@preserve_existing_bin_dev
       end
 
-      def bin_scripts_to_chmod(template_bin_path, preserve_existing_shakapacker_watch:)
-        files = Dir.children(template_bin_path).reject do |filename|
-          filename == "dev" || (filename == "shakapacker-watch" && preserve_existing_shakapacker_watch)
-        end
+      def bin_scripts_to_chmod(template_bin_path)
+        files = Dir.children(template_bin_path).reject { |filename| filename == "dev" }
         files << "dev" unless preserve_existing_bin_dev?
         files.map { |filename| File.join(destination_root, "bin/#{filename}") }
       end

react_on_rails/lib/generators/react_on_rails/rsc_setup.rb

@@ -183,7 +183,7 @@ def add_rsc_to_procfile
             ⚠️  Procfile.dev not found. Skipping RSC bundle watcher addition.
 
             You'll need to add the RSC bundle watcher to your process manager manually:
-              rsc-bundle: RSC_BUNDLE_ONLY=true bin/shakapacker-watch --watch
+              rsc-bundle: RSC_BUNDLE_ONLY=true #{shakapacker_watch_command}
           MSG
           return
         end
@@ -198,7 +198,7 @@ def add_rsc_to_procfile
         rsc_watcher_line = <<~PROCFILE
 
           # React on Rails Pro - RSC bundle watcher
-          rsc-bundle: RSC_BUNDLE_ONLY=true bin/shakapacker-watch --watch
+          rsc-bundle: RSC_BUNDLE_ONLY=true #{shakapacker_watch_command}
         PROCFILE
 
         append_to_file("Procfile.dev", rsc_watcher_line)

…tes/base/base/Procfile.dev-static-assets …/base/base/Procfile.dev-static-assets.ttreact_on_rails/lib/generators/react_on_rails/templates/base/base/Procfile.dev-static-assets renamed to react_on_rails/lib/generators/react_on_rails/templates/base/base/Procfile.dev-static-assets.tt react_on_rails/lib/generators/react_on_rails/templates/base/base/Procfile.dev-static-assets renamed to react_on_rails/lib/generators/react_on_rails/templates/base/base/Procfile.dev-static-assets.tt

@@ -1,2 +1,2 @@
 web: bin/rails server -p ${PORT:-3000}
-js: bin/shakapacker-watch --watch
+js: <%= shakapacker_watch_command %>

…n_rails/templates/base/base/Procfile.dev …ails/templates/base/base/Procfile.dev.ttreact_on_rails/lib/generators/react_on_rails/templates/base/base/Procfile.dev renamed to react_on_rails/lib/generators/react_on_rails/templates/base/base/Procfile.dev.tt react_on_rails/lib/generators/react_on_rails/templates/base/base/Procfile.dev renamed to react_on_rails/lib/generators/react_on_rails/templates/base/base/Procfile.dev.tt

@@ -7,4 +7,4 @@
 # For manual worktree setup (no base-port tool), see .env.example.
 rails: bundle exec rails s -p ${PORT:-3000}
 dev-server: bin/shakapacker-dev-server
-server-bundle: SERVER_BUNDLE_ONLY=true bin/shakapacker-watch --watch
+server-bundle: SERVER_BUNDLE_ONLY=true <%= shakapacker_watch_command %>

react_on_rails/lib/generators/react_on_rails/templates/base/base/bin/shakapacker-watch

@@ -1,20 +1,71 @@
 #!/usr/bin/env sh
 set -eu
 
+show_help() {
+  cat <<'HELP'
+Usage: bin/shakapacker-watch [OPTIONS]
+
+Signal-safe wrapper around bin/shakapacker for Procfile-based workflows
+(foreman, overmind, bin/dev). Traps INT/TERM signals and forwards TERM
+to the child process, preventing Ruby interrupt backtraces on Ctrl-C.
+
+All options are passed through to bin/shakapacker. Common options:
+
+  --watch, -w          Watch for file changes and rebuild
+  --progress           Show build progress
+  --help, -h           Show this help
+  --version, -v        Show version (from bin/shakapacker)
+
+Examples:
+  bin/shakapacker-watch --watch              # Procfile watcher
+  bin/shakapacker-watch --watch --progress   # Procfile watcher with progress
+
+Procfile example:
+  web: bin/rails s
+  js: bin/shakapacker-watch --watch
+HELP
+  exit 0
+}
+
+case "${1:-}" in
+  -h|--help) show_help ;;
+esac
+
 child_pid=""
+shutdown_requested=""
+script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
 
 cleanup() {
-  if [ -n "${child_pid}" ] && kill -0 "$child_pid" 2>/dev/null; then
+  shutdown_requested=1
+  if [ -z "${child_pid}" ]; then
+    return
+  fi
+
+  if kill -0 "$child_pid" 2>/dev/null; then
     kill -TERM "$child_pid" 2>/dev/null || true
+    i=0
+    while [ "$i" -lt 50 ] && kill -0 "$child_pid" 2>/dev/null; do
+      sleep 0.1
+      i=$((i + 1))
+    done
+
+    if kill -0 "$child_pid" 2>/dev/null; then
+      kill -KILL "$child_pid" 2>/dev/null || true
+    fi
+
     wait "$child_pid" 2>/dev/null || true
   fi
 
   exit 0
 }
 
-bin/shakapacker "$@" &
-child_pid=$!
 trap cleanup INT TERM
+"$script_dir/shakapacker" "$@" &
+child_pid=$!
+
+if [ -n "$shutdown_requested" ]; then
+  cleanup
+fi
 
 if wait "$child_pid"; then
   status=0

react_on_rails/spec/dummy/bin/shakapacker-watch

@@ -461,18 +461,15 @@ def run_add_agent_files(options = {})
       end
     end
 
-    it "creates the shakapacker watch wrapper and uses it in Procfiles" do
-      assert_file "bin/shakapacker-watch" do |content|
-        expect(content).to include('bin/shakapacker "$@" &')
-        expect(content).to include("trap cleanup INT TERM")
-      end
+    it "uses the standard Shakapacker command when the optional watch binstub is absent" do
+      assert_no_file "bin/shakapacker-watch"
 
       assert_file "Procfile.dev" do |content|
-        expect(content).to include("server-bundle: SERVER_BUNDLE_ONLY=true bin/shakapacker-watch --watch")
+        expect(content).to include("server-bundle: SERVER_BUNDLE_ONLY=true bin/shakapacker --watch")
       end
 
       assert_file "Procfile.dev-static-assets" do |content|
-        expect(content).to include("js: bin/shakapacker-watch --watch")
+        expect(content).to include("js: bin/shakapacker --watch")
       end
     end
 
@@ -513,6 +510,38 @@ def run_add_agent_files(options = {})
     end
   end
 
+  context "when the Shakapacker watch binstub is already installed" do
+    shakapacker_watch = <<~RUBY
+      #!/usr/bin/env ruby
+      puts "Shakapacker-owned watcher"
+    RUBY
+
+    before(:all) do
+      run_generator_test_with_args(%w[], package_json: true) do
+        simulate_preinstalled_shakapacker(source_path: "app/javascript", source_entry_path: "packs")
+        simulate_existing_file("bin/shakapacker-watch", shakapacker_watch)
+        File.chmod(0o640, File.join(destination_root, "bin/shakapacker-watch"))
+      end
+    end
+
+    it "preserves Shakapacker's binstub under --force" do
+      assert_file "bin/shakapacker-watch" do |content|
+        expect(content).to eq(shakapacker_watch)
+      end
+      expect(File.stat(File.join(destination_root, "bin/shakapacker-watch")).mode & 0o777).to eq(0o640)
+    end
+
+    it "uses Shakapacker's binstub in generated Procfiles" do
+      assert_file "Procfile.dev" do |content|
+        expect(content).to include("server-bundle: SERVER_BUNDLE_ONLY=true bin/shakapacker-watch --watch")
+      end
+
+      assert_file "Procfile.dev-static-assets" do |content|
+        expect(content).to include("js: bin/shakapacker-watch --watch")
+      end
+    end
+  end
+
   context "with a pre-installed custom Shakapacker source root" do
     before(:all) do
       run_generator_test_with_args(%w[], package_json: true, force: false) do
@@ -3580,7 +3609,7 @@ class ActiveSupport::TestCase
       assert_file "Procfile.dev" do |content|
         expect(content).to include("RSC_BUNDLE_ONLY=true")
         expect(content).to include("rsc-bundle:")
-        expect(content).to include("bin/shakapacker-watch --watch")
+        expect(content).to include("bin/shakapacker --watch")
       end
     end
 
@@ -4760,12 +4789,7 @@ class ActiveSupport::TestCase
 
     it "does not chmod copied bin scripts in pretend mode" do
       allow(install_generator).to receive(:directory)
-      allow(install_generator).to receive(:copy_file).and_call_original
       allow(install_generator).to receive(:use_rsc?).and_return(false)
-      shakapacker_watch_template = File.expand_path(
-        "../../../lib/generators/react_on_rails/templates/base/base/bin/shakapacker-watch",
-        __dir__
-      )
 
       expect(install_generator).to receive(:say_status)
         .with(:gsub, "bin/dev", true)
@@ -4776,9 +4800,6 @@ class ActiveSupport::TestCase
       expect(File).not_to receive(:chmod)
 
       install_generator.send(:add_bin_scripts)
-
-      expect(install_generator).to have_received(:copy_file)
-        .with(shakapacker_watch_template, "bin/shakapacker-watch")
     end
 
     it "does not install typescript dependencies in pretend mode" do
@@ -6327,39 +6348,6 @@ class ActiveSupport::TestCase
       expect(File.stat(shakapacker_watch_path).mode & 0o777).to eq(0o640)
     end
 
-    it "preserves an existing Shakapacker watch binstub when run with --force" do
-      shakapacker_watch = <<~RUBY
-        #!/usr/bin/env ruby
-        puts "Customized watcher"
-      RUBY
-      shakapacker_watch_path = File.join(destination_root, "bin/shakapacker-watch")
-      force_generator = described_class.new([], { force: true }, destination_root:)
-      simulate_existing_file("bin/shakapacker-watch", shakapacker_watch)
-      File.chmod(0o640, shakapacker_watch_path)
-
-      Dir.chdir(destination_root) do
-        force_generator.send(:add_bin_scripts)
-      end
-
-      expect(File.read(shakapacker_watch_path)).to eq(shakapacker_watch)
-      expect(File.stat(shakapacker_watch_path).mode & 0o777).to eq(0o640)
-    end
-
-    it "installs the React on Rails Shakapacker watch fallback when the binstub is absent" do
-      template_path = File.expand_path(
-        "../../../lib/generators/react_on_rails/templates/base/base/bin/shakapacker-watch",
-        __dir__
-      )
-      shakapacker_watch_path = File.join(destination_root, "bin/shakapacker-watch")
-
-      Dir.chdir(destination_root) do
-        install_generator.send(:add_bin_scripts)
-      end
-
-      expect(File.read(shakapacker_watch_path)).to eq(File.read(template_path))
-      expect(File.stat(shakapacker_watch_path).mode & 0o777).to eq(0o755)
-    end
-
     it "detects custom bin/dev files" do
       simulate_existing_file("bin/dev", "#!/usr/bin/env ruby\nputs 'custom'\n")