shakapacker 9.3.0.beta.2 → 9.3.0.beta.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d196f7ff4fd6270c0a4739f62ed17ee202eef663222018dc0b031b7dfb8ec015
-  data.tar.gz: cb645bae3cb677c7b7f7e35164d99b779dfb92d7d6a975204ac0fcae71b56f40
+  metadata.gz: 9db05ecb02b4491f31eb4ec2374057933be5cf90a09b6dded781c036ff8e494e
+  data.tar.gz: a8f9b04812aff8a73275044f61a1ecbc096c5131a3bca69d5b75e292c1c31064
 SHA512:
-  metadata.gz: ee177b62cc41abd5fbd460d34f8f8dfe387385152cc683aed5034fe3fd67050043dd3cd2fe32f09f06735ff28a4e71ec6f1f4f945e6ea582dbba06e0883dbb1d
-  data.tar.gz: dcb85543ec034ede52cf91ed5e36ab5a987e8fb485d54c857fd1762f133252a827d760ac92dd36b9973897e30c3ab1d89f64bacd5761ffe6815b75c990c2c2f9
+  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/ESLINT_TECHNICAL_DEBT.md

@@ -6,7 +6,7 @@ This document tracks the ESLint errors currently suppressed in the codebase and
 
 **As of 2025-10-14**: All TypeScript files in `package/` directory are temporarily excluded from linting via the ignore pattern `package/**/*.ts` in `eslint.config.js`. This allows the project to adopt ESLint configuration without requiring immediate fixes to all existing issues.
 
-**Latest Update**: Fixed all `class-methods-use-this` violations by converting FileWriter methods to static methods (4 violations resolved).
+**Latest Update**: Fixed all `no-param-reassign` violations by refactoring to create new objects instead of mutating parameters (7 violations resolved).
 
 ## Current Linting Status
 
@@ -19,12 +19,12 @@ This document tracks the ESLint errors currently suppressed in the codebase and
 
 **TypeScript files** (currently ignored via `package/**/*.ts`):
 
-- **Estimated suppressed errors: ~172** (from sample analysis)
-  - TypeScript type-safety issues: ~114 (66%)
-  - Style/convention issues: ~58 (34%)
+- **Estimated suppressed errors: ~163** (from sample analysis)
+  - TypeScript type-safety issues: ~114 (70%)
+  - Style/convention issues: ~49 (30%)
 
 **Target**: Reduce suppressed errors by 50% within Q1 2025
-**Last Updated**: 2025-10-14
+**Last Updated**: 2025-10-15
 
 ## Priority Matrix
 
@@ -33,9 +33,9 @@ This document tracks the ESLint errors currently suppressed in the codebase and
 | `@typescript-eslint/no-explicit-any` | High   | High   | P1       | 22    |
 | `@typescript-eslint/no-unsafe-*`     | High   | High   | P1       | 85    |
 | `config.ts` type safety              | High   | Medium | P1       | 7     |
-| `no-param-reassign`                  | Medium | Low    | P2       | 7     |
+| `no-param-reassign`                  | Medium | Low    | P2       | 0     |
 | `class-methods-use-this`             | Low    | Low    | P3       | 0     |
-| `no-nested-ternary`                  | Low    | Low    | P3       | 3     |
+| `no-nested-ternary`                  | Low    | Low    | P3       | 0     |
 | `import/prefer-default-export`       | Low    | Medium | P3       | 9     |
 | `global-require`                     | Medium | High   | P2       | 3     |
 | Other style issues                   | Low    | Low    | P3       | 31    |
@@ -80,15 +80,13 @@ This document tracks the ESLint errors currently suppressed in the codebase and
 
 ✅ **FIXED** - All FileWriter methods that didn't use instance state have been converted to static methods
 
-#### `no-nested-ternary` (3 instances)
+#### `no-nested-ternary` (0 instances)
 
-**Fix strategy:** Refactor to if-else statements
+✅ **FIXED** - All nested ternary expressions have been refactored to if-else statements for better readability
 
-#### `no-param-reassign` (7 instances)
+#### `no-param-reassign` (0 instances)
 
-**Files affected:** `configExporter/cli.ts`
-**Why suppressed:** Common pattern for option objects
-**Fix strategy:** Create new objects instead of mutating parameters
+✅ **FIXED** - Refactored `applyDefaults` function to return new objects instead of mutating parameters
 
 #### `no-underscore-dangle` (2 instances)
 
@@ -115,10 +113,11 @@ This document tracks the ESLint errors currently suppressed in the codebase and
 - Added proper type annotations for `requireOrError` calls
 - Configured appropriate global rule disables (`no-console`, `no-restricted-syntax`)
 - ✅ **Fixed `class-methods-use-this`** - Converted FileWriter methods to static methods
+- ✅ **Fixed `no-nested-ternary`** - Refactored to if-else statements for better readability
+- ✅ **Fixed `no-param-reassign`** - Refactored `applyDefaults` to return new objects instead of mutating parameters
 
 🔧 Could still fix (low risk):
 
-- `no-nested-ternary` - Refactor conditionals
 - `no-useless-escape` - Remove unnecessary escapes
 - Unused variables - Remove or prefix with underscore
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    shakapacker (9.3.0.beta.2)
+    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)
@@ -477,8 +478,8 @@ And the main layout has:
 is the same as using this in the main layout:
 
 ```erb
-<%= javascript_pack_tag 'calendar', 'map', application' %>
-<%= stylesheet_pack_tag 'calendar', 'map', application' %>
+<%= javascript_pack_tag 'calendar', 'map', 'application' %>
+<%= stylesheet_pack_tag 'calendar', 'map', 'application' %>
 ```
 
 However, you typically can't do that in the main layout, as the view and partial codes will depend on the route.
