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

data/lib/shakapacker/helper.rb

@@ -95,13 +95,45 @@ module Shakapacker::Helper
   #
   #   <%= javascript_pack_tag 'calendar' %>
   #   <%= javascript_pack_tag 'map' %>
-  def javascript_pack_tag(*names, defer: true, async: false, **options)
+  #
+  # Early Hints:
+  #   By default, HTTP 103 Early Hints are sent automatically when this helper is called,
+  #   allowing browsers to preload JavaScript assets in parallel with Rails rendering.
+  #
+  #   <%= javascript_pack_tag 'application' %>
+  #   # Automatically sends early hints for 'application' pack
+  #
+  #   # Customize handling per pack:
+  #   <%= javascript_pack_tag 'application', 'vendor',
+  #         early_hints: { 'application' => 'preload', 'vendor' => 'prefetch' } %>
+  #
+  #   # Disable early hints:
+  #   <%= javascript_pack_tag 'application', early_hints: false %>
+  def javascript_pack_tag(*names, defer: true, async: false, early_hints: nil, **options)
     if @javascript_pack_tag_loaded
       raise "To prevent duplicated chunks on the page, you should call javascript_pack_tag only once on the page. " \
       "Please refer to https://github.com/shakacode/shakapacker/blob/main/README.md#view-helpers-javascript_pack_tag-and-stylesheet_pack_tag for the usage guide"
     end
 
+    # Collect all packs (queue + direct args)
     append_javascript_pack_tag(*names, defer: defer, async: async)
+    all_packs = javascript_pack_tag_queue.values.flatten.uniq
+
+    # Resolve effective early hints value (nil = use config default)
+    effective_hints = resolve_early_hints_value(early_hints, :javascript)
+
+    # Send early hints automatically if enabled
+    if early_hints_enabled? && effective_hints && effective_hints != "none"
+      hints_config = normalize_pack_hints(all_packs, effective_hints)
+      send_javascript_early_hints_internal(hints_config)
+      # Flush accumulated hints (sends the single 103 response)
+      flush_early_hints
+    elsif early_hints_debug_enabled?
+      store = early_hints_store
+      store[:debug_buffer] ||= []
+      store[:debug_buffer] << "<!-- Shakapacker Early Hints (JS): SKIPPED (early_hints: #{effective_hints.inspect}) -->"
+    end
+
     sync = sources_from_manifest_entrypoints(javascript_pack_tag_queue[:sync], type: :javascript)
     async = sources_from_manifest_entrypoints(javascript_pack_tag_queue[:async], type: :javascript) - sync
     deferred = sources_from_manifest_entrypoints(javascript_pack_tag_queue[:deferred], type: :javascript) - sync - async
@@ -109,6 +141,15 @@ module Shakapacker::Helper
     @javascript_pack_tag_loaded = true
 
     capture do
+      # Output debug buffer first
+      if early_hints_debug_enabled?
+        store = early_hints_store
+        if store[:debug_buffer] && store[:debug_buffer].any?
+          concat store[:debug_buffer].join("\n").html_safe
+          concat "\n"
+        end
+      end
+
       render_tags(async, :javascript, **options.dup.tap { |o| o[:async] = true })
       concat "\n" if async.any? && deferred.any?
       render_tags(deferred, :javascript, **options.dup.tap { |o| o[:defer] = true })
@@ -133,6 +174,80 @@ module Shakapacker::Helper
     end
   end
 
