Summary

The precompile_hook configuration in shakapacker.yml is a powerful feature but lacks comprehensive documentation. Users need guidance on:

1. How the hook works and when it runs
2. When to use it vs. alternative approaches
3. How to handle projects with custom build requirements (ReScript, TypeScript, etc.)

Current Documentation Gap

The precompile_hook option is mentioned but not thoroughly documented:

• When exactly does it run? (Before each webpack compile? Once at startup?)
• How does it interact with shakapacker_precompile?
• What's the relationship with React on Rails' pack generation?
• When should projects NOT use the hook?

Proposed Documentation

1. How precompile_hook Works

# config/shakapacker.yml
default: &default
  precompile_hook: 'bin/shakapacker-precompile-hook'

Execution timing:

• Called by Shakapacker BEFORE webpack compilation starts
• In development with bin/dev: runs once at startup (if using React on Rails ServerManager)
• During rails assets:precompile: runs before webpack builds production assets
• Can be skipped via SHAKAPACKER_SKIP_PRECOMPILE_HOOK=true environment variable

2. When to Use precompile_hook

Good fit:

• React on Rails auto-bundling (pack generation)
• Simple precompile tasks that should run before every webpack build
• Projects using the default React on Rails setup

Example hook script:

#!/usr/bin/env ruby
require_relative "../config/environment"
ReactOnRails::PacksGenerator.instance.generate_packs_if_stale

3. Alternative: Explicit Precompile in bin/dev

For projects with custom build requirements, an alternative pattern avoids the hook entirely:

shakapacker.yml:

default: &default
  shakapacker_precompile: false
  # precompile_hook: not configured
  
  # Note: Precompile tasks handled by bin/dev before starting processes.
  # This approach is better for:
  # - Projects with custom build steps (ReScript, TypeScript, etc.)
  # - Avoiding version manager PATH issues with rake tasks
  # - Cleaner Procfiles without embedded shell commands

bin/dev with explicit precompile:

#!/usr/bin/env ruby
require "bundler/setup"

def run_precompile_tasks
  require_relative "../config/environment"
  
  puts "📦 Running precompile tasks..."
  
  # Custom: Build ReScript/TypeScript/etc.
  print "   Custom build... "
  system("yarn build:custom") or exit(1)
  puts "✅"
  
  # Locale generation via direct Ruby API (faster than rake task)
  print "   Locale generation... "
  ReactOnRails::Locales.compile
  puts "✅"
end

unless ARGV.include?("kill") || ARGV.include?("-h")
  run_precompile_tasks
end

# Start development server
require "react_on_rails/dev"
ReactOnRails::Dev::ServerManager.run_from_command_line(ARGV)

Clean Procfile.dev (no embedded precompile):

rails: bundle exec rails server -p 3000
wp-client: bin/shakapacker-dev-server
wp-server: SERVER_BUNDLE_ONLY=yes bin/shakapacker --watch

4. Comparison Table

5. Interplay with shakapacker_precompile

# Option A: Use Shakapacker's precompile (default)
shakapacker_precompile: true
precompile_hook: 'bin/shakapacker-precompile-hook'

# Option B: Use React on Rails' build commands
shakapacker_precompile: false
# Hook runs via React on Rails build_production_command

# Option C: Explicit precompile in bin/dev (no hook)
shakapacker_precompile: false
# precompile_hook: not configured
# Precompile handled by bin/dev or build commands

6. Environment Variables

Benefits of This Documentation

1. Clarity: Users understand when/how the hook runs
2. Flexibility: Documents alternative approaches for different project needs
3. Troubleshooting: Explains interaction between shakapacker_precompile and precompile_hook
4. Best practices: Guides users to the right approach for their project type

Reference

• react-webpack-rails-tutorial branch: justin808/shakapacker-early-hints
• Related React on Rails issue: Enhancement: Extensible bin/dev precompile pattern as alternative to precompile_hook react_on_rails#2347