shakapacker 9.3.0.beta.2 → 9.3.0.beta.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d196f7ff4fd6270c0a4739f62ed17ee202eef663222018dc0b031b7dfb8ec015
-  data.tar.gz: cb645bae3cb677c7b7f7e35164d99b779dfb92d7d6a975204ac0fcae71b56f40
+  metadata.gz: 2f2fafddfa10d364b8e62946786c16d9206ecffadf82b719e3ffeb2100608da0
+  data.tar.gz: 0e0cdc08d53e64e8066d7232aba1022b6a7708067d56ff7ba738803bfbc49a78
 SHA512:
-  metadata.gz: ee177b62cc41abd5fbd460d34f8f8dfe387385152cc683aed5034fe3fd67050043dd3cd2fe32f09f06735ff28a4e71ec6f1f4f945e6ea582dbba06e0883dbb1d
-  data.tar.gz: dcb85543ec034ede52cf91ed5e36ab5a987e8fb485d54c857fd1762f133252a827d760ac92dd36b9973897e30c3ab1d89f64bacd5761ffe6815b75c990c2c2f9
+  metadata.gz: dcbb4604f956d78acaea611bb760ecea97a1afcc15bc390b9c5a64c5d9654f5d08e83c57ed24da55aca0a1a98da074a0047a754cadf5f74ee8ba832fb6e93b3e
+  data.tar.gz: 47b7d7887f770f5712b5f020afd260fcefcb4b09a0c707e1b2bc921c38d2944bf6045b6b9752295790806018d98cd95d43313f9079719bcb3c808ff9f6e6c2ad

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.4)
       activesupport (>= 5.2)
       package_json
       rack-proxy (>= 0.6.1)

data/README.md

@@ -477,8 +477,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 +490,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 +523,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:

data/docs/configuration.md

