@modern-js/main-doc 2.67.7 → 2.67.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (87) hide show
  1. package/docs/en/apis/app/commands.mdx +3 -3
  2. package/docs/en/community/blog/v2-release-note.mdx +2 -2
  3. package/docs/en/community/contributing-guide.mdx +1 -1
  4. package/docs/en/components/builder.mdx +1 -1
  5. package/docs/en/components/bundler.mdx +1 -1
  6. package/docs/en/components/rsbuild.mdx +1 -1
  7. package/docs/en/components/rspack.mdx +1 -1
  8. package/docs/en/components/rspackPrecautions.mdx +2 -2
  9. package/docs/en/configure/app/builder-plugins.mdx +1 -1
  10. package/docs/en/configure/app/output/assets-retry.mdx +1 -1
  11. package/docs/en/configure/app/output/copy.mdx +1 -1
  12. package/docs/en/configure/app/performance/build-cache.mdx +1 -1
  13. package/docs/en/configure/app/security/sri.mdx +1 -1
  14. package/docs/en/configure/app/source/exclude.mdx +2 -2
  15. package/docs/en/configure/app/source/include.mdx +1 -1
  16. package/docs/en/configure/app/source/transform-import.mdx +2 -2
  17. package/docs/en/configure/app/tools/babel.mdx +5 -5
  18. package/docs/en/configure/app/tools/bundler-chain.mdx +2 -2
  19. package/docs/en/configure/app/tools/css-extract.mdx +1 -1
  20. package/docs/en/configure/app/tools/dev-server.mdx +1 -1
  21. package/docs/en/configure/app/tools/lightningcss-loader.mdx +1 -1
  22. package/docs/en/configure/app/tools/rspack.mdx +1 -1
  23. package/docs/en/configure/app/tools/swc.mdx +3 -3
  24. package/docs/en/configure/app/tools/webpack-chain.mdx +19 -19
  25. package/docs/en/guides/advanced-features/build-performance.mdx +1 -1
  26. package/docs/en/guides/advanced-features/compatibility.mdx +1 -1
  27. package/docs/en/guides/advanced-features/page-performance/optimize-bundle.mdx +3 -3
  28. package/docs/en/guides/advanced-features/rspack-start.mdx +2 -2
  29. package/docs/en/guides/basic-features/css/css.mdx +4 -4
  30. package/docs/en/guides/basic-features/debug/rsdoctor.mdx +1 -1
  31. package/docs/en/guides/basic-features/routes.mdx +3 -3
  32. package/docs/en/guides/basic-features/static-assets.mdx +1 -1
  33. package/docs/en/guides/concept/builder.mdx +3 -3
  34. package/docs/en/guides/concept/entries.mdx +1 -1
  35. package/docs/en/guides/get-started/tech-stack.mdx +3 -3
  36. package/docs/en/guides/troubleshooting/builder.mdx +4 -5
  37. package/docs/en/plugin/cli-plugins/api.mdx +140 -134
  38. package/docs/en/plugin/introduction.mdx +27 -24
  39. package/docs/en/tutorials/examples/csr-auth.mdx +15 -198
  40. package/docs/zh/apis/app/commands.mdx +3 -3
  41. package/docs/zh/community/blog/v2-release-note.mdx +2 -2
  42. package/docs/zh/community/contributing-guide.mdx +1 -1
  43. package/docs/zh/components/builder.mdx +1 -1
  44. package/docs/zh/components/bundler.mdx +1 -2
  45. package/docs/zh/components/rsbuild.mdx +1 -1
  46. package/docs/zh/components/rspack.mdx +1 -1
  47. package/docs/zh/components/rspackPrecautions.mdx +2 -2
  48. package/docs/zh/configure/app/builder-plugins.mdx +1 -1
  49. package/docs/zh/configure/app/output/assets-retry.mdx +1 -1
  50. package/docs/zh/configure/app/output/copy.mdx +1 -1
  51. package/docs/zh/configure/app/performance/build-cache.mdx +1 -1
  52. package/docs/zh/configure/app/security/sri.mdx +1 -1
  53. package/docs/zh/configure/app/source/exclude.mdx +2 -2
  54. package/docs/zh/configure/app/source/include.mdx +1 -1
  55. package/docs/zh/configure/app/source/transform-import.mdx +2 -2
  56. package/docs/zh/configure/app/tools/babel.mdx +5 -6
  57. package/docs/zh/configure/app/tools/bundler-chain.mdx +2 -2
  58. package/docs/zh/configure/app/tools/css-extract.mdx +1 -1
  59. package/docs/zh/configure/app/tools/dev-server.mdx +1 -1
  60. package/docs/zh/configure/app/tools/lightningcss-loader.mdx +1 -1
  61. package/docs/zh/configure/app/tools/rspack.mdx +1 -1
  62. package/docs/zh/configure/app/tools/swc.mdx +3 -3
  63. package/docs/zh/configure/app/tools/webpack-chain.mdx +20 -20
  64. package/docs/zh/guides/advanced-features/compatibility.mdx +1 -1
  65. package/docs/zh/guides/advanced-features/page-performance/optimize-bundle.mdx +2 -2
  66. package/docs/zh/guides/advanced-features/rspack-start.mdx +2 -2
  67. package/docs/zh/guides/basic-features/css/css.mdx +4 -4
  68. package/docs/zh/guides/basic-features/debug/rsdoctor.mdx +1 -1
  69. package/docs/zh/guides/basic-features/static-assets.mdx +2 -2
  70. package/docs/zh/guides/concept/builder.mdx +3 -3
  71. package/docs/zh/guides/concept/entries.mdx +1 -1
  72. package/docs/zh/guides/get-started/tech-stack.mdx +3 -3
  73. package/docs/zh/guides/troubleshooting/builder.mdx +4 -5
  74. package/docs/zh/plugin/cli-plugins/api.mdx +122 -120
  75. package/docs/zh/plugin/introduction.mdx +18 -15
  76. package/docs/zh/tutorials/examples/csr-auth.mdx +15 -198
  77. package/package.json +6 -6
  78. package/rspress.config.ts +12 -1
  79. package/src/components/RsbuildLink/index.tsx +1 -1
  80. package/src/components/Sandpack/index.tsx +1 -11
  81. package/src/components/ShowcaseList/useShowcases.ts +1 -1
  82. package/src/sandbox/csr-auth/src/routes/Auth-tsx.txt +74 -0
  83. package/src/sandbox/csr-auth/src/routes/fakeAuth-ts.txt +16 -0
  84. package/src/sandbox/csr-auth/src/routes/layout-tsx.txt +21 -0
  85. package/src/sandbox/csr-auth/src/routes/login/page-tsx.txt +40 -0
  86. package/src/sandbox/csr-auth/src/routes/page-tsx.txt +17 -0
  87. package/src/sandbox/csr-auth/src/routes/protected/page-tsx.txt +11 -0
