Document content_for pattern to prevent FOUC with SSR and auto_load_bundle

justin808 · claude · justin808 · commit a7f765a3bd57 · 2025-10-15T23:05:50.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 that ensures all react_component calls happen before the head renders, preventing FOUC. Key improvements: - Explains the root cause of FOUC with SSR + auto_load_bundle - Documents the content_for :body_content pattern with full example - Provides alternative solutions (disable auto_load_bundle, manual packs) - Clarifies that HMR FOUC is separate from this SSR issue - References working example in react-webpack-rails-tutorial PR #686 🤖 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,76 @@ 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 with SSR + auto_load_bundle**: Shakapacker requires `append_stylesheet_pack_tag` to be called before `stylesheet_pack_tag` renders. However, with SSR and `auto_load_bundle = true`, `react_component` calls in the `<body>` automatically call `append_stylesheet_pack_tag`, but this happens AFTER the `<head>` (which contains `stylesheet_pack_tag`) has already been rendered. This creates a chicken-and-egg problem causing FOUC.
 
 **Solutions**:
 
-- **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
+**Option 1: Use content_for pattern (Recommended for SSR + auto_load_bundle)**
+
+Render your body content BEFORE the head using Rails `content_for` blocks. This ensures all `react_component` calls (and their auto-appends) happen before the head renders:
+
+```erb
+<% 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 %>
+
+  <!-- All auto-appended stylesheets will be included here -->
+  <%= stylesheet_pack_tag(media: 'all') %>
+  <%= javascript_pack_tag(defer: true) %>
+</head>
+<body>
+  <%= yield :body_content %>
+</body>
+</html>
+```
+
+**Note**: While this pattern may seem counter-intuitive (body content before `<!DOCTYPE html>`), it ensures proper stylesheet loading order and prevents FOUC.
+
+**Option 2: Disable auto_load_bundle and manually manage packs**
+
+If the `content_for` pattern doesn't fit your architecture, set `auto_load_bundle = false` and manually manage pack loading:
+
+```ruby
+# config/initializers/react_on_rails.rb
+config.auto_load_bundle = false
+```
+
+Then in your layout:
+
+```erb
+<head>
+  <%= stylesheet_pack_tag 'application' %>
+</head>
+<body>
+  <%= react_component "MyComponent", prerender: true %>
+</body>
+```
+
+**Option 3: HMR-related FOUC (Development Only)**
+
+With HMR (Hot Module Replacement) in development mode, FOUC is expected behavior due to dynamic CSS injection:
+
+- **Development with HMR** (`./bin/dev`): FOUC is expected - CSS is dynamically injected
+- **Development static** (`./bin/dev static`): No FOUC - CSS is extracted to separate files
 - **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';`
 
-**Key insight**: Choose your development mode based on your current needs:
+**Additional checks**:
 
-- Use HMR for fastest development (accept FOUC)
-- Use static mode when testing styling without FOUC
-- Use production mode for final testing
+- **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';`
 
 #### 3. "document is not defined" errors during SSR
 
