Add automatic precompile hook coordination in bin/dev

The bin/dev command now automatically runs Shakapacker's precompile_hook
once before starting development processes and sets
SHAKAPACKER_SKIP_PRECOMPILE_HOOK=true to prevent duplicate execution in
spawned webpack processes.

Key improvements:
- Executes precompile_hook once before launching Procfile processes
- Sets SHAKAPACKER_SKIP_PRECOMPILE_HOOK environment variable
- All spawned processes inherit the variable to prevent re-execution
- Displays warning for Shakapacker versions below 9.4.0
- Skips hook execution for help and kill commands

This eliminates the need for:
- Manual coordination in Procfile.dev
- Sleep hacks to sequence tasks
- Duplicate task calls across processes
- Race conditions when multiple processes generate files

Users can now configure expensive build tasks (locale generation, ReScript
compilation, etc.) once in config/shakapacker.yml and bin/dev handles the
coordination automatically.

Changes:
- lib/react_on_rails/dev/server_manager.rb: Added hook execution logic
  with version warning for Shakapacker < 9.4.0
- spec/react_on_rails/dev/server_manager_spec.rb: Added comprehensive
  tests for hook execution, environment variable setting, and version
  warnings
- docs/building-features/process-managers.md: Updated documentation with
  precompile hook integration details and version requirements
- CHANGELOG.md: Added entry for automatic precompile hook coordination

Addresses #2091

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

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

Author: justin808

CHANGELOG.md

@@ -25,6 +25,8 @@ Changes since the last non-beta release.
 
 #### Improved
 