+  # Sends HTTP 103 Early Hints for specified packs with fine-grained control over
+  # JavaScript and CSS handling. This is the "raw" method for maximum flexibility.
+  #
+  # Use this in controller actions BEFORE expensive work (database queries, API calls)
+  # to maximize parallelism - the browser downloads assets while Rails processes the request.
+  #
+  # For simpler cases, use javascript_pack_tag and stylesheet_pack_tag which automatically
+  # send hints when called (combining queued + direct pack names).
+  #
+  # HTTP 103 Early Hints allows the server to send preliminary responses with Link headers
+  # before the final HTTP 200 response, enabling browsers to start downloading critical
+  # assets during the server's "think time".
+  #
+  # Timeline:
+  #   1. Browser requests page
+  #   2. Controller calls send_pack_early_hints (this method)
+  #   3. Server sends HTTP 103 with Link: headers
+  #   4. Browser starts downloading assets IN PARALLEL with step 5
+  #   5. Rails continues expensive work (queries, rendering)
+  #   6. Server sends HTTP 200 with full HTML
+  #   7. Assets already downloaded = faster page load
+  #
+  # Requires Rails 5.2+, HTTP/2, and server support (Puma 5+, nginx 1.13+).
+  # Gracefully degrades if not supported.
+  #
+  # References:
+  # - Rails API: https://api.rubyonrails.org/classes/ActionDispatch/Request.html#method-i-send_early_hints
+  # - HTTP 103 Spec: https://datatracker.ietf.org/doc/html/rfc8297
+  #
+  # Examples:
+  #
+  #   # Controller pattern: send hints BEFORE expensive work
+  #   def show
+  #     send_pack_early_hints({
+  #       "application" => { js: "preload", css: "preload" },
+  #       "vendor" => { js: "prefetch", css: "none" }
+  #     })
+  #
+  #     # Browser now downloading assets while we do expensive work
+  #     @posts = Post.includes(:comments, :author).where(complex_conditions)
+  #     # ... more expensive work ...
+  #   end
+  #
+  #   # Supported handling values:
+  #   # - "preload": High-priority, browser downloads immediately
+  #   # - "prefetch": Low-priority, browser may download when idle
+  #   # - "none" or false: Skip this asset type for this pack
+  def send_pack_early_hints(config)
+    return nil unless early_hints_supported? && early_hints_enabled?
+
+    # Accumulate both JS and CSS hints, then send ONCE
+    config.each do |pack_name, handlers|
+      # Accumulate JavaScript hints
+      js_handling = handlers[:js] || handlers["js"]
+      normalized_js = normalize_hint_value(js_handling)
+      if normalized_js
+        send_early_hints_internal({ pack_name.to_s => normalized_js }, type: :javascript)
+      end
+
+      # Accumulate CSS hints
+      css_handling = handlers[:css] || handlers["css"]
+      normalized_css = normalize_hint_value(css_handling)
+      if normalized_css
+        send_early_hints_internal({ pack_name.to_s => normalized_css }, type: :stylesheet)
+      end
+    end
+
+    # Flush the accumulated hints as a SINGLE 103 response
+    # (Browsers only process the first 103)
+    flush_early_hints
+
+    nil
+  end
+
   # Creates link tags that reference the css chunks from entrypoints when using split chunks API,
   # as compiled by webpack per the entries list in package/environments/base.js.
   # By default, this list is auto-generated to match everything in
@@ -158,15 +273,56 @@ module Shakapacker::Helper
   #
   #   <%= stylesheet_pack_tag 'calendar' %>
   #   <%= stylesheet_pack_tag 'map' %>
-  def stylesheet_pack_tag(*names, **options)
+  #
+  # Early Hints:
+  #   By default, HTTP 103 Early Hints are sent automatically when this helper is called,
+  #   allowing browsers to preload CSS assets in parallel with Rails rendering.
+  #
+  #   <%= stylesheet_pack_tag 'application' %>
+  #   # Automatically sends early hints for 'application' pack
+  #
+  #   # Customize handling per pack:
+  #   <%= stylesheet_pack_tag 'application', 'vendor',
+  #         early_hints: { 'application' => 'preload', 'vendor' => 'prefetch' } %>
+  #
+  #   # Disable early hints:
+  #   <%= stylesheet_pack_tag 'application', early_hints: false %>
+  def stylesheet_pack_tag(*names, early_hints: nil, **options)
     return "" if Shakapacker.inlining_css?
 
