Document content_for pattern to prevent FOUC with SSR and auto_load_bundle

justin808 · claude · justin808 · commit 32c22aab17d2 · 2025-10-16T10:55:25.000-10:00
Fixes #1864 When using auto_load_bundle = true with server-side rendering, there's a chicken-and-egg problem: stylesheets must load in the <head>, but react_component calls in <body> trigger auto-appends after the head has rendered, causing FOUC (Flash of Unstyled Content). This commit documents the content_for workaround pattern and references the comprehensive Shakapacker FOUC prevention guide (PR #737). Key improvements: - Explains the root cause of FOUC with SSR + auto_load_bundle - Documents the content_for :body_content pattern with execution flow - Added step-by-step comments showing Rails execution order - References Shakapacker's comprehensive FOUC prevention documentation - Links to working example in react-webpack-rails-tutorial PR #686 - Provides alternative solution (disable auto_load_bundle) - Clarifies that HMR FOUC is separate from this SSR issue - Addresses code review feedback from PR #1865 comment #3412140475 Aligns with Shakapacker PR #737 preventing_fouc.md documentation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/docs/core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md b/docs/core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md
@@ -522,23 +522,58 @@ As of version 13.3.4, bundles inside directories that match `config.components_s
 
 #### 2. CSS not loading (FOUC - Flash of Unstyled Content)
 
-**Problem**: Components load but CSS styles are missing or delayed.
+**Problem**: Components load but CSS styles are missing or delayed, particularly with server-side rendering and `auto_load_bundle = true`.
 
-**Important**: FOUC (Flash of Unstyled Content) **only occurs with HMR (Hot Module Replacement)**. Static and production modes work perfectly without FOUC.
+**Root Cause**: When using `auto_load_bundle = true`, `react_component` calls automatically invoke `append_stylesheet_pack_tag` during rendering. However, Shakapacker requires these appends to execute BEFORE the main `stylesheet_pack_tag` in your layout's `<head>`. Since Rails renders the layout's `<head>` before the `<body>` (where `react_component` calls typically occur), the appends happen too late, causing FOUC.
 
-**Solutions**:
+**Solution**: Use the `content_for :body_content` pattern documented in Shakapacker's [Preventing FOUC guide](https://github.com/shakacode/shakapacker/blob/master/docs/preventing_fouc.md#the-content_for-body_content-pattern).
+
+This pattern renders your body content first, ensuring all `react_component` auto-appends execute before the `<head>` renders:
+
+```erb
+<%# Step 1: This block executes first, capturing content AND triggering auto-appends %>
+<% content_for :body_content do %>
+  <%= react_component "NavigationBarApp", prerender: true %>
+
+  <div class="container">
+    <%= yield %>
+  </div>
+
+  <%= react_component "Footer", prerender: true %>
+<% end %>
+<!DOCTYPE html>
+<html>
+<head>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%# Step 2: Head renders with all accumulated stylesheet/JS appends %>
+  <%= stylesheet_pack_tag(media: 'all') %>
+  <%= javascript_pack_tag(defer: true) %>
+</head>
+<body>
+  <%# Step 3: Finally, the captured body_content is rendered here %>
+  <%= yield :body_content %>
+</body>
+</html>
+```
+
+**Note**: While defining body content before `<!DOCTYPE html>` may seem counter-intuitive, Rails processes the `content_for` block first (capturing content and triggering appends), then renders the HTML in proper document order.
+
+**Alternative**: If the `content_for` pattern doesn't fit your needs, disable auto-loading and manually specify packs:
+
+```ruby
+# config/initializers/react_on_rails.rb
+config.auto_load_bundle = false
+```
 
-- **Development with HMR** (`./bin/dev`): FOUC is expected behavior due to dynamic CSS injection - **not a bug**
-- **Development static** (`./bin/dev static`): No FOUC - CSS is extracted to separate files like production
-- **Production** (`./bin/dev prod`): No FOUC - CSS is extracted and optimized
-- **Layout**: Verify your layout includes empty `<%= stylesheet_pack_tag %>` placeholder for CSS injection
-- **Component imports**: Check that CSS files are properly imported: `import styles from './Component.module.css';`
+**Additional Resources**:
 
-**Key insight**: Choose your development mode based on your current needs:
+- **Complete FOUC prevention guide**: [Shakapacker Preventing FOUC documentation](https://github.com/shakacode/shakapacker/blob/master/docs/preventing_fouc.md)
+- **Working example**: [react-webpack-rails-tutorial PR #686](https://github.com/shakacode/react-webpack-rails-tutorial/pull/686)
+- **Related issue**: [Shakapacker #720](https://github.com/shakacode/shakapacker/issues/720)
 
-- Use HMR for fastest development (accept FOUC)
-- Use static mode when testing styling without FOUC
-- Use production mode for final testing
+**Note**: HMR-related FOUC in development mode (dynamic CSS injection) is separate from this SSR auto-loading issue. See Shakapacker docs for details.
 
 #### 3. "document is not defined" errors during SSR
 
