Breaking change in 9.3.0-beta.1: requires config/rspack directory when assets_bundler: rspack

[justin808]

Problem

Upgrading from Shakapacker 9.1.0 to 9.3.0-beta.1 breaks CI with the following error:

[Shakapacker] ERROR: rspack config /home/runner/work/react-webpack-rails-tutorial/react-webpack-rails-tutorial/config/rspack/rspack.config.js not found.

Please run 'bundle exec rails shakapacker:install' to install Shakapacker with default configs,
or create the missing config file.

If your config file is in a different location, you can configure it in config/shakapacker.yml:

  assets_bundler_config_path: your/custom/path

Current configured path: config/rspack
[Shakapacker] Looking for Rspack config in: /home/runner/work/react-webpack-rails-tutorial/react-webpack-rails-tutorial/config/rspack/rspack.config.ts, /home/runner/work/react-webpack-rails-tutorial/react-webpack-rails-tutorial/config/rspack/rspack.config.js
[Shakapacker] Rspack config not found, checking for webpack config fallback...

Configuration

Our config/shakapacker.yml has:

assets_bundler: rspack

And we have a config/webpack/ directory with webpack config files (including webpack.config.js).

Expected Behavior

An upgrade should only require updating Gemfile and package.json. The upgrade documentation states this should be a simple version bump, not a migration requiring directory restructuring or running installers.

In Shakapacker 9.1.0, having assets_bundler: rspack worked fine with configs in config/webpack/. The beta appears to have introduced a breaking change that now requires configs to be in config/rspack/.

Actual Behavior

Shakapacker 9.3.0-beta.1 now strictly enforces that rspack configs must be in config/rspack/ directory, breaking existing working configurations.

Suggested Solutions

1. Backwards compatibility: When assets_bundler: rspack is set but config/rspack/ doesn't exist, fall back to checking config/webpack/ (with a deprecation warning)

2. Better documentation: The upgrade guide should explicitly mention this breaking change and provide migration steps:

   # If upgrading to 9.3.0 with rspack
   mv config/webpack config/rspack

3. Migration tool: Provide a rake task that handles this migration automatically:

   rails shakapacker:migrate_rspack_configs

4. Document assets_bundler_config_path: The new assets_bundler_config_path config option (mentioned in CHANGELOG for 9.3.0-beta.0) should be documented as the way to override the default path if needed.

Impact on AI Tools

This breaking change particularly affects AI-assisted upgrades because:

• The upgrade docs don't mention directory restructuring is required
• AI tools follow documentation which says "update Gemfile and package.json"
• The error message suggests running the installer (which overwrites configs) rather than explaining the path change

Reproduction

1. Have a working Shakapacker 9.1.0 setup with assets_bundler: rspack and configs in config/webpack/
2. Update Gemfile: gem "shakapacker", "9.3.0.beta.1"
3. Update package.json: "shakapacker": "9.3.0-beta.1"
4. Run bundle install && yarn install
5. Run bundle exec bin/shakapacker
6. Observe error about missing config/rspack directory

Related

• Project: https://github.com/shakacode/react-webpack-rails-tutorial
• Failed PR: Upgrade to Shakapacker 9.3.0.beta.1 react-webpack-rails-tutorial#685
• Related to documentation issue: Improve upgrade documentation to clarify both Gemfile and package.json need updating #730

CC: @justin808