shakapacker 9.3.0.beta.5 → 9.3.0.beta.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9db05ecb02b4491f31eb4ec2374057933be5cf90a09b6dded781c036ff8e494e
-  data.tar.gz: a8f9b04812aff8a73275044f61a1ecbc096c5131a3bca69d5b75e292c1c31064
+  metadata.gz: 6d74b7ba9b6d6c78f1909339be00ce6d88a6d3f8e8cd64ada499992c3bf6691f
+  data.tar.gz: f51ffe665f554536b8defcf139399eb6f6630c61f427a4be9c88aebf14404b25
 SHA512:
-  metadata.gz: 88f63fdaaed2cfad42f000d97e08fec78dddaa24b304dd23ae515ba24b5b68845e33115adf13994f0a59f85b6be4003a442e8d5f88a1a9295484ca0b31e07fc1
-  data.tar.gz: 59069f26686a609a9df9994ec63a1cbc5905d18abbb7379c0460913f16ac58247e760d97eecc544a31a86e212d6af1d171b99f462f4b60b937d0da81d3415a7f
+  metadata.gz: 7fa1c2252b25cc3e265e6375561e0be38d1656604e6bf873eb1d6b25d41478bc48c530e8bcac3a05f6d09f7569f988a65cb52609564c87ea35f657bda3baed27
+  data.tar.gz: a322b6a94de55f7f8da67d54778e6f455726d4778576e5ff689e2874d68f58b8613260d683d93e019d48d44eeeb9a46a7094be12cb7dbaea76824e688350994a

data/CHANGELOG.md

@@ -13,6 +13,22 @@ Changes since the last non-beta release.
 
 ### Added
 
