Using Rspack#

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.

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: [
    appTools({
+     bundler: 'experimental-rspack',
    }),
  ],
});

Precautions#

Before using Rspack, please be aware that Rspack is still an early stage project and is currently in a rapid iteration phase. Therefore, you need to be aware of the following:

• The API and configuration options of Rspack are still unstable, and the support for Rspack in Modern.js is experimental. Therefore, incompatible updates may be introduced in non-major releases in the future.
• Rspack does not currently provide complete optimization capabilities like tree shaking, bundle splitting, and scope hoisting, which are available in webpack. We will continue to enhance these optimization capabilities in Rspack from June to December. Therefore, when migrating to Rspack, you may notice a certain level of increase in the bundle size compared to webpack.
• Rspack currently relies on SWC for code compilation and compression. Due to the lower maturity of SWC compared to Babel and Terser, you may encounter SWC bugs.
• 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 improve the above issues and plans to address them in future releases. We recommend that you evaluate your project requirements and risk tolerance before deciding whether to use Rspack. If your project requires high stability and performance, you should choose the more mature webpack. If you are willing to try new tools and contribute to their development, we welcome 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') {
        chain.devtool('cheap-module-eval-source-map');
      }
    },
  },
};

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,
      },
    },
  },
});

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 update the Rspack version with overrides as shown below:

{
  "pnpm": {
    "overrides": {
      "@rspack/core": "nightly",
      "@rspack/plugin-react-refresh": "nightly",
    }
  }
}

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