@modern-js/main-doc 0.0.0-next-20221203140534 → 0.0.0-next-20221205074243

package/zh/tutorials/first-app/c04-es6-plus-and-ts/4.2-use-typescript.md

@@ -15,7 +15,10 @@ import TabItem from '@theme/TabItem';
 <TabItem value="macOS" label="macOS" default>
 
 ```bash
-mv src/App.jsx src/App.tsx
+mv src/routes/layout.jsx src/routes/layout.tsx
+mv src/routes/page.jsx src/routes/page.tsx
+mv modern.config.js modern.config.ts
+touch src/modern-app-env.d.ts
 
 pnpm add typescript @types/react @types/react-dom @types/node -D
 
@@ -26,7 +29,10 @@ touch tsconfig.json
 <TabItem value="Windows" label="Windows">
 
 ```bash
-mv src/App.jsx src/App.tsx
+mv src/routes/layout.jsx src/routes/layout.tsx
+mv src/routes/page.jsx src/routes/page.tsx
+mv modern.config.js modern.config.ts
+ni src/modern-app-env.d.ts
 
 pnpm add typescript @types/react @types/react-dom @types/node -D
 
@@ -57,28 +63,46 @@ ni tsconfig.json
 }
 ```
 
-打开 `src/App.tsx`，把代码改成以下内容：
+`modern.config.ts` 内容修改如下：
 
 ```ts
-import React from 'react';
+import { defineConfig } from '@modern-js/app-tools';
 
+export default defineConfig({
+  runtime: {
+    router: true,
+    state: true,
+  },
+});
+```
+
+`modern-app-env.d.ts` 内容如下
+
+```ts
+/// <reference types='@modern-js/app-tools/types' />
+```
+
+打开 `src/routes/page.tsx`，把代码改成以下内容：
+
+```ts
 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' },
