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

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

@@ -1,113 +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/components/Item/index.test.tsx
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-ni src/components/Item/index.test.tsx
-```
-
-</TabItem>
-</Tabs>
-
-或
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-mkdir -p src/components/Item/__tests__/
-touch src/components/Item/__tests__/index.tsx
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-mkdir -p src/components/Item/__tests__/
-ni src/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();
-  });
-});
-```
-
-在之前章节创建的 `modern-app-env.d.ts` 文件 **顶部**（[`///` 语法只在文件顶部生效](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html#:~:text=Triple-slash%20directives%20are%20only%20valid%20at%20the%20top%20of%20their%20containing%20file.)） 加上类型定义：
-
-```ts
-/// <reference types="@modern-js/plugin-testing/type" />
-```
-
-:::info 注
-更多相关内容可以查看 [Test API](/docs/apis/app/runtime/testing/render)。
-:::
-
-执行 `pnpm run test`，可以看到测试报告：
-
-```bash
-> modern test
-
- PASS  src/components/Item/index.test.tsx
-  Item
-    ✓ should have contents (27 ms)
-
-Test Suites: 1 passed, 1 total
-Tests:       1 passed, 1 total
-Snapshots:   0 total
-Time:        1.048 s, estimated 2 s
-Ran all test suites.
-```
-
----
-
-> 本小节的代码可以在[这里查看](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,64 +0,0 @@
----
-title: 入口的用途​​​
----
-
-上一章节中，我们介绍了如何编写 UI 组件。
-
-这一章节中，继续沿用之前的代码，到目前为止，hello-modern 的目录结构是这样的：
-
-```md
-.
-├── .vscode/
-├── src/
-│   ├── components/
-│   │   ├── Avatar/
-│   │   │   ├── index.stories.tsx
-│   │   │   └── index.tsx
-│   │   └── Item/
-│   │       ├── index.test.tsx
-│   │       └── index.tsx
-│   ├── styles/
-│   │   └── utils.css
-│   ├── .eslintrc.json
-│   ├── App.css
-│   ├── App.tsx
-│   └── modern-app-env.d.ts
-├── .editorconfig
-├── .gitignore
-├── .npmrc
-├── .nvmrc
-├── README.md
-├── package.json
-├── pnpm-lock.yaml
-└── tsconfig.json
-```
-
-hello-modern 项目是一个应用工程，`src/` 目录里是应用工程源代码的主要部分，我们称之为【 Universal App 代码（大一统应用代码）】—— 既可以在客户端运行又可以在服务器端运行，有多种运行模式和部署模式，既能实现多页（MPA）也能实现单页（SPA）。
-
-我们把 `src/App.tsx` 称作【 应用入口（App Entry）】，一个应用工程可以有一到多个应用入口。
-
-:::info 注
-应用入口不止 `App.[jt]sx` 一种，之后章节中会再次介绍。
-:::
-
-:::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
-.
-├── .vscode/
-├── src/
-│   ├── hello-modern/
-│   │   ├── components/
-│   │   │   ├── Avatar/
-│   │   │   │   ├── index.stories.tsx
-│   │   │   │   └── index.tsx
-│   │   │   └── Item/
-│   │   │       ├── index.test.tsx
-│   │   │       └── index.tsx
-│   │   ├── styles/
-│   │   │   └── utils.css
-│   │   ├── App.css
-│   │   └── App.tsx
-│   ├── landing-page/
-│   │   ├── App.css
-│   │   └── App.tsx
-│   ├── .eslintrc.json
-│   └── modern-app-env.d.ts
-├── .editorconfig
-├── .gitignore
-├── .npmrc
-├── .nvmrc
-├── README.md
-├── package.json
-├── pnpm-lock.yaml
-└── tsconfig.json
-```
-
-可以看到联系人列表应用的文件，都被自动重构到 `src/hello-modern/` 里。
-
-同时新建了一个 `src/landing-page/`，里面同样有 `App.tsx`（`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`。
-
-:::info 注
-`src/` 下如果有 `App.[jt]sx`，就认为这个应用工程是单入口的，`src/` 下的其他文件和目录，都会被视为入口内部的文件。
-
-`src/` 下如果没有  `App.[jt]sx`，那么 `src/` **下一级**目录里，如果有 `App.[jt]sx`，这个目录就会被视为一个应用入口。
-
-`App.jsx` 被看作约定中**标识**，也有其他形式的**标识**，之后的章节中会继续介绍。
-:::
-
-接下来，我们把 `src/hello-modern/App.tsx` 重命名为 `src/contacts/App.tsx`：
-
-```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,74 +0,0 @@
----
-title: 管理应用入口​​​
----
-
-上一个小节中，我们学习了使用命令行手动创建新的入口。
-
-在这一小节中，我们将通过配置项来对入口进行管理。
-
-我们可以在 `package.json` 中的 `modernConfig`，或是在符合[业界主流惯例](https://github.com/davidtheclark/cosmiconfig)的 Modern.js 配置文件里，自己写代码来控制项目的配置。
-
-之前的章节中，我们都是直接修改 `package.json` 中的 `modernConfig` 字段来实现修改配置。
-
-现在，让我们在项目目录下，新建一个 `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 功能就恢复开启了。
-
-:::info 注
-当相同配置字段出现于两个文件中时， `package.json` 中 `modernConfig` 字段里的配置会优先于 `modern.config.js` 中的配置。
-:::
-
-当需要配置包含复杂逻辑的选项时，比如，开发者想在项目中使用 `*.myext` 文件，这是一种非主流的文件类型，Modern.js 没有默认集成对它的支持。
-
-所以，开发者可以在 `modern.config.js` 里增加对它的支持（通过webpack配置），如下所示：
-
-:::info 注
-更多 webpack 配置相关可以查看 [Webpack 配置文档](/docs/configure/app/tools/webpack)。
-:::
-
-```js
-// 注：以下为伪代码，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.js` 来手动配置，比如：
-
-```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/8.1-code-based-routing.md

@@ -1,153 +0,0 @@
----
-title: 使用自控式路由​​​​
----
-
-上一章节中，我们学习了如何创建应用入口。
-
-这一章节中，我们将会学习如何为入口增加【 客户端路由 】。
-
-我们分别用两种不同的方式，为 `contacts` 和 `landing-page` 增加客户端路由逻辑。
-
-`contacts` 和 `landing-page` 这两个入口，都是通过 CLI 自动创建出来的，在创建过程中我们没有修改入口的默认配置，因此每个入口的客户端路由都是默认开启的。
-
-```js title="modern.config.ts"
-export default defineConfig({
-  runtime: {
-    router: true,
-    state: true,
-  },
-});
-```
-
-之前我们已经为联系人列表增加了 Archive 按钮，接下来我们添加一个客户端路由 `/archives`，访问这个路由时，只显示已存档的联系人，而原有的 `/` 继续显示所有联系人。
-
-打开 `src/contacts/App.tsx`，在原有的 `mockData` 下方新增 `mockArchivedData`：
-
-```js
-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' },
-]);
-
-const mockArchivedData = getAvatar([
-  { name: 'Thomas', email: 'w.kccip@bllmfbgv.dm' },
-  { name: 'Chow', email: 'f.lfqljnlk@ywoefljhc.af' },
-]);
-```
-
-在文件顶部引入 [React Router](https://reactrouter.com/) 的 `Route`、`Switch` 和 [React Helmet](https://github.com/nfl/react-helmet) 的 `Helmet` 组件：
-
-```js
-import { Route, Switch } from '@modern-js/runtime/router';
-import { Helmet } from '@modern-js/runtime/head';
-```
-
-在 `App` 组件中使用 `Route` 写两个路由，分别用不同的 mock 数据渲染列表：
-
-```js
-function App() {
-  return (
-    <div className="container lg mx-auto">
-      <Switch>
-        <Route path="/" exact={true}>
-          <Helmet>
-            <title>All</title>
-          </Helmet>
-          <List
-            dataSource={mockData}
-            renderItem={info => <Item key={info.name} info={info} />}
-          />
-        </Route>
-        <Route path="/archives" exact={true}>
-          <Helmet>
-            <title>Archives</title>
-          </Helmet>
-          <List
-            dataSource={mockArchivedData}
-            renderItem={info => <Item key={info.name} info={info} />}
-          />
-        </Route>
-      </Switch>
-    </div>
-  );
-}
-```
-
-:::info 注
-Modern.js 默认集成了 react-helmet，无需安装依赖，可以直接使用，也可以结合 SSR 使用，满足 SEO 需求。
-
-Modern.js 也默认集成了 react-router，无需安装依赖和自己配置 `BrowserRouter` 等样板代码，可以直接用 Route、Switch 等组件实现路由逻辑。
-:::
-
-React Router v4+ 有两种用法，一种是 `component-based` 的，一种是基于全局配置的。这两种都由开发者自己用代码来控制客户端路由逻辑，所以我们把这种模式称作【**自控式路由**】。
-
-执行 `pnpm run dev`，访问 `http://localhost:8080/contacts`，可以看到完整的联系人，页面的标题是 All：
-
-![display](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/08/display.png)
-
-访问 `http://localhost:8080/contacts/archives`，只会看到已存档的联系人，页面的标题是 Archives：
-
-![display1](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/08/display1.png)
-
-查看页面 HTML 源码，可以看到两个页面的内容是一样，是在客户端针对不同 URL 渲染不同内容。
-
-**接下来我们增加一个简单的导航栏，让用户能在两个列表之间切换**。
-
-打开 src/contacts/App.tsx，在顶部导入 Radio 组件：
-
-```tsx
-import { List, Radio } from 'antd';
-```
-
-然后将 UI 最顶部进行修改，增加一组单选框
-
-```tsx {3-8}
-return (
-  <div className="container lg mx-auto">
-    <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>
-    <Switch>
-```
-
-然后我们来实现 `currentList` 和 `handleSetList`。
-
-引入两个 React Hook：`useState` 和 `useHistory`，以及 Ant Design 的事件类型定义：
-
-```js
-import { useState } from 'react';
-import { List, Radio, RadioChangeEvent } from 'antd';
-import { Route, Switch, useHistory } from '@modern-js/runtime/router';
-```
-
-最后在 App 组件里增加局部状态和相关逻辑：
-
-```js {2-8}
-function App() {
-  const history = useHistory();
-  const [currentList, setList] = useState(history.location.pathname || '/');
-  const handleSetList = (e: RadioChangeEvent) => {
-    const { value } = e.target;
-    setList(value);
-    history.push(value);
-  };
-```
-
-到这里就已经完成了页面导航栏实现，执行 `pnpm run dev` 查看效果：
-
-![display2](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/08/display2.png)
-
-点击导航栏中 Archives，可以看到单选框的选中状态和 URL 都会变化，页面没有刷新，只发生了 CSR。
-
-如果我们将 contacts 入口的 SSR 选项开启后（[配置教程](/docs/configure/app/server/ssr)），重新访问两个页面，可以看到 HTML 内容是不同的，这是因为在 SSR 阶段页面就执行了客户端路由的逻辑，HTML 里已经包含了最终的渲染结果。
-
-访问 `http://localhost:8080/contacts/archives`，点击顶部单选框，可以看到在有 SSR 的情况下，CSR 不受影响，跟开启 SSR 之前的效果一致，实现了 UX 的最大化（首屏 SSR，后续交互 CSR）。
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c08/hello-modern)。