+- **Automatic Precompile Hook Coordination in bin/dev**: The `bin/dev` command now automatically runs Shakapacker's `precompile_hook` once before starting development processes and sets `SHAKAPACKER_SKIP_PRECOMPILE_HOOK=true` to prevent duplicate execution in spawned webpack processes. This eliminates the need for manual coordination, sleep hacks, and duplicate task calls in Procfile.dev. Users can now configure expensive build tasks (like locale generation or ReScript compilation) once in `config/shakapacker.yml` and `bin/dev` will handle the coordination automatically. The feature includes a warning for users on Shakapacker versions below 9.4.0, as the `SHAKAPACKER_SKIP_PRECOMPILE_HOOK` environment variable is only supported in 9.4.0+. Addresses [2091](https://github.com/shakacode/react_on_rails/issues/2091) by [justin808](https://github.com/justin808).
+
 - **Idempotent Locale Generation**: The `react_on_rails:locale` rake task is now idempotent, automatically skipping generation when locale files are already up-to-date. This makes it safe to call multiple times (e.g., in Shakapacker's `precompile_hook`) without duplicate work. Added `force=true` option to override timestamp checking. [PR 2092](https://github.com/shakacode/react_on_rails/pull/2092) by [justin808](https://github.com/justin808).
 
 ### [v16.2.0.beta.12] - 2025-11-20

docs/building-features/process-managers.md

@@ -16,9 +16,46 @@ React on Rails includes `bin/dev` which automatically uses Overmind or Foreman:
 
 This script will:
 
-1. Try to use Overmind (if installed)
-2. Fall back to Foreman (if installed)
-3. Show installation instructions if neither is found
+1. Run Shakapacker's `precompile_hook` once (if configured in `config/shakapacker.yml`)
+2. Set `SHAKAPACKER_SKIP_PRECOMPILE_HOOK=true` to prevent duplicate execution
+3. Try to use Overmind (if installed)
+4. Fall back to Foreman (if installed)
+5. Show installation instructions if neither is found
+
+### Precompile Hook Integration
+
+If you have configured a `precompile_hook` in `config/shakapacker.yml`, `bin/dev` will automatically:
+
+- Execute the hook **once** before starting development processes
+- Set the `SHAKAPACKER_SKIP_PRECOMPILE_HOOK` environment variable
+- Pass this environment variable to all spawned processes (Rails, webpack, etc.)
+- Prevent webpack processes from re-running the hook independently
+
+**Note:** The `SHAKAPACKER_SKIP_PRECOMPILE_HOOK` environment variable is supported in Shakapacker 9.4.0 and later. If you're using an earlier version, `bin/dev` will display a warning recommending you upgrade to avoid duplicate hook execution.
+
+This eliminates the need for manual coordination in your `Procfile.dev`. For example:
+
+**Before (manual coordination with sleep hacks):**
+
+```procfile
+# Procfile.dev
+wp-server: sleep 15 && bundle exec rake react_on_rails:locale && bin/shakapacker --watch
+```
+
+**After (automatic coordination via bin/dev):**
+
+```procfile
+# Procfile.dev
+wp-server: bin/shakapacker --watch
+```
+
+```yaml
+# config/shakapacker.yml
+default: &default
+  precompile_hook: 'bundle exec rake react_on_rails:locale'
+```
+
+See the [i18n documentation](./i18n.md#internationalization) for more details on configuring the precompile hook.
 
 ## Installing a Process Manager
 

lib/react_on_rails/dev/server_manager.rb

@@ -8,6 +8,8 @@
 module ReactOnRails
   module Dev
     class ServerManager
+      HELP_FLAGS = ["-h", "--help"].freeze
+
       class << self
         def start(mode = :development, procfile = nil, verbose: false, route: nil, rails_env: nil)
           case mode
@@ -145,10 +147,17 @@ def show_help
           puts help_troubleshooting
         end
 
-        # rubocop:disable Metrics/AbcSize
+        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
         def run_from_command_line(args = ARGV)
           require "optparse"
 
+          # Get the command early to check for help/kill before running hooks
+          # We need to do this before OptionParser processes flags like -h/--help
+          command = args.find { |arg| !arg.start_with?("--") && !arg.start_with?("-") }
+
+          # Check if help flags are present in args (before OptionParser processes them)
+          help_requested = args.any? { |arg| HELP_FLAGS.include?(arg) }
+
           options = { route: nil, rails_env: nil, verbose: false }
 
           OptionParser.new do |opts|
@@ -172,8 +181,12 @@ def run_from_command_line(args = ARGV)
             end
           end.parse!(args)
 
-          # Get the command (anything that's not parsed as an option)
-          command = args[0]
+          # Run precompile hook once before starting any mode (except kill/help)
+          # Then set environment variable to prevent duplicate execution in spawned processes
+          unless %w[kill help].include?(command) || help_requested
+            run_precompile_hook_if_present
+            ENV["SHAKAPACKER_SKIP_PRECOMPILE_HOOK"] = "true"
+          end
 
           # Main execution
           case command
@@ -184,7 +197,7 @@ def run_from_command_line(args = ARGV)
             start(:static, "Procfile.dev-static-assets", verbose: options[:verbose], route: options[:route])
           when "kill"
             kill_processes
-          when "help", "--help", "-h"
+          when "help"
             show_help
           when "hmr", nil
             start(:development, "Procfile.dev", verbose: options[:verbose], route: options[:route])
@@ -194,10 +207,55 @@ def run_from_command_line(args = ARGV)
             exit 1
           end
         end
-        # rubocop:enable Metrics/AbcSize
+        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
 
         private
 
+        # rubocop:disable Metrics/AbcSize
+        def run_precompile_hook_if_present
+          hook_value = PackerUtils.shakapacker_precompile_hook_value
+          return unless hook_value
+
+          # Warn if Shakapacker version doesn't support SHAKAPACKER_SKIP_PRECOMPILE_HOOK
+          warn_if_shakapacker_version_too_old
+
+          puts Rainbow("🔧 Running Shakapacker precompile hook...").cyan
+          puts Rainbow("   Command: #{hook_value}").cyan
+          puts ""
+
+          unless system(hook_value.to_s)
+            puts ""
+            puts Rainbow("❌ Precompile hook failed!").red.bold
+            puts Rainbow("   Command: #{hook_value}").red
+            puts ""
+            puts Rainbow("💡 Fix the hook command in config/shakapacker.yml or remove it to continue").yellow
+            exit 1
+          end
+
+          puts Rainbow("✅ Precompile hook completed successfully").green
+          puts ""
+        end
+        # rubocop:enable Metrics/AbcSize
+
+        # rubocop:disable Metrics/AbcSize
+        def warn_if_shakapacker_version_too_old
+          return unless PackerUtils.shakapacker_version_requirement_met?("9.0.0")
+          return if PackerUtils.shakapacker_version_requirement_met?("9.4.0")
+
+          puts ""
+          puts Rainbow("⚠️  Warning: Shakapacker #{PackerUtils.shakapacker_version} detected").yellow.bold
+          puts ""
+          puts Rainbow("   The SHAKAPACKER_SKIP_PRECOMPILE_HOOK environment variable is not").yellow
+          puts Rainbow("   supported in Shakapacker versions below 9.4.0. This may cause the").yellow
+          puts Rainbow("   precompile_hook to run multiple times (once by bin/dev, and again").yellow
+          puts Rainbow("   by each webpack process).").yellow
+          puts ""
+          puts Rainbow("   Recommendation: Upgrade to Shakapacker 9.4.0 or later:").cyan
+          puts Rainbow("   bundle update shakapacker").cyan.bold
+          puts ""
+        end
+        # rubocop:enable Metrics/AbcSize
+
         def help_usage
           Rainbow("📋 Usage: bin/dev [command] [options]").bold
         end

spec/react_on_rails/dev/server_manager_spec.rb

@@ -268,4 +268,165 @@ def mock_system_calls
       expect { described_class.show_help }.to output(%r{Usage: bin/dev \[command\]}).to_stdout_from_any_process
     end
   end
+
+  describe ".run_from_command_line with precompile hook" do
+    before do
+      mock_system_calls
+      # Clear environment variable before each test
+      ENV.delete("SHAKAPACKER_SKIP_PRECOMPILE_HOOK")
+    end
+
+    context "when precompile hook is configured" do
+      before do
+        # Default to a version that supports the skip flag (no warning)
+        allow(ReactOnRails::PackerUtils).to receive_messages(
+          shakapacker_precompile_hook_value: "bundle exec rake react_on_rails:locale", shakapacker_version: "9.4.0"
+        )
+        allow(ReactOnRails::PackerUtils).to receive(:shakapacker_version_requirement_met?)
+          .with("9.0.0").and_return(true)
+        allow(ReactOnRails::PackerUtils).to receive(:shakapacker_version_requirement_met?)
+          .with("9.4.0").and_return(true)
+      end
+
+      it "runs the hook and sets environment variable for development mode" do
+        expect_any_instance_of(Kernel)
+          .to receive(:system)
+          .with("bundle exec rake react_on_rails:locale")
+          .and_return(true)
+
+        described_class.run_from_command_line([])
+
+        expect(ENV.fetch("SHAKAPACKER_SKIP_PRECOMPILE_HOOK", nil)).to eq("true")
+      end
+
+      it "runs the hook and sets environment variable for static mode" do
+        expect_any_instance_of(Kernel)
+          .to receive(:system)
+          .with("bundle exec rake react_on_rails:locale")
+          .and_return(true)
+
+        described_class.run_from_command_line(["static"])
+
+        expect(ENV.fetch("SHAKAPACKER_SKIP_PRECOMPILE_HOOK", nil)).to eq("true")
+      end
+
+      it "runs the hook and sets environment variable for prod mode" do
+        env = { "NODE_ENV" => "production" }
+        argv = ["bundle", "exec", "rails", "assets:precompile"]
+        status_double = instance_double(Process::Status, success?: true)
+        expect(Open3).to receive(:capture3).with(env, *argv).and_return(["output", "", status_double])
+
+        expect_any_instance_of(Kernel)
+          .to receive(:system)
+          .with("bundle exec rake react_on_rails:locale")
+          .and_return(true)
+
+        described_class.run_from_command_line(["prod"])
+
+        expect(ENV.fetch("SHAKAPACKER_SKIP_PRECOMPILE_HOOK", nil)).to eq("true")
+      end
+
+      it "exits when hook fails" do
+        expect_any_instance_of(Kernel)
+          .to receive(:system)
+          .with("bundle exec rake react_on_rails:locale")
+          .and_return(false)
+        expect_any_instance_of(Kernel).to receive(:exit).with(1)
+
+        described_class.run_from_command_line([])
+      end
+
+      it "does not run hook or set environment variable for kill command" do
+        expect_any_instance_of(Kernel).not_to receive(:system).with("bundle exec rake react_on_rails:locale")
+
+        described_class.run_from_command_line(["kill"])
+
+        expect(ENV.fetch("SHAKAPACKER_SKIP_PRECOMPILE_HOOK", nil)).to be_nil
+      end
+
+      it "does not run hook or set environment variable for help command" do
+        expect_any_instance_of(Kernel).not_to receive(:system).with("bundle exec rake react_on_rails:locale")
+
+        described_class.run_from_command_line(["help"])
+
+        expect(ENV.fetch("SHAKAPACKER_SKIP_PRECOMPILE_HOOK", nil)).to be_nil
+      end
+
+      it "does not run hook or set environment variable for -h flag" do
+        expect_any_instance_of(Kernel).not_to receive(:system).with("bundle exec rake react_on_rails:locale")
+
+        # The -h flag is handled by OptionParser and calls exit during option parsing
+        # We need to mock exit to prevent the test from actually exiting
+        allow_any_instance_of(Kernel).to receive(:exit)
+
+        described_class.run_from_command_line(["-h"])
+
+        expect(ENV.fetch("SHAKAPACKER_SKIP_PRECOMPILE_HOOK", nil)).to be_nil
+      end
+
+      context "with Shakapacker version below 9.4.0" do
+        before do
+          allow(ReactOnRails::PackerUtils).to receive(:shakapacker_version).and_return("9.3.0")
+          allow(ReactOnRails::PackerUtils).to receive(:shakapacker_version_requirement_met?)
+            .with("9.0.0").and_return(true)
+          allow(ReactOnRails::PackerUtils).to receive(:shakapacker_version_requirement_met?)
+            .with("9.4.0").and_return(false)
+        end
+
+        it "displays warning about unsupported SHAKAPACKER_SKIP_PRECOMPILE_HOOK" do
+          expect_any_instance_of(Kernel)
+            .to receive(:system)
+            .with("bundle exec rake react_on_rails:locale")
+            .and_return(true)
+
+          expect do
+            described_class.run_from_command_line([])
+          end.to output(/Warning: Shakapacker 9\.3\.0 detected/).to_stdout_from_any_process
+
+          expect(ENV.fetch("SHAKAPACKER_SKIP_PRECOMPILE_HOOK", nil)).to eq("true")
+        end
+      end
+
+      context "with Shakapacker version 9.4.0 or later" do
+        before do
+          allow(ReactOnRails::PackerUtils).to receive(:shakapacker_version).and_return("9.4.0")
+          allow(ReactOnRails::PackerUtils).to receive(:shakapacker_version_requirement_met?)
+            .with("9.0.0").and_return(true)
+          allow(ReactOnRails::PackerUtils).to receive(:shakapacker_version_requirement_met?)
+            .with("9.4.0").and_return(true)
+        end
+
+        it "does not display warning" do
+          expect_any_instance_of(Kernel)
+            .to receive(:system)
+            .with("bundle exec rake react_on_rails:locale")
+            .and_return(true)
+
+          expect do
+            described_class.run_from_command_line([])
+          end.not_to output(/Warning: Shakapacker/).to_stdout_from_any_process
+        end
+      end
+    end
+
+    context "when no precompile hook is configured" do
+      before do
+        allow(ReactOnRails::PackerUtils).to receive(:shakapacker_precompile_hook_value).and_return(nil)
+      end
+
+      it "does not run any hook but still sets environment variable for development mode" do
+        expect_any_instance_of(Kernel).not_to receive(:system)
+
+        described_class.run_from_command_line([])
+
+        expect(ENV.fetch("SHAKAPACKER_SKIP_PRECOMPILE_HOOK", nil)).to eq("true")
+      end
+
+      it "does not set environment variable for kill command" do
+        described_class.run_from_command_line(["kill"])
+
+        expect(ENV.fetch("SHAKAPACKER_SKIP_PRECOMPILE_HOOK", nil)).to be_nil
+      end
+    end
+  end
 end