Use Shakapacker's private_output_path instead of react_on_rails server_bundle_output_path

[justin808]

Use Shakapacker's private_output_path Instead of React on Rails server_bundle_output_path

Problem

React on Rails currently has its own server_bundle_output_path configuration (defaults to "ssr-generated") that duplicates functionality now available in Shakapacker's private_output_path configuration.

This creates several issues:

1. Configuration Duplication: Users must configure the same path in two places
2. Potential Mismatch: The two configs can get out of sync, causing runtime errors
3. Confusion: Users don't know which config takes precedence
4. Maintenance Burden: React on Rails has to maintain parallel functionality

Current State

In React on Rails (lib/react_on_rails/configuration.rb):

# Line 56
server_bundle_output_path: "ssr-generated"

There's even a TODO comment acknowledging this issue:

# Lines 59-61
# TODO: Add automatic detection of server_bundle_output_path from shakapacker.yml
# See feature/shakapacker-yml-integration branch for implementation
# Requires Shakapacker v8.5.0+ and semantic version checking

In Shakapacker (config/shakapacker.yml):

# Location for private server-side bundles (e.g., for SSR)
# These bundles are not served publicly, unlike public_output_path
# private_output_path: ssr-generated

Proposed Solution

Phase 1: Read from Shakapacker Config (Backward Compatible)

Update React on Rails to automatically read private_output_path from Shakapacker's configuration:

def setup_config_values
  # ... existing code ...
  
  # Auto-detect from Shakapacker if not explicitly set
  if server_bundle_output_path == "ssr-generated" # default value
    shakapacker_private_path = detect_shakapacker_private_output_path
    self.server_bundle_output_path = shakapacker_private_path if shakapacker_private_path.present?
  end
  
  # ... existing code ...
end

private

def detect_shakapacker_private_output_path
  return nil unless defined?(Shakapacker)
  
  # Try to read from Shakapacker config
  Shakapacker.config.private_output_path
rescue StandardError
  # Shakapacker version doesn't support private_output_path
  nil
end

Benefits:

• Fully backward compatible
• No breaking changes
• Users can still override via server_bundle_output_path if needed
• Automatically stays in sync with Shakapacker config

Phase 2: Update Generated Config Files

Update the generator template to reference Shakapacker's config:

Current (lib/generators/react_on_rails/templates/base/base/config/initializers/react_on_rails.rb.tt):

config.server_bundle_output_path = "ssr-generated"

Proposed:

# Server bundle output path is automatically read from shakapacker.yml's private_output_path
# To override, uncomment and set:
# config.server_bundle_output_path = "custom-path"

Phase 3: Deprecation Path (Future)

In a future major version:

1. Add deprecation warning when server_bundle_output_path is explicitly set
2. Eventually remove the config option entirely
3. Always use Shakapacker's private_output_path

Implementation Checklist

Phase 1: Auto-Detection (Target: Next Minor Release)

• Add detect_shakapacker_private_output_path method to Configuration class
• Update setup_config_values to auto-detect from Shakapacker
• Add version check for Shakapacker >= 9.x (when private_output_path was added)
• Add specs for auto-detection behavior
• Add specs for fallback to default when Shakapacker doesn't support it
• Update documentation to explain the precedence order

Phase 2: Update Generators

• Update react_on_rails.rb.tt template to comment out server_bundle_output_path
• Add comment explaining auto-detection from Shakapacker
• Add example showing how to set private_output_path in shakapacker.yml
• Update upgrade guide with migration instructions

Phase 3: Documentation

• Update main README to reference Shakapacker's private_output_path
• Add troubleshooting section for config mismatch issues
• Update React Server Components docs to use Shakapacker config
• Add example showing both configs in generated apps

Phase 4: Future Deprecation (v17.x or later)

• Add deprecation warning when server_bundle_output_path is set
• Update CHANGELOG with deprecation notice
• Plan removal for next major version

Benefits

1. Single Source of Truth: Shakapacker owns the bundler config
2. Automatic Sync: Changes to private_output_path are automatically picked up
3. Less Configuration: One less thing for users to configure
4. Better Integration: Tighter coupling with Shakapacker ecosystem
5. Easier Upgrades: Config changes happen in one place

Backward Compatibility

This approach is fully backward compatible:

• Existing apps with server_bundle_output_path set will continue to work
• Apps without it will automatically use Shakapacker's config
• No breaking changes required

Related

• React on Rails configuration: lib/react_on_rails/configuration.rb:56
• TODO comment: lib/react_on_rails/configuration.rb:59-61
• Shakapacker private_output_path: https://github.com/shakacode/shakapacker
• Related to enforce_private_server_bundles feature

Questions for Discussion

1. Should we require Shakapacker >= 9.x for this feature, or gracefully fall back?
2. Should we warn users if the two configs are set differently?
3. Timeline for eventual deprecation of server_bundle_output_path?

---

cc @justin808