docuseal/vendor/bundle/ruby/4.0.0/gems/shakapacker-9.7.0/docs/rspack.md

Rspack Integration

Shakapacker supports Rspack 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

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 for full details.

Installation

Install the required Rspack dependencies:

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:

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:

const { generateRspackConfig } = require("shakapacker/rspack")

module.exports = generateRspackConfig()

Custom Configuration

If you need to customize your Rspack configuration:

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):

const { generateWebpackConfig } = require("shakapacker")
module.exports = generateWebpackConfig()

New (rspack.config.js):

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:

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:

# 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:

   npm install @rspack/core @rspack/cli -D
   

2. Update configuration:

   # config/shakapacker.yml
   default: &default
     assets_bundler: "rspack"
   

3. Create Rspack config:

   // 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

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
• Rspack Migration Guide
• Rspack Plugins