shakapacker 10.3.0 → 10.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9066233e8c71edd7018db4b397e132013a8dcde79a111acbd6f3a79617fa9367
-  data.tar.gz: 1e7d899486f7bf0c43cebb923ba4a013bd5bdb7e4348193662872a5b77278208
+  metadata.gz: d74b345013f03450e4cd5050bd22f2364e2acf8b00a750acf833b07eda6046c7
+  data.tar.gz: 4933ffb9d1feb7acc0bdcb2a06fb492b030ea347976da728dd83a7e4b7f3790f
 SHA512:
-  metadata.gz: 6becce7cfd7598aeb8b6cb734882e0dbd6668125e61c711608d81e242724c8b27d613efdf5cecff77e737ca46d8f8c5c727938c5bbb13551f3394f7149d495a0
-  data.tar.gz: f56d65242942ce8ce7b372af52b28a7a62dd6ce47c7fce5b4268bd638d22691276166796620179682b0b61ad2cc4028d951219d208652f84a99cb60bf0d8757a
+  metadata.gz: 1a286328ea129dc5e2c9baad6fae0aaeec4c886533a10489301e3396fd45ac3fb9b3db35455407de79eda6506d983c0a474ba7c69ea2e68eed99b715700ae274
+  data.tar.gz: 1411acd0a7475961d10fc0a8e99bfa76e235b1c9e83ff7e9a152f726c578e2ac0cb5654dced3a52a492e62d75fc741cf68f8a6cd0deabc23ed294229e87a874e

data/CHANGELOG.md

@@ -10,6 +10,35 @@
 
 ## [Unreleased]
 
