react_on_rails 16.2.0.beta.10 → 16.2.0.beta.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da10987e43490e2a8da60fccb2033038aa9fa6a9b5ccce9add3f9d0da795474c
-  data.tar.gz: 9e7a3a46c8bb8e0fcc57142b5a1218ea58d5155d54614038d035e2e6b39fdf47
+  metadata.gz: 1f1f3592776a1d9cc69f832cdd3df34f4f1b696be6dd681d341614830d97a3d3
+  data.tar.gz: d7563d35d02ccd555be46984c21be8bf2cc9b9998d0ad70d0aefd4588940cda5
 SHA512:
-  metadata.gz: d9f6d5be2b5bf2437adc711b6ac77e64fb7c6540d34bdce6380e98bf919872ec59e897b87869e25221f1f461ac91b25fc146c48701eb161630cb9bea7c44c7a1
-  data.tar.gz: 5ec66977d53c808a8983277c6534e24fe966123105c4738e20995a9bb45be34a139030fe3e70ffe3251bb9961470371841bea040e558deb3fc974c154d6bdb7d
+  metadata.gz: b7284eb5e6ef0133546d405f441ae7c0f2099108353d7f6de9d9eff889c0d9d411c2952b37d98c905fb31dd4dc88cb7b3b8ef1dab5d12f6b5856c0172973d0b1
+  data.tar.gz: df238dcf4c71cd74547ff523c52974d752aa1bb53d53de50ec3d9c7227b3d55c4d96102c508561991dc41bba3aa3077eb5b3d81f1c08c0e53fa7ebff2ea1430c

data/CHANGELOG.md

@@ -23,14 +23,20 @@ After a release, please make sure to run `bundle exec rake update_changelog`. Th
 
 Changes since the last non-beta release.
 
-#### Fixed
+#### Added
 
-- **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).
+- **CSP Nonce Support for Console Replay**: Added Content Security Policy (CSP) nonce support for the `consoleReplay` script generated during server-side rendering. When Rails CSP is configured, the console replay script will automatically include the nonce attribute, allowing it to execute under restrictive CSP policies like `script-src: 'self'`. The implementation includes cross-version Rails compatibility (5.2-7.x) and defense-in-depth nonce sanitization to prevent attribute injection attacks. [PR 2059](https://github.com/shakacode/react_on_rails/pull/2059) by [justin808](https://github.com/justin808).
+
+#### Bug Fixes
+
+- [PR 2085](https://github.com/shakacode/react_on_rails/pull/2085) by [justin808](https://github.com/justin808): Fix pack generation in bin/dev when running from Bundler context. Pack generation was failing with "Could not find command 'react_on_rails:generate_packs'" because Bundler was intercepting the subprocess call. The fix wraps the bundle exec call with `Bundler.with_unbundled_env` to prevent interception.
 
-### [v16.2.0.beta.8] - 2025-11-16
+### [v16.2.0.beta.11] - 2025-11-19
 
 #### Added
 
+- **Shakapacker 9.0+ Private Output Path Integration**: Added automatic detection and integration of Shakapacker 9.0+ `private_output_path` configuration. React on Rails now automatically reads `private_output_path` from `shakapacker.yml` and sets server bundle paths, eliminating manual configuration synchronization. Includes version-aware generator templates, enhanced doctor command diagnostics for configuration validation and upgrade recommendations, and improved security with `enforce_private_server_bundles` option. [PR 2028](https://github.com/shakacode/react_on_rails/pull/2028) by [justin808](https://github.com/justin808).
+
 - **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).
 
 - **Attribution Comment**: Added HTML comment attribution to Rails views containing React on Rails functionality. The comment automatically displays which version is in use (open source React on Rails or React on Rails Pro) and, for Pro users, shows the license status. This helps identify React on Rails usage across your application. [PR #1857](https://github.com/shakacode/react_on_rails/pull/1857) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
@@ -41,8 +47,6 @@ 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).
-
 - **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
@@ -67,23 +71,13 @@ Changes since the last non-beta release.
 
 - **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).
 
-#### Deprecated
-
-- **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).
-
 #### Fixed
 
