react_on_rails 16.2.0.beta.4 → 16.2.0.beta.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 559d44da8c51be70681ed059f69f1fb67856a41f86c95bdd35d2a2bbed79f0f8
-  data.tar.gz: 92cd87455b4e96407dcc6b06a5c2eb36a66a229305be63dbb55cd02d6774b638
+  metadata.gz: e2d569c0148019a12155710806cbd6f3d94f6641ffd074099dc9b4255b0202d6
+  data.tar.gz: 8abd5fedee13d2d2d1bfa6fc6a03e8a6d11710ece7fb84b26fb3afc387156d75
 SHA512:
-  metadata.gz: 6877a9fa47c913a103f146b8b6f0e35409618f7341f22fa0f362d73fe2bc2f3348a8d7593aa65dce56b245118a08892b8a2ea8c043ccb21bdc17955145a07189
-  data.tar.gz: 9c81ce27f0c3fee5aea1767613fe696377ea8a4bf61c68a86291ab171c662388cc931f9c7c47d41fa82ed3a27afa8cb953b4ce25ec0408a096c93a107bb5cde4
+  metadata.gz: 22ef214ab6d5c12257a9ebc3fbf01c56c4211405ac4398628b1d69813d236d39dfe02d48168d4fabb0a0eb5d54ce624fb37790776952e4300547e502170432a4
+  data.tar.gz: e1fdf86179a42c10af444265839d2e95fe15b3771f0606038ce1c01611efcd96c03d34c1e94682b718b6011c6f0d9c049b59b1713bdb75fa942a23e08e0c60b2

data/CHANGELOG.md

@@ -23,6 +23,18 @@ After a release, please make sure to run `bundle exec rake update_changelog`. Th
 
 Changes since the last non-beta release.
 
