@modern-js/main-doc 2.0.0-beta.6 → 2.0.0-canary.1

package/zh/configure/app/dev/proxy.md

@@ -5,74 +5,6 @@ sidebar_label: proxy
 # dev.proxy
 
 
+import GlobalProxyConfig from '@site-docs/components/global-proxy-config.md'
 
-* 类型： `string | Object`
-* 默认值： `null`
-
-配置该选项后，开发环境时会启动全局代理，类似 [Fiddler](https://www.telerik.com/fiddler), [Charles](https://www.charlesproxy.com/) 等 web 代理调试工具，可以用来查看、修改 HTTP/HTTPS 请求、响应、也可以用作代理服务器。
-
-
-:::tip 提示
-使用该选项需要提前安装 `@modern-js/plugin-proxy`。
-:::
-
-值为 `Object` 时，对象的 `key` 对应匹配的 `pattern`，对象的 `value` 对应匹配的 `target`。
-
-例如：
-
-```typescript title="modern.config.ts"
-export default defineConfig({
-  dev: {
-    proxy: {
-      'https://www.baidu.com': 'https://google.com.hk',
-      //可以通过 file 协议直接返回静态文件。
-      'https://example.com/api': 'file://./data.json',
-    }
-  }
-});
-```
-
-值为 `string` 时， 可以用来指定单独的代理文件，例如：
-
-
-```typescript title="modern.config.ts"
-export default defineConfig({
-  dev: {
-    proxy: './proxy.js',
-  },
-});
-```
-
-```js title="proxy.js"
-module.exports = {
-  name: 'my-app',
-  rules: `
-    ^example.com:8080/api/***   http://localhost:3001/api/$
-  `,
-};
-```
-
-:::info 注
-Modern.js 全局代理实现底层基于 [whistle](https://wproxy.org/whistle/), 更多匹配模式请参考: [匹配模式](https://wproxy.org/whistle/pattern.html)
-:::
-
-执行 `dev`, 提示如下时，即代理服务器启动成功：
-
-```bash
-  App running at:
-
-  Local:    http://localhost:8080/
-  Network:  http://192.168.0.1:8080/
-
-ℹ  info      Starting the proxy server.....
-✔  success   Proxy Server start on localhost:8899
-```
-
-访问 `localhost:8899`, 可以在 UI 界面上查看 Network 以及配置代理规则：
-
-![proxy ui 界面](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/dev-proxy.png)
-
-:::caution 注意
-https 代理自动安装证书需要获取 root 权限, 请根据提示输入密码即可。**密码仅在信任证书时使用，不会泄漏或者用于其他环节**。
-:::
-
+<GlobalProxyConfig />

package/zh/configure/app/source/entries.md

@@ -61,7 +61,6 @@ export default defineConfig({
 
 * `entry`：`string`，入口文件路径。
 * `disableMount`：`boolean = false`，关闭 Modern.js 生成入口代码的行为。
-* `enableFileSystemRoutes`：`boolean = false`，是否 [使用约定式路由](/docs/apis/app/hooks/src/pages)。
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
@@ -76,8 +75,7 @@ export default defineConfig({
       // 启用约定式路由
       entry_spa: {
         // 约定式路由的入口路径必须设置为目录
-        entry: './src/about',
-        enableFileSystemRoutes: true,
+        entry: './src/about'
       },
     },
   },

package/zh/configure/app/tools/tailwindcss.md

@@ -4,39 +4,32 @@ title: tools.tailwindcss
 sidebar_label: tailwindcss
 ---
 
-
-* 类型： `Object | Function`
-* 默认值：见下方配置详情。
+- 类型： `Object | Function`
+- 默认值：见下方配置详情。
 
 <details>
   <summary>TailwindCSS 配置详情</summary>
 
 ```js
-  const tailwind = {
-    purge: {
-        enabled: options.env === 'production',
-        content: [
-          './config/html/**/*.html',
-          './config/html/**/*.ejs',
-          './config/html/**/*.hbs',
-          './src/**/*',
-        ],
-        layers: ['utilities'],
-    },
-    // https://tailwindcss.com/docs/upcoming-changes
-    future: {
-      removeDeprecatedGapUtilities: false,
-      purgeLayersByDefault: true,
-      defaultLineHeights: false,
-      standardFontWeights: false,
-    },
-    theme: source.designSystem // 使用source.designSystem配置作为Tailwind CSS Theme配置
-  }
+const tailwind = {
+  content: [
+    './config/html/**/*.html',
+    './config/html/**/*.ejs',
+    './config/html/**/*.hbs',
+    './src/**/*.js',
+    './src/**/*.jsx',
+    './src/**/*.ts',
+    './src/**/*.tsx',
+    './storybook/**/*',
+  ],
+  theme: source.designSystem, // 使用source.designSystem配置作为Tailwind CSS Theme配置
+};
 ```
 
 :::tip 提示
 更多关于：<a href="https://tailwindcss.com/docs/configuration" target="_blank">TailwindCSS 配置</a>。
 :::
+
 </details>
 
 对应 [TailwindCSS](https://tailwindcss.com/docs/configuration) 的配置，值为 `Object` 类型时，与默认配置通过 `Object.assign` 合并。

package/zh/guides/advanced-features/bff/frameworks.md

@@ -3,6 +3,8 @@ sidebar_position: 3
 title: 运行时框架
 ---
 
+Modern.js 的 BFF 支持不同的运行时框架，当前 Modern.js 的 BFF 支持两种运行时框架 [Express.js](https://expressjs.com/) 和 [Koa.js](https://koajs.com/)。
+
 ## 函数写法
 
 在函数写法下，各类运行时框架仅中间件写法存在差异，其他实现基本相同。这里以 Express 为例，介绍如何在 `api/_app.ts` 中，手写一个中间件，添加权限校验：

package/zh/guides/advanced-features/bff/function.md

@@ -1,18 +1,24 @@
 ---
 sidebar_position: 1
-title: 一体化调用
+title: 基础用法
 ---
 
-Modern.js 允许在 React 组件中直接调用 `api/` 目录下满足一定条件的函数，称为**一体化调用**。
+通过 Modern.js 开发的应用，可以在 `api/` 目录下定义接口函数，前端可以调用这些接口函数，即可发起请求，无需写前后端胶水层代码，同时保证前后端类型安全。
 
-:::note
-使用一体化调用需要先开启 BFF 功能。
-:::
+## 启用 BFF
+
+import EnableBFF from '@site-docs/components/enable-bff.md'
+
+<EnableBFF/>
 
 ## BFF 函数
 
 允许通过一体化调用的函数，称为 **BFF 函数**。这里写一个最简单的 BFF 函数，创建 `api/hello.ts` 文件：
 
+:::caution
+如果是框架模式（有 `api/lambda` 目录），需要创建 `api/lambda/hello.ts`
+:::
+
 ```ts title="api/hello.ts"
 export const get = async () => 'Hello Modern.js';
 ```
@@ -41,7 +47,7 @@ Modern.js 生成器已经在 `tsconfig.json` 中配置 `@api` 别名，因此可
 
 执行 `pnpm run dev` 打开 `http://localhost:8080/` 可以看到页面已经展示了 BFF 函数返回的内容，在 Network 中可以看到页面向 `http://localhost:8080/api/hello` 发送了请求：
 
