#从 Rspack 0.x 迁移

当前文档列出了从 Rspack v0.7 到 v1.0 的所有不兼容更新，你可以参考此文档来迁移。

查看 Breaking changes in Rspack v1.0.0 了解更多细节。

#配置项默认值调整

在 Rspack 1.x 中，我们对齐了 webpack 的配置项默认值。

#[重要] experiments.css

experiments.css 的默认值从 true 调整为 false。

在 Rspack 0.x 中，experiments.css 默认开启，这意味着以 *.css 结尾的文件会默认被视为 type: 'css/auto'，不需要手动引入其他 loader 来处理 CSS 文件。

如果你依赖内置功能来处理 CSS 文件而不使用任何 loader，或者使用了如下的配置来处理 CSS 文件：

export default {
  module: {
    rules: [
      {
        test: /\.less$/,
        type: 'css/auto', // 👈
        use: ['less-loader'],
      },
    ],
  },
};

请注意，你现在需要手动启用 experiments.css。

#[重要] optimization.concatenateModules

optimization.concatenateModules 默认值由 false 调整为：

• 当 mode 为 'production' 时，默认为 true。
• mode 为其他值时，默认值为 false。

在 Rspack 1.x 中，模块拼接优化变得更加稳定。现在，在生产环境中默认开启该优化，以允许将多个模块拼接成单个模块以降低产物体积，提升压缩效率。

#devtool

devtool 默认值由 false 调整为：

• 当 mode 为 'development' 时，默认为 'eval'。
• mode 为其他值时，默认值为 false。

@rspack/cli 会覆盖 @rspack/core 中 devtool 的默认值，因此如果你使用 @rspack/cli，此变更不受影响。

#experiments.asyncWebAssembly

experiments.asyncWebAssembly 默认值从 false 调整为依赖 experiments.futureDefaults 配置项，当 experiments.futureDefaults 为 true 时才默认开启。

如果你使用 WebAssembly 模块作为异步模块，现在需要手动将 experiments.asyncWebAssembly 设置为 true。

#splitChunks.cacheGroups.{cacheGroup}.reuseExistingChunk

splitChunks.cacheGroups.{cacheGroup}.reuseExistingChunk 默认值从 true 调整为 false。

#optimization.moduleIds

当 mode 为 none 时，optimization.moduleIds 默认值调整为 'natural'。

#optimization.chunkIds

当 mode 为 none 时，optimization.chunkIds 默认值调整为 'natural'。

#移除的配置项

#[重要] 移除 resolve.tsConfigPath

请使用 resolve.tsConfig 代替。

export default {
  resolve: {
-   tsConfigPath: path.resolve(__dirname, './tsconfig.json'),
+   tsConfig: path.resolve(__dirname, './tsconfig.json'),
  },
};

#output.amdContainer

请使用 output.library.amdContainer 代替。

#builtin:swc-loader 的调整

Rspack 1.x 为了精简核心，将内置的 SWC 插件移除，现在你需要手动引入它们。

#[重要] 移除 rspackExperiments.styledComponents

使用 @swc/plugin-styled-components 代替。

export default {
  module: {
    rules: [
      {
        test: /\.jsx$/,
        loader: "builtin:swc-loader",
        options: {
-         rspackExperiments: {
-           styledComponents: true,
-         },
          jsc: {
+           experimental: {
+             plugins: [["@swc/plugin-styled-components", {}]],
+           },
          },
        },
      },
    ],
  },
};

#[重要] 移除 rspackExperiments.emotion

使用 @swc/plugin-emotion 代替。

export default {
  module: {
    rules: [
      {
        test: /\.jsx$/,
        loader: "builtin:swc-loader",
        options: {
-         rspackExperiments: {
-           emotion: true,
-         },
          jsc: {
+           experimental: {
+             plugins: [["@swc/plugin-emotion", {}]],
+           },
          },
        },
      },
    ],
  },
};

