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

package/zh/tutorials/first-app/c06-css-and-component/6.4-design-system.md

@@ -1,83 +0,0 @@
----
-title: ​管理 Design System
----
-
-在前两个小节中，我们了解了 Utility Class 以及使用了 Modern.js 已经集成的 Utility Class 工具库 [Tailwind CSS](https://tailwindcss.com/)，
-默认提供的设计系统生成的样式可以满足实际开发中的部分需求。
-
-然而实际开发中，我们可能需要修改默认的设计系统规范。为此，Modern.js 提供了
-[`source.designSystem`](/docs/configure/app/source/design-system) 配置来管理项目的设计系统。
-
-## 覆盖默认配置
-
-要覆盖默认的设计系统配置，请在 `modern.config.ts` 的 `source.designSystem` 中添加要覆盖的键。
-
-```typescript title="modern.config.ts"
-export default defineConfig({
-  source: {
-    designSystem: {
-      opacity: {
-        0: '0',
-        20: '0.2',
-        40: '0.4',
-        60: '0.6',
-        80: '0.8',
-        100: '1',
-      },
-    },
-  },
-});
-```
-
-这将完全替换默认键配置，因此在上面的示例中，不会生成默认的 opacity utilities。
-
-所有未覆盖的键都将从默认主题继承，因此在上面的示例中，将保留颜色，间距，边框圆角，背景位置等内容的默认主题配置。
-
-## 扩展默认配置
-
-如果您想保留主题选项的默认值，但又要添加新值，请在 `designSystem.extend` 下添加扩展的内容。
-
-例如，如果我们想添加一个额外的断点但保留现有的断点，则可以扩展 `screens` 属性：
-
-```typescript title="modern.config.ts"
-export default defineConfig({
-  source: {
-    designSystem: {
-      opacity: {
-        0: '0',
-        20: '0.2',
-        40: '0.4',
-        60: '0.6',
-        80: '0.8',
-        100: '1',
-      },
-      extend: {
-        screens: {
-          '2xl': '1440px',
-        },
-      },
-    },
-  },
-});
-```
-
-修改 `src/routes/components/Item/index.tsx` 的 button 组件代码
-
-```js
-<button
-  type="button"
-  disabled={archived}
-  className={`bg-blue-500 text-white font-bold
-    py-2 px-4 rounded-full hover:bg-blue-700 2xl:bg-red-500`}
->
-  Archive
-</button>
-```
-
-执行 `pnpm run dev` 后，增加页面宽度超过 1440px 可以看到 button 颜色变化：
-
-![design2](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/result4.png)
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c06/hello-modern-4)。

package/zh/tutorials/first-app/c06-css-and-component/6.5-storybook.md

