@modern-js/main-doc 0.0.0-next-20221203140534 → 0.0.0-next-20221205074243

package/zh/configure/app/output/ssg.md

@@ -3,15 +3,13 @@ sidebar_label: ssg
 ---
 # output.ssg
 
-
-
 * 类型： `boolean` | `object` | `function`
 * 默认值： `undefined`
 
 开启**自控式路由**或**约定式路由** SSG 功能的配置。
 
 :::info 客户端路由
-相关内容可以查看[自控式路由](/docs/tutorials/first-app/c08-client-side-routing/8.1-code-based-routing)或[约定式路由](/docs/tutorials/first-app/c08-client-side-routing/8.2-file-based-routing)。
+相关内容可以查看[路由](/docs/guides/basic-features/routes)。
 :::
 
 ## 示例
@@ -20,115 +18,134 @@ sidebar_label: ssg
 
 当该配置设置为 `true` 时，将会默认开启所有入口的 SSG 功能。
 
-对**自控式路由**而言，将会渲染入口路由。对**约定式路由**而言，将会渲染入口中每一条客户端路由。
+对**自控式路由**而言，将会渲染入口的根路由。对**约定式路由**而言，将会渲染入口中每一条路由。
 
 例如 `src/` 目录下有以下满足**约定式路由**的文件结构：
 
 ```bash
 .
-├── pages/
-│   ├── user/
-│   │   └── info.tsx
-│   ├── home.tsx
-│   └── index.tsx
-├── .eslintrc.json
+├── src
+│   └── routes
+│       ├── layout.tsx
+│       ├── page.tsx
+│       └── user
+│           ├── layout.tsx
+│           ├── page.tsx
+│           └── profile
+│               └── page.tsx
 ```
 
 在 `modern.js.config` 中做以下设置：
 
 ```js
-module.exports = {
+export default defineConfig({
   output: {
     ssg: true,
   },
-};
+});
 ```
 
-执行 `pnpm build` 构建应用后。`dist/` 目录将会生成三张 HTML 分别对应三条路由（不开启 SSG 时只有一张 HTML 对应主入口），并且可以看到所有 HTML 都已经是渲染之后的。
+执行 `pnpm build` 构建应用后。`dist/` 目录将会生成三张 HTML 分别对应三条路由（不开启 SSG 时只有一张 HTML），并且所有 HTML 都已经渲染。
 
 而例如下面的**自控式路由**：
 
-```ts title="App.tsx"
-import { Switch, Route } from '@modern-js/runtime/router';
-
-export default () => (
-  <Switch>
-    <Route path="/" exact={true}>
-      <div>Home</div>
-    </Route>
-    <Route path="/foo" exact={true}>
-      <div>Foo</div>
-    </Route>
-  </Switch>
-);
+```tsx title="App.tsx"
+import { useRuntimeContext } 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();
+  return (
+    <Router location={context.request.pathname}>
+      <Routes>
+        <Route index element={<div>index</div>} />
+        <Route path="about" element={<div>about</div>} />
+      </Routes>
+    </Router>
+  );
+};
 ```
 
-同样使用上面的配置，在执行 `pnpm build` 后，只有入口路由 `/` 会生成渲染后的 HTML。
+同样使用上面的配置，在执行 `pnpm run build` 后，只有入口路由 `/` 会生成渲染后的 HTML。
 
 ### 多入口
 
+:::note
+多入口 SSG 暂未支持，敬请期待。
+:::
+
 `output.ssg` 也可以按照入口配置，配置生效的规则同样由入口路由方式决定。
 
 例如以下目录结构：
 
 ```bash
