react_on_rails 16.2.0.beta.8 → 16.2.0.beta.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2d569c0148019a12155710806cbd6f3d94f6641ffd074099dc9b4255b0202d6
-  data.tar.gz: 8abd5fedee13d2d2d1bfa6fc6a03e8a6d11710ece7fb84b26fb3afc387156d75
+  metadata.gz: 94e2c46e66774ffdeb5902068d74c22daf9b2eafd08b45f1d353be5de6df24b1
+  data.tar.gz: 49e2fc58fbc4e1df4d5a0573940b5bbe2c346c7bf226f6535e80b8e1fd82e216
 SHA512:
-  metadata.gz: 22ef214ab6d5c12257a9ebc3fbf01c56c4211405ac4398628b1d69813d236d39dfe02d48168d4fabb0a0eb5d54ce624fb37790776952e4300547e502170432a4
-  data.tar.gz: e1fdf86179a42c10af444265839d2e95fe15b3771f0606038ce1c01611efcd96c03d34c1e94682b718b6011c6f0d9c049b59b1713bdb75fa942a23e08e0c60b2
+  metadata.gz: ca050de67f3ae49a02674b0130b1b2532d090605565cff6055fa51f779741109d2415a4069ceb470a819fdcb988fab51795b278eff644c122599c484a1e6aada
+  data.tar.gz: 99e95152c8015ae37ca106f70ac64bb1b64e52c006b0fd0836f84a091bf00db014d2f09c81199b19624ddc8f6db68ea75c4d74ace02445a7d25cf7db3d79f529

data/CHANGELOG.md

@@ -23,17 +23,7 @@ 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
+### [v16.2.0.beta.10] - 2025-11-18
 
 #### Added
 
@@ -49,6 +39,8 @@ Changes since the last non-beta release.
 
 - **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).
 
