Add shakapacker:switch_bundler rake task (#660)

This new feature makes it easy to switch between webpack and rspack bundlers
in Shakapacker applications, based on the switch-bundler script from
react_on_rails-demos.

Key features:
- Automatically updates config/shakapacker.yml to switch bundler
- Optional --install-deps flag to manage npm dependencies automatically
- Support for custom dependencies via .shakapacker-switch-bundler-dependencies.yml
- Preserves config file structure and comments during updates
- Updates javascript_transpiler to swc when switching to rspack (recommended)

Usage:
  rails shakapacker:switch_bundler [webpack|rspack] [--install-deps]
  rails shakapacker:switch_bundler --init-config  # Create custom deps config
  rails shakapacker:switch_bundler --help         # Show usage information

Author: justin808

CHANGELOG.md

@@ -33,6 +33,20 @@ Changes since the last non-beta release.
 
 ### Added
 
+- **New `shakapacker:switch_bundler` rake task** for easy switching between webpack and rspack
+  - Automatically updates `config/shakapacker.yml` to switch bundler configuration
+  - Optional `--install-deps` flag to automatically manage dependencies
+  - `--no-uninstall` flag for faster switching by keeping both bundlers installed
+  - **Supports all package managers**: Auto-detects and uses npm, yarn, pnpm, or bun
+  - Shows clear list of packages being added/removed during dependency management
+  - Support for custom dependency configuration via `.shakapacker-switch-bundler-dependencies.yml`
+  - Includes SWC dependencies (`@swc/core`, `swc-loader`) in default webpack setup
+  - Preserves config file structure and comments during updates
+  - Updates `javascript_transpiler` to `swc` when switching to rspack (recommended)
+  - Ruby 2.7+ compatible YAML loading with proper alias/anchor support
+  - Secure command execution (prevents shell injection)
+  - Usage: `rails shakapacker:switch_bundler [webpack|rspack] [--install-deps] [--no-uninstall]`
+  - See rake task help: `rails shakapacker:switch_bundler --help`
 - **Stimulus compatibility built into SWC migration** ([#657](https://github.com/shakacode/shakapacker/issues/657))
   - `rake shakapacker:migrate_to_swc` now creates `config/swc.config.js` with `keepClassNames: true`
   - Prevents SWC from mangling class names, which breaks Stimulus controller discovery

README.md

@@ -1,17 +1,21 @@
 # Rspack Migration Guide for Shakapacker
 
 ## 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,36 +40,44 @@ 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'`
 
 ### 4. Configuration Differences
 
 #### TypeScript Configuration
+
 **Required:** Add `isolatedModules: true` to your `tsconfig.json`:
+
 ```json
 {
   "compilerOptions": {
@@ -75,22 +87,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 +119,7 @@ optimization: {
 ```
 
 #### Minimization
+
 ```javascript
 optimization: {
   minimize: true,
@@ -118,7 +131,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 +145,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 +203,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 +241,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 +272,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)