shakapacker 8.0.2 → 9.2.0

data/docs/rspack_migration_guide.md

@@ -0,0 +1,305 @@
+# 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)$/,
+  loader: 'builtin:swc-loader',
+  options: {
+    jsc: {
+      parser: {
+        syntax: 'typescript', // or 'ecmascript'
+        tsx: true, // for TSX files
+        jsx: true  // for JSX files
+      },
+      transform: {
+        react: {
+          runtime: 'automatic'
+        }
+      }
+    }
+  }
+}
+```
+
+### 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 |
+| `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`     |
+| `@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`         |
+
+#### 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": {
+    "isolatedModules": true
+  }
+}
+```
+
+#### React Fast Refresh
+
+```javascript
+// Development configuration
+const ReactRefreshPlugin = require("@rspack/plugin-react-refresh")
+
+module.exports = {
+  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: {
+    chunks: 'all',
+    cacheGroups: {
+      vendor: {
+        test: /[\\/]node_modules[\\/]/,
+        priority: -10,
+        reuseExistingChunk: true
+      }
+    }
+  }
+}
+```
+
+#### Minimization
+
+```javascript
+optimization: {
+  minimize: true,
+  minimizer: [
+    new rspack.SwcJsMinimizerRspackPlugin(),
+    new rspack.LightningCssMinimizerRspackPlugin()
+  ]
+}
+```
+
+### 6. Development Server
+
+Rspack uses its own dev server with some configuration differences:
+
+```javascript
+devServer: {
+  // Rspack-specific: Force writing assets to disk
+  devMiddleware: {
+    writeToDisk: true
+  }
+}
+```
+
+## 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
+
+# Install Rspack
+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"
+```
+
+### 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
+
+# Production build
+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`.
+
+## Performance Tips
+
+1. **Use Built-in Loaders:** Always prefer Rspack's built-in loaders for better performance
+2. **Minimize Plugins:** Use only necessary plugins as each adds overhead
+3. **Enable Caching:** Rspack has built-in persistent caching
+4. **Use SWC:** The built-in SWC loader is significantly faster than Babel
+
+## Debugging Configuration
+
+To compare your webpack and rspack configurations during migration:
+
+```bash
+# Export webpack configs before switching
+bin/export-bundler-config --doctor
+
+# Switch to rspack
+rails shakapacker:switch_bundler rspack --install-deps
+
+# Export rspack configs to compare
+bin/export-bundler-config --doctor
+
+# Compare the files in shakapacker-config-exports/
+diff shakapacker-config-exports/webpack-production-client.yaml \
+     shakapacker-config-exports/rspack-production-client.yaml
+```
+
+The config export utility creates annotated YAML files that make it easy to:
+
+- Verify plugin replacements are correct
+- Compare loader configurations
+- Identify missing or different options
+- Debug configuration issues
+
+See the [Troubleshooting Guide](./troubleshooting.md#exporting-webpack--rspack-configuration) for more details.
+
+## Resources
+
+- [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)

data/docs/subresource_integrity.md

@@ -0,0 +1,54 @@
+# Subresource integrity
+It's a cryptographic hash that helps browsers check that the served js or css file has not been tampered in any way.
+
+[MDN - Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity)
+
+## Important notes
+- If you somehow modify the file after the hash was generated, it will automatically be considered as tampered, and the browser will not allow it to be executed.
+- Enabling subresource integrity generation, will change the structure of `manifest.json`. Keep that in mind if you utilize this file in any other custom implementation.
+
+Before:
+```json
+{
+  "application.js": "/path_to_asset"
+}
+```
+
+After:
+```json
+{
+  "application.js": {
+    "src": "/path_to_asset",
+    "integrity": "<sha256-hash> <sha384-hash> <sha512-hash>"
+  }
+}
+```
+
+## Possible CORS issues
+Enabling subresource integrity for an asset, actually enforces CORS checks on that resource too. Which means that
+if you haven't set that up properly beforehand, it will probably lead to CORS errors with cached assets.
+
+[MDN - How browsers handle Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity#how_browsers_handle_subresource_integrity)
+
+## Configuration
+
+By default, this setting is disabled, to ensure backwards compatibility, and let developers adapt at their own pace.
+This may change in the future, as it is a very nice security feature, and it should be enabled by default.
+
+To enable it, just add this in `shakapacker.yml`
+```yml
+  integrity:
+    enabled: true    
+```
+
+For further customization, you can also utilize the options `hash_functions` that control the functions used to generate 
+integrity hashes. And `cross_origin` that sets the cross-origin loading attribute.
+
+```yml
+  integrity:
+    enabled: true
+    hash_functions: ["sha256", "sha384", "sha512"]
+    cross_origin: "anonymous" # or "use-credentials"
+```
+
+This will utilize under the hood webpack-subresource-integrity plugin and will modify `manifest.json` to include integrity hashes.

data/docs/transpiler-migration.md

@@ -0,0 +1,209 @@
+# 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:
+
+- **Webpack**: `babel` (default) - Maintains backward compatibility
+- **Rspack**: `swc` (default) - Modern, faster transpiler for new bundler
+
+## Available Transpilers
+
+- `babel` - Traditional JavaScript transpiler with wide ecosystem support
+- `swc` - Rust-based transpiler, 20-70x faster than Babel
+- `esbuild` - Go-based transpiler, extremely fast
+- `none` - No transpilation (use native JavaScript)
+
+## Configuration
+
+Set the transpiler in your `config/shakapacker.yml`:
+
+```yaml
+default: &default
+  # For webpack users (babel is default, no change needed)
+  javascript_transpiler: babel
+
+  # To opt-in to SWC for better performance
+  javascript_transpiler: swc
+
+  # For rspack users (swc is default, no change needed)
+  assets_bundler: rspack
+  javascript_transpiler: swc
+```
+
+## Migration Guide
+
+### Migrating from Babel to SWC
+
+SWC offers significant performance improvements while maintaining high compatibility with Babel.
+
+#### 1. Install SWC dependencies
+
+```bash
+yarn add --dev @swc/core swc-loader
+```
+
+#### 2. Update your configuration
+
+```yaml
+# config/shakapacker.yml
+default: &default
+  javascript_transpiler: swc
+```
+
+#### 3. Create SWC configuration (optional)
+
+If you need custom transpilation settings, create `config/swc.config.js`:
+
+```javascript
+// config/swc.config.js
+// This file is merged with Shakapacker's default SWC configuration
+// See: https://swc.rs/docs/configuration/compilation
+
+module.exports = {
+  jsc: {
+    transform: {
+      react: {
+        runtime: "automatic"
+      }
+    }
+  }
+}
+```
+
+**Important:** Use `config/swc.config.js` instead of `.swcrc`. The `.swcrc` file completely overrides Shakapacker's default SWC settings and can cause build failures. `config/swc.config.js` properly merges with Shakapacker's defaults.
+
+#### 4. Update React configuration (if using React)
+
+For React projects, ensure you have the correct refresh plugin:
+
+```bash
+# For webpack
+yarn add --dev @pmmmwh/react-refresh-webpack-plugin
+
+# For rspack
+yarn add --dev @rspack/plugin-react-refresh
+```
+
+### Performance Comparison
+
+Typical build time improvements when migrating from Babel to SWC:
+
+| Project Size           | Babel | SWC | Improvement |
+| ---------------------- | ----- | --- | ----------- |
+| Small (<100 files)     | 5s    | 1s  | 5x faster   |
+| Medium (100-500 files) | 20s   | 3s  | 6.7x faster |
+| Large (500+ files)     | 60s   | 8s  | 7.5x faster |
+
+### Compatibility Notes
+
+#### Babel Features Not Yet in SWC
+
+- Some experimental/stage-0 proposals
+- Custom Babel plugins (need SWC equivalents)
+- Babel macros
+
+#### Migration Checklist
+
+- [ ] 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:
+
+```yaml
+# config/shakapacker.yml
+default: &default
+  javascript_transpiler: babel # Revert to babel
+```
+
+Then rebuild your application:
+
+```bash
+bin/shakapacker clobber
+bin/shakapacker compile
+```
+
+## Environment Variables
+
+You can also control the transpiler via environment variables:
+
+```bash
+# Override config file setting
+SHAKAPACKER_JAVASCRIPT_TRANSPILER=swc bin/shakapacker compile
+
+# For debugging
+SHAKAPACKER_DEBUG_CACHE=true bin/shakapacker compile
+```
+
+## Troubleshooting
+
+### Issue: Build fails after switching to SWC
+
+**Solution**: Ensure all SWC dependencies are installed:
+
+```bash
+yarn add --dev @swc/core swc-loader
+```
+
+### Issue: React Fast Refresh not working
+
+**Solution**: Install the correct refresh plugin for your bundler:
+
+```bash
+# Webpack
+yarn add --dev @pmmmwh/react-refresh-webpack-plugin
+
+# Rspack
+yarn add --dev @rspack/plugin-react-refresh
+```
+
+### Issue: Decorators not working
+
+**Solution**: Enable decorator support in `config/swc.config.js`:
+
+```javascript
+// config/swc.config.js
+module.exports = {
+  jsc: {
+    parser: {
+      decorators: true,
+      decoratorsBeforeExport: true
+    }
+  }
+}
+```
+
+## Further Reading
+
+- [SWC Documentation](https://swc.rs/docs/getting-started)
+- [Babel to SWC Migration Guide](https://swc.rs/docs/migrating-from-babel)
+- [Rspack Configuration](https://www.rspack.dev/config/index)