+#### Changed
+
+- **Generator Configuration Modernization**: Updated the generator to enable recommended configurations by default for new applications:
+
+  - `config.build_test_command` is now uncommented and set to `"RAILS_ENV=test bin/shakapacker"` by default, enabling automatic asset building during tests for better integration test reliability
+  - `config.auto_load_bundle = true` is now set by default, enabling automatic loading of component bundles
+  - `config.components_subdirectory = "ror_components"` is now set by default, organizing React components in a dedicated subdirectory
+
+  **Note:** These changes only affect newly generated applications. Existing applications are unaffected and do not need to make any changes. If you want to adopt these settings in an existing app, you can manually add them to your `config/initializers/react_on_rails.rb` file. [PR 2039](https://github.com/shakacode/react_on_rails/pull/2039) by [justin808](https://github.com/justin808).
+
+### [16.2.0.beta.4] - 2025-11-12
+
 #### Added
 
 - **Rspack Support**: Added `--rspack` flag to `react_on_rails:install` generator for significantly faster builds (~20x improvement with SWC). Includes unified webpack/rspack configuration templates and `bin/switch-bundler` utility to switch between bundlers post-installation. [PR #1852](https://github.com/shakacode/react_on_rails/pull/1852) by [justin808](https://github.com/justin808).
@@ -35,6 +47,8 @@ Changes since the last non-beta release.
 
 - **Improved RSC Payload Error Handling**: Errors that happen during generation of RSC payload are transferred properly to rails side and logs the error message and stack. [PR #1888](https://github.com/shakacode/react_on_rails/pull/1888) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
 
+- **Use as Git dependency**: All packages can now be installed as Git dependencies. This is useful for development and testing purposes. See [CONTRIBUTING.md](./CONTRIBUTING.md#git-dependencies) for documentation. [PR #1873](https://github.com/shakacode/react_on_rails/pull/1873) by [alexeyr-ci2](https://github.com/alexeyr-ci2).
+
 #### Changed
 
 - **Shakapacker 9.0.0 Upgrade**: Upgraded Shakapacker from 8.2.0 to 9.0.0 with Babel transpiler configuration for compatibility. Key changes include:
@@ -45,19 +59,23 @@ Changes since the last non-beta release.
   - Fixed webpack configuration to process SCSS rules and CSS loaders in a single pass for better performance
     [PR 1904](https://github.com/shakacode/react_on_rails/pull/1904) by [justin808](https://github.com/justin808).
 
-- **Shakapacker 9.1.0 Upgrade**: Upgraded Shakapacker from 9.0.0 to 9.1.0. This minor version update includes bug fixes and improvements. Updated webpack configuration in Pro dummy apps to use forEach pattern for better compatibility with multiple SCSS rules. [PR 1921](https://github.com/shakacode/react_on_rails/pull/1921) by [justin808](https://github.com/justin808).
+- **`immediate_hydration` now automatically enabled for Pro users**: The `config.immediate_hydration` configuration option has been removed. Immediate hydration is now automatically enabled for React on Rails Pro users and disabled for non-Pro users, simplifying configuration while providing optimal performance by default. Component-level overrides are still supported via the `immediate_hydration` parameter on `react_component`, `redux_store`, and `stream_react_component` helpers. [PR 1997](https://github.com/shakacode/react_on_rails/pull/1997) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
+
+- **`generated_component_packs_loading_strategy` now defaults based on Pro license**: When using Shakapacker >= 8.2.0, the default loading strategy is now `:async` for Pro users and `:defer` for non-Pro users. This provides optimal performance for Pro users while maintaining compatibility for non-Pro users. You can still explicitly set the strategy in your configuration. [PR #1993](https://github.com/shakacode/react_on_rails/pull/1993) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
 
-- **Shakapacker 9.2.0 Upgrade**: Upgraded Shakapacker from 9.1.0 to 9.2.0. This minor version update adds a new `bin/shakapacker-config` utility for debugging webpack/rspack configurations with doctor mode, save mode, and stdout mode options. Supports YAML, JSON, and Node.js inspect output formats. by [justin808](https://github.com/justin808).
+#### Documentation
 
-- **Removed Pro Warning Badge**: Removed the visual warning badge that appeared when non-Pro users attempted to enable Pro-only features like `immediate_hydration`. Pro features are now silently disabled when a Pro license is not available, providing a cleaner user experience without intrusive warning banners. [PR #1993](https://github.com/shakacode/react_on_rails/pull/1993) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
+- **Simplified Configuration Files**: Improved configuration documentation and generator template for better clarity and usability. Reduced generator template from 67 to 42 lines (37% reduction). Added comprehensive testing configuration guide. Reorganized configuration docs into Essential vs Advanced sections. Enhanced Doctor program with diagnostics for server rendering and test compilation consistency. [PR #2011](https://github.com/shakacode/react_on_rails/pull/2011) by [justin808](https://github.com/justin808).
 
-- **`immediate_hydration` now automatically enabled for Pro users**: The `config.immediate_hydration` configuration option has been removed. Immediate hydration is now automatically enabled for React on Rails Pro users and disabled for non-Pro users, simplifying configuration while providing optimal performance by default. Component-level overrides are still supported via the `immediate_hydration` parameter on `react_component`, `redux_store`, and `stream_react_component` helpers. [PR 1997](https://github.com/shakacode/react_on_rails/pull/1997) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
+#### Deprecated
 
-- **`generated_component_packs_loading_strategy` now defaults based on Pro license**: When using Shakapacker >= 8.2.0, the default loading strategy is now `:async` for Pro users and `:defer` for non-Pro users. This provides optimal performance for Pro users while maintaining compatibility for non-Pro users. You can still explicitly set the strategy in your configuration. [PR #1993](https://github.com/shakacode/react_on_rails/pull/1993) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
+- **Node Renderer Configuration**: Renamed `bundlePath` configuration option to `serverBundleCachePath` in the node renderer to better describe its purpose and avoid confusion with Shakapacker's public bundle path. The old `bundlePath` option continues to work with deprecation warnings. Both `RENDERER_SERVER_BUNDLE_CACHE_PATH` (new) and `RENDERER_BUNDLE_PATH` (deprecated) environment variables are supported. [PR #2008](https://github.com/shakacode/react_on_rails/pull/2008) by [justin808](https://github.com/justin808).
 
-#### Bug Fixes
+#### Fixed
 
-- **Use as Git dependency**: All packages can now be installed as Git dependencies. This is useful for development and testing purposes. See [CONTRIBUTING.md](./CONTRIBUTING.md#git-dependencies) for documentation. [PR #1873](https://github.com/shakacode/react_on_rails/pull/1873) by [alexeyr-ci2](https://github.com/alexeyr-ci2).
+- **Node Renderer Worker Restart**: Fixed "descriptor closed" error that occurred when the node renderer restarts while handling an in-progress request (especially streaming requests). Workers now perform graceful shutdowns: they disconnect from the cluster to stop receiving new requests, wait for active requests to complete, then shut down cleanly. A configurable `gracefulWorkerRestartTimeout` ensures workers are forcibly killed if they don't shut down in time. [PR 1970](https://github.com/shakacode/react_on_rails/pull/1970) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
+
+- **Body Duplication Bug On Streaming**: Fixed a bug that happens while streaming if the node renderer connection closed after streaming some chunks to the client. [PR #1995](https://github.com/shakacode/react_on_rails/pull/1995) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
 
 #### Breaking Changes
 
@@ -1819,7 +1837,8 @@ such as:
 
 - Fix several generator-related issues.
 
-[unreleased]: https://github.com/shakacode/react_on_rails/compare/16.1.1...master
+[unreleased]: https://github.com/shakacode/react_on_rails/compare/16.2.0.beta.4...master
+[16.2.0.beta.4]: https://github.com/shakacode/react_on_rails/compare/16.1.1...16.2.0.beta.4
 [16.1.1]: https://github.com/shakacode/react_on_rails/compare/16.1.0...16.1.1
 [16.1.0]: https://github.com/shakacode/react_on_rails/compare/16.0.0...16.1.0
 [16.0.0]: https://github.com/shakacode/react_on_rails/compare/14.2.0...16.0.0

data/CONTRIBUTING.md

@@ -129,7 +129,7 @@ Package react-on-rails@12.0.0-12070fd1 added ==> /Users/justin/shakacode/react-o
 Don't forget you may need to run yarn after adding packages with yalc to install/update dependencies/bin scripts.
 ```
 
-Of course, you can do the same with `react-on-rails-pro` and `@shakacode-tools/react-on-rails-pro-node-renderer` packages.
+Of course, you can do the same with `react-on-rails-pro` and `react-on-rails-pro-node-renderer` packages.
 
 This is the approach `spec/dummy` apps use, so you can also look at their implementation.
 

data/Gemfile.development_dependencies

@@ -38,7 +38,6 @@ group :development, :test do
   gem "rubocop", "1.61.0", require: false
   gem "rubocop-performance", "~>1.20.0", require: false
   gem "rubocop-rspec", "~>2.26", require: false
-  gem "scss_lint", require: false
   gem "spring", "~> 4.0"
   gem "lefthook", require: false
   # Added for Ruby 3.5+ compatibility to silence warnings

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    react_on_rails (16.2.0.beta.4)
+    react_on_rails (16.2.0.beta.8)
       addressable
       connection_pool
       execjs (~> 2.5)
@@ -332,11 +332,6 @@ GEM
       rubocop (~> 1.40)
     ruby-progressbar (1.13.0)
     rubyzip (2.3.2)
-    sass (3.7.4)
-      sass-listen (~> 4.0.0)
-    sass-listen (4.0.0)
-      rb-fsevent (~> 0.9, >= 0.9.4)
-      rb-inotify (~> 0.9, >= 0.9.7)
     sass-rails (6.0.0)
       sassc-rails (~> 2.1, >= 2.1.1)
     sassc (2.4.0)
@@ -347,8 +342,6 @@ GEM
       sprockets (> 3.0)
       sprockets-rails
       tilt
-    scss_lint (0.60.0)
-      sass (~> 3.5, >= 3.5.5)
     sdoc (2.6.1)
       rdoc (>= 5.0)
     securerandom (0.4.1)
@@ -473,7 +466,6 @@ DEPENDENCIES
   rubocop-performance (~> 1.20.0)
   rubocop-rspec (~> 2.26)
   sass-rails (~> 6.0)
-  scss_lint
   sdoc
   selenium-webdriver (= 4.9.0)
   shakapacker (= 9.3.0)

data/bin/ci-rerun-failures

@@ -173,15 +173,41 @@ if [ -z "$FAILED_CHECKS" ]; then
   exit 0
 fi
 
-# Map CI job names to local commands
+# Map CI job names to identifiers
 # NOTE: Version numbers below must match .github/workflows/main.yml matrix configuration
 declare -A JOB_MAP
-JOB_MAP["lint-js-and-ruby"]="bundle exec rubocop && yarn run eslint --report-unused-disable-directives && yarn start format.listDifferent"
-JOB_MAP["rspec-package-tests"]="bundle exec rake run_rspec:gem"
-JOB_MAP["package-js-tests"]="yarn test"
-JOB_MAP["dummy-app-integration-tests (3.4, 22, latest)"]="bundle exec rake run_rspec:all_dummy"
-JOB_MAP["dummy-app-integration-tests (3.2, 20, minimum)"]="bundle exec rake run_rspec:all_dummy"
-JOB_MAP["examples"]="bundle exec rake run_rspec:shakapacker_examples"
+JOB_MAP["lint-js-and-ruby"]="lint-js-and-ruby"
+JOB_MAP["rspec-package-tests"]="rspec-package-tests"
+JOB_MAP["package-js-tests"]="package-js-tests"
+JOB_MAP["dummy-app-integration-tests (3.4, 22, latest)"]="dummy-app-integration-tests"
+JOB_MAP["dummy-app-integration-tests (3.2, 20, minimum)"]="dummy-app-integration-tests"
+JOB_MAP["examples"]="examples"
+
+# Function to execute commands without eval
+run_command() {
+  local cmd_id="$1"
+  case "$cmd_id" in
+    "lint-js-and-ruby")
+      bundle exec rubocop && yarn run eslint --report-unused-disable-directives && yarn start format.listDifferent
+      ;;
+    "rspec-package-tests")
+      bundle exec rake run_rspec:gem
+      ;;
+    "package-js-tests")
+      yarn test
+      ;;
+    "dummy-app-integration-tests")
+      bundle exec rake run_rspec:all_dummy
+      ;;
+    "examples")
+      bundle exec rake run_rspec:shakapacker_examples
+      ;;
+    *)
+      echo "Unknown command ID: $cmd_id"
+      return 1
+      ;;
+  esac
+}
 
 # Map CI job names to human-readable versions (matches SWITCHING_CI_CONFIGS.md)
 declare -A JOB_VERSION_MAP
@@ -236,10 +262,10 @@ if [ "$NUM_COMMANDS" -eq 0 ]; then
 fi
 
 echo -e "${BLUE}Will run the following commands:${NC}"
-for cmd in "${!COMMANDS_TO_RUN[@]}"; do
-  job_name="${COMMANDS_TO_RUN[$cmd]}"
+for cmd_id in "${!COMMANDS_TO_RUN[@]}"; do
+  job_name="${COMMANDS_TO_RUN[$cmd_id]}"
   version_info=$(get_version_info "$job_name")
-  echo -e "${BLUE}  • $job_name${version_info}:${NC} $cmd"
+  echo -e "${BLUE}  • $job_name${version_info}${NC}"
 done
 echo ""
 
@@ -270,17 +296,14 @@ fi
 # Run commands
 FAILED_COMMANDS=()
 
-for cmd in "${!COMMANDS_TO_RUN[@]}"; do
-  job_name="${COMMANDS_TO_RUN[$cmd]}"
+for cmd_id in "${!COMMANDS_TO_RUN[@]}"; do
+  job_name="${COMMANDS_TO_RUN[$cmd_id]}"
   version_info=$(get_version_info "$job_name")
 
   echo -e "${BLUE}▶ Running: $job_name${version_info}${NC}"
-  echo -e "${BLUE}Command: $cmd${NC}"
   echo ""
 
-  # Note: Using eval here is safe because $cmd comes from predefined JOB_MAP,
-  # not from user input. Commands may contain shell operators like && and ||.
-  if eval "$cmd"; then
+  if run_command "$cmd_id"; then
     echo -e "${GREEN}✓ $job_name${version_info} passed${NC}"
     echo ""
   else

data/bin/ci-run-failed-specs

@@ -139,7 +139,7 @@ echo ""
 
 # Determine the working directory (check if we need to be in spec/dummy)
 WORKING_DIR="."
-if [[ "${UNIQUE_SPECS[0]}" == *"spec/system"* ]] || [[ "${UNIQUE_SPECS[0]}" == *"spec/helpers"* ]]; then
+if [ ${#UNIQUE_SPECS[@]} -gt 0 ] && ([[ "${UNIQUE_SPECS[0]}" == *"spec/system"* ]] || [[ "${UNIQUE_SPECS[0]}" == *"spec/helpers"* ]]); then
   if [ -d "spec/dummy" ]; then
     WORKING_DIR="spec/dummy"
     echo -e "${BLUE}Running from spec/dummy directory${NC}"

data/bin/ci-switch-config

@@ -255,6 +255,9 @@ EOF
   set_node_version "20.18.1" "$VERSION_MANAGER"
 
   # Run conversion script
+  # NOTE: This uses whatever 'ruby' is in PATH after version manager updates above.
+  # The version manager may not have reloaded yet, so ensure your current Ruby is
+  # compatible with script/convert (Ruby 2.6+ should work).
   print_header "Running script/convert to downgrade dependencies"
   cd "$PROJECT_ROOT"
   ruby script/convert
@@ -395,8 +398,11 @@ EOF
   # Restore files from git
   print_header "Restoring dependency files from git"
   cd "$PROJECT_ROOT"
-  git restore Gemfile.development_dependencies package.json spec/dummy/package.json packages/react-on-rails-pro/package.json 2>/dev/null || true
-  print_success "Files restored from git"
+  if ! git restore Gemfile.development_dependencies package.json spec/dummy/package.json packages/react-on-rails-pro/package.json 2>/dev/null; then
+    print_warning "Some files could not be restored (may not exist in git)"
+  else
+    print_success "Files restored from git"
+  fi
 
   # Clean and reinstall
   print_header "Cleaning node_modules and reinstalling"

data/bin/lefthook/ruby-autofix

@@ -17,6 +17,7 @@ else
 fi
 printf "  %s\n" $files
 
-bundle exec rake autofix
+# Run RuboCop only on changed files (not the full rake autofix)
+bundle exec rubocop -A --force-exclusion -- $files
 
 echo "✅ Auto-fix complete (fixed files staged automatically)"

data/knip.ts

@@ -5,13 +5,11 @@ const config: KnipConfig = {
   workspaces: {
     // Root workspace - manages the monorepo and global tooling
     '.': {
-      entry: ['eslint.config.ts'],
+      entry: ['eslint.config.ts', 'jest.config.base.js'],
       project: ['*.{js,mjs,ts}'],
       ignoreBinaries: [
         // Has to be installed globally
         'yalc',
-        // Used in package.json scripts (devDependency, so unlisted in production mode)
-        'nps',
         // Pro package binaries used in Pro workflows
         'playwright',
         'e2e-test',
@@ -41,6 +39,17 @@ const config: KnipConfig = {
         // SWC transpiler dependencies used in dummy apps
         '@swc/core',
         'swc-loader',
+        // Test dependencies used by child workspaces (packages/react-on-rails, packages/react-on-rails-pro)
+        '@testing-library/dom',
+        '@testing-library/jest-dom',
+        '@testing-library/react',
+        '@types/react-dom',
+        'create-react-class',
+        'jest-fetch-mock',
+        'prop-types',
+        'react',
+        'react-dom',
+        'redux',
       ],
     },
 
@@ -89,6 +98,11 @@ const config: KnipConfig = {
         'src/RSCRoute.tsx:RSCRouteProps',
         'src/streamServerRenderedReactComponent.ts:StreamingTrackers',
       ],
+      ignoreDependencies: [
+        // Test dependencies used only in tests
+        '@types/mock-fs',
+        'mock-fs',
+      ],
     },
     'spec/dummy': {
       entry: [
@@ -112,6 +126,12 @@ const config: KnipConfig = {
         '**/app-react16/**/*',
         // Playwright support files and helpers - generated by cypress-on-rails gem
         'e2e/playwright/support/**',
+        // Components and files used dynamically by React on Rails (registered at runtime)
+        'client/app/actions/**',
+        'client/app/components/**',
+        'client/app/routes/**',
+        'client/app/startup/**',
+        'client/app/store/**',
       ],
       project: ['**/*.{js,cjs,mjs,jsx,ts,cts,mts,tsx}!', 'config/webpack/*.js'],
       paths: {
@@ -124,9 +144,6 @@ const config: KnipConfig = {
         'bin/.*',
       ],
       ignoreDependencies: [
-        // Build-time dependencies not detected by Knip in any mode
-        '@babel/runtime',
-        'mini-css-extract-plugin',
         // There's no ReScript plugin for Knip
         '@rescript/react',
         // The Babel plugin fails to detect it
@@ -136,18 +153,27 @@ const config: KnipConfig = {
         'node-libs-browser',
         // The below dependencies are not detected by the Webpack plugin
         // due to the config issue.
-        'css-loader',
         'expose-loader',
         'file-loader',
         'imports-loader',
         'null-loader',
-        'sass',
-        'sass-loader',
         'sass-resources-loader',
         'style-loader',
         'url-loader',
         // Transitive dependency of shakapacker but listed as direct dependency
         'webpack-merge',
+        // Dependencies not detected in production mode
+        '@babel/runtime',
+        'mini-css-extract-plugin',
+        'css-loader',
+        'sass',
+        'sass-loader',
+        // Dependencies used dynamically by React on Rails
+        'create-react-class',
+        'react-helmet',
+        '@types/react-helmet',
+        'react-redux',
+        'react-router-dom',
       ],
     },
   },

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

@@ -1,67 +1,47 @@
 # 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 (Optional)
   ################################################################################
-  # 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.
+  # ⚠️ IMPORTANT: Two mutually exclusive approaches - use ONLY ONE:
   #
-  # 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.
+  # RECOMMENDED APPROACH: Set `compile: true` in config/shakapacker.yml test section
+  # - Simpler configuration (no additional setup needed)
+  # - Handled automatically by Shakapacker
   #
-  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
+  # ALTERNATIVE APPROACH: Uncomment below AND configure ReactOnRails::TestHelper
+  # - Provides explicit control over test asset compilation timing
+  # - Requires adding ReactOnRails::TestHelper to spec/rails_helper.rb
+  # - See: https://github.com/shakacode/react_on_rails/blob/master/docs/guides/testing-configuration.md
+  #
+  config.build_test_command = "RAILS_ENV=test bin/shakapacker"
 
-  ################################################################################
-  ################################################################################
-  # 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.auto_load_bundle = true
   config.components_subdirectory = "ror_components"
+  ################################################################################
+  # Advanced Configuration
+  ################################################################################
+  # 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

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

@@ -55,6 +55,11 @@ default: &default
   # https://webpack.js.org/guides/build-performance/#avoid-production-specific-tooling
   useContentHash: false
 
+  # On-demand compilation of packs when modified. Defaults to false.
+  # Set to false if using bin/shakapacker-dev-server or bin/shakapacker --watch via Procfiles.
+  # Set to true only in test environment for on-demand compilation.
+  compile: false
+
   # Setting the asset host here will override Rails.application.config.asset_host.
   # Here, you can set different asset_host per environment. Note that
   # SHAKAPACKER_ASSET_HOST will override both configurations.
@@ -72,7 +77,6 @@ default: &default
 
 development:
   <<: *default
-  compile: true
   compiler_strategy: mtime
 
   # Reference: https://webpack.js.org/configuration/dev-server/

data/lib/react_on_rails/dev/server_manager.rb

@@ -144,10 +144,11 @@ module ReactOnRails
           puts help_troubleshooting
         end
 
+        # rubocop:disable Metrics/AbcSize
         def run_from_command_line(args = ARGV)
           require "optparse"
 
-          options = { route: nil, rails_env: nil }
+          options = { route: nil, rails_env: nil, verbose: false }
 
           OptionParser.new do |opts|
             opts.banner = "Usage: dev [command] [options]"
@@ -160,6 +161,10 @@ module ReactOnRails
               options[:rails_env] = env
             end
 
+            opts.on("-v", "--verbose", "Enable verbose output for pack generation") do
+              options[:verbose] = true
+            end
+
             opts.on("-h", "--help", "Prints this help") do
               show_help
               exit
@@ -172,21 +177,23 @@ module ReactOnRails
           # Main execution
           case command
           when "production-assets", "prod"
-            start(:production_like, nil, verbose: false, route: options[:route], rails_env: options[:rails_env])
+            start(:production_like, nil, verbose: options[:verbose], route: options[:route],
+                                         rails_env: options[:rails_env])
           when "static"
-            start(:static, "Procfile.dev-static-assets", verbose: false, route: options[:route])
+            start(:static, "Procfile.dev-static-assets", verbose: options[:verbose], route: options[:route])
           when "kill"
             kill_processes
           when "help", "--help", "-h"
             show_help
           when "hmr", nil
-            start(:development, "Procfile.dev", verbose: false, route: options[:route])
+            start(:development, "Procfile.dev", verbose: options[:verbose], route: options[:route])
           else
             puts "Unknown argument: #{command}"
             puts "Run 'dev help' for usage information"
             exit 1
           end
         end
+        # rubocop:enable Metrics/AbcSize
 
         private