2024 年 4 月 10 日

#Rspack 0.6 发布公告

#主要功能更新

#内置支持 mini-css-extract-plugin

你现在可以使用 rspack.CssExtractRspackPlugin 作为 mini-css-extract-plugin 的替代。

这在一些场景很实用，例如当内置的 CSS 处理不能满足你的需求，有更定制化的 CSS Modules name 等，或者你想要使用一些依赖 css-loader 的 loader，但仍然想要将 CSS 提取成单独文件。

详细配置见 CssExtractRspackPlugin。

import { rspack } from '@rspack/core';

export default {
  plugins: [new rspack.CssExtractRspackPlugin()],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [rspack.CssExtractRspackPlugin.loader, 'css-loader'],
      },
    ],
  },
};

你可以在这里找到一个基础的项目例子。

#默认开启新版 tree shaking

Rspack 在 0.1.0 支持了基本的 tree shaking 功能，由于最初的架构还未稳定, 我们使用了相对简单的方法实现了基础版的 tree shaking（仅支持未使用导出删除），但是随着 Rspack 功能的完善，架构逐渐稳定 基础的 tree shaking 无法满足用户的需求，比如：

1. 无法处理循环引用，无法给其他构建阶段足够的优化信息，实现进一步的优化 (mangleExports, concatenateModules, barrel exports optimization)。
2. 经常出现一些 interop 相关的 badcase，例如: worker-thread 模块，Common Js 模块，module federation 等

为了解决以上问题，我们决定使用类似 webpack 的方案，自底向上重新实现整个优化流程，并在 0.4.2 引入 experiments.rspackFuture.newTreeshaking 配置，来实验性的开启新的优化算法。 经过 4 个月 bug 修复和优化，新的 tree shaking 算法已经相对稳定，因此我们决定在 0.6.0 默认开启新的 tree shaking 算法。

#不兼容更新

#移除 experiments.rspackFuture.disableApplyEntryLazily

experiments.rspackFuture.disableApplyEntryLazily 选项自 v0.5.0 已被默认开启，并在 v0.6.0 中被删除。

#移除 compiler.build 和 compiler.rebuild

compiler.build 与 compiler.rebuild 不属于 webpack 公开 API，目前已经被移除。

#移除 builtins.css 并引入 CSS 相关 module.parser 和 module.generator 选项

移除 builtins.css，请使用引入的 CSS 相关的 module.parser 和 module.generator 选项进行替代。

同时，从 v0.6.0 版本开始，Rspack 的 experiments.css 将会以 webpack 的 experiments.css 为目标进行对齐，这意味着和 webpack experiments.css 一样在未来将不再支持不支持 CSS 变量的浏览器。因此，对于那些需要使用尚未得到 experiments.css 支持的配置，或者需要兼容老版本浏览器的项目，我们推荐迁移至 rspack.CssExtractRspackPlugin。

在 v0.6.0 中，我们引入了三种新的模块类型的 module.generator 和 module.parser 选项：css/auto、css 和 css/module，这些选项只有在启用 experiments.css 时才会生效，关于如何使用可查看这个例子。

在 module.parser 选项中，css、css/auto 和 css/module 模块类型都包含了 namedExports 属性。它取代了 builtins.css.namedExports 配置。

对于 module.generator 选项，css/auto 和 css/module 模块类型提供了 exportsOnly、exportsConvention 和 localIdentName 属性。css 类型只包含 exportsOnly 和 exportsConvention 属性。exportsOnly、exportsConvention 和 localIdentName 分别取代了 builtins.css.modules.exportsOnly、builtins.css.modules.localsConvention 和 builtins.css.modules.localIdentName。

除此之外，还包括一些关于默认值的修改：

1. exportsConvention 的值从 'asIs', 'camelCaseOnly' 等变更为 'as-is', 'camel-case-only' 等，以保持与 webpack experiments.css 的一致。

2. namedExports: false 支持同时使用默认导出（default export）、命名导出（named export）和命名空间导出（namespace export），在此之前它只支持使用默认导出：

   // v0.6.0 之前只支持使用默认导出
   import classes from './index.module.css';
   
   // 现在除默认导出之外，也支持：
   // 命名空间导出
   import * as classes from './index.module.css';
   // 命名导出
   import { class1, class2 } from './index.module.css';
   // 默认导出和命名导出同时使用
   import classes, { class1, class2 } from './index.module.css';

3. namedExports 的默认值从 false 变更为 true，这意味着你需要默认使用命名空间导入（例如 import * as classes from './style.css'）或命名导入（例如 import { class1 } from './style.css'），这将提高与未来原生 CSS 模块的兼容性。而这并不意味着你需要一次性迁移所有的导入，你可以通过设置 namedExports: false 来禁用此行为，并且由于现在 namedExports: false 也支持命名导出和命名空间导出，因此你可以逐步迁移这些导入。

