使用 Rspack

什么是 Rspack

Rspack 是一个基于 Rust 的高性能 Web 构建工具,具备与 webpack 生态系统的互操作性,可以被 webpack 项目低成本集成,并提供更好的构建性能。

相较于 webpack,Rspack 的构建性能有明显提升,除了 Rust 带来的语言优势,这也来自于它的并行架构和增量编译等特性。经过 benchmark 验证,Rspack 可以带来 5 ~ 10 倍编译性能的提升。

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 即可体验项目,更多信息可参考快速上手

TIP

在使用 Rspack 作为打包工具时,由于部分能力尚在开发中,以下 features 暂时无法使用,我们将在未来提供支持:

开启 Rspack 构建

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

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

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

如果你当前版本低于 2.46.0, 可通过执行 npx modern upgrade 进行升级。

注意事项

在使用 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,并提供反馈和报告问题,以帮助改进它的稳定性和功能。

配置迁移

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

开启 Rspack 构建能力后,目前有小部分配置在 Rspack 中还不支持使用,如 source.moduleScopessecurity.sri 等。

对于不支持的配置,我们在文档中有标注 打包工具: 仅支持 webpack打包工具: 仅支持 rspack,可参考具体配置介绍。

修改转译配置

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

Modern.js 已对 builtin:swc-loader 的常见配置提供了更方便的配置方式,如:通过 source.transformImport 配置组件库按需引入。如果对 builtin:swc-loader 有自定义配置的需求,可参考以下代码:

export default {
  tools: {
    bundlerChain: (chain, { CHAIN_ID }) => {
      chain.module
        .rule(CHAIN_ID.RULE.JS)
        .use(CHAIN_ID.USE.SWC)
        .tap(options => {
          options.xxx = '';
          return options;
        });
    },
  }
};
TIP

在启用 Rspack 构建时,babel-loader 默认不会被启用。如需添加 babel 插件,可通过 tools.babel 配置,此时会产生额外的编译开销,在一定程度上拖慢 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_version_log

修改内置 Rspack 版本

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

以 pnpm 为例,可通过 overrides 以下依赖更新 Rspack 版本:

package.json
{
  "pnpm": {
    "overrides": {
      "@rspack/core": "nightly",
      "@rspack/plugin-react-refresh": "nightly",
    }
  }
}
Nightly 版本介绍

每天,Rspack 会自动构建基于最新代码的 nightly 版本,用于测试和及早发现错误。

通常情况下,这些版本是可用的。如果发现问题,我们会及时进行修复。但是,如果 Rspack 有一些 break change,需要 Modern.js 同步修改代码,那么我们建议等待下一个 Modern.js 版本再进行更新。

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