shakapacker 9.0.0 → 9.2.0

data/docs/releasing.md

@@ -0,0 +1,197 @@
+# Releasing Shakapacker
+
+This guide is for Shakapacker maintainers who need to publish a new release.
+
+## Prerequisites
+
+1. **Install required tools:**
+
+   ```bash
+   bundle install              # Installs gem-release
+   yarn global add release-it  # Installs release-it for npm publishing
+   ```
+
+2. **Ensure you have publishing access:**
+
+   - npm: You must be a collaborator on the [shakapacker npm package](https://www.npmjs.com/package/shakapacker)
+   - RubyGems: You must be an owner of the [shakapacker gem](https://rubygems.org/gems/shakapacker)
+
+3. **Enable 2FA on both platforms:**
+   - npm: 2FA is required for publishing
+   - RubyGems: 2FA is required for publishing
+
+## Release Process
+
+### 1. Prepare the Release
+
+Before running the release task:
+
+1. Ensure all desired changes are merged to `main` branch
+2. Update `CHANGELOG.md` with the new version and release notes
+3. Commit the CHANGELOG changes
+4. Ensure your working directory is clean (`git status` shows no uncommitted changes)
+
+### 2. Run the Release Task
+
+The automated release task handles the entire release process:
+
+```bash
+# For a specific version (e.g., 9.1.0)
+rake create_release[9.1.0]
+
+# For a beta release (note: use period, not dash)
+rake create_release[9.2.0.beta.1]  # Creates npm package 9.2.0-beta.1
+
+# For a patch version bump (auto-increments)
+rake create_release
+
+# Dry run to test without publishing
+rake create_release[9.1.0,true]
+```
+
+### 3. What the Release Task Does
+
+The `create_release` task automatically:
+
+1. **Pulls latest changes** from the repository
+2. **Bumps version numbers** in:
+   - `lib/shakapacker/version.rb` (Ruby gem version)
+   - `package.json` (npm package version - converted from Ruby format)
+3. **Publishes to npm:**
+   - Prompts for npm OTP (2FA code)
+   - Creates git tag
+   - Pushes to GitHub
+4. **Publishes to RubyGems:**
+   - Prompts for RubyGems OTP (2FA code)
+5. **Updates spec/dummy lockfiles:**
+   - Runs `bundle install` to update `Gemfile.lock`
+   - Runs `npm install` to update `package-lock.json` (yarn.lock may also be updated for multi-package-manager compatibility testing)
+6. **Commits and pushes lockfile changes** automatically
+
+### 4. Version Format
+
+**Important:** Use Ruby gem version format (no dashes):
+
+- ✅ Correct: `9.1.0`, `9.2.0.beta.1`, `9.0.0.rc.2`
+- ❌ Wrong: `9.1.0-beta.1`, `9.0.0-rc.2`
+
+The task automatically converts Ruby gem format to npm semver format:
+
+- Ruby: `9.2.0.beta.1` → npm: `9.2.0-beta.1`
+- Ruby: `9.0.0.rc.2` → npm: `9.0.0-rc.2`
+
+**Examples:**
+
+```bash
+# Regular release
+rake create_release[9.1.0]  # Gem: 9.1.0, npm: 9.1.0
+
+# Beta release
+rake create_release[9.2.0.beta.1]  # Gem: 9.2.0.beta.1, npm: 9.2.0-beta.1
+
+# Release candidate
+rake create_release[10.0.0.rc.1]  # Gem: 10.0.0.rc.1, npm: 10.0.0-rc.1
+```
+
+### 5. During the Release
+
+1. When prompted for **npm OTP**, enter your 2FA code from your authenticator app
+2. Accept defaults for release-it options
+3. When prompted for **RubyGems OTP**, enter your 2FA code
+4. The script will automatically commit and push lockfile updates
+
+### 6. After Release
+
+1. Verify the release on:
+
+   - [npm](https://www.npmjs.com/package/shakapacker)
+   - [RubyGems](https://rubygems.org/gems/shakapacker)
+   - [GitHub releases](https://github.com/shakacode/shakapacker/releases)
+
+2. Check that the lockfile commit was pushed:
+
+   ```bash
+   git log --oneline -5
+   # Should see "Update spec/dummy lockfiles after release"
+   ```
+
+3. Announce the release (if appropriate):
+   - Post in relevant Slack/Discord channels
+   - Tweet about major releases
+   - Update documentation if needed
+
+## Troubleshooting
+
+### Uncommitted Changes After Release
+
+If you see uncommitted changes to lockfiles after a release, this means:
+
+1. The release was successful but the lockfile commit step may have failed
+2. **Solution:** Manually commit these files:
+   ```bash
+   git add spec/dummy/Gemfile.lock spec/dummy/package-lock.json spec/dummy/yarn.lock
+   git commit -m 'Update spec/dummy lockfiles after release'
+   git push
+   ```
+
+### Failed npm or RubyGems Publish
+
+If publishing fails partway through:
+
+1. Check which step failed (npm or RubyGems)
+2. If npm failed: Fix the issue and manually run `npm publish`
+3. If RubyGems failed: Fix the issue and manually run `gem release`
+4. Then manually update and commit spec/dummy lockfiles
+
+### Wrong Version Format
+
+If you accidentally use npm format (with dashes):
+
+1. The gem will be created with an invalid version
+2. **Solution:** Don't push the changes, reset your branch:
+   ```bash
+   git reset --hard HEAD
+   ```
+3. Re-run with correct Ruby gem format
+
+## Manual Release Steps
+
+If you need to release manually (not recommended):
+
+1. **Bump version:**
+
+   ```bash
+   gem bump --version 9.1.0
+   bundle install
+   ```
+
+2. **Publish to npm:**
+
+   ```bash
+   release-it 9.1.0 --npm.publish
+   ```
+
+3. **Publish to RubyGems:**
+
+   ```bash
+   gem release
+   ```
+
+4. **Update lockfiles:**
+   ```bash
+   cd spec/dummy
+   bundle install
+   npm install
+   cd ../..
+   git add spec/dummy/Gemfile.lock spec/dummy/package-lock.json spec/dummy/yarn.lock
+   git commit -m 'Update spec/dummy lockfiles after release'
+   git push
+   ```
+
+## Questions?
+
+If you encounter issues not covered here, please:
+
+1. Check the [CONTRIBUTING.md](../CONTRIBUTING.md) guide
+2. Ask in the maintainers channel
+3. Update this documentation for future releases

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`.
 
@@ -194,9 +269,37 @@ bin/shakapacker --mode production
 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)
+- [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: