v10.3.0

Added

• Allowed webpack-dev-server v6. PR #1102 by G-Rath.

Fixed

• Fixed implicit SWC defaults for existing webpack/Babel apps without swc-loader. PR #1206 by justin808. Webpack apps that omit both javascript_transpiler and the deprecated webpack_loader now fall back to Babel with a warning when Shakapacker's bundled SWC default is active, swc-loader is missing, and Babel is present. Explicit transpiler settings, webpack apps with swc-loader, and Rspack's built-in SWC path keep their existing behavior. Closes #1203.
• Fixed JavaScript config loading for missing Rails environments to use the production fallback. PR #1206 by justin808. When RAILS_ENV has no matching section in config/shakapacker.yml, the Node package config now merges the production section instead of only bundled defaults, matching Ruby configuration loading and honoring explicit production javascript_transpiler, source_path, dev_server, and related settings for custom environments such as staging.
• Fixed helper binstubs delegating Node resolution to Ruby exec in unset and empty PATH environments. PR #1200 and PR #1201 by justin808. Restores shell-compatible Node lookup for bin/shakapacker-config and bin/diff-bundler-config after the v10.2.0 Ruby-binstub regression, while keeping friendly missing-Node errors for ENOENT and EACCES.

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.

v10.1.0

Added

• Added supplemental npm packages shakapacker-webpack and shakapacker-rspack. PR #1096, PR #1133 by justin808. Optional packages that lockstep with core and declare the managed-build stack as required peer dependencies (so on npm 7+ a single yarn add shakapacker-webpack auto-installs shakapacker, webpack, webpack-cli, and webpack-assets-manifest; shakapacker-rspack declares shakapacker, @rspack/core, @rspack/cli, and rspack-manifest-plugin). Required peers eliminate the silent duplicate-bundler failure mode that direct dependencies could cause when an app or transitive dep pins a different bundler version. Optional features (transpilers, dev-server, CSS preprocessors, react-refresh) remain as opt-in peerDependencies so SCSS/native-binding bloat isn't forced on every install. The wrappers emit structured warnings (SHAKAPACKER_BUNDLER_MISMATCH, SHAKAPACKER_NO_TRANSPILER) when config.assets_bundler or javascript_transpiler doesn't match the installed peers. pnpm and Yarn PnP users should keep packages imported by app config files as explicit app dependencies (the Rails installer handles this automatically). See the v10.1 migration guide for adoption steps and docs/dependency-strategy.md for the design rationale and v11 roadmap.
• Added shakapacker:doctor check for disabled Rspack cache. PR #1100 by justin808. The doctor now inspects the Rspack config file for an explicit cache: false, warns when found (disabling cache causes significantly slower builds), and also flags Rspack v1 installs (where persistent cache is experimental) with a recommendation to upgrade to v2.
• Added a shakapacker:doctor hint to compiler output. PR #1100 by justin808. The compiler now logs a one-time tip suggesting bundle exec rake shakapacker:doctor after a failed compilation, so healthy build loops stay quiet.

Migration Notes

• Simplify your package.json by adopting a supplemental package. On npm 7+ (or Yarn 2+ in nodeLinker: node-modules mode), existing apps can drop the explicit managed-build deps from devDependencies and let the supplemental package's required peers be auto-installed:

  • Rspack apps can replace shakapacker + @rspack/core + @rspack/cli + rspack-manifest-plugin with a single shakapacker-rspack. See packages/shakapacker-rspack/README.md §"Simplifying an existing rspack install" for the before/after.
  • Webpack apps can replace shakapacker + webpack + webpack-cli + webpack-assets-manifest with a single shakapacker-webpack. See packages/shakapacker-webpack/README.md §"Simplifying an existing webpack install" for the before/after.
  • Optional peers (transpilers, webpack-dev-server, CSS preprocessors, react-refresh) stay only if your app uses those features.
  • Adoption is opt-in: leaving your package.json untouched on v10.1 also continues to work.

• Adopting shakapacker-webpack requires webpack-assets-manifest@^6.0.0. Core shakapacker still accepts both v5 and v6 (^5.0.6 || ^6.0.0), but shakapacker-webpack pins ~6.5.1. Apps still on webpack-assets-manifest@5.x must upgrade when switching to the supplemental package; v6 fixed an ENOENT crash on clean builds with merge: true and dropped a Node 14 install path. See the v5→v6 release notes and packages/shakapacker-webpack/README.md for details.