-![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/hello-modern.png)
+![Network](https://p6-piu.byteimg.com/tos-cn-i-8jisjyls3a/fd41750f8d414179a9b4ecb519919b36~tplv-8jisjyls3a-3:0:0:q75.png)
 
 ## 函数路由
 
@@ -53,32 +59,30 @@ Modern.js 中，BFF 函数对应的路由系统是基于文件系统实现的，
 函数写法和框架写法会在下一节详细介绍。
 :::
 
-以下的 `$BASENAME` 指的是 BFF 函数的[路由前缀](/docs/configure/app/bff/prefix)，可以在 `modern.config.js` 中进行配置，默认值为 `/api`。
+所有 BFF 函数生成的路由都带有统一的前缀，默认值为 `/api`。可以通过 [bff.prefix](/docs/configure/app/bff/prefix) 设置公共路由的前缀。
 
-:::info 注
-可以通过 [bff.prefix](/docs/configure/app/bff/prefix) 设置公共路由的前缀。
-:::
+下面介绍几种路由的约定。
 
 ### 默认路由
 
 以 `index.[jt]s` 命名的文件会被映射到上一层目录。
 
-* `api/index.ts` -> `$BASENAME/`
-* `api/user/index.ts` -> `$BASENAME/user`
+* `api/index.ts` -> `{prefix}/`
+* `api/user/index.ts` -> `{prefix}/user`
 
-### 嵌套路由
+### 多层路由
 
 支持解析嵌套的文件，如果创建嵌套文件夹结构，文件仍会以相同方式自动解析路由。
 
-* `api/hello.ts` -> `$BASENAME/hello`
-* `api/user/list.ts` -> `$BASENAME/user/list`
+* `api/hello.ts` -> `{prefix}/hello`
+* `api/user/list.ts` -> `{prefix}/user/list`
 
 ### 动态路由
 
-同样的，创建命名带有 `[xxx]` 的文件夹或者文件，支持动态的命名路由参数。
+同样的，创建命名带有 `[xxx]` 的文件夹或者文件，支持动态的命名路由参数。动态路由的函数参数规则可以看 [dynamac-path](/docs/guides/advanced-features/bff/function#dynamic-path)
 
-* `api/user/[username]/info.ts` -> `$BASENAME/user/:username/info`
-* `api/user/username/[action].ts` -> `$BASENAME/user/username/:action`
+* `api/user/[username]/info.ts` -> `{prefix}/user/:username/info`
+* `api/user/username/[action].ts` -> `{prefix}/user/username/:action`
 
 ### 白名单
 
@@ -102,7 +106,7 @@ Modern.js 的 BFF 函数需要遵循 RESTful API 标准来定义, 遵循 HTTP Me
 
 ### 函数具名导出
 
-Modern.js BFF 函数的导出名决定了函数对应接口的 Method，如`get`，`post`等。
+Modern.js BFF 函数的导出名决定了函数对应接口的 Method，如 `get`，`post` 等。
 
 例如，按照以下例子，可导出一个 GET 接口。
 
@@ -126,9 +130,9 @@ export const post = async () => {
 };
 ```
 
-* 应用工程 中支持了 9 种 Method 定义，即：`GET`、`POST`、`PUT`、`DELETE`、`CONNECT`、`TRACE`、`PATCH`、`OPTION`、`HEAD`，即可以用这些 Method 作为函数导出的名字。
+* 对应 HTTP Method，Modern.js 也支持了 9 种定义，即：`GET`、`POST`、`PUT`、`DELETE`、`CONNECT`、`TRACE`、`PATCH`、`OPTION`、`HEAD`，即可以用这些 Method 作为函数导出的名字。
 
-* 名字是大小不敏感的，就是说，如果是 `GET`，写成 `get`、`Get`、`GEt`、`GET`，都可以准确识别。而默认导出，即 `export default xxx` 则会被映射为 `Get`。
+* 名字是大小不敏感的，如果是 `GET`，写成 `get`、`Get`、`GEt`、`GET`，都可以准确识别。而默认导出，即 `export default xxx` 则会被映射为 `Get`。
 
 * 可以在一个文件中定义多个不同 Method 的函数，但如果定义多个相同 Method 的函数，则只有第一个会生效。
 
@@ -140,9 +144,7 @@ export const post = async () => {
 
 如上所述，为了满足 RESTful API 的设计标准，因此 Modern.js 中 BFF 函数需要遵循一定的入参规则。
 
-Modern.js 函数定义分为普通函数与带有 schema 的函数，这一小节先介绍普通函数。
-
-普通函数参数分为两块，分别是请求路径中的动态部分和请求选项 `RequestOption`。
+函数参数分为两块，分别是请求路径中的动态部分和请求选项 `RequestOption`。
 
 #### Dynamic Path
 
@@ -190,6 +192,24 @@ export async function post(
 }
 ```
 
+这里你也可以使用自定义类型：
+```ts title="api/lambda/hello.ts"
+import type { RequestOption } from '@modern-js/runtime/server'
+
+type IQuery = {
+  // some types
+}
+type IData = {
+  // some types
+}
+
+export async function post(
+  { query, data }: { query:IQuery, data:IData }
+) {
+  // do somethings
+}
+```
+
 当函数文件使用动态路由规则时，动态路由会在 `RequestOption` 对象参数前。
 
 ```ts title="api/[sku]/[id]/item.ts"

package/zh/guides/advanced-features/code-split.md

@@ -5,6 +5,10 @@ sidebar_position: 6
 
 代码分割是优化前端资源加载的一种常用手段，本文将介绍 Modern.js 支持的三种代码分割方式：
 
+:::info
+使用 Modern.js [约定式路由](/docs/guides/basic-features/routes#约定式路由)时，默认会根据路由组件做代码分割，包裹 `Suspense` 组件，无需自行进行代码分割。
+:::
+
 - `import`
 - `React.lazy`
 - `loadable`
@@ -21,30 +25,14 @@ import("./math").then(math => {
 
 `./math` 路径对应的 JS 模块会被打包到单独的 JS 文件中。
 
-## loadable
-
-使用 `loadable` API，示例如下：
-
-```ts
-import loadable from '@modern-js/runtime/loadable'
-
-const OtherComponent = loadable(() => import('./OtherComponent'));
-
-function MyComponent() {
-  return <OtherComponent />
-}
-```
+## React.lazy
 
-`loadable` 更多用法请见 [loadable API](/docs/apis/app/runtime/utility/loadable)。
+React 官方提供的组件代码分割的方式。
 
-:::info 注
-`loadable` 开箱即用的支持 SSR。
+:::caution
+React 17 及以下版本不支持 SSR，建议 React17 的 SSR 应用使用 loadable。
 :::
 
-## React.lazy
-
-React 官方提供的组件代码分割的方式，**缺点是不支持 SSR**。
-
 ```ts
 import React, { Suspense } from 'react';
 
@@ -66,3 +54,23 @@ function MyComponent() {
 ```
 
 `React.lazy` 更多用法请见 [React lazy](https://zh-hans.reactjs.org/docs/code-splitting.html#reactlazy)。
+
+## loadable
+
+使用 `loadable` API，示例如下：
+
+```ts
+import loadable from '@modern-js/runtime/loadable'
+
+const OtherComponent = loadable(() => import('./OtherComponent'));
+
+function MyComponent() {
+  return <OtherComponent />
+}
+```
+
+`loadable` 更多用法请见 [loadable API](/docs/apis/app/runtime/utility/loadable)。
+
+:::info 注
+`loadable` 开箱即用的支持 SSR，但不支持和 Suspense 一起使用，如果是 CSR 项目可以使用 [loadable.lazy](https://loadable-components.com/docs/suspense/)
+:::

package/zh/guides/advanced-features/compatibility.md

@@ -3,13 +3,32 @@ title: 客户端兼容性
 sidebar_position: 5
 ---
 
-## Polyfill 模式
+## Browserslist 配置
+
+Modern.js 支持在项目根目录 `package.json` 文件中的 `browserslist` 字段（或单独的 `.browserslistrc` 文件）指定项目覆盖的目标浏览器范围。该值会被 [`@babel/preset-env`](https://babeljs.io/docs/en/babel-preset-env) 和 [`autoprefixer`](https://github.com/postcss/autoprefixer) 用来确定需要转换的 JavaScript 语法特性和需要添加的 CSS 浏览器前缀。
+
+Modern.js 中默认值如下:
+
+```js
+['> 0.01%', 'not dead', 'not op_mini all']
+```
+
+可以在[这里](https://github.com/browserslist/browserslist)了解如何自定义浏览器范围。
+
+查看 Modern.js Builder 文档了解更多 [Browserlist](https://modernjs.dev/builder/zh/guide/advanced/browserslist.html) 相关内容。
+
+:::note
+Modern.js 支持配置 [output.overrideBrowserlist](/docs/configure/app/output/override-browserslist) 覆盖默认 browserlist 值。
+:::
+
+
+## Polyfill
 
 ### 编译时 Polyfill
 
 Modern.js 在编译时默认通过 [core-js](https://github.com/zloirock/core-js) 引入对应的 Polyfill 代码。
 
-默认情况下会根据项目 [Browserslist](https://github.com/browserslist/browserslist) 的设置情况引入所需的 Polyfill 代码， 这样基本不用再担心项目源码和第三方依赖的 Polyfill 问题了，但是因为包含了一些没有用到的 Polyfill 代码，所以最终的包大小可能会有所增加。
+默认情况下会根据项目 Browserslist 的设置情况引入所需的 Polyfill 代码， 这样基本不用再担心项目源码和第三方依赖的 Polyfill 问题了，但是因为包含了一些没有用到的 Polyfill 代码，所以最终的包大小可能会有所增加。
 
 :::info 注
 对于明确第三方依赖不需要 Polyfill 的场景，可以设置 [`output.polyfill`](/docs/configure/app/output/polyfill) 为 `usage`, 这样 Babel 编译时只会根据代码中使用到的语法引入 Polyfill 代码。
@@ -48,17 +67,8 @@ export default defineConfig({
 
 在 Chrome 51 下访问页面可以看到 `http://localhost:8080/__polyfill__` 返回内容如下:
 
-
 ![ua-polyfill](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ua-polyfill.png)
 
-## Browserslist 配置
-
-Modern.js 支持在项目根目录 `package.json` 文件中的 `browserslist` 字段（或单独的 `.browserslistrc` 文件）指定项目覆盖的目标浏览器范围。该值会被 [`@babel/preset-env`](https://babeljs.io/docs/en/babel-preset-env) 和 [`autoprefixer`](https://github.com/postcss/autoprefixer) 用来确定需要转换的 JavaScript 语法特性和需要添加的 CSS 浏览器前缀。
-
-Modern.js 中默认值如下:
-
-```js
-['> 0.01%', 'not dead', 'not op_mini all']
-```
-
-可以在[这里](https://github.com/browserslist/browserslist)了解如何自定义浏览器范围。
+:::caution 注意
+该功能只有在使用 Modern.js 内置的 Web Server 时才会生效。
+:::

package/zh/guides/advanced-features/ssg.md

@@ -5,10 +5,6 @@ sidebar_position: 4
 
 SSG（Static Site Generation）是一种基于数据与模板，在构建时渲染完整静态网页的技术解决方案。
 
-:::info 注
-SSG 是构建阶段的解决方案，因此仅对生产环境有效。通过 `dev` 命令运行时，表现效果与 SSR 相同。
-:::
-
 我们首先需要执行 `pnpm run new` 启用 SSG 功能：
 
 ```bash
@@ -16,7 +12,7 @@ SSG 是构建阶段的解决方案，因此仅对生产环境有效。通过 `de
 ? 启用可选功能 启用「SSG」功能
 ```
 
-执行命令后，在 `modern.config.ts` 中注册 SSG 插件:
+执行命令后，在 `modern.config.ts` 中注册 SSG 插件：
 
 ```ts title="modern.config.ts"
 import SSGPlugin from '@modern-js/plugin-ssg';
@@ -129,45 +125,3 @@ export default defineConfig({
 :::info
 以上仅介绍了单入口的情况，更多相关内容可以查看 [API 文档](/docs/configure/app/output/ssg)。
 :::
-
-### 获取数据
-
-在 SSR 中，组件可以通过 `useLoader` 同构的获取数据。在 SSG 中，Modern.js 也提供了相同的能力。
-
-调用 `useLoader` 时，在第二个参数中设置 `{ static: true }`，可以在 SSG 阶段执行数据的请求。
-
-:::info 注
-- Modern.js 目前还不支持 SSG 与 SSR 混合渲染，敬请期待。
-- 在开发阶段，不管 `useLoader` 是否配置 `{ static: true }`，函数都会在 SSR 时获取数据。
-:::
-
-修改上述 `src/App.ts` 的代码为：
-
-```tsx title="App.ts"
-import { useRuntimeContext, useLoader } from '@modern-js/runtime';
-import { Routes, Route, BrowserRouter } from '@modern-js/runtime/router';
-import { StaticRouter } from '@modern-js/runtime/router/server';
-
-const Router = typeof window === 'undefined' ? StaticRouter : BrowserRouter;
-
-export default () => {
-  const { context } = useRuntimeContext();
-
-  const { data } = useLoader(async () => ({
-    message: Math.random(),
-  }), { static: true });
-
-  return (
-    <Router location={context.request.pathname}>
-      <Routes>
-        <Route index element={<div>index</div>} />
-        <Route path="about" element={<div>about, {data?.message}</div>} />
-      </Routes>
-    </Router>
-  );
-};
-```
-
-执行 `pnpm run dev`，重复刷新页面，可以看到 `/foo` 页面的渲染结果不断发生变化，说明数据是在请求时获取的。
-
-重新执行 `pnpm run build` 后，执行 `pnpm run serve`，重复刷新页面，发现页面渲染结果始终保持同样的内容，数据在请求时不会再次获取，说明页面在编译时已经完成渲染。

package/zh/guides/advanced-features/ssr.md

@@ -125,7 +125,7 @@ CSR 中这类问题不易被发觉，因此从 CSR 切换到 SSR 时，如果不
 
 ## 收敛服务端数据
 
-为了保持 SSR 阶段请求的数据，可以在浏览器端直接使用， Modern.js 会将渲染过程中收集的数据与状态注入到 HTML 内。但是，CSR 应用常常存在接口数据量大、组件状态未收敛的情况，这时如果直接使用 SSR，渲染得到的 HTML 体积可能会存在过大的问题。此时，SSR 不仅无法为应用带来用户体验上的提升，反而可能起到相反的作用。
+为了保持 SSR 阶段请求的数据，可以在浏览器端直接使用，Modern.js 会将渲染过程中收集的数据与状态注入到 HTML 内。但是，CSR 应用常常存在接口数据量大、组件状态未收敛的情况，这时如果直接使用 SSR，渲染得到的 HTML 体积可能会存在过大的问题。此时，SSR 不仅无法为应用带来用户体验上的提升，反而可能起到相反的作用。
 
 因此，使用 SSR 时，**开发者需要为应用做合理的瘦身**：
 

package/zh/guides/advanced-features/testing.md

@@ -15,7 +15,7 @@ Modern.js 默认继承了 [Jest](https://jestjs.io/) 的测试能力。
 
 执行上述命令后，`package.json` 中将会自动生成 `"test": "modern test"` 命令。
 
-在 `modern.config.ts` 中注册 Test 插件:
+在 `modern.config.ts` 中注册 Test 插件：
 
 ```ts title="modern.config.ts"
 import TestPlugin from '@modern-js/plugin-testing';
@@ -28,7 +28,7 @@ export default defineConfig({
 
 ## 测试文件
 
-Modern.js 默认识别的测试文件路径为： `<rootDir>/src/**/*.test.[jt]s?(x)` 和 `<rootDir>/tests/**/*.test.[jt]s?(x)`。
+Modern.js 默认识别的测试文件路径为：`<rootDir>/src/**/*.test.[jt]s?(x)` 和 `<rootDir>/tests/**/*.test.[jt]s?(x)`。
 
 如果你需要自定义 test 目录，可通过 [tools.jest](/docs/configure/app/tools/jest) 进行配置。
 

package/zh/guides/basic-features/alias.md

@@ -13,10 +13,10 @@ Modern.js 允许在 JS 和 CSS 中使用别名导入自定义目录下的模块
 ```
 
 :::info 注
-在开启可选功能时，生成器也会动态的添加内置别名，例如启用 BFF 时默认会添加 `@api` 别名：
+在开启可选功能时，生成器也会动态的添加内置别名，例如启用 BFF 时默认会添加 `@api` 别名。
 :::
 
-`src/` 目录结构如下时，从 `src/App.tsx` 文件中导入 `src/common` 目录下的模块:
+例如从 `src/App.tsx` 文件中导入 `src/common` 目录下的模块：
 
 ```bash
 .
@@ -28,14 +28,14 @@ Modern.js 允许在 JS 和 CSS 中使用别名导入自定义目录下的模块
 ├── App.tsx
 ```
 
-`src/App.tsx` 中写法如下:
+`src/App.tsx` 中写法如下：
 
 ```ts
 import utils from '@/src/common/utils';
 import '@/src/common/styles/base.css';
 ```
 
-Modern.js 也提供了自定义别名的方式，以添加 `@common` 别名为例，对于 TypeScript 项目，只需要在项目根目录 `tsconfig.json` 下配置 `compilerOptions.paths` 如下:
+Modern.js 也提供了自定义别名的方式，以添加 `@common` 别名为例，对于 TypeScript 项目，只需要在项目根目录 `tsconfig.json` 下配置 `compilerOptions.paths` 如下：
 
 ```json
 {
@@ -52,7 +52,7 @@ Modern.js 也提供了自定义别名的方式，以添加 `@common` 别名为
 }
 ```
 
-JavaScript 项目可以在 `modern.config.js` 中配置 [`source.alias`](/docs/configure/app/source/alias):
+JavaScript 项目可以在 `modern.config.js` 中配置 [`source.alias`](/docs/configure/app/source/alias)：
 
 ```typescript title="modern.config.ts"
 export default defineConfig({

package/zh/guides/basic-features/css/tailwindcss.md

@@ -32,12 +32,40 @@ import 'tailwindcss/components.css';
 import 'tailwindcss/utilities.css';
 ```
 
-然后即可在各个组件中使用 Tailwind CSS 提供的 Utility Class 了。
+然后即可在各个组件中使用 Tailwind CSS 提供的 Utility Class 了：
+
+```tsx
+const App = () => (
+  <div className="h-12 w-48">
+    <p className="text-xl font-medium text-black">hello world</p>
+  </div>
+);
+```
 
 :::info 补充信息
-根据不同需求，可以选择性的导入 Tailwind CSS 提供的 CSS 文件。由于使用 `@taiwind` 与直接导入 CSS 文件的作用等价，因此关于 Tailwind CSS 提供的 CSS 文件的用途，可以参考 [`@tailwind` 的使用](https://tailwindcss.com/docs/functions-and-directives#tailwind) 文档中注释里的内容。
+根据需求不同，你可以选择性的导入 Tailwind CSS 提供的 CSS 文件。由于使用 `@tailwind` 与直接导入 CSS 文件的作用等价，因此关于 Tailwind CSS 提供的 CSS 文件的用途，可以参考 [`@tailwind` 的使用](https://tailwindcss.com/docs/functions-and-directives#tailwind) 文档中注释里的内容。
 :::
 
+## Tailwind CSS 版本
+
+Modern.js 同时支持 Tailwind CSS v2 和 v3 版本，框架会识别项目 `package.json` 中的 `tailwindcss` 依赖版本，并启用相应的配置。默认情况下，我们会为你安装 Tailwind CSS v3 版本。
+
+如果你的项目仍在使用 Tailwind CSS v2，我们推荐你升级到 v3 以支持 JIT 等能力。关于 Tailwind CSS v2 与 v3 版本之间的差异，请参考以下文章：
+
+- [Tailwind CSS v3.0](https://tailwindcss.com/blog/tailwindcss-v3)
+- [Upgrade Guide](https://tailwindcss.com/docs/upgrade-guide)
+
+### 浏览器兼容性
+
+Tailwind CSS v2 和 v3 均不支持 IE 11 浏览器，相关背景请参考：
+
+- [Tailwind CSS v3 - Browser Support](https://tailwindcss.com/docs/browser-support)。
+- [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`](/docs/configure/app/source/design-system) 中修改，例如，颜色主题中增加一个 `primary`：
 
 ```typescript title="modern.config.ts"
@@ -70,36 +98,4 @@ export default defineConfig({
 });
 ```
 
-## 使用 [`Twin`](https://github.com/ben-rogerson/twin.macro) 库
-
-在上一章中介绍了什么是 CSS-in-JS 以及社区常用的 CSS-in-JS 库 [styled-components](https://styled-components.com/)。这一部分将要介绍如何通过 [`Twin`](https://github.com/ben-rogerson/twin.macro) 在 CSS-in-JS 中使用 [Tailwind CSS](https://tailwindcss.com/)。使用 [`Twin`](https://github.com/ben-rogerson/twin.macro) 可以更容易在 CSS-in-JS 的代码中使用 Tailwind CSS。[`Twin`](https://github.com/ben-rogerson/twin.macro) 对于自己的描述是：
-
-> *Twin blends the magic of Tailwind with the flexibility of css-in-js*
-
-在开启「Tailwind CSS 支持」的功能后，首先需要安装 [`Twin`](https://github.com/ben-rogerson/twin.macro) 依赖:
-
-``` bash
-pnpm add twin.macro -D
-```
-
-当项目安装 `twin.macro` 依赖后，Modern.js 会检测到该依赖并对内置的 `babel-plugin-macro` 增加 `twin.macro` 相关的配置。因此在安装完依赖后，无需手动配置。下面是一个简单使用 `twin.macro` 的示例：
-
-``` js
-import tw from 'twin.macro'
-
-const Input = tw.input`border hover:border-black`
-```
-
-:::tip 提示
-如果在运行过程中出现了 `MacroError: /project/App.tsx` 错误的时候，有可能是缺少 `twin.macro` 依赖导致的。
-:::
-
-更多的使用方式可以参考 `twin.macro` 的 [文档](https://github.com/ben-rogerson/twin.macro/blob/master/docs/index.md)。
-
-`twin.macro` 默认会读取项目目录下的 `tailwindcss.config.js` 文件，或者通过 `babel-plugin-macro` 上的 [`twin.config`](https://github.com/ben-rogerson/twin.macro/blob/master/docs/options.md#options) 指定的文件路径读取 Tailwind CSS 配置。不过在 Modern.js 中不需要进行这些额外配置。
-
-当在 `modern.config.ts` 文件中通过 [`source.designSystem`](/docs/configure/app/source/design-system) 和  [`tools.tailwindcss`](/docs/configure/app/tools/tailwindcss) 对 Tailwind CSS 进行配置的时候，这些配置也会对 `twin.macro` 生效。
-> 当为项目配置 Tailwind CSS 的时候，[`source.designSystem`](/docs/configure/app/source/design-system) 和  [`tools.tailwindcss`](/docs/configure/app/tools/tailwindcss) 这两个配置的组合等价于单独配置了一个 `tailwindcss.config.js` 文件。
-> 其中[`source.designSystem`](/docs/configure/app/source/design-system)等效于 Tailwind CSS 的 [`theme`](https://v2.tailwindcss.com/docs/configuration#theme) 配置。
-
-
+> 当你为项目配置 Tailwind CSS 的时候，[source.designSystem](/docs/configure/app/source/design-system) 和 [tools.tailwindcss](/docs/configure/app/tools/tailwindcss) 这两个配置的组合等价于单独配置了一个 `tailwindcss.config.js` 文件。其中 [source.designSystem](/docs/configure/app/source/design-system) 等效于 Tailwind CSS 的 [theme](https://v2.tailwindcss.com/docs/configuration#theme) 配置。