@modern-js/main-doc 2.58.3 → 2.59.0

package/docs/zh/configure/app/output/ssg.mdx

@@ -4,44 +4,22 @@ title: ssg
 
 # output.ssg
 
-- **类型：** `boolean` | `object` | `function`
+- **类型：** `boolean` | `object`
 - **默认值：** `undefined`
 
-开启**自控式路由**或**约定式路由** SSG 功能的配置。
+开启应用 SSG 功能的配置
 
-:::info 开启 SSG 功能
-此配置需要在开启 SSG 功能情况下才会生效。请阅读 [静态站点生成](/guides/advanced-features/ssg) 文档了解如何开启 SSG 功能。
+:::tip 开启 SSG 功能
+此配置需要在开启 SSG 功能情况下才会生效。请阅读 [静态站点生成](/guides/basic-features/render/ssg) 文档了解如何开启 SSG 功能及使用场景。
 :::
 
-:::info 客户端路由
-相关内容可以查看[路由方案](/guides/basic-features/routes)。
-
+:::info 前置阅读
+SSG 功能使用与路由关联性较大，建议使用前先了解[路由方案](/guides/basic-features/routes)。
 :::
 
-## 示例
-
-### 单入口
-
-当该配置设置为 `true` 时，将会默认开启所有入口的 SSG 功能。
-
-对**自控式路由**而言，将会渲染入口的根路由。对**约定式路由**而言，将会渲染入口中每一条路由。
-
-例如 `src/` 目录下有以下满足**约定式路由**的文件结构：
-
-```bash
-.
-├── src
-│   └── routes
-│       ├── layout.tsx
-│       ├── page.tsx
-│       └── user
-│           ├── layout.tsx
-│           ├── page.tsx
-│           └── profile
-│               └── page.tsx
-```
+## Boolean 类型
 
-在 `modern.config.js` 中做以下设置：
+当该配置设置为 `true` 时，将会默认开启所有入口的 SSG 功能。对**自控式路由**而言，将会渲染入口的根路由。对**约定式路由**而言，将会渲染入口中每一条路由。
 
 ```js
 export default defineConfig({
@@ -51,39 +29,20 @@ export default defineConfig({
 });
 ```
 
-执行 `pnpm build` 构建应用后。`dist/` 目录将会生成三张 HTML 分别对应三条路由（不开启 SSG 时只有一张 HTML），并且所有 HTML 都已经渲染。
-
-而例如下面的**自控式路由**：
-
-import SelfRouteExample from "@site-docs/components/self-route-example";
-
-<SelfRouteExample />
-
-同样使用上面的配置，在执行 `pnpm run build` 后，只有入口路由 `/` 会生成渲染后的 HTML。
-
-### 多入口
-
 `output.ssg` 也可以按照入口配置，配置生效的规则同样由入口路由方式决定。
 
-例如以下目录结构：
+例如以下目录结构，分别存在约定式路由入口 `entryA` 和自控式路由入口 `entryB`：
 
 ```bash
-。
-├── src
-│   ├── entryA
-│   │   └── routes
-│   │       ├── layout.tsx
-│   │       ├── page.tsx
-│   │       └── user
-│   │           ├── layout.tsx
-│   │           ├── page.tsx
-│   │           └── profile
-│   │               └── page.tsx
-│   └── entryB
-│       └── App.tsx
+.
+└── src
+    ├── entryA
+    │   └── routes
+    └── entryB
+        └── App.tsx
 ```
 
-默认情况下，所有约定式路由的入口，在设置 `output.ssg` 配置为 `true` 后都会在构建阶段渲染。可以配置 `false` 来取消指定入口的的默认行为，例如取消上述 entryA 入口在构建时的渲染：
+你可以指定 `entryA` 和 `entryB` 的不同 SSG 配置：
 
 ```js
 export default defineConfig({
@@ -96,107 +55,58 @@ export default defineConfig({
 });
 ```
 