⚠️ Breaking Changes

• Breaking: tightened package.json engines.node to ^20.19.0 || >=22.12.0. PR #1099 by justin808. Raised from >= 20, dropping support for Node 20.0.0–20.18.x and Node 21.x to match @rspack/core@2.0.0-rc.0. Consumers on those versions will hit an engine error with --engine-strict or yarn workspaces and need to upgrade. The PR also bumps .node-version to 22.20.0 and updates conductor-setup.sh to enforce the same disjoint range up front, so contributors get a clear error before yarn install fails with a confusing engine mismatch.

Changed

• Changed shakapacker:install to default fresh Rspack installs to v2 (^2.0.0-0). PR #1091 by ihabadham. lib/install/package.json now declares @rspack/core and @rspack/cli as ^1.0.0 || ^2.0.0-0; fresh installs pick the v2 range. Existing apps are unaffected. Note: Rspack v2 requires Node.js 20.19.0+.
• Slimmed the published gem from ~486K (294 files) to ~121K (75 files). PR #1110, PR #1120 by justin808. Replaced the broad git ls-files gem manifest with an explicit runtime/install allowlist (CHANGELOG.md, MIT-LICENSE, README.md, gemspec, lib, sig, package.json), excluding repo-only docs, tests, JavaScript package source, CI/tooling files, and test_files metadata from the published gem. Fixes #987.

Fixed

• Fixed webpack-dev-server static config defaulting to watch public/ directory unnecessarily. PR #1032 by ihabadham. Three bugs fixed: (1) static now defaults to false instead of a misconfigured object that caused webpack-dev-server to watch the public/ directory, which is already served by Rails via ActionDispatch::Static; (2) setting static: false in shakapacker.yml is no longer silently ignored; (3) the default template no longer includes static.watch, which was a v3→v4 migration artifact. Fixes #1031.
• Fixed Rspack React Refresh plugin loading with @rspack/plugin-react-refresh v2. PR #1116 by justin808. Shakapacker now reads the v2 named ReactRefreshRspackPlugin export while retaining compatibility with v1 direct/default CommonJS export shapes, preventing TypeError: ReactRefreshRspackPlugin is not a constructor during rspack dev-server startup.
• Widened @rspack/plugin-react-refresh peer range to ^1.0.0 || ^2.0.0-0. PR #1091 by ihabadham. Fixes the ERESOLVE conflict when installing @rspack/plugin-react-refresh@^2.0.0 alongside shakapacker@10.0.0.
• Fixed NodePackageVersion#find_version for local-path shakapacker installs (e.g. yalc, file:, relative paths). PR #1086, PR #1106 by justin808. The version check now consults package.json first and short-circuits on ../, ./, and file: dependencies, so stale lockfile semvers no longer trigger false gem↔node version mismatches. package_json_dependency also consults devDependencies in addition to dependencies. The LOCAL_PATH_REGEX constant replaces a duplicated inline regex and anchors both alternatives to the start of the string, removing a latent false-positive on version strings containing .. mid-value. Fixes #1103.
• Fix rspack setup not reusing certain shared webpack-rspack config settings. PR #1085 by brunodccarvalho. Default config changes include optimization.splitChunks.chunks="all", optimization.runtimeChunk="single", the webpack compression plugin in production, and the removal of minimization plugins in development. Fixes #984.
• Fixed Rspack Sass rule blocking sass-embedded users by requiring the sass package. PR #1105 by justin808. Rspack Sass detection now only checks for sass-loader; the implementation (sass, sass-embedded, etc.) is resolved by the loader at build time, matching the webpack code path.
• Fixed bin/shakapacker-config and bin/diff-bundler-config in ESM apps and on upgraded apps. PR #1104, PR #1132 by justin808. Apps with "type": "module" in package.json failed to run the JavaScript binstubs because Node parsed them as ESM. The binstubs are now Ruby wrappers that locate Node (without executing it during lookup) and invoke .cjs package scripts shipped inside node_modules/shakapacker/package/bin/. The wrappers also map NODE_ENV from RAILS_ENV and print useful messages for non-Error CLI rejections. shakapacker:export_bundler_config dispatches binstubs by shebang, so upgraded apps with legacy JavaScript binstubs continue to run via Node while Ruby wrappers run via Ruby. Existing apps with the old JavaScript binstubs should re-run bundle exec rake shakapacker:binstubs to install the new Ruby wrappers. Fixes #1123.

v10.1.0-rc.2

