From 8ffaaf50ff14e2ce80466e016517c52e8c7a0b1c Mon Sep 17 00:00:00 2001 From: 9aoy <9aoyuao@gmail.com> Date: Mon, 24 Nov 2025 11:53:07 +0800 Subject: [PATCH 1/2] docs: add `Configure SWC` guide --- .../docs/en/guide/basic/configure-rstest.mdx | 35 +++++++++++++++++++ .../docs/zh/guide/basic/configure-rstest.mdx | 35 +++++++++++++++++++ 2 files changed, 70 insertions(+) diff --git a/website/docs/en/guide/basic/configure-rstest.mdx b/website/docs/en/guide/basic/configure-rstest.mdx index d78dc5e6..126c011a 100644 --- a/website/docs/en/guide/basic/configure-rstest.mdx +++ b/website/docs/en/guide/basic/configure-rstest.mdx @@ -58,6 +58,41 @@ Rstest uses Rspack for building, so you can directly use Rspack's configuration More details can be referred to [Configure Rspack](https://rsbuild.rs/guide/configuration/rspack). +## Configure SWC + +Rstest uses Rspack's [builtin:swc-loader](https://rspack.rs/guide/features/builtin-swc-loader) to transform JavaScript and TypeScript code by default, which is the Rust version of [swc-loader](https://github.com/swc-project/pkgs/tree/main/packages/swc-loader). + +Rstest exposes some options to configure `builtin:swc-loader`: + +- [tools.swc](/config/build/tools#toolsswc): Used to configure the options of `builtin:swc-loader`. +- [source.include](/config/build/source#sourceinclude): Used to specify the files that need to be compiled by SWC. +- [source.exclude](/config/build/source#sourceexclude): Used to exclude files that do not need to be compiled by SWC. + +```ts +export default { + tools: { + swc: { + jsc: { + transform: { + react: { + runtime: 'automatic', + }, + }, + experimental: { + plugins: [['@swc/plugin-emotion', {}]], + }, + }, + }, + }, +}; +``` + +### SWC Plugin Version + +Please note that SWC's plugins are still an experimental feature. Currently, SWC's Wasm plugins are not backward compatible, and the version of SWC plugins is strongly coupled with the `swc_core` version that Rspack depends on. + +This means that you need to choose SWC plugins that match the current `swc_core` version to make them work properly. If the SWC plugin version you use does not match the `swc_core` version that Rspack depends on, Rspack will throw errors during the build. Please refer to [Rspack FAQ - SWC plugin version mismatch](https://rspack.rs/errors/swc-plugin-version) for handling. + ## Detect Rstest environment You can use `process.env.RSTEST` to detect whether it is an Rstest test environment to apply different configurations/codes in your tests. diff --git a/website/docs/zh/guide/basic/configure-rstest.mdx b/website/docs/zh/guide/basic/configure-rstest.mdx index 09332b95..ad8e78ed 100644 --- a/website/docs/zh/guide/basic/configure-rstest.mdx +++ b/website/docs/zh/guide/basic/configure-rstest.mdx @@ -58,6 +58,41 @@ Rstest 底层使用 Rspack 进行构建，因此你可以直接使用 Rspack 的 详情可参考 [配置 Rspack](https://rsbuild.rs/zh/guide/configuration/rspack)。 +## 配置 SWC + +Rstest 默认通过 Rspack 的 [builtin:swc-loader](https://rspack.rs/zh/guide/features/builtin-swc-loader) 来转换 JavaScript 和 TypeScript 代码，它是 [swc-loader](https://github.com/swc-project/pkgs/tree/main/packages/swc-loader) 的 Rust 版本。 + +Rstest 暴露了一些选项来配置 `builtin:swc-loader`： + +- [tools.swc](/config/build/tools#toolsswc)：用于配置 `builtin:swc-loader` 的选项。 +- [source.include](/config/build/source#sourceinclude)：用于指定需要被 SWC 编译的文件。 +- [source.exclude](/config/build/source#sourceexclude)：用于排除不需要被 SWC 编译的文件。 + +```ts +export default { + tools: { + swc: { + jsc: { + transform: { + react: { + runtime: 'automatic', + }, + }, + experimental: { + plugins: [['@swc/plugin-emotion', {}]], + }, + }, + }, + }, +}; +``` + +### SWC 插件版本 + +请注意，SWC 的插件仍然是一个实验性功能，目前 SWC 的 Wasm 插件是不向后兼容的，SWC 插件的版本与 Rspack 依赖的 `swc_core` 版本存在强耦合关系。 + +这意味着，你需要选择和当前 `swc_core` 版本匹配的 SWC 插件，才能使它正常执行。如果你使用的 SWC 插件版本与 Rspack 依赖的 `swc_core` 版本不匹配，Rspack 在执行构建时会抛出错误，请参考 [Rspack 常见问题 - SWC 插件版本不匹配](https://rspack.rs/zh/errors/swc-plugin-version) 进行处理。 + ## 检测 Rstest 环境 你可以使用 `process.env.RSTEST` 来检测是否是 Rstest 测试环境以应用不同的配置 / 代码在你的测试中。 From 431fdfb8bd42f0b9347f7731dbb9c92cb9d973c1 Mon Sep 17 00:00:00 2001 From: 9aoy <9aoyuao@gmail.com> Date: Mon, 24 Nov 2025 12:41:31 +0800 Subject: [PATCH 2/2] fix: lint --- website/docs/en/guide/basic/configure-rstest.mdx | 8 +++++--- website/docs/zh/guide/basic/configure-rstest.mdx | 6 ++++-- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/website/docs/en/guide/basic/configure-rstest.mdx b/website/docs/en/guide/basic/configure-rstest.mdx index 126c011a..d99004a0 100644 --- a/website/docs/en/guide/basic/configure-rstest.mdx +++ b/website/docs/en/guide/basic/configure-rstest.mdx @@ -69,7 +69,9 @@ Rstest exposes some options to configure `builtin:swc-loader`: - [source.exclude](/config/build/source#sourceexclude): Used to exclude files that do not need to be compiled by SWC. ```ts -export default { +import { defineConfig } from '@rsbuild/core'; + +export default defineConfig({ tools: { swc: { jsc: { @@ -84,10 +86,10 @@ export default { }, }, }, -}; +}); ``` -### SWC Plugin Version +### SWC plugin version Please note that SWC's plugins are still an experimental feature. Currently, SWC's Wasm plugins are not backward compatible, and the version of SWC plugins is strongly coupled with the `swc_core` version that Rspack depends on. diff --git a/website/docs/zh/guide/basic/configure-rstest.mdx b/website/docs/zh/guide/basic/configure-rstest.mdx index ad8e78ed..916f0965 100644 --- a/website/docs/zh/guide/basic/configure-rstest.mdx +++ b/website/docs/zh/guide/basic/configure-rstest.mdx @@ -69,7 +69,9 @@ Rstest 暴露了一些选项来配置 `builtin:swc-loader`： - [source.exclude](/config/build/source#sourceexclude)：用于排除不需要被 SWC 编译的文件。 ```ts -export default { +import { defineConfig } from '@rsbuild/core'; + +export default defineConfig({ tools: { swc: { jsc: { @@ -84,7 +86,7 @@ export default { }, }, }, -}; +}); ``` ### SWC 插件版本