-### 配置路由
-
-上述内容中提到，**自控式路由**默认只会开启入口路由的 SSG 配置。
-
-可以在 `output.ssg` 中设置具体的路由，告知 Modern.js 开启这些客户端路由的 SSG 功能。例如上述 `src/App.tsx` 的文件内容为：
-
-
-<SelfRouteExample />
-
-在 `modern.config.js` 中这样设置后，`/about` 路由也会开启 SSG 功能：
-
-```js
-export default defineConfig({
-  output: {
-    ssg: {
-      routes: ['/', '/about'],
-    },
-  },
-});
-```
-
-Modern.js 将会自动根据入口拼接完整的 URL 并交给 SSG 插件完成渲染。
-
-也可以为具体入口或路由配置请求头，例如：
-
-```js
-export default defineConfig({
-  output: {
-    ssg: {
-      headers: {},
-      routes: [
-        '/',
-        {
-          url: '/about',
-          headers: {},
-        },
-      ],
-    },
-  },
-});
-```
-
 :::info
-路由中设置的 `headers` 会覆盖入口中设置的 `headers`。
-
+更多关于**约定式路由**和**自控式路由**在开启 SSG 后的默认行为，请阅读 [静态站点生成](/guides/basic-features/render/ssg) 。
 :::
 
-### 阻止默认行为
+## Object 类型
 
-默认情况下，**约定式路由**的路由会全部开启 SSG。Modern.js 提供了另一个字段，用来阻止默认的 SSG 行为。
+当值类型为 `Object` 时，可以配置如下属性。
 
-例如以下目录结构，`/`、`/user`、`/user/profle` 三条路由都开启 SSG：
+### 配置类型
 
-```bash
-.
-├── src
-│   └── routes
-│       ├── layout.tsx
-│       ├── page.tsx
-│       └── user
-│           ├── layout.tsx
-│           ├── page.tsx
-│           └── profile
-│               └── page.tsx
-```
-
-可以这样设置，禁用某一条客户端路由的默认行为：
+```ts
+type SSGRouteOptions = string | {
+  url: string;
+  params?: Record<string, any>[];
+  headers?: Record<string, any>;
+};
 
-```js
-export default defineConfig({
-  output: {
-    ssg: {
-      preventDefault: ['/user'],
-    },
-  },
-});
+type SSGOptions = {
+  preventDefault?: string[];
+  headers?: Record<string, any>;
+  routes?: SSGRouteOptions[];
+};
 ```
 
-### 添加动态路由参数
+### 示例
 
-部分路由可能是动态的，例如自控式路由中的 `/user/:id` 或是约定式路由中 `user/[id]/page.tsx` 文件生成的路由。
+下面的示例配置中，SSG 会渲染 `/`、`/about` 和 `/user/:id` 三条路由对应的页面。
 
-可以在 `output.ssg` 中配置具体的参数，渲染指定参数的路由，例如：
+对于 `/user/:id` 路由，`cookies` 添加到请求头中，同时会将 `params` 中的 `id` 替换为 `modernjs`。
 
-```js
+```ts title="modern.config.ts"
 export default defineConfig({
   output: {
     ssg: {
       routes: [
+        '/', 
+        '/about',         
         {
           url: '/user/:id',
-          params: [
-            {
-              id: 'modernjs',
-            },
-          ],
-        },
+          headers: {
+            cookies: "name=modernjs"
+          },
+          params: [{
+            id: 'modernjs',
+          }],
+        }
       ],
-    },
-  },
+    }
+  }
 });
 ```
 
-动态路由和 SSG 的组合，在根据 CMS 系统数据变更，实时生成静态页面时非常有用。
+:::note
+多入口的情况和单入口的配置方式一致，这里不再额外介绍。
+:::

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

