Add Shakapacker precompile hook template for generator (#1916)

* Add Shakapacker precompile hook support for auto pack generation

This change leverages Shakapacker's new precompile_hook feature to
automatically generate packs before webpack compilation, replacing the
need to manually modify assets:precompile tasks or bin/dev scripts.

Changes:
- Add bin/shakapacker-precompile-hook script to templates and spec/dummy
- Update shakapacker.yml to configure precompile_hook
- Add PackerUtils.shakapacker_precompile_hook_configured? method
- Skip generate_packs in configuration and PackGenerator when hook configured
- Update generator to copy hook script and make it executable

The precompile hook runs before webpack compilation and is properly
validated by Shakapacker to ensure it points to a file within the
project root.

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

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

* Fix: Add execute permission to shakapacker-precompile-hook template

The template file needs execute permission to pass RuboCop's
Lint/ScriptPermission check.

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

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

* Fix: Skip validation in precompile hook to prevent generator failures

The shakapacker-precompile-hook was causing generator failures because
it loads the Rails environment (which triggers version validation)
before the react-on-rails npm package is installed during initial setup.

This fix adds ENV["REACT_ON_RAILS_SKIP_VALIDATION"] = "true" at the start
of the hook script to skip version validation, since the hook runs as part
of the build process and doesn't need package version validation.

Fixes CI failures in generator tests where the hook was executed during
`rails generate react_on_rails:install` before packages were installed.

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

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

* Fix: Disable yarn caching in examples workflow to prevent V8 crash

The examples.yml workflow was experiencing Node.js V8 crashes during
yarn cache dir commands, similar to the issue fixed in commit a1c71ea.
This commit applies the same fix - disabling yarn caching until the
upstream V8 issue is resolved.

Error observed:
```
# Fatal error in , line 0
# unreachable code
```

Tracking: actions/setup-node#1028

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

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

* Fix: Remove duplicate precompile_hook key in shakapacker.yml

The spec/dummy/config/shakapacker.yml had two `precompile_hook` entries
which caused a YAML parsing error:
  YAMLException: duplicated mapping key (31:3)

Removed the first instance at line 14, keeping the one with better
documentation at line 31.

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

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

* Fix: Correct misleading security comment in shakapacker.yml

The comment claimed "The hook command will be validated to ensure it
points to a file within the project root" but no such validation exists
in the codebase. Updated the comment to accurately reflect that users
must ensure the hook path points to a trusted file they control.

This removes the false promise of automatic validation and places the
security responsibility appropriately on the user configuring the hook.

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

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

* Fix: Correct precompile_hook detection to use top-level config key

The master's sophisticated hook detection was looking for the hook at
`:hooks/:precompile` but shakapacker.yml uses `precompile_hook` at the
top level. Updated `extract_precompile_hook` to look in the correct
location.

Also updated specs to match the sophisticated implementation that checks
if the hook actually contains the generate_packs rake task, rather than
just checking for any hook presence.

Fixes failing rspec-package-tests in CI.

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

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

---------

Co-authored-by: Claude <[email protected]>

Author: justin808

.github/workflows/examples.yml

@@ -66,8 +66,10 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: 20
-          cache: yarn
-          cache-dependency-path: '**/yarn.lock'
+          # TODO: Re-enable yarn caching once Node.js V8 cache crash is fixed
+          # Tracking: https://github.com/actions/setup-node/issues/1028
+          # cache: yarn
+          # cache-dependency-path: '**/yarn.lock'
       - name: Print system information
         run: |
           echo "Linux release: "; cat /etc/issue

lib/generators/react_on_rails/base_generator.rb

@@ -37,12 +37,16 @@ def copy_base_files
                         app/views/layouts/hello_world.html.erb
                         Procfile.dev
                         Procfile.dev-static-assets
-                        Procfile.dev-prod-assets]
+                        Procfile.dev-prod-assets
+                        bin/shakapacker-precompile-hook]
         base_templates = %w[config/initializers/react_on_rails.rb]
         base_files.each { |file| copy_file("#{base_path}#{file}", file) }
         base_templates.each do |file|
           template("#{base_path}/#{file}.tt", file)
         end
