shakapacker 9.3.0.beta.4 → 9.3.0.beta.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f2fafddfa10d364b8e62946786c16d9206ecffadf82b719e3ffeb2100608da0
-  data.tar.gz: 0e0cdc08d53e64e8066d7232aba1022b6a7708067d56ff7ba738803bfbc49a78
+  metadata.gz: 9b7929f32b14b49a2fde4893b66809a37147796c685be9161c12631369105624
+  data.tar.gz: 2601ae85b072d8286700558a5d92f424d6e5989f7e4d990caf2b57c939b1962c
 SHA512:
-  metadata.gz: dcbb4604f956d78acaea611bb760ecea97a1afcc15bc390b9c5a64c5d9654f5d08e83c57ed24da55aca0a1a98da074a0047a754cadf5f74ee8ba832fb6e93b3e
-  data.tar.gz: 47b7d7887f770f5712b5f020afd260fcefcb4b09a0c707e1b2bc921c38d2944bf6045b6b9752295790806018d98cd95d43313f9079719bcb3c808ff9f6e6c2ad
+  metadata.gz: 9459cd0ec016ad83df86dec2ae879be51d1dc0dbd74fa9047b401ea0c0cb5d264438e43445487974d94bb4c82db5d5116ed9b3f5c3219e0d1f74cea65c7b46bc
+  data.tar.gz: 2f77e883a93ff0c80a2f22871d53646b16d94e1ffa648af78f167b699431cd026e8e9c5707a3379d57fd22e588ad7e526673afb324f4997cff5924bb5f2dceef

data/CHANGELOG.md

@@ -11,7 +11,39 @@
 
 Changes since the last non-beta release.
 
-## [v9.3.0-beta.0] - October 13, 2025
+### Added
+
+- **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
+  - **Hero image/video preloading**: Use Rails' built-in `preload_link_tag` (automatically sends early hints)
+  - **Zero-config upgrade**: No changes to layouts or views needed - just enable the config!
+  - Works seamlessly with existing `append_javascript_pack_tag` / `append_stylesheet_pack_tag` pattern
+  - Automatically discovers packs from queues populated by views/partials
+  - New `configure_pack_early_hints` class method for controller-level configuration
+  - New `skip_send_pack_early_hints` helper to opt-out for specific controllers (e.g., JSON APIs)
+  - Optional manual control: `configure_early_hints` can be called in controllers or views
+  - Added `early_hints:` option to `javascript_pack_tag` for per-tag control
+  - New `early_hints` configuration in `shakapacker.yml` with per-environment settings (`enabled: false` by default)
+  - Requires Rails 5.2+ and HTTP/2-capable server (e.g., Puma 5+)
+  - Browser support: All modern browsers (Chrome/Edge/Firefox 103+, Safari 16.4+)
+  - Gracefully degrades if not supported
+  - **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.5] - October 18, 2025
 
 ### Added
 
@@ -33,6 +65,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
@@ -60,6 +101,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
@@ -732,8 +779,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/CLAUDE.md

@@ -27,6 +27,19 @@
 - Create small, focused PRs that are easy to review
 - Always create a PR immediately after pushing changes
 
+## Changelog
+
+- **Update CHANGELOG.md for user-visible changes only**
+- User-visible changes include: new features, bug fixes, breaking changes, deprecations, performance improvements
+- **Do NOT add changelog entries for**: linting fixes, code formatting, internal refactoring, test updates, documentation fixes
+- Non-user-visible changes don't need changelog entries even if they modify code
+- **Format requirements**:
+  - Always link to the PR: `[PR #123](https://github.com/shakacode/shakapacker/pull/123)`
+  - Always link to the author: `by [username](https://github.com/username)`
+  - Keep formatting consistent with existing entries
+  - When releasing a version, update the version diff links at the bottom of CHANGELOG.md
+  - **For breaking changes**: Use bold formatting and link to migration documentation (e.g., `**Breaking**: Description. See [Migration Guide](docs/vX_upgrade.md)`)
+
 ## Shakapacker-Specific
 
 - This gem supports both webpack and rspack configurations