-- **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).
+- **Doctor Command Version Mismatch Detection**: Fixed false version mismatch warnings in `rake react_on_rails:doctor` when using beta/prerelease versions. The command now correctly recognizes that gem version `16.2.0.beta.10` matches npm version `16.2.0-beta.10` using proper semver conversion instead of string normalization that stripped prerelease identifiers. [PR 2064](https://github.com/shakacode/react_on_rails/pull/2064) by [ihabadham](https://github.com/ihabadham).
 
-- **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).
+- **Rails 5.2-6.0 Compatibility**: Fixed compatibility with Rails 5.2-6.0 by adding polyfill for `compact_blank` method (introduced in Rails 6.1). Also refactored webpack asset handling to conditionally include React on Rails Pro files only when available, preventing NoMethodErrors in open-source installations. [PR 2058](https://github.com/shakacode/react_on_rails/pull/2058) 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).
+- **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).
 
 #### Breaking Changes
 
@@ -1845,9 +1839,8 @@ such as:
 
 - Fix several generator-related issues.
 
-[unreleased]: https://github.com/shakacode/react_on_rails/compare/v16.2.0.beta.8...master
-[v16.2.0.beta.8]: https://github.com/shakacode/react_on_rails/compare/16.2.0.beta.4...v16.2.0.beta.8
-[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.11...master
+[v16.2.0.beta.11]: https://github.com/shakacode/react_on_rails/compare/16.1.1...v16.2.0.beta.11
 [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,13 +194,70 @@ 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
 
+### Beta Release Changelog Curation
+
+When consolidating beta versions into a stable release, carefully curate entries to include only user-facing changes:
+
+**Remove these types of entries:**
+
+1. **Developer-only tooling**:
+   - yalc publish fixes (local development tool)
+   - Git dependency support (contributor workflow)
+   - CI/build script improvements
+   - Internal tooling changes
+
+2. **Beta-specific fixes**:
+   - Bugs introduced during the beta cycle (not present in last stable)
+   - Fixes for new beta-only features (e.g., bin/dev in 16.2.0.beta)
+   - Generator handling of beta/RC version formats
+
+3. **Pro-specific features** (move to Pro changelog):
+   - Node renderer fixes/improvements
+   - Streaming-related changes
+   - Async loading features (Pro-exclusive)
+
+**Keep these types of entries:**
+
+1. **User-facing fixes**:
+   - Bugs that existed in previous stable release (e.g., 16.1.x)
+   - Compatibility fixes (Rails version support, etc.)
+   - Performance improvements affecting all users
+
+2. **Breaking changes**:
+   - API changes requiring migration
+   - Removed methods/features
+   - Configuration changes
+
+**Investigation process:**
+
+For each suspicious entry:
+1. Check git history: `git log --oneline <last_stable>..<current_beta> -- <file>`
+2. Determine when bug was introduced (stable vs beta cycle)
+3. Verify whether fix applies to stable users or only beta users
+4. Check PR description for context about what was broken
+
+**Example reference:** See [PR #2072](https://github.com/shakacode/react_on_rails/pull/2072) for a complete example of beta changelog curation with detailed investigation notes.
+
 ## ⚠️ FORMATTING RULES
 
 **Prettier is the SOLE authority for formatting non-Ruby files, and RuboCop for formatting Ruby files. NEVER manually format code.**
@@ -198,12 +271,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 +309,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 +602,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.10)
+    react_on_rails (16.2.0.beta.12)
       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/analysis/v8-crash-retry-solution.md

@@ -0,0 +1,148 @@
+# V8 Crash Retry Solution for CI
+
+## Problem
+
+CI jobs occasionally fail with a transient V8 bytecode deserialization crash during the Node.js setup phase. The error manifests as:
+
+```
+Fatal error in , line 0
+Check failed: ReadSingleBytecodeData( source_.Get(), SlotAccessorForHandle<IsolateT>(&ret, isolate())) == 1.
+```
+
+This error occurs during the `yarn cache dir` command execution within the `actions/setup-node@v4` action.
+
+## Root Cause
+
+This is a known bug in Node.js/V8 that occurs sporadically:
+
+- **Node.js Issue**: https://github.com/nodejs/node/issues/56010
+- **Setup-node Issue**: https://github.com/actions/setup-node/issues/1028
+
+The crash happens when V8 attempts to deserialize cached bytecode and encounters corrupted or incompatible data. It's a transient issue that typically resolves on retry.
+
+## Previous Workarounds
+
+Before this fix, the codebase used two workarounds:
+
+1. **Completely disable yarn caching** in `examples.yml`:
+
+   ```yaml
+   # TODO: Re-enable yarn caching once Node.js V8 cache crash is fixed
+   # Tracking: https://github.com/actions/setup-node/issues/1028
+   # cache: yarn
+   # cache-dependency-path: '**/yarn.lock'
+   ```
+
+2. **Conditionally disable caching for Node 22** in `integration-tests.yml`:
+   ```yaml
+   cache: ${{ matrix.node-version != '22' && 'yarn' || '' }}
+   ```
+
+Both workarounds significantly slowed down CI by preventing yarn dependency caching.
+
+## Solution
+
+Created a custom composite GitHub action at `.github/actions/setup-node-with-retry/` that:
+
+### Key Features
+
+1. **Pre-validation**: Tests `yarn cache dir` works before running `setup-node`
+2. **Automatic retry**: Retries up to 3 times when V8 crashes are detected
+3. **Smart error detection**: Only retries on V8 crashes, fails fast on other errors
+4. **Clear diagnostics**: Provides warning annotations in CI logs
+5. **Configurable**: Allows customizing max retries (defaults to 3)
+6. **Backward compatible**: Drop-in replacement for `actions/setup-node@v4`
+
+### How It Works
+
+```yaml
+- name: Setup Node.js with retry
+  shell: bash
+  run: |
+    # Pre-validate yarn cache dir works
+    if timeout 30 yarn cache dir > "$TEMP_OUTPUT" 2>&1; then
+      echo "Yarn cache dir command succeeded"
+    else
+      # Check for V8 crash signature
+      if grep -q "Fatal error in.*Check failed: ReadSingleBytecodeData" "$TEMP_OUTPUT"; then
+        echo "::warning::V8 bytecode deserialization error detected"
+        # Retry logic...
+      fi
+    fi
+
+- name: Actually setup Node.js
+  uses: actions/setup-node@v4
+  # ... standard setup-node configuration
+```
+
+### Usage
+
+```yaml
+- name: Setup Node
+  uses: ./.github/actions/setup-node-with-retry
+  with:
+    node-version: 22
+    cache: yarn
+    cache-dependency-path: '**/yarn.lock'
+    max-retries: 3 # Optional, defaults to 3
+```
+
+## Changes Made
+
+Updated all 8 CI workflow files to use the new action:
+
+1. ✅ `examples.yml` - **Re-enabled yarn caching**
+2. ✅ `integration-tests.yml` - **Re-enabled yarn caching for Node 22**
+3. ✅ `lint-js-and-ruby.yml`
+4. ✅ `package-js-tests.yml`
+5. ✅ `playwright.yml`
+6. ✅ `pro-integration-tests.yml`
+7. ✅ `pro-lint.yml`
+8. ✅ `pro-test-package-and-gem.yml`
+
+## Benefits
+
+1. **Improved reliability**: CI no longer fails due to transient V8 crashes
+2. **Better performance**: Yarn caching re-enabled across all workflows
+3. **Clear diagnostics**: Warning annotations show when retries occur
+4. **Maintainable**: Centralized retry logic in a reusable action
+5. **Future-proof**: Can be updated independently if V8 crash patterns change
+
+## Monitoring
+
+To verify the retry logic is working when V8 crashes occur:
+
+1. Watch CI logs for these warning messages:
+
+   ```
+   ::warning::V8 bytecode deserialization error detected (attempt 1/3)
+   Retrying in 5 seconds...
+   ```
+
+2. Check that jobs succeed after retry instead of failing
+
+3. If a job exhausts all retries, it will show:
+   ```
+   ::error::All 3 retry attempts failed
+   ```
+
+## Implementation Details
+
+- **Timeout**: Each retry attempt has a 30-second timeout for `yarn cache dir`
+- **Retry delay**: 5 seconds between attempts to allow transient issues to clear
+- **Max retries**: Defaults to 3, configurable via input
+- **Error detection**: Regex pattern matches V8 crash signature in stderr/stdout
+
+## Future Improvements
+
+If the V8 crash persists even with retries, consider:
+
+1. Updating Node.js to a version with the fix (when available)
+2. Increasing max-retries for particularly flaky environments
+3. Adding exponential backoff between retries
+4. Implementing cache clearing before retry
+
+## Pull Request
+
+- **PR**: https://github.com/shakacode/react_on_rails/pull/2082
+- **Branch**: `jg-/ci-retry-v8-crash`