Improve configuration documentation based on code review feedback

Address code review suggestions to improve clarity and usability of
configuration documentation and generated config files.

Key improvements:

Documentation clarity:
- Remove redundant Quick Start code block, reference Essential Configuration instead
- Add clarification that build_test_command is used with TestHelper
- Add context for File-Based Component Registry explaining use cases
- Add stronger warning to server_bundle_output_path with prominent notice
- Add use case guidance for when to override auto-configured settings
- Add "When to disable" guidance for replay_console option
- Add introductory context for I18n configuration section

Generated template improvements:
- Clarify build_test_command usage with TestHelper in comments
- Emphasize that compile: true in shakapacker.yml is preferred alternative

Dummy app improvements:
- Add prominent warning to all dummy app configs to prevent cargo-culting
- Clearly mark as "TEST CONFIGURATION - Do not copy directly for production"

All changes maintain backward compatibility and improve the developer
experience by providing clearer guidance on which options need configuration
and when to override defaults.

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

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

Author: justin808

docs/api-reference/configuration.md

@@ -6,16 +6,7 @@ This document describes all configuration options for React on Rails. Configurat
 
 ## Quick Start
 
-For most applications, your configuration file can be as simple as:
-
-```ruby
-ReactOnRails.configure do |config|
-  config.server_bundle_js_file = "server-bundle.js"
-  config.build_test_command = "RAILS_ENV=test bin/shakapacker"
-end
-```
-
-See [Essential Configuration](#essential-configuration) below for the options you'll commonly use.
+See [Essential Configuration](#essential-configuration) below for the minimal configuration options you'll commonly use. Most applications only need 1-2 settings!
 
 ## Prerequisites
 
@@ -65,7 +56,7 @@ React on Rails configuration options are organized into two categories:
 Options you'll commonly configure for most applications:
 
 - `server_bundle_js_file` - Server rendering bundle (recommended)
-- `build_test_command` - Test environment build command (alternative to Shakapacker compile setting)
+- `build_test_command` - Test environment build command (used with `ReactOnRails::TestHelper.configure_rspec_to_compile_assets`)
 
 ### Advanced Configuration
 
@@ -141,7 +132,9 @@ test:
 
 ## File-Based Component Registry
 
-For information about the file-based component registry feature (including `components_subdirectory`, `auto_load_bundle`, and `make_generated_server_bundle_the_entrypoint` configuration options), see:
+If you have many components and want to avoid manually managing webpack entry points for each one, React on Rails can automatically generate component packs based on your file system structure. This feature is particularly useful for large applications with dozens of components.
+
+For complete information about the file-based component registry feature (including `components_subdirectory`, `auto_load_bundle`, and `make_generated_server_bundle_the_entrypoint` configuration options), see:
 
 [Auto-Bundling: File-System-Based Automated Bundle Generation](../core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md)
 
@@ -165,7 +158,7 @@ Controls how generated component pack scripts are loaded:
 
 **You typically don't need to set this** - React on Rails automatically selects the best strategy based on your Pro license status and Shakapacker version.
 
-To override the default:
+**When to override:** Only change this if you have specific performance requirements or constraints. For example, you might use `:defer` if you need to ensure all page content loads before scripts execute, or `:sync` for testing purposes.
 
 ```ruby
 config.generated_component_packs_loading_strategy = :defer
@@ -178,10 +171,13 @@ config.generated_component_packs_loading_strategy = :defer
 **Type:** String or nil
 **Default:** `"ssr-generated"`
 
-Directory (relative to Rails root) where server bundles are output. **You should not need to set this** - the default value is recommended for all applications.
+> ⚠️ **DO NOT change this setting unless you have a specific reason.** The default is correct for virtually all applications.
+
+Directory (relative to Rails root) where server bundles are output.
 
 ```ruby
-config.server_bundle_output_path = "ssr-generated"  # default (no need to set)
+# No need to set this - the default is recommended
+# config.server_bundle_output_path = "ssr-generated"
 ```
 
 - When set to a string: Server bundles output to this directory (e.g., `ssr-generated/`)
@@ -325,12 +321,14 @@ config.development_mode = Rails.env.development?  # default
 **Type:** Boolean
 **Default:** `true`
 
-When true, server-side console messages replay in the browser console:
+When true, server-side console messages replay in the browser console. This is valuable for debugging server-rendering issues.
 
 ```ruby
 config.replay_console = true  # default
 ```
 
+**When to disable:** You might set this to `false` in production if console logs contain sensitive data or to reduce client-side payload size.
+
 #### logging_on_server
 
 **Type:** Boolean
@@ -427,6 +425,8 @@ Set to `0` to wait indefinitely (not recommended for production).
 
 ### I18n Configuration
 
+These options are for applications using [react-intl](https://formatjs.io/docs/react-intl/) or similar internationalization libraries. If your application doesn't need i18n, you can skip this section.
+
 #### i18n_dir
 
 **Type:** String or nil

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

@@ -14,7 +14,8 @@ ReactOnRails.configure do |config|
 
   ################################################################################
   # Test Configuration
-  # Alternatively, set `compile: true` in config/shakapacker.yml for test env
+  # Used with ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
+  # Preferred alternative: set `compile: true` in config/shakapacker.yml for test env
   ################################################################################
   config.build_test_command = "RAILS_ENV=test bin/shakapacker"
 

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

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
-# Pro dummy app configuration for testing React on Rails Pro features
-# See docs/api-reference/configuration.md for complete documentation
+# ⚠️ 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

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

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-# ExecJS-compatible dummy app configuration
-# This app tests compatibility with legacy webpacker setup
-# See docs/api-reference/configuration.md for complete documentation
+# ⚠️ 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|
   ################################################################################

spec/dummy/config/initializers/react_on_rails.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-# Dummy app configuration for testing React on Rails
-# This demonstrates both essential and advanced configuration options for testing purposes
-# See docs/api-reference/configuration.md for complete documentation
+# ⚠️ 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