Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add FAQ for SWC plugin version unmatched #8829

Merged
merged 1 commit into from
Dec 24, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions website/docs/en/errors/swc-plugin-version.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# SWC Plugin Version Unmatched

## Why This Error Occurred

The SWC plugin is still an experimental feature, and the SWC Wasm plugin is currently not backward compatible. The version of the SWC plugin is closely tied to the version of `swc_core` that Rspack depends on.

This means that you must to choose an SWC plugin that matches the current version of `swc_core` to ensure that it works properly. If the version of the SWC plugin you are using does not match the version of `swc_core` that Rspack depends on, Rspack will throw the following error during the build process:

```text
The version of the SWC Wasm plugin you're using might not be compatible with 'builtin:swc-loader'
```

## Possible Ways to Fix It

If you encounter the above issues, a common solution is to upgrade both the Rspack and SWC plugins to the latest versions.

Alternatively, you can follow these steps to select a suitable SWC plugin version:

1. Check the current version of [@rspack/core](https://www.npmjs.com/package/@rspack/core) you are using.
2. Visit [plugins.swc.rs](https://plugins.swc.rs/) and select the version of Rspack you are currently using.
3. The website will list the range of SWC plugin versions that match to your current Rspack version. Then select the matched version of the SWC plugin to use.

If the SWC plugin you are using is not listed on [plugins.swc.rs](https://plugins.swc.rs/), you can find the version information of `swc_core` in the Cargo.toml file within the Rust code repository.

For example, in the Rspack repository, you can open [Cargo.toml](https://github.com/web-infra-dev/rspack/blob/main/Cargo.toml) and search for the keyword `swc_core` to find the version. Then read [SWC - Selecting the version](https://swc.rs/docs/plugin/selecting-swc-core) for further guidance.
3 changes: 2 additions & 1 deletion website/docs/en/guide/features/builtin-swc-loader.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -225,7 +225,8 @@ The following is an introduction to some SWC configurations and Rspack specific

:::warning
The Wasm plugin is deeply coupled with the version of SWC, you need to choose a Wasm plugin that is compatible with the corresponding version of SWC in order to function normally.
you can see more compatible info about how to choose right Wasm plugin version in [selecting-swc-core](https://swc.rs/docs/plugin/selecting-swc-core#088x--089x).

See [FAQ - SWC Plugin Version Unmatched](/errors/swc-plugin-version) for more details.
:::

Rspack supports load Wasm plugin in `builtin:swc-loader`, you can specify the plugin name like
Expand Down
25 changes: 25 additions & 0 deletions website/docs/zh/errors/swc-plugin-version.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# SWC 插件版本不匹配

## 错误出现的原因

SWC 的插件仍然是一个实验性功能,目前 SWC 的 Wasm 插件是不向后兼容的,SWC 插件的版本与 Rspack 依赖的 `swc_core` 版本存在强耦合关系。

这意味着,你需要选择和当前 `swc_core` 版本匹配的 SWC 插件,才能使它正常执行。如果你使用的 SWC 插件版本与 Rspack 依赖的 `swc_core` 版本不匹配,Rspack 在执行构建时会抛出如下错误:

```text
The version of the SWC Wasm plugin you're using might not be compatible with 'builtin:swc-loader'
```

## 可能的修复方式

如果你遇到了以上问题,通常可行的解决方法是将 Rspack 和 SWC 插件都升级到最新版本。

此外,你也可以按照以下步骤来选择合适的 SWC 插件版本:

1. 查看当前使用的 [@rspack/core](https://www.npmjs.com/package/@rspack/core) 版本。
2. 访问 [plugins.swc.rs](https://plugins.swc.rs/),选择你当前使用的 Rspack 版本。
3. 该网站会列出你当前使用的 Rspack 版本所匹配的 SWC 插件版本范围,选择匹配的 SWC 插件版本使用即可。

如果你使用的 SWC 插件未收录到 [plugins.swc.rs](https://plugins.swc.rs/),你可以通过 Rust 代码仓库中的 Cargo.toml 文件来查看 `swc_core` 的版本信息。

以 Rspack 仓库为例,你可以打开 [Cargo.toml](https://github.com/web-infra-dev/rspack/blob/main/Cargo.toml),搜索 `swc_core` 关键字来查看版本,然后参考 [SWC - Selecting the version](https://swc.rs/docs/plugin/selecting-swc-core) 进行选择。
4 changes: 3 additions & 1 deletion website/docs/zh/guide/features/builtin-swc-loader.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -224,7 +224,9 @@ export default {
<ApiMeta stability={Stability.Experimental} />

:::warning
Wasm 插件和 SWC 的版本存在一定的绑定关系,需要选择和对应 SWC 版本兼容的 Wasm 插件才能正常执行, [selecting-swc-core](https://swc.rs/docs/plugin/selecting-swc-core#088x--089x) 里有更多关于如何选择兼容的 Wasm 插件的信息。
Wasm 插件和 SWC 的版本存在一定的绑定关系,需要选择和对应 SWC 版本兼容的 Wasm 插件才能正常执行。

详见 [常见问题 - SWC 插件版本不匹配](/errors/swc-plugin-version)
:::

Rspack 支持在 `builtin:swc-loader` 里加载 SWC 的 Wasm 插件, 你可以通过如下配置启用 Wasm 插件
Expand Down
Loading