@@ -490,12 +491,13 @@ Thus, you can distribute the logic of what packs are needed for any route. All t
 The typical issue is that your layout might reference some partials that need to configure packs. A good way to solve this problem is to use `content_for` to ensure that the code to render your partial comes before the call to `javascript_pack_tag`.
 
 ```erb
-<% content_for :footer do
-   render 'shared/footer' %>
+<% content_for :footer do %>
+  <%= render 'shared/footer' %>
+<% end %>
 
 <%= javascript_pack_tag %>
 
-<%= content_for :footer %>
+<%= yield :footer %>
 ```
 
 There is also `prepend_javascript_pack_tag` that will put the entry at the front of the queue. This is handy when you want an entry in the main layout to go before the partial and main layout `append_javascript_pack_tag` entries.
@@ -522,11 +524,13 @@ And the main layout has:
 is the same as using this in the main layout:
 
 ```erb
-<%= javascript_pack_tag 'main', 'calendar', 'map', application' %>
+<%= javascript_pack_tag 'main', 'calendar', 'map', 'application' %>
 ```
 
 For alternative options for setting the additional packs, [see this discussion](https://github.com/shakacode/shakapacker/issues/39).
 
+**Important:** To prevent FOUC (Flash of Unstyled Content), always place `stylesheet_pack_tag` in the `<head>` section of your layout. When using `append_*` helpers with dynamic pack loading (e.g., React on Rails), use the `content_for` pattern to control execution order. See the [Preventing FOUC guide](./docs/preventing_fouc.md) for detailed examples.
+
 #### View Helper: `asset_pack_path`
 
 If you want to link a static asset for `<img />` tag, you can use the `asset_pack_path` helper:
@@ -560,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,7 +11,10 @@ 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)
 
 ## Basic Configuration
 
@@ -484,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:
@@ -608,6 +642,106 @@ default: &default
     - packages/ui-components
 ```
 
+## Build Configurations (config/shakapacker-builds.yml)
+
+Shakapacker supports defining reusable build configurations in `config/shakapacker-builds.yml`. This allows you to run predefined builds with a simple command, making it easy to switch between different build scenarios.
+
+### Creating a Build Configuration File
+
+Generate `config/shakapacker-builds.yml` with example builds:
+
+```bash
+bin/shakapacker --init  # Creates config/shakapacker-builds.yml
+```
+
+This generates a file with example builds for common scenarios (HMR development, standard development, and production).
+
+### Running Builds by Name
+
+Once you have `config/shakapacker-builds.yml`, you can run builds by name:
+
+```bash
+# List available builds
+bin/shakapacker --list-builds
+
+# Run a specific build
+bin/shakapacker --build dev-hmr    # Client bundle with HMR (automatically uses dev server)
+bin/shakapacker --build prod        # Client and server bundles for production
+bin/shakapacker --build dev         # Client bundle for development
+```
+
+### Build Configuration Format
+
+Example `config/shakapacker-builds.yml`:
+
+```yaml
+builds:
+  dev-hmr:
+    description: Client bundle with HMR (React Fast Refresh)
+    bundler: rspack # Optional: override assets_bundler from config/shakapacker.yml
+    environment:
+      NODE_ENV: development
+      RAILS_ENV: development
+      WEBPACK_SERVE: "true" # Automatically uses bin/shakapacker-dev-server
+    outputs:
+      - client
+    config: config/${BUNDLER}/custom.config.js # Optional: custom config file with variable substitution
+
+  prod:
+    description: Production client and server bundles
+    environment:
+      NODE_ENV: production
+      RAILS_ENV: production
+    outputs:
+      - client # Multiple outputs - builds both client and server bundles
+      - server
+```
+
+### Build Configuration Options
+
+- **`description`** (optional): Human-readable description of the build
+- **`bundler`** (optional): Override the default bundler from `config/shakapacker.yml` (`webpack` or `rspack`)
+- **`dev_server`** (optional): Boolean flag to force routing to dev server (overrides environment variable detection)
+- **`environment`**: Environment variables to set when running the build
+- **`outputs`**: Array of output types - can include `client`, `server`, or both for multiple bundles in a single build
+- **`config`** (optional): Custom config file path (supports `${BUNDLER}` variable substitution)
+- **`bundler_env`** (optional): Key-value pairs passed as bundler `--env` flags (e.g., `{ analyze: true }` becomes `--env analyze=true`)
+
+### Automatic Dev Server Detection
+
+Shakapacker automatically uses `bin/shakapacker-dev-server` instead of the regular build command when:
+
+1. The build has `dev_server: true` explicitly set (preferred method - takes precedence over environment variables), OR
+2. The build has `WEBPACK_SERVE=true` or `HMR=true` in its environment variables (fallback for backward compatibility)
+
+Example:
+
+```bash
+# These are equivalent:
+bin/shakapacker --build dev-hmr
+WEBPACK_SERVE=true bin/shakapacker-dev-server  # (with dev-hmr environment vars)
+```
+
+### Variable Substitution
+
+The `config` field supports `${BUNDLER}` substitution:
+
+```yaml
+builds:
+  custom:
+    bundler: rspack
+    config: config/${BUNDLER}/custom.config.js # Becomes: config/rspack/custom.config.js
+```
+
+### When to Use Build Configurations
+
+Build configurations are useful for:
+
+- **Multiple build scenarios**: Use when you need different builds for HMR development, standard development, and production
+- **CI/CD pipelines**: Use when you want predefined builds that can be referenced in deployment scripts
+- **Team consistency**: Use to ensure all developers use the same build configurations
+- **Complex setups**: Use to manage different bundler configs or environment variables for different scenarios
+
 ## Troubleshooting
 
 If you encounter configuration issues:
@@ -627,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)