使用 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 项目中，你可以通过执行 pnpm run new 来启用 Rspack 构建：

$ pnpm run new
? 请选择你想要的操作 启用可选功能
? 请选择功能名称 启用「Rspack 构建」

执行以上命令后，在 modern.config.ts 中添加 Rspack 相关配置即可：

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

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

注意事项#

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

• Rspack 的 API 和配置项还不稳定，同时 Modern.js 对 Rspack 的支持属于实验性的，因此在后续的非 major 版本中，可能会引入不兼容更新。
• Rspack 并未实现完整的 webpack 优化能力（如 tree shaking、bundle splitting、scope hoist 等能力，我们将在 6 ～ 12 月持续补齐相关优化能力），迁移到 Rspack 后，你可能会发现产物的包体积相较 webpack 有一定程度的增加。
• Rspack 目前基于 SWC 进行代码编译和压缩，由于 SWC 的成熟度不及 babel 和 terser，因此你可能会遇到 SWC 的 bug。
• Rspack 模式兼容了大部分 webpack 生态的插件和 loaders，但仍有部分插件和 loaders 暂时无法使用。

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

配置迁移#

开启 Rspack 构建能力后，还需要参考 配置差异 进行进一步的配置迁移。

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 版本:

{
  "pnpm": {
    "overrides": {
      "@rspack/core": "nightly",
      "@rspack/dev-client": "nightly",
      "@rspack/plugin-html": "nightly"
    }
  }
}

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