Using Rspack

Rspack - A High Performance JavaScript Bundler

Rspack is a high performance JavaScript bundler based on Rust, with interoperability with the webpack ecosystem, allowing it to be integrated into webpack projects at a low cost while providing better build performance.

Compared to webpack, Rspack has significantly improved build performance, thanks not only to the language advantages brought by Rust, but also to its parallel architecture and incremental compilation features. Benchmarking has shown that Rspack can provide 5-10 times better compilation performance.

Modern.js provides out-of-the-box Rspack support, so you can switch between the stable Webpack and the faster Rspack.

This document will show you how to enable Rspack build mode in Modern.js.

Initializing an Rspack project

The Modern.js generator provides an interactive question-and-answer interface to initialize a project. To create an Rspack project, simply select the Rspack build tool by running:

$ npx @modern-js/create@latest myapp
? Please select the type of project you want to create: Web App
? Please select the programming language: TS
? Please select the package manager: pnpm
? Please select the bundler: Rspack

After the project is created, you can experience the project by running pnpm run dev. For more project information, please refer to Quick Start.


When using Rspack as the bundler, the following Features are temporarily unavailable as some of the capabilities are still under development and we will provide support in the future.

  • The usage of useLoader in Client Side Rendering

Enable Rspack build

Since Modern.js 2.46.0, you can enable Rspack build by add the following configuration in modern.config.ts:

import { appTools, defineConfig } from '@modern-js/app-tools';

export default defineConfig({
  plugins: [
+     bundler: 'experimental-rspack',

If your current version is lower than 2.46.0, you can upgrade by executing npx modern upgrade.


Before using Rspack, please be aware that Rspack is currently in the rapid iteration phase. Therefore, you need to be aware of the following:

  • The API and configuration items of Rspack are not completely stable yet, so non-major versions may introduce some incompatible changes.
  • Rspack currently relies on SWC for code transformation and compression. Due to the lower maturity of SWC compared to Babel and Terser, you may encounter bugs of SWC in edge cases.
  • Rspack is compatible with most plugins and loaders in the webpack ecosystem, but there are still some plugins and loaders that cannot be used temporarily.

Rspack is actively working to resolve the above issues and plans to address them in future updates. We recommend evaluating your project requirements and risk tolerance before deciding whether to use Rspack. If your project requires high stability and high performance, you should choose the more mature tool, Webpack. If you are willing to try new tools and contribute to their development, we encourage you to use Rspack and provide feedback and bug reports to help improve its stability and functionality.

Migrating configuration

In Modern.js, the tools.webpack and tools.webpackChain configurations only take effect in webpack mode, after turning on the Rspack build, you can modify it to tools.rspack and tools.bundlerChain.

export default {
  tools: {
-   webpack: (config, { env }) => {
+   rspack: (config, { env }) => {
      if (env === 'development') {
        config.devtool = 'cheap-module-eval-source-map';
      return config;
-   webpackChain: (chain, { env }) => {
+   bundlerChain: (chain, { env }) => {
      if (env === 'development') {

After turning on the Rspack build capability, there are currently a small number of configurations that are not supported in Rspack, such as source.moduleScopes, security.sri etc.

For unsupported configurations, we have marked Bundler: only support webpack or Bundler: only support Rspack in the document. Please refer to the specific configuration introduction.

Modify transpile configuration

Modern.js uses Rspack builtin:swc-loader for code translation in Rspack mode.

Modern.js has provided a more convenient configuration for the common configuration of builtin:swc-loader, such as: configuring the component library to import it on demand through source.transformImport.

If you have custom configuration requirements for builtin:swc-loader, you can set the options of builtin:swc-loader through tools.swc:

import { defineConfig } from '@modern-js/app-tools';

export default defineConfig<'rspack'>({
  tools: {
    swc: {
      jsc: {
        externalHelpers: false,

When Rspack build is enabled, babel-loader is not enabled by default. If you need to add some babel plugins, you can configure it through tools.babel. This will generate additional compilation overhead and slow down the Rspack build speed to a certain extent.

The relationship between Rspack and Modern.js versions

Usually, the latest version of Rspack will be integrated into Modern.js. You can update the Modern.js-related dependencies and built-in Rspack to the latest version by using npx modern upgrade in your project.

However, Modern.js uses a locked version dependency method (non-automatic upgrade) for Rspack. Due to differences in release cycles, the version of Rspack integrated into Modern.js may be behind the latest version of Rspack.

When Rspack is enabled for building through dev / build, the current version of Rspack used in the framework will be printed automatically when debugging mode is turned on:


Override the Built-in Rspack Version

You can override Rspack to a specific version using the capbilities provided by package managers such as pnpm, yarn, npm.

For example, if you are using pnpm, you can override the Rspack version with overrides. Assume that the version of Rspack needs to be specified as 0.7.5:

  "pnpm": {
    "overrides": {
      "@rspack/binding": "0.7.5",
      "@rspack/core": "0.7.5",
      "@rspack/plugin-react-refresh": "0.7.5"

If you need to use the nightly/canary version of Rspack, the package name of the nightly/canary version of Rspack will be released after adding the -canary suffix, and needs to be modified to:

  "pnpm": {
    "overrides": {
      "@rspack/binding": "npm:@rspack/binding-canary@nightly",
      "@rspack/core": "npm:@rspack/core-canary@nightly",
      "@rspack/plugin-react-refresh": "npm:@rspack/plugin-react-refresh-canary@nightly"
    "peerDependencyRules": {
      "allowAny": [

Rspack provides install-rspack tooling to quickly override versions:

npx install-rspack --version nightly # nightly npm tag
npx install-rspack --version 0.7.5-canary-d614005-20240625082730 # A specific canary version
What is Rspack Nightly Version

The Rspack nightly build fully replicates the full release build for catching errors early.

Usually it is available and any errors that arise will fixed promptly.

However, if there are any break changes that require modern.js to modify the code, we recommend to wait for the next version of modern.js.

More examples of using package managers, please refer to: Lock nested dependency.