shakapacker 8.0.2 → 9.2.0

data/docs/optional-peer-dependencies.md

@@ -0,0 +1,198 @@
+# Optional Peer Dependencies in Shakapacker
+
+## Overview
+
+As of Shakapacker v9, all peer dependencies are marked as optional via `peerDependenciesMeta`. This design provides maximum flexibility while maintaining clear version constraints.
+
+## Key Benefits
+
+1. **No Installation Warnings** - Package managers (npm, yarn, pnpm) won't warn about missing peer dependencies
+2. **Install Only What You Need** - Users only install packages for their chosen configuration
+3. **Clear Version Constraints** - When packages are installed, version compatibility is still enforced
+4. **Smaller Node Modules** - Reduced disk usage by not installing unnecessary packages
+
+## Implementation Details
+
+### Package.json Structure
+
+```json
+{
+  "dependencies": {
+    "js-yaml": "^4.1.0",
+    "path-complete-extname": "^1.0.0",
+    "webpack-merge": "^5.8.0"  // Direct dependency - always available
+  },
+  "peerDependencies": {
+    "webpack": "^5.76.0",
+    "@rspack/core": "^1.0.0",
+    // ... all build tools
+  },
+  "peerDependenciesMeta": {
+    "webpack": { "optional": true },
+    "@rspack/core": { "optional": true },
+    // ... all marked as optional
+  }
+}
+```
+
+### TypeScript Type-Only Imports
+
+To prevent runtime errors when optional packages aren't installed, all webpack imports use type-only syntax:
+
+```typescript
+// @ts-ignore: webpack is an optional peer dependency (using type-only import)
+import type { Configuration } from "webpack"
+```
+
+Type-only imports are erased during compilation and don't trigger module resolution at runtime.
+
+## Configuration Examples
+
+### Webpack + Babel (Traditional)
+```json
+{
+  "dependencies": {
+    "shakapacker": "^9.0.0",
+    "webpack": "^5.76.0",
+    "webpack-cli": "^5.0.0",
+    "babel-loader": "^8.2.4",
+    "@babel/core": "^7.17.9",
+    "@babel/preset-env": "^7.16.11"
+  }
+}
+```
+
+### Webpack + SWC (20x Faster)
+```json
+{
+  "dependencies": {
+    "shakapacker": "^9.0.0",
+    "webpack": "^5.76.0",
+    "webpack-cli": "^5.0.0",
+    "@swc/core": "^1.3.0",
+    "swc-loader": "^0.2.0"
+  }
+}
+```
+
+### Rspack + SWC (10x Faster Bundling)
+```json
+{
+  "dependencies": {
+    "shakapacker": "^9.0.0",
+    "@rspack/core": "^1.0.0",
+    "@rspack/cli": "^1.0.0",
+    "rspack-manifest-plugin": "^5.0.0"
+  }
+}
+```
+
+## Migration Guide
+
+### From v8 to v9
+
+If upgrading from Shakapacker v8:
+
+1. **No action required** - Your existing dependencies will continue to work
+2. **No more warnings** - Peer dependency warnings will disappear after upgrading
+3. **Option to optimize** - You can now remove unused dependencies (e.g., remove Babel if using SWC)
+
+### New Installations
+
+The installer (`rails shakapacker:install`) only adds packages needed for your configuration:
+- Detects your preferred bundler (webpack/rspack)
+- Installs appropriate JavaScript transpiler (babel/swc/esbuild)
+- Adds only required dependencies
+
+## Version Constraints
+
+Version ranges are carefully chosen for compatibility:
+
+- **Broader ranges for peer deps** - Allows flexibility (e.g., `^5.76.0` for webpack)
+- **Specific versions in devDeps** - Ensures testing against known versions
+- **Forward compatibility** - Ranges include future minor versions (e.g., `^5.0.0 || ^6.0.0`)
+
+## Testing
+
+### Installation Tests
+
+Test that no warnings appear during installation:
+
+```bash
+# Test script available at test/peer-dependencies.sh
+./test/peer-dependencies.sh
+```
+
+### Runtime Tests
+
+Verify Shakapacker loads without optional dependencies:
+
+```javascript
+// This works even without webpack installed (when using rspack)
+const shakapacker = require('shakapacker');
+```
+
+### CI Integration
+
+The test suite includes:
+- `spec/shakapacker/optional_dependencies_spec.rb` - Package.json structure validation
+- `spec/shakapacker/doctor_optional_peer_spec.rb` - Doctor command validation
+- `test/peer-dependencies.sh` - Installation warning tests
+
+## Troubleshooting
+
+### Still seeing peer dependency warnings?
+
+1. Ensure you're using Shakapacker v9.0.0 or later
+2. Clear your package manager cache:
+   - npm: `npm cache clean --force`
+   - yarn: `yarn cache clean`
+   - pnpm: `pnpm store prune`
+3. Reinstall dependencies
+
+### Module not found errors?
+
+1. Check you've installed required dependencies for your configuration
+2. Refer to the configuration examples above
+3. Run `rails shakapacker:doctor` for diagnostics
+
+### TypeScript errors?
+
+The `@ts-ignore` comments are intentional and necessary for optional dependencies.
+They prevent TypeScript errors when optional packages aren't installed.
+
+## Contributing
+
+When adding new dependencies:
+
+1. Add to `peerDependencies` with appropriate version range
+2. Mark as optional in `peerDependenciesMeta`
+3. Use type-only imports in TypeScript: `import type { ... }`
+4. Test with all package managers (npm, yarn, pnpm)
+5. Update this documentation if needed
+
+## Design Rationale
+
+This approach balances several concerns:
+
+1. **User Experience** - No confusing warnings during installation
+2. **Flexibility** - Support multiple configurations without forcing unnecessary installs
+3. **Compatibility** - Maintain version constraints for safety
+4. **Performance** - Reduce installation time and disk usage
+5. **Type Safety** - TypeScript support without runtime dependencies
+
+## Future Improvements
+
+Potential enhancements for future versions:
+
+1. **Conditional exports** - Use package.json exports field for better tree-shaking
+2. **Dynamic imports** - Load bundler-specific code only when needed
+3. **Doctor updates** - Enhance doctor command to better understand optional dependencies
+4. **Automated testing** - Add CI jobs testing each configuration combination
+
+## References
+
+- [npm: peerDependenciesMeta](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#peerdependenciesmeta)
+- [TypeScript: Type-Only Imports](https://www.typescriptlang.org/docs/handbook/modules.html#type-only-imports-and-exports)
+- [Shakapacker Issue #565](https://github.com/shakacode/shakapacker/issues/565)
+- [Pull Request #615](https://github.com/shakacode/shakapacker/pull/615)

data/docs/peer-dependencies.md

@@ -0,0 +1,60 @@
+# Shakapacker's Peer Dependencies
+## Last updated for our 9.0.0 version — see lib/install/package.json
+
+To simplify peer dependencies while supporting both webpack & rspack, we decided to document the dependencies here instead of creating two separate npm packages.
+
+**Important Note**: Starting with v9, Babel dependencies are no longer included as peer dependencies. They will be installed automatically only if you're using Babel as your JavaScript transpiler.
+
+## Essential for Rspack
+```
+    "@rspack/cli": "^1.0.0",
+    "@rspack/core": "^1.0.0",
+    "rspack-manifest-plugin": "^5.0.0",
+```
+## Essential for Webpack
+```
+    "mini-css-extract-plugin": "^2.0.0",
+    "terser-webpack-plugin": "^5.3.1",
+    "webpack": "^5.76.0",
+    "webpack-assets-manifest": "^5.0.6 || ^6.0.0",
+    "webpack-cli": "^4.9.2 || ^5.0.0 || ^6.0.0",
+    "webpack-dev-server": "^4.15.2 || ^5.2.2",
+    "webpack-merge": "^5.8.0 || ^6.0.0",
+    "webpack-subresource-integrity": "^5.1.0"
+```
+
+## Highly recommended
+```
+    "compression-webpack-plugin": "^9.0.0 || ^10.0.0|| ^11.0.0",
+    "css-loader": "^6.0.0 || ^7.0.0",
+    "sass-loader": "^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0",
+    "style-loader": "^3.0.0 || ^4.0.0",
+```
+
+## Optional JavaScript Transpilers
+
+### Babel (installed automatically when `javascript_transpiler: 'babel'`)
+```
+    "@babel/core": "^7.17.9",
+    "@babel/plugin-transform-runtime": "^7.17.0",
+    "@babel/preset-env": "^7.16.11",
+    "@babel/runtime": "^7.17.9",
+    "babel-loader": "^8.2.4 || ^9.0.0 || ^10.0.0",
+```
+Note: These dependencies are only installed if you're using Babel as your JavaScript transpiler. Consider using SWC or esbuild for better performance.
+
+### SWC (default - 20x faster than Babel)
+```
+    "@swc/core": "latest",
+    "swc-loader": "latest"
+```
+- **For webpack**: Installed automatically when using default configuration
+- **For rspack**: Built-in, no additional installation needed (rspack includes SWC natively)
+- Manual install: `npm install @swc/core swc-loader`
+
+### esbuild
+```
+    "esbuild": "latest",
+    "esbuild-loader": "latest"
+```
+Install manually with: `npm install esbuild esbuild-loader`

data/docs/react.md

@@ -34,7 +34,7 @@ Update the Babel configuration in the `package.json` file:
 },
 ```
 
-And that's it. You can now create a React app using `app/javascript/application.js` as your entry point.
+And that's it. You can now create a React app using `app/javascript/packs/application.js` as your entry point.
 
 ## Enabling Hot Module Replacement (HMR)
 
@@ -61,11 +61,7 @@ const webpackConfig = generateWebpackConfig();
 
 if (isDevelopment && inliningCss) {
   webpackConfig.plugins.push(
-    new ReactRefreshWebpackPlugin({
-      overlay: {
-        sockPort: webpackConfig.devServer.port,
-      },
-    })
+    new ReactRefreshWebpackPlugin()
   );
 }
 
@@ -152,11 +148,11 @@ echo '<div id="root"></div>' > app/views/site/index.html.erb
 touch app/javascript/App.css app/javascript/App.js
 ```
 
-4. Edit `app/javascript/application.js` like so:
+4. Edit `app/javascript/packs/application.js` like so:
 ```jsx
 import React from 'react';
 import { createRoot } from 'react-dom/client';
-import HelloMessage from './App';
+import HelloMessage from '../App';
 
 const container = document.getElementById('root');
 const root = createRoot(container);
@@ -201,11 +197,7 @@ const webpackConfig = generateWebpackConfig();
 
 if (isDevelopment && inliningCss) {
   webpackConfig.plugins.push(
-    new ReactRefreshWebpackPlugin({
-      overlay: {
-        sockPort: webpackConfig.devServer.port,
-      },
-    })
+    new ReactRefreshWebpackPlugin()
   );
 }
 
@@ -267,4 +259,4 @@ rails s
 
 11. Edit either the React component at `app/javascript/App.js` or the CSS file at `app/javascript/App.css` and observe the HMR goodness.
 
-Note that HMR will not work if you edit `app/javascript/application.js` and experience a full refresh with a warning in the console. For more info on this, see here: https://github.com/pmmmwh/react-refresh-webpack-plugin/issues/177
+Note that HMR will not work if you edit `app/javascript/packs/application.js` and experience a full refresh with a warning in the console. For more info on this, see here: https://github.com/pmmmwh/react-refresh-webpack-plugin/issues/177

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.md

@@ -0,0 +1,190 @@
+# Rspack Integration
+
+Shakapacker supports [Rspack](https://rspack.rs) as an alternative assets bundler to Webpack. Rspack is a fast Rust-based web bundler with webpack-compatible API that can significantly speed up your build times.
+
+## Installation
+
+First, install the required Rspack dependencies:
+
+```bash
+npm install @rspack/core @rspack/cli -D
+# or
+yarn add @rspack/core @rspack/cli -D
+# or  
+pnpm add @rspack/core @rspack/cli -D
+# or
+bun add @rspack/core @rspack/cli -D
+```
+
+Note: These packages are already listed as optional peer dependencies in Shakapacker, so you may see warnings if they're not installed.
+
+## Configuration
+
+To enable Rspack, update your `config/shakapacker.yml`:
+
+```yaml
+default: &default
+  # ... other config options
+  assets_bundler: 'rspack'  # Change from 'webpack' to 'rspack'
+```
+
+### Configuration Files
+
+Rspack uses its own configuration directory to keep things organized. Create your Rspack configuration file at `config/rspack/rspack.config.js`:
+
+```javascript
+const { generateRspackConfig } = require('shakapacker/rspack')
+
+module.exports = generateRspackConfig()
+```
+
+### Custom Configuration
+
+If you need to customize your Rspack configuration:
+
+```javascript
+const { generateRspackConfig } = require('shakapacker/rspack')
+
+const rspackConfig = generateRspackConfig({
+  plugins: [
+    new SomeRspackCompatiblePlugin()
+  ],
+  resolve: {
+    extensions: ['.ts', '.tsx', '.js', '.jsx']
+  }
+})
+
+module.exports = rspackConfig
+```
+
+### Migration from Webpack Config
+
+If you have an existing `config/webpack/webpack.config.js`, you can migrate it to `config/rspack/rspack.config.js`:
+
+**Old (webpack.config.js):**
+```javascript
+const { generateWebpackConfig } = require('shakapacker')
+module.exports = generateWebpackConfig()
+```
+
+**New (rspack.config.js):**
+```javascript
+const { generateRspackConfig } = require('shakapacker/rspack')
+module.exports = generateRspackConfig()
+```
+
+> **Note:** Shakapacker will show a deprecation warning if you use `config/webpack/webpack.config.js` with `assets_bundler: 'rspack'`. Please migrate to `config/rspack/rspack.config.js`.
+
+## Key Differences from Webpack
+
+### Built-in Loaders
+
+Rspack has built-in loaders that are faster than their webpack counterparts:
+
+- **JavaScript/TypeScript**: Uses `builtin:swc-loader` instead of `babel-loader`
+- **CSS Extraction**: Uses `rspack.CssExtractRspackPlugin` instead of `mini-css-extract-plugin`
+- **Asset Handling**: Uses built-in asset modules instead of `file-loader`/`url-loader`
+
+### Plugin Compatibility
+
+Most webpack plugins work with Rspack, but some have Rspack-specific alternatives:
+
+| Webpack Plugin | Rspack Alternative | Status |
+|---|---|---|
+| `mini-css-extract-plugin` | `rspack.CssExtractRspackPlugin` | Built-in |
+| `copy-webpack-plugin` | `rspack.CopyRspackPlugin` | Built-in |
+| `terser-webpack-plugin` | `rspack.SwcJsMinimizerRspackPlugin` | Built-in |
+
+### Minification
+
+Rspack uses SWC for minification by default, which is significantly faster than Terser:
+
+```javascript
+optimization: {
+  minimize: true,
+  minimizer: [
+    new rspack.SwcJsMinimizerRspackPlugin(),
+    new rspack.SwcCssMinimizerRspackPlugin()
+  ]
+}
+```
+
+## Limitations
+
+- **CoffeeScript**: Not supported with Rspack
+- **Some Webpack Plugins**: May not be compatible; check Rspack documentation
+
+## Commands
+
+All existing Shakapacker commands work the same way and automatically use Rspack when configured:
+
+```bash
+# Build (automatically uses rspack when assets_bundler: 'rspack')
+./bin/shakapacker
+
+# Development server (automatically uses rspack when assets_bundler: 'rspack')
+./bin/shakapacker-dev-server
+
+# Watch mode
+./bin/shakapacker --watch
+```
+
+The same dev server configuration in `shakapacker.yml` applies to both webpack and rspack.
+
+## Performance Benefits
+
+Rspack typically provides:
+
+- **2-10x faster** cold builds
+- **5-20x faster** incremental builds  
+- **Faster HMR** (Hot Module Replacement)
+- **Lower memory usage**
+
+## Migration Checklist
+
+1. **Install Rspack dependencies:**
+   ```bash
+   npm install @rspack/core @rspack/cli -D
+   ```
+
+2. **Update configuration:**
+   ```yaml
+   # config/shakapacker.yml
+   default: &default
+     assets_bundler: 'rspack'
+   ```
+
+3. **Create Rspack config:**
+   ```javascript
+   // config/rspack/rspack.config.js
+   const { generateRspackConfig } = require('shakapacker/rspack')
+   module.exports = generateRspackConfig()
+   ```
+
+4. **Remove CoffeeScript files** (if any) - not supported by Rspack
+
+5. **Test your application** - same commands work automatically
+
+## Troubleshooting
+
+### Configuration Issues
+
+If you encounter configuration issues:
+
+1. Check that all plugins are Rspack-compatible
+2. Verify custom loaders work with Rspack
+3. Review the [Rspack migration guide](https://rspack.rs/guide/migration/webpack)
+
+### Performance Issues
+
+If builds are unexpectedly slow:
+
+1. Ensure you're using built-in Rspack loaders
+2. Check for webpack-specific plugins that should be replaced
+3. Review your asset optimization settings
+
+## Further Reading
+
+- [Rspack Official Documentation](https://rspack.rs)
+- [Rspack Migration Guide](https://rspack.rs/guide/migration/webpack)
+- [Rspack Plugins](https://rspack.rs/plugins/webpack/)