@modern-js/main-doc 2.35.1 → 2.36.0

package/docs/en/tutorials/first-app/c07-container.mdx

@@ -15,7 +15,7 @@ Because the two pages need to share the same set of state (point of contact tabu
 
 Modern.js support obtaining data through Data Loader in `layout.tsx`, we first move the data acquisition part of the code to `src/routes/layout.tsx`:
 
-```ts title="src/routes/layout.loader.ts"
+```ts title="src/routes/layout.data.ts"
 export type LoaderData = {
   code: number;
   data: {
@@ -25,7 +25,7 @@ export type LoaderData = {
   }[];
 };
 
-export default async (): Promise<LoaderData> => {
+export const loader = async (): Promise<LoaderData> => {
   const data = new Array(20).fill(0).map(() => {
     const firstName = name.firstName();
     return {
@@ -58,7 +58,7 @@ import 'tailwindcss/base.css';
 import 'tailwindcss/components.css';
 import 'tailwindcss/utilities.css';
 import '../styles/utils.css';
-import type { LoaderData } from './layout.loader';
+import type { LoaderData } from './layout.data';
 
 export default function Layout() {
   const { data } = useLoaderData() as LoaderData;

package/docs/en/tutorials/foundations/introduction.mdx

@@ -31,7 +31,8 @@ We have prepared a tutorial on creating a "contact list app" that you can follow
 
 We offer some commonly used case studies for your reference during the development process. Here you can find some usage patterns of the feature combinations provided by Modern.js. We will continue to improve the case studies here.
 
-- [Route Authorization](/tutorials/examples/csr-auth.html)
-- ...
+import ExampleList from '@site-docs-en/components/turtorials-example-list';
+
+<ExampleList />
 
 Let's start from [creating a project](tutorials/first-app/c01-start) now!

package/docs/zh/apis/app/hooks/src/routes.mdx

@@ -54,7 +54,7 @@ sidebar_position: 2
 
 在组件中，可以通过 [useParams](/apis/app/runtime/router/router#useparams) 获取对应命名的参数。
 
-在使用 [loader](/guides/basic-features/data-fetch#loader-函数) 函数获取数据时，`params` 会作为 `loader` 函数的入参，通过 `params` 的属性可以获取到对应的参数。
+在使用 [loader](/guides/basic-features/data/data-fetch#loader-函数) 函数获取数据时，`params` 会作为 `loader` 函数的入参，通过 `params` 的属性可以获取到对应的参数。
 
 ## 布局组件
 

package/docs/zh/components/debug-app.mdx

@@ -6,7 +6,7 @@ $ pnpm run dev
 > modern dev
 
 info    Starting dev server...
-ready   Client compiled in 50ms
+ready   Client compiled in 50 ms
 
   > Local:    http://localhost:8080/
   > Network:  http://192.168.0.1:8080/

package/docs/zh/components/micro-runtime-config.mdx

@@ -5,11 +5,11 @@ defineConfig(App, {
   masterApp: {
     apps: [{
       name: 'Table',
-      entry: 'http://localhost:8001',
+      entry: 'http://localhost:8081',
       // activeWhen: '/table'
     }, {
       name: 'Dashboard',
-      entry: 'http://localhost:8002'
+      entry: 'http://localhost:8082'
       // activeWhen: '/dashboard'
     }]
   },

package/docs/zh/components/turtorials-example-list.mdx

@@ -0,0 +1,2 @@
+- [路由鉴权](/tutorials/examples/csr-auth.html)
+- ...

package/docs/zh/configure/app/source/entries.mdx

@@ -39,8 +39,8 @@ import { defineConfig } from '@modern-js/app-tools';
 export default defineConfig({
   source: {
     entries: {
-      // 指定一个名称为 entry_customize 的新入口
-      entry_customize: './src/home/test/index.ts',
+      // 指定一个名称为 'my-entry' 的新入口
+      'my-entry': './src/home/test/index.ts',
     },
     // 禁用默认入口扫描
     disableDefaultEntries: true,
@@ -92,9 +92,10 @@ import { defineConfig } from '@modern-js/app-tools';
 export default defineConfig({
   source: {
     entries: {
-      entry_customize: {
+      'my-entry': {
         // 入口文件路径
-        entry: './src/home/test/index.tsx',
+        entry: './src/my-page/index.tsx',
+        disableMount: true,
       },
     },
     // 禁用默认入口扫描
@@ -113,8 +114,8 @@ export default defineConfig({
 export default defineConfig({
   source: {
     entries: {
-      entry_customize: {
-        entry: './src/home/test/index.tsx',
+      'my-entry': {
+        entry: './src/my-page/index.tsx',
         disableMount: true,
       },
     },

package/docs/zh/guides/advanced-features/bff/sdk.mdx

@@ -0,0 +1,119 @@
+---
+sidebar_position: 4
+title: 自定义请求 SDK
+---
+# 自定义请求 SDK
+
+Modern.js 的 BFF 在 CSR 和 SSR 是同构的。在浏览器端依赖了[Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch)，在服务端依赖了 [node-fetch](https://www.npmjs.com/package/node-fetch)。但在很多业务场景下我们需要对请求或响应做一些额外的处理，例如：
+
+- 在请求头中写入鉴权信息
+- 对响应的数据或错误进行统一的处理
+- 特定平台无法使用浏览器的原生 fetch 函数，需要使用其他方式发送请求
+
+针对上述的场景，Modern.js 提供了 `configure` 函数，自定义能力从低到高，可以用它配置 ssr 透传请求头，拦截器，请求 SDK。
+
+:::caution 注意
+`configure` 函数的调用需要在所有 BFF 请求发送前调用，以确保覆盖默认的请求配置。
+
+:::
+
+
+```ts title="App.tsx"
+import { configure } from '@modern-js/runtime/bff';
+
+configure({
+  request: customRequest
+})
+```
+
+## 配置 ssr 透传请求头
+
+在同时使用 Modernjs SSR 和 BFF 的场景下，常常需要将 SSR 页面请求上的一些请求头信息，透传给 BFF 服务。
+
+例如项目有页面地址是 `https://website.com`，该页面是 SSR 的，在组件中会调用 API 接口 `https://website.com/api/info`，该接口需要用户的 cookie 信息做鉴权。页面在请求该 API 接口时，需要将 SSR 页面请求的 `cookie` 传给 BFF。
+
+目前以下请求头在 Modernjs 中是自动透传的：
+
+- cookie
+- x-tt-logid
+- user-agent
+- x-tt-stress
+
+可以通过 `configure` 配置请求头。例如以下例子，Modern.js 会自动将 SSR 页面请求的 cookie 信息透传给 BFF 服务：
+
+```tsx title="App.tsx"
+import { configure } from '@modern-js/runtime/bff';
+
+configure({
+  allowedHeaders: ['x-uid']
+})
+```
+
+## 配置拦截器
+
+在有些业务场景下需要对请求和响应进行一些统一的处理，这种场景下可以配置拦截器满足需求：
+
+```tsx title="App.tsx"
+configure({
+  // 这里的 request 是一体化默认的请求工具，interceptor 函数需返回一个新的 request。
+  // 新 request 的出参必须是 parse body 之后的结果
+  interceptor(request){
+    return async(url, params) => {
+      const res = await request(url, params);
+      return res.json();
+    };
+  }
+});
+```
+
+## 配置自定义请求 SDK
+
+如果仅仅通过配置拦截器无法满足需求，需要对请求的 SDK 做进一步的自定义，可以通过 `configure` 函数配置自定义请求 SDK：
+
+:::caution 注意
+在 SSR 和一体化调用的场景下，在 SSR 向 BFF 服务发送请求时，Modern.js 会通过**服务发现**找到 BFF 服务内网 IP，并通过 IP 发送请求，以提高性能。如果使用自定义请求 SDK 会**失去这种优化**。
+
+:::
+
+```tsx title="App.tsx"
+import nodeFetch from 'node-fetch';
+
+const customFetch = (input: RequestInfo | URL, init: RequestInit) => {
+  const curFetch = process.env.MODERN_TARGET !== 'node' ? fetch : nodeFetch as unknown as typeof fetch;
+  return curFetch(input, init).then(async res => {
+    const data = await res.json();
+    data.hello = 'hello custom sdk';
+    return data;
+  });
+};
+
+configure({
+  request: customFetch,
+});
+```
+
+配置自定义请求 SDK 有以下约定：
+
+- 通过 `configure` 函数可以配置一个 `request` 函数，这个函数的入参与浏览器中的 Fetch 或 node-fetch 对齐，所有的一体化 BFF 函数会通过该函数发送请求。
+- `request` 函数出参必须是接口实际返回的数据，不能是 Promise，否则会导致一体化 BFF 函数无法正常返回数据。
+- 如果是 SSR 项目，`request` 必须要同时支持浏览器端和服务器端发送请求。
+
+使用 axios 定制自定义请求 SDK 的示例：
+
+```tsx title="App.tsx"
+import { configure } from '@modern-js/runtime/bff';
+import type { Method, AxiosRequestHeaders as Headers } from 'axios';
+
+configure({
+  async request(...config: Parameters<typeof fetch>) {
+    const [url, params] = config;
+    const res = await axios({
+      url: url as string,  // 这里因为 fetch 和 axios 类型有些不兼容，需要使用 as
+      method: params?.method as Method,
+      data: params?.body,
+      headers: params?.headers as Headers,
+    });
+    return res.data;
+  },
+});
+```

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

@@ -26,7 +26,7 @@ import InitRspackApp from '@site-docs/components/init-rspack-app';
 在使用 Rspack 作为打包工具时，由于部分能力尚在开发中，以下 features 暂时无法使用，我们将在未来提供支持：
 
 - Storybook 调试
-- 客户端渲染（CSR）使用 [useLoader](/guides/basic-features/data-fetch.html)
+- 客户端渲染（CSR）使用 [useLoader](/guides/basic-features/data/data-fetch.html)
 
 :::
 

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

@@ -22,8 +22,8 @@ export default defineConfig({
 
 Modern.js 中提供了 Data Loader，方便开发者在 SSR、CSR 下同构的获取数据。每个路由模块，如 `layout.tsx` 和 `page.tsx` 都可以定义自己的 Data Loader：
 
-```ts title="src/routes/page.loader.ts"
-export default () => {
+```ts title="src/routes/page.data.ts"
+export const loader = () => {
   return {
     message: 'Hello World',
   };
@@ -48,7 +48,7 @@ Modern.js 打破传统的 SSR 开发模式，提供了用户无感的 SSR 开发
 
 1. 当以客户端路由的方式请求页面时，Modern.js 会发送一个 HTTP 请求，服务端接收到请求后执行页面对应的 Data Loader 函数，然后将执行结果作为请求的响应返回浏览器。
 
-2. 使用 Data Loader 时，数据获取发生在渲染前，Modern.js 也仍然支持在组件渲染时获取数据。更多相关内容可以查看[数据获取](/guides/basic-features/data-fetch)。
+2. 使用 Data Loader 时，数据获取发生在渲染前，Modern.js 也仍然支持在组件渲染时获取数据。更多相关内容可以查看[数据获取](/guides/basic-features/data/data-fetch)。
 
 :::
 
@@ -147,8 +147,8 @@ SPR 利用预渲染与缓存技术，为 SSR 页面提供静态 Web 的响应性
 
 这里模拟一个使用 `useLoaderData` API 的组件，Data Loader 中的请求需要消耗 2s 时间。
 
-```tsx title="page.loader.ts"
-export default async () => {
+```tsx title="page.data.ts"
+export const loader = async () => {
   await new Promise((resolve, reject) => {
     setTimeout(() => {
       resolve(null);
@@ -297,9 +297,9 @@ export const loader = () => {
 
 上述两种方式，都会为开发者带来一些心智负担。在真实的业务中，我们发现大多数的 Node / Web 代码混用都出现在数据请求中。
 
-因此，Modern.js 基于[嵌套路由](/guides/basic-features/routes)开发设计了[更简单的方案](/guides/basic-features/data-fetch)来分离 CSR 和 SSR 的代码。
+因此，Modern.js 基于[嵌套路由](/guides/basic-features/routes)开发设计了[更简单的方案](/guides/basic-features/data/data-fetch)来分离 CSR 和 SSR 的代码。
 
-我们可以通过独立文件来分离**数据请求**与**组件代码**。在 `routes/page.tsx` 中编写组件逻辑，在 `routes/page.loader.ts` 中编写数据请求逻辑。
+我们可以通过独立文件来分离**数据请求**与**组件代码**。在 `routes/page.tsx` 中编写组件逻辑，在 `routes/page.data.ts` 中编写数据请求逻辑。
 
 ```ts title="routes/page.tsx"
 export default Page = () => {
@@ -307,9 +307,9 @@ export default Page = () => {
 }
 ```
 
-```ts title="routes/page.loader.tsx"
+```ts title="routes/page.data.tsx"
 import fse from 'fs-extra';
-export default () => {
+export const loader = () => {
   const file = fse.readFileSync('./myfile');
   return {
     ...
@@ -319,7 +319,7 @@ export default () => {
 
 ## 接口请求
 
-在 SSR 中发起接口请求时，开发者有时自己封装了同构的请求工具。部分接口需要传递用户 Cookie，开发者可以通过 [`useRuntimeContext`](/guides/basic-features/data-fetch#route-loader) API 获取到请求头来实现。
+在 SSR 中发起接口请求时，开发者有时自己封装了同构的请求工具。部分接口需要传递用户 Cookie，开发者可以通过 [`useRuntimeContext`](/guides/basic-features/data/data-fetch#route-loader) API 获取到请求头来实现。
 
 需要注意的是，此时获取到的是 HTML 请求的请求头，不一定适用于接口请求，因此**千万不能**透传所有请求头。并且，一些后端接口，或是通用网关，会根据请求头中的信息做校验，全量透传容易出现各种难以排查的问题，推荐**按需透传**。
 
@@ -349,7 +349,7 @@ Modern.js 的流式渲染基于 React Router 实现，主要涉及 API 有：
 
 ### 异步获取数据
 
-```ts title="page.loader.ts"
+```ts title="page.data.ts"
 import { defer, type LoaderFunctionArgs } from '@modern-js/runtime/router';
 
 interface User {
@@ -361,7 +361,7 @@ export interface Data {
   data: User;
 }
 
-export default ({ params }: LoaderFunctionArgs) => {
+export const loader = ({ params }: LoaderFunctionArgs) => {
   const userId = params.id;
 
   const user = new Promise<User>(resolve => {
@@ -382,10 +382,10 @@ export default ({ params }: LoaderFunctionArgs) => {
 
 `defer` 还可以同时接收异步数据和同步数据。例如：
 
-```ts title="page.loader.ts"
+```ts title="page.data.ts"
 // 省略部分代码
 
-export default ({ params }: LoaderFunctionArgs) => {
+export const loader = ({ params }: LoaderFunctionArgs) => {
   const userId = params.id;
 
   const user = new Promise<User>(resolve => {
@@ -419,7 +419,7 @@ export default ({ params }: LoaderFunctionArgs) => {
 ```tsx title="page.tsx"
 import { Await, useLoaderData } from '@modern-js/runtime/router';
 import { Suspense } from 'react';
-import type { Data } from './page.loader';
+import type { Data } from './page.data';
 
 const Page = () => {
   const data = useLoaderData() as Data;
@@ -452,7 +452,7 @@ export default Page;
 :::warning 注意
 从 Data Loader 文件导入类型时，需要使用 import type 语法，保证只导入类型信息，这样可以避免 Data Loader 的代码打包到前端产物的 bundle 文件中。
 
-所以，这里的导入方式为：`import type { Data } from './page.loader'`;
+所以，这里的导入方式为：`import type { Data } from './page.data'`;
 
 :::
 

package/docs/zh/guides/basic-features/data/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "数据管理",
+  "position": 3
+}

package/docs/zh/guides/basic-features/{data-fetch.mdx → data/data-fetch.md}

@@ -11,16 +11,22 @@ Modern.js 中提供了开箱即用的数据获取能力，开发者可以通过
 
 ## Data Loader(推荐)
 
-Modern.js 推荐使用约定式路由做路由的管理，通过 Modern.js 的[约定式（嵌套）路由](/guides/basic-features/routes#约定式路由)，每个路由组件(`layout.ts` 或 `page.ts`)可以有一个同名的 `loader` 文件，该 `loader` 文件需要导出一个函数，函数会在组件渲染之前执行，为路由组件提供数据。
+Modern.js 推荐使用约定式路由做路由的管理，通过 Modern.js 的[约定式（嵌套）路由](/guides/basic-features/routes#约定式路由)，每个路由组件(`layout.ts` 或 `page.ts`)可以有一个同名的 `data` 文件，该 `data` 文件可以导出一个 `loader` 函数，函数会在组件渲染之前执行，为路由组件提供数据。
 
 :::info
 Modern.js v1 支持通过 [useLoader](#useloader（旧版）) 获取数据，这已经不是我们推荐的用法，除迁移过程外，不推荐两者混用。
 
 :::
 
+:::warning
+- 在之前的版本中，Modern.js Data Loader 是定义在 `loader` 文件中的，在之后的版本中，我们推荐定义在 `data` 文件中，同时我们会保持对 `loader` 文件的兼容。
+- 在 `data` 文件中，对应的 `loader` 需要具名导出。
+
+:::
+
 ### 基础示例
 
-路由组件如 `layout.ts` 或 `page.ts`，可以定义同名的 `loader` 文件，`loader` 文件中导出一个函数，该函数提供组件所需的数据，然后在路由组件中通过 `useLoaderData` 函数获取数据，如下面示例：
+路由组件如 `layout.ts` 或 `page.ts`，可以定义同名的 `data` 文件，`data` 文件中导出一个 `loader` 函数，该函数提供组件所需的数据，然后在路由组件中通过 `useLoaderData` 函数获取数据，如下面示例：
 
 ```bash
 .
@@ -28,16 +34,16 @@ Modern.js v1 支持通过 [useLoader](#useloader（旧版）) 获取数据，这
     ├── layout.tsx
     └── user
         ├── layout.tsx
-        ├── layout.loader.ts
+        ├── layout.data.ts
         ├── page.tsx
-        └── page.loader.ts
+        └── page.data.ts
 ```
 
 在文件中定义以下代码：
 
 ```ts title="routes/user/page.tsx"
 import { useLoaderData } from '@modern-js/runtime/router';
-import type { ProfileData } from './page.loader.ts';
+import type { ProfileData } from './page.data.ts';
 
 export default function UserPage() {
   const profileData = useLoaderData() as ProfileData;
@@ -45,19 +51,19 @@ export default function UserPage() {
 }
 ```
 
-```ts title="routes/user/page.loader.ts"
+```ts title="routes/user/page.data.ts"
 export type ProfileData = {
   /*  some types */
 };
 
-export default async (): Promise<ProfileData> => {
+export const loader = async (): Promise<ProfileData> => {
   const res = await fetch('https://api/user/profile');
   return await res.json();
 };
 ```
 
 :::caution
-这里路由组件和 `loader` 文件共享类型，要使用 `import type` 语法。
+这里路由组件和 `data` 文件共享类型，要使用 `import type` 语法。
 
 :::
 
@@ -81,10 +87,10 @@ export default async (): Promise<ProfileData> => {
 当路由文件通过 `[]` 时，会作为[动态路由](/guides/basic-features/routes#动态路由)，动态路由片段会作为参数传入 `loader` 函数：
 
 ```tsx
-// routes/user/[id]/page.loader.ts
+// routes/user/[id]/page.data.ts
 import { LoaderFunctionArgs } from '@modern-js/runtime/router';
 
-export default async ({ params }: LoaderFunctionArgs) => {
+export const loader = async ({ params }: LoaderFunctionArgs) => {
   const { id } = params;
   const res = await fetch(`https://api/user/${id}`);
   return res.json();
@@ -100,10 +106,10 @@ export default async ({ params }: LoaderFunctionArgs) => {
 一个常见的使用场景是通过 `request` 获取查询参数：
 
 ```tsx
-// routes/user/[id]/page.loader.ts
+// routes/user/[id]/page.data.ts
 import { LoaderFunctionArgs } from '@modern-js/runtime/router';
 
-export default async ({ request }: LoaderFunctionArgs) => {
+export const loader = async ({ request }: LoaderFunctionArgs) => {
   const url = new URL(request.url);
   const userId = url.searchParams.get('id');
   return queryUser(userId);
@@ -142,7 +148,7 @@ const loader = async (): Promise<ProfileData> => {
 Modern.js 对 `fetch` API 做了 polyfill, 用于发起请求，该 API 与浏览器的 `fetch` API 一致，但是在服务端也能使用该 API 发起请求，这意味着不管是 CSR 还是 SSR，都可以使用统一的 `fetch` API 进行数据获取：
 
 ```tsx
-async function loader() {
+export async function loader() {
   const res = await fetch('https://api/user/profile');
 }
 ```
@@ -152,8 +158,8 @@ async function loader() {
 在 `loader` 函数中，可以通过 `throw error` 或者 `throw response` 的方式处理错误，当 `loader` 函数中有错误被抛出时，Modern.js 会停止执行当前 `loader` 中的代码，并将前端 UI 切换到定义的 [`ErrorBoundary`](/guides/basic-features/routes#错误处理) 组件：
 
 ```tsx
-// routes/user/profile/page.loader.ts
-export default async function loader() {
+// routes/user/profile/page.data.ts
+export async function loader() {
   const res = await fetch('https://api/user/profile');
   if (!res.ok) {
     throw res;
@@ -184,8 +190,8 @@ export default ErrorBoundary;
 // routes/user/profile/page.tsx
 import { useRouteLoaderData } from '@modern-js/runtime/router';
 
-export default function UserLayout() {
-  // 获取 routes/user/layout.loader.ts 中 `loader` 返回的数据
+export function UserLayout() {
+  // 获取 routes/user/layout.data.ts 中 `loader` 返回的数据
   const data = useRouteLoaderData('user/layout');
   return (
     <div>
@@ -220,12 +226,12 @@ export default function UserLayout() {
 
 :::
 
-创建 `user/layout.loader.ts`，并添加以下代码：
+创建 `user/layout.data.ts`，并添加以下代码：
 
-```ts title="routes/user/layout.loader.ts"
+```ts title="routes/user/layout.data.ts"
 import { defer } from '@modern-js/runtime/router';
 
-const loader = () =>
+export const loader = () =>
   defer({
     userInfo: new Promise(resolve => {
       setTimeout(() => {
@@ -236,8 +242,6 @@ const loader = () =>
       }, 1000);
     }),
   });
-
-export default loader;
 ```
 
 在 `user/layout.tsx` 中添加以下代码：
@@ -298,12 +302,12 @@ export default () => {
 
 ```ts
 // This won't work!
-export default async () => {
+export const loader = async () => {
   const res = fetch('https://api/user/profile');
   return res.json();
 };
 
-import loader from './page.loader.ts';
+import { loader } from './page.data.ts';
 export default function RouteComp() {
   const data = loader();
 }
@@ -315,7 +319,7 @@ export default function RouteComp() {
 // Not allowed
 // routes/layout.tsx
 import { useLoaderData } from '@modern-js/runtime/router';
-import { ProfileData } from './page.loader.ts'; // should use "import type" instead
+import { ProfileData } from './page.data.ts'; // should use "import type" instead
 
 export const fetch = wrapFetch(fetch);
 
@@ -324,13 +328,13 @@ export default function UserPage() {
   return <div>{profileData}</div>;
 }
 
-// routes/layout.loader.ts
+// routes/layout.data.ts
 import { fetch } from './layout.tsx'; // should not be imported from the routing component
 export type ProfileData = {
   /*  some types */
 };
 
-export default async (): Promise<ProfileData> => {
+export const loader = async (): Promise<ProfileData> => {
   const res = await fetch('https://api/user/profile');
   return await res.json();
 };