+
+        # Make the hook script executable (copy_file guarantees it exists)
+        File.chmod(0o755, File.join(destination_root, "bin/shakapacker-precompile-hook"))
       end
 
       def copy_js_bundle_files

lib/generators/react_on_rails/templates/base/base/bin/shakapacker-precompile-hook

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Shakapacker precompile hook for React on Rails
+#
+# This script runs before webpack compilation to generate pack files
+# for auto-bundled components. It's called automatically by Shakapacker
+# when configured in config/shakapacker.yml:
+#   precompile_hook: 'bin/shakapacker-precompile-hook'
+#
+# Emoji Scheme:
+#   🔄 = Running/in-progress
+#   ✅ = Success
+#   ❌ = Error
+
+# Skip validation during precompile hook execution
+# The hook runs early in the build process, potentially before full Rails initialization,
+# and doesn't need package version validation since it's part of the build itself
+ENV["REACT_ON_RAILS_SKIP_VALIDATION"] = "true"
+
+require_relative "../config/environment"
+
+begin
+  puts Rainbow("🔄 Running React on Rails precompile hook...").cyan
+  ReactOnRails::PacksGenerator.instance.generate_packs_if_stale
+rescue StandardError => e
+  warn Rainbow("❌ Error in precompile hook: #{e.message}").red
+  warn e.backtrace.first(5).join("\n")
+  exit 1
+end

lib/generators/react_on_rails/templates/base/base/config/shakapacker.yml

@@ -42,6 +42,11 @@ default: &default
   # Raises an error if there is a mismatch in the shakapacker gem and npm package being used
   ensure_consistent_versioning: true
 
+  # Hook to run before webpack compilation (e.g., for generating dynamic entry points)
+  # SECURITY: Only reference trusted scripts within your project. Ensure the hook path
+  # points to a file within the project root that you control.
+  precompile_hook: 'bin/shakapacker-precompile-hook'
+
   # Select whether the compiler will use SHA digest ('digest' option) or most recent modified timestamp ('mtime') to determine freshness
   compiler_strategy: digest
 

lib/react_on_rails/dev/server_manager.rb

@@ -248,7 +248,7 @@ def help_mode_details
           <<~MODES
             #{Rainbow('🔥 HMR Development mode (default)').cyan.bold} - #{Rainbow('Procfile.dev').green}:
             #{Rainbow('•').yellow} #{Rainbow('Hot Module Replacement (HMR) enabled').white}
-            #{Rainbow('•').yellow} #{Rainbow('React on Rails pack generation before Procfile start').white}
+            #{Rainbow('•').yellow} #{Rainbow('React on Rails pack generation (via precompile hook or bin/dev)').white}
             #{Rainbow('•').yellow} #{Rainbow('Webpack dev server for fast recompilation').white}
             #{Rainbow('•').yellow} #{Rainbow('Source maps for debugging').white}
             #{Rainbow('•').yellow} #{Rainbow('May have Flash of Unstyled Content (FOUC)').white}
@@ -257,15 +257,15 @@ def help_mode_details
 
             #{Rainbow('📦 Static development mode').cyan.bold} - #{Rainbow('Procfile.dev-static-assets').green}:
             #{Rainbow('•').yellow} #{Rainbow('No HMR (static assets with auto-recompilation)').white}
-            #{Rainbow('•').yellow} #{Rainbow('React on Rails pack generation before Procfile start').white}
+            #{Rainbow('•').yellow} #{Rainbow('React on Rails pack generation (via precompile hook or bin/dev)').white}
             #{Rainbow('•').yellow} #{Rainbow('Webpack watch mode for auto-recompilation').white}
             #{Rainbow('•').yellow} #{Rainbow('CSS extracted to separate files (no FOUC)').white}
             #{Rainbow('•').yellow} #{Rainbow('Development environment (faster builds than production)').white}
             #{Rainbow('•').yellow} #{Rainbow('Source maps for debugging').white}
             #{Rainbow('•').yellow} #{Rainbow('Access at:').white} #{Rainbow('http://localhost:3000/<route>').cyan.underline}
 
             #{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('React on Rails pack generation (via precompile hook or assets:precompile)').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}
