shakapacker 8.4.0 → 9.7.0

data/docs/rspack.md

@@ -0,0 +1,218 @@
+# 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.
+
+**📖 For configuration options, see the [Configuration Guide](./configuration.md)**
+
+## Version Compatibility
+
+Shakapacker supports both Rspack v1 (`^1.0.0`) and Rspack v2 (`^2.0.0-0`). No configuration changes are needed when upgrading between rspack versions — shakapacker's generated config works with both.
+
+**Rspack v2 note:** Rspack v2 ships as a pure ESM package and requires **Node.js 20.19.0+**.
+
+**Rspack v1 note:** Rspack v1 itself supports older Node versions, but Shakapacker requires Node 20+.
+
+**React refresh plugin note:** `@rspack/plugin-react-refresh` currently remains on the v1 line in Shakapacker peer deps.
+
+**Current CI coverage note:** Shakapacker currently validates rspack v2 using `2.0.0-beta.6`. The rspack v2 dev dependencies are intentionally pinned while v2 is in beta and should be revisited when stable `2.0.0` is released.
+
+### Why upgrade to Rspack v2?
+
+- **Persistent cache with proper invalidation** — Rspack v2 promotes persistent caching (`cache.type: 'filesystem'`) from experimental to stable, with portable cache support (`cache.portable`) and read-only cache for CI (`cache.readonly`). This means fast rebuilds that survive process restarts and are properly invalidated when dependencies change.
+- **Incremental compilation (stable)** — The `incremental` option moves from `experiments` to a top-level config, signaling it's production-ready. Incremental builds skip unchanged work in the dependency graph.
+- **Better tree shaking** — CJS `require()` destructuring and variable property access are now tree-shaken, and Module Federation shares can be tree-shaken.
+- **Unified target configuration** — A single `target` setting now propagates defaults to SWC and LightningCSS automatically, eliminating redundant per-loader configuration.
+- **Stricter export validation** — `exportsPresence` defaults to `'error'`, catching missing or misspelled exports at build time instead of silently producing broken bundles.
+- **React Server Components** — Built-in RSC support for frameworks.
+- **Performance** — Dozens of Rust-level optimizations across every beta release (hash caching, regex fast paths, reduced allocations, rayon parallelism).
+
+See the [Rspack v2 breaking changes discussion](https://github.com/web-infra-dev/rspack/discussions/9270) for full details.
+
+## Installation
+
+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/)