Added

• Added supplemental npm packages shakapacker-webpack and shakapacker-rspack. PR #1096 by justin808. Optional packages that lockstep with core and bundle the managed-build stack as direct dependencies (so a single yarn add shakapacker-webpack pulls in shakapacker, webpack, webpack-cli, and webpack-assets-manifest; the rspack package bundles shakapacker, @rspack/core, @rspack/cli, and rspack-manifest-plugin). Optional features (transpilers, dev-server, CSS preprocessors, react-refresh) remain as opt-in peerDependencies so SCSS/native-binding bloat isn't forced on every install. The wrappers emit structured warnings (SHAKAPACKER_BUNDLER_MISMATCH, SHAKAPACKER_NO_TRANSPILER) when config.assets_bundler or javascript_transpiler doesn't match the installed peers. See the v10.1 migration guide for adoption steps and docs/dependency-strategy.md for the design rationale and v11 roadmap.
• Added shakapacker:doctor check for disabled Rspack cache. PR #1100 by justin808. The doctor now inspects the Rspack config file for an explicit cache: false, warns when found (disabling cache causes significantly slower builds), and also flags Rspack v1 installs (where persistent cache is experimental) with a recommendation to upgrade to v2.
• Added a shakapacker:doctor hint to compiler output. PR #1100 by justin808. The compiler now logs a one-time tip suggesting bundle exec rake shakapacker:doctor after a failed compilation, so healthy build loops stay quiet.

Migration Notes

• Simplify your package.json by adopting a supplemental package. Existing apps can drop the explicit managed-build deps from devDependencies and rely on the bundled stack:

  • Rspack apps can replace shakapacker + @rspack/core + @rspack/cli + rspack-manifest-plugin with a single shakapacker-rspack. See packages/shakapacker-rspack/README.md §"Simplifying an existing rspack install" for the before/after.
  • Webpack apps can replace shakapacker + webpack + webpack-cli + webpack-assets-manifest with a single shakapacker-webpack. See packages/shakapacker-webpack/README.md §"Simplifying an existing webpack install" for the before/after.
  • Optional peers (transpilers, webpack-dev-server, CSS preprocessors, react-refresh) stay only if your app uses those features.
  • Adoption is opt-in: leaving your package.json untouched on v10.1 also continues to work.

• Adopting shakapacker-webpack requires webpack-assets-manifest@^6.0.0. Core shakapacker still accepts both v5 and v6 (^5.0.6 || ^6.0.0), but shakapacker-webpack pins ~6.5.1. Apps still on webpack-assets-manifest@5.x must upgrade when switching to the supplemental package; v6 fixed an ENOENT crash on clean builds with merge: true and dropped a Node 14 install path. See the v5→v6 release notes and packages/shakapacker-webpack/README.md for details.

⚠️ Breaking Changes

• Breaking: tightened package.json engines.node to ^20.19.0 || >=22.12.0. PR #1099 by justin808. Raised from >= 20, dropping support for Node 20.0.0–20.18.x and Node 21.x to match @rspack/core@2.0.0-rc.0. Consumers on those versions will hit an engine error with --engine-strict or yarn workspaces and need to upgrade. The PR also bumps .node-version to 22.20.0 and updates conductor-setup.sh to enforce the same disjoint range up front, so contributors get a clear error before yarn install fails with a confusing engine mismatch.

Changed

• Restructured shakapacker-webpack and shakapacker-rspack dependency declarations. PR #1133 by justin808. In response to #1131, bundler singletons (webpack, webpack-cli, webpack-assets-manifest for webpack; @rspack/core, @rspack/cli, rspack-manifest-plugin for rspack) are now required peer dependencies instead of direct dependencies. This eliminates the silent duplicate-bundler failure mode that direct deps could cause when an app or transitive dep pinned a different bundler version. npm 7+ auto-installs required peers, preserving the one-command install experience there; pnpm and Yarn PnP users should keep packages imported by app config files as explicit app dependencies (the Rails installer handles this automatically). The tilde (~) constraints from the v10.1.0-rc.1 shape have also been loosened to caret (^) for all non-shakapacker packages, so consumers can pick up upstream patch/minor releases without waiting for a coordinated Shakapacker release. terser-webpack-plugin moved from optional peer to direct dependency on shakapacker-webpack because package/optimization/webpack.ts always requires it for the default production minimizer.
• Changed shakapacker:install to default fresh Rspack installs to v2 (^2.0.0-0). PR #1091 by ihabadham. lib/install/package.json now declares @rspack/core and @rspack/cli as ^1.0.0 || ^2.0.0-0; fresh installs pick the v2 range. Existing apps are unaffected. Note: Rspack v2 requires Node.js 20.19.0+.
• Slimmed the published gem from ~486K (294 files) to ~121K (75 files). PR #1110, PR #1120 by justin808. Replaced the broad git ls-files gem manifest with an explicit runtime/install allowlist (CHANGELOG.md, MIT-LICENSE, README.md, gemspec, lib, sig, package.json), excluding repo-only docs, tests, JavaScript package source, CI/tooling files, and test_files metadata from the published gem. Fixes #987.

