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

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

@@ -0,0 +1,94 @@
+---
+title: 创建项目
+---
+
+从这一章节开始，我们将进入实战教程部分。在实战教程中，我们将会从环境准备开始，从简单到复杂，一步一步搭建一个真实的项目。
+
+## 环境准备
+
+import Prerequisites from '@site-docs/components/prerequisites.md'
+
+<Prerequisites />
+
+## 初始化项目
+
+我们创建新的目录，通过命令行工具初始化项目：
+
+```bash
+mkdir myapp && cd myapp
+npx @modern-js/create
+```
+
+import InitApp from '@site-docs/components/init-app.md'
+
+<InitApp />
+
+## 调试项目
+
+import DebugApp from '@site-docs/components/debug-app.md'
+
+<DebugApp />
+
+## 修改代码
+
+我们将原本的示例代码删除，替换成一个简单的联系人列表：
+
+```tsx title="src/routes/page.tsx"
+const getAvatar = (users: Array<{ name: string; email: string }>) =>
+  users.map(user => ({
+    ...user,
+    avatar: `https://avatars.dicebear.com/v2/identicon/${user.name}.svg`,
+  }));
+
+const mockData = getAvatar([
+  { name: 'Thomas', email: 'w.kccip@bllmfbgv.dm' },
+  { name: 'Chow', email: 'f.lfqljnlk@ywoefljhc.af' },
+  { name: 'Bradley', email: 'd.wfovsqyo@gpkcjwjgb.fr' },
+  { name: 'Davis', email: '"t.kqkoj@utlkwnpwk.nu' },
+]);
+
+function App() {
+  return (
+    <ul>
+      {mockData.map(({ name, avatar, email }) => (
+        <li key={name}>
+          <img src={avatar} width={60} height={60} /> ---
+          <span>{name}</span> ---
+          <span>{email}</span>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+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
+```
+
+## 使用配置
+
+接下来，我们修改项目中的 `modern.config.ts`，开启 SSR 能力：
+
+```ts
+import { defineConfig } from '@modern-js/app-tools';
+
+// https://modernjs.dev/docs/apis/app/config
+export default defineConfig({
+  runtime: {
+    router: true,
+    state: true,
+  },
+  server: {
+    ssr: true,
+  },
+});
+```
+
+重新执行 `pnpm run dev`，可以发现项目已经在服务端完成了页面渲染。

package/zh/tutorials/first-app/c02-component.md

@@ -0,0 +1,56 @@
+---
+title: 编写 UI 组件
+---
+
+上一章节中，我们学习了如何初始化项目，并使用配置修改 Modern.js 的默认行为。
+
+这一章节中，我们继续沿用上一章节的项目代码，继续完善联系人列表。
+
+为了做更好的 UI 展示和交互，我们引入组件库 [Antd](https://ant.design/index-cn) 来开发，使用 `<List>` 组件来代替原始的列表。先添加依赖：
+
+```bash
+pnpm add antd
+```
+
+修改 `src/routes/page.tsx`，在顶部导入组件：
+
+```ts
+import { List } from 'antd';
+```
+
+修改 `<App>` 组件的实现：
+
+```tsx
+function App() {
+  return (
+    <div>
+      <List
+        dataSource={mockData}
+        renderItem={({ name, email, avatar }) => (
+          <List.Item key={name}>
+            <List.Item.Meta
+              avatar={<img alt="avatar" src={avatar} width={60} height={60} />}
+              title={name}
+              description={email}
+            />
+          </List.Item>
+        )}
+      />
+    </div>
+  );
+}
+```
+
+执行 `pnpm run dev`，查看运行结果：
+
+![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c02-antd-result.png)
+
+可以看到 Ant Design 导出的组件，已经具备了完整的样式。
+
+:::info 注
+Modern.js 会[自动按需导入 Ant Design 组件需要的 CSS](https://github.com/ant-design/babel-plugin-import)。
+:::
+
+:::note
+我们也可以使用其他组件库来实现同样的功能，例如 [Arco Design](https://arco.design/)。
+:::

package/zh/tutorials/first-app/c03-css.md

@@ -0,0 +1,305 @@
+---
+title: 添加样式
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+上一章节中，我们学习了如何使用使用三方库中的组件。
+
+这一章节中，我们将学习如何实现 UI 组件。
+
+## 使用 CSS 写 JS 组件
+
+首先我们希望自己控制联系人头像的展示，实现这种设计稿：
+
+![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c03-css-expect.jpg)
+
+假设没有现成的组件可以实现，那就需要自己写些 CSS 了，这里我们使用 [styled-components](https://styled-components.com/)，来实现类似的需求。Modern.js 开箱即用的支持 styled-components，既不需要安装依赖，也不需要做任何配置。
+
+styled-components 通过模块化的方式，避免了传统 CSS 写法上的诸多问题。例如直接在元素的 style 属性上写样式，UI 视觉上的细节也会跟 UI 结构上的细节和业务逻辑混在一起。或是 classname 需要避免全局空间重名，需要用到命名规范的问题。
+
+在 `src/routes/page.tsx` 里修改顶部的代码：
+
+```js
+import styled from '@modern-js/runtime/styled';
+```
+
+添加以下代码：
+
+```js
+const Avatar = styled.img`
+  width: 50px;
+  height: 50px;
+  border: 4px solid #0ef;
+  border-radius: 50%;
+`;
+```
+
+修改 `List.Item.Meta` 的代码：
+
+```tsx
+<List.Item.Meta
+  avatar={<Avatar src={avatar} />}
+  title={name}
+  description={email}
+/>
+```
+
+执行 `pnpm run dev`，可以看到预期的运行结果：
+
+![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c03-css-result1.png)
+
+接下来我们做一点重构，为了增强可读性，让代码更容易维护，可以把 Avatar 组件拆分出去。我们在终端执行以下命令，创建新的文件：
+
+<Tabs>
+<TabItem value="macOS" label="macOS" default>
+
+```bash
+mkdir -p src/components/Avatar
+touch src/components/Avatar/index.tsx
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows">
+
+```powershell
+mkdir -p src/components/Avatar
+ni src/components/Avatar/index.tsx
+```
+
+</TabItem>
+</Tabs>
+
+把 `src/routes/page.tsx` 里的 `<Avatar>` 实现删掉，修改为：
+
+```ts
+import Avatar from '../components/Avatar';
+```
+
+`src/components/Avatar/index.tsx` 的内容，修改为：
+
+```ts
+import styled from '@modern-js/runtime/styled';
+
+const Avatar = styled.img`
+  width: 50px;
+  height: 50px;
+  border: 4px solid #0ef;
+  border-radius: 50%;
+`;
+
+export default Avatar;
+```
+
+执行 `pnpm run dev`，运行结果应该是一样的。
+
+:::info 注
+采用目录形式 `Avatar/index.tsx` 而不是单文件形式 `Avatar.tsx` 的原因是，之后可以方便的在目录内部增加子文件，包括专用的资源（图片等）、专用子组件、CSS 文件等。
+:::
+
+
+## 使用 Utility
+
+我们已经使用 style-components 实现 `<Avatar>` 组件，但当前的 UI 仍然不能让人满意，缺乏专业感，例如列表项内部的布局有点粗糙，很多地方没对齐。
+
+现在，我们自己来实现一个更好的 `Item` 组件，实现这样的设计稿：
+
+![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/design2.png)
+
+这次要实现的 UI 更复杂，有内部结构，但另一方面，并没有 `<Avatar>` 组件的**很粗的亮蓝色边框**这样很特殊的 UI，都是很常规的水平垂直布局、居中、字体样式等。这种情况下，其实根本没必要写 CSS，有更高效的、跟 styled-components 互补的实现方式：**Utility Class**。
+
+Modern.js 集成了主流、轻量、通用的 Utility Class 工具库 [Tailwind CSS](https://tailwindcss.com/)。
+
+执行 `pnpm run new`，进行如下选择，开启 Tailwind CSS：
+
+```bash
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 启用 Tailwind CSS 支持
+```
+
+在 `src/routes/page.tsx` 顶部引入 Tailwind CSS 的 css 文件，就可以开始快速实现专业的 UI：
+
+```js
+import 'tailwindcss/base.css';
+import 'tailwindcss/components.css';
+import 'tailwindcss/utilities.css';
+```
+
+先创建 Item 组件：
+
+<Tabs>
+<TabItem value="macOS" label="macOS" default>
+
+```bash
+mkdir -p src/components/Item
+touch src/components/Item/index.tsx
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows">
+
+```powershell
+mkdir -p src/components/Item
+ni src/components/Item/index.tsx
+```
+
+</TabItem>
+</Tabs>
+
+修改 `src/routes/page.tsx`，把 `List` 的 `render` 实现交给 `Item` 组件：
+
+```js
+import { List } from 'antd';
+import 'tailwindcss/base.css';
+import 'tailwindcss/components.css';
+import 'tailwindcss/utilities.css';
+import Item from '../components/Item';
+
+const getAvatar = (users: Array<{ name: string; email: string }>) =>
+  users.map(user => ({
+    ...user,
+    avatar: `https://avatars.dicebear.com/v2/identicon/${user.name}.svg`,
+  }));
+
+const mockData = getAvatar([
+  { name: 'Thomas', email: 'w.kccip@bllmfbgv.dm' },
+  { name: 'Chow', email: 'f.lfqljnlk@ywoefljhc.af' },
+  { name: 'Bradley', email: 'd.wfovsqyo@gpkcjwjgb.fr' },
+  { name: 'Davis', email: '"t.kqkoj@utlkwnpwk.nu' },
+]);
+
+function Index() {
+  return (
+    <div className="container lg mx-auto">
+      <List
+        dataSource={mockData}
+        renderItem={info => <Item key={info.name} info={info} />}
+      />
+    </div>
+  );
+}
+
+export default Index;
+```
+
+在父容器的上使用了 [Utility Class](https://tailwindcss.com/docs/container) ，快速实现了最基本的最大宽度、居中等样式。
+
+接下来实现 `src/components/Item/index.tsx`：
+
+```tsx
+import Avatar from '../Avatar';
+
+type InfoProps = {
+  avatar: string;
+  name: string;
+  email: string;
+  archived?: boolean;
+};
+
+const Item = ({ info }: { info: InfoProps }) => {
+  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 flex-1 flex justify-between">
+        <div className="flex-1">
+          <p>{name}</p>
+          <p>{email}</p>
+        </div>
+        <button
+          type="button"
+          disabled={archived}
+          className={`bg-blue-500  text-white font-bold
+            py-2 px-4 rounded-full hover:bg-blue-700`}
+        >
+          Archive
+        </button>
+      </div>
+    </div>
+  );
+};
+
+export default Item;
+```
+
+执行 `pnpm run dev`，可以看到预期的运行结果：
+
+![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/result2.png)
+
+我们只使用了少量 Utility Class，比如 [Flex](https://tailwindcss.com/docs/display/)、[Padding](https://tailwindcss.com/docs/padding/)、[Margin](https://tailwindcss.com/docs/margin/)、[Text](https://tailwindcss.com/docs/text-color/)、[Font](https://tailwindcss.com/docs/font-weight/)、[Border](https://tailwindcss.com/docs/border-width)，不写一行 CSS 就实现了符合设计稿的专业 UI。
+
+
+## 自定义 Utility Class
+
+我们也可以自己实现新的 Utility Class，方便在代码间复用。
+
+Utility Class 本身也是一种**面向组件**的技术（将不同 class 用在一个组件上，等价于给这个组件设置了一些来自基类的属性），但 Utility Class 的 classname 是全局的（因为要用在任意组件/元素上），很适合用独立 CSS 文件来实现。
+
+创建一个新的 CSS 文件：
+
+<Tabs>
+<TabItem value="macOS" label="macOS" default>
+
+```bash
+mkdir -p src/styles
+touch src/styles/utils.css
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows">
+
+```powershell
+mkdir -p src/styles
+ni src/styles/utils.css
+```
+
+</TabItem>
+</Tabs>
+
+在 `src/routes/page.tsx` 里导入 `utils.css`：
+
+```js
+import '../styles/utils.css';
+```
+
+在 `src/routes/styles/utils.css` 里实现一个名为 `custom-text-gray` 的 Utility Class。
+
+```css
+:root {
+  --custom-text-color:rgb(113, 128, 150);
+}
+
+.custom-text-gray {
+  color: var(--custom-text-color);
+}
+```
+
+:::info 注
+Modern.js 集成了 [PostCSS](/docs/guides/basic-features/css/postcss)，支持现代 CSS 语法特性，比如 [custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*)。
+:::
+
+在 `src/routes/components/Item/index.tsx` 里使用，把：
+
+```js
+<div className="ml-4 flex-1 flex justify-between">
+```
+
+改成：
+
+```js
+<div className="ml-4 custom-text-gray flex-1 flex justify-between">
+```
+
+执行 `pnpm run dev`，可以看到字体颜色改变了：
+
+![design2](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/result3.png)
+
+:::info 注
+此处只是为了演示 Utility Class 用法。真实项目中，在有 Tailwind CSS 的情况下，这种 Utility Class 没什么价值，应该通过配置 Design System 的 [**theme**](https://tailwindcss.com/docs/customizing-colors) 来增加字体颜色。
+
+`utils.css` 也可以写成 `utils.scss` 或 `utils.less`，Modern.js 对 SCSS 和 Less 同样提供开箱即用的支持。
+
+不过在 PostCSS 的支持下，现代 CSS 应该足以满足这些开发需求，性能相较于预处理器也更好，建议优先用 .css 文件。
+:::
+

package/zh/tutorials/first-app/c04-routes.md

@@ -0,0 +1,169 @@
+---
+title: 添加客户端路由
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+上一章节中，我们学习了如何为创建 UI 组件，并添加样式。
+
+这一章节中，我们将会学习如何添加**客户端路由**。
+
+之前我们已经为联系人列表增加了 Archive 按钮，接下来我们添加一个客户端路由 `/archives`，访问这个路由时，只显示已存档的联系人，而原有的 `/` 继续显示所有联系人。
+
+新建 `src/routes/archives/page.tsx` 文件：
+
+<Tabs>
+<TabItem value="macOS" label="macOS" default>
+
+```bash
+mkdir -p src/routes/archives
+touch src/routes/archives/page.tsx
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows">
+
+```powershell
+mkdir -p src/routes/archives
+ni src/routes/archives/page.tsx
+```
+
+</TabItem>
+</Tabs>
+
+添加如下代码：
+
+```tsx
+import { List } from 'antd';
+import { Helmet } from '@modern-js/runtime/head';
+import Item from '../../components/Item';
+
+const getAvatar = (users: Array<{ name: string; email: string }>) =>
+  users.map(user => ({
+    ...user,
+    avatar: `https://avatars.dicebear.com/v2/identicon/${user.name}.svg`,
+  }));
+
+const getMockArchivedData = () =>
+  getAvatar([
+    { name: 'Thomas', email: 'w.kccip@bllmfbgv.dm' },
+    { name: 'Chow', email: 'f.lfqljnlk@ywoefljhc.af' },
+  ]);
+function Index() {
+  return (
+    <div className="container lg mx-auto">
+      <Helmet>
+        <title>Archives</title>
+      </Helmet>
+      <List
+        dataSource={getMockArchivedData()}
+        renderItem={info => <Item key={info.name} info={info} />}
+      />
+    </div>
+  );
+}
+
+export default Index;
+```
+
+这里使用了 [React Helmet](https://github.com/nfl/react-helmet) 的 `Helmet` 组件，在 `src/routes/page.tsx` 中也添加 Helmet 组件：
+
+```tsx
+import { Helmet } from '@modern-js/runtime/head';
+
+function Index() {
+  return (
+    <div className="container lg mx-auto">
+      <Helmet>
+        <title>All</title>
+      </Helmet>
+      ...
+    </div>
+  );
+}
+```
+
+:::info 注
+Modern.js 默认集成了 react-helmet，也可以结合 SSR 使用，满足 SEO 需求。
+:::
+
+因为现在有多个页面，都需要用到前面的 Utility Class，因此我们需要把样式文件移动到 `src/routes/layout.tsx`：
+
+```tsx
+import 'tailwindcss/base.css';
+import 'tailwindcss/components.css';
+import 'tailwindcss/utilities.css';
+import "../styles/utils.css";
+```
+
+执行 `pnpm run dev`，访问 `http://localhost:8080`，可以看到完整的联系人，页面的标题是 All：
+
+![display](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c04-all.png)
+
+访问 `http://localhost:8080/archives`，只会看到已存档的联系人，页面的标题是 Archives：
+
+![display1](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c04-archives.png)
+
+查看页面 HTML 源码，可以看到两个页面的内容是一样，是在客户端针对不同 URL 渲染不同内容。
+
+**接下来我们增加一个简单的导航栏，让用户能在两个列表之间切换**。
+
+打开 `src/routes/layout.tsx`，在顶部导入 Radio 组件：
+
+```tsx
+import { Radio } from 'antd';
+```
+
+然后将 UI 最顶部进行修改，增加一组单选框
+
+```tsx {4-9}
+export default function Layout() {
+  return (
+    <div>
+      <div className="h-16 p-2 flex items-center justify-center">
+        <Radio.Group onChange={handleSetList} value={currentList}>
+          <Radio value="/">All</Radio>
+          <Radio value="/archives">Archives</Radio>
+        </Radio.Group>
+      </div>
+      <Outlet />
+    </div>
+  );
+}
+```
+
+然后我们来实现 `currentList` 和 `handleSetList`。
+
+引入三个 React Hook：`useState` 和 `useNavigate` 和 `useParams`，以及 Ant Design 的事件类型定义：
+
+```js
+import { useState } from 'react';
+import { Radio, RadioChangeEvent } from 'antd';
+import { Outlet, useLocation, useNavigate } from "@modern-js/runtime/router";
+```
+
+最后在 Layout 组件里增加局部状态和相关逻辑：
+
+```tsx {2-9}
+export default function Layout() {
+  const navigate = useNavigate();
+  const location = useLocation();
+  const [currentList, setList] = useState(location.pathname || '/');
+  const handleSetList = (e: RadioChangeEvent) => {
+    const { value } = e.target;
+    setList(value);
+    navigate(value);
+  };
+  return (
+  ...
+}
+```
+
+到这里就已经完成了页面导航栏实现，执行 `pnpm run dev` 查看效果：
+
+![display2](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c04-switch.png)
+
+点击导航栏中 Archives，可以看到单选框的选中状态和 URL 都会变化，页面没有刷新，只发生了 CSR。
+
+通过 URL 访问两个页面，可以看到 HTML 内容是不同的，这是因为在 SSR 阶段页面就执行了客户端路由的逻辑，HTML 里已经包含了最终的渲染结果。

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

@@ -0,0 +1,82 @@
+---
+title: 添加 Loader
+---
+
+上一章节中，我们学习了如何添加客户端路由。
+
+这一章节中，我们将会学习如何**为路由组件添加 Loader**。
+
+到目前为止，我们都是通过硬编码的方式，为组件提供数据。如果要从远端获取数据，通常情况下会使用 `useEffect` 来做。但在启用 SSR 的情况下，`useEffect` 是不会在服务端执行的，所以这种 SSR 只能渲染很有限的 UI。
+
+Modern.js 为提供了 Data Loader 的能力，支持同构的在组件中获取数据，让 SSR 的价值最大化。
+
+下面我们演示如何为路由组件添加 Data Loader，并模拟远端数据获取。我们使用 faker 来 mock 需要的数据，首先安装依赖：
+
+```bash
+pnpm add faker@5
+pnpm add @types/faker@5 -D
+```
+
+修改 `src/routes/page.tsx`：
+
+```tsx
+import { name, internet } from "faker";
+
+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(),
+    };
+  });
+
+  return {
+    code: 200,
+    data,
+  };
+};
+```
+
+:::note
+Data Loader 并非只为 SSR 工作。在 CSR 项目中，Data Loader 也可以避免数据获取依赖 UI 渲染，解决请求瀑布流的问题。未来，Modern.js 也会为这一特性添加更多能力，例如预获取、数据缓存等。
+:::
+
+Modern.js 也提供了一个叫 `useLoaderData` 的 hooks API，我们修改 `src/routes/page.tsx` 导出的组件：
+
+```tsx {1,4,13}
+import { useLoaderData } from "@modern-js/runtime/router";
+
+function Index() {
+  const { data } = useLoaderData() as LoaderData;
+
+  return (
+    <div className="container lg mx-auto">
+      <Helmet>
+        <title>All</title>
+      </Helmet>
+      <List
+        dataSource={data}
+        renderItem={(info) => <Item key={info.name} info={info} />}
+      />
+    </div>
+  );
+}
+
+export default Index;
+```
+
+<!-- Todo 重新截图，SSR 内容 -->
+重新执行 `pnpm run dev`，查看 `view-source:http://localhost:8080/`，或在 devtools 的 Network 面板里查看 HTML 请求的「 Preview 」，可以看到 SSR 渲染出来的 HTML 已经包含完整的 UI：
+
+![display6](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/11/display6.png)