@@ -281,16 +281,20 @@ def help_mode_details
         def run_production_like(_verbose: false, route: nil, rails_env: nil)
           procfile = "Procfile.dev-prod-assets"
 
+          features = [
+            "Precompiling assets with production optimizations",
+            "Running Rails server on port 3001",
+            "No HMR (Hot Module Replacement)",
+            "CSS extracted to separate files (no FOUC)"
+          ]
+
+          # NOTE: Pack generation happens automatically during assets:precompile
+          # either via precompile hook or via the configuration.rb adjust_precompile_task
+
           print_procfile_info(procfile, route: route)
           print_server_info(
             "🏭 Starting production-like development server...",
-            [
-              "Generating React on Rails packs",
-              "Precompiling assets with production optimizations",
-              "Running Rails server on port 3001",
-              "No HMR (Hot Module Replacement)",
-              "CSS extracted to separate files (no FOUC)"
-            ],
+            features,
             3001,
             route: route
           )
@@ -409,15 +413,22 @@ def run_production_like(_verbose: false, route: nil, rails_env: nil)
 
         def run_static_development(procfile, verbose: false, route: nil)
           print_procfile_info(procfile, route: route)
+
+          features = [
+            "Using shakapacker --watch (no HMR)",
+            "CSS extracted to separate files (no FOUC)",
+            "Development environment (source maps, faster builds)",
+            "Auto-recompiles on file changes"
+          ]
+
+          # Add pack generation info if not using precompile hook
+          unless ReactOnRails::PackerUtils.shakapacker_precompile_hook_configured?
+            features.unshift("Generating React on Rails packs")
+          end
+
           print_server_info(
             "⚡ Starting development server with static assets...",
-            [
-              "Generating React on Rails packs",
-              "Using shakapacker --watch (no HMR)",
-              "CSS extracted to separate files (no FOUC)",
-              "Development environment (source maps, faster builds)",
-              "Auto-recompiles on file changes"
-            ],
+            features,
             route: route
           )
 

lib/react_on_rails/packer_utils.rb

@@ -197,8 +197,8 @@ def self.extract_precompile_hook
       config_data = ::Shakapacker.config.send(:data)
 
       # Try symbol keys first (Shakapacker's internal format), then fall back to string keys
-      # Note: Currently only one hook value is supported, but this will change to support lists
-      config_data&.dig(:hooks, :precompile) || config_data&.dig("hooks", "precompile")
+      # The key is 'precompile_hook' at the top level of the config
+      config_data&.[](:precompile_hook) || config_data&.[]("precompile_hook")
     end
 
     def self.hook_contains_generate_packs?(hook_value)

spec/dummy/config/shakapacker.yml

@@ -8,10 +8,6 @@ default: &default
   # Using SWC for faster JavaScript transpilation (20x faster than Babel)
   javascript_transpiler: swc
 
-  # Hook to run before compilation (e.g., for ReScript builds, pack generation)
-  # See: https://github.com/shakacode/shakapacker/blob/main/docs/precompile_hook.md
-  precompile_hook: bin/shakapacker-precompile-hook
-
   cache_path: tmp/cache/shakapacker
   webpack_compile_output: false
   ensure_consistent_versioning: true
@@ -24,6 +20,11 @@ default: &default
   cache_manifest: false
   nested_entries: true
 
+  # Hook to run before webpack compilation (e.g., for generating dynamic entry points)
+  # SECURITY: Only reference trusted scripts within your project. Ensure the hook path
+  # points to a file within the project root that you control.
+  precompile_hook: 'bin/shakapacker-precompile-hook'
+
 development:
   <<: *default
   # Turn this to true if you want to use the rails/shakapacker check that the test