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 Rspack v2 (^2.0.0) going forward. Rspack v1 is no longer a supported target for new Shakapacker releases.

Fresh installs use the supported Rspack v2 ranges from lib/install/package.json.

Rspack v2 note: Rspack v2 ships as a pure ESM package and requires Node.js 20.19.0+.

Why 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

Recommended (Shakapacker 10.1+): shakapacker-rspack

shakapacker-rspack ships shakapacker as a direct dependency and declares @rspack/core, @rspack/cli, @rspack/dev-server, and rspack-manifest-plugin as required peer dependencies. npm 7+ auto-installs those peers, so npm users can install the managed Rspack stack with one command:

npm install shakapacker-rspack -D

npm <7, Yarn Classic, pnpm, and Yarn PnP users should keep app-imported packages explicit in package.json. The default generated rspack config imports shakapacker/rspack, so list the supplemental package, shakapacker, and the required peers together:

npm install shakapacker-rspack shakapacker @rspack/core @rspack/cli @rspack/dev-server rspack-manifest-plugin -D
# or
yarn add shakapacker-rspack shakapacker @rspack/core @rspack/cli @rspack/dev-server rspack-manifest-plugin -D
# or
pnpm add shakapacker-rspack shakapacker @rspack/core @rspack/cli @rspack/dev-server rspack-manifest-plugin -D

See packages/shakapacker-rspack/README.md for the full install reference and the v10.1 supplemental packages migration guide for swapping an existing rspack install over to the supplemental package.

Manual install (self-managed versions)

If you prefer to manage @rspack/core, @rspack/cli, @rspack/dev-server, and rspack-manifest-plugin versions yourself, install them directly:

npm install @rspack/core @rspack/cli @rspack/dev-server rspack-manifest-plugin -D
# or
yarn add @rspack/core @rspack/cli @rspack/dev-server rspack-manifest-plugin -D
# or
pnpm add @rspack/core @rspack/cli @rspack/dev-server rspack-manifest-plugin -D
# or
bun add @rspack/core @rspack/cli @rspack/dev-server rspack-manifest-plugin -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.LightningCssMinimizerRspackPlugin()
  ]
}

Shakapacker's generated Rspack config preserves the shared optimization defaults from the base config, including optimization.splitChunks.chunks = "all" and optimization.runtimeChunk = "single". In production it also preserves compression plugins and Rspack's SWC/Lightning CSS minimizers.

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.

Lazy Compilation

Rspack v2 uses top-level lazyCompilation; do not rely on experiments.lazyCompilation. For Rails split dev-server topology, Shakapacker sets top-level lazyCompilation: false in the generated Rspack development config when the dev server is running. This avoids Rspack CLI dev-server auto-lazy behavior sending dynamic imports through lazy trigger URLs that Rails does not serve.

If your app has a custom, safe lazy-compilation setup, configure the top-level field explicitly in config/rspack/rspack.config.js:

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

module.exports = generateRspackConfig({
  lazyCompilation: {
    imports: false,
    entries: true
  }
})

Performance Benefits

Rspack typically provides:

• Substantially faster cold builds — Rspack's own benchmark reports roughly 8x faster production builds on a 5,000-component React app (rspack.rs, benchmark sources)
• Substantially faster development startup — roughly 10–15x in the same benchmark
• Substantially faster HMR — roughly 17x in the same benchmark
• Lower memory usage in most reported cases

Actual gains depend on project size, configuration, source maps, cache state, and hardware. See Transpiler Performance Guide for measurement guidance.

Migration Checklist

1. Install Rspack dependencies:

   npm install @rspack/core @rspack/cli @rspack/dev-server rspack-manifest-plugin -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

6. Compare the generated configs - use bin/diff-bundler-config when you are converting custom webpack configuration or need to prove the rspack config kept the same entrypoints, loaders, output paths, and plugin intent.

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