-.
-├── src/
-│   ├── contacts/
-│   │   └── App.tsx
-│   ├── landing-page/
-│   │   └── pages/
-│   │       ├── [user].tsx
-│   │       ├── docs.tsx
-│   │       └── index.tsx
+。
+├── src
+│   ├── entryA
+│   │   └── routes
+│   │       ├── layout.tsx
+│   │       ├── page.tsx
+│   │       └── user
+│   │           ├── layout.tsx
+│   │           ├── page.tsx
+│   │           └── profile
+│   │               └── page.tsx
+│   └── entryB
+│       └── App.tsx
 ```
 
-默认情况下，所有约定式路由的入口，在设置 `output.ssg` 配置后都会在构建阶段渲染，可以配置 `false` 来取消指定入口的的默认行为，例如取消上述 landing-page 入口在构建时的渲染：
+默认情况下，所有约定式路由的入口，在设置 `output.ssg` 配置为 `true` 后都会在构建阶段渲染。可以配置 `false` 来取消指定入口的的默认行为，例如取消上述 entryA 入口在构建时的渲染：
 
 ```js
-module.exports = {
+export default defineConfig({
   output: {
     ssg: {
-      contacts: true,
-      'landing-page': false,
+      entryA: true,
+      entryB: false,
     },
   },
-};
+});
 ```
 
 ### 配置路由
 
 上述内容中提到，**自控式路由**默认只会开启入口路由的 SSG 配置。
 
-可以在 `output.ssg` 中设置具体的路由，告知 Modern.js 开启这些客户端路由的 SSG 功能。例如上述 `contacts/App.tsx` 的文件内容为：
-
-```ts title="contacts/App.tsx"
-import { Switch, Route } from '@modern-js/runtime/router';
-
-export default () => (
-  <Switch>
-    <Route path="/" exact={true}>
-      <div>Home</div>
-    </Route>
-    <Route path="/foo" exact={true}>
-      <div>Foo</div>
-    </Route>
-  </Switch>
-);
+可以在 `output.ssg` 中设置具体的路由，告知 Modern.js 开启这些客户端路由的 SSG 功能。例如上述 `src/App.tsx` 的文件内容为：
+
+```tsx title="src/App.tsx"
+import { useRuntimeContext } 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();
+  return (
+    <Router location={context.request.pathname}>
+      <Routes>
+        <Route index element={<div>index</div>} />
+        <Route path="about" element={<div>about</div>} />
+      </Routes>
+    </Router>
+  );
+};
 ```
 
-在 `modern.config.js` 中这样设置后，`/foo` 路由也会开启 SSG 功能：
+在 `modern.config.js` 中这样设置后，`/about` 路由也会开启 SSG 功能：
 
 ```js
-module.exports = {
+export default defineConfig({
   output: {
     ssg: {
-      contacts: {
-        routes: ['/', '/foo'],
-      },
+      routes: ['/', '/about'],
     },
   },
-};
+});
 ```
 
 Modern.js 将会自动根据入口拼接完整的 URL 并交给 SSG 插件完成渲染。
@@ -136,22 +153,20 @@ Modern.js 将会自动根据入口拼接完整的 URL 并交给 SSG 插件完成
 也可以为具体入口或路由配置请求头，例如：
 
 ```js
-module.exports = {
+export default defineConfig({
   output: {
     ssg: {
-      contacts: {
-        headers: {},
-        routes: [
-          '/',
-          {
-            url: '/foo',
-            headers: {},
-          },
-        ],
-      },
+      headers: {},
+      routes: [
+        '/',
+        {
+          url: '/about',
+          headers: {},
+        },
+      ],
     },
   },
-};
+});
 ```
 
 :::info
