@modern-js/main-doc 2.0.0-beta.2 → 2.0.0-beta.3

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

@@ -1,11 +1,11 @@
 ---
-title: 服务端渲染
+title: 服务端渲染（SSR）
 sidebar_position: 3
 ---
 
-在 Modern.js 中，和 Web Server 一样，SSR 服务与应用也是一体的，开发者无需为 SSR 编写复杂的服务端逻辑。同样，开发者也无需关心 SSR 服务的运维，Modern.js 拥有完备的 SSR 降级策略，保证页面能够安全运行。
+在 Modern.js 中，SSR 也是开箱即用的。开发者无需为 SSR 编写复杂的服务端逻辑，也无需关心 SSR 的运维，或是创建单独的服务。Modern.js 拥有完备的 SSR 降级策略，保证页面能够安全运行。
 
-Modern.js 启用 SSR 非常简单，只需要设置 [`server.ssr`](/docs/configure/app/server/ssr) 为 `true` 即可：
+启用 SSR 非常简单，只需要设置 [`server.ssr`](/docs/configure/app/server/ssr) 为 `true` 即可：
 
 ```json title="package.json"
 {
@@ -15,9 +15,9 @@ Modern.js 启用 SSR 非常简单，只需要设置 [`server.ssr`](/docs/configu
 }
 ```
 
-## SSR 时的数据请求
+## SSR 时的数据获取
 