@@ -1,77 +0,0 @@
----
-title: ​用 Storybook 调试组件
----
-
-前几个小节中，我们已经开发了一个简单的 UI 组件。组件开发完后，一般我们需要对它进行调试。
-
-除了可以直接在项目中进行调试以外，我们还可以使用 [**Storybook**](https://storybook.js.org/) 进行调试。
-
-Modern.js 提供了开箱即用的 Storybook 能力，可以识别应用工程下的 Story 文件。
-
-我们执行 `pnpm run new`，启用该模式：
-
-```bash
-# 启用可选功能
-  ...
-  启用「单元测试 / 集成测试」功能
-❯ 启用「Visual Testing (Storybook)」模式
-```
-
-安装成功后，我们需要为我们的组件添加 Story 文件。
-
-:::info 补充信息
-Story 文件是指 `*.stories.[t|j]sx?` 格式的文件。
-:::
-
-这里我们为 `Avatar` 组件 添加 `src/components/Avatar/index.stories.tsx` Story 文件。
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-touch src/routes/components/Avatar/index.stories.tsx
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-ni src/routes/components/Avatar/index.stories.tsx
-```
-
-</TabItem>
-</Tabs>
-
-内容如下：
-
-``` javascript
-import Avatar from '.';
-
-export const DanielTaylorAvatar = () => (
-  <Avatar src="https://avatars.dicebear.com/v2/identicon/Daniel Taylor.svg" />
-);
-
-export default {
-  title: 'Avatar Demo',
-};
-```
-
-然后我们启动 Storybook 调试：
-
-``` bash
-pnpm run dev story
-```
-
-然后我们可以看到如下界面：
-
-![storybook demo](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/mwa-storybook-demo.png)
-
-如果需要配置 Storybook，则需要在 [`config/storybook/**`](/docs/apis/app/hooks/config/storybook) 目录下进行配置。
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c06/hello-modern-5)。
-

package/zh/tutorials/first-app/c06-css-and-component/6.6-testing.md

@@ -1,104 +0,0 @@
----
-title: ​测试组件​​​
----
-
-Modern.js 集成了 [Jest](https://jestjs.io/)，不需要做任何配置，可以直接给组件写测试用例。
-
-我们执行 `pnpm run new` 开启测试功能：
-
-```bash
-# 启用可选功能
-❯ 启用「单元测试 / 集成测试」功能
-```
-
-可以用以下两种方式给 Item 组件创建测试用例：
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-touch src/routes/components/Item/index.test.tsx
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-ni src/routes/components/Item/index.test.tsx
-```
-
-</TabItem>
-</Tabs>
-
-或
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-mkdir -p src/routes/components/Item/__tests__/
-touch src/routes/components/Item/__tests__/index.tsx
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-mkdir -p src/routes/components/Item/__tests__/
-ni src/routes/components/Item/__tests__/index.tsx
-```
-
-</TabItem>
-</Tabs>
-
-
-以前者为例，`Item/index.test.tsx` 的内容：
-
-```js
-import { render } from '@modern-js/runtime/testing';
-import Item from '.';
-
-const defaultProps = {
-  info: {
-    avatar: 'https://via.placeholder.com/350x350',
-    name: 'foo',
-    email: 'foo.bar@bytedance.com',
-    archived: false,
-  },
-};
-
-describe('Item', () => {
-  it('should have contents', () => {
-    const {
-      info: { name },
-    } = defaultProps;
-    const { getByText } = render(<Item {...defaultProps} />);
-    expect(getByText(name)).toBeInTheDocument();
-  });
-});
-```
-
-:::info 注
-更多相关内容可以查看 [Test API](/docs/apis/app/runtime/testing/render)。
-:::
-
-执行 `pnpm run test`，可以看到测试报告：
-
-```bash
-> modern test
-
- PASS  src/routes/components/Item/index.test.tsx
-
-Test Suites: 1 passed, 1 total
-Tests:       1 passed, 1 total
-Snapshots:   0 total
-Time:        1.708 s
-```
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c06/hello-modern-6)。
-

package/zh/tutorials/first-app/c06-css-and-component/_category_.json

@@ -1,3 +0,0 @@
-{
-  "label": "6: 添加 UI 组件"
-}

package/zh/tutorials/first-app/c07-app-entry/7.1-intro.md

@@ -1,69 +0,0 @@
----
-title: 入口的用途​​​
----
-
-上一章节中，我们介绍了如何编写 UI 组件。
-
-这一章节中，继续沿用之前的代码，到目前为止，hello-modern 的目录结构是这样的：
-
-```md
-.
-├── .eslintrc.js
-├── .gitignore
-├── .husky
-├── .npmrc
-├── .nvmrc
-├── .prettierrc
-├── .vscode
-├── README.md
-├── modern.config.ts
-├── package.json
-├── pnpm-lock.yaml
-├── src
-│   ├── .eslintrc.js
-│   ├── modern-app-env.d.ts
-│   └── routes
-│       ├── components
-│       │   ├── Avatar
-│       │   │   ├── index.stories.tsx
-│       │   │   └── index.tsx
-│       │   └── Item
-│       │       ├── index.test.tsx
-│       │       └── index.tsx
-│       ├── index.css
-│       ├── layout.tsx
-│       ├── page.tsx
-│       └── styles
-│           └── utils.css
-└── tsconfig.json
-```
-
-hello-modern 项目是一个应用工程，`src/` 目录里是应用工程源代码的主要部分，我们称之为【 Universal App 代码（大一统应用代码）】—— 既可以在客户端运行又可以在服务器端运行，有多种运行模式和部署模式，既能实现多页（MPA）也能实现单页（SPA）。
-
-我们把 `src/routes` 称作【 应用入口（App Entry）】，一个应用工程可以有一到多个应用入口。
-
-:::info 注
-应用入口不止 `src/routes` 一种，之后章节中会再次介绍。
-:::
-
-:::info 注
-在不启用 SSG（Static Site Generation）的情况下，Modern.js 会为每一个应用入口，都自动生成一个对应的 HTML，用于在浏览器、WebView 等平台上运行。
-
-一个应用入口适用于：
-
-- 一个中后台应用（SPA）
-- 一个桌面应用（SPA）
-- 一个PWA
-- 一个大型的多页网站（SPA + SSR）
-- 一个落地页、活动页或分享页
-- 一个端内界面
-- 一个微前端子应用
-- ……
-
-多个应用入口适用于：
-
-- 简单的多页网站（多个 HTML 互相链接）
-- 由多种不同类型入口组成的产品『系统』（整个产品不是单一的客户端，而是由多种不同客户端组成，比如同时有落地页、端内界面、端外独立 Web App、后台管理应用）
-:::
-
-hello-modern 项目目前是【 单入口 】形式的，我们接下来添加一个新入口，实现这个联系人列表应用的落地页，把项目转变成【 多入口 】形式。

package/zh/tutorials/first-app/c07-app-entry/7.2-add-entry-in-cli.md

@@ -1,100 +0,0 @@
----
-title: 用 new 命令创建入口​​​
----
-
-Modern.js 支持自动创建新入口，前面的章节中提到过，`pnpm run new` 可以启用可选功能。
-
-我们也可以通过它来创建新的工程元素，在项目根目录下执行 `pnpm run new`：
-
-```bash
-# 请选择你想要的操作
-❯ 创建工程元素
-  启用可选功能
-
-# 创建工程元素
-❯ 新建「应用入口」
-  新建「自定义 Web Serve」源码目录
-
-# 请填写入口名称
-- landing-page
-```
-
-创建完成，项目会变成这样：
-
-```md
-.
-├── .eslintrc.js
-├── .gitignore
-├── .husky
-├── .npmrc
-├── .nvmrc
-├── .prettierrc
-├── .vscode
-├── README.md
-├── modern.config.ts
-├── package.json
-├── pnpm-lock.yaml
-├── src
-│   ├── .eslintrc.js
-│   ├── hello-modern
-│   │   ├── index.test.ts
-│   │   └── routes
-│   │       ├── components
-│   │       │   ├── Avatar
-│   │       │   │   ├── index.stories.tsx
-│   │       │   │   └── index.tsx
-│   │       │   └── Item
-│   │       │       ├── index.test.tsx
-│   │       │       └── index.tsx
-│   │       ├── index.css
-│   │       ├── layout.tsx
-│   │       ├── page.tsx
-│   │       └── styles
-│   │           └── utils.css
-│   ├── landing-page
-│   │   └── routes
-│   │       ├── index.css
-│   │       ├── layout.tsx
-│   │       └── page.tsx
-│   └── modern-app-env.d.ts
-└── tsconfig.json
-```
-
-可以看到联系人列表应用的文件，都被自动重构到 `src/hello-modern/` 里。
-
-同时新建了一个 `src/landing-page/`，里面同样有 `routes/*`（`pnpm run new` 命令只做了这些事，所以你也可以很容易的手动创建新入口或修改入口）
-
-执行 `pnpm run dev`，显示：
-
-![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/landing-page.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/hello-modern/` 和 `src/landing-page/` 被自动识别为两个应用入口：hello-modern 和 landing-page。
-
-其中 `src/hello-modern/` 的目录名跟项目名（`package.json` 里的 `name`）一致，会被认为是项目**主入口**，项目 URL 的根路径（开发环境里默认是 `http://localhost:8080/`）会自动指向主入口。
-
-其他入口的 URL，是在根路径后追加入口名，比如 `http://localhost:8080/landing-page`。
-
-接下来，我们把 `src/hello-modern/` 重命名为 `src/contacts/`：
-
-```bash
-mv src/hello-modern src/contacts
-```
-
-再次执行 `pnpm run dev`，结果变成：
-
-![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/contacts.png)
-
-现在不再有主入口，联系人列表现在是一个普通入口，需要用 `http://localhost:8080/contacts` 访问。
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c07/hello-modern-2)。
-

package/zh/tutorials/first-app/c07-app-entry/7.3-manage-entries-by-hand.md

@@ -1,69 +0,0 @@
----
-title: 管理应用入口​​​
----
-
-上一个小节中，我们学习了使用命令行手动创建新的入口。
-
-在这一小节中，我们将通过配置项来对入口进行管理。
-
-我们可以在 `package.json` 中的 `modernConfig`，或是在符合[业界主流惯例](https://github.com/davidtheclark/cosmiconfig)的 Modern.js 配置文件里，自己写代码来控制项目的配置。
-
-
-现在，让我们在项目目录 `modern.config.ts` 里面添加内容：
-
-```typescript title="modern.config.ts"
-export default defineConfig({
-  server: {
-    ssr: true,
-    ssrByEntries: {
-      'landing-page': false,
-    },
-  },
-};
-```
-
-执行 `pnpm run dev`，再用浏览器打开 `view-source:http://localhost:8080/landing-page`，可以看到 `landing-page` 网页内容是通过 js 动态加载的，且此页面的 SSR 功能被关闭。
-
-注：此时，其他页面的 SSR 功能仍然正常开启。
-
-如果注释掉 `ssrByEntries` 和它的值，landing-page 的 SSR 功能就恢复开启了。
-
-当需要配置包含复杂逻辑的选项时，比如，开发者想在项目中使用 `*.myext` 文件，这是一种非主流的文件类型，Modern.js 没有默认集成对它的支持。
-
-所以，开发者可以在 `modern.config.ts` 里增加对它的支持（通过webpack配置），如下所示：
-
-:::info 注
-更多 webpack 配置相关可以查看 [Webpack 配置文档](/docs/configure/app/tools/webpack)。
-:::
-
-```ts
-// 注：以下为伪代码，loader等名字皆为虚构，仅做演示使用
-export default defineConfig({
-  tools: {
-    webpackChain: (chain) => {
-      chain.module
-        .rule('my-loader')
-        .test(/\.myext$/)
-        .use('custom-loader')
-        .loader('myext-loader')
-        .options({});
-    },
-  },
-};
-```
-
-这个需求要修改 webpack 配置，用 Modern.js 配置的`tools.webpack`选项来实现显然是更方便的。
-
-还有一些时候，需要一些更复杂的逻辑来做设置，比如需要 JS 变量、表达式、导入模块等，这种时候也适合用 `modern.config.ts` 来手动配置，比如：
-
-```js
-export default defineConfig({
-  server: {
-    ssrByEntries: {
-      'landing-page': process.env.NODE_ENV !== 'production',
-    },
-  },
-};
-```
-
-以上代码实现表示只在开发环境里开启 SSR。

package/zh/tutorials/first-app/c07-app-entry/_category_.json

@@ -1,3 +0,0 @@
-{
-  "label": "7: 添加应用入口"
-}

package/zh/tutorials/first-app/c08-client-side-routing/_category_.json

@@ -1,3 +0,0 @@
-{
-  "label": "8: 添加客户端路由"
-}

package/zh/tutorials/first-app/c09-bff/9.1-serverless.md

@@ -1,30 +0,0 @@
----
-title: Serverless 开发范式
----
-
-之前的章节中，我们用来渲染联系人列表的数据，都来自代码中的 Mock 数据。
-
-本章节中，我们将介绍如何通过 BFF 获取数据。
-
-在这之前，我们先回顾下上一章节 Demo 中的联系人列表应用，它有多种运行方式，比如：
-
-- `pnpm run dev` - 在本地开发环境中用于调试
-- `pnpm run build && pnpm run start` - 在生产环境中正式运行
-
-无论哪种方式，整个应用在运行时（runtime）都是一个【 Universal App 】，既有客户端部分（在客户端运行的 App 代码和框架代码），也有服务器端部分（框架内置的 Static Web Server 或 SSR Server，在 SSR 环节运行的 App 代码和框架代码）。
-
-但开发者对服务器几乎是无感知的，开发环节并没有专门写 server 代码，运行和部署的时候，也不跟具体 server 打交道，不需要运维 server，开发者可以专注于产品本身。
-
-这种开发范式，我们称作 Serverless Web Development。
-
-其中的 SSR 技术，我们称作 Serverless SSR，实现了 SSR 在开发、运行、部署全流程中的 Serverless。
-
-从本节开始，我们要接触 Serverless Web Development 的另一部分：Serverless BFF，跟 SSR 一样，能实现 [BFF（Backends for Frontends）](https://microservices.io/patterns/apigateway.html)在开发、运行、部署全流程中的 Serverless。
-
-:::info 注
-我们这里说的 BFF，不是指任意的面向客户端程序的服务器端 API，而是是更纯粹、狭义的 BFF，指专门服务特定客户端程序、特定产品 UI 需求的服务器端 API。
-
-这种 API 更适合跟客户端代码在一起实现、调试、运行和部署，由同一个/批开发者负责。
-
-简单情况下这种 API 做的是对更底层 API（比如各种微服务）的聚合、映射、裁剪、代理等，复杂情况下也会访问数据存储（比如应用数据库、缓存等），有服务器端 Model 等业务逻辑分层，但都倾向于只维护很薄的一层服务器端业务逻辑。
-:::

package/zh/tutorials/first-app/c09-bff/9.2-enable-bff.md

@@ -1,95 +0,0 @@
----
-title: 启用 BFF
----
-
-和之前章节一样，我们同样使用生成器来启用 BFF。
-
-在项目根目录下执行 `pnpm run new` 命令：
-
-```bash
-# 启用可选功能
-❯ 启用「BFF」功能
-  ...
-
-# 请选择 BFF 类型
-❯ 函数写法
-  框架写法
-
-# 请选择运行时框
-❯ Express
-  Koa
-```
-
-:::info 注
-函数模式与框架模式都是基于 Modern.js 的 BFF 函数的，两种模式的主体都是函数，也都需要运行时框架的支持，这里的提问是为了提供不同的样板文件。更多相关内容可以查看[一体化 BFF 专题](/docs/guides/advanced-features/bff/function)。
-:::
-
-我们先选择【 函数写法 】，并选择运行时框架为 Express，项目结构将变成：
-
-```md
-.
-├── .eslintrc.js
-├── .gitignore
-├── .husky
-├── .npmrc
-├── .nvmrc
-├── .prettierrc
-├── .vscode
-├── README.md
-├── api
-│   ├── _app.ts
-│   ├── index.ts
-│   └── info
-│       └── [type].ts
-├── modern.config.ts
-├── package.json
-├── pnpm-lock.yaml
-├── src
-│   ├── .eslintrc.js
-│   ├── contacts
-│   │   ├── index.test.ts
-│   │   └── routes
-│   │       ├── archives
-│   │       │   └── page.tsx
-│   │       ├── components
-│   │       │   ├── Avatar
-│   │       │   │   ├── index.stories.tsx
-│   │       │   │   └── index.tsx
-│   │       │   └── Item
-│   │       │       ├── index.test.tsx
-│   │       │       └── index.tsx
-│   │       ├── index.css
-│   │       ├── layout.tsx
-│   │       ├── page.tsx
-│   │       └── styles
-│   │           └── utils.css
-│   ├── landing-page
-│   │   └── routes
-│   │       ├── index.css
-│   │       ├── layout.tsx
-│   │       └── page.tsx
-│   └── modern-app-env.d.ts
-└── tsconfig.json
-```
-
-新增的 `api/` 目录，跟 `src/` 目录一样是源代码目录，目录中有几个示范用法的样板文件
-
-`package.json` 中则会增加 BFF 插件：
-
-```json
-+ "@modern-js/plugin-bff"
-+ "@modern-js/plugin-express"
-+ "express"
-```
-
-在函数写法中，BFF 的 API 路由也遵循类似【 约定式路由 】的生成逻辑。
-
-Modern.js Serverless BFF 的默认前缀为 `/api`，例如上述目录结构可以得到两个 API 路由：
-
-`http://localhost:8080/api`
-
-`http://localhost:8080/api/info/:type`
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c09/hello-modern-2)。