Fix component registration race condition by using defer for all scripts

justin808 · claude · justin808 · commit cf17e36421f3 · 2025-11-09T20:36:29.000-10:00
Changes the default loading strategy from :async to :defer to prevent race conditions where React hydration starts before component registrations complete. Root cause: With async script loading, both client-bundle and generated component packs can execute in any order. When client-bundle executes first, React attempts to hydrate components that haven't been registered yet, causing "Could not find component registered with name X" errors. Solution: - Default generated_component_packs_loading_strategy to :defer (was :async) - Use defer: true for client-bundle in dummy app layout - Update comments to reflect new strategy With defer, scripts execute in DOM order after parsing, ensuring: 1. Generated component packs load first 2. Components register before main bundle executes 3. React hydration finds all registered components Fixes CI failures in: - spec/system/integration_spec.rb[1:1:6:1:2] - spec/system/integration_spec.rb[1:1:6:2:2] 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -51,6 +51,25 @@ Pre-commit hooks automatically run:
 
 **CRITICAL: NEVER wait for CI to verify fixes. Always replicate failures locally first.**
 
+#### Switch Between CI Configurations (🔥 NEW!)
+
+The project tests against two configurations:
+- **Latest**: Ruby 3.4, Node 22, Shakapacker 9.3.0, React 19 (runs on all PRs)
+- **Minimum**: Ruby 3.2, Node 20, Shakapacker 8.2.0, React 18 (runs only on master)
+
+```bash
+# Check your current configuration
+bin/ci-switch-config status
+
+# Switch to minimum dependencies (for debugging minimum CI failures)
+bin/ci-switch-config minimum
+
+# Switch back to latest dependencies
+bin/ci-switch-config latest
+```
+
+**See `SWITCHING_CI_CONFIGS.md` for detailed usage and troubleshooting.**
+
 #### Re-run Failed CI Jobs (🔥 NEW - Most Efficient!)
 
 ```bash
diff --git a/SWITCHING_CI_CONFIGS.md b/SWITCHING_CI_CONFIGS.md
@@ -0,0 +1,286 @@
+# Switching Between CI Configurations Locally
+
+This guide explains how to switch between different CI test configurations locally to replicate CI failures.
+
+## Quick Start
+
+```bash
+# Check your current configuration
+bin/ci-switch-config status
+
+# Switch to minimum dependencies (Ruby 3.2, Node 20)
+bin/ci-switch-config minimum
+
+# Switch back to latest dependencies (Ruby 3.4, Node 22)
+bin/ci-switch-config latest
+```
+
+## CI Configurations
+
+The project runs tests against two configurations:
+
+### Latest (Default Development)
+
+- **Ruby**: 3.4
+- **Node**: 22
+- **Shakapacker**: 9.3.0
+- **React**: 19.0.0
+- **Dependencies**: Latest versions with `--frozen-lockfile`
+- **When it runs**: Always on PRs and master
+
+### Minimum (Compatibility Testing)
+
+- **Ruby**: 3.2
+- **Node**: 20
+- **Shakapacker**: 8.2.0
+- **React**: 18.0.0
+- **Dependencies**: Minimum supported versions
+- **When it runs**: Only on master branch
+
+## When to Switch Configurations
+
+**Switch to minimum when:**
+
+- CI fails on `dummy-app-integration-tests (3.2, 20, minimum)` but passes on latest
+- You're debugging compatibility with older dependencies
+- You want to verify minimum version support before releasing
+
+**Switch to latest when:**
+
+- You're done testing minimum configuration
+- You want to return to normal development
+- CI failures are on latest configuration
+
+## Prerequisites
+
+You must have [asdf](https://asdf-vm.com/) installed to manage Ruby and Node versions.
+
+```bash
+# Install asdf if needed (macOS with Homebrew)
+brew install asdf
+echo -e "\n. $(brew --prefix asdf)/libexec/asdf.sh" >> ~/.zshrc
+source ~/.zshrc
+
+# Install plugins
+asdf plugin add ruby
+asdf plugin add nodejs
+```
+
+## Detailed Usage
+
+### 1. Check Current Configuration
+
+```bash
+bin/ci-switch-config status
+```
+
+This shows:
+
+- Current Ruby and Node versions
+- Dependency versions (Shakapacker, React)
+- Which configuration you're currently on
+
+### 2. Switch to Minimum Configuration
+
+```bash
+bin/ci-switch-config minimum
+```
+
+This will:
+
+1. Create `.tool-versions` with Ruby 3.2.8 and Node 20.18.1
+2. Run `script/convert` to downgrade dependencies:
+   - Shakapacker 9.3.0 → 8.2.0
+   - React 19.0.0 → 18.0.0
+   - Remove ESLint and other packages incompatible with Node 20
+3. Clean `node_modules` and `yarn.lock`
+4. Reinstall dependencies without `--frozen-lockfile`
+5. Clean and reinstall spec/dummy dependencies
+
+**After switching, run:**
+
+```bash
+# Reload your shell to pick up new Ruby/Node versions
+cd /Users/justin/conductor/react_on_rails/.conductor/kuwait-v1
+asdf current
+
+# Build and test
+rake node_package
+cd spec/dummy
+bin/shakapacker-precompile-hook
+RAILS_ENV=test bin/shakapacker
+cd ../..
+bundle exec rake run_rspec:all_dummy
+```
+
+### 3. Switch Back to Latest Configuration
+
+```bash
+bin/ci-switch-config latest
+```
+
+This will:
+
+1. Create `.tool-versions` with Ruby 3.4.3 and Node 22.12.0
+2. Restore files from git (reverting changes made by `script/convert`)
+3. Clean `node_modules` and `yarn.lock`
+4. Reinstall dependencies with `--frozen-lockfile`
+5. Clean and reinstall spec/dummy dependencies
+
+**After switching, run:**
+
+```bash
+# Reload your shell to pick up new Ruby/Node versions
+cd /Users/justin/conductor/react_on_rails/.conductor/kuwait-v1
+asdf current
+
+# Build and test
+rake node_package
+cd spec/dummy
+bin/shakapacker-precompile-hook
+RAILS_ENV=test bin/shakapacker
+cd ../..
+bundle exec rake run_rspec:all_dummy
+```
+
+## What Gets Modified
+
+When switching to **minimum**, these files are modified:
+
+- `.tool-versions` - Ruby/Node versions
+- `Gemfile.development_dependencies` - Shakapacker gem version
+- `package.json` - React versions, dev dependencies removed
+- `spec/dummy/package.json` - React and Shakapacker versions
+- `packages/react-on-rails-pro/package.json` - Test scripts modified
+- `node_modules/`, `yarn.lock` - Cleaned and regenerated
+- `spec/dummy/node_modules/`, `spec/dummy/yarn.lock` - Cleaned and regenerated
+
+When switching to **latest**, these files are restored from git.
+
+## Common Workflows
+
+### Debugging a Minimum Config CI Failure
+
+```bash
+# 1. Check current config
+bin/ci-switch-config status
+
+# 2. Switch to minimum
+bin/ci-switch-config minimum
+
+# 3. Reload shell
+cd /Users/justin/conductor/react_on_rails/.conductor/kuwait-v1
+
+# 4. Verify versions changed
+ruby --version  # Should show 3.2.x
+node --version  # Should show v20.x
+
+# 5. Build and test
+rake node_package
+cd spec/dummy
+bin/shakapacker-precompile-hook
+RAILS_ENV=test bin/shakapacker
+cd ../..
+
+# 6. Run the failing tests
+bundle exec rake run_rspec:all_dummy
+
+# 7. Fix the issue
+
+# 8. Switch back when done
+bin/ci-switch-config latest
+```
+
+### Quick Test in Both Configurations
+
+```bash
+# Test in latest (current default)
+bin/ci-switch-config status
+bundle exec rake run_rspec:all_dummy
+
+# Switch and test in minimum
+bin/ci-switch-config minimum
+rake node_package
+cd spec/dummy && bin/shakapacker-precompile-hook && RAILS_ENV=test bin/shakapacker && cd ../..
+bundle exec rake run_rspec:all_dummy
+
+# Switch back
+bin/ci-switch-config latest
+```
+
+## Troubleshooting
+
+### "asdf: No version is set for ruby"
+
+After switching, you need to reload your shell:
+
+```bash
+cd /Users/justin/conductor/react_on_rails/.conductor/kuwait-v1
+# The cd command will trigger asdf to load the new versions
+ruby --version  # Verify it changed
+```
+
+### Ruby/Node version didn't change
+
+If asdf doesn't automatically switch:
+
+```bash
+asdf install  # Install missing versions from .tool-versions
+asdf reshim ruby
+asdf reshim nodejs
+```
+
+### Yarn install fails
+
+If you get package resolution errors:
+
+```bash
+# Clean everything and try again
+rm -rf node_modules yarn.lock spec/dummy/node_modules spec/dummy/yarn.lock
+yarn install
+cd spec/dummy && yarn install
+```
+
+### Git complains about modified files
+
+The script will warn you if you have uncommitted changes. You can:
+
+- Commit or stash your changes first, OR
+- Proceed (script will ask for confirmation)
+
+### Switching back doesn't restore everything
+
+If `git restore` doesn't work:
+
+```bash
+# Manually restore from git
+git restore Gemfile.development_dependencies package.json spec/dummy/package.json packages/react-on-rails-pro/package.json
+
+# Then run latest again
+bin/ci-switch-config latest
+```
+
+## Integration with CI Debugging Tools
+
+This script works well with the other CI debugging tools:
+
+```bash
+# 1. Check what failed in CI
+bin/ci-rerun-failures
+
+# 2. If it's a minimum config failure, switch
+bin/ci-switch-config minimum
+
+# 3. Run the specific failing tests
+pbpaste | bin/ci-run-failed-specs
+
+# 4. Switch back when done
+bin/ci-switch-config latest
+```
+
+## See Also
+
+- `CLAUDE.md` - Main development guide with CI debugging info
+- `bin/ci-rerun-failures` - Re-run only failed CI jobs locally
+- `bin/ci-run-failed-specs` - Run specific failing RSpec examples
+- `bin/ci-local` - Smart test detection based on changes
diff --git a/lib/react_on_rails/configuration.rb b/lib/react_on_rails/configuration.rb
@@ -154,9 +154,9 @@ def check_component_registry_timeout
       raise ReactOnRails::Error, "component_registry_timeout must be a positive integer"
     end
 
-    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    # rubocop:disable Metrics/CyclomaticComplexity
     def validate_generated_component_packs_loading_strategy
-      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      # rubocop:enable Metrics/CyclomaticComplexity
 
       if defer_generated_component_packs
         if %i[async sync].include?(generated_component_packs_loading_strategy)
@@ -176,13 +176,11 @@ def validate_generated_component_packs_loading_strategy
         1. Use :defer or :sync loading strategy instead of :async
         2. Upgrade to Shakapacker v8.2.0 or above to enable async script loading
       MSG
-      if PackerUtils.supports_async_loading?
-        self.generated_component_packs_loading_strategy ||= :async
-      elsif generated_component_packs_loading_strategy.nil?
-        # Use defer as the default for older Shakapacker versions to ensure
-        # generated component packs load and register components before main bundle executes
+      if generated_component_packs_loading_strategy.nil?
+        # Use defer as the default to ensure generated component packs load and register
+        # components before main bundle executes, avoiding race conditions with async loading
         self.generated_component_packs_loading_strategy = :defer
-      elsif generated_component_packs_loading_strategy == :async
+      elsif generated_component_packs_loading_strategy == :async && !PackerUtils.supports_async_loading?
         raise ReactOnRails::Error, "**ERROR** #{msg}"
       end
 
diff --git a/spec/dummy/app/views/layouts/application.html.erb b/spec/dummy/app/views/layouts/application.html.erb
@@ -9,16 +9,10 @@
 
   <%= yield :head %>
 
-  <%# Conditionally use defer: true for pages with Redux shared stores (inline registration).
-      Modern apps should use async: true for optimal performance. See docs for details:
-      docs/building-features/streaming-server-rendering.md %>
-  <% if uses_redux_shared_store? %>
-    <%# defer: true required for Redux shared stores with inline component registration %>
-    <%= javascript_pack_tag('client-bundle', 'data-turbo-track': 'reload', defer: true) %>
-  <% else %>
-    <%# async: true is the recommended approach for modern apps (Shakapacker >= 8.2.0) %>
-    <%= javascript_pack_tag('client-bundle', 'data-turbo-track': 'reload', async: true) %>
-  <% end %>
+  <%# Use defer: true to ensure proper script execution order.
+      When using generated component packs (auto_load_bundle), defer ensures
+      component registrations complete before React hydration begins. %>
+  <%= javascript_pack_tag('client-bundle', 'data-turbo-track': 'reload', defer: true) %>
 
   <%= csrf_meta_tags %>
 </head>
diff --git a/spec/dummy/config/initializers/react_on_rails.rb b/spec/dummy/config/initializers/react_on_rails.rb
@@ -42,7 +42,6 @@ def self.adjust_props_for_client_side_hydration(component_name, props)
   config.components_subdirectory = "startup"
   config.auto_load_bundle = true
   config.immediate_hydration = false
-  # Don't explicitly set generated_component_packs_loading_strategy - let it default based on Shakapacker version
-  # - Shakapacker >= 8.2.0: defaults to :async (optimal performance)
-  # - Shakapacker < 8.2.0: defaults to :defer (ensures proper component registration order)
+  # Don't explicitly set generated_component_packs_loading_strategy - let it default to :defer
+  # which ensures generated component packs load and register components before main bundle executes
 end
