shakapacker 9.4.0 → 9.6.0.beta.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a0519c935e0e3d98204aeaeec6cc35b57fa13be1fe8a6f62e5e6cd5124d09c7
-  data.tar.gz: 7f6fe4134fd9b17de2dcd26b5c9e80f1f41d2019dfa0ed337092c1d23a9aa077
+  metadata.gz: 16a87e8e339c085afc34f5f70af6fee7aa534590949f02faa1863d9c5e7f9f7d
+  data.tar.gz: 19d1f859e00dc29bfe4c593ba1b4a1e5b64c6347fc1b56a2cbabcc8c8020205b
 SHA512:
-  metadata.gz: 8789ef5d5cf102254f27c0833b3a7bd8239b5b97d2dfa97ac79fb01827931397dc71dd35f82971a61354a1751f6dafd80d91a322e51b6390f83132f17a786626
-  data.tar.gz: 3a6cff63ba261b9cec55cdd683e7cfa96a24e52b753639643bf2f6874ed49c0f50a990a771a85c4265e9e6394a8fc7e8b4e3440ed5d62982f89b98cddadf9450
+  metadata.gz: f4286284b7cbbec5324ce2ad26c6d6892cfcecae96e31c7324ff0a533f332301b4008e7083592b3b4b639be131758ab6fa5bc81ed46ac0903f2370f20a05fae0
+  data.tar.gz: e4e6bfdd5837dabfd9f5d031e5a1d905ca88b6c1d50b1f3d440fb3f3c6a23d0abbec1d8839a769536af52d67eed5657ec602786c824dd57156f1678026ec300e

data/.github/workflows/claude-code-review.yml

@@ -2,7 +2,7 @@ name: Claude Code Review
 
 on:
   pull_request:
-    types: [opened, synchronize]
+    types: [opened, synchronize, ready_for_review, reopened]
     # Optional: Only run on specific file changes
     # paths:
     #   - "src/**/*.ts"
@@ -36,18 +36,9 @@ jobs:
         uses: anthropics/claude-code-action@v1
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-          prompt: |
-            Please review this pull request and provide feedback on:
-            - Code quality and best practices
-            - Potential bugs or issues
-            - Performance considerations
-            - Security concerns
-            - Test coverage
-
-            Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
-
-            Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
-
+          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
+          plugins: 'code-review@claude-code-plugins'
+          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
-          # or https://docs.claude.com/en/docs/claude-code/sdk#command-line for available options
-          claude_args: '--model claude-sonnet-4-5-20250929 --allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
+          # or https://code.claude.com/docs/en/cli-reference for available options
+

data/.github/workflows/claude.yml

@@ -45,5 +45,6 @@ jobs:
 
           # Optional: Add claude_args to customize behavior and configuration
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
-          # or https://docs.claude.com/en/docs/claude-code/sdk#command-line for available options
-          # claude_args: '--model claude-opus-4-1-20250805 --allowed-tools Bash(gh pr:*)'
+          # or https://code.claude.com/docs/en/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr:*)'
+

data/.prettierignore

@@ -1,3 +1,7 @@
 # Template files that should maintain their original quote style
 lib/install/config/**/*.ts
 lib/install/config/**/*.js
+
+# Temporarily ignore workflow files that cannot be modified in PRs due to claude-review validation
+.github/workflows/claude.yml
+.github/workflows/claude-code-review.yml

data/.rubocop.yml

@@ -10,6 +10,7 @@ AllCops:
     - "node_modules/**/*"
     - "_actions/**/*"
     - "spec/dummy-rspack/**/*"
+    - "bin/conductor-exec" # Shell script, not Ruby
 
 # Prefer &&/|| over and/or.
 Style/AndOr:

data/CHANGELOG.md

@@ -11,9 +11,80 @@
 
 Changes since the last non-beta release.
 