Fixed

• Fixed config helper binstubs and shakapacker:export_bundler_config dispatch for upgraded apps. PR #1132 by justin808. The export task now runs legacy JavaScript bin/shakapacker-config binstubs via Node while keeping Ruby binstubs on Ruby. Generated helper binstubs now map NODE_ENV from RAILS_ENV, locate Node without executing it during lookup, and print useful messages for non-Error CLI rejections. Fixes #1123.
• Fixed webpack-dev-server static config defaulting to watch public/ directory unnecessarily. PR #1032 by ihabadham. Three bugs fixed: (1) static now defaults to false instead of a misconfigured object that caused webpack-dev-server to watch the public/ directory, which is already served by Rails via ActionDispatch::Static; (2) setting static: false in shakapacker.yml is no longer silently ignored; (3) the default template no longer includes static.watch, which was a v3→v4 migration artifact. Fixes #1031.
• Fixed Rspack React Refresh plugin loading with @rspack/plugin-react-refresh v2. PR #1116 by justin808. Shakapacker now reads the v2 named ReactRefreshRspackPlugin export while retaining compatibility with v1 direct/default CommonJS export shapes, preventing TypeError: ReactRefreshRspackPlugin is not a constructor during rspack dev-server startup.
• Widened @rspack/plugin-react-refresh peer range to ^1.0.0 || ^2.0.0-0. PR #1091 by ihabadham. Fixes the ERESOLVE conflict when installing @rspack/plugin-react-refresh@^2.0.0 alongside shakapacker@10.0.0.
• Fixed NodePackageVersion#find_version for local-path shakapacker installs (e.g. yalc, file:, relative paths). PR #1086 by justin808. The version check now consults package.json first and short-circuits on ../ or file: dependencies, so stale lockfile semvers no longer trigger false gem↔node version mismatches. package_json_dependency also consults devDependencies in addition to dependencies. The LOCAL_PATH_REGEX constant replaces a duplicated inline regex and anchors both alternatives to the start of the string, removing a latent false-positive on version strings containing .. mid-value.
• Detected single-dot (./...) local-path declarations in NodePackageVersion#find_version. PR #1106 by justin808. Extended LOCAL_PATH_REGEX to treat ./vendor/shakapacker-style declarations as local-path installs (alongside the ../ and file: patterns added in #1086), so version checks short-circuit before consulting potentially stale lockfile semvers. Fixes #1103.
• Fix rspack setup not reusing certain shared webpack-rspack config settings. PR #1085 by brunodccarvalho. Default config changes include optimization.splitChunks.chunks="all", optimization.runtimeChunk="single", the webpac...

v10.1.0-rc.1

Added

• Added supplemental npm packages shakapacker-webpack and shakapacker-rspack. PR #1096 by justin808. Optional packages that lockstep with core and bundle the managed-build stack as direct dependencies (so a single yarn add shakapacker-webpack pulls in shakapacker, webpack, webpack-cli, and webpack-assets-manifest; the rspack package bundles shakapacker, @rspack/core, @rspack/cli, and rspack-manifest-plugin). Optional features (transpilers, dev-server, CSS preprocessors, react-refresh) remain as opt-in peerDependencies so SCSS/native-binding bloat isn't forced on every install. The wrappers emit structured warnings (SHAKAPACKER_BUNDLER_MISMATCH, SHAKAPACKER_NO_TRANSPILER) when config.assets_bundler or javascript_transpiler doesn't match the installed peers. See the v10.1 migration guide for adoption steps and docs/dependency-strategy.md for the design rationale and v11 roadmap.
• Added shakapacker:doctor check for disabled Rspack cache. PR #1100 by justin808. The doctor now inspects the Rspack config file for an explicit cache: false, warns when found (disabling cache causes significantly slower builds), and also flags Rspack v1 installs (where persistent cache is experimental) with a recommendation to upgrade to v2.
• Added a shakapacker:doctor hint to compiler output. PR #1100 by justin808. The compiler now logs a one-time tip suggesting bundle exec rake shakapacker:doctor after a failed compilation, so healthy build loops stay quiet.