@@ -12,6 +12,7 @@ This guide covers all configuration options available in `config/shakapacker.yml
 - [Compilation Options](#compilation-options)
 - [Advanced Options](#advanced-options)
 - [Environment-Specific Configuration](#environment-specific-configuration)
+- [Build Configurations (config/shakapacker-builds.yml)](#build-configurations-configshakapacker-buildsyml)
 
 ## Basic Configuration
 
@@ -608,6 +609,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:

data/docs/preventing_fouc.md

@@ -0,0 +1,132 @@
+# Preventing FOUC (Flash of Unstyled Content)
+
+## Overview
+
+FOUC (Flash of Unstyled Content) occurs when content is rendered before stylesheets load, causing a brief flash of unstyled content. This guide explains how to prevent FOUC when using Shakapacker's view helpers.
+
+## Basic Solution
+
+Place `stylesheet_pack_tag` in the `<head>` section of your layout, not at the bottom of the `<body>`. This ensures styles load before content is rendered.
+
+**Recommended layout structure:**
+
+```erb
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>My App</title>
+
+  <%= stylesheet_pack_tag 'application', media: 'all' %>
+  <%= javascript_pack_tag 'application', defer: true %>
+</head>
+<body>
+  <%= yield %>
+</body>
+</html>
+```
+
+## Advanced: Using `content_for` with Dynamic Pack Loading
+
+If you're using libraries that dynamically append packs during rendering (like React on Rails with `auto_load_bundle`), or if you need to append packs from views/partials, you must ensure that all `append_*` helpers execute before the pack tags render.
+
+Rails' `content_for` pattern solves this execution order problem.
+
+### The `content_for :body_content` Pattern
+
+This pattern renders the body content first, allowing all append calls to register before the pack tags in the head are rendered:
+
+```erb
+<% content_for :body_content do %>
+  <%= render 'shared/header' %>
+  <%= yield %>
+  <%= render 'shared/footer' %>
+<% end %>
+
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>My App</title>
+
+  <%= stylesheet_pack_tag 'application', media: 'all' %>
+  <%= javascript_pack_tag 'application', defer: true %>
+</head>
+<body>
+  <%= yield :body_content %>
+</body>
+</html>
+```
+
+**How this works:**
+
+1. The `content_for :body_content` block executes first during template rendering
+2. Any `append_stylesheet_pack_tag` or `append_javascript_pack_tag` calls in your views/partials register their packs
+3. Libraries like React on Rails can auto-append component-specific packs during rendering
+4. The pack tags in `<head>` then render with all registered appends
+5. Finally, `yield :body_content` outputs the pre-rendered content
+
+**Result:**
+
+- ✅ All appends (explicit + auto) happen before pack tags
+- ✅ Stylesheets load in head, eliminating FOUC
+- ✅ Works with `auto_load_bundle` and similar features
+
+### Alternative: Using `yield :head` for Explicit Appends
+
+For simpler cases where you know which packs you need upfront and can explicitly specify them, you can use `content_for :head` in your views and yield it in your layout.
+
+**Layout (app/views/layouts/application.html.erb):**
+
+```erb
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>My App</title>
+
+  <%= yield :head %>
+  <%= stylesheet_pack_tag 'application', media: 'all' %>
+  <%= javascript_pack_tag 'application', defer: true %>
+</head>
+<body>
+  <%= yield %>
+</body>
+</html>
+```
+
+**View (app/views/pages/show.html.erb):**
+
+```erb
+<% content_for :head do %>
+  <%= append_stylesheet_pack_tag 'my-component' %>
+  <%= append_javascript_pack_tag 'my-component' %>
+<% end %>
+
+<h1>My Page</h1>
+<p>Content goes here...</p>
+```
+
+This approach works when:
+
+- You're not using auto-appending libraries
+- You can explicitly list all required packs in each view
+- You don't need dynamic pack determination
+
+## Key Takeaways
+
+- Always place `stylesheet_pack_tag` in `<head>` to prevent FOUC
+- Use `content_for` to control execution order when using `append_*` helpers
+- Ensure `append_*` helpers execute before the main pack tags
+- JavaScript can use `defer: true` (default) or be placed at end of `<body>`
+- The `content_for :body_content` pattern is essential when using auto-appending libraries
+
+## Related
+
+- [View Helpers Documentation](../README.md#view-helpers)
+- [Troubleshooting Guide](./troubleshooting.md)
+- Original issue: [#720](https://github.com/shakacode/shakapacker/issues/720)
+- Working implementation: [react-webpack-rails-tutorial PR #686](https://github.com/shakacode/react-webpack-rails-tutorial/pull/686)

data/docs/troubleshooting.md

@@ -1,5 +1,9 @@
 # Troubleshooting
 
+## Flash of Unstyled Content (FOUC)
+
+If you're experiencing FOUC where content briefly appears unstyled before CSS loads, see the [Preventing FOUC guide](./preventing_fouc.md) for solutions including proper `stylesheet_pack_tag` placement and `content_for` patterns for dynamic pack loading.
+
 ## Debugging your webpack config
 
 1. Read the error message carefully. The error message will tell you the precise key value

data/eslint.config.js

@@ -177,8 +177,7 @@ module.exports = [
       "@typescript-eslint/no-unsafe-argument": "off",
       "@typescript-eslint/no-explicit-any": "off",
       "no-useless-escape": "off",
-      "no-continue": "off",
-      "no-nested-ternary": "off"
+      "no-continue": "off"
     }
   },
   {
@@ -193,9 +192,7 @@ module.exports = [
       "@typescript-eslint/no-unsafe-function-type": "off",
       "@typescript-eslint/no-unused-vars": "off",
       "@typescript-eslint/require-await": "off",
-      "no-param-reassign": "off",
       "no-await-in-loop": "off",
-      "no-nested-ternary": "off",
       "import/prefer-default-export": "off",
       "global-require": "off",
       "no-underscore-dangle": "off"
@@ -215,8 +212,7 @@ module.exports = [
       "@typescript-eslint/no-unsafe-argument": "off",
       "@typescript-eslint/no-explicit-any": "off",
       "no-useless-escape": "off",
-      "no-continue": "off",
-      "no-nested-ternary": "off"
+      "no-continue": "off"
     }
   },
   {

data/lib/shakapacker/build_config_loader.rb

@@ -0,0 +1,147 @@
+require "yaml"
+
+module Shakapacker
+  class BuildConfigLoader
+    attr_reader :config_file_path
+
+    def initialize(config_file_path = nil)
+      @config_file_path = config_file_path || File.join(Dir.pwd, "config", "shakapacker-builds.yml")
+    end
+
+    def exists?
+      File.exist?(@config_file_path)
+    end
+
+    def load_build(build_name)
+      unless exists?
+        raise ArgumentError, "Config file not found: #{@config_file_path}\n" \
+                            "Run 'bin/shakapacker --init' to generate a sample config file."
+      end
+
+      config = load_config
+      fetch_build_or_raise(config, build_name)
+    end
+
+    def resolve_build_config(build_name, default_bundler: "webpack")
+      config = load_config
+      build = fetch_build_or_raise(config, build_name)
+
+      # Resolve bundler with precedence: build.bundler > config.default_bundler > default_bundler
+      bundler = build["bundler"] || config["default_bundler"] || default_bundler
+
+      # Get environment variables
+      environment = build["environment"] || {}
+
+      # Get config file path if specified
+      config_file = build["config"]
+      if config_file
+        # Expand ${BUNDLER} variable
+        config_file = config_file.gsub("${BUNDLER}", bundler)
+      end
+
+      # Get bundler_env for --env flags
+      bundler_env = build["bundler_env"] || {}
+
+      # Get outputs
+      outputs = build["outputs"] || []
+
+      # Validate outputs
+      if outputs.empty?
+        raise ArgumentError, "Build '#{build_name}' has empty outputs array. " \
+                            "Please specify at least one output type (client, server, or all)."
+      end
+
+      {
+        name: build_name,
+        description: build["description"],
+        bundler: bundler,
+        dev_server: build["dev_server"],
+        environment: environment,
+        bundler_env: bundler_env,
+        outputs: outputs,
+        config_file: config_file
+      }
+    end
+
+    def uses_dev_server?(build_config)
+      # Check explicit dev_server flag first (preferred)
+      # Only return early if the value is explicitly set (not nil)
+      return build_config[:dev_server] unless build_config[:dev_server].nil?
+
+      # Fallback: check environment variables for backward compatibility
+      env = build_config[:environment]
+      return false unless env
+
+      # Handle both string "true" and boolean true from YAML
+      %w[WEBPACK_SERVE HMR].any? do |key|
+        value = env[key]
+        value.to_s.strip.casecmp("true").zero?
+      end
+    end
+
+    def list_builds
+      config = load_config
+      builds = config["builds"]
+
+      puts "\nAvailable builds in #{@config_file_path}:\n\n"
+
+      builds.each do |name, build|
+        bundler = build["bundler"] || config["default_bundler"] || "webpack (default)"
+        outputs = build["outputs"] ? build["outputs"].join(", ") : "missing (invalid)"
+
+        puts "  #{name}"
+        puts "    Description: #{build["description"]}" if build["description"]
+        puts "    Bundler: #{bundler}"
+        puts "    Outputs: #{outputs}"
+        puts ""
+      end
+    end
+
+    private
+
+      def fetch_build_or_raise(config, build_name)
+        build = config["builds"][build_name]
+        unless build
+          available = config["builds"].keys.join(", ")
+          raise ArgumentError, "Build '#{build_name}' not found in config file.\n" \
+                              "Available builds: #{available}\n" \
+                              "Use 'bin/shakapacker --list-builds' to see all available builds."
+        end
+        build
+      end
+
+      # Load YAML config file safely with Ruby version compatibility
+      # Ruby 3.1+ supports safe_load_file with aliases, older versions need safe_load
+      def load_config
+        begin
+          config = if YAML.respond_to?(:safe_load_file)
+            # Ruby 3.1+: Use safe_load_file with aliases enabled
+            YAML.safe_load_file(@config_file_path, aliases: true)
+          else
+            # Ruby 2.7-3.0: Use safe_load with aliases enabled
+            YAML.safe_load(
+              File.read(@config_file_path),
+              permitted_classes: [],
+              permitted_symbols: [],
+              aliases: true
+            )
+          end
+        rescue ArgumentError
+          # Fallback for older Psych versions without aliases support
+          config = YAML.safe_load(
+            File.read(@config_file_path),
+            permitted_classes: [],
+            permitted_symbols: []
+          )
+        end
+
+        unless config["builds"]&.is_a?(Hash)
+          raise ArgumentError, "Config file must contain a 'builds' object"
+        end
+
+        config
+      rescue Psych::SyntaxError => e
+        raise ArgumentError, "Invalid YAML in config file: #{e.message}"
+      end
+  end
+end

data/lib/shakapacker/configuration.rb

@@ -8,12 +8,13 @@ class Shakapacker::Configuration
     attr_accessor :installing
   end
 
-  attr_reader :root_path, :config_path, :env
+  attr_reader :root_path, :config_path, :env, :bundler_override
 
-  def initialize(root_path:, config_path:, env:)
+  def initialize(root_path:, config_path:, env:, bundler_override: nil)
     @root_path = root_path
     @env = env
     @config_path = config_path
+    @bundler_override = bundler_override
   end
 
   def dev_server
@@ -97,6 +98,9 @@ class Shakapacker::Configuration
   end
 
   def assets_bundler
+    # CLI --bundler flag takes highest precedence
+    return @bundler_override if @bundler_override
+
     # Show deprecation warning if using old 'bundler' key
     if data.has_key?(:bundler) && !data.has_key?(:assets_bundler)
       $stderr.puts "⚠️  DEPRECATION WARNING: The 'bundler' configuration option is deprecated. Please use 'assets_bundler' instead to avoid confusion with Ruby's Bundler gem manager."