+## [v10.3.2] - August 28, 2026
+
+### Changed
+
+- **Bumped the development and CI pin for Rspack from `2.0.1` to `2.2.0`.** [PR #1258](https://github.com/shakacode/shakapacker/pull/1258) by [justin808](https://github.com/justin808). The `@rspack/core`, `@rspack/cli`, `@rspack/dev-server`, and `@rspack/plugin-react-refresh` peer ranges are unchanged at `^2.0.0`, so applications may stay on any Rspack `2.x` release; only this repository's own development pins and dummy-app lockfiles move, so CI now exercises Rspack 2.2 against the range it already advertises. Annotated config exports (`bin/shakapacker-config --annotate`) also now list the complete `optimization.moduleIds` and `optimization.chunkIds` value sets for both bundlers, including `'compat-hashed'`, which requires Rspack 2.2 or newer and is documented as opt-in rather than made a default.
+
+### Fixed
+
+- **Fixed `shakapacker:doctor` not telling Rspack apps that a `.swcrc` is ignored outright.** [PR #1276](https://github.com/shakacode/shakapacker/pull/1276) by [justin808](https://github.com/justin808). Doctor previously told Rspack apps only that moving `.swcrc` settings into `config/swc.config.js` would not help, while deliberately making no claim about the `.swcrc` itself, because the behavior had never been verified. It has now been verified against `@rspack/core` 2.0.1 and 2.2.0: Rspack's `builtin:swc-loader` never reads `.swcrc`. A `.swcrc` setting `jsc.target` and injecting an optimizer global produced byte-identical output to no `.swcrc` at all, while the same options passed inline as loader options did change the output. A `.swcrc` enabling decorator syntax likewise failed to unblock a decorator source, including with empty loader options and with `swcrc`/`configFile` set, so this is not merely inline options taking precedence. Doctor now states that a `.swcrc` is not read on Rspack and that every setting in it is silently inert - the mirror image of the `config/swc.config.js` case in [#1259](https://github.com/shakacode/shakapacker/issues/1259) - and continues to point at overriding the built-in `builtin:swc-loader` rule. Webpack messaging is unchanged. Fixes [#1263](https://github.com/shakacode/shakapacker/issues/1263).
+- **Fixed `shakapacker:doctor` staying silent about SWC configuration on Rspack apps that do not set `javascript_transpiler: swc`.** [PR #1269](https://github.com/shakacode/shakapacker/pull/1269) by [justin808](https://github.com/justin808). Shakapacker's Rspack rules always transpile with `builtin:swc-loader` and never consult `javascript_transpiler`, so `config/swc.config.js` goes unread on an Rspack app configured for Babel or esbuild exactly as it does on one configured for SWC. Doctor's Rspack SWC-configuration warnings were gated on `javascript_transpiler: swc`, so those apps got no warning at all. Those warnings now reach any Rspack app: that `config/swc.config.js` is not read, and, for a `.swcrc`, that moving its settings into `config/swc.config.js` would not affect the build. The webpack-only SWC content checks and the "merged with Shakapacker's defaults" messaging stay gated on `javascript_transpiler: swc`, and apps with `javascript_transpiler: none` remain opted out. Fixes [#1265](https://github.com/shakacode/shakapacker/issues/1265).
+- **Fixed `shakapacker:doctor` and `rake shakapacker:migrate_to_swc` telling Rspack apps that `config/swc.config.js` is merged into their build.** [PR #1260](https://github.com/shakacode/shakapacker/pull/1260) by [justin808](https://github.com/justin808). Rspack builds never read `config/swc.config.js`, because Shakapacker's Rspack rules set their `builtin:swc-loader` options inline. Doctor now warns that the file is unread on Rspack instead of reporting it as merged (and skips its content checks there), and no longer tells Rspack users with a `.swcrc` to migrate those settings into `config/swc.config.js`. The migrator's post-migration guidance and the generated file header instead show how to override the built-in `builtin:swc-loader` rule: apply `webpack-merge`'s `mergeWithRules` to the _output_ of `generateRspackConfig()`, since that function merges with plain `merge`, which concatenates `module.rules`, so an override passed into it is appended alongside the built-in rule rather than replacing it. Webpack apps keep the existing messaging. Fixes [#1259](https://github.com/shakacode/shakapacker/issues/1259).
+- **Fixed post-publish GitHub release failures hiding successful package publication details.** The release task now prints its normal publication summary and the exact `sync_github_release` recovery command before exiting nonzero. [PR #1250](https://github.com/shakacode/shakapacker/pull/1250) by [justin808](https://github.com/justin808).
+- **Fixed helper binstubs to fail closed when `PATH` is unset.** [PR #1240](https://github.com/shakacode/shakapacker/pull/1240) by [justin808](https://github.com/justin808). `bin/shakapacker-config` and `bin/diff-bundler-config` now report the missing-Node error without executing an app-root `node` binary when `PATH` is unset, while explicit `PATH` values retain their existing Node-resolution behavior. Fixes [#1234](https://github.com/shakacode/shakapacker/issues/1234).
+- **Fixed the deprecation warning for the legacy `bundler` config key claiming the value was understood while it was ignored.** [PR #1270](https://github.com/shakacode/shakapacker/pull/1270) by [justin808](https://github.com/justin808). An app whose `config/shakapacker.yml` set only `bundler:` was told the key was deprecated and then built with a different bundler, because `assets_bundler` always resolves from the bundled defaults and the legacy key was never read. The warning now states that the value is ignored, names the bundler actually in use, and tells you to set `assets_bundler` instead. One resolution change accompanies it: a config that leaves `assets_bundler:` blank while setting `bundler:` previously resolved the legacy value in Ruby and now resolves `webpack`, matching what `package/config.ts` already built for it. Fixes [#1262](https://github.com/shakacode/shakapacker/issues/1262).
+
+## [v10.3.1] - August 3, 2026
+
+### Fixed
+
+- **Fixed 502 responses for proxied dev server assets under `rack-proxy` v1.** [PR #1222](https://github.com/shakacode/shakapacker/pull/1222) by [jcbpl](https://github.com/jcbpl). Fixes [#1220](https://github.com/shakacode/shakapacker/issues/1220).
+- **Fixed dev-server liveness checks treating refused macOS 27 connections as running.** The Ruby probe now verifies the connected socket's `SO_ERROR` result before proxying asset requests, avoiding false-positive dev-server detection and resulting 502 responses. [PR #1225](https://github.com/shakacode/shakapacker/pull/1225) by [justin808](https://github.com/justin808). Fixes [#1224](https://github.com/shakacode/shakapacker/issues/1224).
+- **Fixed webpack Babel, SWC, and esbuild rules skipping explicitly included `.cjs` files.** [PR #1219](https://github.com/shakacode/shakapacker/pull/1219) by [oiahoon](https://github.com/oiahoon). Fixes [#1218](https://github.com/shakacode/shakapacker/issues/1218).
+- **Added a `shakapacker:doctor` warning for Rspack React Refresh v2 configs that still use the v1 default-export constructor pattern.** [PR #1207](https://github.com/shakacode/shakapacker/pull/1207) by [justin808](https://github.com/justin808). Existing configs with `const ReactRefreshPlugin = require("@rspack/plugin-react-refresh")` followed by `new ReactRefreshPlugin()` can fail after upgrading to `@rspack/plugin-react-refresh` v2 with `ReactRefreshPlugin is not a constructor`; Doctor now points to the affected JS/TS config file and suggests the named-export/default/module compatibility form. Fixes [#1204](https://github.com/shakacode/shakapacker/issues/1204).
+- **Fixed the missing-`@babel/core` failure to report an actionable install message.** [PR #1212](https://github.com/shakacode/shakapacker/pull/1212) by [justin808](https://github.com/justin808). Babel-transpiled builds whose app lacks `@babel/core` previously surfaced a raw module-resolution error from the Babel 8 compatibility check; the rule now explains which package to install and how to switch `javascript_transpiler` instead. Refs [#1163](https://github.com/shakacode/shakapacker/issues/1163).
+
+### Documentation
+
+- **Documented the required `css-loader@^7.1.4` in the v10 Rspack upgrade instructions.** [PR #1211](https://github.com/shakacode/shakapacker/pull/1211) by [justin808](https://github.com/justin808). The v10 upgrade guide's copy-paste Rspack v2 commands omitted `css-loader`, so apps following them could upgrade into an unsatisfied peer dependency.
+
 ## [v10.3.0] - July 5, 2026
 
 ### Added
@@ -20,7 +49,7 @@
 
 - **Fixed implicit SWC defaults for existing webpack/Babel apps without `swc-loader`.** [PR #1206](https://github.com/shakacode/shakapacker/pull/1206) by [justin808](https://github.com/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](https://github.com/shakacode/shakapacker/issues/1203).
 - **Fixed JavaScript config loading for missing Rails environments to use the production fallback.** [PR #1206](https://github.com/shakacode/shakapacker/pull/1206) by [justin808](https://github.com/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](https://github.com/shakacode/shakapacker/pull/1200) and [PR #1201](https://github.com/shakacode/shakapacker/pull/1201) by [justin808](https://github.com/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`.
+- **Fixed helper binstub Node resolution after the `v10.2.0` Ruby-binstub regression.** [PR #1200](https://github.com/shakacode/shakapacker/pull/1200) and [PR #1201](https://github.com/shakacode/shakapacker/pull/1201) by [justin808](https://github.com/justin808). Restores shell-compatible Node lookup for `bin/shakapacker-config` and `bin/diff-bundler-config` when `PATH` is empty, while keeping friendly missing-Node errors for `ENOENT` and `EACCES`. For an unset `PATH`, PR #1200 deliberately delegates Node resolution to Ruby `exec`'s default-path behavior; PR #1240 later changed that case to fail closed.
 
 ## [v10.2.0] - July 3, 2026
 
@@ -63,7 +92,7 @@
   - 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](https://github.com/webdeveric/webpack-assets-manifest/releases) and `packages/shakapacker-webpack/README.md` for details.
+- **Adopting `shakapacker-webpack` requires `webpack-assets-manifest@^6.0.0`**. [PR #1096](https://github.com/shakacode/shakapacker/pull/1096) and [PR #1133](https://github.com/shakacode/shakapacker/pull/1133) by [justin808](https://github.com/justin808). Core `shakapacker` still accepts both v5 and v6 (`^5.0.6 || ^6.0.0`), and `shakapacker-webpack` requires `^6.0.0`. 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](https://github.com/webdeveric/webpack-assets-manifest/releases) and `packages/shakapacker-webpack/README.md` for details.
 
 ### ⚠️ Breaking Changes
 
@@ -986,7 +1015,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/v10.3.0...main
+[Unreleased]: https://github.com/shakacode/shakapacker/compare/v10.3.2...main
+[v10.3.2]: https://github.com/shakacode/shakapacker/compare/v10.3.1...v10.3.2
+[v10.3.1]: https://github.com/shakacode/shakapacker/compare/v10.3.0...v10.3.1
 [v10.3.0]: https://github.com/shakacode/shakapacker/compare/v10.2.0...v10.3.0
 [v10.2.0]: https://github.com/shakacode/shakapacker/compare/v10.1.0...v10.2.0
 [v10.1.0]: https://github.com/shakacode/shakapacker/compare/v10.0.0...v10.1.0

data/lib/install/bin/diff-bundler-config

@@ -24,7 +24,7 @@ def shakapacker_warn_missing_node
 end
 
 def shakapacker_exec_env(launch_dir)
-  return {} unless ENV.key?("PATH")
+  return unless ENV.key?("PATH")
 
   path_entries = ENV["PATH"].split(File::PATH_SEPARATOR, -1)
   path_entries = [""] if path_entries.empty?
@@ -38,12 +38,9 @@ end
 
 def shakapacker_exec_node(script_path, argv, launch_dir)
   exec_env = shakapacker_exec_env(launch_dir)
+  shakapacker_warn_missing_node unless exec_env
 
-  if exec_env.empty?
-    exec shakapacker_node_binary, script_path, *argv
-  else
-    exec exec_env, shakapacker_node_binary, script_path, *argv
-  end
+  exec exec_env, shakapacker_node_binary, script_path, *argv
 rescue Errno::ENOENT, Errno::EACCES
   shakapacker_warn_missing_node
 end

data/lib/install/bin/shakapacker-config

@@ -24,7 +24,7 @@ def shakapacker_warn_missing_node
 end
 
 def shakapacker_exec_env(launch_dir)
-  return {} unless ENV.key?("PATH")
+  return unless ENV.key?("PATH")
 
   path_entries = ENV["PATH"].split(File::PATH_SEPARATOR, -1)
   path_entries = [""] if path_entries.empty?
@@ -38,12 +38,9 @@ end
 
 def shakapacker_exec_node(script_path, argv, launch_dir)
   exec_env = shakapacker_exec_env(launch_dir)
+  shakapacker_warn_missing_node unless exec_env
 
-  if exec_env.empty?
-    exec shakapacker_node_binary, script_path, *argv
-  else
-    exec exec_env, shakapacker_node_binary, script_path, *argv
-  end
+  exec exec_env, shakapacker_node_binary, script_path, *argv
 rescue Errno::ENOENT, Errno::EACCES
   shakapacker_warn_missing_node
 end

data/lib/shakapacker/configuration.rb

@@ -303,20 +303,30 @@ class Shakapacker::Configuration
   # Resolution order:
   # 1. CLI --bundler flag (via bundler_override)
   # 2. SHAKAPACKER_ASSETS_BUNDLER environment variable
-  # 3. assets_bundler setting in config file
-  # 4. bundler setting in config file (deprecated)
-  # 5. Defaults to "webpack"
+  # 3. assets_bundler setting in config file (or the bundled default)
+  # 4. Defaults to "webpack"
+  #
+  # The legacy 'bundler' setting is not consulted; it is only used to warn that
+  # its value is ignored.
   #
   # @return [String] "webpack" or "rspack"
   def assets_bundler
     # CLI --bundler flag takes highest precedence
     return @bundler_override if @bundler_override
 
-    # Show deprecation warning if using old 'bundler' key
+    resolved = ENV["SHAKAPACKER_ASSETS_BUNDLER"] || fetch(:assets_bundler) || "webpack"
+
+    # The legacy 'bundler' key is never read, so warn that its value is ignored
     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."
+      legacy_value = data[:bundler].to_s.strip
+      described_value = legacy_value.empty? ? "empty" : legacy_value
+      # An empty SHAKAPACKER_ASSETS_BUNDLER resolves to an empty string; name that
+      # state rather than printing "using ''". Doctor reports it as its own issue.
+      described_resolved = resolved.to_s.empty? ? "no bundler (SHAKAPACKER_ASSETS_BUNDLER is set but empty)" : "'#{resolved}'"
+      $stderr.puts "⚠️  DEPRECATION WARNING: The 'bundler' configuration option is no longer supported and its value (#{described_value}) is IGNORED. Shakapacker is using #{described_resolved}. Set 'assets_bundler' in your shakapacker.yml instead — it was renamed to avoid confusion with Ruby's Bundler gem manager."
     end
-    ENV["SHAKAPACKER_ASSETS_BUNDLER"] || fetch(:assets_bundler) || fetch(:bundler) || "webpack"
+
+    resolved
   end
 
   # Deprecated alias for {#assets_bundler}

data/lib/shakapacker/dev_server.rb

@@ -47,8 +47,13 @@ class Shakapacker::DevServer
   # @return [Boolean] true if the dev server is running
   def running?
     if config.dev_server.present?
-      Socket.tcp(host, port, connect_timeout: connect_timeout).close
-      true
+      socket = Socket.tcp(host, port, connect_timeout: connect_timeout)
+
+      begin
+        socket.getsockopt(Socket::SOL_SOCKET, Socket::SO_ERROR).int.zero?
+      ensure
+        socket.close
+      end
     else
       false
     end

data/lib/shakapacker/dev_server_proxy.rb

@@ -11,6 +11,10 @@ class Shakapacker::DevServerProxy < Rack::Proxy
 
   def perform_request(env)
     if env["PATH_INFO"].start_with?("/#{public_output_uri_path}") && dev_server.running?
+      # rack-proxy v1 refuses to derive the backend from the Host header.
+      env["rack.backend"] = URI::Generic.build(
+        scheme: dev_server.protocol, host: dev_server.host, port: dev_server.port
+      )
       env["HTTP_HOST"] = env["HTTP_X_FORWARDED_HOST"] = dev_server.host
       env["HTTP_X_FORWARDED_SERVER"] = dev_server.host_with_port
       env["HTTP_PORT"] = env["HTTP_X_FORWARDED_PORT"] = dev_server.port.to_s

data/lib/shakapacker/doctor.rb

@@ -59,6 +59,9 @@ module Shakapacker
       "@rspack/plugin-react-refresh" => "^2.0.0"
     }.freeze
 
+    RSPACK_REACT_REFRESH_PACKAGE = "@rspack/plugin-react-refresh".freeze
+    VERSION_UPPER_BOUND_OPERATORS = %w[< <=].freeze
+
     CUSTOM_HYBRID_LOADER_DEPS = %w[
       babel-loader
       esbuild-loader
@@ -72,6 +75,25 @@ module Shakapacker
 
     PACKAGE_ROOT_MARKERS = (["package.json"] + PACKAGE_MANAGER_LOCKFILES.keys + ["node_modules"]).freeze
 
+    # generateRspackConfig merges with plain webpack-merge `merge` (package/rspack/index.ts),
+    # which concatenates `module.rules`, so an override handed to it is appended next to the
+    # built-in rule rather than replacing it. mergeWithRules must be applied to its output.
+    RSPACK_SWC_OVERRIDE_HINT =
+      "Apply webpack-merge's 'mergeWithRules' to the output of generateRspackConfig() in your Rspack config, " \
+      "matching on both 'test' and 'use.loader', and using options: 'merge' (not 'replace', which swaps the whole " \
+      "options object and drops the built-in parser and transform.react defaults). " \
+      "Keep 'test' in the match: matching on 'use.loader' alone makes webpack-merge append 'builtin:swc-loader' to " \
+      "every rule's 'use' chain, including the CSS and Sass rules. " \
+      "Override the JS (/\\.(js|jsx|mjs)$/) and TypeScript (/\\.(ts|tsx)$/) rules separately, since Shakapacker " \
+      "registers a 'builtin:swc-loader' rule for each. " \
+      "Passing an override into generateRspackConfig() cannot replace the built-in rule, because it merges with " \
+      "plain 'merge', which concatenates 'module.rules' and leaves the built-in 'builtin:swc-loader' rule in place " \
+      "alongside yours. Shakapacker re-exports 'mergeWithRules'. " \
+      "See: https://github.com/shakacode/shakapacker/blob/main/docs/rspack.md".freeze
+
+    RSPACK_SWC_OVERRIDE_HINT_BACKREF =
+      "See the Rspack 'builtin:swc-loader' override guidance above.".freeze
+
     def initialize(config = nil, root_path = nil, options = {})
       @config = config || Shakapacker.config
       @root_path = root_path || (defined?(Rails) ? Rails.root : Pathname.new(Dir.pwd))
@@ -170,6 +192,7 @@ module Shakapacker
         check_css_modules_configuration
         check_bundler_dependencies if config_exists?
         check_rspack_cache_configuration if config_exists?
+        check_rspack_react_refresh_plugin_constructor if config_exists?
         check_file_type_dependencies if config_exists?
         check_sri_dependencies if config_exists?
         check_peer_dependencies
@@ -661,8 +684,11 @@ module Shakapacker
           add_warning("Both esbuild and Babel dependencies are installed. Consider removing Babel dependencies to reduce node_modules size")
         end
 
-        # Check for SWC configuration conflicts
-        if transpiler == "swc"
+        # Check for SWC configuration conflicts. Rspack always transpiles with
+        # builtin:swc-loader, so SWC config files go unread there regardless of
+        # javascript_transpiler; the webpack-only content checks stay SWC-gated
+        # inside check_swc_config_conflicts.
+        if transpiler == "swc" || assets_bundler == "rspack"
           check_swc_config_conflicts
         end
       end
@@ -714,16 +740,48 @@ module Shakapacker
         swcrc_path = root_path.join(".swcrc")
         swc_config_path = root_path.join("config/swc.config.js")
 
+        rspack = assets_bundler == "rspack"
+
         if swcrc_path.exist?
-          add_warning("SWC configuration: .swcrc file detected. This file completely overrides Shakapacker's default SWC settings and may cause build failures. " \
-                      "Please migrate to config/swc.config.js which properly merges with Shakapacker defaults. " \
-                      "To migrate: Move your custom settings from .swcrc to config/swc.config.js (see docs for format). " \
-                      "See: https://github.com/shakacode/shakapacker/blob/main/docs/using_swc_loader.md")
+          if rspack
+            # Verified against @rspack/core 2.0.1 and 2.2.0: 'builtin:swc-loader' never reads .swcrc.
+            # A .swcrc setting jsc.target and an optimizer global produced byte-identical output to
+            # no .swcrc, and the same options passed inline did change the output. A .swcrc enabling
+            # decorator syntax also failed to unblock a decorator source, including with empty loader
+            # options and with swcrc/configFile set, so this is not just inline options winning.
+            add_warning("SWC configuration: .swcrc is present but is NOT read when assets_bundler is 'rspack'. " \
+                        "Rspack transpiles with 'builtin:swc-loader', which ignores .swcrc entirely, so every setting in it is silently inert. " \
+                        "Moving these settings to config/swc.config.js would not help either - Shakapacker's Rspack build does not read that file.")
+            add_rspack_swc_override_hint("To apply custom SWC options on Rspack, override the built-in 'builtin:swc-loader' rule.")
+          else
+            add_warning("SWC configuration: .swcrc file detected. This file completely overrides Shakapacker's default SWC settings and may cause build failures. " \
+                        "Please migrate to config/swc.config.js which properly merges with Shakapacker defaults. " \
+                        "To migrate: Move your custom settings from .swcrc to config/swc.config.js (see docs for format). " \
+                        "See: https://github.com/shakacode/shakapacker/blob/main/docs/using_swc_loader.md")
+          end
         end
 
-        if swc_config_path.exist?
-          @info << "SWC configuration: Using config/swc.config.js (recommended). This config is merged with Shakapacker's defaults."
-          check_swc_config_settings(swc_config_path)
+        return unless swc_config_path.exist?
+
+        if rspack
+          add_warning("SWC configuration: config/swc.config.js is present but is NOT read when assets_bundler is 'rspack'. " \
+                      "Shakapacker's Rspack config sets its 'builtin:swc-loader' options inline, so nothing in this file reaches your build.")
+          add_rspack_swc_override_hint("Customize SWC for Rspack by overriding the built-in 'builtin:swc-loader' rule instead.")
+          return
+        end
+
+        @info << "SWC configuration: Using config/swc.config.js (recommended). This config is merged with Shakapacker's defaults."
+        check_swc_config_settings(swc_config_path)
+      end
+
+      # The full hint is ~700 characters, and an Rspack app with both .swcrc and
+      # config/swc.config.js hits both call sites, so emit it once and refer back after that.
+      def add_rspack_swc_override_hint(lead)
+        if @rspack_swc_override_hint_emitted
+          add_fix_hint("#{lead} #{RSPACK_SWC_OVERRIDE_HINT_BACKREF}")
+        else
+          @rspack_swc_override_hint_emitted = true
+          add_fix_hint("#{lead} #{RSPACK_SWC_OVERRIDE_HINT}")
         end
       end
 
@@ -878,14 +936,89 @@ module Shakapacker
                      "See https://rspack.rs/config/cache for options.")
       end
 
+      def check_rspack_react_refresh_plugin_constructor
+        return unless rspack_react_refresh_check_applicable?
+        return unless rspack_react_refresh_plugin_v2_or_newer?
+
+        rspack_react_refresh_config_paths.each do |path|
+          content = File.read(path)
+          next unless legacy_rspack_react_refresh_constructor?(content)
+
+          relative = config_path_for_warning(path)
+          add_action_required("Rspack React Refresh config #{relative} uses the " \
+                              "#{RSPACK_REACT_REFRESH_PACKAGE} v1 default-export constructor pattern. " \
+                              "With #{RSPACK_REACT_REFRESH_PACKAGE} v2, rspack may fail with " \
+                              "'ReactRefreshPlugin is not a constructor'.")
+          add_fix_hint("Use a compat constructor: const ReactRefresh = require(\"#{RSPACK_REACT_REFRESH_PACKAGE}\"); " \
+                       "const ReactRefreshRspackPlugin = ReactRefresh.ReactRefreshRspackPlugin || " \
+                       "ReactRefresh.default || ReactRefresh; then call new ReactRefreshRspackPlugin().")
+        rescue SystemCallError => e
+          add_info_warning("Unable to validate Rspack React Refresh config #{config_path_for_warning(path)}: #{e.message}")
+        end
+      end
+
+      def rspack_react_refresh_check_applicable?
+        assets_bundler == "rspack" || unconfigured_hybrid_loader_graph?
+      end
+
+      def rspack_react_refresh_plugin_v2_or_newer?
+        version = installed_package_version(RSPACK_REACT_REFRESH_PACKAGE)
+        return version >= Gem::Version.new("2.0.0") if version
+
+        package_specifier_allows_version_or_newer?(
+          package_json_dependency_version(RSPACK_REACT_REFRESH_PACKAGE),
+          Gem::Version.new("2.0.0")
+        )
+      end
+
+      def rspack_react_refresh_config_paths
+        config_dir = rspack_react_refresh_config_dir
+        config_dir_path = Pathname.new(File.join(root_path.to_s, config_dir))
+        return [] unless config_dir_path.directory?
+
+        path = active_bundler_config_path_in(config_dir)
+        path ? [path] : []
+      end
+
+      def rspack_react_refresh_config_dir
+        config_dir = config.assets_bundler_config_path.to_s
+
+        if assets_bundler == "rspack" || same_directory_hybrid_config_present?(config_dir)
+          config_dir
+        else
+          "config/rspack"
+        end
+      end
+
+      def legacy_rspack_react_refresh_constructor?(content)
+        stripped = strip_rspack_config_comments_and_literals(content, preserve_literals: [RSPACK_REACT_REFRESH_PACKAGE])
+        constructor_names = []
+
+        constructor_names.concat(stripped.scan(
+          /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*require\(\s*["']#{Regexp.escape(RSPACK_REACT_REFRESH_PACKAGE)}["']\s*\)(?=\s*(?:[;,\)]|$))/
+        ).flatten)
+        constructor_names.concat(stripped.scan(
+          /\bimport\s+([A-Za-z_$][\w$]*)\s*(?:,\s*\{[^}]*\}\s*)?\s+from\s*["']#{Regexp.escape(RSPACK_REACT_REFRESH_PACKAGE)}["']/
+        ).flatten)
+        constructor_names.concat(stripped.scan(
+          /\bimport\s+\*\s+as\s+([A-Za-z_$][\w$]*)\s+from\s*["']#{Regexp.escape(RSPACK_REACT_REFRESH_PACKAGE)}["']/
+        ).flatten)
+
+        constructor_names.uniq.any? do |constructor_name|
+          stripped.match?(/\bnew\s+#{Regexp.escape(constructor_name)}\s*\(/)
+        end
+      end
+
       # Returns the single active config path the runner would load, or nil. Mirrors the
       # resolution order in Shakapacker::Runner#find_rspack_config_with_fallback so the
       # doctor inspects the same file the build will actually use (and so unused sibling
       # configs in the same directory don't trigger spurious warnings).
       # NOTE: keep this candidate list in sync with Runner#find_rspack_config_with_fallback.
       def active_assets_bundler_config_path
-        config_dir = config.assets_bundler_config_path.to_s
+        active_bundler_config_path_in(config.assets_bundler_config_path.to_s)
+      end
 
+      def active_bundler_config_path_in(config_dir)
         candidates = %w[ts js].map { |ext| Pathname.new(File.join(root_path.to_s, config_dir, "rspack.config.#{ext}")) }
         candidates += %w[ts js].map { |ext| Pathname.new(File.join(root_path.to_s, config_dir, "webpack.config.#{ext}")) }
         if default_rspack_config_dir?(config_dir)
@@ -944,7 +1077,7 @@ module Shakapacker
         stripped.gsub(%r{/(?:\\.|\[[^\]\n]*\]|[^/\n\\\[])+?/[gimsuy]*}, "")
       end
 
-      def strip_rspack_config_comments_and_literals(content)
+      def strip_rspack_config_comments_and_literals(content, preserve_literals: [])
         stripped = +""
         index = 0
 
@@ -987,8 +1120,12 @@ module Shakapacker
             end
 
             literal = content[index...literal_end]
-            stripped << '""'
-            stripped << literal.gsub(/[^\n]/, "")
+            if preserved_js_string_literal?(literal, char, preserve_literals)
+              stripped << literal
+            else
+              stripped << '""'
+              stripped << literal.gsub(/[^\n]/, "")
+            end
             index = literal_end
           elsif char == "`"
             literal_end = index + 1
@@ -1029,6 +1166,12 @@ module Shakapacker
         stripped
       end
 
+      def preserved_js_string_literal?(literal, quote, preserve_literals)
+        return false unless literal.end_with?(quote)
+
+        preserve_literals.include?(literal[1...-1])
+      end
+
       def direct_export_cache_disabled?(stripped)
         # Match `cache: false` only near an exported config object at brace depth
         # 1. This avoids warning on local base config objects while still
@@ -1183,8 +1326,9 @@ module Shakapacker
           return versions.min
         end
 
+        return package_version_from_range_specifier(cleaned) if cleaned.match?(/[<>=]/)
         return nil unless cleaned.match?(/\A[\^~]?\d/)
-        return nil if cleaned.match?(/(\s|\|\||[<>=:]|\A(?:git|file|link|workspace|npm):)/)
+        return nil if cleaned.match?(/(\s|\|\||:|\A(?:git|file|link|workspace|npm):)/)
 
         match = cleaned.sub(/\A[\^~]/, "").match(/\A(\d+(?:\.\d+){0,2})(?:-[0-9A-Za-z.-]+)?\z/)
         match && Gem::Version.new(match[1])
@@ -1192,6 +1336,48 @@ module Shakapacker
         nil
       end
 
+      def package_version_from_range_specifier(specifier)
+        lower_bounds = specifier.scan(/(?:\A|\s)(?:>=|>)\s*(\d+(?:\.\d+){0,2})(?:-[0-9A-Za-z.-]+)?/)
+        versions = lower_bounds.flatten.map { |version| Gem::Version.new(version) }
+
+        versions.max
+      rescue ArgumentError
+        nil
+      end
+
+      def package_specifier_allows_version_or_newer?(specifier, minimum)
+        return false unless specifier
+
+        cleaned = specifier.strip
+        if cleaned.include?("||")
+          return cleaned.split("||").any? { |part| package_specifier_allows_version_or_newer?(part, minimum) }
+        end
+        return false if cleaned.match?(/(:|\A(?:git|file|link|workspace|npm):)/)
+
+        if cleaned.match?(/[<>=]/)
+          return package_range_specifier_allows_version_or_newer?(cleaned, minimum)
+        end
+
+        version = package_version_from_specifier(cleaned)
+        version && version >= minimum
+      end
+
+      def package_range_specifier_allows_version_or_newer?(specifier, minimum)
+        comparators = specifier.scan(/(?:\A|\s)(<=|<|>=|>|=)\s*(\d+(?:\.\d+){0,2})(?:-[0-9A-Za-z.-]+)?/)
+        return false if comparators.empty?
+
+        equalities = comparators.select { |operator, _version| operator == "=" }
+        return equalities.any? { |_operator, version| Gem::Version.new(version) >= minimum } if equalities.any?
+
+        upper_bounds = comparators.select { |operator, _version| VERSION_UPPER_BOUND_OPERATORS.include?(operator) }
+        upper_bounds.all? do |operator, version|
+          parsed = Gem::Version.new(version)
+          operator == "<" ? parsed > minimum : parsed >= minimum
+        end
+      rescue ArgumentError
+        false
+      end
+
       def declared_package_dependencies
         @declared_package_dependencies ||= begin
           package_json_paths.reverse_each.each_with_object({}) do |path, dependencies|

data/lib/shakapacker/swc_migrator.rb

@@ -46,11 +46,65 @@ module Shakapacker
       .eslintrc.json
     ].freeze
 
-    DEFAULT_SWC_CONFIG = <<~JS.freeze
+    SWC_CONFIG_WEBPACK_HEADER = <<~JS.freeze
       // config/swc.config.js
       // This file is merged with Shakapacker's default SWC configuration
       // See: https://swc.rs/docs/configuration/compilation
+    JS
+
+    # Rspack never reads config/swc.config.js: package/rules/rspack.ts sets its
+    # builtin:swc-loader options inline, so the file is generated with a header that says so.
+    #
+    # The example keeps `test: 'match'` and overrides the JS and TS rules separately on
+    # purpose. Matching on `use.loader` alone (a single override with no `test`) looks tidier
+    # but is wrong: webpack-merge cannot pair such an override with a specific rule, so it
+    # appends builtin:swc-loader onto EVERY rule's `use` chain, including the CSS and Sass
+    # rules. Verified at webpack-merge 5.10.0 and 6.0.1.
+    SWC_CONFIG_RSPACK_HEADER = <<~JS.freeze
+      // config/swc.config.js
+      // NOTE: This file is NOT read when assets_bundler is 'rspack'.
+      // Shakapacker's Rspack config sets its 'builtin:swc-loader' options inline, so nothing
+      // here reaches your build. To customize SWC for Rspack, apply webpack-merge's
+      // mergeWithRules to the OUTPUT of generateRspackConfig(). Passing an override into
+      // generateRspackConfig() cannot replace the built-in rule: it merges with plain merge,
+      // which concatenates module.rules and leaves the built-in rule in place alongside yours.
+      //
+      // Use options: 'merge', not 'replace'. 'merge' deep-merges into the built-in options so
+      // parser.jsx (JS), parser.syntax/tsx (TS), and transform.react.runtime survive.
+      // 'replace' swaps the whole options object and silently drops them, breaking JSX and
+      // TypeScript compilation.
+      //
+      // Keep test: 'match' in the merge spec. Matching on use.loader alone appends
+      // builtin:swc-loader to every rule's use chain, CSS and Sass included.
+      //
+      //   const { mergeWithRules } = require('shakapacker');
+      //   const { generateRspackConfig } = require('shakapacker/rspack');
+      //
+      //   const swcOptions = { jsc: { keepClassNames: true } }; // your SWC options
+      //
+      //   module.exports = mergeWithRules({
+      //     module: { rules: { test: 'match', use: { loader: 'match', options: 'merge' } } },
+      //   })(generateRspackConfig(), {
+      //     module: {
+      //       rules: [
+      //         // Shakapacker registers separate builtin:swc-loader rules for JS and TS.
+      //         // Override both: a JS-only override never reaches .ts/.tsx files.
+      //         {
+      //           test: /\\.(js|jsx|mjs)$/,
+      //           use: [{ loader: 'builtin:swc-loader', options: swcOptions }],
+      //         },
+      //         {
+      //           test: /\\.(ts|tsx)$/,
+      //           use: [{ loader: 'builtin:swc-loader', options: swcOptions }],
+      //         },
+      //       ],
+      //     },
+      //   });
+      //
+      // See: https://github.com/shakacode/shakapacker/blob/main/docs/rspack.md
+    JS
 
+    SWC_CONFIG_BODY = <<~JS.freeze
       const { env } = require('shakapacker');
 
       module.exports = {
@@ -70,6 +124,11 @@ module Shakapacker
       };
     JS
 
+    # Kept for backward compatibility: same value as before, and still the webpack variant.
+    DEFAULT_SWC_CONFIG = "#{SWC_CONFIG_WEBPACK_HEADER}\n#{SWC_CONFIG_BODY}".freeze
+
+    RSPACK_SWC_CONFIG = "#{SWC_CONFIG_RSPACK_HEADER}\n#{SWC_CONFIG_BODY}".freeze
+
     def initialize(root_path, logger: nil)
       @root_path = Pathname.new(root_path)
       @logger = logger || Logger.new($stdout)
@@ -89,9 +148,7 @@ module Shakapacker
       logger.info "   Note: SWC is approximately 20x faster than Babel for transpilation."
       logger.info "   Please test your application thoroughly after migration."
       logger.info "\n📝 Configuration Info:"
-      logger.info "   - config/swc.config.js is merged with Shakapacker's default SWC configuration"
-      logger.info "   - You can customize config/swc.config.js to add additional options"
-      logger.info "   - Avoid using .swcrc as it overrides Shakapacker defaults completely"
+      log_swc_config_guidance
 
       # Show cleanup recommendations if babel packages found
       if results[:babel_packages_found].any?
@@ -275,6 +332,48 @@ module Shakapacker
         {}
       end
 
+      def log_swc_config_guidance
+        if rspack?
+          logger.info "   - config/swc.config.js is NOT read when assets_bundler is 'rspack'"
+          logger.info "     Shakapacker's Rspack config sets its 'builtin:swc-loader' options inline"
+          logger.info "   - To customize SWC for Rspack, apply webpack-merge's 'mergeWithRules' to the"
+          logger.info "     OUTPUT of generateRspackConfig(), matching on both 'test' and 'use.loader'"
+          logger.info "     and merging 'use.options'. Matching on 'use.loader' alone would append"
+          logger.info "     'builtin:swc-loader' to every rule's 'use' chain, CSS and Sass included."
+          logger.info "     Passing an override into generateRspackConfig() cannot replace"
+          logger.info "     the built-in rule, because it merges with plain 'merge', which concatenates"
+          logger.info "     'module.rules' and leaves the built-in rule in place alongside yours"
+          logger.info "   - Use options: 'merge', not 'replace', so the built-in parser and"
+          logger.info "     transform.react defaults survive, and override the JS and TS rules separately"
+          logger.info "   - The generated config/swc.config.js header contains a copy-pasteable example"
+          logger.info "   - See: https://github.com/shakacode/shakapacker/blob/main/docs/rspack.md"
+        else
+          logger.info "   - config/swc.config.js is merged with Shakapacker's default SWC configuration"
+          logger.info "   - You can customize config/swc.config.js to add additional options"
+          logger.info "   - Avoid using .swcrc as it overrides Shakapacker defaults completely"
+        end
+      end
+
+      def rspack?
+        assets_bundler == "rspack"
+      end
+
+      # Resolves through Shakapacker's own configuration rather than re-reading
+      # config/shakapacker.yml here, so this guidance can never disagree with the bundler the
+      # build actually uses. Instance handles SHAKAPACKER_CONFIG, Env.inquire (Rails.env plus
+      # the production fallback), and Configuration's own precedence. Falls back to webpack
+      # when the config is missing or unparseable, since migration must not crash on it.
+      def assets_bundler
+        return @assets_bundler if defined?(@assets_bundler)
+
+        @assets_bundler = begin
+          require "shakapacker"
+          Shakapacker::Instance.new(root_path: root_path).config.assets_bundler
+        rescue StandardError, LoadError
+          "webpack"
+        end
+      end
+
       def create_swc_config
         config_dir = root_path.join("config")
         swc_config_path = config_dir.join("swc.config.js")
@@ -287,7 +386,7 @@ module Shakapacker
         FileUtils.mkdir_p(config_dir) unless config_dir.exist?
 
         logger.info "📄 Creating config/swc.config.js..."
-        File.write(swc_config_path, DEFAULT_SWC_CONFIG)
+        File.write(swc_config_path, rspack? ? RSPACK_SWC_CONFIG : DEFAULT_SWC_CONFIG)
         logger.info "✅ config/swc.config.js created"
         true
       rescue StandardError => e

data/lib/shakapacker/utils/misc.rb

@@ -33,7 +33,11 @@ module Shakapacker
         [true, "true", "yes", 1, "1", "t"].include?(value.instance_of?(String) ? value.downcase : value)
       end
 
-      # Executes a string or an array of strings in a shell in the given directory in an unbundled environment
+      # Executes a string or an array of strings in a shell in the given directory.
+      # NOTE: this does NOT unbundle. The caller's Bundler environment (BUNDLE_GEMFILE,
+      # RUBYOPT, ...) is inherited, so a `bundle` command run here against a different
+      # directory's Gemfile still resolves the caller's Gemfile. Wrap the call in
+      # Bundler.with_unbundled_env when that matters.
       def self.sh_in_dir(dir, *shell_commands)
         shell_commands.flatten.each { |shell_command| sh %(cd '#{dir}' && #{shell_command.strip}) }
       end

data/lib/shakapacker/version.rb

@@ -1,4 +1,4 @@
 module Shakapacker
   # Change the version in package.json too, please!
-  VERSION = "10.3.0".freeze
+  VERSION = "10.3.2".freeze
 end

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shakapacker",
-  "version": "10.3.0",
+  "version": "10.3.2",
   "description": "Use webpack to manage app-like JavaScript modules in Rails",
   "homepage": "https://github.com/shakacode/shakapacker",
   "bugs": {
@@ -58,8 +58,8 @@
     "@babel/core": "7.29.0",
     "@eslint/eslintrc": "^3.2.0",
     "@eslint/js": "^9.37.0",
-    "@rspack/cli": "2.0.1",
-    "@rspack/core": "2.0.1",
+    "@rspack/cli": "2.2.0",
+    "@rspack/core": "2.2.0",
     "@swc/core": "1.15.33",
     "@types/babel__core": "^7.20.5",
     "@types/js-yaml": "^4.0.9",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shakapacker
 version: !ruby/object:Gem::Version
-  version: 10.3.0
+  version: 10.3.2
 platform: ruby
 authors:
 - David Heinemeier Hansson
@@ -225,7 +225,7 @@ homepage: https://github.com/shakacode/shakapacker
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/shakacode/shakapacker/tree/v10.3.0
+  source_code_uri: https://github.com/shakacode/shakapacker/tree/v10.3.2
 rdoc_options: []
 require_paths:
 - lib
@@ -240,7 +240,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.18
 specification_version: 4
 summary: Use webpack to manage app-like JavaScript modules in Rails
 test_files: []