Migration Notes

• Simplify your package.json by adopting a supplemental package. Existing apps can drop the explicit managed-build deps from devDependencies and rely on the bundled stack:

  • Rspack apps can replace shakapacker + @rspack/core + @rspack/cli + rspack-manifest-plugin with a single shakapacker-rspack. See packages/shakapacker-rspack/README.md §"Simplifying an existing rspack install" for the before/after.
  • Webpack apps can replace shakapacker + webpack + webpack-cli + webpack-assets-manifest with a single shakapacker-webpack. See packages/shakapacker-webpack/README.md §"Simplifying an existing webpack install" for the before/after.
  • Optional peers (transpilers, webpack-dev-server, CSS preprocessors, react-refresh) stay only if your app uses those features.
  • Adoption is opt-in: leaving your package.json untouched on v10.1 also continues to work.

• Adopting shakapacker-webpack requires webpack-assets-manifest@^6.0.0. Core shakapacker still accepts both v5 and v6 (^5.0.6 || ^6.0.0), but shakapacker-webpack pins ~6.5.1. Apps still on webpack-assets-manifest@5.x must upgrade when switching to the supplemental package; v6 fixed an ENOENT crash on clean builds with merge: true and dropped a Node 14 install path. See the v5→v6 release notes and packages/shakapacker-webpack/README.md for details.

⚠️ Breaking Changes

• Breaking: tightened package.json engines.node to ^20.19.0 || >=22.12.0. PR #1099 by justin808. Raised from >= 20, dropping support for Node 20.0.0–20.18.x and Node 21.x to match @rspack/core@2.0.0-rc.0. Consumers on those versions will hit an engine error with --engine-strict or yarn workspaces and need to upgrade. The PR also bumps .node-version to 22.20.0 and updates conductor-setup.sh to enforce the same disjoint range up front, so contributors get a clear error before yarn install fails with a confusing engine mismatch.

Changed

• Changed shakapacker:install to default fresh Rspack installs to v2 (^2.0.0-0). PR #1091 by ihabadham. lib/install/package.json now declares @rspack/core and @rspack/cli as ^1.0.0 || ^2.0.0-0; fresh installs pick the v2 range. Existing apps are unaffected. Note: Rspack v2 requires Node.js 20.19.0+.
• Slimmed the published gem from ~486K (294 files) to ~121K (75 files). PR #1110 by justin808. Replaced the broad git ls-files gem manifest with an explicit runtime/install allowlist (CHANGELOG.md, MIT-LICENSE, README.md, gemspec, lib, sig), excluding repo-only docs, tests, JavaScript package source, CI/tooling files, and test_files metadata from the published gem. Fixes #987.

Fixed

