From 90fa94041831893b65b5d1fe7437613cf1468dc7 Mon Sep 17 00:00:00 2001 From: neverland Date: Mon, 27 Jan 2025 13:40:56 +0800 Subject: [PATCH] docs: rewrite plugins usage guide --- website/docs/en/config/plugins.mdx | 47 ++++++++++++++-- website/docs/en/guide/features/plugin.mdx | 53 ++++++++++++++++-- .../webpack/hot-module-replacement-plugin.mdx | 1 + website/docs/zh/config/plugins.mdx | 49 +++++++++++++++-- website/docs/zh/guide/features/plugin.mdx | 54 +++++++++++++++++-- .../webpack/hot-module-replacement-plugin.mdx | 1 + 6 files changed, 189 insertions(+), 16 deletions(-) diff --git a/website/docs/en/config/plugins.mdx b/website/docs/en/config/plugins.mdx index 34890700ef6d..d74e80be53b8 100644 --- a/website/docs/en/config/plugins.mdx +++ b/website/docs/en/config/plugins.mdx @@ -1,23 +1,47 @@ # Plugins -The `plugins` option is used to customize the Rspack build process in a variety of ways. Rspack comes with a variety built-in plugins available under `rspack.[plugin-name]`. See [Plugins page](/plugins/index) for a list of plugins and documentation but note that there are a lot more out in the community. +- **Type:** + +```ts +type Falsy = false | '' | 0 | null | undefined; + +type Plugin = + | RspackPluginInstance + | RspackPluginFunction + | WebpackPluginInstance + | WebpackPluginFunction + | Falsy; + +type Plugins = Plugin[]; +``` -- **Type:** `Array` - **Default:** `[]` -An array of webpack plugins. For example, [`DefinePlugin`](/plugins/webpack/define-plugin) allows you to create global constants which can be configured at compile time. This can be useful for allowing different behavior between development builds and release builds. +The `plugins` option is used to register a set of Rspack or webpack plugins to customize the build process. + +Please refer to [Plugins page](/guide/features/plugin) for more information on using plugins in Rspack. + +## Built-in plugins + +Rspack comes with a variety built-in plugins available under `rspack.PluginName`. + +For example, [`DefinePlugin`](/plugins/webpack/define-plugin) allows you to replaces variables in your code with other values or expressions at compile time. You can access it via `rspack.DefinePlugin` and create a plugin instance with `new`: ```js title=rspack.config.js +const { rspack } = require('@rspack/core'); + module.exports = { //... plugins: [ new rspack.DefinePlugin({ - // Definitions... + // pass plugin options }), ], }; ``` +## webpack plugins + 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: ```js title=rspack.config.js @@ -29,3 +53,18 @@ module.exports = { plugins: [new HtmlWebpackPlugin()], }; ``` + +## Disable plugins + +Rspack ignores `false`、`''`、`0`、`null` 和 `undefined` values in the `plugins` array, which allows you to easily disable a plugin. + +For example, enable [HotModuleReplacementPlugin](/plugins/webpack/hot-module-replacement-plugin) only in the development environment: + +```js title=rspack.config.js +const { rspack } = require('@rspack/core'); +const isDev = process.env.NODE_ENV === 'development'; + +module.exports = { + plugins: [isDev && new rspack.HotModuleReplacementPlugin()], +}; +``` diff --git a/website/docs/en/guide/features/plugin.mdx b/website/docs/en/guide/features/plugin.mdx index 617e5b37996a..83821fa6c1d1 100644 --- a/website/docs/en/guide/features/plugin.mdx +++ b/website/docs/en/guide/features/plugin.mdx @@ -1,16 +1,24 @@ # Plugins -If [loaders](/guide/features/loader) are the workhorse for file transformations (preprocessing), then plugins are the workhorse for the overall Rspack build process. Most of Rspack's native implementations rely on the Rust side of the plugin system. For Node users, you don't need to worry about compatibility issues with Rust, because Rspack takes care of those details for you automatically. You can just focus on how to use the plugins. Find out [plugins](/plugins/index) you can use with Rspack. +If [loaders](/guide/features/loader) are the workhorse for file transformations (preprocessing), then plugins are the workhorse for the overall Rspack build process. Most of Rspack's native implementations rely on the Rust side of the plugin system. + +For Node.js users, you don't need to worry about interoperability issues with Node.js and Rust, because Rspack takes care of those details for you automatically. You can just focus on how to use the plugins. ## Plugin usage -Here's an example of how to use the already compatible [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) in `rspack.config.js`: +Rspack provides the [plugins](/config/plugins) configuration, which is used to register a set of Rspack or webpack plugins to customize the build process. + +Here is an example of using the [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) in `rspack.config.js`: ```js title="rspack.config.js" const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer'); module.exports = { - plugins: [new BundleAnalyzerPlugin()], + plugins: [ + new BundleAnalyzerPlugin({ + // options + }), + ], }; ``` @@ -18,6 +26,45 @@ If you're looking for more Rspack plugins, have a look at the great list of [sup You can also refer to [Plugin compat](/guide/compatibility/plugin) for the list of webpack plugins that have passed Rspack compatibility tests. +## Other plugins + +### Unplugin + +[unplugin](https://github.com/unjs/unplugin) is a unified plugin system for various build tools. You can use plugins implemented based on unplugin in Rspack, typically by importing the `/rspack` subpath of the plugin and registering it through `plugins`. + +Here is an example of using [unplugin-vue-components](https://www.npmjs.com/package/unplugin-vue-components): + +```js title=rspack.config.js +const Components = require('unplugin-vue-components/rspack'); + +module.exports = { + plugins: [ + Components.default({ + // options + }), + ], +}; +``` + +### SWC plugins + +In the built-in [swc-loader](/guide/features/builtin-swc-loader) of Rspack, you can use SWC's Wasm plugins, see [jsc.experimental.plugins](/guide/features/builtin-swc-loader#jscexperimentalplugins). + +### Rsbuild plugins + +[Rsbuild](https://rsbuild.dev) is a build tool based on Rspack, and Rsbuild has its own plugin system. + +Please note that you cannot use Rsbuild plugins in Rspack, because Rspack is a more low-level tool, but you can use Rspack plugins in Rsbuild. + +Here is a comparison table for the plugins that can be used in Rspack and Rsbuild: + +| Tool used | Rspack plugins | webpack plugins | Rsbuild plugins | Unplugins | SWC plugins | +| --------- | -------------- | --------------- | --------------- | --------- | ----------- | +| Rspack | ✅ | ✅ | ❌ | ✅ | ✅ | +| Rsbuild | ✅ | ✅ | ✅ | ✅ | ✅ | + +> Please refer to the [Rsbuild plugin documentation](https://rsbuild.dev/plugins/list/index) for more information. + ## Write a plugin ### Plugin structure diff --git a/website/docs/en/plugins/webpack/hot-module-replacement-plugin.mdx b/website/docs/en/plugins/webpack/hot-module-replacement-plugin.mdx index 2df6df25ae8c..a655fdd88d35 100644 --- a/website/docs/en/plugins/webpack/hot-module-replacement-plugin.mdx +++ b/website/docs/en/plugins/webpack/hot-module-replacement-plugin.mdx @@ -13,6 +13,7 @@ Enabling HMR is straightforward and in most cases no options are necessary. Note that HMR can not be used in production build. You can use `process.env.NODE_ENV` to determine if it is a development environment. ```js title="rspack.config.js" +const { rspack } = require('@rspack/core'); const isDev = process.env.NODE_ENV === 'development'; module.exports = { diff --git a/website/docs/zh/config/plugins.mdx b/website/docs/zh/config/plugins.mdx index 0cbfc12f7047..c0b7cbe8e235 100644 --- a/website/docs/zh/config/plugins.mdx +++ b/website/docs/zh/config/plugins.mdx @@ -1,24 +1,48 @@ # Plugins -`plugins` 选项用于以各种方式自定义 Rspack 构建过程。Rspack 附带了各种内置插件，可以通过 `rspack.[plugin-name]` 访问这些插件。请查看[插件页面](/plugins/index)获取插件列表和对应文档，但请注意这只是其中一部分，社区中还有许多插件。 +- **类型：** + +```ts +type Falsy = false | '' | 0 | null | undefined; + +type Plugin = + | RspackPluginInstance + | RspackPluginFunction + | WebpackPluginInstance + | WebpackPluginFunction + | Falsy; + +type Plugins = Plugin[]; +``` -- **类型：** `Array` - **默认值：** `[]` -一组 Rspack 插件。例如，[`DefinePlugin`](/plugins/webpack/define-plugin) 允许你创建可在编译时配置的全局常量。这对需要再开发环境构建和生产环境构建之间产生不同行为来说非常有用。 +`plugins` 选项用于注册一组 Rspack 或 webpack 插件来自定义构建过程。 + +请查看 [插件页面](/guide/features/plugin) 来了解在 Rspack 中使用插件的更多信息。 + +## 内置插件 + +Rspack 附带了许多内置插件，你可以通过 `rspack.PluginName` 访问这些插件。 + +例如，[`DefinePlugin`](/plugins/webpack/define-plugin) 允许你在编译时将代码中的变量替换为其他值或表达式。你可以通过 `rspack.DefinePlugin` 来访问它，并使用 `new` 来创建插件实例： ```js title=rspack.config.js +const { rspack } = require('@rspack/core'); + module.exports = { //... plugins: [ new rspack.DefinePlugin({ - // 定义的全局常量... + // 传入插件选项 }), ], }; ``` -Rspack 致力于兼容 webpack 生态下的插件，以使用社区中已经积累和验证的优秀功能。请查看[插件兼容列表](/guide/compatibility/plugin)获取经过我们兼容性测试的 webpack 插件清单： +## webpack 插件 + +Rspack 致力于兼容 webpack 生态中的插件，让用户能够使用社区中经过验证的优秀功能。你可以查看 [插件兼容列表](/guide/compatibility/plugin) 来获取已通过兼容性测试的 webpack 插件清单： ```js title=rspack.config.js const { rspack } = require('@rspack/core'); @@ -29,3 +53,18 @@ module.exports = { plugins: [new HtmlWebpackPlugin()], }; ``` + +## 禁用插件 + +Rspack 会忽略 `plugins` 数组中的 `false`、`''`、`0`、`null` 和 `undefined` 这些值，这允许你更容易地禁用某个插件。 + +比如，仅在开发环境中启用 [HotModuleReplacementPlugin](/plugins/webpack/hot-module-replacement-plugin)： + +```js title=rspack.config.js +const { rspack } = require('@rspack/core'); +const isDev = process.env.NODE_ENV === 'development'; + +module.exports = { + plugins: [isDev && new rspack.HotModuleReplacementPlugin()], +}; +``` diff --git a/website/docs/zh/guide/features/plugin.mdx b/website/docs/zh/guide/features/plugin.mdx index c340fbadea17..de749c926b17 100644 --- a/website/docs/zh/guide/features/plugin.mdx +++ b/website/docs/zh/guide/features/plugin.mdx @@ -1,17 +1,24 @@ # 插件 -如果说 [Loader](/guide/features/loader) 是文件转换（预处理）的核心，那么插件（Plugin）则是 Rspack 整体构建流程的核心组成部分，大部分 Rspack 的原生实现依赖了 Rust 侧的插件系统。 -对于 Node 的用户来说，你无需担心和 Rust 的 Interop 问题，因为 Rspack 会自动帮你处理好这些细节，你只需要关注如何使用插件即可。 +如果说 [loader](/guide/features/loader) 是文件转换（预处理）的核心，那么插件（plugin）则是 Rspack 整体构建流程的核心组成部分，Rspack 大部分的原生实现都依赖于 Rust 侧的插件系统。 + +对于 Node.js 的用户来说，你无需担心 Node.js 和 Rust 的互操作问题，因为 Rspack 会自动帮你处理好这些细节，你只需要关注如何使用插件即可。 ## 使用插件 -下面是一个例子，在 `rspack.config.js` 中使用已经兼容的 [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer)： +Rspack 提供了 [plugins](/config/plugins) 配置项，用于注册一组 Rspack 或 webpack 插件来自定义构建过程。 + +下面是一个例子，在 `rspack.config.js` 中使用 [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) 插件： ```js title="rspack.config.js" const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer'); module.exports = { - plugins: [new BundleAnalyzerPlugin()], + plugins: [ + new BundleAnalyzerPlugin({ + // options + }), + ], }; ``` @@ -19,6 +26,45 @@ module.exports = { 你也可以参考 [Plugin 兼容](/guide/compatibility/plugin) 列表，查看已通过 Rspack 兼容性测试的 webpack 插件。 +## 其他插件 + +### Unplugin + +[unplugin](https://github.com/unjs/unplugin) 是一个适用于不同构建工具的统一插件系统。你可以在 Rspack 中使用基于 unplugin 实现的插件，通常需要引入插件的 `/rspack` 子路径，并通过 `plugins` 注册它。 + +下面是使用 [unplugin-vue-components](https://www.npmjs.com/package/unplugin-vue-components) 的示例： + +```js title=rspack.config.js +const Components = require('unplugin-vue-components/rspack'); + +module.exports = { + plugins: [ + Components.default({ + // options + }), + ], +}; +``` + +### SWC 插件 + +在 Rspack 内置的 [swc-loader](/guide/features/builtin-swc-loader) 中，你可以使用 SWC 的 Wasm 插件，详见 [jsc.experimental.plugins](/guide/features/builtin-swc-loader#jscexperimentalplugins)。 + +### Rsbuild 插件 + +[Rsbuild](https://rsbuild.dev) 是基于 Rspack 的构建工具，并且具备一套独立的插件系统。 + +请注意，你无法在 Rspack 中使用 Rsbuild 插件，因为 Rspack 是更加底层的工具，但你可以在 Rsbuild 中使用 Rspack 插件。 + +下面是 Rspack 与 Rsbuild 可用的插件对比： + +| 使用的工具 | Rspack 插件 | webpack 插件 | Rsbuild 插件 | Unplugins | SWC 插件 | +| ---------- | ----------- | ------------ | ------------ | --------- | -------- | +| Rspack | ✅ | ✅ | ❌ | ✅ | ✅ | +| Rsbuild | ✅ | ✅ | ✅ | ✅ | ✅ | + +> 请查看 [Rsbuild 插件文档](https://rsbuild.dev/zh/plugins/list/index) 来获取更多信息。 + ## 编写一个插件 ### 插件结构 diff --git a/website/docs/zh/plugins/webpack/hot-module-replacement-plugin.mdx b/website/docs/zh/plugins/webpack/hot-module-replacement-plugin.mdx index 3f89a1ab90fd..f5e1e1ec09b9 100644 --- a/website/docs/zh/plugins/webpack/hot-module-replacement-plugin.mdx +++ b/website/docs/zh/plugins/webpack/hot-module-replacement-plugin.mdx @@ -13,6 +13,7 @@ new rspack.HotModuleReplacementPlugin(); 注意 HMR 不能被用于生产构建，因此你需要通过 `process.env.NODE_ENV` 来判断当前是否是开发环境。 ```js title="rspack.config.js" +const { rspack } = require('@rspack/core'); const isDev = process.env.NODE_ENV === 'development'; module.exports = {