Using Rspack#

This document will show you how to enable Rspack build mode in the Builder.

Enable Rspack#

Enable in Modern.js framework#

Modern.js framework uses webpack as the default bundler. If you want to use Rspack as the bundler, you can refer to: Using Rspack.

Use Builder in a front-end framework#

Integrating rspack-provider into a frontend framework is similar to integrating webpack-provider. You only need to change the dependency from @modern-js/builder-webpack-provider to @modern-js/builder-rspack-provider.

import { createBuilder } from '@modern-js/builder';
import { builderRspackProvider } from '@modern-js/builder-rspack-provider';

const provider = builderRspackProvider({
  builderConfig: {
    // some configs
  },
});

{
  "devDependencies": {
-    "@modern-js/builder-webpack-provider": "2.8.0",
+    "@modern-js/builder-rspack-provider": "2.8.0"
  }
}

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 from webpack to Rspack#

Builder aims to eliminate the main differences between different bundlers and help users migrate at a lower cost. However, due to the different capabilities of each bundler, you still need to be aware of some differences.

This article will introduce the differences between webpack and Rspack from the perspective of Builder. If you need to know more in-depth differences, please refer to the Rspack documentation.

1. Builder configuration differences#

Currently, most of configuration options in Builder have been adapted for Rspack, but there are still some configurations that are in the process of being supported.

Source Config#

Source code parsing and compilation related configurations in Builder.

Unsupported configurations and capabilities include:

• source.include (track issue)
• source.exclude (track issue)
• source.moduleScopes (track issue)

Html Config#

HTML related configurations in Builder.

All configurations and capabilities under html are available within rspack.

Security Config#

Security related configurations in Builder.

Unsupported configurations and capabilities include:

• security.sri (track issue)

Dev Config#

Dev related configurations in Builder.

All configurations and capabilities under dev are available within rspack.

Output Config#

Output related configurations in Builder.

Unsupported configurations and capabilities include:

• output.enableInlineScripts
• output.polyfill.usage (track issue)

Experiments Config#

Experimental related configurations in the Builder

Unsupported configurations and capabilities include:

• experiments.lazyCompilation

Performance Config#

Performance related configurations in Builder.

Unsupported configurations and capabilities include:

• performance.buildCache
• performance.chunkSplit (split-by-module)

Tools Config#

Low-level tools configurations in Builder.

Unsupported configurations and capabilities include:

• tools.terser
• tools.cssExtract
• tools.cssLoader (Only supported when disableCssExtract is true)
• tools.styledComponents
• tools.tsLoader
• tools.webpack：use tools.rspack instead.
• tools.webpackChain：use tools.bundlerChain instead.

2. Migrating from webpackChain to bundlerChain#

Builder supports modifying Rspack config via bundlerChain. configurations modified via bundlerChain will take effect on both webpack and Rspack builds.

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

CHAIN_ID differences#

Because of some implementation differences between webpack and Rspack, there are some differences in the rules configuration.

You can see all the rules that are supported in both Rspack & webpack via tools.bundlerChain#CHAIN_ID.

3. Migrating from tools.webpack to tools.rspack#

BundlerChain only supports modifying the Rspack & webpack intersection config, more Rspack-exclusive features need to be modified via tools.rspack.

Before modify the Rspack configuration object, you may should know the config diff between Rspack and Webapck.

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

More information about Rspack, please refer to the Rspack website.

4. Babel Configuration Migration#

By default, Rspack uses SWC for transpilation and compression. Therefore, when using Rspack as the bundler, babel-loader is not loaded by default.

For most common Babel plugins, you can find corresponding alternatives in Rspack, and there are also corresponding compatible configuration options in Builder.

5. SWC Configuration Support#

Rspack has built-in support for some swc configurations, such as builtins.react, which can be referred to in Builtins.

Adding swc plugins and more custom configurations is not currently supported in Rspack. Relevant requirements can be tracked through the corresponding issue.

6. Webpack Plugin Migration#

Currently, only a limited number of webpack plugins are compatible with Rspack.

If you are using the following plugins (or indirect dependencies) in your project, you will need to temporarily remove them or use alternative solutions, otherwise you won't be able to switch to the Rspack build:

• webpack-retry-chunk-load-plugin：use output.assetsRetry instead.
• webpack.ProviderPlugin：use builtins.provide instead.
• webpack.DefinePlugin：use builtins.define instead.
• webpack.ContextReplacementPlugin
• ...

Detailed plugin support can be found at: Plugin compatibility.

The plugins not listed can be judged according to Rspack Plugin API.

7. CSS Modules Configuration Migration#

Rspack mode does not support modifying CSS Modules configuration through tools.cssLoader, however, Builder provides output.cssModules configuration, it used to smooth Rspack mode and webpack mode difference.

export default {
+  output: {
+    cssModules: {
+      auto: resource => {
+        return resource.includes('.module.') || resource.includes('shared/');
+      },
+    },
+  },
-  tools: {
-    cssLoader: {
-      modules: {
-        auto: path => {
-          return resource.includes('.module.') || resource.includes('shared/');
-        },
-      },
-    },
-  }
};

Build performance profile#

Builder supports the use of the RSPACK_PROFILE environment variable for build performance profile.

$ RSPACK_PROFILE=ALL pnpm build

This command will generate a rspack-profile-${timestamp} folder in the dist folder, and it will contain logging.json, trace.json and jscpuprofile.json files.

• trace.json: The time spent on each phase of the Rust side is recorded at a granular level using tracing and can be viewed using ui.perfetto.dev
• jscpuprofile.json: The time spent at each stage on the JavaScript side is recorded at a granular level using Node.js inspector and can be viewed using speedscope.app
• logging.json: Includes some logging information that keeps a coarse-grained record of how long each phase of the build took

Compare with Rspack CLI#

Builder Rspack build mode comparison Rspack CLI adds a lot of out-of-the-box capabilities. At the same time, these capabilities will bring a certain degree of performance overhead and behavioral differences:

All of the above capabilities provide configurable options that can be adjusted as needed based on the actual situation of the project.

For more built-in capabilities, please refer to Feature Navigation.

FAQ#

After enabling Rspack, the performance is not as fast as expected?#

Usually, after enabling Rspack, there will be a 5 to 10 times improvement in compilation performance compared to Webpack.

The following behaviors are currently known to slow down Rspack build performance to some extent:

Using configuration options or plugins that rely on Babel#

When using Rspack to build, babel-loader is not enabled by default.

However, when a project uses configuration options or plugins implemented with Babel, an additional babel-loader will be added for file transpilation:

• Add the Babel plugin via tools.babel
• Use Modern.js SSR feature
• ...

You can check whether the Babel plugin exists in the final generated Rspack configuration by using debug mode.

Enable TypeScript type checking#

By default, Builder enables TypeScript type checking during build. In large projects, type checking can take much longer than the actual build time of Rspack, so this behavior can slow down the build speed to some extent during production environment builds.

In this case, you can disable type checking using output.disableTsChecker to see if Rspack performance meets your expectations after excluding type checking.

Large number of Less files#

Currently, Less files are processed using the less-loader based on JavaScript and no Rust version is provided. Therefore, processing a large number of Less files can slow down the build performance.

Large number of SVG files#

By default, builder supports using SVG resources as React components, which incurs some performance overhead.

If you don't need this feature, you can set output.disableSvgr to true to disable this behavior to improve build performance.

Not import component library on demand#

By default, when using Ant Design or Arco Design component library, Builder will automatically enable the on-demand import function, and the default configuration can refer to source.transformImport.

When using other component libraries, if the component library supports on-demand import, we recommend to configure on-demand import through source.transformImport first.