• Fixed webpack-dev-server static config defaulting to watch public/ directory unnecessarily. PR #1032 by ihabadham. Three bugs fixed: (1) static now defaults to false instead of a misconfigured object that caused webpack-dev-server to watch the public/ directory, which is already served by Rails via ActionDispatch::Static; (2) setting static: false in shakapacker.yml is no longer silently ignored; (3) the default template no longer includes static.watch, which was a v3→v4 migration artifact. Fixes #1031.
• Fixed Rspack React Refresh plugin loading with @rspack/plugin-react-refresh v2. PR #1116 by justin808. Shakapacker now reads the v2 named ReactRefreshRspackPlugin export while retaining compatibility with v1 direct/default CommonJS export shapes, preventing TypeError: ReactRefreshRspackPlugin is not a constructor during rspack dev-server startup.
• Widened @rspack/plugin-react-refresh peer range to ^1.0.0 || ^2.0.0-0. PR #1091 by ihabadham. Fixes the ERESOLVE conflict when installing @rspack/plugin-react-refresh@^2.0.0 alongside shakapacker@10.0.0.
• Fixed NodePackageVersion#find_version for local-path shakapacker installs (e.g. yalc, file:, relative paths). PR #1086 by justin808. The version check now consults package.json first and short-circuits on ../ or file: dependencies, so stale lockfile semvers no longer trigger false gem↔node version mismatches. package_json_dependency also consults devDependencies in addition to dependencies. The LOCAL_PATH_REGEX constant replaces a duplicated inline regex and anchors both alternatives to the start of the string, removing a latent false-positive on version strings containing .. mid-value.
• Detected single-dot (./...) local-path declarations in NodePackageVersion#find_version. PR #1106 by justin808. Extended LOCAL_PATH_REGEX to treat ./vendor/shakapacker-style declarations as local-path installs (alongside the ../ and file: patterns added in #1086), so version checks short-circuit before consulting potentially stale lockfile semvers. Fixes #1103.
• Fix rspack setup not reusing certain shared webpack-rspack config settings. PR #1085 by brunodccarvalho. Default config changes include optimization.splitChunks.chunks="all", optimization.runtimeChunk="single", the webpack compression plugin in production, and the removal of minimization plugins in development. Fixes #984.
• Fixed Rspack Sass rule blocking sass-embedded users by requiring the sass package. PR #1105 by justin808. Rspack Sass detection now only checks for sass-loader; the implementation (sass, sass-embedded, etc.) is resolved by the loader at build time, matching the webpack code path.
• Fixed bin/shakapacker-config and bin/diff-bundler-config in ESM apps. PR #1104 by justin808. Apps with "type": "module" in package.json failed to run the JavaScript binstubs because Node parsed them as ESM. The binstubs are now Ruby wrappers that locate Node and invoke .cjs package scripts shipped inside node_modules/shakapacker/package/bin/. Existing apps with the old JavaScript binstubs should re-run bundle exec rake shakapacker:binstubs to install the new Ruby wrappers.

v10.1.0-rc.0

Added

• Added supplemental npm packages shakapacker-webpack and shakapacker-rspack. PR #1096 by justin808. Optional packages that lockstep with core and bundle the managed-build stack as direct dependencies (so a single yarn add shakapacker-webpack pulls in shakapacker, webpack, webpack-cli, and webpack-assets-manifest; the rspack package bundles shakapacker, @rspack/core, @rspack/cli, and rspack-manifest-plugin). Optional features (transpilers, dev-server, CSS preprocessors, react-refresh) remain as opt-in peerDependencies so SCSS/native-binding bloat isn't forced on every install. The wrappers emit structured warnings (SHAKAPACKER_BUNDLER_MISMATCH, SHAKAPACKER_NO_TRANSPILER) when config.assets_bundler or javascript_transpiler doesn't match the installed peers. See the v10.1 migration guide for adoption steps and docs/dependency-strategy.md for the design rationale and v11 roadmap.
• Added shakapacker:doctor check for disabled Rspack cache. PR #1100 by justin808. The doctor now inspects the Rspack config file for an explicit cache: false, warns when found (disabling cache causes significantly slower builds), and also flags Rspack v1 installs (where persistent cache is experimental) with a recommendation to upgrade to v2.
• Added a shakapacker:doctor hint to compiler output. PR #1100 by justin808. The compiler now logs a one-time tip suggesting bundle exec rake shakapacker:doctor after a failed compilation, so healthy build loops stay quiet.

Migration Notes

• Simplify your package.json by adopting a supplemental package. Existing apps can drop the explicit managed-build deps from devDependencies and rely on the bundled stack:

  • Rspack apps can replace shakapacker + @rspack/core + @rspack/cli + rspack-manifest-plugin with a single shakapacker-rspack. See packages/shakapacker-rspack/README.md §"Simplifying an existing rspack install" for the before/after.
  • Webpack apps can replace shakapacker + webpack + webpack-cli + webpack-assets-manifest with a single shakapacker-webpack. See packages/shakapacker-webpack/README.md §"Simplifying an existing webpack install" for the before/after.
  • Optional peers (transpilers, webpack-dev-server, CSS preprocessors, react-refresh) stay only if your app uses those features.
  • Adoption is opt-in: leaving your package.json untouched on v10.1 also continues to work.

• Adopting shakapacker-webpack requires webpack-assets-manifest@^6.0.0. Core shakapacker still accepts both v5 and v6 (^5.0.6 || ^6.0.0), but shakapacker-webpack pins ~6.5.1. Apps still on webpack-assets-manifest@5.x must upgrade when switching to the supplemental package; v6 fixed an ENOENT crash on clean builds with merge: true and dropped a Node 14 install path. See the v5→v6 release notes and packages/shakapacker-webpack/README.md for details.

⚠️ Breaking Changes