+- **Doctor Checks for :async Loading Strategy**: Added proactive diagnostic checks to the React on Rails doctor tool to detect usage of the `:async` loading strategy in projects without React on Rails Pro. The feature scans view files and initializer configuration, providing clear guidance to either upgrade to Pro or use alternative loading strategies like `:defer` or `:sync` to avoid component registration race conditions. [PR 2010](https://github.com/shakacode/react_on_rails/pull/2010) by [justin808](https://github.com/justin808).
+
 #### 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:
@@ -63,6 +55,10 @@ Changes since the last non-beta release.
 
 - **`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).
 
+- **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).
+
+- **Removed Babel Dependency Installation**: The generator no longer installs `@babel/preset-react` or `@babel/preset-typescript` packages. Shakapacker handles JavaScript transpiler configuration (Babel, SWC, or esbuild) via the `javascript_transpiler` setting in `shakapacker.yml`. SWC is now the default transpiler and includes built-in support for React and TypeScript. Users who explicitly choose Babel will need to manually install and configure the required presets. This change reduces unnecessary dependencies and aligns with Shakapacker's modular transpiler approach. [PR 2051](https://github.com/shakacode/react_on_rails/pull/2051) by [justin808](https://github.com/justin808).
+
 #### Documentation
 
 - **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).
@@ -73,10 +69,20 @@ Changes since the last non-beta release.
 
 #### Fixed
 
+- **Duplicate Rake Task Execution**: Fixed rake tasks executing twice during asset precompilation and other rake operations. Rails Engine was loading task files twice: once via explicit `load` calls in the `rake_tasks` block (Railtie layer) and once via automatic file loading from `lib/tasks/` (Engine layer). This caused `react_on_rails:assets:webpack`, `react_on_rails:generate_packs`, and `react_on_rails:locale` tasks to run twice, significantly increasing build times. Removed explicit `load` calls and now rely on Rails Engine's standard auto-loading behavior. [PR 2052](https://github.com/shakacode/react_on_rails/pull/2052) by [justin808](https://github.com/justin808).
+
 - **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).
 
+- **bin/dev --verbose Option**: Fixed `OptionParser::InvalidOption` error that occurred when using the `--verbose`/`-v` flag. The flag was documented in help text but not functional. Now properly implemented with flag parsing and passing verbose option through method calls. [PR 2023](https://github.com/shakacode/react_on_rails/pull/2023) by [justin808](https://github.com/justin808).
+
+- **Shakapacker Template Configuration**: Fixed shakapacker.yml template to prevent unnecessary "Slow setup for development" warnings by setting `compile: false` as the default configuration. This allows development environments to inherit the setting instead of forcing on-demand compilation when using Procfiles with `bin/dev` that already run the shakapacker dev server or watch mode. [PR 2021](https://github.com/shakacode/react_on_rails/pull/2021) by [justin808](https://github.com/justin808).
+
+#### Improved
+
+- **Concurrent Streaming Performance**: Implemented concurrent draining of streamed React components using the async gem. Instead of processing components sequentially, the system now uses a producer-consumer pattern with bounded buffering to allow multiple components to stream simultaneously while maintaining per-component chunk ordering. [PR 2015](https://github.com/shakacode/react_on_rails/pull/2015) by [ihabadham](https://github.com/ihabadham).
+
 #### Breaking Changes
 
 - **`config.immediate_hydration` configuration removed**: The `config.immediate_hydration` setting in `config/initializers/react_on_rails.rb` has been removed. Immediate hydration is now automatically enabled for React on Rails Pro users and automatically disabled for non-Pro users.
@@ -1837,8 +1843,8 @@ such as:
 
 - Fix several generator-related issues.
 
-[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
+[unreleased]: https://github.com/shakacode/react_on_rails/compare/v16.2.0.beta.10...master
+[v16.2.0.beta.10]: https://github.com/shakacode/react_on_rails/compare/16.1.1...v16.2.0.beta.10
 [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/CLAUDE.md

@@ -2,6 +2,22 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Project Structure Guidelines
+
+### Analysis Documents
+
+When creating analysis documents (deep dives, investigations, historical context):
+- **Location**: Place in `/analysis` directory
+- **Format**: Use Markdown (.md)
+- **Naming**: Use descriptive kebab-case names (e.g., `rake-task-duplicate-analysis.md`)
+- **Purpose**: Keep detailed analyses separate from top-level project files
+
+Examples:
+- `/analysis/rake-task-duplicate-analysis.md` - Historical analysis of duplicate rake task bug
+- `/analysis/feature-investigation.md` - Investigation of a specific feature or issue
+
+Top-level documentation (like README.md, CONTRIBUTING.md) should remain at the root.
+
 ## ⚠️ CRITICAL REQUIREMENTS
 
 **BEFORE EVERY COMMIT/PUSH:**
@@ -178,11 +194,24 @@ cd react_on_rails_pro && bundle exec rake rbs:validate
 ```
 ## Changelog
 
+**IMPORTANT: This is a monorepo with TWO separate changelogs:**
+- **Open Source**: `/CHANGELOG.md` - for react_on_rails gem and npm package
+- **Pro**: `/react_on_rails_pro/CHANGELOG.md` - for react_on_rails_pro gem and npm packages
+
+When making changes, update the **appropriate changelog(s)**:
+- Open-source features/fixes → Update `/CHANGELOG.md`
+- Pro-only features/fixes → Update `/react_on_rails_pro/CHANGELOG.md`
+- Changes affecting both → Update **BOTH** changelogs
+
+### Changelog Guidelines
+
 - **Update CHANGELOG.md for user-visible changes only** (features, bug fixes, breaking changes, deprecations, performance improvements)
 - **Do NOT add entries for**: linting, formatting, refactoring, tests, or documentation fixes
 - **Format**: `[PR 1818](https://github.com/shakacode/react_on_rails/pull/1818) by [username](https://github.com/username)` (no hash in PR number)
 - **Use `/update-changelog` command** for guided changelog updates with automatic formatting
-- **Version management**: Run `bundle exec rake update_changelog` after releases to update version headers
+- **Version management after releases**:
+  - Open source: `bundle exec rake update_changelog`
+  - Pro: `cd react_on_rails_pro && bundle exec rake update_changelog`
 - **Examples**: Run `grep -A 3 "^#### " CHANGELOG.md | head -30` to see real formatting examples
 
 ## ⚠️ FORMATTING RULES
@@ -198,12 +227,25 @@ cd react_on_rails_pro && bundle exec rake rbs:validate
 **CRITICAL**: When resolving merge conflicts, follow this exact sequence:
 
 1. **Resolve logical conflicts only** - don't worry about formatting
-2. **Add resolved files**: `git add .` (or specific files)
-3. **Auto-fix everything**: `rake autofix`
-4. **Add any formatting changes**: `git add .`
-5. **Continue rebase/merge**: `git rebase --continue` or `git commit`
+2. **VERIFY FILE PATHS** - if the conflict involved directory structure:
+   - Check if any hardcoded paths need updating
+   - Run: `grep -r "old/path" . --exclude-dir=node_modules`
+   - Pay special attention to package-scripts.yml, webpack configs, package.json
+   - **Test affected scripts:** If package-scripts.yml changed, run `yarn run prepack`
+3. **Add resolved files**: `git add .` (or specific files)
+4. **Auto-fix everything**: `rake autofix`
+5. **Add any formatting changes**: `git add .`
+6. **Continue rebase/merge**: `git rebase --continue` or `git commit`
+7. **TEST CRITICAL SCRIPTS if build configs changed:**
+   ```bash
+   yarn run prepack          # Test prepack script
+   yarn run yalc.publish     # Test yalc publish if package structure changed
+   rake run_rspec:gem        # Run relevant test suites
+   ```
 
 **❌ NEVER manually format during conflict resolution** - this causes formatting wars between tools.
+**❌ NEVER blindly accept path changes** - verify they're correct for current structure.
+**❌ NEVER skip testing after resolving conflicts in build configs** - silent failures are dangerous.
 
 ### Debugging Formatting Issues
 - Check current formatting: `yarn start format.listDifferent`
@@ -223,6 +265,18 @@ cd react_on_rails_pro && bundle exec rake rbs:validate
 - **Gem-only tests**: `rake run_rspec:gem`
 - **All tests except examples**: `rake all_but_examples`
 
+## Testing Build and Package Scripts
+
+@.claude/docs/testing-build-scripts.md
+
+## Master Branch Health Monitoring
+
+@.claude/docs/master-health-monitoring.md
+
+## Managing File Paths in Configuration Files
+
+@.claude/docs/managing-file-paths.md
+
 ## Project Architecture
 
 ### Monorepo Structure
@@ -504,6 +558,83 @@ Playwright E2E tests run automatically in CI via GitHub Actions (`.github/workfl
 - Uploads HTML reports as artifacts (available for 30 days)
 - Auto-starts Rails server before running tests
 
+## Rails Engine Development Nuances
+
+React on Rails is a **Rails Engine**, which has important implications for development:
+
+### Automatic Rake Task Loading
+
+**CRITICAL**: Rails::Engine automatically loads all `.rake` files from `lib/tasks/` directory. **DO NOT** use a `rake_tasks` block to explicitly load them, as this causes duplicate task execution.
+
+```ruby
+# ❌ WRONG - Causes duplicate execution
+module ReactOnRails
+  class Engine < ::Rails::Engine
+    rake_tasks do
+      load File.expand_path("../tasks/generate_packs.rake", __dir__)
+      load File.expand_path("../tasks/assets.rake", __dir__)
+      load File.expand_path("../tasks/locale.rake", __dir__)
+    end
+  end
+end
+
+# ✅ CORRECT - Rails::Engine loads lib/tasks/*.rake automatically
+module ReactOnRails
+  class Engine < ::Rails::Engine
+    # Rake tasks are automatically loaded from lib/tasks/*.rake by Rails::Engine
+    # No explicit loading needed
+  end
+end
+```
+
+**When to use `rake_tasks` block:**
+- Tasks are in a **non-standard location** (not `lib/tasks/`)
+- You need to **programmatically generate** tasks
+- You need to **pass context** to the tasks
+
+**Historical Context**: PR #1770 added explicit rake task loading, causing webpack builds and pack generation to run twice during `rake assets:precompile`. This was fixed in PR #2052. See `analysis/rake-task-duplicate-analysis.md` for full details.
+
+### Engine Initializers and Hooks
+
+Engines have specific initialization hooks that run at different times:
+
+```ruby
+module ReactOnRails
+  class Engine < ::Rails::Engine
+    # Runs after Rails initializes but before routes are loaded
+    config.to_prepare do
+      ReactOnRails::ServerRenderingPool.reset_pool
+    end
+
+    # Runs during Rails initialization, use for validations
+    initializer "react_on_rails.validate_version" do
+      config.after_initialize do
+        # Validation logic here
+      end
+    end
+  end
+end
+```
+
+### Engine vs Application Code
+
+- **Engine code** (`lib/react_on_rails/`): Runs in the gem context, has limited access to host application
+- **Host application code**: The Rails app that includes the gem
+- **Generators** (`lib/generators/react_on_rails/`): Run in host app context during setup
+
+### Testing Engines
+
+- **Dummy app** (`spec/dummy/`): Full Rails app for integration testing
+- **Unit tests** (`spec/react_on_rails/`): Test gem code in isolation
+- Always test both contexts: gem code alone and gem + host app integration
+
+### Common Pitfalls
+
+1. **Assuming host app structure**: Don't assume `app/javascript/` exists—it might not in older apps
+2. **Path resolution**: Use `Rails.root` for host app paths, not relative paths
+3. **Autoloading**: Engine code follows Rails autoloading rules but with a different load path
+4. **Configuration**: Engine config is separate from host app config—use `ReactOnRails.configure`
+
 ## IDE Configuration
 
 Exclude these directories to prevent IDE slowdowns:

data/CONTRIBUTING.md

@@ -426,12 +426,14 @@ For more details, see [`docs/CI_OPTIMIZATION.md`](./docs/CI_OPTIMIZATION.md).
 
 React on Rails provides PR comment commands to control CI behavior:
 
-#### `/run-skipped-ci` - Enable Full CI Mode
+#### `/run-skipped-ci` (or `/run-skipped-tests`) - Enable Full CI Mode
 
 Runs all skipped CI checks and enables full CI mode for the PR:
 
 ```
 /run-skipped-ci
+# or use the shorter alias:
+/run-skipped-tests
 ```
 
 **What it does:**

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    react_on_rails (16.2.0.beta.8)
+    react_on_rails (16.2.0.beta.11)
       addressable
       connection_pool
       execjs (~> 2.5)

data/Steepfile

@@ -28,6 +28,10 @@ target :lib do
   check "lib/react_on_rails.rb"
   check "lib/react_on_rails/configuration.rb"
   check "lib/react_on_rails/controller.rb"
+  check "lib/react_on_rails/dev/file_manager.rb"
+  check "lib/react_on_rails/dev/pack_generator.rb"
+  check "lib/react_on_rails/dev/process_manager.rb"
+  check "lib/react_on_rails/dev/server_manager.rb"
   check "lib/react_on_rails/git_utils.rb"
   check "lib/react_on_rails/helper.rb"
   check "lib/react_on_rails/packer_utils.rb"

data/analysis/rake-task-duplicate-analysis.md

@@ -0,0 +1,149 @@
+# Analysis: Why rake_tasks Block Was Added in PR #1770 and Caused Duplicate Execution
+
+## Summary
+
+In PR #1770 (commit `8f3d178` - "Generator Overhaul & Developer Experience Enhancement"), Ihab added a `rake_tasks` block to `lib/react_on_rails/engine.rb` that explicitly loaded three rake task files. This was part of a **massive generator overhaul** that introduced new rake tasks for the file-system auto-registration feature. However, this caused those tasks to execute **twice** during operations like `rake assets:precompile`, which was fixed in PR #2052.
+
+## The Problem: Double Loading of Rake Tasks
+
+### What Was Added in PR #1770 (8f3d178)
+
+```ruby
+# lib/react_on_rails/engine.rb
+module ReactOnRails
+  class Engine < ::Rails::Engine
+    # ... existing code ...
+
+    rake_tasks do
+      load File.expand_path("../tasks/generate_packs.rake", __dir__)
+      load File.expand_path("../tasks/assets.rake", __dir__)
+      load File.expand_path("../tasks/locale.rake", __dir__)
+    end
+  end
+end
+```
+
+### Why This Caused Duplicate Execution
+
+Rails Engines have **two different mechanisms** for loading rake tasks, and this code inadvertently activated both:
+
+1. **Automatic Loading (Engine Layer)**: Rails::Engine automatically loads all `.rake` files from `lib/tasks/` directory
+2. **Manual Loading (Railtie Layer)**: The `rake_tasks` block explicitly loads specific files
+
+Because the task files existed in `lib/tasks/`:
+
+- `lib/tasks/assets.rake`
+- `lib/tasks/generate_packs.rake`
+- `lib/tasks/locale.rake`
+
+They were being loaded **twice**:
+
+- Once automatically by Rails::Engine from the `lib/tasks/` directory
+- Once explicitly by the `rake_tasks` block
+
+## Why Was This Added in PR #1770?
+
+PR #1770 was a **major overhaul** with 97 files changed. Looking at the context:
+
+### The Generator Overhaul Introduced:
+
+1. **File-system auto-registration**: New feature where components auto-register under `app/javascript/src/.../ror_components`
+2. **New `react_on_rails:generate_packs` rake task**: Critical new task for the auto-registration system
+3. **Enhanced dev tooling**: New `ReactOnRails::Dev` namespace with ServerManager, ProcessManager, PackGenerator
+4. **Shakapacker as required dependency**: Made Shakapacker mandatory (removed Webpacker support)
+
+### Why the Explicit Loading Was Added:
+
+Based on the PR context and commit message, the most likely reasons:
+
+1. **Ensuring Critical Task Availability**: The `react_on_rails:generate_packs` task was brand new and absolutely critical to the file-system auto-registration feature. Ihab may have wanted to guarantee it would be loaded in all contexts.
+
+2. **Following Common Rails Engine Patterns**: The `rake_tasks` block is a well-documented pattern in Rails engines. Many gems use it explicitly, even when files are in `lib/tasks/`. Ihab likely followed this pattern as "best practice."
+
+3. **Massive PR Complexity**: With 97 files changed, this was a huge refactor. The `rake_tasks` block addition was a tiny part of the overall changes, and the duplicate loading issue was subtle enough that it wasn't caught during review.
+
+4. **Lack of Awareness About Automatic Loading**: Rails::Engine's automatic loading of `lib/tasks/*.rake` files is not as well-known as it should be. Many developers (even experienced ones) don't realize this happens automatically.
+
+5. **"Belt and Suspenders" Approach**: Given the criticality of the new auto-registration feature, Ihab may have intentionally added explicit loading as a safety measure, not realizing it would cause duplication.
+
+**The commit message doesn't mention the rake_tasks addition at all**—it focuses on generator improvements, dev experience, and component architecture. This suggests the `rake_tasks` block was added as a routine implementation detail, not something Ihab thought needed explanation.
+
+## The Impact
+
+Tasks affected by duplicate execution:
+
+- `react_on_rails:assets:webpack` - Webpack builds ran twice
+- `react_on_rails:generate_packs` - Pack generation ran twice
+- `react_on_rails:locale` - Locale file generation ran twice
+
+This meant:
+
+- **2x build times** during asset precompilation
+- **Slower CI** builds
+- **Confusing console output** showing duplicate webpack compilation messages
+- **Wasted resources** running the same expensive operations twice
+
+## The Fix (PR #2052)
+
+The fix was simple—remove the redundant `rake_tasks` block and rely solely on Rails' automatic loading:
+
+```ruby
+# lib/react_on_rails/engine.rb
+module ReactOnRails
+  class Engine < ::Rails::Engine
+    # ... existing code ...
+
+    # Rake tasks are automatically loaded from lib/tasks/*.rake by Rails::Engine
+    # No need to explicitly load them here to avoid duplicate loading
+  end
+end
+```
+
+## Key Lesson
+
+**Rails::Engine Best Practice**: If your rake task files are in `lib/tasks/`, you don't need a `rake_tasks` block. Rails will load them automatically. Only use `rake_tasks do` if:
+
+- Tasks are in a non-standard location
+- You need to programmatically generate tasks
+- You need to pass context to the tasks
+
+## Timeline
+
+- **Sep 16, 2025** (PR #1770, commit 8f3d178): Ihab adds `rake_tasks` block as part of massive Generator Overhaul (97 files changed)
+- **Nov 18, 2025** (PR #2052, commit 3f6df6be9): Justin discovers and fixes duplicate execution issue by removing the block (~2 months later)
+
+## What We Learned
+
+### For Code Reviews
+
+This incident highlights the challenge of reviewing massive PRs:
+
+- **97 files changed** made it nearly impossible to catch subtle issues
+- The `rake_tasks` addition was 6 lines in a file that wasn't the focus of the PR
+- The duplicate loading bug only manifested during asset precompilation, not during normal development
+- Smaller, focused PRs would have made this easier to catch
+
+### For Testing
+
+The duplicate execution bug was subtle:
+
+- **Didn't cause failures**—just slower builds (2x time)
+- **Hard to notice locally**—developers might not realize builds were taking twice as long
+- **Only obvious in CI**—where build times are closely monitored
+- **Needed production-like scenarios**—requires running `rake assets:precompile` to trigger
+
+### For Documentation
+
+Better documentation of Rails::Engine automatic loading would help:
+
+- Many Rails guides show `rake_tasks` blocks without mentioning automatic loading
+- The Rails Engine guide doesn't clearly state when NOT to use `rake_tasks`
+- This leads to cargo-culting of the pattern
+
+## References
+
+- **Original PR**: [#1770 - "React on Rails Generator Overhaul & Developer Experience Enhancement"](https://github.com/shakacode/react_on_rails/pull/1770)
+- **Original commit**: `8f3d178` - 97 files changed, massive refactor
+- **Fix PR**: [#2052 - "Fix duplicate rake task execution by removing explicit task loading"](https://github.com/shakacode/react_on_rails/pull/2052)
+- **Fix commit**: `3f6df6be9` - Simple 6-line removal
+- **Rails Engine documentation**: https://guides.rubyonrails.org/engines.html#rake-tasks

data/bin/ci-run-failed-specs

@@ -139,10 +139,12 @@ echo ""
 
 # Determine the working directory (check if we need to be in spec/dummy)
 WORKING_DIR="."
-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}"
+if [ ${#UNIQUE_SPECS[@]} -gt 0 ]; then
+  if [[ "${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}"
+    fi
   fi
 fi
 

data/bin/ci-switch-config

@@ -255,9 +255,10 @@ 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).
+  # NOTE: This executes 'ruby' before the version manager reloads in your current shell.
+  # The script/convert file requires Ruby 2.6+ and uses basic file I/O operations.
+  # Most modern Ruby versions (2.6+) are compatible. The version manager changes above
+  # only take effect after shell reload, so this uses your current Ruby installation.
   print_header "Running script/convert to downgrade dependencies"
   cd "$PROJECT_ROOT"
   ruby script/convert

data/knip.ts

@@ -162,7 +162,7 @@ const config: KnipConfig = {
         'url-loader',
         // Transitive dependency of shakapacker but listed as direct dependency
         'webpack-merge',
-        // Dependencies not detected in production mode
+        // Dependencies not detected in production mode (runtime injected or dynamic imports)
         '@babel/runtime',
         'mini-css-extract-plugin',
         'css-loader',

data/lib/generators/react_on_rails/base_generator.rb

@@ -4,10 +4,12 @@ require "rails/generators"
 require "fileutils"
 require_relative "generator_messages"
 require_relative "generator_helper"
+require_relative "js_dependency_manager"
 module ReactOnRails
   module Generators
     class BaseGenerator < Rails::Generators::Base
       include GeneratorHelper
+      include JsDependencyManager
 
       Rails::Generators.hide_namespace(namespace)
       source_root(File.expand_path("templates", __dir__))
@@ -99,7 +101,8 @@ module ReactOnRails
         puts "Adding Shakapacker #{ReactOnRails::PackerUtils.shakapacker_version} config"
         base_path = "base/base/"
         config = "config/shakapacker.yml"
-        copy_file("#{base_path}#{config}", config)
+        # Use template to enable version-aware configuration
+        template("#{base_path}#{config}.tt", config)
         configure_rspack_in_shakapacker if options.rspack?
       end
 
@@ -107,7 +110,7 @@ module ReactOnRails
         run "bundle"
       end
 
-      def update_gitignore_for_generated_bundles
+      def update_gitignore_for_auto_registration
         gitignore_path = File.join(destination_root, ".gitignore")
         return unless File.exist?(gitignore_path)
 
@@ -146,123 +149,6 @@ module ReactOnRails
 
       private
 
-      def setup_js_dependencies
-        add_js_dependencies
-        install_js_dependencies
-      end
-
-      def add_js_dependencies
-        add_react_on_rails_package
-        add_react_dependencies
-        add_css_dependencies
-        add_dev_dependencies
-      end
-
-      def add_react_on_rails_package
-        major_minor_patch_only = /\A\d+\.\d+\.\d+\z/
-
-        # Try to use package_json gem first, fall back to direct npm commands
-        react_on_rails_pkg = if ReactOnRails::VERSION.match?(major_minor_patch_only)
-                               ["react-on-rails@#{ReactOnRails::VERSION}"]
-                             else
-                               puts "Adding the latest react-on-rails NPM module. " \
-                                    "Double check this is correct in package.json"
-                               ["react-on-rails"]
-                             end
-
-        puts "Installing React on Rails package..."
-        return if add_npm_dependencies(react_on_rails_pkg)
-
-        puts "Using direct npm commands as fallback"
-        success = system("npm", "install", *react_on_rails_pkg)
-        handle_npm_failure("react-on-rails package", react_on_rails_pkg) unless success
-      end
-
-      def add_react_dependencies
-        puts "Installing React dependencies..."
-        react_deps = %w[
-          react
-          react-dom
-          @babel/preset-react
-          prop-types
-          babel-plugin-transform-react-remove-prop-types
-          babel-plugin-macros
-        ]
-        return if add_npm_dependencies(react_deps)
-
-        success = system("npm", "install", *react_deps)
-        handle_npm_failure("React dependencies", react_deps) unless success
-      end
-
-      def add_css_dependencies
-        puts "Installing CSS handling dependencies..."
-        css_deps = %w[
-          css-loader
-          css-minimizer-webpack-plugin
-          mini-css-extract-plugin
-          style-loader
-        ]
-        return if add_npm_dependencies(css_deps)
-
-        success = system("npm", "install", *css_deps)
-        handle_npm_failure("CSS dependencies", css_deps) unless success
-      end
-
-      def add_dev_dependencies
-        puts "Installing development dependencies..."
-        dev_deps = %w[
-          @pmmmwh/react-refresh-webpack-plugin
-          react-refresh
-        ]
-        return if add_npm_dependencies(dev_deps, dev: true)
-
-        success = system("npm", "install", "--save-dev", *dev_deps)
-        handle_npm_failure("development dependencies", dev_deps, dev: true) unless success
-      end
-
-      def install_js_dependencies
-        # Detect which package manager to use
-        success = if File.exist?(File.join(destination_root, "yarn.lock"))
-                    system("yarn", "install")
-                  elsif File.exist?(File.join(destination_root, "pnpm-lock.yaml"))
-                    system("pnpm", "install")
-                  elsif File.exist?(File.join(destination_root, "package-lock.json")) ||
-                        File.exist?(File.join(destination_root, "package.json"))
-                    # Use npm for package-lock.json or as default fallback
-                    system("npm", "install")
-                  else
-                    true # No package manager detected, skip
-                  end
-
-        unless success
-          GeneratorMessages.add_warning(<<~MSG.strip)
-            ⚠️  JavaScript dependencies installation failed.
-
-            This could be due to network issues or missing package manager.
-            You can install dependencies manually later by running:
-            • npm install (if using npm)
-            • yarn install (if using yarn)
-            • pnpm install (if using pnpm)
-          MSG
-        end
-
-        success
-      end
-
-      def handle_npm_failure(dependency_type, packages, dev: false)
-        install_command = dev ? "npm install --save-dev" : "npm install"
-        GeneratorMessages.add_warning(<<~MSG.strip)
-          ⚠️  Failed to install #{dependency_type}.
-
-          The following packages could not be installed automatically:
-          #{packages.map { |pkg| "  • #{pkg}" }.join("\n")}
-
-          This could be due to network issues or missing package manager.
-          You can install them manually later by running:
-            #{install_command} #{packages.join(' ')}
-        MSG
-      end
-
       def copy_webpack_main_config(base_path, config)
         webpack_config_path = "config/webpack/webpack.config.js"