From 489e74b90f34a6a5f37c1804c16708f995c9f992 Mon Sep 17 00:00:00 2001 From: neverland Date: Fri, 3 Jan 2025 17:33:39 +0800 Subject: [PATCH] docs: add loader API overview page (#8928) --- website/docs/en/api/loader-api/index.mdx | 21 +++++++++++++++++-- .../api/loader-api/inline-match-resource.mdx | 8 +++++-- .../loader-api/rspack-specific-properties.mdx | 2 +- website/docs/en/blog/announcing-0-4.mdx | 2 +- website/docs/en/plugins/index.mdx | 10 +++++++++ website/docs/zh/api/loader-api/index.mdx | 21 +++++++++++++++++-- .../api/loader-api/inline-match-resource.mdx | 9 ++++++-- website/docs/zh/blog/announcing-0-3.mdx | 2 +- website/docs/zh/plugins/index.mdx | 12 ++++++++++- 9 files changed, 75 insertions(+), 12 deletions(-) diff --git a/website/docs/en/api/loader-api/index.mdx b/website/docs/en/api/loader-api/index.mdx index 0bab72a38a52..b3eaee0e0dd8 100644 --- a/website/docs/en/api/loader-api/index.mdx +++ b/website/docs/en/api/loader-api/index.mdx @@ -1,5 +1,22 @@ -# Compatibility Status +# Overview + +## Compatibility Status Rspack is committed to being compatible with the loaders within the webpack ecosystem. We ensure that Rspack is as compatible as possible with the webpack loader API, allowing more existing webpack loaders to be directly used in Rspack. -We have already made most of the webpack loader APIs compatible. You can visit [this page](https://github.com/orgs/web-infra-dev/projects/10) to learn about the current compatibility status of webpack loader APIs. +Currently, Rspack is compatible with most of webpack's loader APIs. If you find that a webpack loader cannot be used in Rspack, feel free to file an issue in the [Rspack repository](https://github.com/web-infra-dev/rspack). + +## Examples + +We provide some basic examples of different types of loaders. If you want to write a loader, you can refer to [these examples](./examples) to get started. + +If you need to use an existing loader, you can refer to [Features - Loader](/guide/features/loader) to learn how to use it. + +## Loader API + +Loader API includes: + +- [Loader Context](/api/loader-api/context): Represents the properties that are available inside of a loader assigned to the `this` property. +- [Compiler internal specific properties](/api/loader-api/rspack-specific-properties): In rare cases you might need access to the compiler API itself. +- [Inline loader](/api/loader-api/inline): Specify a loader in an `import` statement. +- [Inline matchResource](/api/loader-api/inline-match-resource): Allows you to dynamically change the matching rules when loading resources. diff --git a/website/docs/en/api/loader-api/inline-match-resource.mdx b/website/docs/en/api/loader-api/inline-match-resource.mdx index 852eb7777689..6dc3b8433c68 100644 --- a/website/docs/en/api/loader-api/inline-match-resource.mdx +++ b/website/docs/en/api/loader-api/inline-match-resource.mdx @@ -4,11 +4,15 @@ import WebpackLicense from '@components/WebpackLicense'; # Inline matchResource -Prefixing `!=!` to a request will set the `matchResource` for this request. +Inline matchResource allows you to dynamically change the matching rules when loading resources. You can set the `matchResource` for a request by prefixing `!=!` to the request. When a `matchResource` is set, it will be used to match with the `module.rules` instead of the original resource. This can be useful if further loaders should be applied to the resource, or if the module type needs to be changed. -Example: +:::tip +It is not recommended to use this syntax in source code. Inline request syntax is intended to only be used by loader generated code. Not following this recommendation will make your code Rspack-specific and non-standard. +::: + +## Example ```js title="file.js" /* STYLE: body { background: red; } */ diff --git a/website/docs/en/api/loader-api/rspack-specific-properties.mdx b/website/docs/en/api/loader-api/rspack-specific-properties.mdx index 7b26a3edf478..3b286be5baf6 100644 --- a/website/docs/en/api/loader-api/rspack-specific-properties.mdx +++ b/website/docs/en/api/loader-api/rspack-specific-properties.mdx @@ -6,7 +6,7 @@ import WebpackLicense from '@components/WebpackLicense'; # Compiler internal specific properties -The loader interface provides all module relate information. However in rare cases you might need access to the compiler api itself. +The loader interface provides all module relate information. However in rare cases you might need access to the compiler API itself. :::warning Please note that using these Rspack specific properties will have a negative impact on your loaders compatibility. diff --git a/website/docs/en/blog/announcing-0-4.mdx b/website/docs/en/blog/announcing-0-4.mdx index 82a3ee8268da..3a60fe628dc9 100644 --- a/website/docs/en/blog/announcing-0-4.mdx +++ b/website/docs/en/blog/announcing-0-4.mdx @@ -170,7 +170,7 @@ Checkout [here](/guide/tech/react#fast-refresh) for more details. `experiments.incrementalRebuild` has now been deprecated. Rspack will remove it in v0.5.0. -### Refactoring export api in @rspack/core +### Refactoring export API in @rspack/core Before, some APIs should not be exported accidentally exported through re-export from @rspack/core. Now with this refactor, we clean up the export APIs from @rspack/core. diff --git a/website/docs/en/plugins/index.mdx b/website/docs/en/plugins/index.mdx index 7081379687ce..ca5d824f3b06 100644 --- a/website/docs/en/plugins/index.mdx +++ b/website/docs/en/plugins/index.mdx @@ -6,10 +6,20 @@ Rspack enhances its compilation capabilities through a rich ecosystem of plugins To align with webpack's functionality, Rspack has replicated most of webpack's built-in plugins. They maintain the same naming and configuration parameters as closely as possible and provide the same features. +See [Webpack-aligned built-in plugins - Overview](/plugins/webpack/index) for more details. + ## Rspack-only Built-in Plugins Combining its own implementation characteristics, Rspack offers several unique plugins as alternatives to corresponding plugins from the webpack ecosystem, aiming to deliver more efficient performance. +Including: + +- [CopyRspackPlugin](/plugins/rspack/copy-rspack-plugin) +- [CssExtractRspackPlugin](/plugins/rspack/css-extract-rspack-plugin) +- [HtmlRspackPlugin](/plugins/rspack/html-rspack-plugin) +- [LightningCssMinimizerRspackPlugin](/plugins/rspack/lightning-css-minimizer-rspack-plugin) +- [SwcJsMinimizerRspackPlugin](/plugins/rspack/swc-js-minimizer-rspack-plugin) + ## Compatible Plugins from the webpack Ecosystem Rspack strives to maintain compatibility with the webpack plugin ecosystem to leverage the excellent features that have been accumulated and validated by the community. Please refer to the [Plugin Compatibility List](/guide/compatibility/plugin) to access a list of webpack plugins that have passed our compatibility tests. diff --git a/website/docs/zh/api/loader-api/index.mdx b/website/docs/zh/api/loader-api/index.mdx index 9da84de6b3f4..5e86d065dcd9 100644 --- a/website/docs/zh/api/loader-api/index.mdx +++ b/website/docs/zh/api/loader-api/index.mdx @@ -1,5 +1,22 @@ -# 兼容情况 +# 总览 + +## 兼容情况 Rspack 致力于兼容 webpack 生态中的 loader。我们确保 Rspack 尽可能地去兼容 webpack 的 loader API，使更多现有的 webpack loader 能够在 Rspack 中直接使用。 -我们已兼容了大部分 webpack 的 loader API，你可以访问[这个页面](https://github.com/orgs/web-infra-dev/projects/10)来了解目前 webpack Loader API 的兼容情况。 +目前 Rspack 已经兼容了绝大部分 webpack 的 loader API，如果你发现某个 webpack loader 无法在 Rspack 中使用，欢迎到 [Rspack 仓库](https://github.com/web-infra-dev/rspack) 通过 issue 反馈。 + +## 示例 + +我们提供了不同类型 loader 的一些基本示例，如果你想要编写一个 loader，可以参考 [这些示例](/api/loader-api/examples) 来上手。 + +如果你需要使用一个已有的 loader，可以参考 [特性 - loader](/guide/features/loader) 来了解如何使用。 + +## Loader API + +Loader API 包含： + +- [Loader 上下文](/api/loader-api/context)：表示 loader 内部可用的属性，这些属性在 loader 中通过 `this` 属性进行访问。 +- [编译器特定属性](/api/loader-api/rspack-specific-properties)：在极少数情况下，你可能需要访问编译器 API 本身。 +- [内联 loader](/api/loader-api/inline)：在 `import` 语句中指定 loader。 +- [内联 matchResource](/api/loader-api/inline-match-resource)：允许你在加载资源时动态改变匹配规则。 diff --git a/website/docs/zh/api/loader-api/inline-match-resource.mdx b/website/docs/zh/api/loader-api/inline-match-resource.mdx index cb4d03eb013b..69a0957783ea 100644 --- a/website/docs/zh/api/loader-api/inline-match-resource.mdx +++ b/website/docs/zh/api/loader-api/inline-match-resource.mdx @@ -4,10 +4,15 @@ import WebpackLicense from '@components/WebpackLicense'; # 内联 matchResource -在一个请求前缀 `!=!` 将为这个请求设置匹配资源。 +Inline matchResource 允许你在加载资源时动态改变匹配规则。你可以通过在请求前添加 `!=!` 前缀来为该请求设置 `matchResource`。 + 当 `matchResource` 被设置时，它将被用来与 `module.rules` 而不是原始资源进行匹配。当如果有更多的 loader 应该应用到资源上，或者需要改变模块的类型，这可能很有用。 -例子： +:::tip +不建议在源代码中使用这种语法。内联请求语法应该仅用于 loader 生成的代码。如果不遵循此建议，你的代码将与 Rspack 耦合，且不符合标准规范。 +::: + +## 示例 ```js title="file.js" /*STYLE: body { background: red; } */ diff --git a/website/docs/zh/blog/announcing-0-3.mdx b/website/docs/zh/blog/announcing-0-3.mdx index ee2695934a2c..13d86679d40d 100644 --- a/website/docs/zh/blog/announcing-0-3.mdx +++ b/website/docs/zh/blog/announcing-0-3.mdx @@ -184,7 +184,7 @@ $ RSPACK_PROFILE=ALL rspack build ### 更多的 Hook 和插件支持 -相比 0.2 版本，我们在 0.3 版本中实现了更多的插件 API 和兼容了更多的插件，同时我们对 webpack 的 插件 API 进行了梳理，将 插件 API 的支持进度透明化，你可以在这里[plugin-api-progress](https://github.com/orgs/web-infra-dev/projects/9/views/1) 追踪插件 api 的实现进度。 +相比 0.2 版本，我们在 0.3 版本中实现了更多的插件 API 和兼容了更多的插件，同时我们对 webpack 的 插件 API 进行了梳理，将 插件 API 的支持进度透明化，你可以在这里[plugin-api-progress](https://github.com/orgs/web-infra-dev/projects/9/views/1) 追踪插件 API 的实现进度。 ### 和 webpack 架构对齐 diff --git a/website/docs/zh/plugins/index.mdx b/website/docs/zh/plugins/index.mdx index 0c77c36f6182..a07a0c658cea 100644 --- a/website/docs/zh/plugins/index.mdx +++ b/website/docs/zh/plugins/index.mdx @@ -6,13 +6,23 @@ Rspack 通过丰富插件生态来增强编译功能，这些插件分为以下 为了对齐 webpack 的功能，Rspack 实现了大部分 webpack 内置插件，它们尽可能地保持了相同的命名和参数配置，并提供相同的功能。 +详见 [同步自 webpack 的内置插件 - 总览](/plugins/webpack/index)。 + ## Rspack 独有的内置插件 Rspack 结合自身实现特点，提供了一些独有的插件，替代对应的 webpack 生态插件，旨在提供更高效的性能。 +包括： + +- [CopyRspackPlugin](/plugins/rspack/copy-rspack-plugin) +- [CssExtractRspackPlugin](/plugins/rspack/css-extract-rspack-plugin) +- [HtmlRspackPlugin](/plugins/rspack/html-rspack-plugin) +- [LightningCssMinimizerRspackPlugin](/plugins/rspack/lightning-css-minimizer-rspack-plugin) +- [SwcJsMinimizerRspackPlugin](/plugins/rspack/swc-js-minimizer-rspack-plugin) + ## 兼容的 webpack 生态插件 -Rspack 致力于兼容 webpack 生态下的插件，以使用社区中已经积累和验证的优秀功能。请查看[插件兼容列表](/guide/compatibility/plugin)获取经过我们兼容性测试的 webpack 插件清单。 +Rspack 致力于兼容 webpack 生态下的插件，以使用社区中已经积累和验证的优秀功能。请查看 [插件兼容列表](/guide/compatibility/plugin) 获取经过我们兼容性测试的 webpack 插件清单。 ## 社区插件