# Using Rspack

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

import Rspack from '@en/shared/rspack-tip.mdx';

<Rspack />

## 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](https://modernjs.dev/en/guides/advanced-features/rspack-start.html#initializing-an-rspack-project).

### 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`.

```ts title=modern.config.ts
import { createBuilder } from '@modern-js/builder';
import { builderRspackProvider } from '@modern-js/builder-rspack-provider';

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

```diff title=package.json
{
  "devDependencies": {
-    "@modern-js/builder-webpack-provider": "2.8.0",
+    "@modern-js/builder-rspack-provider": "2.8.0"
  }
}
```

## 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](http://rspack.dev/guide/migrate-from-webpack.html).

### 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](/api/config-source.html#sourceinclude) ([track issue](https://github.com/web-infra-dev/rspack/issues/3067))
- [source.exclude](/api/config-source.html#sourceexclude) ([track issue](https://github.com/web-infra-dev/rspack/issues/3067))
- [source.moduleScopes](/api/config-source.html#sourcemodulescopes)

#### 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:

- [source.sri](/api/config-security.html#securitysri) ([track issue](https://github.com/web-infra-dev/rspack/issues/2669))

#### 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.disableCssExtract](/api/config-output.html#outputdisablecssextract)
- [output.disableSourcemap.css](/api/config-output.html#outputdisablesourcemap)
- [output.enableCssModuleTSDeclaration](/api/config-output.html#outputenablecssmoduletsdeclaration)
- [output.enableInlineScripts](/api/config-output.html#outputenableinlinescripts)
- [output.legalComments.inline](/api/config-output.html#outputlegalcomments)
- [output.polyfill.usage](/api/config-output.html#usage) ([track issue](https://github.com/web-infra-dev/rspack/issues/3067))

#### Experiments Config

> Experimental related configurations in the Builder

Unsupported configurations and capabilities include:

- [experiments.lazyCompilation](/api/config-experiments.html#experimentslazycompilation)

#### Performance Config

> Performance related configurations in Builder.

Unsupported configurations and capabilities include:

- [performance.profile](/api/config-performance.html#performanceprofile)
- [performance.removeMomentLocale](/api/config-performance.html#performanceremovemomentlocale)
- [performance.buildCache](/api/config-performance.html#performancebuildcache)
- [performance.chunkSplit (split-by-module)](/api/config-performance.html#performancechunksplit)

#### Tools Config

> Low-level tools configurations in Builder.

Unsupported configurations and capabilities include:

- [tools.terser](/api/config-tools.html#toolsterser)
- [tools.cssExtract](/api/config-tools.html#toolscssextract)
- [tools.cssLoader](/api/config-tools.html#toolscssloader)
- [tools.devServer.devMiddleware](/api/config-tools.html#devmiddleware) ([track issue](https://github.com/web-infra-dev/rspack/issues/2391))
- [tools.inspector](/api/config-tools.html#toolsinspector)
- [tools.minifyCss](/api/config-tools.html#toolsminifycss)
- [tools.styleLoader](/api/config-tools.html#toolsstyleloader)
- [tools.styledComponents](/api/config-tools.html#toolsstyledcomponents)
- [tools.tsLoader](/api/config-tools.html#toolstsloader)
- [tools.webpack](/api/config-tools.html#toolswebpack)：use [tools.rspack](/api/config-tools#toolsrspack) instead.
- [tools.webpackChain](/api/config-tools.html#toolswebpackchain)：use [tools.bundlerChain](/api/config-tools#toolsbundlerchain) instead.

:::tip
In addition to the above configurations, some of the supported configurations may have differences in their capabilities. For specific differences in configurations, please refer to the corresponding API for each configuration.
:::

### 2. Migrating from webpackChain to bundlerChain

Builder supports modifying Rspack config via [bundlerChain](/api/config-tools.html#toolsbundlerchain). configurations modified via bundlerChain will take effect on both webpack and Rspack builds.

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

:::tip
The bundlerChain only provides consistent api modification for Rspack & webpack configurations, the actual plugin / loader availability depends on the actual Rspack / webpack support.
:::

#### 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](/api/config-tools.html#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](/api/config-tools.html#toolsrspack).

Before modify the Rspack configuration object, you may should know [the config diff between Rspack and Webapck](https://www.rspack.dev/guide/config-diff.html).

```diff
export default {
  tools: {
-   webppack: (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](https://www.rspack.dev/).

### 4. Babel Configuration Migration

By default, Rspack uses SWC for transpilation and compression. Therefore, when using Rspack for building, 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.

| Babel Plugin                                    | Rspack Configuration                                                                      | Builder Configuration                                                                                                        |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| @babel/preset-env                               | [builtins.presetEnv](https://www.rspack.dev/config/builtins.html#builtinspresetenv)       | [Browserslist](/guide/advanced/browserslist.html)、<br />[Browser Compatibility](/guide/advanced/browser-compatibility.html) |
| @babel/preset-react                             | [builtins.react](https://www.rspack.dev/config/builtins.html#builtinsreact)               | [Hot Module Replacement](/guide/advanced/hmr.html)                                                                           |
| @emotion/babel-plugin                           | [builtins.emotion](https://www.rspack.dev/config/builtins.html#builtinsemotion)           | Not supported                                                                                                                         |
| babel-plugin-import                             | [builtins.pluginImport](https://www.rspack.dev/config/builtins.html#builtinspluginimport) | [source.transformImport](/api/config-source.html#sourcetransformimport)                                                      |
| babel-plugin-lodash                             | Not supported                                                                                      | Not supported                                                                                                                         |
| babel-plugin-styled-components                  | Not supported                                                                                      | Not supported                                                                                                                         |
| @babel/plugin-react-transform-remove-prop-types | Not supported                                                                                      | Not supported                                                                                                                         |

:::Tip
When using Rspack for building, you can still configure Babel plugins through [tools.babel](/api/config-tools.html#toolsbabel), but this will result in additional compilation overhead, which may slow down the Rspack build to some extent.
:::

### 5. SWC Configuration Support

Rspack has built-in support for some swc configurations, such as builtins.react, which can be referred to in [Builtins](https://www.rspack.dev/config/builtins.html).

Adding swc plugins and more custom configurations is not currently supported in Rspack. Relevant requirements can be tracked through the corresponding [issue](https://github.com/web-infra-dev/rspack/issues/3067).

### 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](/api/config-output.html#outputassetsretry) instead.
- webpack.ProviderPlugin：use [builtins.provide](https://www.rspack.dev/config/builtins.html#builtinsprovide) instead.
- webpack.DefinePlugin：use [builtins.define](https://www.rspack.dev/config/builtins.html#builtinsdefine) instead.
- webpack.ContextReplacementPlugin
- ...

Detailed plugin support can be found at: [Plugin compatibility](https://www.rspack.dev/guide/plugin-compat.html).

The plugins not listed can be judged according to [Rspack Plugin API](https://www.rspack.dev/api/plugin-api.html).

## 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](/api/config-tools.html#toolsbabel)
- Use [Modern.js SSR feature](https://modernjs.dev/en/guides/advanced-features/ssr.html)
- ...

You can check whether the babel plugin exists in the final generated Rspack configuration by using [debug mode](/guide/debug/debug-mode.html).

##### 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](/api/config-output.html#outputdisabletschecker) 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](/api/config-output.html#outputdisablesvgr) to true to disable this behavior to improve build performance.
