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.

Fresh installs default to the latest supported Rspack range from lib/install/package.json, which is currently the Rspack v2 prerelease line (^2.0.0-0).

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

Current CI coverage note: Shakapacker currently validates rspack v2 using 2.0.0-rc.0. The rspack v2 dev dependencies are intentionally pinned while v2 is pre-release 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

Recommended (Shakapacker 10.1+): shakapacker-rspack

shakapacker-rspack bundles shakapacker, @rspack/core, @rspack/cli, and rspack-manifest-plugin as direct dependencies, so a single install pulls in the full managed Rspack stack:

npm install shakapacker-rspack -D
# or
yarn add shakapacker-rspack -D
# or
pnpm add shakapacker-rspack -D
# or
bun add shakapacker-rspack -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 (Shakapacker 10.0 and earlier, or self-managed versions)

If you're on Shakapacker 10.0 or prefer to manage @rspack/core, @rspack/cli, and rspack-manifest-plugin versions yourself, install them directly:

npm install @rspack/core @rspack/cli rspack-manifest-plugin -D
# or
yarn add @rspack/core @rspack/cli rspack-manifest-plugin -D
# or
pnpm add @rspack/core @rspack/cli rspack-manifest-plugin -D
# or
bun add @rspack/core @rspack/cli 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.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:

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