使用 Rspack#

Modern.js 提供开箱即用的 Rspack 支持，你可以在成熟的 Webpack 和更快的 Rspack 之间进行切换。

这篇文档会向你介绍如何在 Modern.js 中开启 Rspack 构建模式。

初始化 Rspack 项目#

Modern.js 生成器会提供一个可交互的问答界面，只需将构建工具选择为 Rspack，即可创建一个 Rspack 项目:

$ npx @modern-js/create@latest myapp
? 请选择你想创建的工程类型：Web 应用
? 请选择开发语言：TS
? 请选择包管理工具：pnpm
? 请选择构建工具：Rspack

项目创建完成后，在项目中执行 pnpm run dev 即可体验项目，更多信息可参考快速上手。

开启 Rspack 构建#

从 Modern.js 2.46.0 版本起，在一个已有的 Modern.js 项目中，你仅需在 modern.config.ts 中添加以下配置，即可启用 Rspack 构建：

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

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

注意事项#

在使用 Rspack 之前，请留意 Rspack 当前还处于快速迭代阶段。因此，你需要预先了解以下事项：

• Rspack 的 API 和配置项尚未完全稳定，因此在后续的非 major 版本中，可能会引入个别不兼容更新。
• Rspack 目前基于 SWC 进行代码编译和压缩，由于 SWC 的成熟度不及 babel 和 terser，因此你可能会遇到 SWC 在边界场景下的 bug。
• Rspack 模式兼容了大部分 webpack 生态的插件和 loaders，但仍有少部分插件和 loaders 暂时无法使用。

Rspack 正在积极改善上述问题，并计划在未来的版本中逐步解决它们。在决定是否使用 Rspack 之前，我们建议你评估项目需求和风险承受能力。如果你的项目对稳定性和性能要求较高，可以先选择更成熟的 webpack。如果你愿意尝试新的开发体验并为其发展做出贡献，我们欢迎你使用 Rspack，并提供反馈和报告问题，以帮助改进它的稳定性和功能。

配置迁移#

Modern.js 中 tools.webpack 和 tools.webpackChain 配置仅在 webpack 模式下生效，开启 Rspack 构建能力后，可根据实际使用场景决定是否修改为 tools.rspack 或 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');
      }
    },
  },
};

修改转译配置#

Modern.js 在 Rspack 模式下使用 Rspack builtin:swc-loader 进行代码转译。

Modern.js 已对 builtin:swc-loader 的常见配置提供了更方便的配置方式，如：通过 source.transformImport 配置组件库按需引入。如果对 builtin:swc-loader 有自定义配置的需求，可通过 tools.swc 进行配置：

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

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

Rspack 和 Modern.js 的版本关系#

通常情况下，Modern.js 内会集成 Rspack 的最新版本，通过 npx modern upgrade 即可将当前项目中的 Modern.js 相关依赖以及内置的 Rspack 更新至最新版本。

但 Modern.js 对于 Rspack 的依赖方式为锁版本方式(非自动升级)，由于发版周期不同步等原因，可能会出现 Modern.js 内集成的 Rspack 版本落后于 Rspack 最新版本的情况。

当你执行 dev / build 命令时，Modern.js 会在开启调试模式时自动打印当前使用的 Rspack 版本：

修改内置 Rspack 版本#

可以使用 pnpm / yarn / npm 等包管理工具自带的依赖升级功能来将 Rspack 强制升级到指定版本。

以 pnpm 为例，可通过 overrides 修改内置的 Rspack 版本。假设需要指定 Rspack 的版本为 0.7.5:

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

如果需要使用 Rspack 的 nightly/canary 版本，Rspack 的 nightly/canary 版本的包名会在增加 -canary 后缀之后发布，需要修改为:

{
  "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@nightly"
    },
    "peerDependencyRules": {
      "allowAny": [
        "@rspack/*"
      ]
    }
  }
}

Rspack 提供了 install-rspack 工具来快速修改 Rspack 版本:

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

如果想了解其他包管理工具锁定依赖版本的示例，可以参考：锁定子依赖。