---
sidebar_position: 1
---

# Using Rspack

import Rspack from '@site-docs-en/components/rspackTip.mdx';

<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 new project has enabled Rspack by default. Just execute [Initialize Project](/guides/get-started/quick-start.html#initialize) to create an Rspack project:

import InitRspackApp from '@site-docs-en/components/init-rspack-app';

<InitRspackApp />

After the project is created, you can experience the project by running `pnpm run dev`. For more project information, please refer to [Quick Start](/guides/get-started/quick-start.html).

## Enable Rspack build

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

```diff title=modern.config.ts
import { appTools, defineConfig } from '@modern-js/app-tools';

export default defineConfig({
  plugins: [
    appTools({
+     bundler: 'rspack',
    }),
  ],
});
```

:::tip
If your current version is lower than MAJOR_VERSION.59.0, you can upgrade by executing `npx modern upgrade`.
:::

import RspackPrecautions from '@site-docs-en/components/rspackPrecautions.mdx';

<RspackPrecautions />

## Migrating configuration

In Modern.js, the [tools.webpack](/configure/app/tools/webpack) and [tools.webpackChain](/configure/app/tools/webpack-chain) configurations only take effect in webpack mode, after turning on the Rspack build, you can modify it to [tools.rspack](/configure/app/tools/rspack) and [tools.bundlerChain](/configure/app/tools/bundler-chain).

```diff
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](https://rspack.dev/guide/features/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](/configure/app/source/transform-import).

If you have custom configuration requirements for `builtin:swc-loader`, you can set the options of builtin:swc-loader through [tools.swc](/configure/app/tools/swc):

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

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

:::tip
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](/configure/app/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](https://rsbuild.dev/guide/debug/debug-mode) is turned on:

![rspack_version_log](https://lf3-static.bytednsdoc.com/obj/eden-cn/6221eh7uhbfvhn/modern/20240110-155444.png)

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

```json title=package.json
{
  "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:

```json title=package.json
{
  "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/*"]
    }
  }
}
```

Rspack provides [install-rspack](https://github.com/rspack-contrib/install-rspack) tooling to quickly override versions:

```sh
npx install-rspack --version nightly # nightly npm tag
npx install-rspack --version 0.7.5-canary-d614005-20240625082730 # A specific canary version
```

:::tip 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](/guides/get-started/upgrade.html#lock-nested-dependency).
