@modern-js/main-doc 0.0.0-next-20221227040741 → 0.0.0-next-20221227140603

package/en/docusaurus-plugin-content-docs/current/guides/basic-features/data-fetch.md

@@ -7,6 +7,405 @@ Modern.js provides out of the box fetching data capabilities, developers can use
 
 It should be noted that these APIs do not help applications to initiate requests, but help developers better manage the relationship between data and routing.
 
+## Data loader(recommend)
+
+Modern.js recommends the use of conventional routing for route management. With Modern.js' [conventional (nested) routing](/docs/guides/basic-features/routes#conventional-routing), each routing component (`layout.ts` or `page.ts`) can export a function `loader` that can be executed before the component renders, providing data to the routing component.
+
+:::info
+Modern.js v1 supports getting data by [useLoader](#useloaderold), which is no longer the recommended usage and it is not recommended to mix both except for migration process.
+:::
+
+### Basic example
+
+Each routing component can export a `loader` function and get the  data via the `useLoaderData` function:
+
+```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>;
+}
+```
+
+In a CSR environment, the `loader` function is executed on the client side, and the browser API can be used within the `loader` function (but it is usually not needed and not recommended).
+
+In an SSR environment, the `loader` function will only be executed on the server side, regardless of the first screen or the navigation on the client side, where any Node.js API can be called, and any dependencies and code used here will not be included in the client bundle.
+
+:::info
+In later versions, Modern.js may support `loader` functions running on the server side as well in CSR environments to improve performance and security, so here it is recommended to keep the loader as pure as possible and only do data fetching scenarios.
+:::
+
+When navigating on the client side, all loader functions under `/user` and `/user/profile` are executed (requested) in parallel based on Modern.js's [conventional routing](/docs/guides/basic-features/routes), i.e. when accessing `/user/profile`, the loader functions under `/user` and `/user/profile` are executed (requested) in parallel to improve client-side performance.
+
+### Loader is defined in a separate file
+
+In addition to supporting the export of `loader` functions from front-end components, Modern.js also supports placing `loader` functions in a separate file, by defining the `loader` function in a separate file, there is no need to pay attention to [side effect](#side-effects) related considerations, but it is important to note that routing components such as `layout.ts` and the loader file `layout.loader.ts` cannot introduce each other's code, if you need the related types you can use `import type`, you can see the following example:
+
+```
+.
+└── routes
+    ├── layout.tsx
+    └── user
+        ├── layout.tsx
+        ├── layout.loader.ts
+        ├── page.tsx
+        └── page.loader.ts
+```
+
+For example, `loader` in [basic example](#basic-example) can be replaced with the following code:
+
+```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';
+// here you can only use import type
+import type { ProfileData } from './page.loader';
+
+export default function UserPage() {
+  const profileData = useLoaderData() as ProfileData;
+  return <div>{profileData}</div>;
+}
+```
+
+### `loader` function
+
+The `loader` function has two input parameters：
+
+##### `Params`
+
+When a routing file is passed through `[]`, it is passed as a [dynamic route](/docs/guides/basic-features/routes#dynamic-route) and the dynamic route fragment is passed as an argument to the loader function：
+
+```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` is a [Fetch Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) instance.
+
+A common usage scenario is to obtain query parameters via `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);
+}
+```
+
+#### Return value
+
+`loader` 函数的返回值可以是任何可序列化的内容，也可以是一个 [Fetch Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) 实例：
+
+```tsx
+export const loader = async(): ProfileData => {
+  return {
+    message: 'hello world',
+  }
+}
+```
+
+By default, the response `Content-type` returned by `loader` is `application/json` and `status` is 200, which you can set by customizing `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",
+    },
+  });
+}
+```
+
+### Request API
+
+Modern.js does a polyfill of the `fetch` API to initiate requests, which is consistent with the browser's `fetch` API, but can also be used on the server side to initiate requests, meaning that both CSRs and SSRs can use the unified `fetch` API for data fetching：
+
+```tsx
+export async function loader(){
+  const res = await fetch('https://api/user/profile');
+}
+```
+
+### Error handling
+
+In the `loader` function, errors can be handled by `throw error` or `throw response`. When an error is thrown in the `loader` function, Modern.js will stop executing the code in the current loader and switch the front-end UI to the defined [`ErrorBoundary`](/docs/guides/basic-features/routes#errorboundary) component.
+
+```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;
+```
+
+### Get data from upper level components
+
+In many cases, the child component needs to access the data in the ancestor's loader, and you can easily access the ancestor's data with `useRouteLoaderData`: `useRouteLoaderData`:
+
+```tsx
+// routes/user/profile/page.tsx
+import { useRouteLoaderData } from '@modern-js/runtime/router';
+
+export default function UserLayout() {
+  // Get the data returned by the loader in routes/user/layout.tsx
+  const data = useRouteLoaderData('user/layout');
+  return (
+    <div>
+      <h1>{data.name}</h1>
+      <h2>{data.age}</h2>
+    </div>
+  );
+}
+```
+
+`userRouteLoaderData` takes one parameter `routeId`,When using conventional routing, Modern.js will automatically generate `routeId` for you. The value of `routeId` is the path of the corresponding component relative to `src/routes`, as in the example above, the child component wants to get the data returned by the loader in `routes/user/layout.tsx`, the value of `routeId` is  `user/layout`.
+
+In a multi-entry (MPA) scenario, the value of `routeId` needs to be added to the name of the corresponding entry, and the entry name is usually the entry directory name if not specified, such as the following directory structure:
+```bash
+.
+└── src
+    ├── entry1
+    │   ├── layout.tsx
+    └── entry2
+        └── layout.tsx
+```
+
+If you want to get the data returned by the loader in `entry1/layout.tsx`, the value of `routeId` is `entry1_layout`.
+
+### (WIP)Loading UI
+
+:::info
+This feature is currently experimental and the API may be adjusted in the future.
+Currently, only CSR is supported, so stay tuned for Streaming SSR.
+:::
+
+Because fetching data is asynchronous, it is often necessary to display a loading UI before the data fetching is complete, and the following is a basic example, assuming the following directory structure:
+
+```bash
+.
+└── routes
+    ├── layout.tsx
+    └── user
+        ├── layout.tsx
+        └── page.ts
+```
+
+We get the user's detailed data in `user/layout.tsx` and want to show a loading UI before getting the data.
+
+First, add a `loading.tsx` component to the `routes` directory in your project, which will take effect for all routes in the subdirectory (e.g. user):
+```bash
+.
+└── routes
+    ├── layout.tsx
+    └── user
+        ├── layout.tsx
+        └── page.ts
+```
+
+:::info
+For specific usage of the loading component, see [loading](/docs/guides/basic-features/routes#loading)
+:::
+
+Then, add the following code to `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
+For specific usage of the Await component, see [Await](/docs/guides/basic-features/routes#await)
+
+For specific usage of the defer function, see[defer](https://reactrouter.com/en/main/guides/deferred)
+:::
+
+### Side Effects
+
+As mentioned above, Modern.js removes the server-side code `loader` from the client bundle, there are some things you need to be aware of, if you don't want to suffer from side effects, you can define `loader` in a [separate file](#loader-is-defined-in-a-separate-file).
+
+:::info
+In CSR scenarios, the side effects usually have less impact on the project, but you are still expected to follow the following conventions.
+:::
+
+Side effects of a module can be thought of as code that is executed when the module is loaded, such as:
+
+```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>;
+}
+```
+
+Since `console.log` is executed when `routes/user/page.tsx` is loaded, the compiler does not remove it and `transformProfile` is bundled into the client bundle.
+
+So we do not recommend having any code executed when the module is loaded, including project code and third-party modules used, and the following are some of the ways we do not recommend writing.
+
+```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 <></>
+}
+```
+
+In SSR scenarios, you usually need to use Server Side packages  in the `loader` function, and for non-Node.js core packages, you need to do a re-export using a specially agreed file, such as using `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';
+```
+
+### Wrong usage
+
+1. Only serializable data can be returned in `loader`. In SSR environments, the return value of the `loader` function is serialized to a JSON string, which is then deserialized to an object on the client side. Therefore, no non-serializable data (such as functions) can be returned in the `loader` function.
+
+:::warning
+This restriction is not currently in place under CSR, but we strongly recommend that you follow it, and we may add it under CSR in the future.
+:::
+
+```ts
+// This won't work!
+export const loader = () => {
+  return {
+    user: {},
+    method: () => {
+
+    }
+  }
+}
+```
+
+2. Modern.js will call the `loader` function for you, you shouldn't call it yourself in the component.
+
+```tsx
+// 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. When run on the server side, the `loader` functions are packaged into a single bundle, so we do not recommend using `__filename` and `__dirname` for server-side code.
+
+
 ## useLoader(Old)
 
 **`useLoader`** is an API in Modern.js old version. The API is a React Hook specially provided for SSR applications, allowing developers to fetch data in components.

package/en/docusaurus-plugin-content-docs/current/guides/basic-features/html.md

@@ -3,9 +3,9 @@ title: HTML Template
 sidebar_position: 9
 ---
 
-Modern.js provides **JSX template** and **traditional template** for customizing HTML template.
+Modern.js provides **JSX syntax**  and **HTML(Ejs) syntax** for customizing HTML template.
 
-## JSX Template
+## JSX syntax
 
 Modern.js convention, in the `src/`, or in the entry directory, you can create `Document.[jt]sx` and export a component by default. The rendering result of this component can be used as an HTML template for the entry.
 
@@ -141,11 +141,11 @@ The above JSX component will generate the following HTML template:
 </html>
 ```
 
-## Traditional template
+## Html Synxtax
 
-Modern.js also supports traditional HTML templates. By default, an HTML template is built into Modern.js application project to generate HTML code.
+Modern.js also supports HTML syntax. By default, an HTML template is built into the Modern.js application project to generate HTML code.
 
-Based on traditional HTML templates, Modern.js provides **Custom HTML Fragments** and **Fully Custom HTML Templates** two ways to customize templates.
+Based on HTML syntax templates, Modern.js provides **Custom HTML Fragments** and **Fully Custom HTML Templates** two ways to customize templates.
 
 ### Custom HTML Fragments
 

package/package.json

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

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

@@ -1,6 +1,6 @@
 ---
 title: index.[tj]s
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 应用项目自定义路由入口标识。

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

@@ -1,6 +1,6 @@
 ---
 title: pages/
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 应用使用基于文件系统路由时的入口标识。

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

@@ -0,0 +1,89 @@
+---
+title: routes/
+sidebar_position: 2
+---
+
+应用使用基于文件系统路由时的入口标识。
+
+当项目结构为 `Routes 入口` 类型时， 会分析 `src/routes` 目录下的文件得到客户端路由配置。具体用法请查看[约定式路由](/docs/guides/basic-features/routes)
+
+任何在 `src/routes` 下的 `layout.[tj]sx` 和 `page.[tj]sx` 都会作为应用的路由：
+```bash {3}
+.
+└── routes
+    ├── layout.tsx
+    ├── page.tsx
+    └── user
+        ├── layout.tsx
+        └── page.tsx
+```
+
+## 基本示例
+
+`routes` 目录下的目录名会作为路由 url 的映射，其中 `layout.tsx` 中作为布局组件，`page.tsx` 作为内容组件，是整条路由的叶子节点，例如以下目录结构：
+
+```bash
+.
+└── routes
+    ├── page.tsx
+    └── user
+        └── page.tsx
+```
+
+会产出下面两条路由：
+- `/`
+- `/user`
+
+## 动态路由
+
+如果路由文件的目录名以 `[]` 命名，生成的路由会作为动态路由。例如以下文件目录：
+```
+└── routes
+    ├── [id]
+    │   └── page.tsx
+    ├── blog
+    │   └── page.tsx
+    └── page.tsx
+```
+
+`routes/[id]/page.tsx` 文件会转为 `/:id` 路由。除了可以确切匹配的 `/blog` 路由，其他所有 `/xxx` 都会匹配到该路由。
+
+在组件中，可以通过 [useParams](/docs/apis/app/runtime/router/#useparams) 获取对应命名的参数。
+
+在 loader 中，params 会作为 [loader](/docs/guides/basic-features/data-fetch#loader-函数) 的入参，通过 `params` 的属性可以获取到对应的参数。
+
+
+## 布局组件
+
+如下面的例子，可以通过添加 `layout.tsx`，为所有路由组件添加公共的布局组件：
+
+```bash
+.
+└── routes
+    ├── layout.tsx
+    ├── page.tsx
+    └── user
+        ├── layout.tsx
+        └── page.tsx
+```
+
+在布局组件中可以通过使用 `<Outlet>` 表示子组件：
+```tsx title=routes/layout.tsx
+import { Link, Outlet, useLoaderData } from '@modern-js/runtime/router';
+
+export default () => {
+  return (
+    <>
+      <Outlet></Outlet>
+    </>
+  )
+}
+```
+
+:::note
+`<Outlet>` 是 React Router 6 中新的 API，详情可以查看 [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
+:::
+
+
+
+

package/zh/configure/app/dev/with-master-app.md

@@ -0,0 +1,32 @@
+---
+sidebar_label: withMasterApp
+---
+
+# dev.withMasterApp
+
+
+
+* 类型： `Object`
+* 默认值： `null`
+
+当项目为微前端子应用的时候，可以使用 `withMasterApp` 配置启用子应用调试模式。
+
+:::caution 注意
+使用子应用调试的模式时，应该先确保主应用开启了线上 debug 模式。
+:::
+
+```js title=modern.config.js
+export default defineConfig({
+  dev: {
+    withMasterApp: {
+      // 主应用的路径
+      moduleApp: 'https://www.masterApp.com',
+      // 子应用的名称
+      moduleName: 'Contact'
+    }
+  }
+})
+```
+
+- moduleApp: `string` 主应用的线上地址。
+- moduleName: `Contact` 子应用的名称（需要和在主应用中注册的模块名匹配）。

package/zh/configure/app/runtime/master-app.md

@@ -13,10 +13,24 @@ sidebar_label: masterApp
 ## 示例
 
 import EnableMicroFrontend from '@site-docs/components/enable-micro-frontend.md';
-import MasterManifestAppConfig from '@site-docs/components/micro-master-manifest-config.md';
 
 <EnableMicroFrontend />
-<MasterManifestAppConfig />
+
+## `manifest`
+
+```ts
+interface Manifest {
+  getAppList?: ()=> Array<AppInfo>
+}
+```
+
+#### `getAppList?`
+
+通过 `getAppList` 配置，可以自定义如何获取远程列表数据
+
+```ts
+type GetAppList = ()=> Promise<Array<AppInfo>>;
+```
 
 
 ### apps

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` 合并。