+    # Collect all packs (queue + direct args)
+    all_packs = ((@stylesheet_pack_tag_queue || []) + names).uniq
+
+    # Resolve effective early hints value (nil = use config default)
+    effective_hints = resolve_early_hints_value(early_hints, :stylesheet)
+
+    # Send early hints automatically if enabled
+    if early_hints_enabled? && effective_hints && effective_hints != "none"
+      hints_config = normalize_pack_hints(all_packs, effective_hints)
+      send_stylesheet_early_hints_internal(hints_config)
+      # Flush accumulated hints (sends the single 103 response)
+      flush_early_hints
+    elsif early_hints_debug_enabled?
+      store = early_hints_store
+      store[:debug_buffer] ||= []
+      store[:debug_buffer] << "<!-- Shakapacker Early Hints (CSS): SKIPPED (early_hints: #{effective_hints.inspect}) -->"
+    end
+
     requested_packs = sources_from_manifest_entrypoints(names, type: :stylesheet)
     appended_packs = available_sources_from_manifest_entrypoints(@stylesheet_pack_tag_queue || [], type: :stylesheet)
 
     @stylesheet_pack_tag_loaded = true
 
     capture do
+      # Output debug buffer first
+      if early_hints_debug_enabled?
+        store = early_hints_store
+        if store[:debug_buffer] && store[:debug_buffer].any?
+          concat store[:debug_buffer].join("\n").html_safe
+          concat "\n"
+        end
+      end
+
       render_tags(requested_packs | appended_packs, :stylesheet, options)
     end
   end
@@ -253,25 +409,264 @@ module Shakapacker::Helper
     def render_tags(sources, type, options)
       return unless sources.present? || type.present?
 
-      sources.each.with_index do |source, index|
-        tag_source = lookup_source(source)
+      # Temporarily disable Rails' built-in early hints for ALL tags
+      # Rails' javascript_include_tag and stylesheet_link_tag call request.send_early_hints
+      # We handle early hints ourselves before render_tags is called
+      patched = false
+      if respond_to?(:request) && request&.respond_to?(:send_early_hints)
+        request.define_singleton_method(:send_early_hints) { |*args| nil }
+        patched = true
+      end
+
+      begin
+        sources.each.with_index do |source, index|
+          # Duplicate options per iteration to avoid leaking integrity/crossorigin between tags
+          local_options = options.dup
+          tag_source = lookup_source(source)
+
+          if current_shakapacker_instance.config.integrity[:enabled]
+            integrity = lookup_integrity(source)
 
-        if current_shakapacker_instance.config.integrity[:enabled]
-          integrity = lookup_integrity(source)
+            if integrity.present?
+              local_options[:integrity] = integrity
+              local_options[:crossorigin] = current_shakapacker_instance.config.integrity[:cross_origin]
+            end
+          end
 
-          if integrity.present?
-            options[:integrity] = integrity
-            options[:crossorigin] = current_shakapacker_instance.config.integrity[:cross_origin]
+          if type == :javascript
+            concat javascript_include_tag(tag_source, **local_options)
+          else
+            concat stylesheet_link_tag(tag_source, **local_options)
           end
+
+          concat "\n" unless index == sources.size - 1
+        end
+      ensure
+        # Restore original method by removing the singleton method
+        if patched
+          request.singleton_class.send(:remove_method, :send_early_hints)
         end
+      end
+    end
+
+    # Check if early hints are supported by Rails and the request object
+    def early_hints_supported?
+      request.respond_to?(:send_early_hints)
+    end
+
+    # Check if early hints are enabled in configuration
+    def early_hints_enabled?
+      config = current_shakapacker_instance.config.early_hints rescue nil
+      return false unless config
+      # Handle both symbol and string keys from YAML config
+      enabled = config[:enabled] || config["enabled"]
+      enabled == true
+    end
 
