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

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

@@ -0,0 +1,256 @@
+---
+title: 添加业务模型（状态管理）
+---
+
+上一章节中，我们把硬编码的 `mockData` 改成从 Data Loader 中加载。
+
+这一章节中，我们会进一步实现项目的功能，例如实现 **Archive** 按钮的功能，把联系人归档。
+
+因此会开始编写一些跟 UI 完全无关的业务逻辑，如果继续写在组件代码中，会产生越来越多的面条式代码。为此，我们引入了一种叫做**业务模型（Model）**的代码模块，将这些业务逻辑和 UI 解耦。
+
+## 实现 Model
+
+创建一个完整的 Model 首先需要定义**状态（state）**，包括状态中数据的名称和初始值。
+
+我们使用 Model 来管理联系人列表的数据，因此定义如下数据状态：
+
+```js
+const state = {
+  items: [],
+};
+```
+
+使用 TS 语法，可以定义更完整的类型信息，比如 items 里每个对象都应该有 `name`、`email` 字段。为了实现归档功能，还需要创建 `archived` 字段保存这个联系人是否已被归档的状态。
+
+我们还需要一个字段用来访问所有已归档的联系人，可以定义 **computed** 类型的字段，对已有的数据做转换：
+
+```js
+const computed = {
+  archived: ({ items }) => {
+    return items.filter(item => item.archived);
+  },
+};
+```
+
+computed 类型字段的定义方式是函数，但使用时可以像普通字段一样通过 state 访问。
+
+:::info
+Modern.js 集成了 [Immer](https://immerjs.github.io/immer/)，能够像操作 JS 中常规的可变数据一样，去写这种状态转移的逻辑。
+:::
+
+实现 Archive 按钮时，我们需要一个 `archive` 函数，负责修改指定联系人的 `archived` 字段，我们把这种函数都叫作 **action**：
+
+```js
+const actions = {
+  archive(draft, payload) {
+    const target = draft.items.find(item => item.email === payload);
+    if (target) {
+      target.archived = true;
+    }
+  },
+};
+```
+
+action 函数是一种**纯函数**，确定的输入得到确定的输出（转移后的状态），不应该有任何副作用。
+
+函数的第一个参数是 Immer 提供的 Draft State，第二个参数是 action 被调用时传入的参数（后面会介绍怎么调用）。
+
+我们尝试完整实现它们：
+
+```js
+const state = {
+  items: [],
+  pending: false,
+  error: null,
+};
+
+const computed = {
+  archived: ({ items }) => {
+    return items.filter(item => item.archived);
+  },
+};
+
+const actions = {
+  archive(draft, payload) {
+    const target = draft.items.find(item => item.email === payload);
+    if (target) {
+      target.archived = true;
+    }
+  },
+};
+```
+
+接下来我们把上面的代码连起来，放在同一个 Model 文件里。首先执行以下命令，创建新的文件目录：
+
+```bash
+mkdir -p src/models/
+touch src/models/contacts.ts
+```
+
+添加 `src/models/contacts.ts` 的内容：
+
+```tsx
+import { model } from "@modern-js/runtime/model";
+
+type State = {
+  items: {
+    avatar: string;
+    name: string;
+    email: string;
+    archived?: boolean;
+  }[];
+  pending: boolean;
+  error: null | Error;
+};
+
+export default model<State>("contacts").define({
+  state: {
+    items: [],
+    pending: false,
+    error: null,
+  },
+  computed: {
+    archived: ({ items }: State) => items.filter((item) => item.archived),
+  },
+  actions: {
+    archive(draft, payload) {
+      const target = draft.items.find((item) => item.email === payload)!;
+      if (target) {
+        target.archived = true;
+      }
+    },
+  },
+});
+```
+
+我们把一个包含 state，action 等要素的 plain object 称作 **Model Spec**，Modern.js 提供了 [Model API](/docs/apis/app/runtime/model/model_)，可以根据 Model Spec 生成 **Model**。
+
+## 使用 Model
+
+现在我们直接使用这个 Model，把项目的逻辑补充起来。
+
+首先修改 `src/components/Item/index.tsx`，添加 **Archive 按钮**的 UI 和交互，内容如下：
+
+```tsx
+import Avatar from "../Avatar";
+
+type InfoProps = {
+  avatar: string;
+  name: string;
+  email: string;
+  archived?: boolean;
+};
+
+const Item = ({
+  info,
+  onArchive,
+}: {
+  info: InfoProps;
+  onArchive?: () => void;
+}) => {
+  const { avatar, name, email, archived } = info;
+  return (
+    <div className="flex p-4 items-center border-gray-200 border-b">
+      <Avatar src={avatar} />
+      <div className="ml-4 custom-text-gray flex-1 flex justify-between">
+        <div className="flex-1">
+          <p>{name}</p>
+          <p>{email}</p>
+        </div>
+        <button
+          type="button"
+          disabled={archived}
+          onClick={onArchive}
+          className={`text-white font-bold py-2 px-4 rounded-full ${
+            archived
+              ? "bg-gray-400 cursor-default"
+              : "bg-blue-500 hover:bg-blue-700"
+          }`}
+        >
+          {archived ? "Archived" : "Archive"}
+        </button>
+      </div>
+    </div>
+  );
+};
+
+export default Item;
+```
+
+接下来，我们修改 `src/routes/page.tsx`，为 `<Item>` 组件传递更多参数：
+
+```tsx
+import { Helmet } from "@modern-js/runtime/head";
+import { useModel } from "@modern-js/runtime/model";
+import { useLoaderData } from "@modern-js/runtime/router";
+import { List } from "antd";
+import { name, internet } from "faker";
+import Item from "../components/Item";
+import contacts from "../models/contacts";
+
+type LoaderData = {
+  code: number;
+  data: {
+    name: string;
+    avatar: string;
+    email: string;
+  }[];
+};
+
+export const loader = async (): Promise<LoaderData> => {
+  const data = new Array(20).fill(0).map(() => {
+    const firstName = name.firstName();
+    return {
+      name: firstName,
+      avatar: `https://avatars.dicebear.com/api/identicon/${firstName}.svg`,
+      email: internet.email(),
+      archived: false,
+    };
+  });
+
+  return {
+    code: 200,
+    data,
+  };
+};
+
+function Index() {
+  const { data } = useLoaderData() as LoaderData;
+  const [{ items }, { archive, setItem }] = useModel(contacts);
+  if (items.length === 0) {
+    setItem(data);
+  }
+
+  return (
+    <div className="container lg mx-auto">
+      <Helmet>
+        <title>All</title>
+      </Helmet>
+      <List
+        dataSource={items}
+        renderItem={(info) => (
+          <Item
+            key={info.name}
+            info={info}
+            onArchive={() => {
+              archive(info.email);
+            }}
+          />
+        )}
+      />
+    </div>
+  );
+}
+
+export default Index;
+```
+
+`useModel` 是 Modern.js 提供的 hooks API。可以在组件中提供 Model 中定义的 state，或通过 actions 调用 Model 中定义的 side effect 与 action，从而改变 Model 的 state。
+
+Model 是业务逻辑，是计算过程，本身不创建也不持有状态。只有在被组件用 hooks API 使用后，才在指定的地方创建状态。
+
+执行 `pnpm run dev`，点击 **Archive 按钮**，可以看到页面 UI 发生了变化。
+
+:::note
+上述例子中，`useLoaderData` 其实在每次切换路由时都会执行。因为我们在 Data Loader 里使用了 fake 数据，每次返回的数据是不同的。但我们优先使用了 Model 中的数据，因此切换路由时数据没有发生改变。
+:::

package/zh/tutorials/first-app/c07-container.md

@@ -0,0 +1,268 @@
+---
+title: 添加容器组件
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+上一章节中，我们初步引入**业务模型**，从 UI 组件中拆分出这部分逻辑。`page.tsx` 中不再包含 UI 无关的业务逻辑实现细节，只需要使用 Model，就能实现同样的功能。
+
+这一章节中，我们要进一步利用 Model 中实现的业务逻辑，让 `page.tsx` 和 `archived/page.tsx` 获取同一份数据。并实现 Archive 按钮，点击按钮能把联系人归档，只显示在 Archives 列表里，不显示在 All 列表里。
+
+## 使用完整 Model
+
+因为两个页面需要共用同一套状态（联系人列表数据、联系人是否被归档），都需要包含加载初始数据的逻辑，因此我们需要在更上一层完成数据获取。
+
+Modern.js 支持在 `layout.tsx` 通过 Data Loader 获取数据，我们先数据获取这部分代码移动到 `src/routes/layout.tsx` 中：
+
+```tsx
+import { name, internet } from "faker";
+import { useModel } from "@modern-js/runtime/model";
+import contacts from "../models/contacts";
+
+type LoaderData = {
+  code: number;
+  data: {
+    name: string;
+    avatar: string;
+    email: string;
+  }[];
+};
+
+export const loader = async (): Promise<LoaderData> => {
+  const data = new Array(20).fill(0).map(() => {
+    const firstName = name.firstName();
+    return {
+      name: firstName,
+      avatar: `https://avatars.dicebear.com/api/identicon/${firstName}.svg`,
+      email: internet.email(),
+      archived: false,
+    };
+  });
+
+  return {
+    code: 200,
+    data,
+  };
+};
+
+export default function Layout() {
+  const { data } = useLoaderData() as LoaderData;
+  const [{ items }, { setItem }] = useModel(contacts);
+  if (items.length === 0) {
+    setItem(data);
+  }
+
+  const navigate = useNavigate();
+  ...
+}
+```
+
+在 `src/routes/page.tsx` 中，直接使用 Model，获取数据：
+
+```tsx
+import { Helmet } from "@modern-js/runtime/head";
+import { useModel } from "@modern-js/runtime/model";
+import { List } from "antd";
+import Item from "../components/Item";
+import contacts from "../models/contacts";
+
+function Index() {
+  const [{ items }, { archive }] = useModel(contacts);
+
+  return (
+    <div className="container lg mx-auto">
+      <Helmet>
+        <title>All</title>
+      </Helmet>
+      <List
+        dataSource={items}
+        renderItem={(info) => (
+          <Item
+            key={info.name}
+            info={info}
+            onArchive={() => {
+              archive(info.email);
+            }}
+          />
+        )}
+      />
+    </div>
+  );
+}
+
+export default Index;
+```
+
+同样在 `archived/page.tsx` 中，删除原本的 `mockData` 逻辑，使用 Model 中 computed 的 `archived` 值作为数据源：
+
+```tsx
+import { Helmet } from "@modern-js/runtime/head";
+import { useModel } from "@modern-js/runtime/model";
+import { List } from "antd";
+import Item from "../../components/Item";
+import contacts from "../../models/contacts";
+
+function Index() {
+  const [{ archived }, { archive }] = useModel(contacts);
+
+  return (
+    <div className="container lg mx-auto">
+      <Helmet>
+        <title>Archives</title>
+      </Helmet>
+      <List
+        dataSource={archived}
+        renderItem={(info) => (
+          <Item
+            key={info.name}
+            info={info}
+            onArchive={() => {
+              archive(info.email);
+            }}
+          />
+        )}
+      />
+    </div>
+  );
+}
+
+export default Index;
+```
+
+执行 `pnpm run dev`，访问 `http://localhost:8080/`，点击 Archive 按钮后，可以看到按钮置灰：
+
+![display](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c07-contacts-all.png)
+
+接下来点击顶部导航，切换到 Archives 列表，可以发现刚才 **Archive** 的联系人已经出现在列表当中：
+
+![display](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c07-contacts-archives.png)
+
+## 抽离容器组件
+
+前面章节中，我们把项目中的业务逻辑拆分成了两个 layer，一个是**视图组件**，另一个是**业务模块**。前者负责 UI 展示、交互等，后者负责实现 UI 无关的业务逻辑，专门管理状态。
+
+像 `src/routes/page.tsx` 和 `src/routes/archives/page.tsx` 这样使用了 `useModel` API 的组件，负责把 View 和 Model 这两个 layer 连接起来，类似传统 MVC 架构中 Controller 的角色，在 Modern.js 里我们沿用习惯，把它们称作**容器组件（Container）**。
+
+容器组件推荐放在专门的 `containers/` 目录里，我们执行以下命令，创建新的文件：
+
+<Tabs>
+<TabItem value="macOS" label="macOS" default>
+
+```bash
+mkdir -p src/containers
+touch src/containers/Contacts.tsx
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows">
+
+```powershell
+mkdir -p src/containers
+ni src/containers/Contacts.tsx
+```
+
+</TabItem>
+</Tabs>
+
+我们将原本两个 `page.tsx` 中公共的部分抽离出来，`src/containers/Contacts.tsx` 的代码如下：
+
+```tsx
+import { Helmet } from "@modern-js/runtime/head";
+import { useModel } from "@modern-js/runtime/model";
+import { List } from "antd";
+import Item from "../components/Item";
+import contacts from "../models/contacts";
+
+function Contacts({
+  title,
+  source,
+}: {
+  title: string;
+  source: "items" | "archived";
+}) {
+  const [state, { archive }] = useModel(contacts);
+
+  return (
+    <div className="container lg mx-auto">
+      <Helmet>
+        <title>{title}</title>
+      </Helmet>
+      <List
+        dataSource={state[source]}
+        renderItem={(info) => (
+          <Item
+            key={info.name}
+            info={info}
+            onArchive={() => {
+              archive(info.email);
+            }}
+          />
+        )}
+      />
+    </div>
+  );
+}
+
+export default Contacts;
+```
+
+修改 `src/routes/page.tsx` 和 `src/routes/archives/page.tsx` 的代码：
+
+```tsx title="src/routes/page.tsx"
+import Contacts from "../containers/Contacts";
+
+function Index() {
+  return <Contacts title="All" source="items" />;
+}
+
+export default Index;
+```
+
+```tsx title="src/routes/archives/page.tsx"
+import Contacts from "../../containers/Contacts";
+
+function Index() {
+  return <Contacts title="Archives" source="archived" />;
+}
+
+export default Index;
+```
+
+重构完成，现在的项目结构是：
+
+```md
+.
+├── README.md
+├── dist
+├── modern.config.ts
+├── node_modules
+├── package.json
+├── pnpm-lock.yaml
+├── src
+│   ├── components
+│   │   ├── Avatar
+│   │   │   └── index.tsx
+│   │   └── Item
+│   │       └── index.tsx
+│   ├── containers
+│   │   └── Contacts.tsx
+│   ├── models
+│   │   └── contacts.ts
+│   ├── modern-app-env.d.ts
+│   ├── routes
+│   │   ├── archives
+│   │   │   └── page.tsx
+│   │   ├── layout.tsx
+│   │   └── page.tsx
+│   └── styles
+│       └── utils.css
+└── tsconfig.json
+```
+
+`components/` 里的**视图组件**，都是目录形式，如 `Avatar/index.tsx`。而 `containers/` 里的**容器组件**，都是单文件形式，如 `contacts.tsx`。**这是我们推荐的一种最佳实践**。
+
+在​ [添加 UI 组件（Component）](./c02-component.md) 章节提到过，视图组件用目录形式，是因为视图组件负责实现 UI 展示和交互细节，可以演变的复杂。用目录形式，可以方便增加子文件，包括专用的资源（图片等）、专用子组件、CSS 文件等。在这个目录内部可以随意重构，只考虑最小局部。
+
+而容器组件只负责连接，是一个胶水层，复杂的业务逻辑和实现细节都交给 View 层和 Model 层去实现。容器组件自己应该保持简单清晰，不应该包含复杂实现细节，所以不应该有内部结构。采用单文件形式不但更简洁，也能起到约束作用，提醒开发者不要把容器组件写复杂。
+

package/zh/tutorials/first-app/c08-entries.md

@@ -0,0 +1,134 @@
+---
+title: 添加应用入口
+---
+
+上一个章节中，我们基本完成了联系人列表应用的开发，介绍了 Modern.js 中部分功能的用法，以及推荐的最佳实践。
+
+这一章节中，我们将介绍如何为应用添加新的入口。
+
+## 新建入口
+
+一个完整的项目可能需要多个入口，Modern.js 支持自动创建新入口，前面的章节中提到过，`pnpm run new` 可以启用可选功能。
+
+我们也可以通过它来创建新的工程元素，在项目根目录下执行 `pnpm run new`：
+
+```bash
+? 请选择你想要的操作 创建工程元素
+? 创建工程元素 新建「应用入口」
+? 请填写入口名称 (entry) landing-page
+```
+
+创建完成，项目会变成这样：
+
+```md
+.
+├── README.md
+├── modern.config.ts
+├── node_modules
+├── package.json
+├── pnpm-lock.yaml
+├── src
+│   ├── modern-app-env.d.ts
+│   ├── landing-page
+│   │   └── routes
+│   │       ├── index.css
+│   │       ├── layout.tsx
+│   │       └── page.tsx
+│   └── myapp
+│       ├── components
+│       │   ├── Avatar
+│       │   │   └── index.tsx
+│       │   └── Item
+│       │       └── index.tsx
+│       ├── containers
+│       │   └── Contacts.tsx
+│       ├── models
+│       │   └── contacts.ts
+│       ├── routes
+│       │   ├── archives
+│       │   │   └── page.tsx
+│       │   ├── layout.tsx
+│       │   └── page.tsx
+│       └── styles
+│           └── utils.css
+└── tsconfig.json
+
+```
+
+可以看到联系人列表应用的文件，都被自动重构到 `src/myapp/` 里。
+
+同时新建了一个 `src/landing-page/`，里面同样有 `routes/*`（`pnpm run new` 命令只做了这些事，所以你也可以很容易的手动创建新入口或修改入口）
+
+执行 `pnpm run dev`，显示：
+
+![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c08-entries-myapp.png)
+
+访问 `http://localhost:8080/`，可以像之前一样看到应用程序。
+
+访问 `http://localhost:8080/landing-page`，可以看到刚创建的新入口 `landing-page` 的页面（Modern.js 自动生成的默认页面）。
+
+Modern.js 框架的设计原则之一是【[约定优于配置（Convention over Configuration）](https://en.wikipedia.org/wiki/Convention_over_configuration)】，多数情况下可以按约定直接写代码，不需要做任何配置，这里 `src/` 中的目录结构就是一种约定：
+
+`src/myapp/` 和 `src/landing-page/` 被自动识别为两个应用入口：myapp 和 landing-page。
+
+其中 `src/myapp/` 的目录名跟项目名（`package.json` 里的 `name`）一致，会被认为是项目**主入口**，项目 URL 的根路径（开发环境里默认是 `http://localhost:8080/`）会自动指向主入口。
+
+其他入口的 URL，是在根路径后追加入口名，比如 `http://localhost:8080/landing-page`。
+
+接下来，我们把 `src/myapp/` 重命名为 `src/contacts/`：
+
+```bash
+mv src/myapp src/contacts
+```
+
+再次执行 `pnpm run dev`，结果变成：
+
+![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c08-entries-contacts.png)
+
+现在不再有主入口，联系人列表现在是一个普通入口，需要用 `http://localhost:8080/contacts` 访问。
+
+
+## 按入口修改配置
+
+我们可以在 Modern.js 配置文件里，自己写代码来控制项目的配置。
+
+现在，修改 `modern.config.ts` 里面添加内容：
+
+```typescript
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  runtime: {
+    router: true,
+    state: true,
+  },
+  server: {
+    ssr: true,
+    ssrByEntries: {
+      'landing-page': false,
+    },
+  },
+});
+```
+
+执行 `pnpm run dev`，再用浏览器打开 `view-source:http://localhost:8080/landing-page`，可以看到 `landing-page` 网页内容是通过 js 动态加载的，且此页面的 SSR 功能被关闭。
+
+如果注释掉 `ssrByEntries` 和它的值，landing-page 的 SSR 功能就恢复开启了。
+
+还有一些时候，需要一些更复杂的逻辑来做设置，比如需要 JS 变量、表达式、导入模块等，例如在只在开发环境里开启 SSR：
+
+```js
+export default defineConfig({
+  server: {
+    ssrByEntries: {
+      'landing-page': process.env.NODE_ENV !== 'production',
+    },
+  },
+};
+```
+
+到底为止，我们的联系人列表应用的雏形就基本完成了 👏👏👏。
+
+## 下一步
+
+接下来你可以通过了解[指南](/docs/guides/overview)、[配置](/docs/configure/app/usage) 等更多教程，进一步完善你的应用。

package/zh/tutorials/foundations/introduction.md

@@ -38,4 +38,4 @@ Modern.js 能为开发者提供极致的**开发体验（Development Experience
 
 如果你是前端初学者，可能会觉得这些概念有些复杂。我们提供了一些 [JavaScript 和 React](/docs/tutorials/foundations/basic) 的学习资料，你可以先对它们做些了解。
 
-如果你是有经验的开发者，希望了解如何使用 Modern.js，你可以尝试[创建第一个应用](/docs/tutorials/first-app/overview)，或是阅读[指南](/docs/guides/overview)。
+如果你是有经验的开发者，希望了解如何使用 Modern.js，你可以尝试[创建第一个应用](/docs/tutorials/first-app/c01-start)，或是阅读[指南](/docs/guides/overview)。

package/en/docusaurus-plugin-content-docs/current/configure/app/output/enable-modern-mode.md

@@ -1,34 +0,0 @@
----
-sidebar_label: enableModernMode
----
-
-# output.enableModernMode
-
-* Type: `boolean`
-* Default: `false`
-
-Modern.js default value to build JS products with Polyfill for older browsers. After opening this configuration, you can automatically build JS products that are not degraded for modern browser syntax in the production environment. The product filename format is `[name].[hash]-es6/js`.
-
-For example, configure the following configuration:
-
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  output: {
-    enableModernMode: true,
-  },
-});
-```
-
-After executing the `build` command, modern is packaged in addition to the normal Client packaging, and the `dist/static/js` directory will generate es6 related products.
-
-![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/output-enable-modern-build.jpeg)
-
-After executing the `start` command, use the latest version Chrome browser access, and observe that the requested JS resource in the Network is an es6 product.
-
-![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/output-enable-modern-network.jpeg)
-
-:::info
-For more information, see [Client side compatibility](/docs/guides/advanced-features/compatibility)。
-:::