v10.2.0

Added

• Added webpack_compile_flags configuration. PR #1180 by justin808. Allows Rails-driven Shakapacker compiles to pass extra webpack/rspack CLI flags, such as --fail-on-warnings or --progress, through bin/shakapacker. Fixes #1175.
• Added AI analysis prompt generation to the config exporter. PR #695, PR #1184 by justin808. When running doctor mode (bin/shakapacker-config --doctor), the exporter now also writes an AI-ANALYSIS-PROMPT.md: a ready-to-paste prompt that guides an AI assistant (ChatGPT, Claude, Gemini, etc.) to review the configuration for migration issues (webpack ↔ rspack), build errors, client/server and development/production optimizations, and best practices. The React on Rails–specific guidance in the generated prompt is included only when React on Rails is detected in the app (via package.json, Gemfile, or Gemfile.lock). This is purely additive; existing exports are unchanged, and a failure to write the prompt file only warns without affecting the exported configs.
• Added support for sass-loader v17. PR #1141 by fukayatsu. Widened the optional sass-loader peer range to ^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0 in core shakapacker, shakapacker-webpack, and shakapacker-rspack. The Sass rule already selects loadPaths for v16+ and keeps api: "modern", both of which remain valid in v17. Note that sass-loader v17 requires Node.js 22.11.0+ and drops node-sass and the legacy Sass JS API, so apps that opt into v17 must already be on Node 22.12+ (the upper branch of Shakapacker's engines.node range).
• Added Babel 8 peer dependency support. PR #1187 by justin808. Widened the Babel peer ranges in core shakapacker and the shakapacker-webpack supplemental package to allow Babel 8, and updated the Shakapacker Babel preset to omit options removed in Babel 8 while preserving existing Babel 7 behavior. Repository development pins stay on Babel 7, with added compatibility tests covering Babel 8. Refs #1163.

Changed

• New installs now default to Rspack instead of webpack. PR #1150 by justin808. bundle exec rake shakapacker:install now scaffolds an Rspack project (config, dependencies, and config/shakapacker.yml) by default. This is a new-install default only: existing applications are unaffected. The Rspack default applies only to brand-new installs — re-running the installer on an app that already has a config/shakapacker.yml keeps that app's current bundler (and installs that bundler's dependencies), so the installer never silently switches an existing project's bundler. To install with webpack, run bundle exec rake shakapacker:install[webpack] or set SHAKAPACKER_ASSETS_BUNDLER=webpack; to change an existing app's bundler, use bundle exec rake shakapacker:switch_bundler.
• Changed Rspack support to target Rspack v2 only. PR #1179 by justin808. Core, installer, switch-bundler defaults, supplemental package, dummy app, and docs now use @rspack/core, @rspack/cli, @rspack/dev-server, and @rspack/plugin-react-refresh v2 ranges. Rspack installs now also require rspack-manifest-plugin@^5.2.2, and shakapacker-rspack requires css-loader@^7.1.4 for Rspack v2 peer compatibility. The Rspack React Refresh loader now uses the v2 named ReactRefreshRspackPlugin export instead of retaining legacy v1 export-shape fallbacks.

Fixed

• Fixed helper binstubs and doctor checks for subdirectory JavaScript layouts. PR #1192 by justin808. bin/shakapacker-config and bin/diff-bundler-config now resolve package scripts from a configured client package root before falling back to the Rails root, and shakapacker:doctor now searches package metadata, lockfiles, and installed packages across client/root layouts while reducing false SWC dependency issues for custom hybrid webpack/Rspack setups. Fixes #1170 and #1090.
• Fixed dev-server passthrough argument validation messages. PR #1180 by justin808. bin/shakapacker-dev-server -- --host ... or --port ... now fails with a clearer Shakapacker message instead of forwarding the separator to the bundler; set dev_server.host and dev_server.port in config/shakapacker.yml instead.
• Fixed shakapacker:export_bundler_config regression on apps upgraded from older Shakapacker versions. PR #1127 by justin808. The task previously invoked bin/shakapacker-config unconditionally via RbConfig.ruby, which crashed when the file was still the legacy JavaScript binstub (#!/usr/bin/env node) left over from earlier installs. The task now inspects the shebang and exec's the file directly when it points at Node, while keeping the Ruby+RbConfig.ruby path for the current Ruby binstub. Affected users are also nudged to run bundle exec rake shakapacker:binstubs to refresh their helper binstub. Refs #1123.
• Fixed shakapacker:doctor Sass implementation detection for sass-embedded apps. PR #1178 by justin808. The doctor now accepts either modern Sass implementation package (sass or sass-embedded) when Sass files are present, matching Shakapacker's default modern Sass API instead of incorrectly requiring Dart Sass. New installs also include sass alongside sass-loader. Fixes #1172.
• Fixed Psych::DisallowedClass boot crash when pnpm-lock.yaml contains a time: section. PR #1161 by justin808. pnpm >= 10.16 (default in pnpm 11) writes publish timestamps into pnpm-lock.yaml that Psych 4+ refuses to safe-load, so the shakapacker.version_checker boot initializer raised Psych::DisallowedClass: Tried to load unspecified class: Time and crashed every Rails boot — even when version checking was disabled. The lockfile is now parsed with YAML.safe_load(..., permitted_classes: [Time, Date]). Fixes #1160.
• Fixed Rspack dev-server lazy compilation defaults for Rails split dev-server topology. PR #1179 by justin808. Generated Rspack development configs now set top-level lazyCompilation: false while the dev server is running, preventing Rspack CLI dev-server auto-lazy behavior from routing dynamic imports through lazy trigger URLs Rails does not serve. Apps that intentionally use lazy compilation can still set a safe top-level lazyCompilation value in their Rspack config.
• Fixed Rspack dev-server config loading during static watch builds. PR #1142 by justin808. The Rspack devServer configuration is now gated behind WEBPACK_SERVE=true, matching the webpack development config, so static watch builds (bin/shakapacker --watch) no longer load the dev-server client. The devMiddleware.writeToDisk filter that skips hot-update files is preserved. Fixes #1137.
• Fixed compiler strategies ignoring the instance config of custom Shakapacker::Instance objects. PR #1147 by justin808. Ports #976 by brunodccarvalho. Strategies now read the instance-specific config and watch both webpack and rspack config directories.