From 4444be4bacc60e030eda017f1074d188f5a7acf8 Mon Sep 17 00:00:00 2001 From: sadan4 <117494111+sadan4@users.noreply.github.com> Date: Wed, 11 Jun 2025 21:24:29 -0400 Subject: [PATCH 1/3] docs: fix minor grammar issue in `config/build-options` (#20193) --- config/build-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config/build-options.md b/config/build-options.md index 86689230..c6f667ee 100644 --- a/config/build-options.md +++ b/config/build-options.md @@ -125,7 +125,7 @@ This option allows users to set a different browser target for CSS minification It should only be used when you are targeting a non-mainstream browser. One example is Android WeChat WebView, which supports most modern JavaScript features but not the [`#RGBA` hexadecimal color notation in CSS](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#rgb_colors). -In this case, you need to set `build.cssTarget` to `chrome61` to prevent vite from transform `rgba()` colors into `#RGBA` hexadecimal notations. +In this case, you need to set `build.cssTarget` to `chrome61` to prevent vite from transforming `rgba()` colors into `#RGBA` hexadecimal notations. ## build.cssMinify From 30bb5fa45fdb9dc780231f27244dce48a7346426 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=BF=A0?= Date: Thu, 12 Jun 2025 18:01:03 +0900 Subject: [PATCH 2/3] docs(rolldown): update to reflect the latest changes (#20196) --- guide/rolldown.md | 33 ++++++++++++++++++++++----------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/guide/rolldown.md b/guide/rolldown.md index 1146ad24..712abce9 100644 --- a/guide/rolldown.md +++ b/guide/rolldown.md @@ -89,15 +89,15 @@ After adding these overrides, reinstall your dependencies and start your develop While Rolldown aims to be a drop-in replacement for Rollup, there are features that are still being implemented and minor intentional behavior differences. For a comprehensive list, please refer to [this GitHub PR](https://github.com/vitejs/rolldown-vite/pull/84#issue-2903144667) which is regularly updated. -### Option Validation Errors +### Option Validation Warnings -Rolldown throws an error when unknown or invalid options are passed. Because some options available in Rollup are not supported by Rolldown, you may encounter errors based on the options you or the meta framework you use set. Below, you can find an example of such an error message: +Rolldown outputs an warning when unknown or invalid options are passed. Because some options available in Rollup are not supported by Rolldown, you may encounter warnings based on the options you or the meta framework you use set. Below, you can find an example of such an warning message: -> Error: Failed validate input options. +> Warning validate output options. > -> - For the "preserveEntrySignatures". Invalid key: Expected never but received "preserveEntrySignatures". +> - For the "generatedCode". Invalid key: Expected never but received "generatedCode". -If you don't pass the option in yourself, this must be fixed by the utilized framework. You can suppress this error in the meantime by setting the `ROLLDOWN_OPTIONS_VALIDATION=loose` environment variable. +If you don't pass the option in yourself, this must be fixed by the utilized framework. ### API Differences @@ -257,6 +257,12 @@ const plugin = { } ``` +::: tip + +Since Vite 7.0.0, `this.meta` is available in all hooks. In previous versions, `this.meta` was not available in Vite-specific hooks, such as the `config` hook. + +::: +
Checking the existence of the `rolldownVersion` export: @@ -275,16 +281,15 @@ If you have `vite` as a dependency (not a peer dependency), the `rolldownVersion ### Ignoring option validation in Rolldown -As [mentioned above](#option-validation-errors), Rolldown throws an error when unknown or invalid options are passed. +As [mentioned above](#option-validation-errors), Rolldown outputs a warning when unknown or invalid options are passed. This can be fixed by conditionally passing the option by checking whether it's running with `rolldown-vite` as [shown above](#detecting-rolldown-vite). -Suppressing the error by setting the `ROLLDOWN_OPTIONS_VALIDATION=loose` environment variable also works in this case. -However, keep in mind that you will **eventually need to stop passing the options not supported by Rolldown**. - ### `transformWithEsbuild` requires `esbuild` to be installed separately -A similar function called `transformWithOxc`, which uses Oxc instead of `esbuild`, is exported from `rolldown-vite`. +Since Vite itself does not use `esbuild` any more, `esbuild` is now an optional peer dependency. If your plugin uses `transformWithEsbuild`, the plugin needs to add `esbuild` to its dependencies or the user needs to install it manually. + +The recommended migration is to use the newly exported `transformWithOxc` function, which utilizes Oxc instead of `esbuild`. ### Compatibility layer for `esbuild` options @@ -306,6 +311,12 @@ const plugin = { Rolldown introduced a [hook filter feature](https://rolldown.rs/guide/plugin-development#plugin-hook-filters) to reduce the communication overhead the between Rust and JavaScript runtimes. By using this feature you can make your plugin more performant. This is also supported by Rollup 4.38.0+ and Vite 6.3.0+. To make your plugin backward compatible with the older versions, make sure to also run the filter inside the hook handlers. +::: tip + +[`@rolldown/pluginutils`](https://www.npmjs.com/package/@rolldown/pluginutils) exports some utilities for hook filters like `exactRegex` and `prefixRegex`. + +::: + ### Converting content to JavaScript in `load` or `transform` hooks If you are converting the content to JavaScript from other types in `load` or `transform` hooks, you may need to add `moduleType: 'js'` to the returned value. @@ -325,4 +336,4 @@ const plugin = { } ``` -This is because [Rolldown supports non-JavaScript modules](https://rolldown.rs/guide/in-depth/module-types) and infers the module type from extensions unless specified. Note that `rolldown-vite` does not support ModuleTypes in dev. +This is because [Rolldown supports non-JavaScript modules](https://rolldown.rs/guide/in-depth/module-types) and infers the module type from extensions unless specified. From 1c0668d3b1351774eb48dee23d6d406b0324b6a2 Mon Sep 17 00:00:00 2001 From: Kylin <1159469891@qq.com> Date: Fri, 13 Jun 2025 10:10:44 +0800 Subject: [PATCH 3/3] docs: update content --- config/build-options.md | 6 ----- guide/rolldown.md | 51 ++++++++--------------------------------- 2 files changed, 10 insertions(+), 47 deletions(-) diff --git a/config/build-options.md b/config/build-options.md index ab41b433..b95f8e16 100644 --- a/config/build-options.md +++ b/config/build-options.md @@ -123,15 +123,9 @@ Git LFS 占位符会自动排除在内联之外，因为它们不包含其所表 此选项允许用户为 CSS 的压缩设置一个不同的浏览器 target，此处的 target 并非是用于 JavaScript 转写目标。 -<<<<<<< HEAD 应只在针对非主流浏览器时使用。 最直观的示例是当你要兼容的场景是安卓微信中的 webview 时，它支持大多数现代的 JavaScript 功能，但并不支持 [CSS 中的 `#RGBA` 十六进制颜色符号](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#rgb_colors)。 这种情况下，你需要将 `build.cssTarget` 设置为 `chrome61`，以防止 vite 将 `rgba()` 颜色转化为 `#RGBA` 十六进制符号的形式。 -======= -It should only be used when you are targeting a non-mainstream browser. -One example is Android WeChat WebView, which supports most modern JavaScript features but not the [`#RGBA` hexadecimal color notation in CSS](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#rgb_colors). -In this case, you need to set `build.cssTarget` to `chrome61` to prevent vite from transforming `rgba()` colors into `#RGBA` hexadecimal notations. ->>>>>>> 30bb5fa45fdb9dc780231f27244dce48a7346426 ## build.cssMinify {#build-cssminify} diff --git a/guide/rolldown.md b/guide/rolldown.md index 6d18faf9..0769eedb 100644 --- a/guide/rolldown.md +++ b/guide/rolldown.md @@ -89,25 +89,15 @@ Rolldown 专注于三个主要原则： 虽然 Rolldown 的目标是成为 Rollup 的替代品，但还有一些特性正在实现中，以及一些小的有意的行为差异。需要查看完整的列表，请参考 [这个 GitHub PR](https://github.com/vitejs/rolldown-vite/pull/84#issue-2903144667)，它会定期更新。 -<<<<<<< HEAD -### 验证选项错误 {#option-validation-errors} +### 验证选项警告 {#option-validation-warnings} -当传入未知或无效选项时，Rolldown 会抛出错误。由于 Rolldown 不支持 Rollup 中的部分选项，根据您或所使用的元框架设置的选项，可能会遇到相关错误。下方展示了此类错误消息的示例： -======= -### Option Validation Warnings - -Rolldown outputs an warning when unknown or invalid options are passed. Because some options available in Rollup are not supported by Rolldown, you may encounter warnings based on the options you or the meta framework you use set. Below, you can find an example of such an warning message: ->>>>>>> 30bb5fa45fdb9dc780231f27244dce48a7346426 +当传入未知或无效选项时，Rolldown 会输出警告。由于 Rolldown 不支持 Rollup 中的部分选项，根据您或所使用的元框架设置的选项，可能会遇到相关警告。下方展示了此类警告消息的示例： > Warning validate output options. > > - For the "generatedCode". Invalid key: Expected never but received "generatedCode". -<<<<<<< HEAD -如果你自己没有传递这个选项，这个问题必须由使用的框架来解决。你可以通过设置 `ROLLDOWN_OPTIONS_VALIDATION=loose` 环境变量来暂时忽略这个错误。 -======= -If you don't pass the option in yourself, this must be fixed by the utilized framework. ->>>>>>> 30bb5fa45fdb9dc780231f27244dce48a7346426 +如果你自己没有传递这个选项，这个问题必须由使用的框架来解决。 ### API 差异 {#api-differences} @@ -269,7 +259,7 @@ const plugin = { ::: tip -Since Vite 7.0.0, `this.meta` is available in all hooks. In previous versions, `this.meta` was not available in Vite-specific hooks, such as the `config` hook. +自 Vite 7.0.0 起，`this.meta` 在所有钩子中都可用。在此版本之前，`this.meta` 在 Vite 特有的钩子（如 `config` 钩子）中不可用。 ::: @@ -291,28 +281,15 @@ if (vite.rolldownVersion) { ### 在 Rolldown 中忽略选项验证 {#ignoring-option-validation-in-rolldown} -<<<<<<< HEAD -如 [前文所述](#option-validation-errors)，当传入未知或无效选项时，Rolldown 会抛出错误。 -======= -As [mentioned above](#option-validation-errors), Rolldown outputs a warning when unknown or invalid options are passed. ->>>>>>> 30bb5fa45fdb9dc780231f27244dce48a7346426 +如 [前文所述](#option-validation-errors)，当传入未知或无效选项时，Rolldown 会输出警告。 可通过条件式传递选项（通过 [如上所示](#detecting-rolldown-vite) 检测是否使用 `rolldown-vite`）来修复此问题。 -<<<<<<< HEAD -在此场景中，设置环境变量 `ROLLDOWN_OPTIONS_VALIDATION=loose` 亦可抑制错误。 -但需注意，**最终仍需停止传递 Rolldown 不支持的选项**。 - ### `transformWithEsbuild` 需要单独安装 `esbuild` {#transformwithesbuild-requires-installing-esbuild-separately} -一个类似的函数，名为 `transformWithOxc`，它使用 Oxc 而非 `esbuild`，从 `rolldown-vite` 中导出。 -======= -### `transformWithEsbuild` requires `esbuild` to be installed separately - -Since Vite itself does not use `esbuild` any more, `esbuild` is now an optional peer dependency. If your plugin uses `transformWithEsbuild`, the plugin needs to add `esbuild` to its dependencies or the user needs to install it manually. +由于 Vite 本身已不再使用 `esbuild`，`esbuild` 现在被作为可选的 peer dependency。如果你的插件使用了 `transformWithEsbuild`，则需要将 `esbuild` 添加到插件的依赖中，或者由用户手动安装。 -The recommended migration is to use the newly exported `transformWithOxc` function, which utilizes Oxc instead of `esbuild`. ->>>>>>> 30bb5fa45fdb9dc780231f27244dce48a7346426 +推荐的迁移方式是使用新导出的 `transformWithOxc` 函数，它采用 Oxc 而不是 `esbuild` 来完成相应任务。 ### `esbuild` 选项的兼容层 {#compatibility-layer-for-esbuild-options} @@ -334,17 +311,13 @@ const plugin = { Rolldown 引入了[钩子过滤功能](https://rolldown.rs/guide/plugin-development#plugin-hook-filters)，以减少 Rust 和 JavaScript 运行时之间的通信开销。通过使用此功能，你可以使你的插件性能更高。 这也在 Rollup 4.38.0+ 和 Vite 6.3.0+ 被支持。为了使你的插件向后兼容较旧的版本，请确保也在钩子处理程序内运行过滤器。 -<<<<<<< HEAD -### 在 `load` 或 `transform` 钩子中将内容转换为 JavaScript {#converting-content-to-javascript-in-load-or-transform-hooks} -======= ::: tip -[`@rolldown/pluginutils`](https://www.npmjs.com/package/@rolldown/pluginutils) exports some utilities for hook filters like `exactRegex` and `prefixRegex`. +[`@rolldown/pluginutils`](https://www.npmjs.com/package/@rolldown/pluginutils) 导出了一些用于钩子过滤器的工具函数，例如 `exactRegex` 和 `prefixRegex`。 ::: -### Converting content to JavaScript in `load` or `transform` hooks ->>>>>>> 30bb5fa45fdb9dc780231f27244dce48a7346426 +### 在 `load` 或 `transform` 钩子中将内容转换为 JavaScript {#converting-content-to-javascript-in-load-or-transform-hooks} 如果你在 `load` 或 `transform` 钩子中将内容转换为 JavaScript，你可能需要添加 `moduleType: 'js'` 到返回值中。 @@ -363,8 +336,4 @@ const plugin = { } ``` -<<<<<<< HEAD -这是因为 [Rolldown 支持非 JavaScript 模块](https://rolldown.rs/guide/in-depth/module-types) 并且除非指定，否则从扩展名推断模块类型。注意 `rolldown-vite` 不支持开发中的 ModuleTypes。 -======= -This is because [Rolldown supports non-JavaScript modules](https://rolldown.rs/guide/in-depth/module-types) and infers the module type from extensions unless specified. ->>>>>>> 30bb5fa45fdb9dc780231f27244dce48a7346426 +这是因为 [Rolldown 支持非 JavaScript 模块](https://rolldown.rs/guide/in-depth/module-types) 并且除非指定，否则从扩展名推断模块类型。