Simplify configuration files to improve usability

docs/api-reference/configuration-deprecated.md

@@ -0,0 +1,52 @@
+# Deprecated Configuration Options
+
+This document lists configuration options that have been deprecated or removed from React on Rails.
+
+For current configuration options, see [configuration.md](configuration.md).
+
+## Removed Options
+
+### immediate_hydration
+
+**Status:** ⚠️ REMOVED in v17.0
+
+This configuration option has been removed. Immediate hydration is now automatically enabled for Pro users and disabled for non-Pro users.
+
+**Migration:** Remove any `config.immediate_hydration` lines from your configuration. Use per-component overrides if needed:
+
+```ruby
+# Pro users can disable for specific components:
+react_component("MyComponent", immediate_hydration: false)
+
+# Non-Pro users: immediate_hydration is ignored
+```
+
+See [CHANGELOG.md](../CHANGELOG.md) for details.
+
+## Deprecated Options
+
+### defer_generated_component_packs
+
+**Type:** Boolean
+**Default:** `false`
+**Status:** ⚠️ DEPRECATED
+
+**Deprecated:** Use `generated_component_packs_loading_strategy = :defer` instead.
+
+**Migration:**
+
+```ruby
+# Old (deprecated):
+config.defer_generated_component_packs = true
+
+# New:
+config.generated_component_packs_loading_strategy = :defer
+```
+
+See the [16.0.0 Release Notes](../upgrading/release-notes/16.0.0.md) for more details.
+
+## Need Help?
+
+- **Documentation:** [React on Rails Guides](https://www.shakacode.com/react-on-rails/docs/)
+- **Support:** [ShakaCode Forum](https://forum.shakacode.com/)
+- **Consulting:** [justin@shakacode.com](mailto:justin@shakacode.com)

docs/api-reference/configuration-pro.md

@@ -0,0 +1,40 @@
+# React on Rails Pro Configuration Options
+
+This document describes configuration options specific to React on Rails Pro features.
+
+For general React on Rails configuration options, see [configuration.md](configuration.md).
+
+## React Server Components (RSC)
+
+React Server Components and Streaming SSR are React on Rails Pro features.
+
+For detailed configuration of RSC and streaming features, see the Pro package documentation:
+[react_on_rails_pro/docs/configuration.md](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/docs/configuration.md)
+
+### Key Pro Configurations
+
+These options are configured in the `ReactOnRailsPro.configure` block:
+
+- `rsc_bundle_js_file` - Path to RSC bundle
+- `react_client_manifest_file` - Client component manifest for RSC
+- `react_server_client_manifest_file` - Server manifest for RSC
+- `enable_rsc_support` - Enable React Server Components
+
+### Example Configuration
+
+```ruby
+# config/initializers/react_on_rails_pro.rb
+ReactOnRailsPro.configure do |config|
+  config.rsc_bundle_js_file = "rsc-bundle.js"
+  config.react_client_manifest_file = "client-manifest.json"
+  config.react_server_client_manifest_file = "server-manifest.json"
+  config.enable_rsc_support = true
+end
+```
+
+See the Pro documentation for complete setup instructions.
+
+## Need Help?
+
+- **Pro Features:** [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/)
+- **Consulting:** [justin@shakacode.com](mailto:justin@shakacode.com)

lib/generators/react_on_rails/templates/base/base/config/initializers/react_on_rails.rb.tt

@@ -1,67 +1,36 @@
 # frozen_string_literal: true
 
-# See https://github.com/shakacode/react_on_rails/blob/master/docs/guides/configuration.md
-# for many more options.
+# React on Rails configuration
+# See https://github.com/shakacode/react_on_rails/blob/master/docs/api-reference/configuration.md
+# for complete documentation of all configuration options.
 
 ReactOnRails.configure do |config|
-  # This configures the script to run to build the production assets by webpack. Set this to nil
-  # if you don't want react_on_rails building this file for you.
-  # If nil, then the standard shakacode/shakapacker assets:precompile will run
-  # config.build_production_command = nil
-
-  ################################################################################
   ################################################################################
-  # TEST CONFIGURATION OPTIONS
-  # Below options are used with the use of this test helper:
-  # ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
+  # Server Rendering (Recommended)
   ################################################################################
-
-  # If you are using this in your spec_helper.rb (or rails_helper.rb):
-  #
-  # ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
-  #
-  # with rspec then this controls what npm command is run
-  # to automatically refresh your webpack assets on every test run.
-  #
-  # Alternately, you can remove the `ReactOnRails::TestHelper.configure_rspec_to_compile_assets`
-  # and set the config/shakapacker.yml option for test to true.
-  config.build_test_command = "RAILS_ENV=test bin/shakapacker"
+  # Configure server bundle for server-side rendering with `prerender: true`
+  # Set to "" if you're not using server rendering
+  config.server_bundle_js_file = "server-bundle.js"
 
   ################################################################################
+  # Test Configuration
+  # Used with ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
+  # Preferred alternative: set `compile: true` in config/shakapacker.yml for test env
   ################################################################################
-  # SERVER RENDERING OPTIONS
-  ################################################################################
-  # This is the file used for server rendering of React when using `(prerender: true)`
-  # If you are never using server rendering, you should set this to "".
-  # Note, there is only one server bundle, unlike JavaScript where you want to minimize the size
-  # of the JS sent to the client. For the server rendering, React on Rails creates a pool of
-  # JavaScript execution instances which should handle any component requested.
-  #
-  # While you may configure this to be the same as your client bundle file, this file is typically
-  # different. You should have ONE server bundle which can create all of your server rendered
-  # React components.
-  #
-  config.server_bundle_js_file = "server-bundle.js"
-
-  # Configure where server bundles are output. Defaults to "ssr-generated".
-  # This should match your webpack configuration for server bundles.
-  config.server_bundle_output_path = "ssr-generated"
-
-  # Enforce that server bundles are only loaded from private (non-public) directories.
-  # When true, server bundles will only be loaded from the configured server_bundle_output_path.
-  # This is recommended for production to prevent server-side code from being exposed.
-  config.enforce_private_server_bundles = true
+  config.build_test_command = "RAILS_ENV=test bin/shakapacker"
 
   ################################################################################
+  # Advanced Configuration
   ################################################################################
-  # FILE SYSTEM BASED COMPONENT REGISTRY
-  ################################################################################
-  # `components_subdirectory`  is the name of the matching directories that contain automatically registered components
-  # for use in the Rails views. The default is nil, you can enable the feature by updating it in the next line.
-  config.components_subdirectory = "ror_components"
+  # Most configuration options have sensible defaults and don't need to be set.
+  # For advanced options including:
+  # - File-based component registry (components_subdirectory, auto_load_bundle)
+  # - Component loading strategies (async/defer/sync)
+  # - Server bundle security and organization
+  # - I18n configuration
+  # - Server rendering pool configuration
+  # - Custom rendering extensions
+  # - And more...
   #
-  # For automated component registry, `render_component` view helper method tries to load bundle for component from
-  # generated directory. default is false, you can pass option at the time of individual usage or update the default
-  # in the following line
-  config.auto_load_bundle = true
+  # See: https://github.com/shakacode/react_on_rails/blob/master/docs/api-reference/configuration.md
 end

react_on_rails_pro/spec/dummy/config/initializers/react_on_rails.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
-# For documentation of parameters see: docs/basics/configuration.md
+# ⚠️ TEST CONFIGURATION - Do not copy directly for production apps
+# This is the Pro dummy app configuration used for testing React on Rails Pro features.
+# See docs/api-reference/configuration.md for production configuration guidance.
+
+# Advanced: Custom rendering extension to add values to railsContext
 module RenderingExtension
-  # Return a Hash that contains custom values from the view context that will get passed to
-  # all calls to react_component and redux_store for rendering
   def self.custom_context(view_context)
     if view_context.controller.is_a?(ActionMailer::Base)
       {}
@@ -15,6 +17,7 @@ def self.custom_context(view_context)
   end
 end
 
+# Advanced: Custom props extension for client-side hydration
 module RenderingPropsExtension
   def self.adjust_props_for_client_side_hydration(_component_name, props)
     if props.instance_of?(Hash)
@@ -26,19 +29,32 @@ def self.adjust_props_for_client_side_hydration(_component_name, props)
 end
 
 ReactOnRails.configure do |config|
+  ################################################################################
+  # Essential Configuration
+  ################################################################################
   config.server_bundle_js_file = "server-bundle.js"
+  config.components_subdirectory = "ror-auto-load-components"
+  config.auto_load_bundle = true
+
+  ################################################################################
+  # Pro Feature Testing: Server Bundle Security
+  ################################################################################
+  # Testing private server bundle enforcement (recommended for production)
+  config.enforce_private_server_bundles = true
+  config.server_bundle_output_path = "ssr-generated"
+
+  ################################################################################
+  # Test-specific Advanced Configuration
+  ################################################################################
+  # Testing with fixed DOM IDs for easier test assertions
   config.random_dom_id = false # default is true
 
-  # Next 2 lines are commented out because we've set test.compile to true
-  # config.build_test_command = "yarn run build:test"
-  # config.webpack_generated_files = %w[server-bundle.js manifest.json]
+  # Testing advanced rendering customization
   config.rendering_extension = RenderingExtension
-
   config.rendering_props_extension = RenderingPropsExtension
 
-  config.auto_load_bundle = true
-  config.components_subdirectory = "ror-auto-load-components"
-
-  config.enforce_private_server_bundles = true
-  config.server_bundle_output_path = "ssr-generated"
+  # NOTE: build_test_command and webpack_generated_files are commented out
+  # because we've set test.compile to true in shakapacker.yml
+  # config.build_test_command = "yarn run build:test"
+  # config.webpack_generated_files = %w[server-bundle.js manifest.json]
 end

react_on_rails_pro/spec/execjs-compatible-dummy/config/initializers/react_on_rails.rb

@@ -1,58 +1,31 @@
 # frozen_string_literal: true
 
-# See https://github.com/shakacode/react_on_rails/blob/master/docs/guides/configuration.md
-# for many more options.
+# ⚠️ TEST CONFIGURATION - Do not copy directly for production apps
+# This is the ExecJS-compatible dummy app for testing legacy webpacker compatibility.
+# See docs/api-reference/configuration.md for production configuration guidance.
 
 ReactOnRails.configure do |config|
-  # This configures the script to run to build the production assets by webpack. Set this to nil
-  # if you don't want react_on_rails building this file for you.
-  # If nil, then the standard shakacode/webpacker assets:precompile will run
-  # config.build_production_command = nil
-
-  ################################################################################
   ################################################################################
-  # TEST CONFIGURATION OPTIONS
-  # Below options are used with the use of this test helper:
-  # ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
+  # Essential Configuration
   ################################################################################
+  # Configure server bundle for server-side rendering
+  config.server_bundle_js_file = "server-bundle.js"
 
-  # If you are using this in your spec_helper.rb (or rails_helper.rb):
-  #
-  # ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
-  #
-  # with rspec then this controls what yarn command is run
-  # to automatically refresh your webpack assets on every test run.
-  #
-  # Alternately, you can remove the `ReactOnRails::TestHelper.configure_rspec_to_compile_assets`
-  # and set the config/webpacker.yml option for test to true.
+  # Test configuration
   config.build_test_command = "RAILS_ENV=test bin/webpacker"
 
   ################################################################################
+  # File System Based Component Registry (Optional - Disabled for this test)
   ################################################################################
-  # SERVER RENDERING OPTIONS
-  ################################################################################
-  # This is the file used for server rendering of React when using `(prerender: true)`
-  # If you are never using server rendering, you should set this to "".
-  # Note, there is only one server bundle, unlike JavaScript where you want to minimize the size
-  # of the JS sent to the client. For the server rendering, React on Rails creates a pool of
-  # JavaScript execution instances which should handle any component requested.
-  #
-  # While you may configure this to be the same as your client bundle file, this file is typically
-  # different. You should have ONE server bundle which can create all of your server rendered
-  # React components.
-  #
-  config.server_bundle_js_file = "server-bundle.js"
+  # Uncomment to enable automatic component registration:
+  # config.components_subdirectory = "ror_components"
+  # config.auto_load_bundle = true
+  config.auto_load_bundle = false
 
   ################################################################################
+  # Advanced Configuration
   ################################################################################
-  # FILE SYSTEM BASED COMPONENT REGISTRY
-  ################################################################################
-  # `components_subdirectory`  is the name of the matching directories that contain automatically registered components
-  # for use in the Rails views. The default is nil, you can enable the feature by updating it in the next line.
-  # config.components_subdirectory = "ror_components"
-  #
-  # For automated component registry, `render_component` view helper method tries to load bundle for component from
-  # generated directory. default is false, you can pass option at the time of individual usage or update the default
-  # in the following line
-  config.auto_load_bundle = false
+  # Most options have sensible defaults. For advanced configuration including
+  # component loading strategies, server bundle security, and more, see:
+  # https://github.com/shakacode/react_on_rails/blob/master/docs/api-reference/configuration.md
 end

spec/dummy/config/initializers/react_on_rails.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
-# For documentation of parameters see: docs/basics/configuration.md
+# ⚠️ TEST CONFIGURATION - Do not copy directly for production apps
+# This is the dummy app configuration used for testing React on Rails features.
+# See docs/api-reference/configuration.md for production configuration guidance.
+
+# Advanced: Custom rendering extension to add values to railsContext
 module RenderingExtension
-  # Return a Hash that contains custom values from the view context that will get passed to
-  # all calls to react_component and redux_store for rendering
   def self.custom_context(view_context)
     if view_context.controller.is_a?(ActionMailer::Base)
       {}
@@ -15,31 +17,36 @@ def self.custom_context(view_context)
   end
 end
 
+# Advanced: Custom props extension for client-side hydration
 module RenderingPropsExtension
-  # Return a Hash that contains custom props for all client rendered react_components
   def self.adjust_props_for_client_side_hydration(component_name, props)
     props[:modificationTarget] = "client-only" if component_name == "HelloWorldProps"
     props
   end
 end
 
 ReactOnRails.configure do |config|
+  ################################################################################
+  # Essential Configuration
+  ################################################################################
   config.server_bundle_js_file = "server-bundle.js"
-  config.random_dom_id = false # default is true
+  config.components_subdirectory = "startup"
+  config.auto_load_bundle = true
 
-  # Set server_bundle_output_path to nil so bundles are read from public path
-  # This ensures the dummy app uses the standard webpack output location
+  ################################################################################
+  # Test-specific Advanced Configuration
+  ################################################################################
+  # Testing server bundles from public path instead of private directory
   config.server_bundle_output_path = nil
   config.enforce_private_server_bundles = false
 
-  # Uncomment to test these
-  # config.build_test_command = "yarn run build:test"
-  # config.build_production_command = "RAILS_ENV=production NODE_ENV=production bin/shakapacker"
-  # config.webpack_generated_files = %w[server-bundle.js manifest.json]
-  config.rendering_extension = RenderingExtension
+  # Testing with fixed DOM IDs for easier test assertions
+  config.random_dom_id = false # default is true
 
-  config.rendering_props_extension = RenderingPropsExtension
-  config.components_subdirectory = "startup"
-  config.auto_load_bundle = true
+  # Testing with explicit loading strategy
   config.generated_component_packs_loading_strategy = :defer
+
+  # Testing advanced rendering customization
+  config.rendering_extension = RenderingExtension
+  config.rendering_props_extension = RenderingPropsExtension
 end