@modern-js/main-doc 2.32.0 → 2.32.2-alpha.1

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

@@ -1,9 +1,8 @@
 ---
-title: Upgrade
 sidebar_position: 3
 ---
 
-# Upgrade
+# Upgrading
 
 ## Upgrade with command
 

package/docs/en/guides/topic-detail/framework-plugin/hook.mdx

@@ -66,7 +66,7 @@ pipeline.use((count, next) => {
   return count * 2;
 });
 
-// 3. 执行
+// 3. Run
 pipeline.run(1); // 2
 pipeline.run(5); // 6
 ```
@@ -155,7 +155,7 @@ workflow.use(count => {
   return count * 2;
 });
 
-// 3. 执行
+// 3. Run
 workflow.run(1); // [2, 2]
 workflow.run(5); // [6, 10]
 ```

package/docs/en/guides/topic-detail/generator/plugin/category.md

@@ -58,7 +58,7 @@ npx @modern-js/create@latest plugin --plugin @modern-js/generator-plugin-plugin
 ? Please select the base type of the plugin: Web App
 ```
 
-### 自定义
+### Custom
 
 ```bash
 npx @modern-js/create@latest plugin --plugin @modern-js/generator-plugin-plugin

package/docs/en/guides/topic-detail/generator/plugin/context.md

@@ -37,7 +37,7 @@ context.addInputBefore('packageManager', {
   properties: {
     'username': {
       type: 'string',
-      title: '用户名',
+      title: 'Username',
     },
   },
 });

package/docs/en/guides/topic-detail/micro-frontend/c02-development.mdx

@@ -1,6 +1,6 @@
 ---
 sidebar_position: 2
-title: development
+title: Development
 ---
 
 # Experience Micro Frontend
@@ -16,7 +16,7 @@ Currently supports two routing modes
 - Self-controlled routing
 - Conventional routing
 