-        if type == :javascript
-          concat javascript_include_tag(tag_source, **options)
-        else
-          concat stylesheet_link_tag(tag_source, **options)
+    # Check if early hints debug mode is enabled
+    def early_hints_debug_enabled?
+      config = current_shakapacker_instance.config.early_hints rescue nil
+      return false unless config
+      # Handle both symbol and string keys from YAML config
+      debug = config[:debug] || config["debug"]
+      debug == true
+    end
+
+    # Resolve the effective early hints value
+    # If nil or true, read from config; otherwise use the provided value
+    def resolve_early_hints_value(early_hints, asset_type)
+      # If explicitly set to false or "none", use that
+      return "none" if early_hints == false || early_hints == "none"
+
+      # If nil or true, read from config
+      if early_hints.nil? || early_hints == true
+        config = current_shakapacker_instance.config.early_hints rescue nil
+        return "preload" unless config  # Default fallback
+
+        # Get type-specific config (js/css), handling both symbol and string keys
+        type_key = asset_type == :javascript ? "js" : "css"
+        value = config[type_key.to_sym] || config[type_key]
+        return value || "preload"  # Default to preload if not configured
+      end
+
+      # Return provided value as-is (will be normalized later)
+      early_hints
+    end
+
+    # Normalize pack hints into a hash mapping pack names to validated hint values
+    # Converts booleans, validates strings, and ensures only valid values are used
+    def normalize_pack_hints(packs, early_hints)
+      # Normalize the hint value(s)
+      if early_hints.is_a?(Hash)
+        # Per-pack configuration
+        packs.each_with_object({}) do |pack, result|
+          hint_value = early_hints[pack] || early_hints[pack.to_s] || early_hints[pack.to_sym]
+          result[pack] = normalize_hint_value(hint_value || "preload")
         end
+      else
+        # Single value for all packs
+        normalized_value = normalize_hint_value(early_hints)
+        packs.each_with_object({}) do |pack, result|
+          result[pack] = normalized_value
+        end
+      end
+    end
 
-        concat "\n" unless index == sources.size - 1
+    # Normalize and validate a single hint value
+    # Converts false/nil to "none", downcases strings, validates against allowed values
+    def normalize_hint_value(value)
+      # Convert booleans and nil
+      return "none" if value == false || value.nil?
+      return "preload" if value == true
+
+      # Downcase and validate string
+      str_value = value.to_s.downcase.strip
+
+      # Only allow valid values
+      valid_values = ["preload", "prefetch", "none"]
+      valid_values.include?(str_value) ? str_value : "none"
+    end
+
+    # Generate reason why early hints were skipped
+    def early_hints_skip_reason
+      unless early_hints_supported?
+        return "Rails request.send_early_hints not available (requires Rails 5.2+)"
+      end
+      unless early_hints_enabled?
+        return "early_hints.enabled is false in config/shakapacker.yml"
+      end
+      "Unknown reason"
+    end
+
+    # Build a Link header value for early hints
+    # Takes the already-resolved source_path to avoid duplicate lookup_source calls
+    def build_link_header(source_path, source, as:, rel: "preload")
+      parts = ["<#{source_path}>", "rel=#{rel}", "as=#{as}"]
+
+      # Add crossorigin and integrity if enabled (consistent with render_tags)
+      if current_shakapacker_instance.config.integrity[:enabled]
+        integrity = lookup_integrity(source)
+        if integrity.present?
+          parts << "integrity=\"#{integrity}\""
+          # Use configured cross_origin value, consistent with render_tags
+          cross_origin = current_shakapacker_instance.config.integrity[:cross_origin]
+          parts << "crossorigin=\"#{cross_origin}\""
+        end
+      elsif ["script", "style", "font"].include?(as)
+        # When integrity not enabled, scripts, styles, and fonts still need crossorigin for CORS
+        parts << "crossorigin=\"anonymous\""
       end
