shakapacker 9.0.0 → 9.2.0

data/docs/troubleshooting.md

@@ -17,12 +17,72 @@
 
 4. You can also pass additional options to the command to run the webpack-dev-server and start the webpack-dev-server with the option `--debug-shakapacker`
 
-5. ChatGPT and other AI tools can consume this output file. Change the NODE_ENV per your needs. Then upload the file to your favorite AI tool.
+5. **Export your full webpack/rspack configuration for analysis**: Use the `bin/export-bundler-config` utility to export your complete resolved configuration. This is especially helpful for:
+
+   - **Migrations**: Comparing configurations before and after migrating between webpack and rspack, or between different Shakapacker versions
+   - **Debugging**: Inspecting the exact configuration webpack/rspack is using, including all merged settings
+   - **AI Analysis**: Uploading the exported config to ChatGPT or other AI tools for troubleshooting
+
+   **Installation**: The utility is installed when you run `rake shakapacker:binstubs` or can be used directly via `rake shakapacker:export_bundler_config`.
+
+   **RECOMMENDED - Quick troubleshooting:**
+
+   ```bash
+   # Install the binstub (one-time setup)
+   rake shakapacker:binstubs
+
+   # Export EVERYTHING for troubleshooting (dev + prod, annotated YAML)
+   bin/export-bundler-config --doctor
+   # Creates: webpack-development-client.yaml, webpack-development-server.yaml,
+   #          webpack-production-client.yaml, webpack-production-server.yaml
+   ```
+
+   **Other usage examples:**
+
+   ```bash
+   # Save current environment configs with auto-generated names
+   bin/export-bundler-config --save
+   # Creates: webpack-development-client.yaml, webpack-development-server.yaml
+
+   # Save to specific directory
+   bin/export-bundler-config --save --save-dir=./debug-configs
+
+   # Export only client config for production
+   bin/export-bundler-config --save --env=production --client-only
+   # Creates: webpack-production-client.yaml
+
+   # Compare development vs production configs
+   bin/export-bundler-config --save --save-dir=./configs
+   diff configs/webpack-development-client.yaml configs/webpack-production-client.yaml
+
+   # View config in terminal (no files created)
+   bin/export-bundler-config
+
+   # Export without inline documentation annotations
+   bin/export-bundler-config --save --no-annotate
+
+   # Export in JSON format for programmatic analysis
+   bin/export-bundler-config --save --format=json
    ```
+
+   **Config files are automatically named:** `{bundler}-{env}-{type}.{ext}`
+
+   - Examples: `webpack-development-client.yaml`, `rspack-production-server.yaml`
+   - YAML format includes inline documentation explaining each config key
+   - Separate files for client and server bundles (cleaner than combined)
+
+   See `bin/export-bundler-config --help` for all available options.
+
+6. Generate webpack stats for build analysis (useful for bundle size optimization):
+
+   ```bash
    NODE_ENV=development bin/shakapacker --profile --json > /tmp/webpack-stats.json
    ```
 
+   ChatGPT and other AI tools can consume this output file. Change the NODE_ENV per your needs.
+
 ## Incorrect peer dependencies
+
 Shakapacker uses peer dependencies to make it easier to manage what versions are being used for your app, which is especially
 useful for patching security vulnerabilities. However, not all package managers will actually enforce these versions - notably,
 Yarn will omit a warning rather than erroring if you forget to update a peer dependency:
@@ -32,6 +92,7 @@ warning " > shakapacker@6.1.1" has incorrect peer dependency "compression-webpac
 ```
 
 This omission resulted in an error in the browser:
+
 ```
 Failed to load resource: net::ERR_CONTENT_DECODING_FAILED
 ```
@@ -40,6 +101,40 @@ The error was caused by an old version of the peer dependency `webpack-compressi
 
 So, be sure to investigate warnings from `yarn install`!
 