-]);
+const getMockData = () =>
+  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() {
+function Index() {
   return (
     <ul>
-      {mockData.map(({ name, avatar, email }) => (
+      {getMockData().map(({ name, avatar, email }) => (
         <li key={name}>
           <img src={avatar} width={60} height={60} /> ---
           <span>{name}</span> ---
@@ -89,7 +113,7 @@ function App() {
   );
 }
 
-export default App;
+export default Index;
 ```
 
 可以看到，跟 ES6+ 的代码相比有以下不同：

package/zh/tutorials/first-app/c05-component/5.1-use-ui-library.md

@@ -14,26 +14,16 @@ title: 使用主流组件库
 pnpm add antd
 ```
 
-之前章节介绍过，Modern.js 支持在项目创建后继续为项目增加功能，我们执行 `pnpm run new`，进行如下选择，开启 Less 支持。
-
-```bash
-# 启用可选功能
-  启用 Tailwind CSS 支持
-❯ 启用 Less 支持
-  启用 Sass 支持
-  ...
-```
-
-修改 `src/App.tsx`，在顶部导入组件:
+修改 `src/routes/page.tsx`，在顶部导入组件:
 
 ```js
 import { List } from 'antd';
 ```
 
-修改 App 组件的实现：
+修改 Index 组件的实现：
 
 ```ts
-function App() {
+function Index() {
   return (
     <div>
       <List

package/zh/tutorials/first-app/c05-component/5.2-use-standalone-component.md

@@ -12,7 +12,7 @@ title: 使用独立开源组件
 pnpm add react-ladda ladda
 ```
 
-在 `src/App.tsx` 里导入组件，同时手动导入需要的 CSS：
+在 `src/routes/page.tsx` 里导入组件，同时手动导入需要的 CSS：
 
 ```ts
 import LaddaButton, { S, SLIDE_UP } from 'react-ladda';
@@ -46,26 +46,6 @@ import 'ladda/dist/ladda.min.css';
 
 `react-ladda` 组件库没有提供 types 文件，我们添加一个 `.d.ts` 文件：
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-touch src/modern-app-env.d.ts
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```bash
-ni src/modern-app-env.d.ts
-```
-
-</TabItem>
-</Tabs>
-
 在 `modern-app-env.d.ts` 中添加模块定义：
 
 ```ts

package/zh/tutorials/first-app/c06-css-and-component/6.1-css-in-js.md

@@ -21,7 +21,7 @@ Modern.js 开箱即用的支持 CSS Modules，但我们更推荐优先采用 CSS
 
 Modern.js 同样开箱即用的支持 styled-components，既不需要安装依赖，也不需要做任何配置。
 
-在 `src/App.tsx` 里修改顶部的代码：
+在 `src/routes/page.tsx` 里修改顶部的代码：
 
 ```js
 import styled from '@modern-js/runtime/styled';
@@ -63,30 +63,30 @@ import TabItem from '@theme/TabItem';
 <TabItem value="macOS" label="macOS" default>
 
 ```bash
-mkdir -p src/components/Avatar
-touch src/components/Avatar/index.tsx
+mkdir -p src/routes/components/Avatar
+touch src/routes/components/Avatar/index.tsx
 ```
 
 </TabItem>
 <TabItem value="Windows" label="Windows">
 
 ```powershell
-mkdir -p src/components/Avatar
-ni src/components/Avatar/index.tsx
+mkdir -p src/routes/components/Avatar
+ni src/routes/components/Avatar/index.tsx
 ```
 
 </TabItem>
 </Tabs>
 
-把 `src/App.tsx` 里的 Avatar 实现删掉，改成：
+把 `src/routes/page.tsx` 里的 Avatar 实现删掉，改成：
 
-```js
+```ts
 import Avatar from './components/Avatar';
 ```
 
-`src/components/Avatar/index.tsx` 的内容：
+`src/routes/components/Avatar/index.tsx` 的内容：
 
-```js
+```ts
 import styled from '@modern-js/runtime/styled';
 
 const Avatar = styled.img`

package/zh/tutorials/first-app/c06-css-and-component/6.2-utility-class.md

@@ -21,15 +21,10 @@ Modern.js 集成了主流、轻量、通用的 Utility Class 工具库 [Tailwind
 ```bash
 # 启用可选功能
 ❯ 启用 Tailwind CSS 支持
-  启用 Sass 支持
   ...
 ```
 
-:::info 注
-因为我们之前已经开启了 Less 支持，所以再次添加可选功能时，不再有这个选项。
-:::
-
-在 `src/App.tsx` 顶部引入 Tailwind CSS 的 css 文件，就可以开始快速实现专业的 UI：
+在 `src/routes/page.tsx` 顶部引入 Tailwind CSS 的 css 文件，就可以开始快速实现专业的 UI：
 
 ```js
 import 'tailwindcss/base.css';
@@ -46,22 +41,22 @@ import TabItem from '@theme/TabItem';
 <TabItem value="macOS" label="macOS" default>
 
 ```bash
-mkdir -p src/components/Item
-touch src/components/Item/index.tsx
+mkdir -p src/routes/components/Item
+touch src/routes/components/Item/index.tsx
 ```
 
 </TabItem>
 <TabItem value="Windows" label="Windows">
 
 ```powershell
-mkdir -p src/components/Item
-ni src/components/Item/index.tsx
+mkdir -p src/routes/components/Item
+ni src/routes/components/Item/index.tsx
 ```
 
 </TabItem>
 </Tabs>
 
-修改 `src/App.tsx`，把 `List` 的 `render` 实现交给 `Item` 组件：
+修改 `src/routes/page.tsx`，把 `List` 的 `render` 实现交给 `Item` 组件：
 
 ```js
 import { List } from 'antd';
@@ -83,7 +78,7 @@ const mockData = getAvatar([
   { name: 'Davis', email: '"t.kqkoj@utlkwnpwk.nu' },
 ]);
 
-function App() {
+function Index() {
   return (
     <div className="container lg mx-auto">
       <List
@@ -94,12 +89,12 @@ function App() {
   );
 }
 
-export default App;
+export default Index;
 ```
 
 在父容器的上使用了 [Utility Class](https://tailwindcss.com/docs/container) ，快速实现了最基本的 [RWD](https://tailwindcss.com/docs/responsive-design)（最大宽度、居中）。
 
-接下来实现 `src/components/Item/index.tsx`：
+接下来实现 `src/routes/components/Item/index.tsx`：
 
 ```tsx
 import Avatar from '../Avatar';

package/zh/tutorials/first-app/c06-css-and-component/6.3-postcss.md

@@ -17,28 +17,28 @@ import TabItem from '@theme/TabItem';
 <TabItem value="macOS" label="macOS" default>
 
 ```bash
-mkdir -p src/styles
-touch src/styles/utils.css
+mkdir -p src/routes/styles
+touch src/routes/styles/utils.css
 ```
 
 </TabItem>
 <TabItem value="Windows" label="Windows">
 
 ```powershell
-mkdir -p src/styles
-ni src/styles/utils.css
+mkdir -p src/routes/styles
+ni src/routes/styles/utils.css
 ```
 
 </TabItem>
 </Tabs>
 
-在 `src/App.tsx` 里导入 `utils.css`：
+在 `src/routes/page.tsx` 里导入 `utils.css`：
 
 ```js
 import './styles/utils.css';
 ```
 
-在 `src/styles/utils.css` 里实现一个叫作 `custom-text-gray` 的 Utility Class。
+在 `src/routes/styles/utils.css` 里实现一个叫作 `custom-text-gray` 的 Utility Class。
 
 ```css
 :root {
@@ -54,7 +54,7 @@ import './styles/utils.css';
 Modern.js 集成了 [PostCSS](/docs/guides/basic-features/css/postcss)，支持现代 CSS 语法特性，比如 [custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*)。
 :::
 
-在 `src/components/Item/index.tsx` 里使用，把：
+在 `src/routes/components/Item/index.tsx` 里使用，把：
 
 ```js
 <div className="ml-4 flex-1 flex justify-between">

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

@@ -61,7 +61,7 @@ export default defineConfig({
 });
 ```
 
-修改 `src/Item/index.tsx` 的 button 组件代码
+修改 `src/routes/components/Item/index.tsx` 的 button 组件代码
 
 ```js
 <button

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

@@ -32,14 +32,14 @@ import TabItem from '@theme/TabItem';
 <TabItem value="macOS" label="macOS" default>
 
 ```bash
-touch src/components/Avatar/index.stories.tsx
+touch src/routes/components/Avatar/index.stories.tsx
 ```
 
 </TabItem>
 <TabItem value="Windows" label="Windows">
 
 ```powershell
-ni src/components/Avatar/index.stories.tsx
+ni src/routes/components/Avatar/index.stories.tsx
 ```
 
 </TabItem>

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

@@ -20,14 +20,14 @@ import TabItem from '@theme/TabItem';
 <TabItem value="macOS" label="macOS" default>
 
 ```bash
-touch src/components/Item/index.test.tsx
+touch src/routes/components/Item/index.test.tsx
 ```
 
 </TabItem>
 <TabItem value="Windows" label="Windows">
 
 ```powershell
-ni src/components/Item/index.test.tsx
+ni src/routes/components/Item/index.test.tsx
 ```
 
 </TabItem>
@@ -39,16 +39,16 @@ ni src/components/Item/index.test.tsx
 <TabItem value="macOS" label="macOS" default>
 
 ```bash
-mkdir -p src/components/Item/__tests__/
-touch src/components/Item/__tests__/index.tsx
+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/components/Item/__tests__/
-ni src/components/Item/__tests__/index.tsx
+mkdir -p src/routes/components/Item/__tests__/
+ni src/routes/components/Item/__tests__/index.tsx
 ```
 
 </TabItem>
@@ -81,12 +81,6 @@ describe('Item', () => {
 });
 ```
 
-在之前章节创建的 `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)。
 :::
@@ -96,15 +90,12 @@ describe('Item', () => {
 ```bash
 > modern test
 
- PASS  src/components/Item/index.test.tsx
-  Item
-    ✓ should have contents (27 ms)
+ PASS  src/routes/components/Item/index.test.tsx
 
 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.
+Time:        1.708 s
 ```
 
 ---

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

@@ -8,37 +8,42 @@ title: 入口的用途​​​
 
 ```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
+├── .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/App.tsx` 称作【 应用入口（App Entry）】，一个应用工程可以有一到多个应用入口。
+我们把 `src/routes` 称作【 应用入口（App Entry）】，一个应用工程可以有一到多个应用入口。
 
 :::info 注
-应用入口不止 `App.[jt]sx` 一种，之后章节中会再次介绍。
+应用入口不止 `src/routes` 一种，之后章节中会再次介绍。
 :::
 
 :::info 注

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

@@ -23,38 +23,46 @@ Modern.js 支持自动创建新入口，前面的章节中提到过，`pnpm run
 
 ```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
+├── .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/`，里面同样有 `App.tsx`（`pnpm run new` 命令只做了这些事，所以你也可以很容易的手动创建新入口或修改入口）
+同时新建了一个 `src/landing-page/`，里面同样有 `routes/*`（`pnpm run new` 命令只做了这些事，所以你也可以很容易的手动创建新入口或修改入口）
 
 执行 `pnpm run dev`，显示：
 
@@ -74,15 +82,7 @@ Modern.js 框架的设计原则之一是【[约定优于配置（Convention over
 
 其他入口的 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`：
+接下来，我们把 `src/hello-modern/` 重命名为 `src/contacts/`：
 
 ```bash
 mv src/hello-modern src/contacts

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

@@ -8,9 +8,8 @@ title: 管理应用入口​​​
 
 我们可以在 `package.json` 中的 `modernConfig`，或是在符合[业界主流惯例](https://github.com/davidtheclark/cosmiconfig)的 Modern.js 配置文件里，自己写代码来控制项目的配置。
 
-之前的章节中，我们都是直接修改 `package.json` 中的 `modernConfig` 字段来实现修改配置。
 
-现在，让我们在项目目录下，新建一个 `modern.config.ts`（若已新建可忽略），并在里面添加内容：
+现在，让我们在项目目录 `modern.config.ts` 里面添加内容：
 
 ```typescript title="modern.config.ts"
 export default defineConfig({
@@ -29,19 +28,15 @@ export default defineConfig({
 
 如果注释掉 `ssrByEntries` 和它的值，landing-page 的 SSR 功能就恢复开启了。
 
-:::info 注
-当相同配置字段出现于两个文件中时， `package.json` 中 `modernConfig` 字段里的配置会优先于 `modern.config.js` 中的配置。
-:::
-
 当需要配置包含复杂逻辑的选项时，比如，开发者想在项目中使用 `*.myext` 文件，这是一种非主流的文件类型，Modern.js 没有默认集成对它的支持。
 
-所以，开发者可以在 `modern.config.js` 里增加对它的支持（通过webpack配置），如下所示：
+所以，开发者可以在 `modern.config.ts` 里增加对它的支持（通过webpack配置），如下所示：
 
 :::info 注
 更多 webpack 配置相关可以查看 [Webpack 配置文档](/docs/configure/app/tools/webpack)。
 :::
 
-```js
+```ts
 // 注：以下为伪代码，loader等名字皆为虚构，仅做演示使用
 export default defineConfig({
   tools: {
@@ -59,7 +54,7 @@ export default defineConfig({
 
 这个需求要修改 webpack 配置，用 Modern.js 配置的`tools.webpack`选项来实现显然是更方便的。
 
-还有一些时候，需要一些更复杂的逻辑来做设置，比如需要 JS 变量、表达式、导入模块等，这种时候也适合用 `modern.config.js` 来手动配置，比如：
+还有一些时候，需要一些更复杂的逻辑来做设置，比如需要 JS 变量、表达式、导入模块等，这种时候也适合用 `modern.config.ts` 来手动配置，比如：
 
 ```js
 export default defineConfig({