+
+      parts.join("; ")
+    end
+
+    # Returns the shared early hints storage from request.env
+    # This ensures state is shared across controller/view contexts
+    def early_hints_store
+      request.env["shakapacker.early_hints"] ||= {}
+    end
+
+    # Internal method to accumulate and send early hints
+    # Sends only ONE 103 response (browsers ignore subsequent ones)
+    # config: { "application" => "preload", "vendor" => "prefetch" }
+    # type: :javascript or :stylesheet
+    def send_early_hints_internal(config, type:)
+      return unless early_hints_supported?
+
+      # Use request.env as shared storage across controller/view contexts
+      # This prevents duplicate packs and ensures debug info is preserved
+      store = early_hints_store
+      store[:sent_packs] ||= { javascript: {}, stylesheet: {} }
+      store[:link_buffer] ||= []
+      store[:debug_buffer] ||= []
+
+      # If we've already sent the 103 response, just track for debug
+      if store[:http_103_sent]
+        if early_hints_debug_enabled?
+          store[:debug_buffer] << "<!-- Shakapacker Early Hints (#{type.upcase}): Not sent (103 already sent) -->"
+          store[:debug_buffer] << "<!--   Packs: #{config.keys.join(', ')} -->"
+        end
+        return
+      end
+
+      # Filter to only new packs for THIS type, and skip "none" values
+      new_hints = config.reject { |pack, handling| store[:sent_packs][type].key?(pack) || handling == "none" }
+
+      if early_hints_debug_enabled? && new_hints.empty?
+        store[:debug_buffer] << "<!-- Shakapacker Early Hints (#{type.upcase}): All packs already queued -->"
+      end
+
+      # Accumulate Link headers for this type
+      asset_type = type == :javascript ? "script" : "style"
+      new_hints.each do |pack_name, handling|
+        # Skip if handling is "none" (extra safety check)
+        next if handling == "none"
+
+        begin
+          sources = available_sources_from_manifest_entrypoints([pack_name], type: type)
+          sources.each do |source|
+            source_path = lookup_source(source)
+            store[:link_buffer] << build_link_header(source_path, source, as: asset_type, rel: handling)
+          end
+          # Mark pack as queued for THIS type
+          store[:sent_packs][type][pack_name] = handling
+        rescue Shakapacker::Manifest::MissingEntryError, NoMethodError => e
+          Rails.logger.debug { "Early hints: skipping pack '#{pack_name}' - #{e.class}: #{e.message}" }
+        end
+      end
+
+      # Note: We DON'T flush here - caller must call flush_early_hints explicitly
+      # This allows accumulating multiple calls (JS + CSS) before sending ONE 103
+    end
+
+    # Send accumulated early hints as a SINGLE 103 response
+    # Browsers only process the first 103, so we send everything at once
+    def flush_early_hints
+      store = early_hints_store
+
+      # Guard against multiple flushes - only send once per request
+      return if store[:http_103_sent]
+      return if store[:link_buffer].nil? || store[:link_buffer].empty?
+
+      # Check if response is already committed (headers already sent)
+      if respond_to?(:response) && response&.committed?
+        Rails.logger.debug { "Early hints: Cannot send 103 - response already committed" }
+        return
+      end
+
+      # Set flag BEFORE sending to prevent race conditions
+      store[:http_103_sent] = true
+
+      # Send the 103 response with error handling
+      begin
+        request.send_early_hints({ "Link" => store[:link_buffer].join(", ") })
+      rescue => e
+        Rails.logger.error { "Early hints: Failed to send 103 - #{e.class}: #{e.message}" }
+      end
+
+      if early_hints_debug_enabled?
+        all_packs = (store[:sent_packs][:javascript].keys + store[:sent_packs][:stylesheet].keys).uniq
+        store[:debug_buffer] << "<!-- Shakapacker Early Hints: HTTP/1.1 103 SENT -->"
+        store[:debug_buffer] << "<!--   Total Links: #{store[:link_buffer].size} -->"
+        store[:debug_buffer] << "<!--   Packs: #{all_packs.join(', ')} -->"
+        store[:debug_buffer] << "<!--   JS Packs: #{store[:sent_packs][:javascript].keys.join(', ')} -->"
+        store[:debug_buffer] << "<!--   CSS Packs: #{store[:sent_packs][:stylesheet].keys.join(', ')} -->"
+        store[:debug_buffer] << "<!--   Headers: -->"
+        store[:link_buffer].each do |link|
+          store[:debug_buffer] << "<!--     #{link} -->"
+        end
+        store[:debug_buffer] << "<!--   Note: Browsers only process the FIRST 103 response -->"
+        store[:debug_buffer] << "<!--   Note: Puma only supports HTTP/1.1 Early Hints (not HTTP/2) -->"
+      end
+    end
+
+    # Wrapper for JavaScript early hints
+    def send_javascript_early_hints_internal(config)
+      send_early_hints_internal(config, type: :javascript)
+    end
+
+    # Wrapper for stylesheet early hints
+    def send_stylesheet_early_hints_internal(config)
+      send_early_hints_internal(config, type: :stylesheet)
     end
 end

