shakapacker 9.3.0.beta.4 → 9.3.0.beta.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f2fafddfa10d364b8e62946786c16d9206ecffadf82b719e3ffeb2100608da0
-  data.tar.gz: 0e0cdc08d53e64e8066d7232aba1022b6a7708067d56ff7ba738803bfbc49a78
+  metadata.gz: 9db05ecb02b4491f31eb4ec2374057933be5cf90a09b6dded781c036ff8e494e
+  data.tar.gz: a8f9b04812aff8a73275044f61a1ecbc096c5131a3bca69d5b75e292c1c31064
 SHA512:
-  metadata.gz: dcbb4604f956d78acaea611bb760ecea97a1afcc15bc390b9c5a64c5d9654f5d08e83c57ed24da55aca0a1a98da074a0047a754cadf5f74ee8ba832fb6e93b3e
-  data.tar.gz: 47b7d7887f770f5712b5f020afd260fcefcb4b09a0c707e1b2bc921c38d2944bf6045b6b9752295790806018d98cd95d43313f9079719bcb3c808ff9f6e6c2ad
+  metadata.gz: 88f63fdaaed2cfad42f000d97e08fec78dddaa24b304dd23ae515ba24b5b68845e33115adf13994f0a59f85b6be4003a442e8d5f88a1a9295484ca0b31e07fc1
+  data.tar.gz: 59069f26686a609a9df9994ec63a1cbc5905d18abbb7379c0460913f16ac58247e760d97eecc544a31a86e212d6af1d171b99f462f4b60b937d0da81d3415a7f

data/CHANGELOG.md

@@ -11,6 +11,26 @@
 
 Changes since the last non-beta release.
 
+### Added
+
+- **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.0] - October 13, 2025
 
 ### Added

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.5)
       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,440 @@
+# HTTP 103 Early Hints Guide
+
+This guide shows you how to use HTTP 103 Early Hints with Shakapacker to optimize page load performance.
+
+## 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. Use manual control for view-specific logic:
+
+```erb
+<%# app/views/layouts/application.html.erb %>
+<% send_pack_early_hints css: 'prefetch', js: 'preload' %>
+
+<!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' } %>
+```
+
+**Use cases:** Layout-specific optimizations, conditional hints based on view variables, A/B testing
+
+## 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)