@@ -160,67 +175,56 @@ module.exports = {
 
 ### 阻止默认行为
 
-**约定式路由**也可以通过配置的方式来开启指定路由的 SSG。
-
-但因为默认行为的不同，这里为**约定式路由**提供了另一个字段，用来阻止默认的 SSG 行为。
+默认情况下，**约定式路由**的路由会全部开启 SSG。Modern.js 提供了另一个字段，用来阻止默认的 SSG 行为。
 
-例如以下目录结构，除了 `/docs4` 外的所有 landing-page 入口中的路由都开启 SSG：
+例如以下目录结构，`/`、`/user`、`/user/profle` 三条路由都开启 SSG：
 
 ```bash
 .
-├── src/
-│   ├── contacts/
-│   │   └── App.tsx
-│   ├── landing-page/
-│   │   └── pages/
-│   │       ├── [user].tsx
-│   │       ├── docs.tsx
-│   │       ├── docs1.tsx
-│   │       ├── docs2.tsx
-│   │       ├── docs3.tsx
-│   │       ├── docs4.tsx
-│   │       └── index.tsx
+├── src
+│   └── routes
+│       ├── layout.tsx
+│       ├── page.tsx
+│       └── user
+│           ├── layout.tsx
+│           ├── page.tsx
+│           └── profile
+│               └── page.tsx
 ```
 
 可以这样设置，禁用某一条客户端路由的默认行为：
 
-:::info 注
-该配置仅在渲染动态路径的约定式路由时使用。
-:::
-
 ```js
-module.exports = {
+export default defineConfig({
   output: {
-    'landing-page': {
-      preventDefault: ['/docs4'],
-    },
+    preventDefault: ['/user'],
   },
-};
+});
 ```
 
 ### 添加动态路由参数
 
-部分路由可能是动态的，例如自控式路由中的 `/user/:id` 或是约定式路由中 `user/[id].ts` 文件生成的路由。
+部分路由可能是动态的，例如自控式路由中的 `/user/:id` 或是约定式路由中 `user/[id]/page.tsx` 文件生成的路由。
 
 可以在 `output.ssg` 中配置具体的参数，渲染指定参数的路由，例如：
 
 ```js
-module.exports = {
+export default defineConfig({
   output: {
     ssg: {
-      'landing-page': {
-        routes: [
-          {
-            url: '/user/:id',
-            params: [
-              {
-                id: 'modernjs',
-              },
-            ],
-          },
-        ],
-      },
+      routes: [
+        {
+          url: '/user/:id',
+          params: [
+            {
+              id: 'modernjs',
+            },
+          ],
+        },
+      ],
     },
   },
-};
+});
 ```
+
+动态路由和 SSG 的组合，在根据 CMS 系统数据变更，实时生成静态页面时非常有用。

package/zh/configure/app/server/ssr.md

@@ -4,8 +4,6 @@ sidebar_label: ssr
 
 # server.ssr
 
-
-
 * 类型： `boolean`
 * 默认值： `false`
 

package/zh/guides/advanced-features/custom-app.md

@@ -9,17 +9,23 @@ sidebar_position: 7
 
 ## 添加自定义行为
 
-当 `index` 文件默认导出**函数**是，Modern.js 还是会根据 `runtime.features` 的设置情况生成 `createApp` 包裹后的代码。在渲染过程中，将 `createApp` 包裹后的组件作为参数传递给 `index` 文件导出的函数，这样开发者可以自定义将组件挂载到 DOM 节点上，或在挂载前添加自定义行为。例如：
+当 `index` 文件默认导出**函数**是，Modern.js 还是会根据 `runtime` 的设置情况生成 `createApp` 包裹后的代码。在渲染过程中，将 `createApp` 包裹后的组件作为参数传递给 `index` 文件导出的函数，这样开发者可以自定义将组件挂载到 DOM 节点上，或在挂载前添加自定义行为。例如：
 
 ```js title=src/index.jsx
+import ReactDOM from 'react-dom/client'
 import { bootstrap } from '@modern-js/runtime';
 
+
 export default App => {
   // do something before bootstrap...
-  bootstrap(App, 'root');
+  bootstrap(App, 'root', undefined, ReactDOM);
 };
 ```
 
+:::warning
+由于 bootstrap 函数需要兼容 React17 和 React18 的用法，调用 bootstrap 函数时需要手动传入 ReactDOM 参数。
+:::
+
 Modern.js 生成的文件内容如下：
 
 ```js

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

@@ -1,5 +1,5 @@
 ---
-title: 静态站点生成
+title: 静态站点生成（SSG）
 sidebar_position: 4
 ---
 
@@ -9,11 +9,11 @@ SSG（Static Site Generation）是一种基于数据与模板，在构建时渲
 SSG 是构建阶段的解决方案，因此仅对生产环境有效。通过 `dev` 命令运行时，表现效果与 SSR 相同。
 :::
 
-我们首先需要执行`pnpm run new`启用 SSG 功能：
+我们首先需要执行 `pnpm run new` 启用 SSG 功能：
 
 ```bash
-? 请选择你想要的操作 启用可选功能
-? 启用可选功能 启用「SSG」功能
+? 请选择你想要的操作： 启用可选功能
+? 启用可选功能： 启用「SSG」功能
 ```
 
 SSG 在**约定式路由**和**自控式路由**下的使用方式不同。
@@ -25,22 +25,37 @@ SSG 在**约定式路由**和**自控式路由**下的使用方式不同。
 例如，以下是一个使用约定式路由的项目目录结构：
 
 ```
-├── src/
-│   ├── pages/
-│   │   ├── home.tsx
-│   │   ├── info.tsx
-│   │   └── index.tsx
+.
+├── src
+│   └── routes
+│       ├── layout.tsx
+│       ├── page.tsx
+│       └── user
+│           ├── layout.tsx
+│           ├── page.tsx
+│           └── profile
+│               └── page.tsx
 ```
 
-在 `src/pages/index.tsx` 中添加组件代码：
+上述文件目录将会生成以下三条路由：
+
+- `/`
+- `/user`
+- `/user/profile`
+
+:::note
+如果还不了解约定式路由的规则，可以先查看[路由](/docs/guides/basic-features/routes)。
+:::
+
+在 `src/routes/page.tsx` 中添加组件代码：
 
 ```jsx title="src/pages/index.tsx"
 export default () => {
-  return  <div>index page</div>
+  return  <div>Index Page</div>
 }
 ```
 
-SSG 和 SSR 一样，也是在 Node.js 环境中完成页面渲染，因此我们可以在开发阶段开启 SSR，提前在开发阶段验证 SSG 渲染效果：
+SSG 也是在 Node.js 环境渲染页面，因此我们可以在**开发阶段开启 SSR**，提前在暴露代码问题，验证 SSG 渲染效果：
 
 ```typescript title="modern.config.ts"
 export default defineConfig({
@@ -50,13 +65,11 @@ export default defineConfig({
 }
 ```
 
-在项目根路径下执行 `pnpm run dev` 命令，查看 `dist/` 目录，此时只生成一个 HTML 文件：
-
-![vsc-alert](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ssg-dev.png)
+在项目根路径下执行 `pnpm run dev` 命令，查看 `dist/` 目录，此时只生成一个 HTML 文件 `main/index.html`。
 
-在项目根路径下执行 `pnpm run build` 命令，构建完成后，查看 `dist/` 目录，此时生成 `main/index.html`、`main/home/index.html` 和 `main/info/index.html` 3 个 HTML 文件，分别对应 `/`、`/home`、`/info` 3 个约定式路由，可见**约定式路由**中的每一条路由，都会生成一个单独的 HTML 文件。查看 `main/index.html`，可以发现包含 `index page` 的文本内容，这正是 SSG 的效果。
+在项目根路径下执行 `pnpm run build` 命令，构建完成后，查看 `dist/` 目录，此时生成 `main/index.html`、`main/user/index.html` 和 `main/user/profile/index.html` 三个 HTML 文件，内容分别对应上述三条路由。
 
-![vsc-alert](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ssg-build.png)
+**约定式路由**中的每一条路由，都会生成一个单独的 HTML 文件。查看 `main/index.html`，可以发现包含 `Index Page` 的文本内容，这正是 SSG 的效果。
 
 执行 `pnpm run start` 启动项目后，访问页面，在浏览器我们工具的 Network 窗口，查看请求返回的文档，文档包含组件渲染后的完整页面内容。
 
@@ -64,45 +77,46 @@ export default defineConfig({
 
 **自控式路由**是通过组件代码自定义路由，需要应用运行起来才能获取准确的路由信息。因此，无法开箱即用的使用 SSG 功能。此时需要用户提前告知 Modern.js 框架，哪些路由需要开启 SSG 功能。
 
-例如有以下代码：
-
-```ts
-import { Switch, Route } from '@modern-js/runtime/router';
-
-export default () => (
-  <Switch>
-    <Route path="/" exact={true}>
-      <div>Home</div>
-    </Route>
-    <Route path="/foo" exact={true}>
-      <div>Foo</div>
-    </Route>
-  </Switch>
-);
-```
+例如有以下代码，包含多条路由，设置 `output.ssg` 为 `true` 时，默认只会渲染入口路由即 `/`：
+
+```tsx title="src/App.tsx"
+import { useRuntimeContext } from '@modern-js/runtime';
+import { Routes, Route, BrowserRouter } from '@modern-js/runtime/router';
+import { StaticRouter } from '@modern-js/runtime/router/server';
 
-希望为 `/foo` 路由开启 SSG 功能，同样利用 `output.ssg` 配置。该参数允许配置页面信息，告知 Modern.js 开启指定路由的 SSG 功能。
+const Router = typeof window === 'undefined' ? StaticRouter : BrowserRouter;
+
+export default () => {
+  const { context } = useRuntimeContext();
+  return (
+    <Router location={context.request.pathname}>
+      <Routes>
+        <Route index element={<div>index</div>} />
+        <Route path="about" element={<div>about</div>} />
+      </Routes>
+    </Router>
+  );
+};
+```
 
-例如上述入口中，包含两条客户端路由，分别是 `/` 和 `/foo`，设置 `output.ssg` 为 `true` 时，默认只会渲染入口路由即 `/`。如果我们希望同时开启 `/foo` 的 SSG 功能，可以这样配置：
+如果我们希望同时开启 `/about` 的 SSG 功能，可以配置 `output.ssg`，告知 Modern.js 开启指定路由的 SSG 功能。
 
 ```typescript title="modern.config.ts"
 export default defineConfig({
   output: {
     ssg: {
-      routes: ['/', '/foo'],
+      routes: ['/', '/about'],
     },
   },
 })
 ```
 
-执行 `pnpm run build` 与 `pnpm run start` 后，访问 `http://localhost:8080/foo`，在 Preview 视图中可以看到页面已经完成渲染。
-
-查看构建产物文件，可以看到 `dist/` 目录中，在默认的 `main` 入口产物目录下，新增一个 `foo.html` 文件：
+执行 `pnpm run build` 与 `pnpm run start` 后，访问 `http://localhost:8080/about`，在 Preview 视图中可以看到页面已经完成渲染。
 
-![vsc-alert](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ssg-foo.png)
+查看构建产物文件，可以看到 `dist/` 目录中，新增了一个 `main/about/index.html` 文件。
 
 :::info
-以上仅介绍了单入口的情况，与部分配置。更多相关内容可以查看 [API 文档](/docs/configure/app/output/ssg)。
+以上仅介绍了单入口的情况，更多相关内容可以查看 [API 文档](/docs/configure/app/output/ssg)。
 :::
 
 ### 获取数据
@@ -116,36 +130,33 @@ export default defineConfig({
 - 在开发阶段，不管 `useLoader` 是否配置 `{ static: true }`，函数都会在 SSR 时获取数据。
 :::
 
-修改上述 `App.ts` 的代码为：
+修改上述 `src/App.ts` 的代码为：
 
-```ts title="App.ts"
-import { Switch, Route } from '@modern-js/runtime/router';
-import { useLoader } from '@modern-js/runtime';
+```tsx title="App.ts"
+import { useRuntimeContext, useStaticLoader } 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 { data } = useLoader(
-    async () => ({
-      message: Math.random(),
-    }),
-    {
-      static: true,
-      params: 'foo',
-    },
-  );
+  const { context } = useRuntimeContext();
+
+  const { data } = useStaticLoader(async () => ({
+    message: Math.random(),
+  }));
 
   return (
-    <Switch>
-      <Route path="/" exact={true}>
-        <div>Home</div>
-      </Route>
-      <Route path="/foo" exact={true}>
-        <div>Foo, {data?.message}</div>
-      </Route>
-    </Switch>
+    <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 start`，重复刷新页面，发现页面渲染结果始终保持同样的内容，说明数据在请求时不会再次获取。
+重新执行 `pnpm run build` 后，执行 `pnpm run start`，重复刷新页面，发现页面渲染结果始终保持同样的内容，数据在请求时不会再次获取，说明页面在编译时已经完成渲染。