data/lib/shakapacker/railtie.rb

@@ -39,6 +39,10 @@ class Shakapacker::Engine < ::Rails::Engine
     end
   end
 
+  # Early hints are handled automatically by javascript_pack_tag and stylesheet_pack_tag helpers
+  # when early_hints.enabled: true in shakapacker.yml
+  # See docs/early_hints_new_api.md for usage
+
   initializer "shakapacker.logger" do
     config.after_initialize do
       if ::Rails.logger.respond_to?(:tagged)

data/lib/shakapacker/version.rb

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

data/package/configExporter/buildValidator.ts

@@ -226,9 +226,8 @@ export class BuildValidator {
 
     if (isHMR) {
       return this.validateHMRBuild(build, appRoot, bundler)
-    } else {
-      return this.validateStaticBuild(build, appRoot, bundler)
     }
+    return this.validateStaticBuild(build, appRoot, bundler)
   }
 
   /**

data/package/configExporter/cli.ts

@@ -1285,7 +1285,8 @@ function formatConfig(
       appRoot
     })
     return serializer.serialize(config, metadata)
-  } else if (options.format === "json") {
+  }
+  if (options.format === "json") {
     const jsonReplacer = (key: string, value: any): any => {
       if (typeof value === "function") {
         return `[Function: ${value.name || "anonymous"}]`

data/package-lock.json

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

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shakapacker",
-  "version": "9.3.0-beta.4",
+  "version": "9.3.0-beta.5",
   "description": "Use webpack to manage app-like JavaScript modules in Rails",
   "homepage": "https://github.com/shakacode/shakapacker",
   "bugs": {

data/scripts/remove-use-strict.js

@@ -41,5 +41,4 @@ files.forEach((file) => {
   fs.writeFileSync(file, content, "utf8")
 })
 
-// eslint-disable-next-line no-console
 console.log(`Removed "use strict" from ${files.length} files`)

data/test/package/rules/babel.test.js

@@ -19,6 +19,7 @@ const babelConfig = require("../../../package/rules/babel")
 
 // Skip tests if babel config is not available (not the active transpiler)
 if (!babelConfig) {
+  // eslint-disable-next-line jest/no-disabled-tests
   describe.skip("babel - skipped", () => {
     test.todo("skipped because babel is not the active transpiler")
   })

data/test/package/rules/swc.test.js

@@ -19,6 +19,7 @@ const swcConfig = require("../../../package/rules/swc")
 
 // Skip tests if swc config is not available (not the active transpiler)
 if (!swcConfig) {
+  // eslint-disable-next-line jest/no-disabled-tests
   describe.skip("swc - skipped", () => {
     test.todo("skipped because swc is not the active transpiler")
   })

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shakapacker
 version: !ruby/object:Gem::Version
-  version: 9.3.0.beta.4
+  version: 9.3.0.beta.5
 platform: ruby
 authors:
 - David Heinemeier Hansson
@@ -180,6 +180,9 @@ files:
 - docs/customizing_babel_config.md
 - docs/deployment.md
 - docs/developing_shakapacker.md
+- docs/early_hints.md
+- docs/early_hints_new_api.md
+- docs/feature_testing.md
 - docs/optional-peer-dependencies.md
 - docs/peer-dependencies.md
 - docs/precompile_hook.md
@@ -382,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.4
+  source_code_uri: https://github.com/shakacode/shakapacker/tree/v9.3.0.beta.5
 rdoc_options: []
 require_paths:
 - lib