@modern-js/main-doc 0.0.0-next-20221218140542 → 0.0.0-next-20221219034957

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # @modern-js/main-doc
 
-## 0.0.0-next-20221218140542
+## 0.0.0-next-20221219034957
 
 ### Patch Changes
 
@@ -30,4 +30,4 @@
 - Updated dependencies [3fae2d03b]
 - Updated dependencies [df41d71ad]
 - Updated dependencies [14b712da8]
-  - @modern-js/builder-doc@0.0.0-next-20221218140542
+  - @modern-js/builder-doc@0.0.0-next-20221219034957

package/package.json

@@ -11,20 +11,20 @@
     "modern",
     "modern.js"
   ],
-  "version": "0.0.0-next-20221218140542",
+  "version": "0.0.0-next-20221219034957",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "0.0.0-next-20221218140542"
+    "@modern-js/builder-doc": "0.0.0-next-20221219034957"
   },
   "devDependencies": {
     "ts-node": "^10",
     "fs-extra": "^10",
     "@types/node": "^16",
     "@types/fs-extra": "^9",
-    "@modern-js/builder-doc": "0.0.0-next-20221218140542"
+    "@modern-js/builder-doc": "0.0.0-next-20221219034957"
   },
   "scripts": {
     "build": "npx ts-node ./scripts/sync.ts"

package/zh/apis/app/runtime/web-server/hook.md

@@ -46,7 +46,6 @@ type HookContext = {
     ) => void;
   };
   request: {
-    url: string;
     host: string;
     pathname: string;
     query: Record<string, any>;
@@ -83,6 +82,7 @@ type AfterRenderContext = {
 };
 ```
 
+
 ### 参数
 
 - `context`：提供当前 Hook 上下文。

package/zh/apis/app/runtime/web-server/middleware.md

@@ -53,7 +53,6 @@ type MiddlewareContext = {
     locals: Record<string, any>;
   };
   request: {
-    url: string;
     host: string;
     pathname: string;
     query: Record<string, any>;

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

@@ -5,404 +5,7 @@ sidebar_position: 3
 
 Modern.js 中提供了开箱即用的数据获取能力，开发者可以通过这些 API，在 CSR 和 SSR 环境同构的进行开发。
 
-需要注意的是，这些 API 并不帮助应用发起请求，而是帮助开发者更好地管理数据，提升项目的性能。
-
-## Data Loader(推荐)
-
-Modern.js 推荐使用约定式路由做路由的管理，通过 Modern.js 的[约定式（嵌套）路由](/docs/guides/basic-features/routes#约定式路由)，每个路由组件(`layout.ts` 或 `page.ts`)可以导出一个函数`loader`，该函数可以在组件渲染之前，为路由组件提供数据。
-
-:::info
-Modern.js 旧版支持通过 [useLoader](#useloader旧版) 获取数据，这已经不是我们推荐的用法，除迁移过程外，不推荐两者混用。
-:::
-
-### 基础示例
-
-每个路由组件可以导出一个 `loader` 函数，然后通过 `useLoaderData` 函数获得相应的数据:
-
-```ts
-// routes/user/page.tsx
-import { useLoaderData } from '@modern-js/runtime/router';
-
-export const loader = async(): ProfileData => {
-  const res = await fetch('https://api/user/profile');
-  return await res.json();
-}
-
-export default function UserPage() {
-  const profileData = useLoaderData() as ProfileData;
-  return <div>{profileData}</div>;
-}
-```
-
-在 CSR 环境下，`loader` 函数会在客户端执行，`loader` 函数内可以使用浏览器的 API（但通常不需要，也不推荐）。
-
-在 SSR 环境下，不管是首屏，还是在客户端的导航，`loader` 函数只会在服务端执行，这里可以调用任意的 Node.js API，同时这里使用的任何依赖和代码都不会包含在客户端的 bundle 中。
-
-:::info
-在以后的版本中，Modern.js 可能会支持在 CSR 环境下，`loader` 函数也在服务端运行，以提高性能和安全性，所以这里建议尽可能地保证 loader 的纯粹，只做数据获取的场景。
-:::
-
-当在客户端导航时，基于 Modern.js 的[约定式路由](/docs/guides/basic-features/routes)，所有的 loader 函数会并行执行（请求），即当访问 `/user/profile` 时，`/user` 和 `/user/profile` 下的 loader 函数都会并行执行（请求），以提高客户端的性能。
-
-### Loader 放在单独文件中
-
-除了支持 `loader` 函数从前端组件中导出，Modern.js 也支持将 `loader` 函数放在单独的文件中， 将 `loader` 函数放在单独的文件中，可以无需留意[副作用](#副作用处理)相关注意事项，但可以要注意的是，路由组件如 `layout.ts` 和 loader 文件 `layout.loader.ts` 不能引入彼此的代码，如果需要相关类型可以使用 `import type`，可以见下面的示例：
-
-```
-.
-└── routes
-    ├── layout.tsx
-    └── user
-        ├── layout.tsx
-        ├── layout.loader.ts
-        ├── page.tsx
-        └── page.loader.ts
-```
-
-如[基础示例](#基础示例)中的 `loader` 可以用以下代码替代：
-```tsx
-// routes/user/page.loader.tsx
-type ProfileData = { /* some type declarations */ }
-
-export const loader = async(): ProfileData => {
-  const res = await fetch('https://api/user/profile');
-  return await res.json();
-}
-
-// routes/user/page.tsx
-import { useLoaderData } from '@modern-js/runtime/router';
-// 这里只能使用 import type，导入类型
-import type { ProfileData } from './page.loader';
-
-export default function UserPage() {
-  const profileData = useLoaderData() as ProfileData;
-  return <div>{profileData}</div>;
-}
-```
-
-
-### `loader` 函数
-
-
-`loader` 函数有两个入参：
-##### `Params`
-
-当路由文件通过 `[]` 时，会作为[动态路由](/docs/guides/basic-features/routes#动态路由)，动态路由片段会作为参数传入 loader 函数：
-
-```tsx
-// routes/user/[id]/page.tsx
-import { LoaderArgs } from '@modern-js/runtime/router';
-
-export const loader = async({ params }: LoaderArgs) => {
-  const { id } = params;
-  const res = await fetch(`https://api/user/${id}`);
-  return res.json();
-}
-```
-
-当访问 `/user/123` 时，`loader` 函数的参数为 `{ params: { id: '123' } }`。
-
-##### `request`
-
-request 是一个 [Fetch Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) 实例。
-
-一个常见的使用场景是通过 `request` 获取查询参数：
-```tsx
-// routes/user/[id]/page.tsx
-import { LoaderArgs } from '@modern-js/runtime/router';
-
-export const loader = async({ request }: LoaderArgs) => {
-  const url = new URL(request.url);
-  const userId = url.searchParams.get("id");
-  return queryUser(userId);
-}
-```
-
-#### 返回值
-
-`loader` 函数的返回值可以是任何可序列化的内容，也可以是一个 [Fetch Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) 实例：
-
-```tsx
-export const loader = async(): ProfileData => {
-  return {
-    message: 'hello world',
-  }
-}
-```
-
-默认情况下，`loader` 返回的响应 `Content-type` 是 `application/json`，`status` 为 200，你可以通过自定义 `Response` 来设置：
-```tsx
-export const loader = async(): ProfileData => {
-  const data = {message: 'hello world'};
-  return new Response(JSON.stringify(data), {
-    status: 200,
-    headers: {
-      "Content-Type": "application/json; utf-8",
-    },
-  });
-}
-```
-
-### 请求 API
-
-Modern.js 对 `fetch` API 做了 polyfill, 用于发起请求，该 API 与浏览器的 `fetch` API 一致，但是在服务端也能使用该 API 发起请求，这意味着不管是 CSR 还是 SSR，都可以使用统一的 `fetch` API 进行数据获取：
-```tsx
-export async function loader(){
-  const res = await fetch('https://api/user/profile');
-}
-```
-
-
-### 错误处理
-
-在 `loader` 函数中，可以通过 `throw error` 或者 `throw response` 的方式处理错误，当 `loader` 函数中有错误被抛出时，Modern.js 会停止执行当前 loader 中的代码，并将前端 UI 切换到定义的 [`ErrorBoundary`](/docs/guides/basic-features/routes#错误处理) 组件：
-```tsx
-// routes/user/profile/page.tsx
-export async function loader(){
-  const res = await fetch('https://api/user/profile');
-  if(!res.ok){
-    throw res;
-  }
-  return res.json();
-}
-
-// routes/user/profile/error.tsx
-import { useRouteError } from '@modern-js/runtime/router';
-const ErrorBoundary = () => {
-  const error = useRouteError() as Response;
-  return (
-    <div>
-      <h1>{error.status}</h1>
-      <h2>{error.statusText}</h2>
-    </div>
-  );
-};
-
-export default ErrorBoundary;
-```
-
-### 获取上层组件数据
-
-很多场景下，子组件需要获取到祖先组件 loader 中的数据，你可以通过 `useRouteLoaderData` 方便地获取到祖先组件的数据：
-```tsx
-// routes/user/profile/page.tsx
-import { useRouteLoaderData } from '@modern-js/runtime/router';
-
-export default function UserLayout() {
-  // 获取 routes/user/layout.tsx 中 loader 返回的数据
-  const data = useRouteLoaderData('user/layout');
-  return (
-    <div>
-      <h1>{data.name}</h1>
-      <h2>{data.age}</h2>
-    </div>
-  );
-}
-```
-
-`userRouteLoaderData` 接受一个参数 `routeId`，在使用约定式路由时，Modern.js 会为你自动生成`routeId`，`routeId` 的值是对应组件相对于 `src/routes` 的路径，如上面的例子中，子组件想要获取 `routes/user/layout.tsx` 中 loader 返回的数据，`routeId` 的值就是 `user/layout`。
-
-在多 entry（MPA） 场景下，`routeId` 的值需要加上对应 entry 的 name，entry name 非指定情况下一般是 entry 目录名，如以下目录结构：
-```bash
-.
-└── src
-    ├── entry1
-    │   ├── layout.tsx
-    └── entry2
-        └── layout.tsx
-```
-
-如果想获取 `entry1/layout.tsx` 中 loader 返回的数据，`routeId` 的值就是 `entry1_layout`。
-
-
-### (WIP)Loading UI
-
-:::info
-此功能目前是实验性质，后续 API 可能有调整。
-目前仅支持 CSR，敬请期待 Streaming SSR。
-:::
-
-因为获取数据是异步的，在数据获取完成之前，常常需要展示一个 Loading UI，以下是一个基本的示例，假设有以下目录：
-```bash
-.
-└── routes
-    ├── layout.tsx
-    └── user
-        ├── layout.tsx
-        └── page.ts
-```
-
-我们在 `user/layout.tsx` 中获取用户的详细数据，在获取数据之前，希望展示一个 Loading UI。
-
-首先，在项目中在 `routes` 目录下增加一个 `loading.tsx` 组件，该 `loading` 组件会对子目录下的所有路由生效（如 user）：
-```bash
-.
-└── routes
-    ├── layout.tsx
-    └── user
-        ├── layout.tsx
-        └── page.ts
-```
-
-:::info
-loading 组件的具体用法，请查看[loading](/docs/guides/basic-features/routes#loading)
-:::
-
-然后，在 `user/layout.tsx` 中添加以下代码：
-```tsx title="routes/user/layout.tsx"
-import {
-  Await,
-  defer,
-  useLoaderData,
-  Outlet
-} from '@modern-js/runtime/router';
-
-export const loader = () => {
-  return defer({
-    // fetchUserInfo 是一个异步函数，返回用户信息
-    userInfo: fetchUserInfo(),
-  })
-}
-
-export default function UserLayout() {
-  const { userInfo } = useLoaderData() as {userInfo: Promise<UserInfo>};
-  return (
-    <div>
-      <Await resolve={userInfo} children={userInfo => (
-        <div>
-          <span>{userInfo.name}</span>
-          <span>{userInfo.age}</span>
-          <Outlet>
-        </div>
-      )}>
-      </Await>
-    </div>
-  );
-}
-```
-
-:::info
-Await 组件的具体用法请查看 [Await](https://reactrouter.com/en/main/components/await)
-
-defer 的具体用法请查看 [defer](https://reactrouter.com/en/main/guides/deferred)
-:::
-
-
-<!-- TODO 缓存相关 -->
-
-### 副作用处理
-
-如上面所述，Modern.js 会将服务端代码 `loader` 从客户端 bundle 中移除，有一些你需要注意的事项，如果不想受副作用的影响，可以使用[单独文件](#单独文件) 的方式定义 `loader`。
-
-:::info
-在 CSR 场景下，通常副作用对项目影响较小，但依然希望你能遵循以下约定。
-:::
-
-模块的副作用可以认为是在模块被加载时执行的代码，比如：
-```tsx
-// routes/user/page.tsx
-import { useLoaderData } from '@modern-js/runtime/router';
-// highlight-next-line
-import { transformProfile } from "./utils";
-// highlight-next-line
-console.log(transformProfile);
-
-export const loader = async(): ProfileData => {
-  const res = await fetch('https://api/user/profile');
-  const data = await res.json();
-  return transformProfile(data);
-}
-
-export default function UserPage() {
-  const profileData = useLoaderData() as ProfileData;
-  return <div>{profileData}</div>;
-}
-```
-
-因为 `console.log` 在 `routes/user/page.tsx` 加载时，就会被执行，编译器不会移除它，`transformProfile` 就会打包到客户端的 bundle 中。
-
-所以我们不推荐有任何代码在模块加载时执行，包括项目代码和使用的第三方模块，以下是一些我们不推荐的写法：
-
-```tsx
-// routes/user/page.tsx
-export default function UserPage() {
-  return <div>profile</div>;
-}
-
-UserPage.config = {}
-```
-
-```tsx
-// routes/init.ts
-document.title = 'Modern.js';
-
-// routes/layout.tsx
-import "./init.ts";
-
-export default function Layout() {
-  return <></>
-}
-```
-
-在 SSR 场景，通常你需要在 `loader` 函数中使用 Node.js 核心包和依赖，对于非 Node.js 核心包，需要使用一个特殊约定的文件做重新导出，如使用 `fs-extra`：
-
-```tsx
-// routes/user/avatar.tsx
-import { useLoaderData } from '@modern-js/runtime/router';
-import { readFile } from './utils.server';
-
-type ProfileData = { /* some type declarations */ }
-
-export const loader = async(): ProfileData => {
-  const profile = await readFile('profile.json');
-  return profile;
-}
-
-export default function UserPage() {
-  const profileData = useLoaderData() as ProfileData;
-  return <div>{profileData}</div>;
-}
-
-// routes/user/utils.server.ts
-export * from 'fs-extra';
-```
-
-
-### 错误用法
-
-1. `loader` 中只能返回可序列化的数据，在 SSR 环境下，`loader` 函数的返回值会被序列化为 JSON 字符串，然后在客户端被反序列化为对象。因此，`loader` 函数中不能返回不可序列化的数据（如函数）。
-
-:::warning
-目前 CSR 下没有这个限制，但我们强烈推荐你遵循该限制，且未来我们可能在 CSR 下也加上该限制。
-:::
-
-```ts
-// This won't work!
-export const loader = () => {
-  return {
-    user: {},
-    method: () => {
-
-    }
-  }
-}
-```
-
-2. Modern.js 会帮你调用 `loader` 函数，你不应该自己调用 `loader` 函数：
-```ts
-// This won't work!
-export const loader = async () => {
-  const res = fetch('https://api/user/profile');
-  return res.json();
-};
-
-export default function RouteComp() {
-  const data = loader();
-}
-```
-
-3. 在服务端运行时，`loader` 函数会被打包为一个统一的 bundle，所以我们不推荐服务端的代码使用 `__filename` 和 `__dirname`。
-
+需要注意的是，这些 API 并不帮助应用发起请求，而是帮助开发者更好的管理数据与路由的关系。
 
 ## useLoader（旧版）
 
@@ -455,4 +58,8 @@ Modern.js 在新版本中，设计了全新的 Loader 方案。新方案解决
 :::note
 详细 API 可以查看 [useLoader](/docs/apis/app/runtime/core/use-loader)。
 :::
+## Route Loader
 
+:::note
+敬请期待
+:::

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

@@ -177,7 +177,7 @@ Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组
 
 `routes/` 下每一层目录中，开发者可以创建 `loading.tsx` 文件，默认导出一个 `<Loading>` 组件。
 
-当路由目录下存在该组件时，这一级子路由下所有的路由切换时，都会以该 `<Loading>` 组件作为静态资源和数据获取时的 Fallback UI。当该目录下未定义 `layout.tsx` 文件时，`<Loading>` 组件不会生效。例如以下文件目录：
+当路由目录下存在该组件时，这一级子路由下所有的路由切换时，都会以该 `<Loading>` 组件作为 JS Chunk 加载时的 Fallback UI。当该目录下未定义 `layout.tsx` 文件时，`<Loading>` 组件不会生效。例如以下文件目录：
 
 ```bash
 .
@@ -206,7 +206,7 @@ Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组
 
 ```tsx
 import { useRouteError } from '@modern-js/runtime/router';
-const ErrorBoundary = () => {
+export default const ErrorBoundary = () => {
   const error = useRouteError();
   return (
     <div>
@@ -215,7 +215,6 @@ const ErrorBoundary = () => {
     </div>
   )
 }
-export default ErrorBoundary;
 ```
 
 ## 自控式路由

package/zh/tutorials/first-app/c01-start.md

@@ -64,19 +64,15 @@ function App() {
 export default App;
 ```
 
+因为框架默认支持 [HMR](https://webpack.js.org/concepts/hot-module-replacement/)，可以看到 `http://localhost:8080/` 里的内容会自动变成 Hello Modern.js。
+
 删除多余的 css 文件，保持目录没有多余的文件：
 
 ```bash
 rm src/routes/index.css
 ```
 
-因为框架默认支持 [HMR](https://webpack.js.org/concepts/hot-module-replacement/)，可以看到 `http://localhost:8080/` 里的内容会自动更新为：
-
-![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvt/ljhwZthlaukjlkulzlp/screenshot-20221214-141909.png)
-
-此刻的页面还没有样式。下一章节将展开这部分的内容。
-
-## 开启 SSR
+## 使用配置
 
 接下来，我们修改项目中的 `modern.config.ts`，开启 SSR 能力：
 

package/zh/tutorials/first-app/c05-loader.md

@@ -4,7 +4,7 @@ title: 添加 Loader
 
 上一章节中，我们学习了如何添加客户端路由。
 
-这一章节中，我们将会学习如何为**路由组件添加 Loader**。
+这一章节中，我们将会学习如何**为路由组件添加 Loader**。
 
 到目前为止，我们都是通过硬编码的方式，为组件提供数据。如果要从远端获取数据，通常情况下会使用 `useEffect` 来做。但在启用 SSR 的情况下，`useEffect` 是不会在服务端执行的，所以这种 SSR 只能渲染很有限的 UI。
 

package/zh/tutorials/first-app/c06-model.md

@@ -216,9 +216,9 @@ export const loader = async (): Promise<LoaderData> => {
 
 function Index() {
   const { data } = useLoaderData() as LoaderData;
-  const [{ items }, { archive, setItems }] = useModel(contacts);
+  const [{ items }, { archive, setItem }] = useModel(contacts);
   if (items.length === 0) {
-    setItems(data);
+    setItem(data);
   }
 
   return (

package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/src/server.md

@@ -1,31 +0,0 @@
----
-title: "*.[server|node].[tj]sx"
-sidebar_position: 8
----
-
-Used in application projects to place server side code, it generally has the following two functions：
-
-1. When `*.tsx` and `*. [server|node].tsx` coexist, rendering on the server side will give preference to the `*. [server|node].tsx` file instead of the `*.tsx` file.
-
-2. When using [data loader](/docs/guides/basic-features/data-fetch), the server-side dependencies need to be re-exported from this file
-
-```tsx
-// routes/user/avatar.tsx
-import { useLoaderData } from '@modern-js/runtime/router';
-import { readFile } from './utils.server';
-
-type ProfileData = { /* some type declarations */ }
-
-export const loader = async(): ProfileData => {
-  const profile = await readFile('profile.json');
-  return profile;
-}
-
-export default function UserPage() {
-  const profileData = useLoaderData() as ProfileData;
-  return <div>{profileData}</div>;
-}
-
-// routes/user/utils.server.ts
-export * from 'fs-extra';
-```

package/zh/apis/app/hooks/src/server.md

@@ -1,31 +0,0 @@
----
-title: "*.[server|node].[tj]sx"
-sidebar_position: 8
----
-
-应用项目中使用，用于放置服务端代码，一般有以下两个作用：
-
-1. 当 `*.tsx` 和 `*.[server|node].tsx` 共存时，SSR 在服务端执行渲染时，会优先使用 `*.[server|node].tsx` 文件，而不是 `*.tsx` 文件。
-
-2. 在使用 [data loader](/docs/guides/basic-features/data-fetch) 时，需要将服务端的依赖从该文件中做重导出
-
-```tsx
-// routes/user/avatar.tsx
-import { useLoaderData } from '@modern-js/runtime/router';
-import { readFile } from './utils.server';
-
-type ProfileData = { /* some type declarations */ }
-
-export const loader = async(): ProfileData => {
-  const profile = await readFile('profile.json');
-  return profile;
-}
-
-export default function UserPage() {
-  const profileData = useLoaderData() as ProfileData;
-  return <div>{profileData}</div>;
-}
-
-// routes/user/utils.server.ts
-export * from 'fs-extra';
-```