+- **`--help=verbose` flag support** to display all available webpack/rspack bundler options. [PR #763](https://github.com/shakacode/shakapacker/pull/763) by [justin808](https://github.com/justin808).
+  - Run `bin/shakapacker --help=verbose` to see complete bundler documentation
+  - Shows all webpack CLI options when using webpack
+  - Useful for discovering advanced bundler configuration options
+- **Support for arbitrary output names in build configurations**. [PR #752](https://github.com/shakacode/shakapacker/pull/752) by [justin808](https://github.com/justin808).
+  - `outputs` array now accepts any custom names (e.g., `client-modern`, `client-legacy`, `server-bundle`)
+  - Previously limited to only `client`, `server`, and `all`
+  - Enables better organization of multi-config webpack builds
+- **Enhanced error reporting in config exporter**. [PR #752](https://github.com/shakacode/shakapacker/pull/752) by [justin808](https://github.com/justin808).
+  - Shows detailed environment variable state when config functions fail
+  - Provides actionable suggestions based on error patterns (e.g., missing NODE_ENV)
+  - Improved formatting with clear sections for easier debugging
+- **Config count validation for build outputs**. [PR #752](https://github.com/shakacode/shakapacker/pull/752) by [justin808](https://github.com/justin808).
+  - Validates webpack/rspack config array length matches `outputs` array
+  - Clear error messages when mismatch detected
+  - Suggests fixes with example configuration
 - **HTTP 103 Early Hints support** for faster asset loading. [PR #722](https://github.com/shakacode/shakapacker/pull/722) by [justin808](https://github.com/justin808). Fixes [#721](https://github.com/shakacode/shakapacker/issues/721).
   - **Automatic sending**: Early hints are sent automatically when `early_hints: enabled: true` in `shakapacker.yml`
   - **Per-page configuration**: Configure hints per-controller/action with `preload`/`prefetch`/`none` options
@@ -31,7 +47,7 @@ Changes since the last non-beta release.
   - **Performance note**: May improve or hurt page load performance depending on content - careful testing advised
   - See [Early Hints Guide](docs/early_hints.md) for detailed usage and advanced patterns
 
-## [v9.3.0-beta.0] - October 13, 2025
+## [v9.3.0-beta.5] - October 18, 2025
 
 ### Added
 
@@ -53,6 +69,15 @@ Changes since the last non-beta release.
 - **Build timing logs** for webpack and rspack. [PR #706](https://github.com/shakacode/shakapacker/pull/706) by [justin808](https://github.com/justin808).
   - Shows duration of build operations
   - Helps identify performance bottlenecks
+- **Named build configurations with `--build` flag**. [PR #728](https://github.com/shakacode/shakapacker/pull/728) by [justin808](https://github.com/justin808).
+  - Allows specifying custom build configurations: `bin/shakapacker --build=production` or `bin/shakapacker --build=test`
+  - Useful for creating specialized build configurations for different deployment environments
+- **Build validation in `bin/export-bundler-config`**. [PR #717](https://github.com/shakacode/shakapacker/pull/717) by [justin808](https://github.com/justin808).
+  - Validates webpack/rspack configuration before export to catch errors early
+  - Provides clear error messages for configuration issues
+- **Backward compatibility for rspack config in `config/webpack/`**. [PR #734](https://github.com/shakacode/shakapacker/pull/734) by [justin808](https://github.com/justin808).
+  - Rspack configurations can now be placed in `config/webpack/` directory for easier migration
+  - Maintains compatibility with existing project structures
 - Added Knip for detecting dead code to CI. [PR #675](https://github.com/shakacode/shakapacker/pull/675) by [justin808](https://github.com/justin808).
 
 ### Changed
@@ -80,6 +105,12 @@ Changes since the last non-beta release.
 - **Improved doctor command output** clarity and accuracy. [PR #682](https://github.com/shakacode/shakapacker/pull/682) by [justin808](https://github.com/justin808).
   - Better formatting and organization of diagnostic information
   - More actionable recommendations
+- **Documented `content_for` pattern to prevent FOUC** with `stylesheet_pack_tag`. [PR #737](https://github.com/shakacode/shakapacker/pull/737) by [justin808](https://github.com/justin808).
+  - Added documentation on using `content_for` to prevent Flash of Unstyled Content
+  - Best practice patterns for managing stylesheet loading order
+- **Improved upgrade documentation** to clarify dual Gemfile and package.json updates. [PR #731](https://github.com/shakacode/shakapacker/pull/731) by [justin808](https://github.com/justin808).
+  - Clearer instructions for upgrading both Ruby gem and NPM package
+  - Helps prevent version mismatch issues
 - Formatted all markdown files with prettier. [PR #673](https://github.com/shakacode/shakapacker/pull/673) by [justin808](https://github.com/justin808).
 
 ### Fixed
@@ -752,8 +783,8 @@ Note: [Rubygem is 6.3.0.pre.rc.1](https://rubygems.org/gems/shakapacker/versions
 
 See [CHANGELOG.md in rails/webpacker (up to v5.4.3)](https://github.com/rails/webpacker/blob/master/CHANGELOG.md)
 
-[Unreleased]: https://github.com/shakacode/shakapacker/compare/v9.3.0-beta.0...main
-[v9.3.0-beta.0]: https://github.com/shakacode/shakapacker/compare/v9.2.0...v9.3.0-beta.0
+[Unreleased]: https://github.com/shakacode/shakapacker/compare/v9.3.0-beta.5...main
+[v9.3.0-beta.5]: https://github.com/shakacode/shakapacker/compare/v9.2.0...v9.3.0-beta.5
 [v9.2.0]: https://github.com/shakacode/shakapacker/compare/v9.1.0...v9.2.0
 [v9.1.0]: https://github.com/shakacode/shakapacker/compare/v9.0.0...v9.1.0
 [v9.0.0]: https://github.com/shakacode/shakapacker/compare/v8.4.0...v9.0.0

data/ESLINT_TECHNICAL_DEBT.md

@@ -6,7 +6,7 @@ This document tracks the ESLint errors currently suppressed in the codebase and
 
 **As of 2025-10-14**: All TypeScript files in `package/` directory are temporarily excluded from linting via the ignore pattern `package/**/*.ts` in `eslint.config.js`. This allows the project to adopt ESLint configuration without requiring immediate fixes to all existing issues.
 
-**Latest Update**: Fixed all `no-param-reassign` violations by refactoring to create new objects instead of mutating parameters (7 violations resolved).
+**Latest Update**: Auto-fixed 28 style violations in `package/configExporter/cli.ts` including unnecessary type assertions, string concatenation to template literals, and object destructuring (reduced from 77 to 49 errors).
 
 ## Current Linting Status
 
@@ -24,7 +24,7 @@ This document tracks the ESLint errors currently suppressed in the codebase and
   - Style/convention issues: ~49 (30%)
 
 **Target**: Reduce suppressed errors by 50% within Q1 2025
-**Last Updated**: 2025-10-15
+**Last Updated**: 2025-10-18
 
 ## Priority Matrix
 
@@ -115,6 +115,12 @@ This document tracks the ESLint errors currently suppressed in the codebase and
 - ✅ **Fixed `class-methods-use-this`** - Converted FileWriter methods to static methods
 - ✅ **Fixed `no-nested-ternary`** - Refactored to if-else statements for better readability
 - ✅ **Fixed `no-param-reassign`** - Refactored `applyDefaults` to return new objects instead of mutating parameters
+- ✅ **Auto-fixed style violations in cli.ts** (2025-10-18):
+  - Removed unnecessary type assertions (`@typescript-eslint/no-unnecessary-type-assertion`)
+  - Used object destructuring (`prefer-destructuring`)
+  - Converted string concatenation to template literals (`prefer-template`)
+  - Removed unused eslint-disable directives
+  - Fixed `no-else-return` violations
 
 🔧 Could still fix (low risk):
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    shakapacker (9.3.0.beta.5)
+    shakapacker (9.3.0.beta.7)
       activesupport (>= 5.2)
       package_json
       rack-proxy (>= 0.6.1)

data/docs/early_hints.md

@@ -2,6 +2,8 @@
 
 This guide shows you how to use HTTP 103 Early Hints with Shakapacker to optimize page load performance.
 
+> **📚 Related Documentation:** For advanced manual control using `send_pack_early_hints` in controllers before expensive work, see [early_hints_manual_api.md](early_hints_manual_api.md).
+
 ## What are Early Hints?
 
 HTTP 103 Early Hints is emitted **after** Rails has finished rendering but **before** the final response is sent, allowing browsers to begin fetching resources (JS, CSS) prior to receiving the full HTML response. This may significantly improve page load performance or cause an equally significant regression, depending on the page's content.
@@ -316,29 +318,13 @@ Shakapacker automatically sends early hints after your views render:
 
 ## Advanced: Manual Control
 
-Most apps should use controller configuration. Use manual control for view-specific logic:
-
-```erb
-<%# app/views/layouts/application.html.erb %>
-<% send_pack_early_hints css: 'prefetch', js: 'preload' %>
+Most apps should use controller configuration. For advanced use cases including:
 
-<!DOCTYPE html>
-<html>
-  <body>
-    <%= yield %>
-    <%= javascript_pack_tag 'application' %>
-  </body>
-</html>
-```
-
-**Per-tag override:**
-
-```erb
-<%= javascript_pack_tag 'application',
-    early_hints: { css: 'preload', js: 'prefetch' } %>
-```
+- Sending hints **before** expensive controller work for maximum parallelism
+- Per-pack customization in layouts
+- View-specific logic
 
-**Use cases:** Layout-specific optimizations, conditional hints based on view variables, A/B testing
+See the [Manual API Guide](early_hints_manual_api.md) for detailed examples and patterns.
 
 ## Requirements
 

data/docs/{early_hints_new_api.md → early_hints_manual_api.md}

@@ -1,4 +1,16 @@
-# HTTP 103 Early Hints - New API
+# HTTP 103 Early Hints - Manual API Guide
+
+> **📚 Main Documentation:** This guide covers the manual `send_pack_early_hints` API for advanced use cases. For the recommended controller-based API (`configure_pack_early_hints`, `skip_send_pack_early_hints`) and comprehensive setup instructions, see [early_hints.md](early_hints.md).
+
+This guide focuses on **manual control** of early hints for advanced scenarios where you need to send hints before expensive controller work or customize hints per-pack in layouts.
+
+## Automatic vs Manual API
+
+By default, Shakapacker automatically sends early hints when `javascript_pack_tag` and `stylesheet_pack_tag` are called (after views render). The manual API allows you to:
+
+- **Send hints earlier** - Before controller work starts, maximizing parallelism
+- **Customize per-pack** - Different strategies for different packs in the same layout
+- **Override automatic behavior** - When you need fine-grained control
 
 ## ⚠️ IMPORTANT: Performance Testing Required
 
@@ -14,73 +26,21 @@
 2. Measure Core Web Vitals (LCP, FCP, TTI) for both groups
 3. Only keep enabled if metrics improve
 
-See [Troubleshooting](#performance-got-worse) if early hints decrease performance.
-
----
-
-## Prerequisites
-
-Before implementing early hints, verify you have:
-
-1. **Puma 5+** with `--early-hints` flag (REQUIRED)
-2. **HTTP/2-capable proxy** in front of Puma:
-   - ✅ Thruster (Rails 8 default)
-   - ✅ nginx 1.13+
-   - ✅ Cloudflare (paid plans)
-   - ❌ Control Plane (strips 103 responses)
-   - ❌ AWS ALB/ELB (strips 103 responses)
-3. **Rails 5.2+** (for `request.send_early_hints` API)
-
-**Critical**: Puma requires the `--early-hints` flag to send HTTP 103:
-
-```bash
-# Procfile / Dockerfile
-web: bundle exec puma --early-hints -C config/puma.rb
-```
-
-Without this flag, early hints will NOT work. See [Setup](#production-setup) for details.
-
----
-
-## Quick Start
+See the [Feature Testing Guide](feature_testing.md#http-103-early-hints) for testing instructions and the [main documentation](early_hints.md) for comprehensive troubleshooting.
 
-### Pattern 1: Automatic (Default)
+## When to Use the Manual API
 
-By default, `javascript_pack_tag` and `stylesheet_pack_tag` automatically send early hints when early hints are enabled in config:
-
-```yaml
-# config/shakapacker.yml
-production:
-  early_hints:
-    enabled: true
-```
-
-```erb
-<%# app/views/layouts/application.html.erb %>
-<!DOCTYPE html>
-<html>
-  <head>
-    <%# Automatically sends early hints for application pack CSS %>
-    <%= stylesheet_pack_tag 'application' %>
-  </head>
-  <body>
-    <%= yield %>
-    <%# Automatically sends early hints for application pack JS %>
-    <%= javascript_pack_tag 'application' %>
-  </body>
-</html>
-```
+Use `send_pack_early_hints` when you need:
 
-**How it works:**
+1. **Maximum parallelism** - Send hints BEFORE expensive controller work (database queries, API calls)
+2. **Per-pack customization** - Different hint strategies for different packs in layouts
+3. **Dynamic control** - Runtime decisions about which packs to hint
 
-- When `stylesheet_pack_tag` is called, it automatically sends CSS early hints
-- When `javascript_pack_tag` is called, it automatically sends JS early hints
-- Combines queue (from `append_*_pack_tag`) + direct args
-- Default: `rel=preload` for all packs
+For most applications, use the [controller-based API](early_hints.md#controller-configuration) instead (`configure_pack_early_hints`, `skip_send_pack_early_hints`).
 
----
+## Manual API Patterns
 
-## Pattern 2: Per-Pack Customization in Layout
+### Pattern 1: Per-Pack Customization in Layout
 
 Customize hint handling per pack using a hash:
 
@@ -109,7 +69,7 @@ Customize hint handling per pack using a hash:
 
 ---
 
-## Pattern 3: Controller Override (Before Expensive Work)
+### Pattern 2: Controller Override (Before Expensive Work)
 
 Send hints manually in controller BEFORE expensive work to maximize parallelism:
 
@@ -148,7 +108,7 @@ end
 
 ---
 
-## Pattern 4: View Override
+### Pattern 3: View Override
 
 Views can use `append_*_pack_tag` to add packs dynamically:
 
@@ -188,13 +148,7 @@ Views can use `append_*_pack_tag` to add packs dynamically:
 
 ## Configuration
 
-```yaml
-# config/shakapacker.yml
-production:
-  early_hints:
-    enabled: true # Master switch (default: false)
-    debug: true # Show HTML comments with debug info (default: false)
-```
+> **📚 Configuration:** See the [main documentation](early_hints.md#quick-start) for all configuration options including global settings, priority levels (preload/prefetch/none), and per-controller configuration.
 
 ---
 
@@ -226,26 +180,20 @@ end
 
 ## When to Use Each Pattern
 
-### Pattern 1 (Automatic) - Best for:
-
-- Simple apps with consistent performance
-- Small/medium JS bundles (<500KB)
-- Fast controllers (<100ms)
-
-### Pattern 2 (Per-Pack) - Best for:
+### Pattern 1 (Per-Pack) - Best for:
 
 - Mixed vendor bundles (preload critical, prefetch non-critical)
 - Different handling for different packs
 - Layout-specific optimizations
 
-### Pattern 3 (Controller) - Best for:
+### Pattern 2 (Controller) - Best for:
 
 - Slow controllers with expensive queries (>300ms)
 - Large JS bundles (>500KB)
 - APIs calls in controller
 - Maximum parallelism needed
 
-### Pattern 4 (View Override) - Best for:
+### Pattern 3 (View Override) - Best for:
 
 - Admin sections with extra packs
 - Feature flags determining packs
@@ -259,11 +207,11 @@ end
 # app/controllers/posts_controller.rb
 class PostsController < ApplicationController
   def index
-    # Fast controller, use automatic hints
+    # Fast controller, automatic hints work fine (Pattern 1)
   end
 
   def show
-    # Slow controller, send hints early
+    # Slow controller, send hints early for parallelism (Pattern 2)
     send_pack_early_hints({
       "application" => { js: "preload", css: "preload" }
     })
@@ -277,6 +225,7 @@ end
 ```erb
 <%# app/views/posts/show.html.erb %>
 <% if current_user&.admin? %>
+  <%# Pattern 3: Dynamic pack loading based on user role %>
   <% append_javascript_pack_tag 'admin_tools' %>
 <% end %>
 ```
@@ -286,13 +235,12 @@ end
 <!DOCTYPE html>
 <html>
   <head>
-    <%# Automatic CSS hints for application %>
     <%= stylesheet_pack_tag 'application' %>
   </head>
   <body>
     <%= yield %>
 
-    <%# Automatic JS hints for application + admin_tools (if appended) %>
+    <%# Sends hints for application + admin_tools (if appended) %>
     <%# Won't duplicate hints already sent in controller %>
     <%= javascript_pack_tag 'application' %>
   </body>
@@ -303,7 +251,9 @@ end
 
 ## Preloading Non-Pack Assets (Images, Videos, Fonts)
 
-**Shakapacker's early hints are for pack assets (JS/CSS bundles).** For non-pack assets like hero images, videos, and fonts, you have two options:
+**Shakapacker's early hints are for pack assets (JS/CSS bundles).** For non-pack assets like hero images, videos, and fonts, you have two options.
+
+> **Note:** The [main documentation](early_hints.md#4-preloading-hero-images-and-videos) covers using Rails' built-in `preload_link_tag` for images and videos, which is simpler than the manual approach below.
 
 ### Option 1: Manual Early Hints (For LCP/Critical Assets)
 
@@ -379,7 +329,9 @@ Use Rails' `preload_link_tag` to add `<link rel="preload">` in the HTML:
 
 ## Requirements & Limitations
 
-**IMPORTANT:** Before implementing Early Hints, understand these limitations:
+> **📚 Full Requirements:** See the [main documentation](early_hints.md#requirements) for complete browser and server requirements. This section covers limitations specific to the manual API.
+
+**IMPORTANT:** Understand these limitations when using the manual API:
 
 ### Architecture: Proxy Required for HTTP/2
 
@@ -426,14 +378,10 @@ Browser (HTTP/2 103) ✅
 - Subsequent 103 responses are ignored by browsers
 - This is by design per the HTTP 103 spec
 
-### Browser Support
-
-- Chrome/Firefox 103+
-- Safari 16.4+
-- Gracefully degrades if not supported
-
 ### Testing Locally
 
+> **📚 Full Testing Guide:** See the [Feature Testing Guide](feature_testing.md#http-103-early-hints) for comprehensive testing instructions with browser DevTools and curl.
+
 **Step 1: Enable early hints in your test environment**
 
 ```yaml
@@ -478,223 +426,29 @@ curl -v http://localhost:3000/
 
 ### Production Setup
 
-#### Thruster (Rails 8+ Default)
-
-**Recommended**: Use [Thruster](https://github.com/basecamp/thruster) in front of Puma (Rails 8 default).
-
-Thruster handles HTTP/2 → HTTP/1.1 translation automatically. No configuration needed - Early Hints just work.
-
-```dockerfile
-# Dockerfile (Rails 8 default)
-CMD ["bundle", "exec", "thrust", "./bin/rails", "server"]
-```
-
-Thruster will:
-
-1. Receive HTTP/2 requests from browsers
-2. Translate to HTTP/1.1 for Puma
-3. Pass through HTTP/1.1 103 Early Hints from Puma
-4. Translate to HTTP/2 103 for browsers
-
-#### Control Plane
-
-**Status: Early Hints NOT supported** ❌
-
-Control Plane's load balancer appears to strip HTTP 103 responses, even with correct configuration:
-
-- Puma sends HTTP/1.1 103 ✅ (verified locally with curl)
-- Control Plane LB strips 103 before reaching browser ❌
-- Workload protocol set to `HTTP` (not `HTTP2`) ✅
-- Puma started with `--early-hints` flag ✅
-
-**Recommendation**: If you need early hints, consider:
-
-- **Thruster** (Rails 8 default, supports early hints)
-- **Self-hosted nginx** (supports early hints)
-- **Cloudflare** (paid plans only)
-- Contact Control Plane support to request early hints support
-
-#### nginx (Self-Hosted)
-
-If you want HTTP/2 in production with self-hosted nginx:
-
-```nginx
-# /etc/nginx/sites-available/myapp
-upstream puma {
-  server unix:///var/www/myapp/tmp/sockets/puma.sock;
-}
-
-server {
-  listen 443 ssl http2;
-  server_name example.com;
-
-  # SSL certificates
-  ssl_certificate /path/to/cert.pem;
-  ssl_certificate_key /path/to/key.pem;
-
-  location / {
-    proxy_pass http://puma;  # Puma uses HTTP/1.1
-    proxy_set_header Host $host;
-    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-    proxy_set_header X-Forwarded-Proto $scheme;
-
-    # CRITICAL: Pass through Early Hints from Puma
-    proxy_pass_header Link;
-  }
-}
-```
-
-nginx will:
+> **📚 Production Setup:** See the [main documentation](early_hints.md#requirements) for complete production setup instructions including Puma configuration, proxy setup (Thruster, nginx, Cloudflare), and troubleshooting proxy issues.
 
-1. Receive HTTP/2 request from browser
-2. Forward as HTTP/1.1 to Puma
-3. Receive HTTP/1.1 103 from Puma
-4. Translate to HTTP/2 103 for browser
+**Quick checklist:**
 
----
-
-## Troubleshooting
-
-### Early Hints Not Appearing
-
-**Step 1: Enable debug mode to see what Puma is sending**
-
-```yaml
-# config/shakapacker.yml
-development:
-  early_hints:
-    enabled: true
-    debug: true # Shows hints in HTML comments
-```
-
-Reload your page and check the HTML source for comments like:
-
-```html
-<!-- Early hints sent (JS): application=preload -->
-<!-- Early hints sent (CSS): application=preload -->
-```
-
-**If debug shows hints are sent:**
-
-The issue is with your **proxy/infrastructure**, not Shakapacker. Proceed to Step 2.
-
-**If debug shows NO hints sent:**
-
-Check your config:
-
-- `early_hints.enabled: true` in `config/shakapacker.yml`
+- Puma 5+ with `--early-hints` flag (REQUIRED)
+- HTTP/2-capable proxy (Thruster ✅, nginx ✅, Cloudflare ✅, Control Plane ❌, AWS ALB ❌)
 - Rails 5.2+
-- Puma 5+
-- **Puma started with `--early-hints` flag** (REQUIRED!)
-
----
-
-**Step 2: Check if your proxy is stripping 103 responses**
-
-This is the **most common cause** of missing early hints.
-
-Test with curl against your local Puma (HTTP/1.1):
-
-```bash
-# Direct to Puma (should work)
-curl -v http://localhost:3000/
-
-# Look for:
-< HTTP/1.1 103 Early Hints
-< link: </packs/application.js>; rel=preload; as=script
-<
-< HTTP/1.1 200 OK
-```
-
-If you see the 103 response, Puma is working correctly.
-
----
-
-**Step 3: Common proxy issues**
-
-#### Control Plane
-
-**Status: NOT supported** ❌
-
-Control Plane strips HTTP 103 responses. No known workaround. Consider switching to Thruster, nginx, or Cloudflare if you need early hints.
-
-#### AWS ALB/ELB
-
-**Not supported** - ALBs strip 103 responses entirely. No workaround except:
-
-- Skip ALB (not recommended)
-- Use CloudFront in front (CloudFront supports early hints)
-
-#### Cloudflare
-
-Enable "Early Hints" in dashboard:
-
-```
-Speed > Optimization > Early Hints: ON
-```
-
-**Note:** Paid plans only (Pro/Business/Enterprise).
-
-#### nginx
-
-nginx 1.13+ passes 103 responses automatically. Ensure you're using HTTP/2:
-
-```nginx
-server {
-  listen 443 ssl http2;  # Enable HTTP/2
-
-  location / {
-    proxy_pass http://puma;  # Puma uses HTTP/1.1
-    proxy_http_version 1.1;  # Required for Puma
-  }
-}
-```
-
-No special configuration needed - nginx automatically translates HTTP/1.1 103 to HTTP/2 103.
-
-#### Thruster (Rails 8+)
-
-Thruster handles HTTP/2 → HTTP/1.1 translation automatically. Early hints just work. No configuration needed.
 
 ---
 
-### Debugging Checklist
-
-1. ✅ **Config enabled:** `early_hints.enabled: true` in `shakapacker.yml`
-2. ✅ **Puma `--early-hints` flag:** Puma started with this flag (REQUIRED!)
-3. ✅ **Debug mode on:** See HTML comments confirming hints sent
-4. ✅ **Puma 5+:** Early hints require Puma 5+
-5. ✅ **Rails 5.2+:** `request.send_early_hints` API available
-6. ✅ **Architecture:** Proxy in front of Puma (Thruster, nginx - NOT Control Plane or AWS ALB)
-7. ✅ **Puma protocol:** Always HTTP/1.1 (never HTTP/2)
-8. ✅ **Proxy protocol:** HTTP/2 to browser, HTTP/1.1 to Puma
-9. ✅ **Browser support:** Chrome 103+, Firefox 103+, Safari 16.4+
-
----
-
-### Performance Got Worse?
-
-If enabling early hints **decreased** performance:
-
-**Likely cause:** Page has large images/videos as LCP (Largest Contentful Paint).
+## Troubleshooting
 
-Preloading large JS bundles can delay image downloads, hurting LCP.
+> **📚 Complete Troubleshooting:** See the [main documentation](early_hints.md#troubleshooting) for comprehensive troubleshooting including debug mode, proxy configuration, and performance optimization.
 
-**Fix:**
+Quick debugging steps:
 
-```yaml
-# config/shakapacker.yml
-production:
-  early_hints:
-    enabled: true
-    css: "prefetch" # Lower priority
-    js: "prefetch" # Lower priority
-```
-
-Or disable entirely and use HTML `preload_link_tag` for images instead.
-
----
+1. Enable `debug: true` in shakapacker.yml to see hints in HTML comments
+2. Verify Puma started with `--early-hints` flag
+3. Test with `curl -v http://localhost:3000/` to see if Puma sends 103 responses
+4. Check if your proxy strips 103 responses (Control Plane ❌, AWS ALB ❌)
 
 ### Reference
 
+- [Main Early Hints Documentation](early_hints.md)
+- [Feature Testing Guide](feature_testing.md#http-103-early-hints)
 - [Rails 103 Early Hints Analysis](https://island94.org/2025/10/rails-103-early-hints-could-be-better-maybe-doesn-t-matter)