4. localIdentName 的默认值在从在开发模式下 '[path][name][ext]__[local]' 和在生产模式下 '[hash]' 变更为在开发和生产模式下都是 '[uniqueName]-[id]-[local]'，这将略微改善 CSS 产物的 gzip 压缩大小。

5. exportsOnly 的默认值在 target: 'node' 下由原来的 false 变更为 true。

6. CSS 默认规则的模块类型从 css 变更为 css/auto，css/auto 将自动解析以 .module. 或 .modules. 为中缀的 CSS 文件作为 CSS Modules 处理，这与 css-loader 的 modules.auto: true 行为一致，这将简化使用 less 或 sass 与 CSS Modules 的规则书写。

#升级 SWC 到 0.90.x

升级 Rust crate swc_core 到 0.90.x，这会对使用 SWC Wasm 插件的用户产生影响。

#当 CSS 的顺序在多个 chunk 中不一致时发出警告

当多个 chunk 中 CSS 顺序不一致时会发出警告，假如你有两个 entry，entryA 和 entryB，entryA 中引入 a.css 然后引入 b.css，而 entryB 中引入 b.css 然后引入 a.css。 当满足 splitChunks 条件时，a.css 和 b.css 会成为单独 chunk，这个 chunk 中 a.css 和 b.css 的顺序无法保证，会产生如下的警告

WARNING in ⚠ chunk src_a_css-src_b_-5c8c53 [css-extract-rspack-plugin]
  │ Conflicting order. Following module has been added:
  │  * css ./css-loader/dist/cjs.js??ruleSet[1].rules[2].use[1]!./src/a.css
  │ despite it was not able to fulfill desired ordering with these modules:
  │  * css ./css-loader/dist/cjs.js??ruleSet[1].rules[2].use[1]!./src/b.css
  │   - couldn't fulfill desired order of chunk group(s) parent2
  │   - while fulfilling desired order of chunk group(s) parent1

如果你确定他们的顺序不一致没有关系，可以通过配置 ignoreWarnings 来忽略这种错误。

export default {
  ignoreWarnings: [/Conflicting order/],
};

#迁移指南

#使用 rspack.CssExtractRspackPlugin

如果你曾经使用 webpack 和 mini-css-extract-plugin，只需要将 mini-css-extract-plugin 换成 rspack.CssExtractPlugin 即可。

+ import { rspack } from '@rspack/core';
- import CssExtract from 'mini-css-extract-plugin';

export default {
  plugins: [new rspack.CssExtractRspackPlugin()],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [CssExtract.loader, 'css-loader'],
      },
    ],
  },
};

#迁移 builtins.css 配置

1. 使用 module.parser["css/auto"].namedExports 替代 builtins.css.namedExports。
2. 使用 module.generator["css/auto"].exportsOnly 替代 builtins.css.modules.exportsOnly。
3. 使用 module.generator["css/auto"].exportsConvention 替代 builtins.css.modules.localsConvention。
4. 使用 module.generator["css/auto"].localIdentName 替代 builtins.css.modules.localIdentName。

以上出现的 "css/auto" 为 CSS 默认的模块类型，可根据需要修改为 "css" 或 "css/module"。

添加以下配置将保持原有 builtins.css 默认行为，可根据以下配置根据需要进行修改：

export default {
   // ...
+  module: {
+    generator: {
+      "css/auto": {
+        exportsOnly: false,
+        exportsConvention: 'as-is',
+        localIdentName: isProduction ? '[hash]' : '[path][name][ext]__[local]',
+      },
+      "css": {
+        exportsOnly: false,
+        exportsConvention: 'as-is',
+      },
+      "css/module": {
+        exportsOnly: false,
+        exportsConvention: 'as-is',
+        localIdentName: isProduction ? '[hash]' : '[path][name][ext]__[local]',
+      },
+    },
+    parser: {
+      "css/auto": {
+        namedExports: false,
+      },
+      "css": {
+        namedExports: false,
+      },
+      "css/module": {
+        namedExports: false,
+      },
+    },
+  },
}

如需要对部分模块进行配置，可使用 module.rules 中的 rule.parser 和 rule.generator 选项进行配置。

#调用 compiler.run 执行构建

compiler.build 或 compiler.rebuild 已经被废弃，请切换到 compiler.run 进行构建，与重新构建。

#升级 SWC 插件

在 0.6.0 中，Rust crate swc_core 的版本升级到 0.90.x，使用到的 SWC Wasm 插件需要确保其使用的 swc_core 的版本一致性，否则可能产生无法预知的问题。

详情请参考文档。