package/docs/zh/guides/basic-features/css/css.mdx CHANGED
@@ -12,20 +12,20 @@ Modern.js 内置了社区流行的 CSS 预处理器，包括 Less 和 Sass。
12
12
 
13
13
  默认情况下，你不需要对 Less 和 Sass 进行任何配置。如果你有自定义 loader 配置的需求，可以通过配置 [tools.less](/configure/app/tools/less)、[tools.sass](/configure/app/tools/sass) 来进行设置。
14
14
 
15
- 你也可以在 Modern.js 中使用 Stylus，只需要安装 Rsbuild 提供的 Stylus 插件即可，使用方式请参考 [Stylus 插件](https://rsbuild.dev/zh/plugins/list/plugin-stylus)。
15
+ 你也可以在 Modern.js 中使用 Stylus，只需要安装 Rsbuild 提供的 Stylus 插件即可，使用方式请参考 [Stylus 插件](https://rsbuild.rs/zh/plugins/list/plugin-stylus)。
16
16
 
17
17
  ## 使用 PostCSS
18
18
 
19
19
  Modern.js 内置了 [PostCSS](https://postcss.org/) 来转换 CSS 代码。
20
20
 
21
- 请阅读 [Rsbuild - 使用 PostCSS](https://rsbuild.dev/zh/guide/basic/css-usage#%E4%BD%BF%E7%94%A8-postcss) 了解更多用法。
21
+ 请阅读 [Rsbuild - 使用 PostCSS](https://rsbuild.rs/zh/guide/basic/css-usage#%E4%BD%BF%E7%94%A8-postcss) 了解更多用法。
22
22
 
23
23
  ## 使用 Lightning CSS
24
24
 
25
25
  Modern.js 支持使用 [Lightning CSS](https://lightningcss.dev/) 来转换 CSS 代码，可以通过配置 [tools.lightningcssLoader](/configure/app/tools/lightningcss-loader) 来开启此功能。
26
26
 
27
- 请阅读 [Rsbuild - 使用 Lightning CSS](https://rsbuild.dev/zh/guide/basic/css-usage#lightning-css) 了解更多用法。
27
+ 请阅读 [Rsbuild - 使用 Lightning CSS](https://rsbuild.rs/zh/guide/basic/css-usage#lightning-css) 了解更多用法。
28
28
 
29
29
  ## 使用 Uno CSS
30
30
 
31
- 请阅读 [Rsbuild - 使用 UnoCSS](https://rsbuild.dev/zh/guide/basic/unocss) 了解更多用法。
31
+ 请阅读 [Rsbuild - 使用 UnoCSS](https://rsbuild.rs/zh/guide/basic/unocss) 了解更多用法。
package/docs/zh/guides/basic-features/debug/rsdoctor.mdx CHANGED
@@ -54,4 +54,4 @@ RSDOCTOR=true npm run build
54
54
 
55
55
  ## 相关文档
56
56
 
57
- 更多内容请查阅 [Rsdoctor 官网文档](https://rsdoctor.dev/)。
57
+ 更多内容请查阅 [Rsdoctor 官网文档](https://rsdoctor.rs/)。
package/docs/zh/guides/basic-features/static-assets.mdx CHANGED
@@ -146,7 +146,7 @@ console.log(myFile); // "/static/myFile.6c12aba3.pdf"
146
146
 
147
147
  关于以上配置的更多介绍，请参考：
148
148
 
149
- - [Rspack 文档 - Asset modules](https://www.rspack.dev/guide/asset-module.html#asset-modules)
149
+ - [Rspack 文档 - Asset modules](https://rspack.rs/guide/asset-module.html#asset-modules)
150
150
  - [webpack 文档 - Asset modules](https://webpack.js.org/guides/asset-modules/)
151
151
 
152
152
  ## 图片格式
@@ -158,4 +158,4 @@ console.log(myFile); // "/static/myFile.6c12aba3.pdf"
158
158
  | PNG | 无损压缩，不会丢失图片细节，不失真，支持半透明 | 不适合色表复杂的图片 | 适合颜色数量少，边界层次分明的图片，适合用在 logo、icon、透明图等场景 |
159
159
  | JPG | 颜色丰富 | 有损压缩，会导致图片失真，不支持透明度 | 适合颜色数量多，颜色带有渐变、过度复杂的图片，适合用在人像照片、风景图等场景 |
160
160
  | WebP | 同时支持有损压缩与无损压缩，支持透明度，体积比 PNG 和 JPG 小很多 | iOS 兼容性不好 | 几乎任何场景的像素图片，支持 WebP 的宿主环境，都应该首选 WebP 图片格式 |
161
- | SVG | 无损格式，不失真，支持透明度 | 不适合复杂图形 | 适合矢量图，适合用于 icon |
161
+ | SVG | 无损格式，不失真，支持透明度 | 不适合复杂图形 | 适合矢量图，适合用于 icon |
package/docs/zh/guides/concept/builder.mdx CHANGED
@@ -4,7 +4,7 @@ sidebar_position: 2
4
4
 
5
5
  # 构建工具
6
6
 
7
- Modern.js 构建是基于 [Rsbuild](https://rsbuild.dev/) 实现的，并支持在 Webpack 和 Rspack 两种打包工具间无缝切换。
7
+ Modern.js 构建是基于 [Rsbuild](https://rsbuild.rs/) 实现的，并支持在 Webpack 和 Rspack 两种打包工具间无缝切换。
8
8
 
9
9
  :::tip 什么是 Rsbuild
10
10
  Rsbuild 是基于 Rspack 的构建工具，是一个增强版的 Rspack CLI，更易用、开箱即用。
@@ -25,7 +25,7 @@ Rsbuild 是基于 Rspack 的构建工具，是一个增强版的 Rspack CLI，
25
25
 
26
26
  ## 构建文档
27
27
 
28
- Rsbuild 的文档地址为：https://rsbuild.dev/
28
+ Rsbuild 的文档地址为：https://rsbuild.rs/
29
29
 
30
30
  在该文档中，你可以了解到 Rsbuild 的详细介绍，同时也可以找到各个构建能力的完整使用指南。
31
31
 
@@ -42,4 +42,4 @@ Rsbuild 的文档地址为：https://rsbuild.dev/
42
42
 
43
43
  Rsbuild 提供了丰富的构建能力，包括 JavaScript 编译、CSS 编译、静态资源处理、代码热更新、代码压缩、TS 类型检查等几十种能力。
44
44
 
45
- 我们推荐你阅读 [「Rsbuild - 功能导航」](https://rsbuild.dev/zh/guide/start/features) 来了解 Rsbuild 提供的所有构建能力。
45
+ 我们推荐你阅读 [「Rsbuild - 功能导航」](https://rsbuild.rs/zh/guide/start/features) 来了解 Rsbuild 提供的所有构建能力。
package/docs/zh/guides/concept/entries.mdx CHANGED
@@ -280,7 +280,7 @@ export default defineConfig({
280
280
 
281
281
  4. **单入口应用是否存在输出多个 HTML 文件的例外情况？**
282
282
 
283
- 你可以自行配置 [html-rspack-plugin](https://rspack.dev/zh/plugins/rspack/html-rspack-plugin#%E7%94%9F%E6%88%90%E5%A4%9A%E4%B8%AA-html-%E6%96%87%E4%BB%B6) 为每个入口生成多个 HTML 产物，或使多个入口共用一个 HTML 产物。
283
+ 你可以自行配置 [html-rspack-plugin](https://rspack.rs/zh/plugins/rspack/html-rspack-plugin#%E7%94%9F%E6%88%90%E5%A4%9A%E4%B8%AA-html-%E6%96%87%E4%BB%B6) 为每个入口生成多个 HTML 产物，或使多个入口共用一个 HTML 产物。
284
284
 
285
285
  5. **什么叫多页应用（Multi-Page Application）？**
286
286
 
package/docs/zh/guides/get-started/tech-stack.mdx CHANGED
@@ -12,7 +12,7 @@ Modern.js 框架默认集成了一些社区中流行的库和开发工具。
12
12
 
13
13
  Modern.js 使用 [React 18](https://react.dev/) 来构建用户界面，同时也兼容 React 17。
14
14
 
15
- Modern.js 底层的 Rsbuild 支持构建 Vue 应用，如果你需要使用 Vue，可以参考 [Rsbuild - Vue](https://rsbuild.dev/zh/guide/framework/vue)。
15
+ Modern.js 底层的 Rsbuild 支持构建 Vue 应用，如果你需要使用 Vue，可以参考 [Rsbuild - Vue](https://rsbuild.rs/zh/guide/framework/vue)。
16
16
 
17
17
  ## 路由
18
18
 
@@ -38,7 +38,7 @@ Modern.js 可以与社区中任意的包管理器搭配使用，比如 [npm](htt
38
38
 
39
39
  ## 打包工具
40
40
 
41
- Modern.js 使用 [Webpack 5](https://webpack.js.org/) 或 [Rspack](https://www.rspack.dev/) 来打包你的 Web 应用。
41
+ Modern.js 使用 [Webpack 5](https://webpack.js.org/) 或 [Rspack](https://rspack.rs/) 来打包你的 Web 应用。
42
42
 
43
43
  默认使用的打包工具为 Webpack 5，你可以参考 [使用 Rspack](/guides/advanced-features/rspack-start) 来切换到更快的 Rspack。
44
44
 
@@ -69,7 +69,7 @@ Modern.js 支持 [启用 Tailwind CSS](/guides/basic-features/css/tailwindcss)
69
69
  Modern.js 支持 [Sass](https://sass-lang.com/)、[Less](https://lesscss.org/) 和 [Stylus](https://stylus-lang.com/) 三种 CSS 预处理器：
70
70
 
71
71
  - 默认支持 Sass 和 Less，开箱即用。
72
- - 可选支持 Stylus，请参考 [Stylus 插件](https://rsbuild.dev/zh/plugins/list/plugin-stylus) 来使用。
72
+ - 可选支持 Stylus，请参考 [Stylus 插件](https://rsbuild.rs/zh/plugins/list/plugin-stylus) 来使用。
73
73
 
74
74
  ## CSS Modules
75
75
 
package/docs/zh/guides/troubleshooting/builder.mdx CHANGED
@@ -10,15 +10,14 @@ sidebar_position: 3
10
10
 
11
11
  ### Rsbuild FAQ
12
12
 
13
- Modern.js 内部基于 [Rsbuild](https://rsbuild.dev/) 封装了自身的构建工具，因此你可以直接参考 Rsbuild 的 FAQ 文档：
13
+ Modern.js 内部基于 [Rsbuild](https://rsbuild.rs/) 封装了自身的构建工具，因此你可以直接参考 Rsbuild 的 FAQ 文档：
14
14
 
15
- - [Rsbuild - 功能类问题](https://rsbuild.dev/zh/guide/faq/features)
16
- - [Rsbuild - 异常类问题](https://rsbuild.dev/zh/guide/faq/exceptions)
17
- - [Rsbuild - 热更新问题](https://rsbuild.dev/zh/guide/faq/hmr)
15
+ - [Rsbuild - 功能类问题](https://rsbuild.rs/zh/guide/faq/features)
16
+ - [Rsbuild - 异常类问题](https://rsbuild.rs/zh/guide/faq/exceptions)
17
+ - [Rsbuild - 热更新问题](https://rsbuild.rs/zh/guide/faq/hmr)
18
18
 
19
19
  ---
20
20
 
21
-
22
21
  ### 如何清空 webpack 编译缓存？
23
22
 
24
23
  默认情况下，Modern.js 的 webpack 编译缓存生成在 `./node_modules/.cache/webpack` 目录下。
package/docs/zh/plugin/cli-plugins/api.mdx CHANGED
@@ -17,7 +17,7 @@ import type { CliPluginFuture, AppTools } from '@modern-js/app-tools';
17
17
 
18
18
  const myCliPlugin = (): CliPluginFuture<AppTools<'shared'>> => ({
19
19
  name: '@my-org/my-plugin', // 插件名称，确保唯一性
20
- setup: (api) => {
20
+ setup: api => {
21
21
  // 在这里使用 API 注册钩子、添加命令等
22
22
  api.onBeforeBuild(() => {
23
23
  console.log('构建即将开始...');
@@ -38,30 +38,30 @@ export default myCliPlugin;
38
38
 
39
39
  - **返回值：** `AppContext` 对象，包含以下字段：
40
40
 
41
- | 字段名 | 类型 | 描述 | 何时可用 |
42
- | -------------------- | -------------------- | --------------------------------------------------------------------- | -------------------------------------- |
43
- | `command` | `string` | 当前执行的命令 (e.g.， `dev`， `build`， `deploy`) | - |
44
- | `port` | `number` | 开发服务器端口号 | `onPrepare` 之后 |
45
- | `configFile` | `string` | 配置文件的绝对路径 | - |
46
- | `isProd` | `boolean` | 是否为生产模式 | - |
47
- | `appDirectory` | `string` | 项目根目录的绝对路径 | - |
48
- | `srcDirectory` | `string` | 项目源码目录的绝对路径 | - |
49
- | `distDirectory` | `string` | 项目产物输出目录的绝对路径 | `modifyResolvedConfig` 之后 |
50
- | `sharedDirectory` | `string` | 公共模块目录的绝对路径 | - |
51
- | `nodeModulesDirectory` | `string` | `node_modules` 目录的绝对路径 | - |
52
- | `ip` | `string` | 当前机器的 IPv4 地址 | - |
53
- | `packageName` | `string` | 项目 `package.json` 中的 `name` 字段 | - |
54
- | `plugins` | `object[]` | 当前已注册的插件列表 | - |
55
- | `entrypoints` | `object[]` | 页面入口信息 | - |
56
- | `serverRoutes` | `object[]` | 服务端路由信息 | - |
57
- | `bundlerType` | `webpack \| rspack` | 当前使用的打包工具类型 (`webpack` 或 `rspack`) | `onPrepare` 之后 |
58
- | `metaName` | `string` | 框架内部名称 | - |
59
- | `apiDirectory` | `string` | API 模块目录的绝对路径 (BFF 使用) | - |
60
- | `lambdaDirectory` | `string` | Lambda 模块目录的绝对路径 (BFF 使用) | - |
61
- | `runtimeConfigFile` | `string` | 运行时配置文件的名称 | - |
62
- | `serverConfigFile` | `string` | 服务器配置文件的名称 | - |
63
- | `checkedEntries` | `string[]` | 指定的入口信息 | - |
64
- | `apiOnly` | `boolean` | 是否为 `apiOnly` 模式 | - |
41
+ | 字段名 | 类型 | 描述 | 何时可用 |
42
+ | ---------------------- | ------------------- | -------------------------------------------------- | --------------------------- |
43
+ | `command` | `string` | 当前执行的命令 (e.g.， `dev`， `build`， `deploy`) | - |
44
+ | `port` | `number` | 开发服务器端口号 | `onPrepare` 之后 |
45
+ | `configFile` | `string` | 配置文件的绝对路径 | - |
46
+ | `isProd` | `boolean` | 是否为生产模式 | - |
47
+ | `appDirectory` | `string` | 项目根目录的绝对路径 | - |
48
+ | `srcDirectory` | `string` | 项目源码目录的绝对路径 | - |
49
+ | `distDirectory` | `string` | 项目产物输出目录的绝对路径 | `modifyResolvedConfig` 之后 |
50
+ | `sharedDirectory` | `string` | 公共模块目录的绝对路径 | - |
51
+ | `nodeModulesDirectory` | `string` | `node_modules` 目录的绝对路径 | - |
52
+ | `ip` | `string` | 当前机器的 IPv4 地址 | - |
53
+ | `packageName` | `string` | 项目 `package.json` 中的 `name` 字段 | - |
54
+ | `plugins` | `object[]` | 当前已注册的插件列表 | - |
55
+ | `entrypoints` | `object[]` | 页面入口信息 | - |
56
+ | `serverRoutes` | `object[]` | 服务端路由信息 | - |
57
+ | `bundlerType` | `webpack \| rspack` | 当前使用的打包工具类型 (`webpack` 或 `rspack`) | `onPrepare` 之后 |
58
+ | `metaName` | `string` | 框架内部名称 | - |
59
+ | `apiDirectory` | `string` | API 模块目录的绝对路径 (BFF 使用) | - |
60
+ | `lambdaDirectory` | `string` | Lambda 模块目录的绝对路径 (BFF 使用) | - |
61
+ | `runtimeConfigFile` | `string` | 运行时配置文件的名称 | - |
62
+ | `serverConfigFile` | `string` | 服务器配置文件的名称 | - |
63
+ | `checkedEntries` | `string[]` | 指定的入口信息 | - |
64
+ | `apiOnly` | `boolean` | 是否为 `apiOnly` 模式 | - |
65
65
 
66
66
  - **示例：**
67
67
 
@@ -83,17 +83,16 @@ api.onPrepare(() => {
83
83
 
84
84
  获取用户在 `modern.config.ts` 文件中定义的配置。
85
85
 
86
- - **返回值：** 用户定义的配置对象。
87
- - **示例：**
86
+ - **返回值：** 用户定义的配置对象。
87
+ - **示例：**
88
88
 
89
89
  ```typescript
90
90
  api.onPrepare(() => {
91
- const userConfig = api.getConfig();
92
- if (userConfig.output) {
93
- console.log('用户自定义了 output 配置');
94
- }
91
+ const userConfig = api.getConfig();
92
+ if (userConfig.output) {
93
+ console.log('用户自定义了 output 配置');
94
+ }
95
95
  });
96
-
97
96
  ```
98
97
 
99
98
  ---
@@ -162,7 +161,7 @@ hooks.onPrepare.call();
162
161
 
163
162
  修改 Modern.js 的初始配置。
164
163
 
165
- - **类型：** `api.config(configFn: () => UserConfig | Promise<UserConfig>)`
164
+ - **类型：** `api.config(configFn: () => UserConfig | Promise<UserConfig>)`
166
165
  - **参数：**
167
166
  - `configFn`： 一个返回配置对象或 Promise 的函数。
168
167
  - **执行阶段：** 解析完 `modern.config.ts` 中的配置之后。
@@ -190,11 +189,11 @@ api.config(() => {
190
189
 
191
190
  使用 chain API 修改 webpack 或者 Rspack 配置。
192
191
 
193
- - **类型：** `api.modifyBundlerChain(modifyFn: (chain: WebpackChain | RspackChain, utils: WebpackUtils | RspackUtils) => void | Promise<void>)`
192
+ - **类型：** `api.modifyBundlerChain(modifyFn: (chain: WebpackChain | RspackChain, utils: WebpackUtils | RspackUtils) => void | Promise<void>)`
194
193
  - **参数：**
195
194
  - `modifyFn`： 修改函数，接收 `webpack-chain` 或 `RspackChain` 实例和实用工具作为参数。
196
195
  - **执行阶段：** 在生成最终的 Webpack 或 Rspack 配置时。
197
- - **对应 Rsbuild Hook**： [modifybundlerchain](https://rsbuild.dev/zh/plugins/dev/hooks#modifybundlerchain)
196
+ - **对应 Rsbuild Hook**： [modifybundlerchain](https://rsbuild.rs/zh/plugins/dev/hooks#modifybundlerchain)
198
197
  - **示例：**
199
198
 
200
199
  ```typescript
@@ -210,32 +209,32 @@ api.modifyBundlerChain((chain, utils) => {
210
209
 
211
210
  修改 Rsbuild 的配置。
212
211
 
213
- - **类型：** `api.modifyRsbuildConfig(modifyFn: (config: RsbuildConfig, utils: RsbuildUtils) => RsbuildConfig | Promise<RsbuildConfig> | void)`
214
- - **参数：**
215
- - `modifyFn`： 修改函数，接收 Rsbuild 配置对象和实用工具作为参数，可以返回修改后的配置对象、Promise 或不返回（直接修改原对象）。
216
- - **执行阶段：** 在生成最终的 Rsbuild 配置时。
217
- - **对应 Rsbuild Hook**： [modifyRsbuildConfig](https://rsbuild.dev/zh/plugins/dev/hooks#modifyrsbuildconfig)
218
- - **示例：**
212
+ - **类型：** `api.modifyRsbuildConfig(modifyFn: (config: RsbuildConfig, utils: RsbuildUtils) => RsbuildConfig | Promise<RsbuildConfig> | void)`
213
+ - **参数：**
214
+ - `modifyFn`： 修改函数，接收 Rsbuild 配置对象和实用工具作为参数，可以返回修改后的配置对象、Promise 或不返回（直接修改原对象）。
215
+ - **执行阶段：** 在生成最终的 Rsbuild 配置时。
216
+ - **对应 Rsbuild Hook**： [modifyRsbuildConfig](https://rsbuild.rs/zh/plugins/dev/hooks#modifyrsbuildconfig)
217
+ - **示例：**
219
218
 
220
219
  ```typescript
221
220
  api.modifyRsbuildConfig((config, utils) => {
222
221
  // 添加一个自定义的 Rsbuild 插件
223
222
  config.plugins.push(myCustomRsbuildPlugin());
224
223
  });
225
-
226
224
  ```
225
+
227
226
  ---
228
227
 
229
228
  #### `api.modifyRspackConfig`
230
229
 
231
230
  修改 Rspack 的配置。(当使用 Rspack 作为打包工具时)
232
231
 
233
- - **类型：** `api.modifyRspackConfig(modifyFn: (config: RspackConfig, utils: RspackUtils) => RspackConfig | Promise<RspackConfig> | void)`
234
- - **参数：**
235
- - `modifyFn`： 修改函数，接收 Rspack 配置对象和实用工具作为参数，可以返回修改后的配置对象、Promise 或不返回（直接修改原对象）。
236
- - **执行阶段：** 在生成最终的 Rspack 配置时。
237
- - **对应 Rsbuild Hook**： [modifyRspackConfig](https://rsbuild.dev/zh/plugins/dev/hooks#modifyrspackconfig)
238
- - **示例：**
232
+ - **类型：** `api.modifyRspackConfig(modifyFn: (config: RspackConfig, utils: RspackUtils) => RspackConfig | Promise<RspackConfig> | void)`
233
+ - **参数：**
234
+ - `modifyFn`： 修改函数，接收 Rspack 配置对象和实用工具作为参数，可以返回修改后的配置对象、Promise 或不返回（直接修改原对象）。
235
+ - **执行阶段：** 在生成最终的 Rspack 配置时。
236
+ - **对应 Rsbuild Hook**： [modifyRspackConfig](https://rsbuild.rs/zh/plugins/dev/hooks#modifyrspackconfig)
237
+ - **示例：**
239
238
 
240
239
  ```typescript
241
240
  api.modifyRspackConfig((config， utils) => {
@@ -252,7 +251,7 @@ api.modifyRspackConfig((config， utils) => {
252
251
 
253
252
  使用 [webpack-chain](https://github.com/neutrinojs/webpack-chain) 修改 Webpack 配置。(当使用 Webpack 作为打包工具时)
254
253
 
255
- - **类型：** `api.modifyWebpackChain(modifyFn: (chain: WebpackChain, utils: WebpackUtils) => void | Promise<void>)`
254
+ - **类型：** `api.modifyWebpackChain(modifyFn: (chain: WebpackChain, utils: WebpackUtils) => void | Promise<void>)`
256
255
  - **参数：**
257
256
  - `modifyFn`： 修改函数，接收 `webpack-chain` 实例和实用工具作为参数。
258
257
  - **执行阶段：** 在生成最终的 Webpack 配置时。
@@ -275,39 +274,38 @@ api.modifyWebpackChain((chain, utils) => {
275
274
 
276
275
  直接修改 Webpack 配置对象。(当使用 Webpack 作为打包工具时)
277
276
 
278
- - **类型：** `api.modifyWebpackConfig(modifyFn: (config: WebpackConfig, utils: WebpackUtils) => WebpackConfig | Promise<WebpackConfig> | void)`
279
- - **参数：**
280
- - `modifyFn`： 修改函数，接收 Webpack 配置对象和实用工具作为参数，可以返回修改后的配置对象、Promise 或不返回（直接修改原对象）。
281
- - **执行阶段：** 在生成最终的 Webpack 配置时。
282
- - **示例：**
277
+ - **类型：** `api.modifyWebpackConfig(modifyFn: (config: WebpackConfig, utils: WebpackUtils) => WebpackConfig | Promise<WebpackConfig> | void)`
278
+ - **参数：**
279
+ - `modifyFn`： 修改函数，接收 Webpack 配置对象和实用工具作为参数，可以返回修改后的配置对象、Promise 或不返回（直接修改原对象）。
280
+ - **执行阶段：** 在生成最终的 Webpack 配置时。
281
+ - **示例：**
283
282
 
284
283
  ```typescript
285
284
  api.modifyWebpackConfig((config, utils) => {
286
285
  // 禁用 source map
287
286
  config.devtool = false;
288
287
  });
289
-
290
288
  ```
291
289
 
292
290
  **构建配置修改顺序**
293
291
 
294
- - **使用 Rspack 构建**：
295
- ```
296
- modifyRsbuildConfig
297
- modifyBundlerChain
298
- tools.bundlerChain
299
- modifyRspackConfig
300
- tools.rspack
301
- ```
302
- - **使用 Webpack 构建**：
303
- ```
304
- modifyBundlerChain
305
- tools.bundlerChain
306
- modifyWebpackChain
307
- tools.webpackChain
308
- modifyWebpackConfig
309
- tools.webpack
310
- ```
292
+ - **使用 Rspack 构建**：
293
+ ```
294
+ modifyRsbuildConfig
295
+ modifyBundlerChain
296
+ tools.bundlerChain
297
+ modifyRspackConfig
298
+ tools.rspack
299
+ ```
300
+ - **使用 Webpack 构建**：
301
+ ```
302
+ modifyBundlerChain
303
+ tools.bundlerChain
304
+ modifyWebpackChain
305
+ tools.webpackChain
306
+ modifyWebpackConfig
307
+ tools.webpack
308
+ ```
311
309
 
312
310
  ---
313
311
 
@@ -352,7 +350,7 @@ api.modifyServerRoutes(routes => {
352
350
  api.modifyHtmlPartials(({ entrypoint, partials }) => {
353
351
  // 在所有页面的 <head> 标签中添加一个 meta 标签
354
352
  if (partials.head && partials.head.append) {
355
- partials.head.append(`<meta name="my-custom-meta" content="value">`);
353
+ partials.head.append(`<meta name="my-custom-meta" content="value">`);
356
354
  }
357
355
  });
358
356
  ```
@@ -460,84 +458,88 @@ api.onFileChanged(({ filename, eventType }) => {
460
458
  - **参数：**
461
459
  - `buildFn`： 构建前执行的函数，无参数，可异步。
462
460
  - **执行阶段：** 在执行构建流程之前。
463
- - **对应 Rsbuild Hook**： [onBeforeBuild](https://rsbuild.dev/zh/plugins/dev/hooks#onbeforebuild)
461
+ - **对应 Rsbuild Hook**： [onBeforeBuild](https://rsbuild.rs/zh/plugins/dev/hooks#onbeforebuild)
464
462
  - **示例：**
465
463
 
466
464
  ```typescript
467
- api.onBeforeBuild(()=>{
468
- // 构建前做一些环境检查
469
- })
465
+ api.onBeforeBuild(() => {
466
+ // 构建前做一些环境检查
467
+ });
470
468
  ```
469
+
471
470
  ---
472
471
 
473
472
  #### `api.onAfterBuild`
474
473
 
475
474
  在构建完成后添加额外的逻辑。
476
475
 
477
- - **类型：** `api.onAfterBuild(buildFn: () => void | Promise<void>)`
478
- - **参数：**
479
- - `buildFn`： 构建后执行的函数，无参数，可异步。
480
- - **执行阶段：** 在执行构建流程之后。
481
- - **对应 Rsbuild Hook**： [onAfterBuild](https://rsbuild.dev/zh/plugins/dev/hooks#onafterbuild)
482
- - **示例：**
476
+ - **类型：** `api.onAfterBuild(buildFn: () => void | Promise<void>)`
477
+ - **参数：**
478
+ - `buildFn`： 构建后执行的函数，无参数，可异步。
479
+ - **执行阶段：** 在执行构建流程之后。
480
+ - **对应 Rsbuild Hook**： [onAfterBuild](https://rsbuild.rs/zh/plugins/dev/hooks#onafterbuild)
481
+ - **示例：**
483
482
 
484
483
  ```typescript
485
- api.onAfterBuild(()=>{
486
- // 构建后上传sourceMap
487
- })
484
+ api.onAfterBuild(() => {
485
+ // 构建后上传sourceMap
486
+ });
488
487
  ```
489
488
 
490
489
  ---
491
490
 
492
491
  #### `api.onDevCompileDone`
492
+
493
493
  在开发服务器编译完成后添加额外的逻辑。
494
494
 
495
- - **类型：** `api.onDevCompileDone(compileFn: () => void | Promise<void>)`
496
- - **参数：**
497
- - `compileFn`： 编译完成后执行的函数。
498
- - **执行阶段：** 开发服务器启动，且首次编译完成后。
499
- - **对应 Rsbuild Hook**： [onDevCompileDone](https://rsbuild.dev/zh/plugins/dev/hooks#ondevcompiledone)
500
- - **示例：**
495
+ - **类型：** `api.onDevCompileDone(compileFn: () => void | Promise<void>)`
496
+ - **参数：**
497
+ - `compileFn`： 编译完成后执行的函数。
498
+ - **执行阶段：** 开发服务器启动，且首次编译完成后。
499
+ - **对应 Rsbuild Hook**： [onDevCompileDone](https://rsbuild.rs/zh/plugins/dev/hooks#ondevcompiledone)
500
+ - **示例：**
501
501
 
502
502
  ```typescript
503
503
  api.onDevCompileDone(() => {
504
- // 首次编译完成，打开浏览器
504
+ // 首次编译完成，打开浏览器
505
505
  });
506
506
  ```
507
+
507
508
  ---
508
509
 
509
510
  #### `api.onBeforeCreateCompiler`
510
511
 
511
512
  在创建编译器实例之前添加额外的逻辑。
512
513
 
513
- - **类型：** `api.onBeforeCreateCompiler(createFn: () => void | Promise<void>)`
514
- - **参数：**
515
- - `createFn`： 创建前执行的函数，无参数，可异步。
516
- - **执行阶段：** 在创建 Webpack 或 Rspack 编译器实例之前。
517
- - **对应 Rsbuild Hook**： [onBeforeCreateCompiler](https://rsbuild.dev/zh/plugins/dev/hooks#onbeforecreatecompiler)
518
- - **示例：**
514
+ - **类型：** `api.onBeforeCreateCompiler(createFn: () => void | Promise<void>)`
515
+ - **参数：**
516
+ - `createFn`： 创建前执行的函数，无参数，可异步。
517
+ - **执行阶段：** 在创建 Webpack 或 Rspack 编译器实例之前。
518
+ - **对应 Rsbuild Hook**： [onBeforeCreateCompiler](https://rsbuild.rs/zh/plugins/dev/hooks#onbeforecreatecompiler)
519
+ - **示例：**
519
520
 
520
521
  ```typescript
521
522
  api.onBeforeCreateCompiler(() => {
522
- // 可以获取 compiler 相关配置
523
+ // 可以获取 compiler 相关配置
523
524
  });
524
525
  ```
525
526
 
526
527
  ---
527
528
 
528
529
  #### `api.onAfterCreateCompiler`
530
+
529
531
  在创建编译器实例之后添加额外的逻辑。
530
532
 
531
- - **类型：** `api.onAfterCreateCompiler(createFn: () => void | Promise<void>)`
532
- - **参数：**
533
- - `createFn`： 创建后执行的函数，无参数，可异步。
534
- - **执行阶段：** 在创建 Webpack 或 Rspack 编译器实例之后。
535
- - **对应 Rsbuild Hook**： [onAfterCreateCompiler](https://rsbuild.dev/zh/plugins/dev/hooks#onaftercreatecompiler)
536
- - **示例：**
533
+ - **类型：** `api.onAfterCreateCompiler(createFn: () => void | Promise<void>)`
534
+ - **参数：**
535
+ - `createFn`： 创建后执行的函数，无参数，可异步。
536
+ - **执行阶段：** 在创建 Webpack 或 Rspack 编译器实例之后。
537
+ - **对应 Rsbuild Hook**： [onAfterCreateCompiler](https://rsbuild.rs/zh/plugins/dev/hooks#onaftercreatecompiler)
538
+ - **示例：**
537
539
 
538
540
  ```typescript
539
541
  api.onAfterCreateCompiler(() => {
540
- // 可以获取 compiler 实例
542
+ // 可以获取 compiler 实例
541
543
  });
542
544
  ```
543
545
 
@@ -568,15 +570,15 @@ api.onBeforeDev(async () => {
568
570
 
569
571
  - **类型：** `api.onAfterDev(devFn: () => void | Promise<void>)`
570
572
  - **参数：**
571
- - `devFn`： 开发服务器启动后执行的函数。
573
+ - `devFn`： 开发服务器启动后执行的函数。
572
574
  - **执行阶段：** 开发服务器成功启动后。
573
- - **对应 Rsbuild Hook**： [onAfterStartDevServer](https://rsbuild.dev/zh/plugins/dev/hooks#onafterstartdevserver)
575
+ - **对应 Rsbuild Hook**： [onAfterStartDevServer](https://rsbuild.rs/zh/plugins/dev/hooks#onafterstartdevserver)
574
576
  - **示例：**
575
577
 
576
578
  ```typescript
577
- api.onAfterDev(()=>{
578
- // 上报 dev 相关信息
579
- })
579
+ api.onAfterDev(() => {
580
+ // 上报 dev 相关信息
581
+ });
580
582
  ```
581
583
 
582
584
  ---
@@ -604,20 +606,20 @@ api.onBeforeExit(async () => {
604
606
 
605
607
  在打印成功信息前添加额外的逻辑。
606
608
 
607
- - **类型：** `api.onBeforePrintInstructions(printFn: ({instructions: string}) => {instructions: string} | Promise<{instructions: string}>)`
608
- - **参数：**
609
- - `printFn`： 修改打印信息的函数， 返回修改后的信息。
610
- - **执行阶段：** 打印成功信息前。
611
- - **示例：**
609
+ - **类型：** `api.onBeforePrintInstructions(printFn: ({instructions: string}) => {instructions: string} | Promise<{instructions: string}>)`
610
+ - **参数：**
611
+ - `printFn`： 修改打印信息的函数， 返回修改后的信息。
612
+ - **执行阶段：** 打印成功信息前。
613
+ - **示例：**
612
614
 
613
615
  ```typescript
614
616
  api.onBeforePrintInstructions(({ instructions }) => {
615
617
  // do something
616
- return { instructions }
618
+ return { instructions };
617
619
  });
618
620
  ```
619
621
 
620
622
  ## 其他说明
621
623
 
622
- - 可以参考 [CLI 插件生命周期](./life-cycle.mdx) 了解插件钩子的执行顺序。
623
- - 可以参考 [CLI 插件迁移指南](./migration.mdx) 了解如何从旧版插件迁移到新版。
624
+ - 可以参考 [CLI 插件生命周期](./life-cycle.mdx) 了解插件钩子的执行顺序。
625
+ - 可以参考 [CLI 插件迁移指南](./migration.mdx) 了解如何从旧版插件迁移到新版。
package/docs/zh/plugin/introduction.mdx CHANGED
@@ -19,16 +19,17 @@ Modern.js 提供了一套强大的插件体系，允许开发者通过编写插
19
19
  Modern.js 提供了两种主要的插件类型：Modern.js 框架插件和 Rsbuild 构建插件。选择哪种插件取决于你的具体需求：
20
20
 
21
21
  - **Rsbuild 构建插件：** 如果你的需求与构建过程密切相关，特别是涉及到 Webpack 或 Rspack 配置的修改，那么你应该选择 Rsbuild 插件。例如：
22
- - 修改 Webpack/Rspack 的 `loader` 或 `plugin` 配置。
23
- - 处理新的文件类型。
24
- - 修改或编译文件内容。
25
- - 对构建产物进行优化或处理。
22
+
23
+ - 修改 Webpack/Rspack 的 `loader` 或 `plugin` 配置。
24
+ - 处理新的文件类型。
25
+ - 修改或编译文件内容。
26
+ - 对构建产物进行优化或处理。
26
27
 
27
28
  - **Modern.js 框架插件：** 如果你的需求与 Modern.js 框架本身的功能扩展、运行时行为或服务端逻辑相关，那么你应该选择 Modern.js 插件。例如：
28
- - 添加自定义的命令行命令。
29
- - 修改应用的路由配置。
30
- - 定制化应用的渲染过程（如 SSR）。
31
- - 添加服务端中间件或处理函数。
29
+ - 添加自定义的命令行命令。
30
+ - 修改应用的路由配置。
31
+ - 定制化应用的渲染过程（如 SSR）。
32
+ - 添加服务端中间件或处理函数。
32
33
 
33
34
  简单来说，需要修改 Webpack/Rspack 配置时，使用 Rsbuild 插件；其他与框架相关的功能扩展，使用 Modern.js 插件。
34
35
 
@@ -69,13 +70,14 @@ export default defineRuntimeConfig({
69
70
  });
70
71
  ```
71
72
 
73
+ {/* prettier-ignore */}
72
74
  {/* #### Server 插件
73
75
 
74
76
  Server 插件用于在应用接受请求时提供额外功能，例如添加中间件、修改请求响应等。
75
77
 
76
78
  Server 插件通过 `server/modern.server.ts` 中的 `plugins` 字段进行配置。
77
79
 
78
- ```ts title="src/modern.server.ts"
80
+ ````ts title="src/modern.server.ts"
79
81
  import { defineConfig } from '@modern-js/app-tools/server';
80
82
  import bffPlugin from '@modern-js/plugin-bff/server';
81
83
 
@@ -106,13 +108,13 @@ Rsbuild 是 Modern.js 底层的构建工具，通过添加 Rsbuild 插件可修
106
108
  你可以在 `modern.config.ts` 中通过 `builderPlugins` 选项注册 Rsbuild 插件，详见 [builderPlugins 构建插件](/configure/app/builder-plugins.html)。
107
109
 
108
110
  :::tip
109
- Modern.js 从 `MAJOR_VERSION.46.0` 起，底层构建工具升级为 [Rsbuild](https://rsbuild.dev/)。
111
+ Modern.js 从 `MAJOR_VERSION.46.0` 起，底层构建工具升级为 [Rsbuild](https://rsbuild.rs/)。
110
112
 
111
113
  如果你的当前版本低于 MAJOR_VERSION.46.0，可通过执行 `npx modern upgrade` 进行升级。
112
114
  :::
113
115
 
114
116
  :::info
115
- 可以阅读 [Rsbuild 官网 - 插件](https://rsbuild.dev/plugins/list/index) 了解更多 Rsbuild 插件体系内容。
117
+ 可以阅读 [Rsbuild 官网 - 插件](https://rsbuild.rs/plugins/list/index) 了解更多 Rsbuild 插件体系内容。
116
118
  :::
117
119
 
118
120
  ### 官方插件
@@ -123,10 +125,10 @@ Modern.js 从 `MAJOR_VERSION.46.0` 起，底层构建工具升级为 [Rsbuild](h
123
125
 
124
126
  | 插件 | 介绍 | Modern.js 链接 |
125
127
  | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
126
- | [React 插件](https://rsbuild.dev/zh/plugins/list/plugin-react) | 提供对 React 的支持 | - |
127
- | [SVGR 插件](https://rsbuild.dev/zh/plugins/list/plugin-svgr) | 支持将 SVG 图片转换为一个 React 组件 | [output.disableSvgr](/configure/app/output/disable-svgr)<br />[output.svgDefaultExport](/configure/app/output/svg-default-export) |
128
+ | [React 插件](https://rsbuild.rs/zh/plugins/list/plugin-react) | 提供对 React 的支持 | - |
129
+ | [SVGR 插件](https://rsbuild.rs/zh/plugins/list/plugin-svgr) | 支持将 SVG 图片转换为一个 React 组件 | [output.disableSvgr](/configure/app/output/disable-svgr)<br />[output.svgDefaultExport](/configure/app/output/svg-default-export) |
128
130
  | [Styled Components 插件](https://github.com/rspack-contrib/rsbuild-plugin-styled-components) | 提供对 styled-components 的编译时支持 | [tools.styledComponents](/configure/app/tools/styled-components.html) |
129
- | [Assets Retry 插件](https://rsbuild.dev/zh/plugins/list/plugin-assets-retry) | 用于在静态资源加载失败时自动发起重试请求 | [output.assetsRetry](/configure/app/output/assets-retry.html) |
131
+ | [Assets Retry 插件](https://rsbuild.rs/zh/plugins/list/plugin-assets-retry) | 用于在静态资源加载失败时自动发起重试请求 | [output.assetsRetry](/configure/app/output/assets-retry.html) |
130
132
  | [Type Check 插件](https://github.com/rspack-contrib/rsbuild-plugin-type-check) | 用于在单独的进程中运行 TypeScript 类型检查 | [output.disableTsChecker](/configure/app/output/disable-ts-checker.html)<br />[tools.tsChecker](/configure/app/tools/ts-checker.html) |
131
133
  | [Node Polyfill 插件](https://github.com/rspack-contrib/rsbuild-plugin-node-polyfill) | 用于注入 Node 核心模块在浏览器端的 polyfills | [output.disableNodePolyfill](/configure/app/output/disable-node-polyfill.html) |
132
134
  | [Source Build 插件](https://github.com/rspack-contrib/rsbuild-plugin-source-build) | 用于 monorepo 场景，支持引用其他子目录的源代码，并完成构建和热更新 | [experiments.sourceBuild](/configure/app/experiments/source-build.html) |
@@ -142,9 +144,10 @@ Modern.js 从 `MAJOR_VERSION.46.0` 起，底层构建工具升级为 [Rsbuild](h
142
144
  以下是未在 Modern.js 中内置的 Rsbuild 官方插件：
143
145
 
144
146
  - [Image Compress 插件](https://github.com/rspack-contrib/rsbuild-plugin-image-compress)：将项目中用到的图片资源进行压缩处理。
145
- - [Stylus 插件](https://rsbuild.dev/zh/plugins/list/plugin-stylus)：使用 Stylus 作为 CSS 预处理器。
147
+ - [Stylus 插件](https://rsbuild.rs/zh/plugins/list/plugin-stylus)：使用 Stylus 作为 CSS 预处理器。
146
148
  - [UMD 插件](https://github.com/rspack-contrib/rsbuild-plugin-umd)：用于构建 UMD 格式的产物。
147
149
 
148
150
  import OtherPlugins from '@site-docs/components/other-plugins.mdx';
149
151
 
150
152
  <OtherPlugins />
153
+ ````