#[重要] 移除 rspackExperiments.relay

使用 @swc/plugin-relay 代替。

export default {
  module: {
    rules: [
      {
        test: /\.jsx$/,
        loader: "builtin:swc-loader",
        options: {
-         rspackExperiments: {
-           relay: true,
-         },
          jsc: {
+           experimental: {
+             plugins: [["@swc/plugin-relay", {}]],
+           },
          },
        },
      },
    ],
  },
};

#[重要] 移除 rspackExperiments.preact

使用 @swc/plugin-prefresh 代替。

export default {
  module: {
    rules: [
      {
        test: /\.jsx$/,
        loader: "builtin:swc-loader",
        options: {
-         rspackExperiments: {
-           preact: true,
-         },
          jsc: {
+           experimental: {
+             plugins: [["@swc/plugin-prefresh", {}]],
+           },
          },
        },
      },
    ],
  },
};

#内置插件的调整

#[重要] CSS 压缩插件的调整

在 Rspack 0.x 中我们使用内置的 rspack.SwcCssMinimizerRspackPlugin 来压缩 CSS 代码。现在，该插件已被移除，并改用 rspack.LightningCssMinimizerRspackPlugin 替代它。

如果你之前手动注册并配置 rspack.SwcCssMinimizerRspackPlugin，现在需要使用 rspack.LightningCssMinimizerRspackPlugin：

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

export default {
  optimization: {
    minimizer: [
-     new rspack.SwcCssMinimizerRspackPlugin({
+     new rspack.LightningCssMinimizerRspackPlugin({
        // 选项配置
      }),
    ],
  },
};

#rspack.SwcJsMinimizerRspackPlugin

这是 Rspack 内置并默认启用的 JS 压缩插件。我们已将其配置与 SWC 的压缩配置对齐，不兼容的配置如下：

• minimizerOptions.passes：移动到 minimizerOptions.compress.passes
• minimizerOptions.dropConsole：移动到 minimizerOptions.compress.drop_console
• minimizerOptions.pureFuncs：移动到 minimizerOptions.compress.pure_funcs
• minimizerOptions.keepClassNames：移动到 minimizerOptions.mangle.keep_classnames
• minimizerOptions.keepFnNames：移动到 minimizerOptions.mangle.keep_fnames
• minimizerOptions.comments：移动到 minimizerOptions.format.comments
• minimizerOptions.asciiOnly：移动到 minimizerOptions.format.ascii_only

默认值的变化：

• comments (options.format.comments)：默认值从 false 改为 "some"

#rspack.HtmlRspackPlugin

我们将其配置与 html-webpack-plugin 对齐，不兼容的配置如下：

• excludedChunks 更名为 excludeChunks
• 当 mode 为 'production' 时，minify 默认为 true

#其他

#[重要] @rspack/cli

@rspack/cli 已将其依赖的 webpack-dev-server 从 v4 升级至 v5。如果你使用 @rspack/cli，请注意以下不兼容的变更：

• webpack-dev-server v5 最低支持的 Node.js 版本为 18.12.0。
• 配置选项发生了若干变更，请参阅 webpack-dev-server v5 的迁移指南。

#[重要] ResolverFactory 和 Resolver 使用 Rust 重构

ResolverFactory 和 Resolver 已被使用 Rust 进行重构，以统一 JS 侧和 Rust 侧的实现。由于这一变更，目前 ResolverFactory 和 Resolver 并不支持任何钩子。

此外，目前 Resolver 仅支持以下方法：

• resolveSync
• resolve
• withOptions

此变更可能会导致某些插件无法正常使用。

compiler.hooks.normalModuleFactory.tap('PLUGIN', normalModuleFactory => {
  normalModuleFactory.hooks.resolve.tap('PLUGIN', data => {
    // 重定向模块
    if (data.request === './foo.js') {
      data.request = './bar.js';
    }
  });
});