shakapacker 9.3.0.beta.5 → 9.3.0.beta.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9db05ecb02b4491f31eb4ec2374057933be5cf90a09b6dded781c036ff8e494e
-  data.tar.gz: a8f9b04812aff8a73275044f61a1ecbc096c5131a3bca69d5b75e292c1c31064
+  metadata.gz: 9b7929f32b14b49a2fde4893b66809a37147796c685be9161c12631369105624
+  data.tar.gz: 2601ae85b072d8286700558a5d92f424d6e5989f7e4d990caf2b57c939b1962c
 SHA512:
-  metadata.gz: 88f63fdaaed2cfad42f000d97e08fec78dddaa24b304dd23ae515ba24b5b68845e33115adf13994f0a59f85b6be4003a442e8d5f88a1a9295484ca0b31e07fc1
-  data.tar.gz: 59069f26686a609a9df9994ec63a1cbc5905d18abbb7379c0460913f16ac58247e760d97eecc544a31a86e212d6af1d171b99f462f4b60b937d0da81d3415a7f
+  metadata.gz: 9459cd0ec016ad83df86dec2ae879be51d1dc0dbd74fa9047b401ea0c0cb5d264438e43445487974d94bb4c82db5d5116ed9b3f5c3219e0d1f74cea65c7b46bc
+  data.tar.gz: 2f77e883a93ff0c80a2f22871d53646b16d94e1ffa648af78f167b699431cd026e8e9c5707a3379d57fd22e588ad7e526673afb324f4997cff5924bb5f2dceef

data/CHANGELOG.md

@@ -13,6 +13,18 @@ Changes since the last non-beta release.
 
 ### 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
@@ -31,7 +43,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 +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
@@ -80,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
@@ -752,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/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    shakapacker (9.3.0.beta.5)
+    shakapacker (9.3.0.beta.6)
       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)

data/lib/shakapacker/version.rb

@@ -1,4 +1,4 @@
 module Shakapacker
   # Change the version in package.json too, please!
-  VERSION = "9.3.0.beta.5".freeze
+  VERSION = "9.3.0.beta.6".freeze
 end

data/package/configExporter/cli.ts