data/Gemfile.lock

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

data/README.md

@@ -78,6 +78,7 @@ Read the [full review here](https://clutch.co/profile/shakacode#reviews?sort_by=
     - [View Helper: `image_pack_tag`](#view-helper-image_pack_tag)
     - [View Helper: `favicon_pack_tag`](#view-helper-favicon_pack_tag)
     - [View Helper: `preload_pack_asset`](#view-helper-preload_pack_asset)
+    - [View Helper: `send_pack_early_hints`](#view-helper-send_pack_early_hints)
   - [Images in Stylesheets](#images-in-stylesheets)
   - [Server-Side Rendering (SSR)](#server-side-rendering-ssr)
   - [Development](#development)
@@ -563,6 +564,24 @@ If you want to preload a static asset in your `<head>`, you can use the `preload
 <%= preload_pack_asset 'fonts/fa-regular-400.woff2' %>
 ```
 
+#### HTTP 103 Early Hints
+
+Automatically send early hints to browsers for faster asset loading. Supports `preload`/`prefetch`/`none` configuration per-page.
+
+```yaml
+# config/shakapacker.yml
+production:
+  early_hints:
+    enabled: true
+    debug: false # Enable to see what hints are sent (as HTML comments)
+```
+
+⚠️ **Important**: May improve or hurt performance depending on content. See the [Early Hints Guide](./docs/early_hints.md) for configuration, performance guidance, and examples.
+
+**Troubleshooting**: Enable `debug: true` to see HTML comments showing what hints were sent or why they were skipped.
+
+**Requirements:** Rails 5.2+, HTTP/2 server, modern browsers. Gracefully degrades if not supported.
+
 ### Images in Stylesheets
 
 If you want to use images in your stylesheets:

data/docs/configuration.md

@@ -11,6 +11,8 @@ This guide covers all configuration options available in `config/shakapacker.yml
 - [Development Server](#development-server)
 - [Compilation Options](#compilation-options)
 - [Advanced Options](#advanced-options)
+  - [Subresource Integrity](#integrity)
+  - [Early Hints](#early_hints)
 - [Environment-Specific Configuration](#environment-specific-configuration)
 - [Build Configurations (config/shakapacker-builds.yml)](#build-configurations-configshakapacker-buildsyml)
 
@@ -485,6 +487,37 @@ integrity:
 
 See [Subresource Integrity Guide](subresource_integrity.md) for details.
 
+### `early_hints`
+
+**Type:** `object`
+**Default:** `{ enabled: false, css: "preload", js: "preload" }`
+**Requires:** Rails 5.2+, HTTP/2 server
+
+Automatically send HTTP 103 Early Hints for faster asset loading.
+
+```yaml
+early_hints:
+  enabled: true # Master switch (default: false)
+  css: "preload" # 'preload' | 'prefetch' | 'none' (default: 'preload')
+  js: "preload" # 'preload' | 'prefetch' | 'none' (default: 'preload')
+```
+
+**Options:**
+
+- `enabled`: Enable/disable early hints (default: `false`)
+- `css`: Hint type for CSS - `'preload'`, `'prefetch'`, or `'none'` (default: `'preload'`)
+- `js`: Hint type for JS - `'preload'`, `'prefetch'`, or `'none'` (default: `'preload'`)
+
+⚠️ **Performance note**: May improve or hurt page load depending on content. Configure per-page for best results.
+
+See the [Early Hints Guide](early_hints.md) for:
+
+- Performance considerations and warnings
+- Per-page configuration (`configure_pack_early_hints`)
+- Dynamic configuration examples
+- Hero image preloading with `preload_link_tag`
+- Troubleshooting and testing recommendations
+
 ## Environment-Specific Configuration
 
 Shakapacker supports per-environment configuration with fallback logic:
@@ -728,4 +761,6 @@ See [Troubleshooting Guide](troubleshooting.md) for more help.
 - [Deployment Guide](deployment.md)
 - [CDN Setup Guide](cdn_setup.md)
 - [Precompile Hook Guide](precompile_hook.md)
+- [Early Hints Guide](early_hints.md)
+- [Subresource Integrity Guide](subresource_integrity.md)
 - [Troubleshooting Guide](troubleshooting.md)

data/docs/early_hints.md

@@ -0,0 +1,426 @@
+# HTTP 103 Early Hints Guide
+
+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.
+
+⚠️ **Critical**: Preloading JavaScript may hurt your LCP (Largest Contentful Paint) metric if you have large images, videos, or other content that should load first. **Careful experimentation and performance measurement is required.**
+
+### Priority Levels: Preload vs Prefetch vs None
+
+Early hints let you control browser download priority for assets:
+
+- **`preload`** - **Prioritize**: High priority, browser downloads immediately before HTML parsing. Use for critical assets needed for initial render.
+- **`prefetch`** - **De-prioritize**: Low priority, browser downloads when idle (doesn't compete for bandwidth). Use for non-critical assets or future navigation.
+- **`none`** - **Default behavior**: No hint sent. Browser discovers asset when parsing HTML (normal page load behavior).
+
+### Performance Considerations
+
+⚠️ **Important**: Different pages have different performance characteristics:
+
+- **LCP Impact**: Preloading JS/CSS competes for bandwidth with images/videos, potentially delaying LCP
+- **Hero Images**: Pages with large hero images usually perform **worse** with JS/CSS preload
+- **Interactive Apps**: Dashboards and SPAs may benefit from aggressive JS preload
+- **Content Sites**: Blogs and marketing sites often need conservative hints (prefetch or none)
+- **Recommendation**: Configure hints **per-page** based on content, measure with real user data
+
+## Quick Start
+
+### 1. Global Configuration
+
+```yaml
+# config/shakapacker.yml
+production:
+  early_hints:
+    enabled: true # Master switch
+    css: "preload" # 'preload' | 'prefetch' | 'none'
+    js: "preload" # 'preload' | 'prefetch' | 'none'
+```
+
+**Defaults**: When `enabled: true`, both `css` and `js` default to `'preload'` if not specified.
+
+**Testing**: See the [Feature Testing Guide](feature_testing.md#http-103-early-hints) for detailed instructions on verifying early hints are working using browser DevTools or curl.
+
+### 2. Per-Page Configuration (Recommended)
+
+Configure hints based on your page content:
+
+```ruby
+class PostsController < ApplicationController
+  # Image-heavy landing page - don't compete with images
+  configure_pack_early_hints only: [:index], css: 'none', js: 'prefetch'
+
+  # Interactive post editor - JS is critical
+  configure_pack_early_hints only: [:edit], css: 'preload', js: 'preload'
+
+  # API endpoints - no hints needed
+  skip_send_pack_early_hints only: [:api_data]
+end
+```
+
+### 3. Dynamic Configuration
+
+Configure based on content:
+
+```ruby
+class PostsController < ApplicationController
+  def show
+    @post = Post.find(params[:id])
+
+    if @post.has_hero_video?
+      # Video is LCP - don't compete
+      configure_pack_early_hints all: 'none'
+    elsif @post.interactive?
+      # JS needed for interactivity
+      configure_pack_early_hints css: 'prefetch', js: 'preload'
+    else
+      # Standard blog post
+      configure_pack_early_hints css: 'preload', js: 'prefetch'
+    end
+  end
+end
+```
+
+### 4. Preloading Hero Images and Videos
+
+Use Rails' built-in `preload_link_tag` to preload hero images, videos, and other LCP resources. Rails automatically sends these as early hints:
+
+```erb
+<%# app/views/layouts/application.html.erb %>
+<!DOCTYPE html>
+<html>
+  <head>
+    <%= preload_link_tag image_path('hero.jpg'), as: 'image', type: 'image/jpeg' %>
+    <%= preload_link_tag video_path('intro.mp4'), as: 'video', type: 'video/mp4' %>
+  </head>
+  <body>
+    <%= yield %>
+  </body>
+</html>
+```
+
+**Dynamic preloading in views:**
+
+```erb
+<%# app/views/posts/show.html.erb %>
+<% if @post.hero_image_url.present? %>
+  <%= preload_link_tag @post.hero_image_url, as: 'image' %>
+<% end %>
+```
+
+**Benefits:**
+
+- ✅ Standard Rails API - no custom Shakapacker code needed
+- ✅ Automatically sends early hints when server supports it
+- ✅ Works with `image_path`, `video_path`, `asset_path` helpers
+- ✅ Supports all standard attributes: `as`, `type`, `crossorigin`, `integrity`
+
+**When to preload images/videos:**
+
+- Hero images that are LCP (Largest Contentful Paint) elements
+- Above-the-fold images critical for initial render
+- Background videos that play on page load
+
+**Performance tip:** Don't over-preload! Each preload competes for bandwidth. Focus only on critical resources that improve LCP.
+
+See [Rails preload_link_tag docs](https://api.rubyonrails.org/classes/ActionView/Helpers/AssetTagHelper.html#method-i-preload_link_tag) for full API.
+
+## Controller Configuration
+
+#### Skip Early Hints Entirely
+
+```ruby
+class ApiController < ApplicationController
+  # Skip for entire controller
+  skip_send_pack_early_hints
+end
+
+class PostsController < ApplicationController
+  # Skip for specific actions
+  skip_send_pack_early_hints only: [:api_endpoint, :feed]
+end
+```
+
+#### Configure Per Action (Class Method)
+
+```ruby
+class PostsController < ApplicationController
+  # Configure specific actions
+  configure_pack_early_hints only: [:show], css: 'prefetch', js: 'preload'
+  configure_pack_early_hints only: [:gallery], css: 'none', js: 'none'
+
+  # Use 'all' shortcut
+  configure_pack_early_hints only: [:about], all: 'prefetch'
+
+  # Mix general and specific (specific wins)
+  configure_pack_early_hints only: [:dashboard], all: 'preload', css: 'prefetch'
+  # Result: css='prefetch', js='preload'
+end
+```
+
+#### Configure in Action Method
+
+```ruby
+class PostsController < ApplicationController
+  def show
+    @post = Post.find(params[:id])
+
+    # Configure based on runtime logic
+    if @post.video_content?
+      configure_pack_early_hints css: 'none', js: 'none'
+    end
+  end
+end
+```
+
+#### Configure in Before Action
+
+```ruby
+class PostsController < ApplicationController
+  before_action :optimize_for_images, only: [:gallery, :portfolio]
+
+  private
+
+  def optimize_for_images
+    configure_pack_early_hints css: 'prefetch', js: 'prefetch'
+  end
+end
+```
+
+## Configuration Precedence
+
+Settings are applied in this order (later overrides earlier):
+
+1. **Global** (shakapacker.yml) - project defaults
+2. **Controller class** (configure_pack_early_hints) - per-action defaults
+3. **Manual call** (send_pack_early_hints in view) - explicit override
+
+Within a single configuration, `all:` is applied first, then specific `css:` and `js:` values override it.
+
+## Usage Examples by Scenario
+
+### Scenario 1: Image-Heavy Landing Page
+
+**Problem**: Large hero image is LCP, JS/CSS hints compete for bandwidth and delay image loading
+
+```ruby
+class HomeController < ApplicationController
+  def index
+    # Save bandwidth for hero image
+    configure_pack_early_hints css: 'none', js: 'prefetch'
+  end
+end
+```
+
+**Why**:
+
+- `css: 'none'` - No hint sent, CSS discovered normally (saves bandwidth)
+- `js: 'prefetch'` - Low priority hint, JS downloads when idle (doesn't compete)
+- **Result**: Hero image gets full bandwidth priority for better LCP
+
+### Scenario 2: Interactive Dashboard
+
+**Problem**: App is useless without JavaScript
+
+```ruby
+class DashboardController < ApplicationController
+  # JS is critical for all actions
+  configure_pack_early_hints all: 'preload'
+end
+```
+
+**Why**: Fast JS load is more important than LCP
+
+### Scenario 3: Blog with Varied Content
+
+**Problem**: Article pages have images, index doesn't
+
+```ruby
+class ArticlesController < ApplicationController
+  # Index: no large images
+  configure_pack_early_hints only: [:index], css: 'preload', js: 'preload'
+
+  # Show: featured images
+  configure_pack_early_hints only: [:show], css: 'prefetch', js: 'prefetch'
+end
+```
+
+**Why**: Different pages have different performance needs
+
+### Scenario 4: Mixed Content Types
+
+**Problem**: Posts contain videos, images, or interactive content
+
+```ruby
+class PostsController < ApplicationController
+  def show
+    @post = Post.find(params[:id])
+
+    case @post.content_type
+    when 'video'
+      # Video is LCP
+      configure_pack_early_hints all: 'none'
+    when 'interactive'
+      # JS needed immediately
+      configure_pack_early_hints css: 'prefetch', js: 'preload'
+    when 'image_gallery'
+      # Images are LCP
+      configure_pack_early_hints all: 'prefetch'
+    else
+      # Standard text post
+      configure_pack_early_hints css: 'preload', js: 'prefetch'
+    end
+  end
+end
+```
+
+**Why**: Dynamic configuration based on actual content
+
+### Scenario 5: E-commerce Product Pages
+
+**Problem**: Product images are critical, but checkout needs JS
+
+```ruby
+class ProductsController < ApplicationController
+  # Product page: images are critical
+  configure_pack_early_hints only: [:show], css: 'prefetch', js: 'prefetch'
+
+  # Checkout: form validation needs JS
+  configure_pack_early_hints only: [:checkout], css: 'preload', js: 'preload'
+end
+```
+
+**Why**: Shopping vs checkout have different needs
+
+## How It Works
+
+Shakapacker automatically sends early hints after your views render:
+
+```text
+1. Request arrives
+2. Controller action runs      → Database queries, business logic
+3. Views render               → append_javascript_pack_tag('admin')
+4. Layout renders             → javascript_pack_tag, stylesheet_pack_tag
+5. after_action hook          → Reads configuration and queues
+6. HTTP 103 sent              → rel=preload or rel=prefetch based on config
+7. HTTP 200 sent              → Full HTML response
+```
+
+**Important timing note**: HTTP 103 is sent after rendering completes but before the final HTTP 200 response. This means:
+
+- ✅ **Benefits**: Browser starts downloading assets while the server transmits the final HTML response
+- ❌ **Limitations**: Does NOT help during database queries or view rendering—only helps with network transfer time
+- 💡 **Best for**: Pages with large HTML responses where asset downloads can happen in parallel with HTML transmission
+
+## Advanced: Manual Control
+
+Most apps should use controller configuration. For advanced use cases including:
+
+- Sending hints **before** expensive controller work for maximum parallelism
+- Per-pack customization in layouts
+- View-specific logic
+
+See the [Manual API Guide](early_hints_manual_api.md) for detailed examples and patterns.
+
+## Requirements
+
+- **Rails 5.2+** (for `request.send_early_hints` support)
+- **Web server with HTTP/2 and early hints:**
+  - Puma 5+ ✅
+  - nginx 1.13+ with ngx_http_v2_module ✅
+  - Other HTTP/2 servers with early hints support
+- **Modern browsers:**
+  - Chrome/Edge/Firefox 103+ ✅
+  - Safari 16.4+ ✅
+
+If requirements not met, feature gracefully degrades with no errors.
+
+## Quick Reference
+
+### Priority levels and when to use each:
+
+- **`preload`** (Prioritize): Critical assets on text-heavy pages, SPAs, pages without large images
+- **`prefetch`** (De-prioritize): Non-critical assets, pages with large LCP images/videos (downloads when idle)
+- **`none`** (Default behavior): Image/video-heavy pages, API endpoints, SSR pages (no hint sent)
+
+### Testing checklist:
+
+1. Measure LCP with Chrome DevTools Performance tab
+2. Test on real mobile devices
+3. A/B test configurations with real user data
+4. Monitor field data with RUM tools
+5. Test each page type separately
+
+## Troubleshooting
+
+For comprehensive testing instructions including browser DevTools and curl methods, see the [Feature Testing Guide: HTTP 103 Early Hints](feature_testing.md#http-103-early-hints).
+
+### Debug Mode
+
+Enable debug mode to see what early hints are being sent (or why they weren't sent):
+
+```yaml
+# config/shakapacker.yml
+production:
+  early_hints:
+    enabled: true
+    debug: true # Outputs debug info as HTML comments
+```
+
+Debug mode adds HTML comments to your page showing:
+
+- Whether hints were sent or skipped
+- What pack names were processed
+- What Link headers were sent
+- HTTP/2 support status
+
+View page source and look for `<!-- Shakapacker Early Hints Debug -->` comments.
+
+**Early hints not appearing:**
+
+- **Enable debug mode first** to see what's happening
+- **Check for proxy stripping**: If debug shows hints sent but curl/DevTools don't show `HTTP/2 103`, your reverse proxy or CDN (Control Plane, Cloudflare, AWS ALB/ELB, nginx) is likely stripping 103 responses. This is the **most common cause** of "missing" early hints
+- Check `early_hints: enabled: true` in shakapacker.yml
+- Verify HTTP/2 server (Puma 5+, nginx 1.13+)
+- Check Network tab shows "h2" protocol and 103 status
+
+**Reverse proxy stripping 103 responses:**
+
+If debug mode shows hints are sent but they're not reaching clients, configure your proxy:
+
+- **nginx**: Add `proxy_pass_header Link;` to pass through early hints (nginx 1.13+)
+- **Cloudflare**: Enable "Early Hints" in Speed > Optimization (paid plans only)
+- **AWS ALB/ELB**: Not supported - ALBs strip 103 responses. Workaround: skip ALB or use CloudFront
+- **Control Plane**: Appears to strip 103 - Contact their support if you need early hints
+
+See the [Feature Testing Guide](feature_testing.md#troubleshooting-early-hints) for detailed proxy configuration examples.
+
+**Performance got worse:**
+
+- Page likely has large images/videos as LCP
+- Try `css: 'prefetch', js: 'prefetch'` or `all: 'none'`
+- Measure LCP before and after changes
+
+**Wrong hints sent:**
+
+- Check configuration precedence (global → controller → manual)
+- Verify values are strings: `'preload'` not `:preload`
+- Check for typos (case-sensitive)
+
+## References
+
+### Shakapacker Documentation
+
+- [Feature Testing Guide: HTTP 103 Early Hints](feature_testing.md#http-103-early-hints) - Detailed testing instructions with browser DevTools and curl
+
+### External Resources
+
+- [Rails API: send_early_hints](https://api.rubyonrails.org/classes/ActionDispatch/Request.html#method-i-send_early_hints)
+- [RFC 8297: HTTP Early Hints](https://datatracker.ietf.org/doc/html/rfc8297)
+- [MDN: rel=preload vs rel=prefetch](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel)
+- [Web.dev: Optimize LCP](https://web.dev/optimize-lcp/)
+- [HTTP 103 Explained](https://http.dev/103)