+### Changed
+
+- **BREAKING: sass-loader now defaults to modern Sass API**. [PR #879](https://github.com/shakacode/shakapacker/pull/879) by [justin808](https://github.com/justin808). The sass-loader configuration now uses `api: "modern"` instead of the deprecated legacy API. This improves compatibility with plugins like sass-resources-loader that require the modern API. If you experience issues after upgrading, you can revert to the legacy API by customizing your webpack config:
+
+  ```javascript
+  // config/webpack/webpack.config.js
+  const { generateWebpackConfig } = require("shakapacker")
+  const config = generateWebpackConfig()
+
+  // Find and modify sass-loader options
+  config.module.rules.forEach((rule) => {
+    if (rule.use) {
+      rule.use.forEach((loader) => {
+        if (loader.loader?.includes("sass-loader")) {
+          loader.options.api = "legacy"
+        }
+      })
+    }
+  })
+
+  module.exports = config
+  ```
+
+### Fixed
+
+- **Fixed orphaned webpack/rspack processes when foreman receives SIGTERM**. [PR #888](https://github.com/shakacode/shakapacker/pull/888) by [jordan-brough](https://github.com/jordan-brough). When running under foreman, sending SIGTERM to foreman (e.g. `kill <pid>`) would kill the Ruby shakapacker process but leave the webpack/rspack child process running as an orphan. DevServerRunner now uses `exec` to replace the Ruby process entirely, and Runner uses `spawn` with SIGTERM forwarding to ensure the child process is properly terminated.
+- **Fixed installer writing wrong shakapacker version in package.json**. [PR #899](https://github.com/shakacode/shakapacker/pull/899) by [justin808](https://github.com/justin808). The `shakapacker:install` generator now keeps the `package.json` dependency value in sync with the exact version or path that was requested, instead of relying on the post-install value which could differ.
+- **Fixed NODE_ENV=test causing DefinePlugin warnings**. [PR #870](https://github.com/shakacode/shakapacker/pull/870) by [justin808](https://github.com/justin808). When RAILS_ENV=test, Shakapacker now sets NODE_ENV=development instead of NODE_ENV=test. This prevents webpack/rspack DefinePlugin conflicts since these bundlers only recognize "development" and "production" as valid NODE_ENV values.
+
+### Documentation
+
+- **Added CDN limitation warnings for Early Hints feature**. [PR #878](https://github.com/shakacode/shakapacker/pull/878) by [justin808](https://github.com/justin808). The early hints documentation now prominently notes that most CDNs (Cloudflare, AWS CloudFront, AWS ALB) strip HTTP 103 responses before they reach end users. Debug mode also includes CDN warnings in HTML comments.
+
+## [v9.5.0] - January 7, 2026
+
+### Security
+
+- **CRITICAL: Fixed environment variable leak via EnvironmentPlugin**. [PR #857](https://github.com/shakacode/shakapacker/pull/857) by [justin808](https://github.com/justin808). The default webpack and rspack plugins were passing the entire `process.env` to `EnvironmentPlugin`, which exposed ALL build environment variables (including secrets like `DATABASE_URL`, `AWS_SECRET_ACCESS_KEY`, `RAILS_MASTER_KEY`, etc.) to client-side JavaScript bundles when code referenced `process.env.VARIABLE_NAME`. **Note**: This issue is especially critical with webpack 5.103+ due to a [serialization change](https://github.com/webpack/webpack/commit/eecdeeb746b2f996ed4ab74365dd72c95070196b) that can embed all environment variables into bundles when `import.meta.env` is accessed conditionally. This vulnerability was inherited from webpacker v1.0.0 (January 2017) and has been present in all versions of webpacker and shakapacker. **Action required**: After upgrading, rotate any secrets that may have been exposed in production JavaScript bundles.
+
+### Added
+
+- **Added `SHAKAPACKER_PUBLIC_*` prefix convention for client-side environment variables**. [PR #857](https://github.com/shakacode/shakapacker/pull/857) by [justin808](https://github.com/justin808). Any environment variable prefixed with `SHAKAPACKER_PUBLIC_` is automatically exposed to client-side JavaScript. This follows the same convention used by Next.js (`NEXT_PUBLIC_*`) and Vite (`VITE_*`), making it explicit which variables are intended for client-side use.
+
+  ```bash
+  # These are automatically available in your JavaScript
+  export SHAKAPACKER_PUBLIC_API_URL=https://api.example.com
+  export SHAKAPACKER_PUBLIC_ANALYTICS_ID=UA-12345
+  ```
+
+- **Added `SHAKAPACKER_ENV_VARS` environment variable as escape hatch for extending allowed client-side env vars**. [PR #857](https://github.com/shakacode/shakapacker/pull/857) by [justin808](https://github.com/justin808). Set `SHAKAPACKER_ENV_VARS=VAR1,VAR2,VAR3` to expose additional environment variables to client-side JavaScript beyond the default allowlist (`NODE_ENV`, `RAILS_ENV`, `WEBPACK_SERVE`). Only add non-sensitive variables that are safe to embed in public JavaScript bundles.
+
+### Changed
+
+- **BREAKING: EnvironmentPlugin now uses allowlist instead of exposing all env vars**. [PR #857](https://github.com/shakacode/shakapacker/pull/857) by [justin808](https://github.com/justin808). Only `NODE_ENV`, `RAILS_ENV`, `WEBPACK_SERVE`, and any `SHAKAPACKER_PUBLIC_*` variables are exposed by default. If your client-side code relies on other environment variables, either rename them with the `SHAKAPACKER_PUBLIC_` prefix (recommended), add them via `SHAKAPACKER_ENV_VARS`, or customize your webpack/rspack config. This is a security fix - the previous behavior was dangerous.
+
+  **Migration examples:**
+
+  ```bash
+  # Option 1 (recommended): Use the SHAKAPACKER_PUBLIC_ prefix
+  export SHAKAPACKER_PUBLIC_API_BASE_URL=https://api.example.com
+
+  # Option 2: Use SHAKAPACKER_ENV_VARS for existing variable names
+  SHAKAPACKER_ENV_VARS=API_BASE_URL bundle exec rails assets:precompile
+  ```
+
+### Fixed
+
+- **Fixed gemspec to exclude Gemfile.lock from published gem**. [PR #856](https://github.com/shakacode/shakapacker/pull/856) by [adrien-k](https://github.com/adrien-k). The gemspec's file pattern now correctly excludes `Gemfile.lock`, preventing vulnerability alerts during Docker image scans caused by outdated pinned versions in the lock file.
+
+## [v9.4.0] - November 22, 2025
+
 ### Added
 
-- **Added `SHAKAPACKER_SKIP_PRECOMPILE_HOOK` environment variable to skip precompile hook**. [PR #XXX](https://github.com/shakacode/shakapacker/pull/XXX) by [justin808](https://github.com/justin808). Set `SHAKAPACKER_SKIP_PRECOMPILE_HOOK=true` to skip the precompile hook during compilation. This is useful when using process managers like Foreman or Overmind to run the hook once before starting multiple webpack processes, preventing duplicate hook execution. **Migration tip:** If you have a custom `bin/dev` script that starts multiple webpack processes, you can now run the precompile hook once in the script and set this environment variable to prevent each webpack process from running the hook again. See the [precompile hook documentation](./docs/precompile_hook.md#skipping-the-hook) for implementation examples.
+- **Added `SHAKAPACKER_SKIP_PRECOMPILE_HOOK` environment variable to skip precompile hook**. [PR #850](https://github.com/shakacode/shakapacker/pull/850) by [justin808](https://github.com/justin808). Set `SHAKAPACKER_SKIP_PRECOMPILE_HOOK=true` to skip the precompile hook during compilation. This is useful when using process managers like Foreman or Overmind to run the hook once before starting multiple webpack processes, preventing duplicate hook execution. **Migration tip:** If you have a custom `bin/dev` script that starts multiple webpack processes, you can now run the precompile hook once in the script and set this environment variable to prevent each webpack process from running the hook again. See the [precompile hook documentation](./docs/precompile_hook.md#skipping-the-hook) for implementation examples.
 
 ## [v9.3.4-beta.0] - November 17, 2025
 
@@ -763,7 +834,9 @@ 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.4-beta.0...main
+[Unreleased]: https://github.com/shakacode/shakapacker/compare/v9.5.0...main
+[v9.5.0]: https://github.com/shakacode/shakapacker/compare/v9.4.0...v9.5.0
+[v9.4.0]: https://github.com/shakacode/shakapacker/compare/v9.3.4...v9.4.0
 [v9.3.4-beta.0]: https://github.com/shakacode/shakapacker/compare/v9.3.3...v9.3.4-beta.0
 [v9.3.3]: https://github.com/shakacode/shakapacker/compare/v9.3.2...v9.3.3
 [v9.3.2]: https://github.com/shakacode/shakapacker/compare/v9.3.1...v9.3.2

data/CLAUDE.md

@@ -12,6 +12,10 @@
 - Run corresponding RSpec tests when changing source files
 - For example, when changing `lib/shakapacker/foo.rb`, run `spec/shakapacker/foo_spec.rb`
 - Run the full test suite with `bundle exec rspec` before pushing
+- **Use explicit RSpec spy assertions** - prefer `have_received`/`not_to have_received` over indirect counter patterns
+  - Good: `expect(Open3).to have_received(:capture3).with(anything, hook_command, anything)`
+  - Good: `expect(Open3).not_to have_received(:capture3).with(anything, hook_command, anything)`
+  - Avoid: `call_count += 1` followed by `expect(call_count).to eq(1)`
 
 ## Code Style
 
@@ -41,3 +45,11 @@
 - This gem supports both webpack and rspack configurations
 - Test changes with both bundlers when modifying core functionality
 - Be aware of the dual package.json/Gemfile dependency management
+
+## Conductor Environment
+
+- **Version manager support**: The setup script detects mise, asdf, or direct PATH tools (rbenv/nvm/nodenv)
+- **bin/conductor-exec**: Use this wrapper for commands when tool versions aren't detected correctly in Conductor's non-interactive shell
+  - Example: `bin/conductor-exec bundle exec rubocop`
+  - The wrapper uses `mise exec` if mise is available, otherwise falls back to direct execution
+- **conductor.json scripts** already use this wrapper, so you typically don't need to use it manually

data/bin/conductor-exec

@@ -0,0 +1,24 @@
+#!/bin/zsh
+# Wrapper script to run commands in Conductor with proper tool versions
+# Usage: bin/conductor-exec <command> [args...]
+#
+# This is needed because Conductor (and other non-interactive shells) don't
+# source .zshrc, so version manager PATH configuration isn't active by default.
+#
+# - If mise is available: uses `mise exec` for correct tool versions
+# - Otherwise: falls back to direct execution (for asdf/rbenv/nvm users)
+#
+# Examples:
+#   bin/conductor-exec ruby --version       # Uses correct Ruby version
+#   bin/conductor-exec bundle exec rubocop  # Correct Ruby for linting
+#   bin/conductor-exec git commit -m "msg"  # Pre-commit hooks work correctly
+#   bin/conductor-exec yarn install         # Uses correct Node version
+#
+# See: https://github.com/shakacode/react_on_rails-demos/issues/105
+
+if command -v mise &> /dev/null; then
+  exec mise exec -- "$@"
+else
+  # Fall back to direct execution for non-mise users
+  exec "$@"
+fi

data/bin/shakapacker-config

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+// Minimal shim - all logic is in the TypeScript module
+const { run } = require("shakapacker/configExporter")
+
+run(process.argv.slice(2))
+  .then((exitCode) => process.exit(exitCode))
+  .catch((error) => {
+    console.error(error.message)
+    process.exit(1)
+  })

data/conductor-setup.sh

@@ -1,43 +1,124 @@
-#!/usr/bin/env bash
+#!/bin/zsh
 set -euo pipefail
 
 echo "🔧 Setting up Shakapacker workspace..."
 
-# Set up Ruby version if asdf is available
-if command -v asdf &> /dev/null; then
-    echo "📝 Using asdf Ruby version management..."
-    # Ensure we have the right Ruby version file
-    echo "ruby 3.3.4" > .tool-versions
-    # Use asdf exec to run commands with the right Ruby version
-    BUNDLE_CMD="asdf exec bundle"
+# Detect and initialize version manager
+# Supports: mise, asdf, or direct PATH (rbenv/nvm/nodenv already in PATH)
+VERSION_MANAGER="none"
+
+echo "📋 Detecting version manager..."
+
+if command -v mise &> /dev/null; then
+    VERSION_MANAGER="mise"
+    echo "✅ Found mise"
+    # Trust mise config for current directory only
+    mise trust 2>/dev/null || true
+elif [[ -f ~/.asdf/asdf.sh ]]; then
+    VERSION_MANAGER="asdf"
+    source ~/.asdf/asdf.sh
+    echo "✅ Found asdf (from ~/.asdf/asdf.sh)"
+elif command -v asdf &> /dev/null; then
+    VERSION_MANAGER="asdf"
+    # For homebrew-installed asdf
+    if [[ -f /opt/homebrew/opt/asdf/libexec/asdf.sh ]]; then
+        source /opt/homebrew/opt/asdf/libexec/asdf.sh
+    fi
+    echo "✅ Found asdf"
 else
-    BUNDLE_CMD="bundle"
+    echo "ℹ️  No version manager detected, using system PATH"
+    echo "   (Assuming rbenv/nvm/nodenv or system tools are already configured)"
+fi
+
+# Ensure version config exists for asdf/mise users
+if [[ "$VERSION_MANAGER" != "none" ]] && [[ ! -f .tool-versions ]] && [[ ! -f .mise.toml ]]; then
+    echo "📝 Creating .tool-versions from project version files..."
+
+    # Read Ruby version from .ruby-version or use default
+    if [[ -f .ruby-version ]]; then
+        RUBY_VER=$(cat .ruby-version | tr -d '[:space:]')
+    else
+        RUBY_VER="3.3.4"  # Default: recent stable Ruby
+    fi
+
+    # Read Node version from .node-version or use default
+    if [[ -f .node-version ]]; then
+        NODE_VER=$(cat .node-version | tr -d '[:space:]')
+    else
+        NODE_VER="20.18.0"  # Default: LTS Node
+    fi
+
+    cat > .tool-versions << EOF
+ruby $RUBY_VER
+nodejs $NODE_VER
+EOF
+    echo "   Using Ruby $RUBY_VER, Node $NODE_VER"
 fi
 
-# Check for required tools
-if ! $BUNDLE_CMD --version &> /dev/null; then
-    echo "❌ Error: Ruby bundler is not installed"
-    echo "Please install bundler first: gem install bundler"
+# Install tools via mise (after .tool-versions exists)
+if [[ "$VERSION_MANAGER" == "mise" ]]; then
+    echo "📦 Installing tools via mise..."
+    mise install
+fi
+
+# Helper function to run commands with the detected version manager
+run_cmd() {
+    if [[ "$VERSION_MANAGER" == "mise" ]] && [[ -x "bin/conductor-exec" ]]; then
+        bin/conductor-exec "$@"
+    else
+        "$@"
+    fi
+}
+
+# Check required tools
+echo "📋 Checking required tools..."
+run_cmd ruby --version >/dev/null 2>&1 || { echo "❌ Error: Ruby is not installed or not in PATH."; exit 1; }
+run_cmd node --version >/dev/null 2>&1 || { echo "❌ Error: Node.js is not installed or not in PATH."; exit 1; }
+
+# Check Ruby version
+RUBY_VERSION=$(run_cmd ruby -v | awk '{print $2}')
+MIN_RUBY_VERSION="2.7.0"
+if [[ $(echo -e "$MIN_RUBY_VERSION\n$RUBY_VERSION" | sort -V | head -n1) != "$MIN_RUBY_VERSION" ]]; then
+    echo "❌ Error: Ruby version $RUBY_VERSION is too old. Shakapacker requires Ruby >= 2.7.0"
+    echo "   Please upgrade Ruby using your version manager or system package manager."
     exit 1
 fi
+echo "✅ Ruby version: $RUBY_VERSION"
 
-if ! command -v yarn &> /dev/null; then
-    echo "❌ Error: Yarn is not installed"
-    echo "Please install yarn first"
+# Check Node version
+NODE_VERSION=$(run_cmd node -v | cut -d'v' -f2)
+MIN_NODE_VERSION="14.0.0"
+if [[ $(echo -e "$MIN_NODE_VERSION\n$NODE_VERSION" | sort -V | head -n1) != "$MIN_NODE_VERSION" ]]; then
+    echo "❌ Error: Node.js version v$NODE_VERSION is too old. Shakapacker requires Node.js >= 14.0.0"
+    echo "   Please upgrade Node.js using your version manager or system package manager."
     exit 1
 fi
+echo "✅ Node.js version: v$NODE_VERSION"
+
+# Copy any environment files from root if they exist
+if [ -n "${CONDUCTOR_ROOT_PATH:-}" ]; then
+    if [ -f "$CONDUCTOR_ROOT_PATH/.env" ]; then
+        echo "📝 Copying .env file..."
+        cp "$CONDUCTOR_ROOT_PATH/.env" .env
+    fi
+
+    if [ -f "$CONDUCTOR_ROOT_PATH/.env.local" ]; then
+        echo "📝 Copying .env.local file..."
+        cp "$CONDUCTOR_ROOT_PATH/.env.local" .env.local
+    fi
+fi
 
 # Install Ruby dependencies
-echo "📦 Installing Ruby dependencies..."
-$BUNDLE_CMD install
+echo "💎 Installing Ruby dependencies..."
+run_cmd bundle install
 
 # Install JavaScript dependencies
 echo "📦 Installing JavaScript dependencies..."
-yarn install --frozen-lockfile
+run_cmd yarn install --frozen-lockfile
 
 # Set up Husky git hooks
 echo "🪝 Setting up Husky git hooks..."
-npx husky
+run_cmd npx husky
 if [ ! -f .husky/pre-commit ]; then
     echo "Creating pre-commit hook..."
     cat > .husky/pre-commit << 'EOF'
@@ -47,24 +128,20 @@ EOF
     chmod +x .husky/pre-commit
 fi
 
-# Copy environment files if they exist in root
-if [ -n "${CONDUCTOR_ROOT_PATH:-}" ]; then
-    if [ -f "$CONDUCTOR_ROOT_PATH/.env" ]; then
-        echo "📋 Copying .env file from root..."
-        cp "$CONDUCTOR_ROOT_PATH/.env" .env
-    fi
-    
-    if [ -f "$CONDUCTOR_ROOT_PATH/.env.local" ]; then
-        echo "📋 Copying .env.local file from root..."
-        cp "$CONDUCTOR_ROOT_PATH/.env.local" .env.local
-    fi
-fi
+# Verify linting tools are available
+echo "✅ Verifying linting tools..."
+run_cmd bundle exec rubocop --version
 
-echo "✅ Workspace setup complete!"
+echo "✨ Workspace setup complete!"
 echo ""
-echo "Available commands:"
-echo "  - Run tests: bundle exec rspec"
-echo "  - Run specific test suites: bundle exec rake run_spec:gem"
-echo "  - Run JavaScript tests: yarn test"
-echo "  - Lint JavaScript: yarn lint"
-echo "  - Lint Ruby: bundle exec rubocop"
+echo "📚 Key commands:"
+echo "  • bundle exec rspec - Run Ruby tests"
+echo "  • bundle exec rake run_spec:gem - Run gem-specific tests"
+echo "  • yarn test - Run JavaScript tests"
+echo "  • yarn lint - Run JavaScript linting"
+echo "  • bundle exec rubocop - Run Ruby linting (required before commits)"
+echo ""
+if [[ "$VERSION_MANAGER" == "mise" ]]; then
+    echo "💡 Tip: Use 'bin/conductor-exec <command>' if tool versions aren't detected correctly."
+fi
+echo "⚠️ Remember: Always run 'bundle exec rubocop' before committing!"

data/conductor.json

@@ -1,7 +1,9 @@
 {
   "scripts": {
     "setup": "./conductor-setup.sh",
-    "run": "bundle exec rspec",
+    "run": "bin/conductor-exec bundle exec rspec",
+    "test": "bin/conductor-exec bundle exec rspec",
+    "lint": "bin/conductor-exec bundle exec rubocop && bin/conductor-exec yarn lint",
     "archive": ""
   }
 }

data/docs/configuration.md

@@ -617,14 +617,57 @@ Shakapacker validates configuration at runtime and provides helpful error messag
 
 Some options can be overridden via environment variables:
 
-| Variable                     | Description              | Example                   |
-| ---------------------------- | ------------------------ | ------------------------- |
-| `SHAKAPACKER_CONFIG`         | Path to shakapacker.yml  | `config/webpack.yml`      |
-| `SHAKAPACKER_ASSETS_BUNDLER` | Override assets bundler  | `rspack`                  |
-| `SHAKAPACKER_PRECOMPILE`     | Override precompile flag | `false`                   |
-| `SHAKAPACKER_ASSET_HOST`     | Override asset host      | `https://cdn.example.com` |
-| `NODE_ENV`                   | Node environment         | `production`              |
-| `RAILS_ENV`                  | Rails environment        | `staging`                 |
+| Variable                     | Description                                        | Example                      |
+| ---------------------------- | -------------------------------------------------- | ---------------------------- |
+| `SHAKAPACKER_CONFIG`         | Path to shakapacker.yml                            | `config/webpack.yml`         |
+| `SHAKAPACKER_ASSETS_BUNDLER` | Override assets bundler                            | `rspack`                     |
+| `SHAKAPACKER_PRECOMPILE`     | Override precompile flag                           | `false`                      |
+| `SHAKAPACKER_ASSET_HOST`     | Override asset host                                | `https://cdn.example.com`    |
+| `SHAKAPACKER_PUBLIC_*`       | Auto-exposed to client-side JS (prefix convention) | `SHAKAPACKER_PUBLIC_API_URL` |
+| `SHAKAPACKER_ENV_VARS`       | Additional env vars to expose to client-side JS    | `API_URL,FEATURE_FLAGS`      |
+| `NODE_ENV`                   | Node environment                                   | `production`                 |
+| `RAILS_ENV`                  | Rails environment                                  | `staging`                    |
+
+### Exposing Environment Variables to Client-Side JavaScript
+
+By default, only `NODE_ENV`, `RAILS_ENV`, and `WEBPACK_SERVE` are exposed to client-side JavaScript via webpack/rspack's `EnvironmentPlugin`. This is a security measure to prevent accidentally leaking secrets like `DATABASE_URL`, `API_SECRET_KEY`, etc. into your JavaScript bundles.
+
+#### SHAKAPACKER*PUBLIC*\* Prefix (Recommended)
+
+Any environment variable prefixed with `SHAKAPACKER_PUBLIC_` is automatically exposed to client-side code. This follows the same convention used by Next.js (`NEXT_PUBLIC_*`) and Vite (`VITE_*`):
+
+```bash
+# These are automatically available in your JavaScript
+export SHAKAPACKER_PUBLIC_API_URL=https://api.example.com
+export SHAKAPACKER_PUBLIC_ANALYTICS_ID=UA-12345
+export SHAKAPACKER_PUBLIC_FEATURE_FLAGS=dark_mode,beta_ui
+```
+
+```javascript
+// Access in your JavaScript code
+console.log(process.env.SHAKAPACKER_PUBLIC_API_URL)
+console.log(process.env.SHAKAPACKER_PUBLIC_ANALYTICS_ID)
+```
+
+The prefix makes it explicit which variables are intended for client-side use, preventing accidental exposure of secrets.
+
+#### SHAKAPACKER_ENV_VARS (Legacy/Escape Hatch)
+
+For variables without the `SHAKAPACKER_PUBLIC_` prefix, you can use `SHAKAPACKER_ENV_VARS` to expose them:
+
+```bash
+# Expose additional variables during build
+SHAKAPACKER_ENV_VARS=API_BASE_URL,FEATURE_FLAGS bundle exec rake assets:precompile
+
+# In development
+SHAKAPACKER_ENV_VARS=API_BASE_URL bin/shakapacker-dev-server
+```
+
+```javascript
+// These are available after adding to SHAKAPACKER_ENV_VARS
+console.log(process.env.API_BASE_URL)
+console.log(process.env.FEATURE_FLAGS)
+```
 
 ## Best Practices
 

data/docs/early_hints.md

@@ -4,6 +4,8 @@ This guide shows you how to use HTTP 103 Early Hints with Shakapacker to optimiz
 
 > **📚 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).
 
+> ⚠️ **CDN Limitation**: Most CDNs (Cloudflare, AWS CloudFront, AWS ALB, etc.) strip HTTP 103 Early Hints before they reach end users. While Shakapacker sends early hints correctly, and your application server (Puma/Thruster) forwards them properly, **CDNs typically strip the 103 response**. End users will only receive the 200 response with Link headers (which arrive too late to provide early hints benefits). This is an industry-wide limitation—even major sites like GitHub, Google, and Shopify don't serve 103 in production through CDNs. For full early hints delivery, you need either direct connections without a CDN, or specific CDN configuration (e.g., Cloudflare's Early Hints feature on paid plans, which works differently by caching Link headers). See [Reverse proxy stripping 103 responses](#reverse-proxy-stripping-103-responses) for configuration details.
+
 ## 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.
@@ -336,8 +338,12 @@ See the [Manual API Guide](early_hints_manual_api.md) for detailed examples and
 - **Modern browsers:**
   - Chrome/Edge/Firefox 103+ ✅
   - Safari 16.4+ ✅
+- **Infrastructure that preserves 103 responses:**
+  - Direct connections (no CDN) ✅
+  - Cloudflare with Early Hints enabled (paid plans, works via Link header caching) ✅
+  - Most CDNs/load balancers ❌ (strip 103 responses - see [CDN Limitation](#troubleshooting) above)
 
-If requirements not met, feature gracefully degrades with no errors.
+If requirements not met, feature gracefully degrades with no errors. The Link headers will still be present in the 200 response, which may provide some browser prefetching benefits even when 103 is stripped.
 
 ## Quick Reference
 
@@ -377,8 +383,9 @@ Debug mode adds HTML comments to your page showing:
 - What pack names were processed
 - What Link headers were sent
 - HTTP/2 support status
+- CDN warning reminder (since most CDNs strip 103 responses)
 
-View page source and look for `<!-- Shakapacker Early Hints Debug -->` comments.
+View page source and look for `<!-- Shakapacker Early Hints -->` comments.
 
 **Early hints not appearing:**
 

data/docs/precompile_hook.md

@@ -23,6 +23,52 @@ The precompile hook is especially useful when you need to run commands like:
 - **Development**: Runs before `bin/shakapacker --watch` or dev server starts
 - **Production**: Runs before `bundle exec rake assets:precompile`
 
+## Choosing an Approach
+
+Use `precompile_hook` when your setup should always run preparatory commands right
+before Shakapacker compiles. For React on Rails projects, this is often the
+simplest default.
+
+For projects with more custom startup needs (for example, additional build steps
+or strict process ordering in `bin/dev`), you can run those commands explicitly
+before launching long-running processes instead of using `precompile_hook`.
+
+### Comparison
+
+| Aspect | `precompile_hook` | Explicit setup in `bin/dev` |
+|--------|-------------------|-------------------------------|
+| Best for | Default/consistent pre-build tasks | Custom multi-step dev boot flows |
+| Runs when | Immediately before compilation starts | Wherever you place it in startup script |
+| Production integration | Automatic via `assets:precompile` | Requires explicit production wiring |
+| Process manager complexity | Lower | Higher (you own orchestration) |
+| Debugging | Centralized hook command | Fully explicit command-by-command flow |
+
+### `shakapacker_precompile` Interaction
+
+`shakapacker_precompile` controls whether Shakapacker compilation is included in
+`assets:precompile`, while `precompile_hook` controls whether a preparatory command
+runs before compilation.
+
+```yaml
+# Option A: Default behavior
+shakapacker_precompile: true
+precompile_hook: "bin/shakapacker-precompile-hook"
+
+# Option B: You manage compilation elsewhere
+shakapacker_precompile: false
+precompile_hook: "bin/shakapacker-precompile-hook"
+
+# Option C: Fully explicit startup flow (no hook)
+shakapacker_precompile: false
+# precompile_hook: not set
+```
+
+To temporarily skip only the hook, set:
+
+```bash
+SHAKAPACKER_SKIP_PRECOMPILE_HOOK=true
+```
+
 ## Configuration
 
 Add the `precompile_hook` option to your `config/shakapacker.yml`:
@@ -300,7 +346,7 @@ This is useful when:
 - Running the hook manually and then compiling multiple times
 - Debugging compilation issues without the hook
 
-**Note:** The examples below show how to implement this in your custom `bin/dev` script. If you're using React on Rails, the generated `bin/dev` script already implements this pattern automatically - it runs the precompile hook once before launching processes, then sets `SHAKAPACKER_SKIP_PRECOMPILE_HOOK=true` to prevent duplicate execution.
+**Note:** The examples below show how to implement this in your custom `bin/dev` script. If you're using React on Rails v13.1.0+, the generated `bin/dev` script already implements this pattern automatically - **no action needed**. It runs the precompile hook once before launching processes, then sets `SHAKAPACKER_SKIP_PRECOMPILE_HOOK=true` to prevent duplicate execution.
 
 **Recommended: Use Procfile env prefix**
 

data/lib/install/template.rb

@@ -141,6 +141,9 @@ if (setup_path = Rails.root.join("bin/setup")).exist?
 end
 
 Dir.chdir(Rails.root) do
+  npm_version = Shakapacker::Utils::VersionSyntaxConverter.new.rubygem_to_npm(Shakapacker::VERSION)
+  shakapacker_dependency_value = nil
+
   # In CI, use the pre-packed tarball if available
   if ENV["SHAKAPACKER_NPM_PACKAGE"]
     package_path = ENV["SHAKAPACKER_NPM_PACKAGE"]
@@ -167,6 +170,7 @@ Dir.chdir(Rails.root) do
         say "📦 Installing shakapacker from local package: #{absolute_path}", :cyan
         begin
           @package_json.manager.add!([absolute_path], type: :production)
+          shakapacker_dependency_value = absolute_path
         rescue PackageJson::Error
           say "Shakapacker installation failed 😭 See above for details.", :red
           exit 1
@@ -174,9 +178,9 @@ Dir.chdir(Rails.root) do
       else
         say "⚠️  SHAKAPACKER_NPM_PACKAGE set but file not found: #{absolute_path}", :yellow
         say "Falling back to npm registry...", :yellow
-        npm_version = Shakapacker::Utils::VersionSyntaxConverter.new.rubygem_to_npm(Shakapacker::VERSION)
         begin
           @package_json.manager.add!(["shakapacker@#{npm_version}"], type: :production)
+          shakapacker_dependency_value = npm_version
         rescue PackageJson::Error
           say "Shakapacker installation failed 😭 See above for details.", :red
           exit 1
@@ -187,10 +191,10 @@ Dir.chdir(Rails.root) do
       exit 1
     end
   else
-    npm_version = Shakapacker::Utils::VersionSyntaxConverter.new.rubygem_to_npm(Shakapacker::VERSION)
     say "Installing shakapacker@#{npm_version}"
     begin
       @package_json.manager.add!(["shakapacker@#{npm_version}"], type: :production)
+      shakapacker_dependency_value = npm_version
     rescue PackageJson::Error
       say "Shakapacker installation failed 😭 See above for details.", :red
       exit 1
@@ -201,8 +205,8 @@ Dir.chdir(Rails.root) do
     if pj["dependencies"] && pj["dependencies"]["shakapacker"]
       {
         "dependencies" => pj["dependencies"].merge({
-          # TODO: workaround for test suite - long-run need to actually account for diff pkg manager behaviour
-          "shakapacker" => pj["dependencies"]["shakapacker"].delete_prefix("^")
+          # Keep package.json aligned with the exact source/version this installer requested.
+          "shakapacker" => shakapacker_dependency_value || pj["dependencies"]["shakapacker"].delete_prefix("^")
         })
       }
     else