+## NoMethodError: undefined method 'deep_symbolize_keys' for nil:NilClass
+
+If you see this error during deployment (especially on Heroku with a staging environment):
+
+```
+NoMethodError: undefined method 'deep_symbolize_keys' for nil:NilClass
+  from shakapacker/configuration.rb:XXX:in 'load'
+```
+
+This happens when deploying to a custom Rails environment (like `staging`) that isn't explicitly defined in your `config/shakapacker.yml` file.
+
+**Solution:** This was fixed in Shakapacker v9.1.1+. Upgrade to the latest version:
+
+```ruby
+# Gemfile
+gem 'shakapacker', '~> 9.1'
+```
+
+After upgrading, Shakapacker will automatically fall back to sensible defaults when your environment isn't defined:
+
+1. First tries your environment (e.g., `staging`)
+2. Falls back to `production` configuration
+
+**Alternative:** If you can't upgrade immediately, explicitly add your environment to `config/shakapacker.yml`:
+
+```yaml
+staging:
+  <<: *default
+  compile: false
+  cache_manifest: true
+```
+
+See the [deployment guide](./deployment.md#custom-rails-environments-eg-staging) for more details.
+
 ## ENOENT: no such file or directory - node-sass
 
 If you get the error `ENOENT: no such file or directory - node-sass` on deploy with
@@ -54,7 +149,7 @@ thing, like Heroku.
 
 However, if you get this on local development, or not during a deploy then you
 may need to rebuild `node-sass`. It's a bit of a weird error; basically, it
-can't find the `node-sass` binary.  An easy solution is to create a postinstall
+can't find the `node-sass` binary. An easy solution is to create a postinstall
 hook to ensure `node-sass` is rebuilt whenever new modules are installed.
 
 In `package.json`:
@@ -67,19 +162,18 @@ In `package.json`:
 
 ## Can't find hello_react.js in manifest.json
 
-* If you get this error `Can't find hello_react.js in manifest.json`
-when loading a view in the browser it's because webpack is still compiling packs.
-Shakapacker uses a `manifest.json` file to keep track of packs in all environments,
-however since this file is generated after packs are compiled by webpack. So,
-if you load a view in browser whilst webpack is compiling you will get this error.
-Therefore, make sure webpack
-(i.e `./bin/shakapacker-dev-server`) is running and has
-completed the compilation successfully before loading a view.
-
+- If you get this error `Can't find hello_react.js in manifest.json`
+  when loading a view in the browser it's because webpack is still compiling packs.
+  Shakapacker uses a `manifest.json` file to keep track of packs in all environments,
+  however since this file is generated after packs are compiled by webpack. So,
+  if you load a view in browser whilst webpack is compiling you will get this error.
+  Therefore, make sure webpack
+  (i.e `./bin/shakapacker-dev-server`) is running and has
+  completed the compilation successfully before loading a view.
 
 ## throw er; // Unhandled 'error' event
 
-* If you get this error while trying to use Elm, try rebuilding Elm. You can do
+- If you get this error while trying to use Elm, try rebuilding Elm. You can do
   so with a postinstall hook in your `package.json`:
 
 ```json
@@ -90,9 +184,9 @@ completed the compilation successfully before loading a view.
 
 ## webpack or webpack-dev-server not found
 
-* This could happen if `shakapacker:install` step is skipped. Please run `bundle exec rails shakapacker:install` to fix the issue.
+- This could happen if `shakapacker:install` step is skipped. Please run `bundle exec rails shakapacker:install` to fix the issue.
 
-* If you encounter the above error on heroku after upgrading from Rails 4.x to 5.1.x, then the problem might be related to missing `yarn` binstub. Please run following commands to update/add binstubs:
+- If you encounter the above error on heroku after upgrading from Rails 4.x to 5.1.x, then the problem might be related to missing `yarn` binstub. Please run following commands to update/add binstubs:
 
 ```bash
 bundle config --delete bin
@@ -137,6 +231,7 @@ chmod +x $HOME/your_rails_app/node_modules/.bin/elm-make
 ```
 
 ## Rake assets:precompile fails. ExecJS::RuntimeError
+
 This error occurs because you are trying to minify by `terser` a pack that's already been minified by Shakapacker. To avoid this conflict and prevent appearing of `ExecJS::RuntimeError` error, you will need to disable uglifier from Rails config:
 
 ```ruby
@@ -152,10 +247,11 @@ Rails.application.config.assets.js_compressor = Uglifier.new(harmony: true)
 ### Angular: WARNING in ./node_modules/@angular/core/esm5/core.js, Critical dependency: the request of a dependency is an expression
 
 To silent these warnings, please update `config/webpack/webpack.config.js`:
+
 ```js
-const webpack = require('webpack')
-const { resolve } = require('path')
-const { generateWebpackConfig } = require('shakapacker')
+const webpack = require("webpack")
+const { resolve } = require("path")
+const { generateWebpackConfig } = require("shakapacker")
 
 module.exports = generateWebpackConfig({
   plugins: [
@@ -192,6 +288,7 @@ Thus ProvidePlugin manages build-time dependencies to global symbols whereas the
 **You don't need to assign dependencies on `window`.**
 
 For instance, with [jQuery](https://jquery.com/):
+
 ```diff
 // app/javascript/entrypoints/application.js
 
@@ -200,19 +297,20 @@ For instance, with [jQuery](https://jquery.com/):
 ```
 
 Instead do:
+
 ```js
 // config/webpack/webpack.config.js
 
-const webpack = require('webpack')
-const { generateWebpackConfig } = require('shakapacker')
+const webpack = require("webpack")
+const { generateWebpackConfig } = require("shakapacker")
 
 module.exports = generateWebpackConfig({
   plugins: [
     new webpack.ProvidePlugin({
-      $: 'jquery',
-      jQuery: 'jquery',
+      $: "jquery",
+      jQuery: "jquery"
     })
-  ],
+  ]
 })
 ```
 
@@ -225,7 +323,7 @@ application is using your staging `config.asset_host` host when using
 
 This can be fixed by setting the environment variable `SHAKAPACKER_ASSET_HOST` to
 an empty string where your assets are compiled. On Heroku this is done under
-*Settings* -> *Config Vars*.
+_Settings_ -> _Config Vars_.
 
 This way shakapacker won't hard-code the CDN host into the manifest file used by
 `javascript_pack_tag`, but instead fetch the CDN host at runtime, resolving the
@@ -243,6 +341,7 @@ In order to generate the storage path, we rely on the filename that's [provided
 This usually works out of the box. There's a potential problem however, if you use the [context setting](https://webpack.js.org/configuration/entry-context/#context) in your webpack config. By default this is set to current Node working directory/project root.
 
 If you were to override it like:
+
 ```
 {
   context: path.resolve(__dirname, '../../app/javascript')
@@ -252,12 +351,14 @@ If you were to override it like:
 Then the filename available in the rule generator will be relative to that directory.
 
 This means for example:
+
 - a static asset from `node_modules` folder could end up being referenced with path of `../../node_modules/some_module/static_file.jpg` rather than simply `node_modules/some_module/static_file.jpg`.
 - a static asset in one of the `additional_paths`, example `app/assets/images/image.jpg`, would end up being referenced with path of `../assets/images/image.jpg`.
 
 Those paths are later passed to [output path generation in the rule](https://github.com/shakacode/shakapacker/blob/e52b335dbabfb934fe7d3076a8322b97d5ef3470/package/rules/file.js#L25-L26), where we would end up with a path like `static/../../node_modules/some_module/static_file.jpg`, resulting in the file being output in a location two directories above the desired path.
 
 You can avoid this by:
+
 - not using overridden `context` in your webpack config, if there's no good reason for it.
 - using custom Webpack config to modify the static file rule, following a similar process as outlined in the [Webpack Configuration](https://github.com/shakacode/shakapacker/blob/main/README.md#webpack-configuration) section of the readme.
 

data/docs/typescript-migration.md

@@ -254,7 +254,8 @@ npm run type-check
 - `WebpackConfigWithDevServer` - Webpack configuration with dev server
 - `RspackConfigWithDevServer` - Rspack configuration with dev server
 - `WebpackPluginInstance` - Webpack plugin instance type
-- `RspackPlugin` - Rspack plugin interface
+- `RspackPluginInstance` - Rspack plugin instance type
+- `RspackPlugin` - **⚠️ Deprecated:** Use `RspackPluginInstance` instead
 
 ### Helper Types
 - `CompressionPluginOptions` - Compression plugin configuration

data/docs/using_swc_loader.md

@@ -25,7 +25,7 @@ npm install @swc/core swc-loader
 ```
 
 2. Add or change `javascript_transpiler` value in your default `shakapacker.yml` config to `swc`
-The default configuration of babel is done by using `package.json` to use the file within the `shakapacker` package.
+   The default configuration of babel is done by using `package.json` to use the file within the `shakapacker` package.
 
 ```yml
 default: &default
@@ -44,7 +44,7 @@ default: &default
   cache_manifest: false
 
   # Select JavaScript transpiler to use, available options are 'babel' (default) or 'swc'
-  javascript_transpiler: 'swc'
+  javascript_transpiler: "swc"
 ```
 
 ## Usage
@@ -73,7 +73,6 @@ See some examples below of potential `config/swc.config.js`.
 
 ### Example: Enabling top level await and decorators
 
-
 ```js
 const customConfig = {
   options: {
@@ -92,7 +91,7 @@ module.exports = customConfig
 ### Example: Matching existing `@babel/present-env` config
 
 ```js
-const { env } = require('shakapacker')
+const { env } = require("shakapacker")
 
 const customConfig = {
   options: {
@@ -114,9 +113,8 @@ module.exports = customConfig
 
 :warning: Remember that you still need to add [@pmmmwh/react-refresh-webpack-plugin](https://github.com/pmmmwh/react-refresh-webpack-plugin) to your webpack config. The setting below just replaces equivalent `react-refresh/babel` Babel plugin.
 
-
 ```js
-const { env } = require('shakapacker')
+const { env } = require("shakapacker")
 
 const customConfig = {
   options: {
@@ -136,11 +134,10 @@ module.exports = customConfig
 ### Example: Adding browserslist config
 
 ```js
-
 const customConfig = {
   options: {
     env: {
-      targets: '> 0.25%, not dead'
+      targets: "> 0.25%, not dead"
     }
   }
 }
@@ -148,6 +145,109 @@ const customConfig = {
 module.exports = customConfig
 ```
 
+## Using SWC with Stimulus
+
+⚠️ **Important:** If you're using [Stimulus](https://stimulus.hotwired.dev/), you need to configure SWC to preserve class names.
+
+### Required Configuration
+
+SWC mangles (minifies) class names by default for optimization. Since Stimulus relies on class names to discover and instantiate controllers, you must preserve class names in your `config/swc.config.js`:
+
+```js
+// config/swc.config.js
+const { env } = require("shakapacker")
+
+module.exports = {
+  options: {
+    jsc: {
+      // CRITICAL for Stimulus: Prevents SWC from mangling class names
+      keepClassNames: true,
+      transform: {
+        react: {
+          runtime: "automatic",
+          refresh: env.isDevelopment && env.runningWebpackDevServer
+        }
+      }
+    }
+  }
+}
+```
+
+**Note:** Starting with Shakapacker v9.1.0, the default `swc.config.js` created by `rake shakapacker:migrate_to_swc` includes `keepClassNames: true` automatically.
+
+### Why This Matters
+
+Without `keepClassNames: true`, your Stimulus controllers will:
+
+- Load without errors in the browser console
+- Fail silently at runtime
+- Not respond to events
+- Not update the DOM as expected
+
+This makes debugging very difficult since there are no visible JavaScript errors.
+
+### Symptoms of Missing Configuration
+
+If your Stimulus controllers aren't working after migrating to SWC, you'll typically see test failures like:
+
+```
+Failure/Error: expect(page).to have_text("Author: can't be blank")
+  expected to be truthy, got false
+
+Failure/Error: expect(page).to have_css("h2", text: comment.author)
+  expected to be truthy, got false
+```
+
+Your controllers appear to load but don't function correctly:
+
+- Form submissions don't work
+- Validation error messages don't appear
+- Dynamic content doesn't get added to the page
+- No JavaScript errors appear in the console
+
+### Common Configuration Error
+
+❌ **Error:** `` `env` and `jsc.target` cannot be used together``
+
+If you see this error:
+
+```
+ERROR in ./client/app/packs/stimulus-bundle.js
+Module build failed (from ./node_modules/swc-loader/src/index.js):
+Error:
+
+Caused by:
+    `env` and `jsc.target` cannot be used together
+```
+
+**Solution:** Do NOT add `jsc.target` to your configuration. Shakapacker already sets `env` for browser targeting. Use `env` OR `jsc.target`, never both.
+
+❌ **Incorrect:**
+
+```js
+jsc: {
+  target: 'es2015',  // Don't add this!
+  keepClassNames: true,
+}
+```
+
+✅ **Correct:**
+
+```js
+jsc: {
+  keepClassNames: true,  // No target specified
+}
+```
+
+### Troubleshooting Checklist
+
+If your Stimulus controllers aren't working after migrating to SWC:
+
+1. ✅ Verify `keepClassNames: true` is set in `config/swc.config.js`
+2. ✅ Ensure your controllers have explicit class names (not anonymous classes)
+3. ✅ Test with `console.log()` in your controller's `connect()` method to verify it's being instantiated
+4. ✅ Check that you haven't added `jsc.target` (which conflicts with Shakapacker's `env` setting)
+5. ✅ Rebuild your assets: `bin/shakapacker clobber && bin/shakapacker compile`
 
 ## Known limitations
 

data/docs/v9_upgrade.md

@@ -2,6 +2,8 @@
 
 This guide outlines new features, breaking changes, and migration steps for upgrading from Shakapacker v8 to v9.
 
+> **⚠️ Important for v9.1.0 Users:** If you're upgrading to v9.1.0 or later, please note the [SWC Configuration Breaking Change](#swc-loose-mode-breaking-change-v910) below. This affects users who previously configured SWC in v9.0.0.
+
 ## New Features
 
 ### TypeScript Support
@@ -41,6 +43,49 @@ See the [TypeScript Documentation](./typescript.md) for usage examples.
 - Remove custom scripts that set NODE_ENV before running the dev server
 - Remove `NODE_ENV=development` from your `bin/dev` or Procfile.dev
 
+## SWC Loose Mode Breaking Change (v9.1.0)
+
+> **⚠️ This breaking change was introduced in v9.1.0.** If you're upgrading from v9.0.0, pay special attention to this section.
+
+**What changed:** SWC default configuration now uses `loose: false` instead of `loose: true`.
+
+**Why:** The previous default of `loose: true` caused:
+
+- **Silent failures with Stimulus controllers** - Controllers wouldn't register properly
+- **Incorrect behavior with spread operators** on iterables (e.g., `[...new Set()]`)
+- **Deviation from SWC and Babel defaults** - Both tools default to `loose: false`
+
+**Impact:**
+
+- **Most projects:** No action needed. The new default is more correct and fixes bugs.
+- **Stimulus users:** This fixes silent controller failures you may have experienced.
+- **Projects relying on loose mode behavior:** May need to explicitly configure `loose: true` (not recommended).
+
+**When you might need the old behavior:**
+
+- If you have code that breaks with spec-compliant transforms
+- Note: `loose: true` provides slightly faster build times but generates less spec-compliant code
+
+**How to restore old behavior (not recommended):**
+
+Create or update `config/swc.config.js`:
+
+```javascript
+module.exports = {
+  options: {
+    jsc: {
+      // Only use this if you have code that requires loose transforms.
+      // This provides slightly faster build performance but may cause runtime bugs.
+      loose: true // Restore v9.0.0 behavior
+    }
+  }
+}
+```
+
+**Better solution:** Fix your code to work with spec-compliant transforms. The `loose: false` default aligns with both SWC and Babel standards and prevents subtle bugs.
+
+**Using Stimulus?** The new default includes `keepClassNames: true` to prevent SWC from mangling class names. If you use `rake shakapacker:migrate_to_swc`, this is configured automatically. See [Using SWC with Stimulus](./using_swc_loader.md#using-swc-with-stimulus) for details.
+
 ## Breaking Changes
 
 ### 1. CSS Modules Configuration Changed to Named Exports

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

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

data/lib/install/bin/shakapacker

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 ENV["RAILS_ENV"] ||= "development"
-ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile", __FILE__)
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
 ENV["APP_ROOT"] ||= File.expand_path("..", __dir__)
 
 require "bundler/setup"

data/lib/install/bin/shakapacker-dev-server

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 ENV["RAILS_ENV"] ||= "development"
-ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile", __FILE__)
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
 
 require "bundler/setup"
 require "shakapacker"