• Breaking: tightened package.json engines.node to ^20.19.0 || >=22.12.0. PR #1099 by justin808. Raised from >= 20, dropping support for Node 20.0.0–20.18.x and Node 21.x to match @rspack/core@2.0.0-rc.0. Consumers on those versions will hit an engine error with --engine-strict or yarn workspaces and need to upgrade. The PR also bumps .node-version to 22.20.0 and updates conductor-setup.sh to enforce the same disjoint range up front, so contributors get a clear error before yarn install fails with a confusing engine mismatch.

Changed

• Changed shakapacker:install to default fresh Rspack installs to v2 (^2.0.0-0). PR #1091 by ihabadham. lib/install/package.json now declares @rspack/core and @rspack/cli as ^1.0.0 || ^2.0.0-0; fresh installs pick the v2 range. Existing apps are unaffected. Note: Rspack v2 requires Node.js 20.19.0+.
• Slimmed the published gem from ~486K (294 files) to ~121K (75 files). PR #1110 by justin808. Replaced the broad git ls-files gem manifest with an explicit runtime/install allowlist (CHANGELOG.md, MIT-LICENSE, README.md, gemspec, lib, sig), excluding repo-only docs, tests, JavaScript package source, CI/tooling files, and test_files metadata from the published gem. Fixes #987.

Fixed

• Fixed Rspack React Refresh plugin loading with @rspack/plugin-react-refresh v2. PR #1116 by justin808. Shakapacker now reads the v2 named ReactRefreshRspackPlugin export while retaining compatibility with v1 direct/default CommonJS export shapes, preventing TypeError: ReactRefreshRspackPlugin is not a constructor during rspack dev-server startup.
• Widened @rspack/plugin-react-refresh peer range to ^1.0.0 || ^2.0.0-0. PR #1091 by ihabadham. Fixes the ERESOLVE conflict when installing @rspack/plugin-react-refresh@^2.0.0 alongside shakapacker@10.0.0.
• Fixed NodePackageVersion#find_version for local-path shakapacker installs (e.g. yalc, file:, relative paths). PR #1086 by justin808. The version check now consults package.json first and short-circuits on ../ or file: dependencies, so stale lockfile semvers no longer trigger false gem↔node version mismatches. package_json_dependency also consults devDependencies in addition to dependencies. The LOCAL_PATH_REGEX constant replaces a duplicated inline regex and anchors both alternatives to the start of the string, removing a latent false-positive on version strings containing .. mid-value.
• Detected single-dot (./...) local-path declarations in NodePackageVersion#find_version. PR #1106 by justin808. Extended LOCAL_PATH_REGEX to treat ./vendor/shakapacker-style declarations as local-path installs (alongside the ../ and file: patterns added in #1086), so version checks short-circuit before consulting potentially stale lockfile semvers. Fixes #1103.
• Fix rspack setup not reusing certain shared webpack-rspack config settings. PR #1085 by brunodccarvalho. Default config changes include optimization.splitChunks.chunks="all", optimization.runtimeChunk="single", the webpack compression plugin in production, and the removal of minimization plugins in development. Fixes #984.

v10.0.0

Added

• Added bin/diff-bundler-config CLI for semantic bundler configuration diffs. PR #973 by justin808. Wraps the extracted pack-config-diff package to provide semantic diffing of webpack/rspack configurations with normalized exit codes. Supersedes #961.
• Added bin/shakapacker-watch binstub for clean Ctrl-C shutdown in Procfile-based workflows. PR #1026 by justin808. The new wrapper script traps INT/TERM signals and forwards TERM to the underlying bin/shakapacker --watch process, preventing Ruby interrupt backtraces when stopping bin/dev. Use bin/shakapacker-watch --watch in Procfiles instead of bin/shakapacker --watch.
• Allowed webpack-cli v7 (^7.0.0) in peer dependencies. PR #1021 by justin808. Fixes #1020. Note: webpack-cli v7 requires Node.js >= 20.9.0.

⚠️ Breaking Changes

• Breaking: bumped the minimum webpack version to ^5.101.0. PR #1021 by justin808. The previous minimum was ^5.76.0.
• Breaking: required webpack-dev-server ^5.2.2 and dropped support for v4. PR #1021 by justin808. The removed v4 range was ^4.15.2.

Changed