-Modern.js 中提供了 `useLoader` Hooks API，可以在某些场景下代替 `useEffect` 进行数据请求。这是一个同构的 API，直接使用它即可完成在服务端的数据获取：
+Modern.js 中提供了 [`useLoader`](/docs/apis/app/runtime/core/use-loader) Hooks API，用于在 SSR 环境下同构的获取数据：
 
 ```ts
 const { data, loading, error } = useLoader(() => {
@@ -30,16 +30,14 @@ Modern.js 打破传统的 SSR 开发模式，提供了用户无感的 SSR 开发
 不过，开发者仍然需要关注数据的兜底处理，例如 `null` 值或不符合预期的数据返回。避免在 SSR 时产生 React 渲染错误或是返回凌乱的渲染结果。
 
 :::info 补充信息
-关于 `useLoader` 的详细介绍可以参考[这里](/docs/apis/app/runtime/core/use-loader)。
+更多相关内容可以查看[数据获取](/docs/guides/basic-features/data-fetch)。
 :::
 
 ## 保持渲染一致
 
-代码中区分 SSR 和 CSR 渲染，通常需要根据当前的运行容器环境特征做判断，例如 [UA](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) 信息或是某个 Native 模块。如果处理不够仔细，此时很有可能出现不符合预期的渲染结果。
+有些业务中，通常需要根据当前的运行容器环境特征做不同的 UI 展示，例如 [UA](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) 信息。如果处理不够仔细，此时很有可能出现不符合预期的渲染结果。
 
-这里通过一个例子，演示当 SSR 与 CSR 渲染不一致时出现的问题。
-
-在组件中添加以下代码：
+这里通过一个例子，演示当 SSR 与 CSR 渲染不一致时出现的问题，在组件中添加以下代码：
 
 ```tsx
 {
@@ -57,7 +55,7 @@ Modern.js 打破传统的 SSR 开发模式，提供了用户无感的 SSR 开发
 Warning: Expected server HTML to contain a matching <div> in <div>.
 ```
 
-这是因为 React 在客户端执行注水逻辑时，发现渲染结果与 SSR 渲染结果不一致造成的。虽然页面表现正常，但在复杂应用中，很有可能因此出现 DOM 层级混乱、样式混乱等问题。
+这是 React 在客户端执行注水逻辑时，发现渲染结果与 SSR 渲染结果不一致造成的。虽然页面表现正常，但在复杂应用中，很有可能因此出现 DOM 层级混乱、样式混乱等问题。
 
 :::info 注
 关于注水逻辑请参考[这里](https://reactjs.org/docs/react-dom.html#hydrate)。
@@ -184,3 +182,68 @@ import { PreRender } from '@modern-js/runtime/ssr';
 :::info 补充信息
 `PreRender` 的详细使用可以参考[这里](/docs/apis/app/runtime/ssr/pre-render)。
 :::
+
+## Treeshaking
+
+开启 SSR 时，Modern.js 会用相同的入口，构建出 SSR Bundle 和 CSR Bundle 两份产物。因此，在 SSR Bundle 中存在 Web API，或是在 CSR Bundle 中存在 Node API 时，都可能导致运行出错。
+
+### 环境变量区分
+
+在组件中可以直接使用 Modern.js 内置的环境变量 `MODERN_TARGET` 进行判断，方便在构建时删除无用代码：
+
+```ts
+export default () => {
+  if (process.env.MODERN_TARGET === 'node') {
+    console.log('server render');
+  } else {
+    console.log('client render');
+  }
+}
+```
+
+:::note
+更多内容可以查看[环境变量](/docs/guides/basic-features/env-vars)。
+:::
+
+### 文件后缀区分
+
+但有时，这种 Treeshaking 的方式并不能保证代码被完全分离。EdenX 也支持通过 `.node.` 后缀的文件来区分 SSR Bundle 和 CSR Bundle 产物的打包文件。
+
+例如存在 `client-sdk` 中直接使用了 Web API：
+
+```ts
+// client-sdk
+export const href = location.href;
+```
+
+这时候直接引用到组件中，会造成 SSR 报错。可以创建同名的 `.ts` 和 `.node.ts` 文件做一层代理：
+
+```ts title="compat.ts"
+export { href } from 'client-sdk';
+```
+
+```ts title="compat.node.ts"
+export const href = '';
+```
+
+在文件中直接引入 `./compat`，此时 SSR 环境下会优先使用 `.node.ts` 后缀的文件，CSR 环境下会使用 `.ts` 后缀的文件。
+
+```ts title="App.tsx"
+import { href } from './compat'
+
+export default () => {
+  return <div onClick={() => { console.log(href) }}></div>
+}
+```
+
+### 独立文件
+
+上述两种方式，都会为开发者带来一些心智负担。Modern.js 正在基于[嵌套路由](/docs/guides/basic-features/routes)开发设计[更简单的方案](/docs/guides/basic-features/data-fetch)来分离 CSR 和 SSR 的代码。
+
+## 接口请求
+
+在 SSR 中发起接口请求时，开发者有时自己封装了同构的请求工具。部分接口需要传递用户 Cookie，开发者可以通过 [`useRuntimeContext`](/docs/guides/basic-features/data-fetch#route-loader) API 获取到请求头来实现。
+
+需要注意的是，此时获取到的是 HTML 请求的请求头，不一定适用于接口请求，因此**千万不能**透传所有请求头。并且，一些后端接口，或是通用网关，会根据请求头中的信息做校验，全量透传容易出现各种难以排查的问题，推荐**按需透传**。
+
+如果实在需要透传所有请求头，请务必过滤 `host` 字段。

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

@@ -0,0 +1,46 @@
+---
+title: 构建能力
+sidebar_position: 2
+---
+
+**Modern.js 的构建能力由 [Modern.js Builder](https://modernjs.dev/builder) 提供。**
+
+Modern.js Builder 是 Modern.js 体系的核心组件之一，它是一个面向现代 Web 开发场景的构建引擎，可以脱离 Modern.js 被独立使用。Modern.js Builder 同时支持 webpack 和 rspack 等多种打包工具，默认情况下使用最成熟的 webpack 进行打包。
+
+## 构建架构
+
+从构建的角度看，Modern.js 分为三层架构，从上到下依次是：
+
+- 上层研发框架：Modern.js。
+- 通用构建引擎：Modern.js Builder。
+- 底层打包工具：webpack 和 rspack。
+
+<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/builder-layers-1117.png" style={{ maxWidth: '540px' }} />
+
+## 构建文档
+
+由于 Modern.js Builder 是一个可独立使用的模块，我们为它提供了单独的文档，文档地址为：[modernjs.dev/builder](https://modernjs.dev/builder)。
+
+在该文档中，你可以了解到 Modern.js Builder 的详细介绍，同时也可以找到各个构建能力的完整使用指南。当你遇到构建方面的需求或问题时，建议你优先阅读 Modern.js Builder 文档来解决。
+
+## 构建配置
+
+Modern.js 的配置继承自 Modern.js Builder，因此你可以在 Modern.js 中使用 Modern.js Builder 提供的所有构建配置。
+
+以 Modern.js Builder 的 `html.title` 配置项为例，你可以直接在 `modern.config.ts` 文件中使用该配置项，它会被自动传递给 Modern.js Builder。
+
+```ts title="modern.config.js"
+export default defineConfig({
+  html: {
+    title: 'example',
+  },
+});
+```
+
+关于构建配置的详细说明，请参考 [「Modern.js Builder - Builder 配置」](https://modernjs.dev/builder/zh/guide/basic/builder-config.html)。
+
+## 构建能力
+
+Modern.js Builder 提供了丰富的构建能力，包括 JavaScript 编译、CSS 编译、静态资源处理、代码热更新、代码压缩、TS 类型检查等几十种能力。
+
+我们推荐你阅读 [「Modern.js Builder - 功能导航」](https://modernjs.dev/builder/zh/guide/features.html) 来了解 Modern.js Builder 提供的所有构建能力。

package/zh/guides/basic-features/css/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "CSS 开发方案",
-  "position": 3
+  "position": 4
 }

package/zh/guides/basic-features/css/less-sass.md

@@ -4,20 +4,7 @@ sidebar_position: 4
 
 # Less 和 Sass
 
-[Less](https://lesscss.org/) 和 [Sass](https://sass-lang.com/) 是常用的两种 CSS 预处理器，Modern.js 通过插件来提供 Less 和 Sass 编译能力的支持。
-
-## 启用 Less 或 Sass
-
-为了使用 Less 或 Sass 编译能力，我们需要先启用对应的功能。
-
-以 Less 为例，在当前项目根目录执行 new 命令, 并选择 **启用 Less 支持** 即可。
-
-```bash
-$ pnpm run new
-? 请选择你想要的操作
-? 启用可选功能 (Use arrow keys)
-❯ 启用 Less 支持
-```
+[Less](https://lesscss.org/) 和 [Sass](https://sass-lang.com/) 是常用的两种 CSS 预处理器，Modern.js 内置了 Less 和 Sass 编译能力的支持。
 
 ## 自定义配置
 

package/zh/guides/basic-features/data-fetch.md

@@ -1,6 +1,6 @@
 ---
 title: 数据获取
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 Modern.js 中提供了开箱即用的数据获取能力，开发者可以通过这些 API，在 CSR 和 SSR 环境同构的进行开发。

package/zh/guides/basic-features/env-vars.md

@@ -23,6 +23,40 @@ Modern.js 提供了对环境变量的支持，包含内置的环境变量和自
 MODERN_ENV 的优先级高于 NODE_ENV。
 :::
 
+### MODERN_TARGET
+
+使用 `@modern-js/runtime` 时会自动注入，用于区分 SSR 与 CSR 环境。开发者可以自行在代码中判断，构建时会默认移除 dead code。
+
+```ts title="App.tsx"
+function App() {
+  if (process.env.MODERN_TARGET === 'browser') {
+    console.log(window.innerHeight);
+  };
+};
+```
+
+开发环境打包后，可以看到 SSR 产物和 CSR 产物如下：
+
+```js title="dist/bundles/main.js"
+function App() {
+  if (false) {}
+}
+```
+
+```js title="dist/static/main.js"
+function App() {
+  if (true) {
+    console.log(window.innerHeight);
+  }
+}
+```
+
+:::note
+在生产环境，会将 dead code 移除，例如上述 `if` 语句。
+:::
+
+这种方式可以针对不同客户端提供不同的产物，保证代码体积最小化。也能方便处理不同环境下，代码中的一些副作用，
+
 ## 自定义环境变量
 
 环境变量支持通过 `shell` 和 `.env` 文件两种方式指定。

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

@@ -3,7 +3,7 @@ title: 路由
 sidebar_position: 1
 ---
 
-Modern.js 内置了对 [React Router 6](https://reactrouter.com/en/main) 的**部分**支持，并提供了多种类型的路由模式。根据不同[入口](/docs/guides/concept/entries)类型，将路由分为三种模式，分别是**约定式路由**，**自控式路由**和**配置式路由**。
+Modern.js 内置了对 [React Router 6](https://reactrouter.com/en/main) 的**部分**支持，并提供了多种类型的路由模式。根据不同[入口](/docs/guides/concept/entries)类型，将路由分为三种模式，分别是**约定式路由**，**自控式路由**和**其他路由方案**。
 
 :::note
 本小节提到的路由，都是客户端路由，即 SPA 路由。
@@ -219,40 +219,21 @@ export default const ErrorBoundary = () => {
 
 ## 自控式路由
 
-以 `routes/` 为约定的入口，Modern.js 不会多路由做额外的操作，开发者可以自行使用 React Router 6 的 API 进行开发。
-
-例如：
+以 `src/App.tsx` 为约定的入口，Modern.js 不会多路由做额外的操作，开发者可以自行使用 React Router 6 的 API 进行开发，例如：
 
 ```tsx
-import {
-  Route,
-  Routes,
-  BrowserRouter,
-  Outlet,
-} from '@modern-js/runtime/router';
+import { Route, Routes, BrowserRouter } from '@modern-js/runtime/router';
+import { StaticRouter } from '@modern-js/runtime/router/server';
 
+const Router = typeof window === 'undefined' ? StaticRouter : BrowserRouter;
 export default () => {
   return (
-    <div>
-      <BrowserRouter>
-        <Routes>
-          <Route index element={<div>index</div>} />
-          <Route
-            path="user"
-            element={
-              <div>
-                User Layout
-                <Outlet />
-              </div>
-            }
-          >
-            <Route index element={<div>user</div>} />
-            <Route path="profile" element={<div>profile</div>} />
-          </Route>
-          <Route path="about" element={<div>about</div>} />
-        </Routes>
-      </BrowserRouter>
-    </div>
+    <Router location={context.request.pathname}>
+      <Routes>
+        <Route index element={<div>index</div>} />
+        <Route path="about" element={<div>about</div>} />
+      </Routes>
+    </Router>
   );
 };
 ```
@@ -261,11 +242,27 @@ export default () => {
 在自控式路由下，开发者如果希望在 SSR 中使用 React Router 6 中 [Loader API](https://reactrouter.com/en/main/hooks/use-loader-data#useloaderdata) 的能力会相对复杂，推荐直接使用约定式路由。Modern.js 已经为你封装好了一切。
 
 <!-- Todo 嵌套路由带来的优化可以补充下文档-->
-如果项目只想升级到 React Router 6，而不希望使用嵌套路由带来的优化，那[useLoader](/docs/apis/app/runtime/core/use-loader) 在 SSR 下仍然可以工作。
+如果项目只想升级到 React Router 6，而不希望使用嵌套路由带来的优化，那 [useLoader](/docs/apis/app/runtime/core/use-loader) 在 SSR 下仍然可以工作。
 :::
 
-## 配置式路由
+## 其他路由方案
 
-:::note
-敬请期待
-:::
+默认情况下，Modern.js 会开启内置的路由方案，即 React Router。
+
+```js
+export default defineConfig({
+  runtime: {
+    router: true,
+  }
+})
+```
+
+Modern.js 从 `@modern-js/runtime/router` 命名空间暴露了 React Router 的 API 供开发者使用，保证开发者和 Modern.js 中使用同一份代码。另外，这种情况下，React Router 的代码会被打包到 JS 产物中。如果项目已经有自己的路由方案，或者不需要使用客户端路由，可以关闭这个功能。
+
+```js
+export default defineConfig({
+  runtime: {
+    router: false,
+  }
+})
+```

package/zh/guides/concept/entries.md

@@ -91,13 +91,13 @@ Modern.js 会将和 `package.json` 中 `name` 同名的目录作为主入口，
 
 如果入口为 `routes/` 约定，Modern.js 会在启动时扫描 `routes` 下的文件，基于文件约定，自动生成客户端路由（react-router）。
 
-详细内容可以参考[路由](/docs/guides/basic-features/routes).
+详细内容可以参考[路由](/docs/guides/basic-features/routes)。
 
 ### App 入口
 
 如果入口为 `App.[jt]sx?` 约定，开发者可以在这个文件中自由的设置客户端路由，或者不设置客户端路由。
 
-详细内容可以参考[路由](/docs/guides/basic-features/routes).
+详细内容可以参考[路由](/docs/guides/basic-features/routes)。
 
 ### Index 入口
 
@@ -105,12 +105,12 @@ Modern.js 会将和 `package.json` 中 `name` 同名的目录作为主入口，
 
 如果入口为 `index.[jt]sx?` 约定，Modern.js 会根据该文件是否存在默认的组件导出，来决定构建行为。
 
-详细内容可以参考[自定义 App](/docs/guides/advanced-features/custom-app).
+详细内容可以参考[自定义 App](/docs/guides/advanced-features/custom-app)。
 
 ## 配置入口
 
 在 Modern.js 中，除了使用文件约定生成入口外，还可以在 `modern.config.[jt]s` 中手动配置入口。
 
 :::tip
-详情可以查看 [source.entries](/docs/configure/app/source/entries).
+详情可以查看 [source.entries](/docs/configure/app/source/entries)。
 :::

package/zh/guides/topic-detail/framework-plugin/extend.md

@@ -1,10 +1,9 @@
 ---
-sidebar_position: 4
+title: 扩展插件 Hook
+sidebar_position: 5
 ---
 
-# 扩展插件 Hook
-
-本章节介绍如何通过动态注册 [Hook 模型](/docs/apis/app/runtime/plugin/hook#hook-模型) 的方式来扩展插件 Hook。
+本小节介绍如何通过动态注册 [Hook 模型](/docs/guides/topic-detail/framework-plugin/hook) 的方式来扩展插件 Hook。
 
 ## 示例