@@ -23,7 +23,7 @@ const tailwind = {
 
 在使用 `tools.tailwindcss` 之前，你需要启用 Modern.js 的 Tailwind CSS 插件。
 
-请阅读[「使用 Tailwind CSS」](/guides/basic-features/css.html#使用-tailwind-css) 章节来了解开启方式。
+请阅读[「使用 Tailwind CSS」](/guides/basic-features/css/tailwindcss) 章节来了解开启方式。
 
 ### Function 类型
 

package/docs/zh/guides/advanced-features/_meta.json

@@ -7,13 +7,6 @@
     "collapsed": true
   },
   "code-split",
-  {
-    "type": "dir",
-    "name": "ssr",
-    "label": "use-ssr",
-    "collapsed": true
-  },
-  "ssg",
   "compatibility",
   "eslint",
   "low-level",
@@ -21,6 +14,5 @@
   "build-performance",
   "inline-assets",
   "optimize-bundle",
-  "using-storybook",
   "web-server"
 ]

package/docs/zh/guides/advanced-features/rsbuild-plugin.mdx

@@ -41,8 +41,8 @@ Modern.js 从 `MAJOR_VERSION.46.0` 起开始将底层的构建工具升级为 [R
 | [CSS Minimizer 插件](https://github.com/rspack-contrib/rsbuild-plugin-css-minimizer)         | 用于自定义 CSS 压缩工具，切换到 [cssnano](https://cssnano.co/) 或其他工具进行 CSS 压缩。 | [tools.minifyCss](/configure/app/tools/minify-css.html)                                                                               |
 | [Pug 插件](https://github.com/rspack-contrib/rsbuild-plugin-pug)                             | 提供对 Pug 模板引擎的支持                                                                | [tools.pug](/configure/app/tools/pug.html)                                                                                            |
 | [Rem 插件](https://github.com/rspack-contrib/rsbuild-plugin-rem)                             | 用于实现移动端页面的 rem 自适应布局                                                      | [output.convertToRem](/configure/app/output/convert-to-rem.html)                                                                      |
-| [YAML 插件](https://github.com/rspack-contrib/rsbuild-plugin-yaml)                           | 用于引用 YAML 文件，并将其转换为 JavaScript 对象                                         | [TOML 文件](/guides/basic-features/json-files.html#toml-文件)                                                                         |
-| [TOML 插件](https://github.com/rspack-contrib/rsbuild-plugin-toml)                           | 用于引用 TOML 文件，并将其转换为 JavaScript 对象                                         | [YAML 文件](/guides/basic-features/json-files.html#yaml-文件)                                                                         |
+| [YAML 插件](https://github.com/rspack-contrib/rsbuild-plugin-yaml)                           | 用于引用 YAML 文件，并将其转换为 JavaScript 对象                                         | [TOML 文件](/guides/basic-features/static-assets/json-files.html#toml-文件)                                                                         |
+| [TOML 插件](https://github.com/rspack-contrib/rsbuild-plugin-toml)                           | 用于引用 TOML 文件，并将其转换为 JavaScript 对象                                         | [YAML 文件](/guides/basic-features/static-assets/json-files.html#yaml-文件)                                                                         |
 
 ### 未内置插件
 

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

@@ -8,13 +8,13 @@ import Rspack from '@modern-js/builder-doc/docs/zh/shared/rspackTip.mdx';
 
 <Rspack />
 
-**Modern.js 提供开箱即用的 Rspack 支持**，你可以在成熟的 Webpack 和更快的 Rspack 之间进行切换。
+**Modern.js 提供开箱即用的 Rspack 支持**，你可以在成熟的 webpack 和更快的 Rspack 之间进行切换。
 
 这篇文档会向你介绍如何在 Modern.js 中开启 Rspack 构建模式。
 
 ## 初始化 Rspack 项目
 
-Modern.js 生成器会提供一个可交互的问答界面，只需将构建工具选择为 **Rspack**，即可创建一个 Rspack 项目:
+Modern.js 新项目已默认启用 Rspack 构建，只需执行 [初始化项目](/guides/get-started/quick-start.html#初始化项目)，即可创建一个 Rspack 项目:
 
 import InitRspackApp from '@site-docs/components/init-rspack-app';
 
@@ -24,7 +24,7 @@ import InitRspackApp from '@site-docs/components/init-rspack-app';
 
 ## 开启 Rspack 构建
 
-从 Modern.js MAJOR_VERSION.46.0 版本起，在一个已有的 Modern.js 项目中，你仅需在 `modern.config.ts` 中添加以下配置，即可启用 Rspack 构建：
+从 Modern.js MAJOR_VERSION.59.0 版本起，在一个已有的 Modern.js 项目中，你仅需在 `modern.config.ts` 中添加以下配置，即可启用 Rspack 构建：
 
 ```diff title=modern.config.ts
 import { appTools, defineConfig } from '@modern-js/app-tools';
@@ -32,14 +32,14 @@ import { appTools, defineConfig } from '@modern-js/app-tools';
 export default defineConfig({
   plugins: [
     appTools({
-+     bundler: 'experimental-rspack',
++     bundler: 'rspack',
     }),
   ],
 });
 ```
 
 :::tip
-如果你当前版本低于 MAJOR_VERSION.46.0, 可通过执行 `npx modern upgrade` 进行升级。
+如果你当前版本低于 MAJOR_VERSION.59.0, 可通过执行 `npx modern upgrade` 进行升级。
 :::
 
 import RspackPrecautions from '@modern-js/builder-doc/docs/zh/shared/rspackPrecautions.md';
@@ -70,13 +70,6 @@ export default {
 };
 ```
 
-
-:::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://rspack.dev/zh/guide/features/builtin-swc-loader) 进行代码转译。
@@ -105,7 +98,7 @@ export default defineConfig<'rspack'>({
 
 通常情况下，Modern.js 内会集成 Rspack 的最新版本，通过 `npx modern upgrade` 即可将当前项目中的 Modern.js 相关依赖以及内置的 Rspack 更新至最新版本。
 
-但 Modern.js 对于 Rspack 的依赖方式为锁版本方式(非自动升级)，由于发版周期不同步等原因，可能会出现 Modern.js 内集成的 Rspack 版本落后于 Rspack 最新版本的情况。
+但 Modern.js 对于 Rspack 的依赖方式为锁版本方式（非自动升级），由于发版周期不同步等原因，可能会出现 Modern.js 内集成的 Rspack 版本落后于 Rspack 最新版本的情况。
 
 当你执行 dev / build 命令时，Modern.js 会在[开启调试模式时](https://rsbuild.dev/zh/guide/debug/debug-mode)自动打印当前使用的 Rspack 版本：
 
@@ -140,9 +133,7 @@ export default defineConfig<'rspack'>({
       "@rspack/plugin-react-refresh": "npm:@rspack/plugin-react-refresh@nightly"
     },
     "peerDependencyRules": {
-      "allowAny": [
-        "@rspack/*"
-      ]
+      "allowAny": ["@rspack/*"]
     }
   }
 }

package/docs/zh/guides/basic-features/_meta.json

@@ -1,5 +1,4 @@
 [
-  "css",
   "routes",
   {
     "type": "dir",
@@ -7,16 +6,39 @@
     "label": "data-solution",
     "collapsed": true
   },
+  {
+    "type": "dir",
+    "name": "render",
+    "label": "rendering",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "css",
+    "label": "css-solution",
+    "collapsed": true
+  },
+  "html",
+  {
+    "type": "dir",
+    "name": "static-assets",
+    "label": "static-assets",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "debug",
+    "label": "debug",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "testing",
+    "label": "testing",
+    "collapsed": true
+  },
   "alias",
-  "mock",
-  "proxy",
   "env-vars",
-  "html",
   "output-files",
-  "static-assets",
-  "svg-assets",
-  "json-files",
-  "wasm-assets",
-  "css-modules",
   "deploy"
 ]

package/docs/zh/guides/basic-features/css/_meta.json

@@ -0,0 +1 @@
+["css", "css-modules", "css-in-js", "tailwindcss"]

package/docs/zh/guides/basic-features/css/css-in-js.mdx

@@ -0,0 +1,34 @@
+# 使用 CSS-in-JS
+
+CSS-in-JS 是一种可以将 CSS 样式写在 JS 文件里的技术。
+
+Modern.js 集成了社区常用的 CSS-in-JS 实现库 [styled-components](https://styled-components.com/)，它使用 JavaScript 的新特性 [Tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) 编写组件的 CSS 样式。可以直接从 `@modern-js/runtime/styled` 引入 [styled-components](https://styled-components.com/) 的 API 进行使用。
+
+当需要编写一个内部字体为红色的 `div` 组件时，可以如下实现：
+
+```js
+import styled from '@modern-js/runtime/styled';
+
+const RedDiv = styled.div`
+  color: red;
+`;
+```
+
+当需要根据组件的 `props` 动态设置组件样式时，例如 `props` 的属性 `primary` 为 `true` 时，按钮的颜色为白色，其他情况为红色，实现代码如下：
+
+```js
+import styled from '@modern-js/runtime/styled';
+
+const Button = styled.button`
+  color: ${props => (props.primary ? 'white' : 'red')};
+  font-size: 1em;
+`;
+```
+
+关于 styled-components 的更多用法，请参考 [styled-components 官网](https://styled-components.com/)。
+
+Modern.js 内部集成了 Babel 的 [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components) 插件，你可以通过 [tools.styledComponents](/configure/app/tools/styled-components) 对插件进行配置。
+
+:::tip 提示
+如果需要使用 [styled-jsx](https://www.npmjs.com/package/styled-jsx)、[Emotion](https://emotion.sh/) 等其他 CSS-in-JS 库，需要先安装对应库的依赖。具体使用方式请参考对应库的官网。
+:::

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

@@ -0,0 +1,25 @@
+---
+sidebar_position: 1
+---
+
+# 引入 CSS
+
+Modern.js 内置多种常用的 CSS 开发方案，包括 Less / Sass / Stylus 预处理器、PostCSS、CSS Modules、CSS-in-JS 和 Tailwind CSS。
+
+## 使用 Less、Sass 和 Stylus
+
+Modern.js 内置了社区流行的 CSS 预处理器，包括 Less 和 Sass。
+
+默认情况下，你不需要对 Less 和 Sass 进行任何配置。如果你有自定义 loader 配置的需求，可以通过配置 [tools.less](/configure/app/tools/less)、[tools.sass](/configure/app/tools/sass) 来进行设置。
+
+你也可以在 Modern.js 中使用 Stylus，只需要安装 Rsbuild 提供的 Stylus 插件即可，使用方式请参考 [Stylus 插件](https://rsbuild.dev/zh/plugins/list/plugin-stylus)。
+
+## 使用 PostCSS
+
+Modern.js 内置了 [PostCSS](https://postcss.org/) 来转换 CSS 代码。
+
+请阅读 [Rsbuild - 使用 PostCSS](https://rsbuild.dev/zh/guide/basic/css-usage#%E4%BD%BF%E7%94%A8-postcss) 了解更多用法。
+
+## 使用 Uno CSS
+
+请阅读 [Rsbuild - 使用 UnoCSS](https://rsbuild.dev/zh/guide/basic/unocss) 了解更多用法。

package/docs/zh/guides/basic-features/{css.mdx → css/tailwindcss.mdx}

@@ -1,65 +1,4 @@
----
-sidebar_position: 1
----
-
-# 样式开发
-
-Modern.js 内置多种常用的 CSS 开发方案，包括 Less / Sass / Stylus 预处理器、PostCSS、CSS Modules、CSS-in-JS 和 Tailwind CSS。
-
-## 使用 Less、Sass 和 Stylus
-
-Modern.js 内置了社区流行的 CSS 预处理器，包括 Less 和 Sass。
-
-默认情况下，你不需要对 Less 和 Sass 进行任何配置。如果你有自定义 loader 配置的需求，可以通过配置 [tools.less](/configure/app/tools/less)、[tools.sass](/configure/app/tools/sass) 来进行设置。
-
-你也可以在 Modern.js 中使用 Stylus，只需要安装 Rsbuild 提供的 Stylus 插件即可，使用方式请参考 [Stylus 插件](https://rsbuild.dev/zh/plugins/list/plugin-stylus)。
-
-## 使用 PostCSS
-
-Modern.js 内置了 [PostCSS](https://postcss.org/) 来转换 CSS 代码。
-
-请阅读 [Rsbuild - 使用 PostCSS](https://rsbuild.dev/zh/guide/basic/css-usage#%E4%BD%BF%E7%94%A8-postcss) 了解更多用法。
-
-## 使用 CSS Modules
-
-请阅读 [使用 CSS Modules](/guides/basic-features/css-modules) 章节来了解 CSS Modules 的完整用法。
-
-## 使用 CSS-in-JS
-
-CSS-in-JS 是一种可以将 CSS 样式写在 JS 文件里的技术。
-
-Modern.js 集成了社区常用的 CSS-in-JS 实现库 [styled-components](https://styled-components.com/)，它使用 JavaScript 的新特性 [Tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) 编写组件的 CSS 样式。可以直接从 `@modern-js/runtime/styled` 引入 [styled-components](https://styled-components.com/) 的 API 进行使用。
-
-当需要编写一个内部字体为红色的 `div` 组件时，可以如下实现：
-
-```js
-import styled from '@modern-js/runtime/styled';
-
-const RedDiv = styled.div`
-  color: red;
-`;
-```
-
-当需要根据组件的 `props` 动态设置组件样式时，例如 `props` 的属性 `primary` 为 `true` 时，按钮的颜色为白色，其他情况为红色，实现代码如下：
-
-```js
-import styled from '@modern-js/runtime/styled';
-
-const Button = styled.button`
-  color: ${props => (props.primary ? 'white' : 'red')};
-  font-size: 1em;
-`;
-```
-
-关于 styled-components 的更多用法，请参考 [styled-components 官网](https://styled-components.com/)。
-
-Modern.js 内部集成了 Babel 的 [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components) 插件，你可以通过 [tools.styledComponents](/configure/app/tools/styled-components) 对插件进行配置。
-
-:::tip 提示
-如果需要使用 [styled-jsx](https://www.npmjs.com/package/styled-jsx)、[Emotion](https://emotion.sh/) 等其他 CSS-in-JS 库，需要先安装对应库的依赖。具体使用方式请参考对应库的官网。
-:::
-
-## 使用 Tailwind CSS
+# 使用 Tailwind CSS
 
 [Tailwind CSS](https://tailwindcss.com/) 是一个以 Utility Class 为基础的 CSS 框架和设计系统，可以快速地为组件添加常用样式，同时支持主题样式的灵活扩展。
 
@@ -153,7 +92,7 @@ Tailwind CSS 官方提供了 [Tailwind CSS IntelliSense](https://github.com/tail
 1. 在 VS Code 中安装 [Tailwind CSS IntelliSense](https://github.com/tailwindlabs/tailwindcss-intellisense) 插件。
 2. 如果项目的根目录没有 `tailwind.config.{ts,js}` 文件，那么你需要创建该文件，并写入当前项目的 Tailwind CSS 配置，否则 IDE 插件将无法正确生效。
 
-### Tailwind CSS 版本
+## Tailwind CSS 版本
 
 Modern.js 同时支持 Tailwind CSS v2 和 v3 版本，框架会识别项目 `package.json` 中的 `tailwindcss` 依赖版本，并启用相应的配置。默认情况下，我们会为你安装 Tailwind CSS v3 版本。
 
@@ -162,7 +101,7 @@ Modern.js 同时支持 Tailwind CSS v2 和 v3 版本，框架会识别项目 `pa
 - [Tailwind CSS v3.0](https://tailwindcss.com/blog/tailwindcss-v3)
 - [Upgrade Guide](https://tailwindcss.com/docs/upgrade-guide)
 
-### 浏览器兼容性
+## 浏览器兼容性
 
 Tailwind CSS v2 和 v3 均不支持 IE 11 浏览器，相关背景请参考：