-First, clarify the routing mode of the main application [create a conventional routing main application](#创建约定式路由主应用) or [create a self-controlled routing main application](#创建自控式路由主应用)
+First, clarify the routing mode of the main application [create a file-based routing main App](#file-based-routing-main-app) or [create a self-controlled main App](#self-controlled-main-app)
 
 In this experience we will create two sub-applications Table and Dashboard for the main application (Table is reduced routing, Dashboard is self-controlled routing)
 

package/docs/en/guides/topic-detail/model/auto-actions.mdx

@@ -23,7 +23,7 @@ function Counter() {
   const [state, actions] = useModel(countModel);
 
   useEffect(() => {
-    // 增加 1
+    // Add 1
     actions.setState(state + 1);
   }, []);
 }

package/docs/en/guides/topic-detail/model/performance.mdx

@@ -84,7 +84,8 @@ const fooModel = model('foo').define({
 });
 
 function ComponentA() {
-  // 通过传入 selector 函数，只返回 a 状态给组件
+  // By passing in the selector function
+  // only the a state is returned to the component
   const [stateA] = useModel(fooModel, state => state.a);
 
   return <div>{stateA}</div>;

package/docs/en/guides/topic-detail/model/typescript-best-practice.mdx

@@ -30,7 +30,7 @@ export const foo = model<State>('foo').define({
 });
 ```
 
-When you declare type information for the State of a Model, the `computed` and `actions` of the Model can get the correct type information. In fact, even if we don't define State type information in the example code above, the type information of State can be automatically inferred based on the initial value information of `state`. However, we still recommend that you declare the type information of State when defining a Model because the type information of State inferred based on the initial value information of `state` may be incomplete (missing fields or field type information), and the type information of State cannot be automatically inferred based on the initial value information of `state` when using [Function Type](/apis/app/runtime/model/model_#函数类型) to define the Model.
+When you declare type information for the State of a Model, the `computed` and `actions` of the Model can get the correct type information. In fact, even if we don't define State type information in the example code above, the type information of State can be automatically inferred based on the initial value information of `state`. However, we still recommend that you declare the type information of State when defining a Model because the type information of State inferred based on the initial value information of `state` may be incomplete (missing fields or field type information), and the type information of State cannot be automatically inferred based on the initial value information of `state` when using [Function Type](/apis/app/runtime/model/model_#function-type) to define the Model.
 
 ## Dependent types of Derived State
 

package/docs/en/guides/topic-detail/model/use-model.mdx

@@ -39,7 +39,7 @@ const barModel = model('bar').define({
 });
 
 const [state, actions] = useModel([fooModel, barModel]);
-// 或
+// Or
 const [state, actions] = useModel(fooModel, barModel);
 ```
 

package/docs/en/tutorials/first-app/c05-loader.mdx

@@ -78,8 +78,6 @@ function Index() {
 export default Index;
 ```
 
-{/* Todo 重新截图，SSR 内容  */}
-
 Re-execute `pnpm run dev`, view `view-source: http://localhost:8080/`, or view the "Preview" of the HTML request in the Network panel of devtools, you can see that the HTML rendered by SSR already contains the complete UI:
 
 ![display6](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/11/display6.png)

package/docs/zh/community/releases.mdx

@@ -24,7 +24,7 @@ Modern.js 遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/) 语义化
 
 ## 版本升级
 
-当你需要升级项目中的 Modern.js 版本时，可以使用 `modern upgrade` 命令，参考 [升级](/guides/get-started/upgrade)。
+当你需要升级项目中的 Modern.js 版本时，可以使用 `modern upgrade` 命令，参考 [版本升级](/guides/get-started/upgrade)。
 
 ```bash
 npx modern upgrade

package/docs/zh/community/team.mdx

@@ -2,7 +2,7 @@
 sidebar_position: 1
 ---
 
-# 团队
+# 开发团队
 
 Modern.js 的开发由字节跳动的 Modern.js 团队和社区贡献者驱动。
 

package/docs/zh/components/enable-bff-caution.mdx

@@ -1,4 +1,4 @@
-:::caution 注意
-请先在当前应用项目根目录使用【[new](/apis/app/commands#modern-new)】 启用 BFF 功能。
+:::tip
+请先在当前项目的根目录使用 [new 命令](/apis/app/commands#modern-new) 启用 BFF 功能。
 
 :::

package/docs/zh/configure/app/auto-load-plugin.mdx

@@ -1,9 +1,8 @@
 ---
-title: autoLoadPlugins (自动注册插件)
-sidebar_position: 11
+sidebar_position: 22
 ---
 
-# autoLoadPlugins (自动注册插件)
+# autoLoadPlugins 自动注册插件
 
 - **类型：** `boolean`
 - **默认值：** `false`

package/docs/zh/configure/app/bff/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "bff (BFF API)",
-  "position": 5
+  "label": "bff 一体化",
+  "position": 2
 }

package/docs/zh/configure/app/builder-plugins.mdx

@@ -1,9 +1,8 @@
 ---
-title: builderPlugins (构建插件)
-sidebar_position: 10
+sidebar_position: 21
 ---
 
-# builderPlugins (构建插件)
+# builderPlugins 构建插件
 
 - **类型：** `BuilderPlugin[]`
 - **默认值：** `[]`

package/docs/zh/configure/app/deploy/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "deploy (部署)",
+  "label": "deploy 部署",
   "position": 8
 }

package/docs/zh/configure/app/dev/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "dev (开发调试)",
-  "position": 7
+  "label": "dev 开发",
+  "position": 1
 }

package/docs/zh/configure/app/experiments/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "experiments (实验性)",
-  "position": 15
+  "label": "experiments 实验性",
+  "position": 14
 }

package/docs/zh/configure/app/html/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "html (模板)",
-  "position": 2
+  "label": "html 模板",
+  "position": 3
 }

package/docs/zh/configure/app/output/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "output (构建产物)",
-  "position": 2
+  "label": "output 产物",
+  "position": 7
 }

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

@@ -10,7 +10,7 @@ sidebar_label: ssg
 开启**自控式路由**或**约定式路由** SSG 功能的配置。
 
 :::info 客户端路由
-相关内容可以查看[路由](/guides/basic-features/routes)。
+相关内容可以查看[路由方案](/guides/basic-features/routes)。
 
 :::
 

package/docs/zh/configure/app/performance/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "performance (性能)",
+  "label": "performance 性能",
   "position": 13
 }

package/docs/zh/configure/app/plugins.mdx

@@ -1,9 +1,8 @@
 ---
-title: plugins (插件)
 sidebar_position: 9
 ---
 
-# plugins (插件)
+# plugins 插件
 
 - **类型：** `CliPlugin[]`
 - **默认值：** `[]`

package/docs/zh/configure/app/runtime/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "runtime (运行时)",
-  "position": 3
+  "label": "runtime 运行时",
+  "position": 12
 }

package/docs/zh/configure/app/security/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "security (安全)",
-  "position": 14
+  "label": "security 安全",
+  "position": 11
 }

package/docs/zh/configure/app/server/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "server (服务器)",
-  "position": 4
+  "label": "server 服务器",
+  "position": 6
 }

package/docs/zh/configure/app/source/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "source (源文件)",
-  "position": 1
+  "label": "source 源文件",
+  "position": 5
 }

package/docs/zh/configure/app/testing/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "testing (测试)",
-  "position": 8
+  "label": "testing 测试",
+  "position": 10
 }

package/docs/zh/configure/app/tools/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "tools (底层配置)",
-  "position": 12
+  "label": "tools 底层工具",
+  "position": 4
 }

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

@@ -14,12 +14,16 @@ const tailwind = {
     './config/html/**/*.{html,ejs,hbs}',
     './storybook/**/*',
   ],
-  // 使用 source.designSystem 配置作为 Tailwind CSS Theme 配置
-  theme: source.designSystem,
 };
 ```
 
-对应 [TailwindCSS](https://tailwindcss.com/docs/configuration) 的配置。
+用于修改 [Tailwind CSS](https://tailwindcss.com/docs/configuration) 的配置项。
+
+### 启用 Tailwind CSS
+
+在使用 `tools.tailwindcss` 之前，你需要启用 Modern.js 的 Tailwind CSS 插件。
+
+请阅读[「使用 Tailwind CSS」](/guides/basic-features/css.html#使用-tailwind-css) 章节来了解开启方式。
 
 ### Function 类型
 
@@ -53,8 +57,42 @@ export default {
 };
 ```
 
-### 限制
+### 注意事项
+
+注意：
+
+- 如果你同时使用了 `tailwind.config.{ts,js}` 文件和 `tools.tailwindcss` 选项，那么 `tools.tailwindcss` 定义的配置会优先生效，并覆盖 `tailwind.config.{ts,js}` 中定义的内容。
+- 如果你同时使用了 `source.designSystem` 配置项，那么 Tailwind CSS 的 `theme` 配置将会被 `source.designSystem` 的值所覆盖。
+
+其他配置的使用方式与 Tailwind CSS 官方用法一致，请参考 [tailwindcss - Configuration](https://tailwindcss.com/docs/configuration)。
+
+### 关于 source.designSystem
 
-注意，该配置中不允许使用 `theme` 配置项，否则会构建失败。在 Modern.js 中，请使用 [source.designSystem](/configure/app/source/design-system) 作为 `Tailwind CSS Theme` 配置。
+`source.designSystem` 是 Modern.js 中废弃的配置项。
 
-其他配置的使用方式和 Tailwind CSS 一致，请参考 [tailwindcss - Configuration](https://tailwindcss.com/docs/configuration)。
+从 Modern.js vMAJOR_VERSION.33.0 版本开始，你可以使用 Tailwind CSS 的 `theme` 配置项来代替 `source.designSystem`，不再需要将 `theme` 配置拆分并设置到 `designSystem` 上。
+
+- 旧版本用法：
+
+```ts title="modern.config.ts"
+const { theme, ...rest } = tailwindConfig;
+
+export default {
+  tools: {
+    tailwindcss: rest,
+  },
+  source: {
+    designSystem: theme,
+  },
+};
+```
+
+- 当前版本用法：
+
+```ts title="modern.config.ts"
+export default {
+  tools: {
+    tailwindcss: tailwindConfig,
+  },
+};
+```

package/docs/zh/guides/advanced-features/bff/_category_.json

@@ -1,5 +1,5 @@
 {
-  "label": "BFF",
+  "label": "使用 BFF",
   "position": 2,
   "link": {
     "type": "doc",

package/docs/zh/guides/advanced-features/code-split.mdx

@@ -1,7 +1,7 @@
 ---
-title: 代码分割
-sidebar_position: 6
+sidebar_position: 3
 ---
+
 # 代码分割
 
 代码分割是优化前端资源加载的一种常用手段，本文将介绍 Modern.js 支持的三种代码分割方式：

package/docs/zh/guides/advanced-features/compatibility.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 # 浏览器兼容性

package/docs/zh/guides/advanced-features/eslint.mdx

@@ -1,7 +1,7 @@
 ---
-title: ESLint 规则集
 sidebar_position: 8
 ---
+
 # ESLint 规则集
 
 {/* 参考 [实战教程 - 确认编程环境](../handbook/c03-ide/3.1-setting-up) 确保本地 IDE 环境正常。  */}

package/docs/zh/guides/advanced-features/low-level.mdx

@@ -1,7 +1,7 @@
 ---
-title: 配置底层工具
-sidebar_position: 11
+sidebar_position: 10
 ---
+
 # 配置底层工具
 
 ## 使用方式

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

@@ -1,5 +1,4 @@
 ---
-title: 使用 Rspack
 sidebar_position: 1
 ---
 

package/docs/zh/guides/advanced-features/ssg.mdx

@@ -1,9 +1,8 @@
 ---
-title: 静态站点生成（SSG）
-sidebar_position: 4
+sidebar_position: 5
 ---
 
-# 静态站点生成（SSG）
+# 静态站点生成
 
 SSG（Static Site Generation）是一种基于数据与模板，在构建时渲染完整静态网页的技术解决方案。
 
@@ -55,7 +54,7 @@ SSG 在**约定式路由**和**自控式路由**下的使用方式不同。
 - `/user/profile`
 
 :::note
-如果还不了解约定式路由的规则，可以先查看[路由](/guides/basic-features/routes)。
+如果还不了解约定式路由的规则，可以先查看[路由方案](/guides/basic-features/routes)。
 
 :::
 

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

@@ -1,9 +1,8 @@
 ---
-title: 服务端渲染（SSR）
-sidebar_position: 3
+sidebar_position: 4
 ---
 
-# 服务端渲染（SSR）
+# 服务端渲染
 
 在 Modern.js 中，SSR 也是开箱即用的。开发者无需为 SSR 编写复杂的服务端逻辑，也无需关心 SSR 的运维，或是创建单独的服务。Modern.js 拥有完备的 SSR 降级策略，保证页面能够安全运行。
 

package/docs/zh/guides/advanced-features/testing.mdx

@@ -1,8 +1,8 @@
 ---
-sidebar_position: 10
+sidebar_position: 11
 ---
 
-# 测试
+# 使用 Jest 测试
 
 Modern.js 默认集成了 [Jest](https://jestjs.io/) 的测试能力。
 

package/docs/zh/guides/advanced-features/using-storybook.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 20
+sidebar_position: 12
 ---
 
 # 使用 Storybook

package/docs/zh/guides/advanced-features/web-server.mdx

@@ -1,7 +1,7 @@
 ---
-title: 自定义 Web Server
-sidebar_position: 3
+sidebar_position: 13
 ---
+
 # 自定义 Web Server
 
 Modern.js 作为以客户端为中心的开发框架，对服务端的定制能力较弱。而在有些开发场景下，需要定制特殊的服务端逻辑，例如用户鉴权、请求预处理、添加页面渲染骨架等。

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

@@ -1,8 +1,8 @@
 ---
-title: 别名
-sidebar_position: 8
+sidebar_position: 3
 ---
-# 别名
+
+# 路径别名
 
 Modern.js 允许在 JS 和 CSS 中使用别名导入自定义目录下的模块，并内置了以下别名:
 

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

@@ -2,7 +2,7 @@
 sidebar_position: 2
 ---
 
-# CSS 开发方案
+# 样式开发
 
 Modern.js 内置多种常用的 CSS 开发方案，包括 Less / Sass / Stylus 预处理器、PostCSS、CSS Modules、CSS-in-JS 和 Tailwind CSS。
 
@@ -103,47 +103,46 @@ const App = () => (
 
 :::
 
-### Tailwind CSS 自动补全
-
-Tailwind CSS 官方提供了 [Tailwind CSS IntelliSense](https://github.com/tailwindlabs/tailwindcss-intellisense) 插件，用于在 VS Code 中自动补全 Tailwind CSS 的 class names、CSS functions 和 directives。
+### 配置 Tailwind CSS
 
-你可以参考以下步骤来启动自动补全功能：
+在 Modern.js 中，你有两种方式来配置 Tailwind CSS：
 
-1. 在 VS Code 中安装 [Tailwind CSS IntelliSense](https://github.com/tailwindlabs/tailwindcss-intellisense) 插件。
-2. 在项目的根目录创建 `tailwind.config.ts` 文件，并写入你需要的 Tailwind CSS 配置。
+1. 使用 `tailwind.config.{ts,js}` 文件，该用法与 Tailwind CSS 的官方用法一致，请参考 ["Tailwind CSS - Configuration"](https://tailwindcss.com/docs/configuration) 来了解更多用法。
 
 ```ts title="tailwind.config.ts"
+import type { Config } from 'tailwindcss';
+
 export default {
-  content: [
-    './src/**/*.{js,jsx,ts,tsx}',
-    './config/html/**/*.{html,ejs,hbs}',
-    './storybook/**/*',
-  ],
-  // 主题配置（可选）
-  theme: {},
-};
+  content: ['./src/**/*.{js,jsx,ts,tsx}'],
+} as Config;
 ```
 
-3. 在 `modern.config.ts` 中引用你创建的 `tailwind.config.ts` 文件，使 Modern.js 可以正确识别 Tailwind CSS 配置内容。
+:::tip
+请升级 Modern.js 到 >= MAJOR_VERSION.33.0 版本，以支持自动读取 `tailwind.config.{ts,js}` 文件。
+:::
 
-```ts title="modern.config.ts"
-import tailwindConfig from './tailwind.config';
+2. 使用 [tools.tailwindcss](/configure/app/tools/tailwindcss.html) 配置项，这是旧版本的用法，我们更推荐使用 `tailwind.config.{ts,js}` 文件进行配置。
 
-export default defineConfig({
+```ts title="modern.config.ts"
+export default {
   tools: {
-    tailwindcss: tailwindConfig,
-  },
-  // 主题配置（可选）
-  source: {
-    designSystem: tailwindConfig.theme,
+    tailwindcss: {
+      content: ['./src/**/*.{js,jsx,ts,tsx}'],
+    },
   },
-});
+};
 ```
 
-请阅读相关配置项的文档来了解其作用：
+如果你同时使用了 `tailwind.config.{ts,js}` 文件和 `tools.tailwindcss` 选项，那么 `tools.tailwindcss` 定义的配置会优先生效，并覆盖 `tailwind.config.{ts,js}` 中定义的内容。
+
+### Tailwind CSS 自动补全
+
+Tailwind CSS 官方提供了 [Tailwind CSS IntelliSense](https://github.com/tailwindlabs/tailwindcss-intellisense) 插件，用于在 VS Code 中自动补全 Tailwind CSS 的 class names、CSS functions 和 directives。
+
+你可以参考以下步骤来启动自动补全功能：
 
-- [tools.tailwindcss](/configure/app/tools/tailwindcss)。
-- [source.designSystem](/configure/app/source/design-system)。
+1. 在 VS Code 中安装 [Tailwind CSS IntelliSense](https://github.com/tailwindlabs/tailwindcss-intellisense) 插件。
+2. 如果项目的根目录没有 `tailwind.config.{ts,js}` 文件，那么你需要创建该文件，并写入当前项目的 Tailwind CSS 配置，否则 IDE 插件将无法正确生效。
 
 ### Tailwind CSS 版本
 
@@ -162,39 +161,3 @@ Tailwind CSS v2 和 v3 均不支持 IE 11 浏览器，相关背景请参考：
 - [Tailwind CSS v2 - Browser Support](https://v2.tailwindcss.com/docs/browser-support)
 
 如果你在 IE 11 浏览器上使用 Tailwind CSS，可能会出现部分样式不可用的现象，请谨慎使用。
-
-### Theme 配置
-
-当需要自定义 Tailwind CSS 的 [theme](https://tailwindcss.com/docs/theme) 配置的时候，可以在配置 [`source.designSystem`](/configure/app/source/design-system) 中修改，例如，颜色主题中增加一个 `primary`：
-
-```ts title="modern.config.ts"
-export default defineConfig({
-  source: {
-    designSystem: {
-      extend: {
-        colors: {
-          primary: '#5c6ac4',
-        },
-      },
-    },
-  },
-});
-```
-
-当需要对 Tailwind CSS 做 [theme](https://tailwindcss.com/docs/theme) 以外的其他特殊配置时，可以在 [`tools.tailwindcss`](/configure/app/tools/tailwindcss) 中配置，例如设置 `variants`：
-
-```ts title="modern.config.ts"
-export default defineConfig({
-  tools: {
-    tailwindcss: {
-      variants: {
-        extend: {
-          backgroundColor: ['active'],
-        },
-      },
-    },
-  },
-});
-```
-
-> 当你为项目配置 Tailwind CSS 的时候，[source.designSystem](/configure/app/source/design-system) 和 [tools.tailwindcss](/configure/app/tools/tailwindcss) 这两个配置的组合等价于单独配置了一个 `tailwindcss.config.js` 文件。其中 [source.designSystem](/configure/app/source/design-system) 等效于 Tailwind CSS 的 [theme](https://v2.tailwindcss.com/docs/configuration#theme) 配置。

package/docs/zh/guides/basic-features/data-fetch.mdx

@@ -1,6 +1,5 @@
 ---
-title: 数据获取
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 # 数据获取

package/docs/zh/guides/basic-features/env-vars.mdx

@@ -1,7 +1,7 @@
 ---
-title: 环境变量
 sidebar_position: 7
 ---
+
 # 环境变量
 
 Modern.js 提供了对环境变量的支持，包含内置的环境变量和自定义的环境变量。