shakapacker 8.4.0 → 9.0.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/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/)

data/docs/rspack_migration_guide.md

@@ -0,0 +1,202 @@
+# 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)$/,
+  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
+
+### 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
+
+## 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)