@@ -596,6 +596,9 @@ async function runValidateCommand(options: ExportOptions): Promise<number> {
       clearBuildEnvironmentVariables()
       restoreBuildEnvironmentVariables(savedEnv)
 
+      // Clear shakapacker config cache between builds
+      shakapackerConfigCache = null
+
       // Get the build's environment to use for auto-detection
       const buildConfig = config.builds[buildName]
       const buildEnv =
@@ -692,6 +695,9 @@ async function runAllBuildsCommand(options: ExportOptions): Promise<number> {
       clearBuildEnvironmentVariables()
       restoreBuildEnvironmentVariables(savedEnv)
 
+      // Clear shakapacker config cache between builds
+      shakapackerConfigCache = null
+
       // Create a modified options object for this build
       const buildOptions = { ...resolvedOptions, build: buildName }
       const configs = await loadConfigsForEnv(undefined, buildOptions, appRoot)
@@ -770,6 +776,9 @@ async function runDoctorMode(
           clearBuildEnvironmentVariables()
           restoreBuildEnvironmentVariables(savedEnv)
 
+          // Clear shakapacker config cache between builds
+          shakapackerConfigCache = null
+
           const configs = await loadConfigsForEnv(
             undefined,
             { ...options, build: buildName },
@@ -798,9 +807,13 @@ async function runDoctorMode(
         // If config file exists but is invalid, show error and exit
         const errorMessage =
           error instanceof Error ? error.message : String(error)
-        console.error(`\n❌ Config file found but invalid: ${errorMessage}`)
+        console.error(`\n❌ Error loading build configuration:`)
+        console.error(`\n${errorMessage}`)
+        console.error(
+          `\n💡 To fix this issue, check your build config in ${configFilePath}`
+        )
         console.error(
-          `Fix the config file or run: bin/shakapacker-config --init\n`
+          `   or run: bin/shakapacker-config --init to regenerate it.\n`
         )
         throw error
       }
@@ -825,6 +838,9 @@ async function runDoctorMode(
       clearBuildEnvironmentVariables()
       restoreBuildEnvironmentVariables(savedEnv)
 
+      // Clear shakapacker config cache between builds
+      shakapackerConfigCache = null
+
       // Set WEBPACK_SERVE for HMR config
       if (hmr) {
         process.env.WEBPACK_SERVE = "true"
@@ -1039,6 +1055,12 @@ async function loadConfigsForEnv(
       "DYLD_INSERT_LIBRARIES"
     ]
 
+    if (process.env.VERBOSE) {
+      console.log(
+        `[Config Exporter] Setting environment variables from build config...`
+      )
+    }
+
     for (const [key, value] of Object.entries(resolvedBuild.environment)) {
       if (DANGEROUS_ENV_VARS.includes(key)) {
         console.warn(
@@ -1053,6 +1075,9 @@ async function loadConfigsForEnv(
         )
         continue
       }
+      if (process.env.VERBOSE) {
+        console.log(`[Config Exporter]   ${key}=${value}`)
+      }
       process.env[key] = value
     }
 
@@ -1080,6 +1105,21 @@ async function loadConfigsForEnv(
     const railsEnv =
       options.env || resolvedBuild.environment.RAILS_ENV || finalEnv
     process.env.RAILS_ENV = railsEnv
+
+    // Auto-set CLIENT_BUNDLE_ONLY/SERVER_BUNDLE_ONLY from outputs if not already in environment
+    // This allows webpack configs to return the correct number of bundles
+    if (
+      !resolvedBuild.environment.CLIENT_BUNDLE_ONLY &&
+      !resolvedBuild.environment.SERVER_BUNDLE_ONLY
+    ) {
+      if (buildOutputs.length === 1) {
+        if (buildOutputs[0] === "client") {
+          process.env.CLIENT_BUNDLE_ONLY = "yes"
+        } else if (buildOutputs[0] === "server") {
+          process.env.SERVER_BUNDLE_ONLY = "yes"
+        }
+      }
+    }
   } else {
     // No build config - use CLI env or default
     finalEnv = env || "development"
@@ -1092,6 +1132,7 @@ async function loadConfigsForEnv(
     process.env.RAILS_ENV = finalEnv
   }
 
+  // Handle CLI flags for client/server only
   if (options.clientOnly) {
     process.env.CLIENT_BUNDLE_ONLY = "yes"
   } else if (options.serverOnly) {
@@ -1165,7 +1206,19 @@ async function loadConfigsForEnv(
   })
 
   // eslint-disable-next-line @typescript-eslint/no-var-requires
-  let loadedConfig = require(configFile)
+  let loadedConfig: any
+  try {
+    loadedConfig = require(configFile)
+  } catch (error: unknown) {
+    const errorMessage = error instanceof Error ? error.message : String(error)
+    throw new Error(
+      `Failed to load webpack/rspack config file.\n\n` +
+        `Config file: ${configFile}\n` +
+        `Build: ${buildName || "default"}\n` +
+        `Error: ${errorMessage}\n\n` +
+        `Tip: Check that the config file is valid and doesn't have syntax errors.`
+    )
+  }
 
   // Handle ES module default export
   if (typeof loadedConfig === "object" && "default" in loadedConfig) {
@@ -1198,10 +1251,41 @@ async function loadConfigsForEnv(
     } catch (error: unknown) {
       const errorMessage =
         error instanceof Error ? error.message : String(error)
+
+      // Build detailed environment information for debugging
+      const envDetails = [
+        `Config file: ${configFile}`,
+        `Build: ${buildName || "default"}`,
+        ``,
+        `Current Environment Variables:`,
+        `  NODE_ENV: ${process.env.NODE_ENV || "(not set)"}`,
+        `  RAILS_ENV: ${process.env.RAILS_ENV || "(not set)"}`,
+        `  CLIENT_BUNDLE_ONLY: ${process.env.CLIENT_BUNDLE_ONLY || "(not set)"}`,
+        `  SERVER_BUNDLE_ONLY: ${process.env.SERVER_BUNDLE_ONLY || "(not set)"}`,
+        `  WEBPACK_SERVE: ${process.env.WEBPACK_SERVE || "(not set)"}`,
+        ``,
+        `Bundler env args: ${JSON.stringify(envObject)}`,
+        `Mode: ${finalEnv}`,
+        ``,
+        `Error: ${errorMessage}`,
+        ``
+      ]
+
+      // Add suggestion based on common error patterns
+      let suggestion = `Check your webpack/rspack config for errors. The config function threw an exception when called.`
+      if (errorMessage.includes("NODE_ENV") && !process.env.NODE_ENV) {
+        suggestion =
+          `NODE_ENV is not set. ` +
+          `Your build config should set NODE_ENV in the 'environment' section.\n` +
+          `Example:\n` +
+          `  environment:\n` +
+          `    NODE_ENV: "development"`
+      }
+
       throw new Error(
         `Failed to execute config function: ${errorMessage}\n` +
-          `Config file: ${configFile}\n` +
-          `Environment: ${JSON.stringify(envObject)}`
+          envDetails.join("\n") +
+          `\nTip: ${suggestion}`
       )
     }
   }
@@ -1212,29 +1296,81 @@ async function loadConfigsForEnv(
     : [loadedConfig]
   const results: Array<{ config: any; metadata: ConfigMetadata }> = []
 
+  // Validate config count matches expected outputs
+  if (buildOutputs.length > 0 && configs.length !== buildOutputs.length) {
+    const errorLines = [
+      `Webpack config returned ${configs.length} config(s) but outputs array specifies ${buildOutputs.length}.`,
+      ``,
+      `Build: ${buildName || "default"}`,
+      `Config file: ${configFile}`,
+      `Expected outputs: [${buildOutputs.join(", ")}]`,
+      `Actual configs returned: ${configs.length}`,
+      ``,
+      `This mismatch means:`
+    ]
+
+    if (configs.length < buildOutputs.length) {
+      errorLines.push(
+        `  - Your webpack config is returning FEWER configs than expected.`,
+        `  - Either update your webpack config to return ${buildOutputs.length} config(s),`,
+        `  - Or update the 'outputs' array in your build config to match what webpack returns.`
+      )
+    } else {
+      errorLines.push(
+        `  - Your webpack config is returning MORE configs than expected.`,
+        `  - Either update the 'outputs' array to include all ${configs.length} outputs,`,
+        `  - Or update your webpack config to return only ${buildOutputs.length} config(s).`
+      )
+    }
+
+    errorLines.push(
+      ``,
+      `Example fix in build config:`,
+      `  outputs:`,
+      ...Array.from({ length: configs.length }, (_, i) =>
+        i < buildOutputs.length
+          ? `    - ${buildOutputs[i]}`
+          : `    - config-${i + 1}  # Add a name for this config`
+      )
+    )
+
+    throw new Error(errorLines.join("\n"))
+  }
+
+  // Debug logging
+  if (process.env.VERBOSE || buildOutputs.length > 0) {
+    console.log(
+      `[Config Exporter] Webpack returned ${configs.length} config(s), buildOutputs: [${buildOutputs.join(", ")}]`
+    )
+    if (buildOutputs.length > 0 && configs.length === buildOutputs.length) {
+      console.log(
+        `[Config Exporter] ✓ Config count matches outputs array (${configs.length})`
+      )
+    }
+  }
+
   configs.forEach((cfg, index) => {
-    let configType: "client" | "server" | "all" = "all"
+    let configType: string = "all"
 
     // Use outputs from build config if available
-    if (
-      buildOutputs.length > 0 &&
-      index < buildOutputs.length &&
-      buildOutputs[index]
-    ) {
-      const outputValue = buildOutputs[index]
-      // Validate the output value is a valid config type
-      if (
-        outputValue === "client" ||
-        outputValue === "server" ||
-        outputValue === "all"
-      ) {
-        configType = outputValue
-      } else {
-        throw new Error(
-          `Invalid output type '${outputValue}' at index ${index} in build '${buildName}'. ` +
-            `Allowed values are: client, server, all`
+    if (buildOutputs.length > 0) {
+      // If outputs are specified, skip configs beyond the outputs array
+      if (index >= buildOutputs.length) {
+        console.log(
+          `[Config Exporter] Skipping config[${index}] - beyond outputs array`
         )
+        return // Skip this config
       }
+
+      const outputValue = buildOutputs[index]
+      if (!outputValue || outputValue.trim() === "") {
+        return // Skip null/undefined/empty string entries
+      }
+
+      // Accept any string as a valid output name
+      // Built-in types: client, server, all, client-hmr
+      // Custom types: client-modern, client-legacy, server-bundle, etc.
+      configType = outputValue
     } else if (configs.length === 2) {
       // Likely client and server configs
       configType = index === 0 ? "client" : "server"
@@ -1398,10 +1534,30 @@ function cleanConfig(obj: any, rootPath: string): any {
 /**
  * Loads and returns shakapacker.yml configuration
  */
+// Cache to avoid duplicate loading and logging
+let shakapackerConfigCache: {
+  env: string
+  result: { bundler: "webpack" | "rspack"; configPath: string }
+} | null = null
+
 function loadShakapackerConfig(
   env: string,
   appRoot: string
 ): { bundler: "webpack" | "rspack"; configPath: string } {
+  // Return cached result if same environment
+  if (shakapackerConfigCache && shakapackerConfigCache.env === env) {
+    if (process.env.VERBOSE) {
+      console.log(
+        `[Config Exporter] Using cached bundler config for env: ${env}`
+      )
+    }
+    return shakapackerConfigCache.result
+  }
+
+  if (process.env.VERBOSE) {
+    console.log(`[Config Exporter] Loading shakapacker config for env: ${env}`)
+  }
+
   try {
     const configFilePath =
       process.env.SHAKAPACKER_CONFIG ||
@@ -1417,10 +1573,12 @@ function loadShakapackerConfig(
         console.warn(
           `[Config Exporter] Invalid bundler '${bundler}' in shakapacker.yml, defaulting to webpack`
         )
-        return {
-          bundler: "webpack",
+        const result = {
+          bundler: "webpack" as const,
           configPath: bundler === "rspack" ? "config/rspack" : "config/webpack"
         }
+        shakapackerConfigCache = { env, result }
+        return result
       }
 
       // Get config path
@@ -1429,10 +1587,15 @@ function loadShakapackerConfig(
         customConfigPath ||
         (bundler === "rspack" ? "config/rspack" : "config/webpack")
 
+      const result = { bundler, configPath }
+      shakapackerConfigCache = { env, result }
+
+      // Only log on first call (when cache was empty)
       console.log(
         `[Config Exporter] Auto-detected bundler: ${bundler}, config path: ${configPath}`
       )
-      return { bundler, configPath }
+
+      return result
     }
   } catch (error: unknown) {
     console.warn(
@@ -1440,7 +1603,9 @@ function loadShakapackerConfig(
     )
   }
 
-  return { bundler: "webpack", configPath: "config/webpack" }
+  const result = { bundler: "webpack" as const, configPath: "config/webpack" }
+  shakapackerConfigCache = { env, result }
+  return result
 }
 
 /**

data/package/configExporter/fileWriter.ts

@@ -46,18 +46,27 @@ export class FileWriter {
    * Generate filename for a config export
    * Format without build: {bundler}-{env}-{type}.{ext}
    * Format with build: {bundler}-{build}-{type}.{ext}
-   * Examples:
-   *   webpack-development-client.yaml
-   *   rspack-production-server.yaml
-   *   webpack-test-all.json
-   *   webpack-development-client-hmr.yaml
-   *   webpack-dev-client.yaml (with build name)
-   *   rspack-cypress-dev-server.yaml (with build name)
+   *
+   * @param bundler - The bundler type (webpack, rspack)
+   * @param env - The environment (development, production, test)
+   * @param configType - Type of config. Built-in: "client", "server", "all", "client-hmr". Custom: any string from outputs array
+   * @param format - Output format (yaml, json, inspect)
+   * @param buildName - Optional build name that overrides env in filename
+   *
+   * @example
+   * // Built-in types
+   * generateFilename("webpack", "development", "client", "yaml")
+   * // => "webpack-development-client.yaml"
+   *
+   * @example
+   * // Custom output names
+   * generateFilename("webpack", "development", "client-modern", "yaml", "dev-hmr")
+   * // => "webpack-dev-hmr-client-modern.yaml"
    */
   static generateFilename(
     bundler: string,
     env: string,
-    configType: "client" | "server" | "all" | "client-hmr",
+    configType: string,
     format: "yaml" | "json" | "inspect",
     buildName?: string
   ): string {

data/package/configExporter/types.ts

@@ -29,7 +29,12 @@ export interface ConfigMetadata {
   bundler: string
   environment: string
   configFile: string
-  configType: "client" | "server" | "all" | "client-hmr"
+  /**
+   * Type of webpack/rspack config output.
+   * Built-in types: "client", "server", "all", "client-hmr"
+   * Custom types: Any string matching your outputs array (e.g., "client-modern", "client-legacy", "server-bundle")
+   */
+  configType: string
   configCount: number
   buildName?: string // New: name of the build from config file
   environmentVariables: {

data/package/utils/errorCodes.ts

@@ -165,6 +165,7 @@ export const ErrorMessages: Record<ErrorCode, string> = {
  */
 export class ShakapackerError extends Error {
   public readonly code: ErrorCode
+
   public readonly details?: Record<string, any>
 
   constructor(

data/package/utils/errorHelpers.ts

@@ -36,12 +36,14 @@ export function createFileOperationError(
   filePath: string,
   details?: string
 ): ShakapackerError {
-  const errorCode =
-    operation === "read"
-      ? ErrorCode.FILE_READ_ERROR
-      : operation === "write"
-        ? ErrorCode.FILE_WRITE_ERROR
-        : ErrorCode.FILE_NOT_FOUND
+  let errorCode: ErrorCode
+  if (operation === "read") {
+    errorCode = ErrorCode.FILE_READ_ERROR
+  } else if (operation === "write") {
+    errorCode = ErrorCode.FILE_WRITE_ERROR
+  } else {
+    errorCode = ErrorCode.FILE_NOT_FOUND
+  }
 
   return new ShakapackerError(errorCode, {
     path: filePath,
@@ -60,12 +62,14 @@ export function createFileOperationErrorLegacy(
 ): Error {
   const baseMessage = `Failed to ${operation} file at path '${filePath}'`
   const errorDetails = details ? ` - ${details}` : ""
-  const suggestion =
-    operation === "read"
-      ? " (check if file exists and permissions are correct)"
-      : operation === "write"
-        ? " (check write permissions and disk space)"
-        : " (check permissions)"
+  let suggestion: string
+  if (operation === "read") {
+    suggestion = " (check if file exists and permissions are correct)"
+  } else if (operation === "write") {
+    suggestion = " (check write permissions and disk space)"
+  } else {
+    suggestion = " (check permissions)"
+  }
   return new Error(`${baseMessage}${errorDetails}${suggestion}`)
 }
 

data/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "shakapacker",
-  "version": "9.3.0-beta.5",
+  "version": "9.3.0-beta.6",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "shakapacker",
-      "version": "9.3.0-beta.5",
+      "version": "9.3.0-beta.6",
       "license": "MIT",
       "dependencies": {
         "js-yaml": "^4.1.0",

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shakapacker",
-  "version": "9.3.0-beta.5",
+  "version": "9.3.0-beta.6",
   "description": "Use webpack to manage app-like JavaScript modules in Rails",
   "homepage": "https://github.com/shakacode/shakapacker",
   "bugs": {
@@ -32,7 +32,7 @@
   ],
   "scripts": {
     "clean:ts": "find package -name '*.ts' -not -name '*.d.ts' | sed 's/\\.ts$//' | xargs -I {} rm -f {}.js {}.d.ts {}.d.ts.map {}.js.map",
-    "build": "tsc && cp package/index.d.ts.template package/index.d.ts && node scripts/remove-use-strict.js && yarn prettier --write 'package/**/*.js'",
+    "build": "tsc && cp package/index.d.ts.template package/index.d.ts && node scripts/remove-use-strict.js && yarn prettier --write 'package/**/*.js' 'package/**/*.ts'",
     "build:types": "tsc",
     "knip": "knip",
     "knip:production": "knip --production",

data/test/package/configExporter.test.js

@@ -58,6 +58,51 @@ describe("configExporter", () => {
       )
       expect(filename).toBe("rspack-production-client.json")
     })
+
+    test("generates correct filename for custom output name client-modern", () => {
+      const { FileWriter } = require("../../package/configExporter/fileWriter")
+      const filename = FileWriter.generateFilename(
+        "webpack",
+        "development",
+        "client-modern",
+        "yaml"
+      )
+      expect(filename).toBe("webpack-development-client-modern.yaml")
+    })
+
+    test("generates correct filename for custom output name client-legacy", () => {
+      const { FileWriter } = require("../../package/configExporter/fileWriter")
+      const filename = FileWriter.generateFilename(
+        "webpack",
+        "production",
+        "client-legacy",
+        "yaml"
+      )
+      expect(filename).toBe("webpack-production-client-legacy.yaml")
+    })
+
+    test("generates correct filename for custom output name server-bundle", () => {
+      const { FileWriter } = require("../../package/configExporter/fileWriter")
+      const filename = FileWriter.generateFilename(
+        "rspack",
+        "development",
+        "server-bundle",
+        "yaml"
+      )
+      expect(filename).toBe("rspack-development-server-bundle.yaml")
+    })
+
+    test("generates correct filename with buildName override", () => {
+      const { FileWriter } = require("../../package/configExporter/fileWriter")
+      const filename = FileWriter.generateFilename(
+        "webpack",
+        "development",
+        "client-modern",
+        "yaml",
+        "dev-hmr"
+      )
+      expect(filename).toBe("webpack-dev-hmr-client-modern.yaml")
+    })
   })
 
   describe("environment variable preservation in runDoctorMode", () => {

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shakapacker
 version: !ruby/object:Gem::Version
-  version: 9.3.0.beta.5
+  version: 9.3.0.beta.6
 platform: ruby
 authors:
 - David Heinemeier Hansson
@@ -181,7 +181,7 @@ files:
 - docs/deployment.md
 - docs/developing_shakapacker.md
 - docs/early_hints.md
-- docs/early_hints_new_api.md
+- docs/early_hints_manual_api.md
 - docs/feature_testing.md
 - docs/optional-peer-dependencies.md
 - docs/peer-dependencies.md
@@ -385,7 +385,7 @@ homepage: https://github.com/shakacode/shakapacker
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/shakacode/shakapacker/tree/v9.3.0.beta.5
+  source_code_uri: https://github.com/shakacode/shakapacker/tree/v9.3.0.beta.6
 rdoc_options: []
 require_paths:
 - lib