• Changed shakapacker:install to default webpack-cli installs to the latest v6 range. PR #1021 by justin808. This keeps installs compatible with Node.js 20.0-20.8; v7 remains supported via peer dependencies for Node.js >= 20.9.0.
• Changed dev server config handling to warn on deprecated middleware hooks and ignore them for webpack-dev-server v5. PR #1021 by justin808. Use setup_middlewares instead of on_before_setup_middleware and on_after_setup_middleware.

Fixed

• Ensured shakapacker:install installs the latest compression-webpack-plugin. PR #1035 by G-Rath.

v10.0.0-rc.1

Added

• Added bin/diff-bundler-config CLI for semantic bundler configuration diffs. PR #973 by justin808. Wraps the extracted pack-config-diff package to provide semantic diffing of webpack/rspack configurations with normalized exit codes. Supersedes #961.
• Added bin/shakapacker-watch binstub for clean Ctrl-C shutdown in Procfile-based workflows. PR #1026 by justin808. The new wrapper script traps INT/TERM signals and forwards TERM to the underlying bin/shakapacker --watch process, preventing Ruby interrupt backtraces when stopping bin/dev. Use bin/shakapacker-watch --watch in Procfiles instead of bin/shakapacker --watch.
• Allowed webpack-cli v7 (^7.0.0) in peer dependencies. PR #1021 by justin808. Fixes #1020. Note: webpack-cli v7 requires Node.js >= 20.9.0.

⚠️ Breaking Changes

• Breaking: bumped the minimum webpack version to ^5.101.0. PR #1021 by justin808. The previous minimum was ^5.76.0.
• Breaking: required webpack-dev-server ^5.2.2 and dropped support for v4. PR #1021 by justin808. The removed v4 range was ^4.15.2.

Changed

• Changed shakapacker:install to default webpack-cli installs to the latest v6 range. PR #1021 by justin808. This keeps installs compatible with Node.js 20.0-20.8; v7 remains supported via peer dependencies for Node.js >= 20.9.0.
• Changed dev server config handling to warn on deprecated middleware hooks and ignore them for webpack-dev-server v5. PR #1021 by justin808. Use setup_middlewares instead of on_before_setup_middleware and on_after_setup_middleware.

Fixed

• Ensured shakapacker:install installs the latest compression-webpack-plugin. PR #1035 by G-Rath.

v10.0.0-rc.0

Added

• Added bin/shakapacker-watch binstub for clean Ctrl-C shutdown in Procfile-based workflows. PR #1026 by justin808. The new wrapper script traps INT/TERM signals and forwards TERM to the underlying bin/shakapacker --watch process, preventing Ruby interrupt backtraces when stopping bin/dev. Use bin/shakapacker-watch --watch in Procfiles instead of bin/shakapacker --watch.
• Allowed webpack-cli v7 (^7.0.0) in peer dependencies. PR #1021 by justin808. Fixes #1020. Note: webpack-cli v7 requires Node.js >= 20.9.0.

⚠️ Breaking Changes

• Breaking: bumped the minimum webpack version to ^5.101.0. PR #1021 by justin808. The previous minimum was ^5.76.0.
• Breaking: required webpack-dev-server ^5.2.2 and dropped support for v4. PR #1021 by justin808. The removed v4 range was ^4.15.2.

Changed

• Changed shakapacker:install to default webpack-cli installs to the latest v6 range. PR #1021 by justin808. This keeps installs compatible with Node.js 20.0-20.8; v7 remains supported via peer dependencies for Node.js >= 20.9.0.
• Changed dev server config handling to warn on deprecated middleware hooks and ignore them for webpack-dev-server v5. PR #1021 by justin808. Use setup_middlewares instead of on_before_setup_middleware and on_after_setup_middleware.

Fixed

• Ensured shakapacker:install installs the latest compression-webpack-plugin. PR #1035 by G-Rath.

v9.7.0

Added

• Added rspack v2 support. PR #975 by justin808. Peer dependencies now accept both rspack v1 and v2 (^1.0.0 || ^2.0.0-0). No source code changes were needed — all existing APIs work identically in v2. Note that rspack v2 requires Node.js 20.19.0+.

Fixed

• Fixed config exporter path traversal and annotation format validation. PR #914 by justin808. Added safeResolvePath security check to prevent path traversal in export save paths, and enforced YAML format when using annotations with build exports.
• Fixed webpack-subresource-integrity v5 named export handling. PR #978 by justin808. Supports both the default export (older versions) and the named SubresourceIntegrityPlugin export (v5.1+), preventing runtime breakage when upgrading the plugin. Fixes #972.