@modern-js/main-doc 2.45.0 → 2.46.1

package/docs/en/guides/advanced-features/rspack-start.mdx

@@ -25,27 +25,18 @@ After the project is created, you can experience the project by running `pnpm ru
 :::tip
 When using Rspack as the bundler, the following Features are temporarily unavailable as some of the capabilities are still under development and we will provide support in the future.
 
-- Storybook Devtool
 - The usage of [useLoader](/guides/basic-features/data/data-fetch.html) in Client Side Rendering
 
 :::
 
 ## Enable Rspack build
 
-You can enable Rspack build by running `pnpm run new`:
-
-```bash
-$ pnpm run new
-? Please select the operation you want: Enable features
-? Please select the feature name: Enable Rspack Build
-```
-
-After executing the command, enable the Rspack build in `modern.config.ts`:
+Since Modern.js MAJOR_VERSION.46.0, you can enable Rspack build by add the following configuration in `modern.config.ts`:
 
 ```diff title=modern.config.ts
 import { appTools, defineConfig } from '@modern-js/app-tools';
 
-+ export default defineConfig<'rspack'>({
+export default defineConfig({
   plugins: [
     appTools({
 +     bundler: 'experimental-rspack',
@@ -54,6 +45,10 @@ import { appTools, defineConfig } from '@modern-js/app-tools';
 });
 ```
 
+:::tip
+If your current version is lower than MAJOR_VERSION.46.0, you can upgrade by executing `npx modern upgrade`.
+:::
+
 import RspackPrecautions from '@modern-js/builder-doc/docs/en/shared/rspackPrecautions.md';
 
 <RspackPrecautions />
@@ -62,15 +57,69 @@ import RspackPrecautions from '@modern-js/builder-doc/docs/en/shared/rspackPreca
 
 After enabling Rspack building capability, further configuration migration is needed by referring to the [Configuration Differences](https://modernjs.dev/builder/en/guide/advanced/rspack-start.html#migrating-from-webpack-to-rspack).
 
+In Modern.js, the [tools.webpack](/configure/app/tools/webpack) and [tools.webpackChain](/configure/app/tools/webpack-chain) configurations only take effect in webpack mode, after turning on the Rspack build, you can modify it to [tools.rspack](/configure/app/tools/rspack) and [tools.bundlerChain](/configure/app/tools/bundler-chain).
+
+```diff
+export default {
+  tools: {
+-   webppack: (config, { env }) => {
++   rspack: (config, { env }) => {
+      if (env === 'development') {
+        config.devtool = 'cheap-module-eval-source-map';
+      }
+      return config;
+    },
+-   webpackChain: (chain, { env }) => {
++   bundlerChain: (chain, { env }) => {
+      if (env === 'development') {
+        chain.devtool('cheap-module-eval-source-map');
+      }
+    },
+  },
+};
+```
+
+:::tip
+After turning on the Rspack build capability, there are currently a small number of configurations that are not supported in Rspack, such as [source.moduleScopes](/configure/app/source/module-scopes), [security.sri](/configure/app/security/sri) etc.
+
+For unsupported configurations, we have marked `Bundler: only support webpack` or `Bundler: only support Rspack` in the document. Please refer to the specific configuration introduction.
+:::
+
+## Modify transpile configuration
+
+Modern.js uses Rspack [builtin:swc-loader](https://www.rspack.dev/guide/builtin-swc-loader.html) for code translation in Rspack mode.
+
+Modern.js has provided a more convenient configuration for the common configuration of `builtin:swc-loader`, such as: configuring the component library to import it on demand through [source.transformImport](/configure/app/source/transform-import). If you have custom configuration requirements for `builtin:swc-loader`, you can refer to the following code:
+
+```ts
+export default {
+  tools: {
+    bundlerChain: (chain, { CHAIN_ID }) => {
+      chain.module
+        .rule(CHAIN_ID.RULE.JS)
+        .use(CHAIN_ID.USE.SWC)
+        .tap(options => {
+          options.xxx = '';
+          return options;
+        });
+    },
+  }
+};
+```
+
+:::tip
+When Rspack build is enabled, `babel-loader` is not enabled by default. If you need to add some babel plugins, you can configure it through [tools.babel](/configure/app/tools/babel). This will generate additional compilation overhead and slow down the Rspack build speed to a certain extent.
+:::
+
 ## The relationship between Rspack and Modern.js versions
 
 Usually, the latest version of Rspack will be integrated into Modern.js. You can update the Modern.js-related dependencies and built-in Rspack to the latest version by using `npx modern upgrade` in your project.
 
 However, Modern.js uses a locked version dependency method (non-automatic upgrade) for Rspack. Due to differences in release cycles, the version of Rspack integrated into Modern.js may be behind the latest version of Rspack.
 
-When Rspack is enabled for building through dev / build, the current version of Rspack used in the framework will be printed automatically:
+When Rspack is enabled for building through dev / build, the current version of Rspack used in the framework will be printed automatically when [debugging mode](https://rsbuild.dev/guide/debug/debug-mode) is turned on:
 
-![rspack_version_log](https://lf3-static.bytednsdoc.com/obj/eden-cn/6221eh7uhbfvhn/modern/img_v2_dfcf051f-21db-4741-a108-d9f7a82c3abg.png)
+![rspack_version_log](https://lf3-static.bytednsdoc.com/obj/eden-cn/6221eh7uhbfvhn/modern/20240110-155444.png)
 
 ### Override the Built-in Rspack Version
 
@@ -84,7 +133,6 @@ For example, if you are using pnpm, you can update the Rspack version with `over
     "overrides": {
       "@rspack/core": "nightly",
       "@rspack/plugin-react-refresh": "nightly",
-      "@rspack/plugin-html": "nightly"
     }
   }
 }

package/docs/en/guides/advanced-features/ssr/stream.mdx

@@ -228,9 +228,21 @@ function ErrorElement() {
 }
 ```
 
+## Waiting for all content to load for spiders
+
+Streaming offers a better user experience because the user can see the content as it becomes available.
+
+However, when a spider visits your page, you might want to let all of the content load first and then produce the final HTML output instead of revealing it progressively.
+
+Modern.js uses [isbot](https://www.npmjs.com/package/isbot) to examine the user-agent of requests, determining whether they come from a crawler.
+
 :::info More
 
 1. [Deferred Data](https://reactrouter.com/en/main/guides/deferred)
 2. [New Suspense SSR Architecture in React 18](https://github.com/reactwg/react-18/discussions/37)
 
 :::
+
+import StreamSSRPerformance from '@site-docs/components/stream-ssr-performance';
+
+<StreamSSRPerformance />

package/docs/en/guides/basic-features/html.mdx

@@ -184,8 +184,6 @@ Under the application root directory, create the `config/html/` directory, which
 <!DOCTYPE html>
 <html>
   <head>
-    <%= meta %>
-    <title><%= title %></title>
     <%= topTemplate %>
     <%= headTemplate %>
     {/* webpack inject css  */}

package/docs/en/guides/get-started/glossary.mdx

@@ -46,6 +46,12 @@ import ModuleFederation from '@modern-js/builder-doc/docs/en/shared/module-feder
 
 <ModuleFederation />
 
+## Rsbuild
+
+import Rsbuild from '@modern-js/builder-doc/docs/en/shared/rsbuild.md';
+
+<Rsbuild />
+
 ## Rspack
 
 import Rspack from '@modern-js/builder-doc/docs/en/shared/rspack.md';

package/docs/zh/guides/advanced-features/rspack-start.mdx

@@ -25,27 +25,18 @@ import InitRspackApp from '@site-docs/components/init-rspack-app';
 :::tip
 在使用 Rspack 作为打包工具时，由于部分能力尚在开发中，以下 features 暂时无法使用，我们将在未来提供支持：
 
-- Storybook 调试
 - 客户端渲染（CSR）使用 [useLoader](/guides/basic-features/data/data-fetch.html)
 
 :::
 
 ## 开启 Rspack 构建
 
-在一个已有的 Modern.js 项目中，你可以通过执行 `pnpm run new` 来启用 Rspack 构建：
-
-```bash
-$ pnpm run new
-? 请选择你想要的操作 启用可选功能
-? 请选择功能名称 启用「Rspack 构建」
-```
-
-执行以上命令后，在 `modern.config.ts` 中添加 Rspack 相关配置即可：
+从 Modern.js MAJOR_VERSION.46.0 版本起，在一个已有的 Modern.js 项目中，你仅需在 `modern.config.ts` 中添加以下配置，即可启用 Rspack 构建：
 
 ```diff title=modern.config.ts
 import { appTools, defineConfig } from '@modern-js/app-tools';
 
-+ export default defineConfig<'rspack'>({
+export default defineConfig({
   plugins: [
     appTools({
 +     bundler: 'experimental-rspack',
@@ -54,13 +45,70 @@ import { appTools, defineConfig } from '@modern-js/app-tools';
 });
 ```
 
+:::tip
+如果你当前版本低于 MAJOR_VERSION.46.0, 可通过执行 `npx modern upgrade` 进行升级。
+:::
+
 import RspackPrecautions from '@modern-js/builder-doc/docs/zh/shared/rspackPrecautions.md';
 
 <RspackPrecautions />
 
 ## 配置迁移
 
-开启 Rspack 构建能力后，还需要参考 [配置差异](https://modernjs.dev/builder/guide/advanced/rspack-start.html#从-webpack-迁移到-rspack) 进行进一步的配置迁移。
+Modern.js 中 [tools.webpack](/configure/app/tools/webpack) 和 [tools.webpackChain](/configure/app/tools/webpack-chain) 配置仅在 webpack 模式下生效，开启 Rspack 构建能力后，可根据实际使用场景决定是否修改为 [tools.rspack](/configure/app/tools/rspack) 或 [tools.bundlerChain](/configure/app/tools/bundler-chain)。
+
+```diff
+export default {
+  tools: {
+-   webppack: (config, { env }) => {
++   rspack: (config, { env }) => {
+      if (env === 'development') {
+        config.devtool = 'cheap-module-eval-source-map';
+      }
+      return config;
+    },
+-   webpackChain: (chain, { env }) => {
++   bundlerChain: (chain, { env }) => {
+      if (env === 'development') {
+        chain.devtool('cheap-module-eval-source-map');
+      }
+    },
+  },
+};
+```
+
+
+:::tip
+开启 Rspack 构建能力后，目前有小部分配置在 Rspack 中还不支持使用，如 [source.moduleScopes](/configure/app/source/module-scopes)、[security.sri](/configure/app/security/sri) 等。
+
+对于不支持的配置，我们在文档中有标注 `打包工具： 仅支持 webpack` 或 `打包工具： 仅支持 rspack`，可参考具体配置介绍。
+:::
+
+## 修改转译配置
+
+Modern.js 在 Rspack 模式下使用 Rspack [builtin:swc-loader](https://www.rspack.dev/zh/guide/builtin-swc-loader.html) 进行代码转译。
+
+Modern.js 已对 `builtin:swc-loader` 的常见配置提供了更方便的配置方式，如：通过 [source.transformImport](/configure/app/source/transform-import) 配置组件库按需引入。如果对 `builtin:swc-loader` 有自定义配置的需求，可参考以下代码：
+
+```ts
+export default {
+  tools: {
+    bundlerChain: (chain, { CHAIN_ID }) => {
+      chain.module
+        .rule(CHAIN_ID.RULE.JS)
+        .use(CHAIN_ID.USE.SWC)
+        .tap(options => {
+          options.xxx = '';
+          return options;
+        });
+    },
+  }
+};
+```
+
+:::tip
+在启用 Rspack 构建时，babel-loader 默认不会被启用。如需添加 babel 插件，可通过 [tools.babel](/configure/app/tools/babel) 配置，此时会产生额外的编译开销，在一定程度上拖慢 Rspack 构建速度。
+:::
 
 ## Rspack 和 Modern.js 的版本关系
 
@@ -68,9 +116,9 @@ import RspackPrecautions from '@modern-js/builder-doc/docs/zh/shared/rspackPreca
 
 但 Modern.js 对于 Rspack 的依赖方式为锁版本方式(非自动升级)，由于发版周期不同步等原因，可能会出现 Modern.js 内集成的 Rspack 版本落后于 Rspack 最新版本的情况。
 
-当你执行 dev / build 命令时，Modern.js 会自动打印当前使用的 Rspack 版本：
+当你执行 dev / build 命令时，Modern.js 会在[开启调试模式时](https://rsbuild.dev/zh/guide/debug/debug-mode)自动打印当前使用的 Rspack 版本：
 
-![rspack_version_log](https://lf3-static.bytednsdoc.com/obj/eden-cn/6221eh7uhbfvhn/modern/img_v2_dfcf051f-21db-4741-a108-d9f7a82c3abg.png)
+![rspack_version_log](https://lf3-static.bytednsdoc.com/obj/eden-cn/6221eh7uhbfvhn/modern/20240110-155444.png)
 
 #### 修改内置 Rspack 版本
 
@@ -84,7 +132,6 @@ import RspackPrecautions from '@modern-js/builder-doc/docs/zh/shared/rspackPreca
     "overrides": {
       "@rspack/core": "nightly",
       "@rspack/plugin-react-refresh": "nightly",
-      "@rspack/plugin-html": "nightly"
     }
   }
 }

package/docs/zh/guides/advanced-features/ssr/stream.mdx

@@ -232,9 +232,21 @@ function ErrorElement() {
 }
 ```
 
+## 为爬虫等待所有内容加载完毕
+
+流式传输可以提高用户体验，因为当页面内容可用时，用户可以及时感知到它们。
+
+然而，当一个爬虫访问该页面时，它可能需要先加载所有内容，直接输出整个 HTML，而不是渐进式地加载它。
+
+Modern.js 使用 [isbot](https://www.npmjs.com/package/isbot) 对请求的 `uesr-agent`, 以判断请求是否来自爬虫。
+
 :::info 补充信息
 
 1. [Deferred Data](https://reactrouter.com/en/main/guides/deferred)
 2. [New Suspense SSR Architecture in React 18](https://github.com/reactwg/react-18/discussions/37)
 
 :::
+
+import StreamSSRPerformance from '@site-docs/components/stream-ssr-performance';
+
+<StreamSSRPerformance />

package/docs/zh/guides/basic-features/css-modules.mdx

@@ -6,7 +6,7 @@ sidebar_position: 14
 
 [CSS Modules](https://github.com/css-modules/css-modules) 让我们能以模块化的方式编写 CSS 代码，并且可以在 JavaScript 文件中导入和使用这些样式。使用 CSS Modules 可以自动生成唯一的类名，隔离不同模块之间的样式，避免类名冲突。
 
-Builder 默认支持使用 CSS Modules，无需添加额外的配置。我们约定使用 `[name].module.css` 文件名来启用 CSS Modules。
+Modern.js 默认支持使用 CSS Modules，无需添加额外的配置。我们约定使用 `[name].module.css` 文件名来启用 CSS Modules。
 
 以下样式文件会被视为 CSS Modules：
 

package/docs/zh/guides/basic-features/html.mdx

@@ -187,8 +187,6 @@ Modern.js 也支持通过 HTML(EJS) 语法来生成 HTML 文件。
 <!DOCTYPE html>
 <html>
   <head>
-    <%= meta %>
-    <title><%= title %></title>
     <%= topTemplate %>
     <%= headTemplate %>
     {/* webpack inject css  */}

package/docs/zh/guides/get-started/glossary.mdx

@@ -46,6 +46,12 @@ import ModuleFederation from '@modern-js/builder-doc/docs/zh/shared/module-feder
 
 <ModuleFederation />
 
+## Rsbuild
+
+import Rsbuild from '@modern-js/builder-doc/docs/zh/shared/rsbuild.md';
+
+<Rsbuild />
+
 ## Rspack
 
 import Rspack from '@modern-js/builder-doc/docs/zh/shared/rspack.md';

package/docs/zh/guides/topic-detail/generator/plugin/api/onForged.md

@@ -40,7 +40,7 @@ export interface IPluginContext {
 
 ### 文件类型
 
-生成器插件将文件类型分为撕四类：
+生成器插件将文件类型分为四类：
 
 - 文本文件
 

package/package.json

@@ -15,17 +15,17 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.45.0",
+  "version": "2.46.1",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public",
     "provenance": true
   },
   "dependencies": {
-    "@modern-js/sandpack-react": "2.45.0"
+    "@modern-js/sandpack-react": "2.46.1"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "^2.45.0"
+    "@modern-js/builder-doc": "^2.46.1"
   },
   "devDependencies": {
     "classnames": "^2",
@@ -35,12 +35,12 @@
     "ts-node": "^10.9.1",
     "typescript": "^5",
     "fs-extra": "^10",
-    "rspress": "1.8.4",
-    "@rspress/shared": "1.8.4",
+    "rspress": "1.10.0",
+    "@rspress/shared": "1.10.0",
     "@types/node": "^16",
     "@types/fs-extra": "9.0.13",
-    "@modern-js/doc-plugin-auto-sidebar": "2.45.0",
-    "@modern-js/builder-doc": "2.45.0"
+    "@modern-js/builder-doc": "2.46.1",
+    "@modern-js/doc-plugin-auto-sidebar": "2.46.1"
   },
   "scripts": {
     "dev": "rspress dev",

package/docs/en/configure/app/tools/inspector.mdx

@@ -1,9 +0,0 @@
----
-sidebar_label: inspector
----
-
-# tools.inspector
-
-import Main from '@modern-js/builder-doc/docs/en/config/tools/inspector.md';
-
-<Main />

package/docs/zh/configure/app/tools/inspector.mdx

@@ -1,9 +0,0 @@
----
-sidebar_label: inspector
----
-
-# tools.inspector
-
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/inspector.md';
-
-<Main />