shakapacker 9.0.0 → 9.1.0

data/docs/rspack_migration_guide.md

@@ -1,17 +1,23 @@
 # Rspack Migration Guide for Shakapacker
 
+> 💡 **Quick Start**: For a step-by-step migration guide from Webpack to Rspack, see [Common Upgrades Guide - Webpack to Rspack](./common-upgrades.md#migrating-from-webpack-to-rspack).
+
 ## Overview
+
 This guide documents the differences between webpack and Rspack configurations in Shakapacker, and provides migration guidance for users switching to Rspack.
 
 ## Key Differences from Webpack
 
 ### 1. Built-in Loaders
+
 Rspack provides built-in loaders for better performance:
 
 **JavaScript/TypeScript:**
+
 - Use `builtin:swc-loader` instead of `babel-loader` or `ts-loader`
 - 20x faster than Babel on single thread, 70x on multiple cores
 - Configuration example:
+
 ```javascript
 {
   test: /\.(js|jsx|ts|tsx)$/,
@@ -36,28 +42,34 @@ Rspack provides built-in loaders for better performance:
 ### 2. Plugin Replacements
 
 #### Built-in Rspack Alternatives
-| Webpack Plugin | Rspack Alternative | Status |
-|---------------|-------------------|---------|
-| `copy-webpack-plugin` | `rspack.CopyRspackPlugin` | ✅ Built-in |
-| `mini-css-extract-plugin` | `rspack.CssExtractRspackPlugin` | ✅ Built-in |
-| `terser-webpack-plugin` | `rspack.SwcJsMinimizerRspackPlugin` | ✅ Built-in |
+
+| Webpack Plugin                 | Rspack Alternative                         | Status      |
+| ------------------------------ | ------------------------------------------ | ----------- |
+| `copy-webpack-plugin`          | `rspack.CopyRspackPlugin`                  | ✅ Built-in |
+| `mini-css-extract-plugin`      | `rspack.CssExtractRspackPlugin`            | ✅ Built-in |
+| `terser-webpack-plugin`        | `rspack.SwcJsMinimizerRspackPlugin`        | ✅ Built-in |
 | `css-minimizer-webpack-plugin` | `rspack.LightningCssMinimizerRspackPlugin` | ✅ Built-in |
 
 #### Community Alternatives
-| Webpack Plugin | Rspack Alternative | Package |
-|---------------|-------------------|----------|
-| `fork-ts-checker-webpack-plugin` | `ts-checker-rspack-plugin` | `npm i -D ts-checker-rspack-plugin` |
+
+| Webpack Plugin                         | Rspack Alternative             | Package                                 |
+| -------------------------------------- | ------------------------------ | --------------------------------------- |
+| `fork-ts-checker-webpack-plugin`       | `ts-checker-rspack-plugin`     | `npm i -D ts-checker-rspack-plugin`     |
 | `@pmmmwh/react-refresh-webpack-plugin` | `@rspack/plugin-react-refresh` | `npm i -D @rspack/plugin-react-refresh` |
-| `eslint-webpack-plugin` | `eslint-rspack-plugin` | `npm i -D eslint-rspack-plugin` |
+| `eslint-webpack-plugin`                | `eslint-rspack-plugin`         | `npm i -D eslint-rspack-plugin`         |
 
 #### Incompatible Plugins
+
 The following webpack plugins are NOT compatible with Rspack:
+
 - `webpack.optimize.LimitChunkCountPlugin` - Use `optimization.splitChunks` configuration instead
 - `webpack-manifest-plugin` - Use `rspack-manifest-plugin` instead
 - Git revision plugins - Use alternative approaches
 
 ### 3. Asset Module Types
+
 Replace file loaders with asset modules:
+
 - `file-loader` → `type: 'asset/resource'`
 - `url-loader` → `type: 'asset/inline'`
 - `raw-loader` → `type: 'asset/source'`
@@ -65,7 +77,9 @@ Replace file loaders with asset modules:
 ### 4. Configuration Differences
 
 #### TypeScript Configuration
+
 **Required:** Add `isolatedModules: true` to your `tsconfig.json`:
+
 ```json
 {
   "compilerOptions": {
@@ -75,22 +89,22 @@ Replace file loaders with asset modules:
 ```
 
 #### React Fast Refresh
+
 ```javascript
 // Development configuration
-const ReactRefreshPlugin = require('@rspack/plugin-react-refresh');
+const ReactRefreshPlugin = require("@rspack/plugin-react-refresh")
 
 module.exports = {
-  plugins: [
-    new ReactRefreshPlugin(),
-    new rspack.HotModuleReplacementPlugin()
-  ]
-};
+  plugins: [new ReactRefreshPlugin(), new rspack.HotModuleReplacementPlugin()]
+}
 ```
 
 ### 5. Optimization Differences
 
 #### Code Splitting
+
 Rspack's `splitChunks` configuration is similar to webpack but with some differences:
+
 ```javascript
 optimization: {
   splitChunks: {
@@ -107,6 +121,7 @@ optimization: {
 ```
 
 #### Minimization
+
 ```javascript
 optimization: {
   minimize: true,
@@ -118,7 +133,9 @@ optimization: {
 ```
 
 ### 6. Development Server
+
 Rspack uses its own dev server with some configuration differences:
+
 ```javascript
 devServer: {
   // Rspack-specific: Force writing assets to disk
@@ -130,7 +147,55 @@ devServer: {
 
 ## Migration Checklist
 
+### Quick Start: Using the Switch Bundler Task
+
+Shakapacker provides a convenient rake task to switch between webpack and rspack:
+
+```bash
+# Switch to rspack with automatic dependency management
+rails shakapacker:switch_bundler rspack --install-deps
+# or with rake (note the -- separator)
+rake shakapacker:switch_bundler rspack -- --install-deps
+
+# Fast switching without uninstalling old bundler (keeps both)
+rails shakapacker:switch_bundler webpack --install-deps --no-uninstall
+rake shakapacker:switch_bundler rspack -- --install-deps --no-uninstall
+
+# Switch to rspack manually (you manage dependencies yourself)
+rails shakapacker:switch_bundler rspack
+rake shakapacker:switch_bundler rspack
+
+# Switch back to webpack if needed
+rails shakapacker:switch_bundler webpack --install-deps
+rake shakapacker:switch_bundler webpack -- --install-deps
+
+# Show help
+rails shakapacker:switch_bundler --help
+rake shakapacker:switch_bundler -- --help
+```
+
+**Note:** When using `rake`, you must use `--` to separate rake options from task arguments.
+
+The task will:
+
+- Update `config/shakapacker.yml` to switch the bundler
+- Optionally install/uninstall npm dependencies with `--install-deps`
+- Use `--no-uninstall` to skip uninstalling the old bundler's packages (faster switching, keeps both bundlers installed)
+- Update `javascript_transpiler` to `swc` when switching to rspack (recommended)
+- Preserve your config file comments and structure
+
+**Custom Dependencies:** You can customize which dependencies are installed by creating a `.shakapacker-switch-bundler-dependencies.yml` file:
+
+```bash
+rails shakapacker:switch_bundler --init-config
+```
+
+### Manual Migration Steps
+
+If you prefer to migrate manually or need more control:
+
 ### Step 1: Update Dependencies
+
 ```bash
 # Remove webpack dependencies
 npm uninstall webpack webpack-cli webpack-dev-server
@@ -140,27 +205,33 @@ npm install --save-dev @rspack/core @rspack/cli
 ```
 
 ### Step 2: Update Configuration Files
+
 1. Create `config/rspack/rspack.config.js` based on your webpack config
 2. Update `config/shakapacker.yml`:
+
 ```yaml
-assets_bundler: 'rspack'
+assets_bundler: "rspack"
 ```
 
 ### Step 3: Replace Loaders
+
 - Replace `babel-loader` with `builtin:swc-loader`
 - Remove `file-loader`, `url-loader`, `raw-loader` - use asset modules
 - Update CSS loaders to use Rspack's built-in support
 
 ### Step 4: Update Plugins
+
 - Replace plugins with Rspack alternatives (see table above)
 - Remove incompatible plugins
 - Add Rspack-specific plugins as needed
 
 ### Step 5: TypeScript Setup
+
 1. Add `isolatedModules: true` to `tsconfig.json`
 2. Optional: Add `ts-checker-rspack-plugin` for type checking
 
 ### Step 6: Test Your Build
+
 ```bash
 # Development build
 bin/shakapacker
@@ -172,18 +243,22 @@ bin/shakapacker --mode production
 ## Common Issues and Solutions
 
 ### Issue: LimitChunkCountPlugin Error
+
 **Error:** `Cannot read properties of undefined (reading 'tap')`
 **Solution:** Remove `webpack.optimize.LimitChunkCountPlugin` and use `splitChunks` configuration instead.
 
 ### Issue: Missing Loaders
+
 **Error:** Module parse errors
 **Solution:** Check console logs for skipped loaders and install missing dependencies.
 
 ### Issue: CSS Extraction
+
 **Error:** CSS not being extracted properly
 **Solution:** Use `rspack.CssExtractRspackPlugin` instead of `mini-css-extract-plugin`.
 
 ### Issue: TypeScript Errors
+
 **Error:** TypeScript compilation errors
 **Solution:** Ensure `isolatedModules: true` is set in `tsconfig.json`.
 
@@ -199,4 +274,4 @@ bin/shakapacker --mode production
 - [Rspack Documentation](https://rspack.rs)
 - [Rspack Examples](https://github.com/rspack-contrib/rspack-examples)
 - [Awesome Rspack](https://github.com/rspack-contrib/awesome-rspack)
-- [Migration Guide](https://rspack.rs/guide/migration/webpack)
+- [Migration Guide](https://rspack.rs/guide/migration/webpack)

data/docs/transpiler-migration.md

@@ -1,5 +1,7 @@
 # JavaScript Transpiler Configuration
 
+> 💡 **Quick Start**: For a concise guide to migrating from Babel to SWC, see [Common Upgrades Guide - Babel to SWC](./common-upgrades.md#migrating-from-babel-to-swc).
+
 ## Default Transpilers
 
 Shakapacker uses different default JavaScript transpilers based on the bundler:
@@ -108,12 +110,31 @@ Typical build time improvements when migrating from Babel to SWC:
 - [ ] Back up your current configuration
 - [ ] Install SWC dependencies
 - [ ] Update `shakapacker.yml`
+- [ ] If using Stimulus, ensure `keepClassNames: true` is set in `config/swc.config.js` (automatically included in v9.1.0+)
 - [ ] Test your build locally
 - [ ] Run your test suite
 - [ ] Check browser compatibility
 - [ ] Deploy to staging environment
 - [ ] Monitor for any runtime issues
 
+#### Stimulus Compatibility
+
+If you're using [Stimulus](https://stimulus.hotwired.dev/), you must configure SWC to preserve class names. See the [Using SWC with Stimulus](using_swc_loader.md#using-swc-with-stimulus) section for detailed instructions.
+
+**Quick summary:** Add `keepClassNames: true` to your `config/swc.config.js`:
+
+```javascript
+module.exports = {
+  options: {
+    jsc: {
+      keepClassNames: true // Required for Stimulus
+    }
+  }
+}
+```
+
+Starting with Shakapacker v9.1.0, running `rake shakapacker:migrate_to_swc` automatically creates a configuration with this setting.
+
 ### Rollback Plan
 
 If you encounter issues, rolling back is simple:

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